scanf


フォーマット指定したテキストをSFRから読み込みます。

[所属]

標準ライブラリ

[指定形式]

#include <stdio.h>

int __far scanf(const char __far *format, ...); (C90)

int __far scanf(const char __far * restrict format, ...); (C99) 【V1.08以降】

[戻り値]

走査,変換,格納が正常に実行できた入力フィールドの個数を返します。返却値には,格納されなかった走査済みフィールドは含まれません。

ファイルの終わりで読み込もうとした場合,返却値はEOFです。

フィールドが格納されなかった場合は,返却値は0です。

[詳細説明]

getchar関数を使用したSFRからの入力を変換し,formatに続く実引数が指すオブジェクトに代入します。その際の変換方法は,formatが指す文字列で指定される書式に従います。指令と矛盾する入力文字によって変換が終了した場合,その矛盾した入力文字は切り捨てられます。

 

書式に対して実引数が不足しているときの動作は保証されません。実引数が残っているにもかかわらず,書式が尽きてしまう場合,余分な実引数は評価するだけで無視されます。

書式は0個以上の指令からなり,書式内の各指令を順に実行します。入力文字が得られないか,不適切な入力により指令の実行が失敗すると,処理は終了します。

 

formatは,次に示す3種類のディレクティブにより構成されます。

1個以上の空白類

スペース( ),タブ(\t),改行(\n)です。

最初の非空白類文字の直前まで(この文字は読まずに残す),またはそれ以上読み取ることができなくなるまで,入力読み取りを実行します。

通常の文字

“%”以外のすべてのASCII文字です。

次の文字を読むことで実行されます。

変換指示

0個以上の引数を取り込み,変換の指示を与えます。

 

各変換指示は“%”で始まります。“%”の後ろは,次のようになります。

 

%[代入抑制文字][フィールド長][サイズ][型指定文字]

 

それぞれの変換指示について,次に説明します。

(1)

代入抑制文字

代入を抑制する“*”です。

(2)

フィールド長

最大フィールド長を規定する正の10進整数です。0の場合,規定がないものとします。

入力フィールドを変換する前に読み込まれる最大文字数を指定します。入力フィールドがこのフィールド長より小さい場合,本関数はフィールド内のすべての文字を読み込み,次のフィールドとその変換指示へ進みます。また,フィールド長分を読み込む前に,空白文字,または変換できない文字が見つかった場合,その文字までの文字群を読み込み,変換し,格納します。その後,本関数は次の変換指示へ進みます。

(3)

サイズ

対応する引数のデータ型を解釈するデフォルトの方法を変更する,任意選択のサイズ文字hh,h,l,ll,j,z,tおよびLです。

指定がない場合,後ろに続くd,i,o,n,u,x,Xの型指定を強制的にint,またはunsigned intへのポインタに適用します。さらに,後ろに続くf,F,e,E,g,Gの型指定をfloatへのポインタに,nの型指定をintへのポインタに適用します。

hhを指定した場合,後ろに続くd,i,o,n,u,x,Xの型指定を強制的にsigned char,またはunsigned charへのポインタに適用します。hhはさらに,後ろに続くf,F,e,E,g,Gの型指定をfloatへのポインタに,nの型指定をsigned charへのポインタに適用します。(C99) 【V1.08以降】

hを指定した場合,後ろに続くd,i,o,n,u,x,Xの型指定を強制的にshort int,またはunsigned short intへのポインタに適用します。hはさらに,後ろに続くf,F,e,E,g,Gの型指定をfloatへのポインタに,nの型指定をshort intへのポインタに適用します。

lを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にlong,またはunsigned longへのポインタに適用します。lはさらに,後ろに続くf,F,e,E,g,Gの型指定をdoubleへのポインタに,nの型指定をlongへのポインタに適用します。

llを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にlong long,またはunsigned long longへのポインタに適用します。llはさらに,後ろに続くnの型指定を強制的にlong longへのポインタに適用します。

jを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にintmax_t,またはuintmax_tへのポインタに適用します。jはさらに,後ろに続くnの型指定をintmax_tへのポインタに適用します。(C99) 【V1.08以降】

zを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にsize_t,またはsigned intへのポインタに適用します。zはさらに,後ろに続くnの型指定をsigned intへのポインタに適用します。(C99) 【V1.08以降】

tを指定した場合,後ろに続くd,i,o,u,x,Xの型指定をptrdiff_t,またはunsigned intへのポインタに適用します。tはさらに,後ろに続くnの型指定をptrdiff_tへのポインタに適用します。(C99) 【V1.08以降】

Lを指定した場合,後ろに続くf,F,e,E,g,Gの型指定を強制的にlong doubleへのポインタに適用します。ただし,本コンパイラではdouble型とlong double型は同じフォーマットです。

(4)

型指定文字

適用される変換の型を指定する文字です。変換の型を指定する文字とその意味を次に示します。

d

10進整数を対応する引数に読み込みます。対応する型はサイズ文字に従います。

i

10進,8進,または16進整数を対応する引数に読み込みます。対応する型はサイズ文字に従います。

o

8進整数を対応する引数に読み込みます。対応する型はサイズ文字に従います。

u

符号なし10進整数を対応する引数に読み込みます。対応する型はサイズ文字に従います。

x,X

16進整数を対応する引数に読み込みます。対応する型はサイズ文字に従います。

e,f,g,E,F,G

浮動小数点数,無限大,またはNaNを対応する引数に読み込みます。対応する型はサイズ文字に従います。

s

与えられた配列の中に文字列を読み込みます。対応する引数は“char __far arg[ ]”にしてください。

ポインタは常にfarポインタとなります。定数を渡す場合は,実引数にキャストをつけてポインタであることを明示してください。nullポインタを渡した場合の動作は保証されません。

[ ]

空でない文字列を引数argで始まるメモリの中へ読み込みます。この領域には,文字列と,自動的に付加される,文字列の終わりを示すnull文字(\0)とを受け入れられる大きさが必要です。対応する引数は“char *arg”にしてください。

[ ]で囲まれた文字パターンを,型指定文字sの代わりに使用することができます。文字パターンは,sscanfの入力フィールドを構成する文字の検索セットを定義する文字集合です。[ ]内の最初の文字が“^”の場合,検索セットは反転され,[ ]内の文字以外のすべてのASCII文字が含まれます。また,ショートカットとして使用できる範囲指定機能もあります。たとえば,%[0-9]は,すべての10進数字と一致します。この集合内では,“-”は最初,または最後の文字にはできません。“-”の前の文字は,その後ろの文字よりも辞書式順序で小さくなるようにしてください。

-

%[abcd]

a,b,c,dのみを含む文字列と一致します。

-

%[^abcd]

a,b,c,d以外の任意の文字を含む文字列と一致します。

-

%[A-DW-Z]

A,B,C,D,W,X,Y,Zを含む文字列と一致します。

-

%[z-a]

z,-,aと一致します(範囲指定とはみなされません)。

c

1文字を走査します。対応する引数は“char __far *arg”にしてください。

ポインタは常にfarポインタとしてください。定数を渡す場合は,実引数にキャストをつけてポインタであることを明示してください。

p

走査したポインタを格納します。対応する引数は“void __far **arg”にしてください。

ポインタは常にfarポインタとしてください。定数を渡す場合は,実引数にキャストをつけてポインタであることを明示してください。

n

入力を読み取りません。これまでに読み取った文字数を,対応する引数に書き込みます。

%n指令を実行しても,関数終了時に返却する入力項目の個数は増加しません。対応する型はサイズ文字に従います。

%

文字“%”にマッチします。変換も代入も行われません。変換指示は“%%”となります。

 

F変換はC99ライブラリのみ指定可能です。

 

浮動小数点数(型指定文字e,f,g,E,F,G)の場合,次の一般形式に対応させてください。

 

[ + | - ] ddddd [ . ] ddd [ E | e [ + | - ] ddd ]

 

ただし,上記の一般形式のうち[ ]で囲まれた部分は任意選択であり,dddは10進数字を表します。

[注意事項]

-

通常のフィールド終了文字に到達する前に,特定フィールドの走査を停止したり完全に終了したりする可能性があります。

-

次の状況では,その時点でのフィールドの走査,格納を停止し,次の入力フィールドに移動します。

-

代入抑制文字(*)が書式指定の中で“%”の後ろに現れており,その時点の入力フィールドは走査されているが格納はされていない。

-

フィールド長(正の10進整数)指定文字を読み込んだ。

-

読み込む次の文字がその変換指示では変換できない(たとえば,指示が10進のときにZを読み込む場合)。

-

入力フィールド内の次の文字が検索セット内に現れていない(または反転検索セット内に現れている)。

 

以上の理由からその時点の入力フィールドの走査を停止すると,次の文字が未読であるとみなされ,次の入力フィールドの最初の文字,またはその入力のあとの読み込み操作の最初の文字として使用されます。

-

本関数は,次の状況では終了します。

-

入力フィールド内の次の文字が変換する文字列内の対応する通常文字と一致していない。

-

入力フィールド内の次の文字がEOFである。

-

変換する文字列が終了した。

-

変換する文字列に変換指示の一部ではない文字の並びが含まれている場合,この同じ文字の並びは入力の中に現れないようにしてください。本関数は一致する文字を走査しますが,格納はしません。不一致があった場合,一致していない最初の文字は読み取られていなかったかのように入力の中に残っています。

[制限]

a,A変換および16進浮動小数点数はサポートしません。