BohYoh.comトップページへ  fscanf
C言語 標準ライブラリ アルファベット順索引 ヘッダ別索引 ホームページへ C言語講座のページ

書式付き入出力関数
scanf
ヘッダ #include <stdio.h>
形 式 int fscanf(FILE *stream, const char *format, ...);
機 能 scanf関数は、streamが指すストリームからの入力を変換し、formatに続く実引数が指すオブジェクトに代入する。formatが指す文字列は入力として許される文字列とそれらの代入時の変換方法とを指定する書式とする。書式に見合うだけの実引数がないときの動作は定義されない。実引数が残っているにもかかわらず書式が尽きてしまう場合、余分の実引数は評価するだけで無視する。
 書式は、初期シフト状態で始まり初期シフト状態で終わる多バイト文字列でなければならない。書式は、0個以上の指令からなる。指令は、1個以上の空白類文字、(%でも空白類文字でもない)通常の多バイト文字、または変換指定とする。
 各変換指定の先頭には、文字%が先行する。%の後ろには、次のものがこの順序で現れる。
(a) 代入抑止文字の* … 省略可

(b) 最大フィールド幅を指定する0以外の10進整数 … 省略可

(c) 変換結果を受け取るオブジェクトの大きさを示すh、l(エル)またはL … 省略可
変換指定子d、iおよびnに対応する実引数が、int型へのポインタではなくshort int型へのポインタである場合、hを変換指定子に前置しなければならない。更に実引数がlong int型へのポインタであるときは、lを変換指定子に前置しなければならない。同様に、変換指定子o、uおよびxに対応する実引数が、unsigned int型へのポインタではなくunsigned short int型へのポインタであるときはhを、unsigned long int型へのポインタであるときはlを、前置しなければならない。最後に変換指定子e、fおよびgに対応する実引数が、float型へのポインタではなくdouble型へのポインタであるときにはlを、long double型へのポインタであるときはLを、それぞれの変換指定子に前置しなければならない。h、lまたはLをこれら以外の変換指定子とともに指定した場合の動作は、定義されない。

(d) 適用する変換の方法を指定する文字適用する変換の方法を指定する文字
fscanf関数は、書式内の各命令を順に実行する。指令の実行が失敗すると、fscanf関数は呼出しもとに復帰する。この失敗には、(入力文字が得られないことによる)入力誤りと(不適切な入力による)照合誤りとがある。
空白類文字で構成される指令は、最初の非空白類文字の直前まで(この文字は読まずに残す)、またはそれ以上読み取ることができなくなるまで、入力読取りを実行する。
通常の多バイト文字の指令は、ストリームでの次の文字の読取りを実行する。入力した文字が指定を構成する文字と異なる場合、その指令は失敗し、その入力文字およびそれ以降の文字は読まれないままストリーム上に残る。
変換指定の指令は照合入力列の集合を、各指定子に対する規定に基づいて定義する。変換指定の実行は、次の手順に従う。
変換指定が[、cまたはn指定子を含まない場合、(isspace関数で規定される)空白類文字列を読み飛ばす。
変換指定がn指定子を含まなければ、ストリームから入力項目を読み取る。入力項目を、入力文字列中の最長の照合列として定義する。ただし、最長の照合列の長さが指定されたフィールド幅を越える場合の入力項目は、照合列の先頭からの部分列で、その長さはフィールド幅とする。入力項目に続く文字が存在する場合、その先頭の文字は読まないまま残る。入力項目の長さがゼロのとき、指令の実行は失敗となる。この状態は、照合誤りとする。ただし、何らかのエラーのために、ストリームからの入力ができないときの失敗は、入力誤りとする。 %指定子の場合を除いて、変換指定は入力項目を(または、%n指定のときには入力文字数を)、変換指定子に対応した適切な型に変換する。入力項目が照合列でないとき、指令の実行は失敗となる。この状態は、照合誤りとする。代入抑止文字*が指定されていなければ、実引数formatに続く実引数のうち、変換結果をまだ受け取っていない先頭のものが指すオブジェクトに、変換結果を代入する。このオブジェクトが適切な型をもたない場合、または変換結果が与えられた記憶領域内で表現できなかった場合、動作は定義されない。
有効な変換指定子は、次のとおりである。

d 符号が省略可能な10進整数。その形式は、実引数baseに値10を指定したときのstrtol関数の変換対象列と形式を同じとする。この指定子に対応する実引数は、整数へのポインタでなければならない。
i 符号が省略可能な整数。その形式は、実引数baseに値0を指定したときのstrtol関数の変換対象列の形式と同じとする。この指定子に対応する実引数は、整数へのポインタでなければならない。
o 符号が省略可能な8進整数。その形式は、実引数baseに値8を指定したときのstrtoul関数の変換対象列の形式と同じとする。この指定子に対応する実引数は、符号無し整数へのポインタでなければならない。
u 符号が省略可能な10進整数。その形式は、実引数baseに値10を指定したときのstrtoul関数の変換対象列の形式と同じとする。この指定子に対応する実引数は、符号無し整数へのポインタでなければならない。
x 符号が省略可能な16進整数。その形式は、実引数baseに値16を指定したときのstrtoul関数の変換対象列の形式と同じとする。この指定子に対応する実引数は、符号無し整数へのポインタでなければならない。
e、f、g 符号が省略可能な浮動小数点。その形式は、strtod関数の変換対象列の形式と同じとする。この指定子に対応する実引数は、浮動小数点へのポインタでなければならない。
s 非空白類文字の列。この指定子に対応する実引数は、文字の列全部と終端ナル文字とを受け取れる大きさをもつ配列への先頭文字へのポインタでなければならない。この変換は、文字列の終わりを示すナル文字を自動的に付加する。
[期待される文字集合[走査文字集合(scanset)]の要素の空でない列 この指定子に対応する実引数は、文字の列全部と終端ナル文字とを受け取れる大きさをもつ配列の先頭文字へのポインタでなければならない。この変換は、文字列の終わりを示すナル文字を自動的に付加する。変換指定子は、この左角括弧の対になる右角括弧(])とそこまでのformat文字列中のすべての文字の列とする。左角括弧の直後がアクサンシルコンフレックス(^)でないときに、左右の角括弧間のすべての文字[走査文字の並び(scanlist)]が走査文字集合を構成する。左角括弧の直後がアクサンシルコンフレックスであるときの走査文字集合は、そのアクサンシルコンフレックスと右角括弧の間にある走査文字の並びに現れないすべての文字とする。変換指定子が[ ]または[^]で始まっているときには、右角括弧を走査文字の並びに含め、その次に現れる右角括弧を変換指定の終了とする。変換指定子の開始が[ ]でも[^]でもないときの変換指定の終わりの文字は、最初の右角括弧とする。文字-(ハイフン)が走査文字の並びに含まれ、かつ走査文字の先頭の文字(先頭が^のときは2文字目)でも最後の文字でもない場合の動作は、処理系定義とする。
c フィールド幅(指令中にフィールド幅がないときは1とする)で指定された長さの文字の列。この指定子に対応する実引数は、文字の列を受け取れる大きさをもつ配列の先頭文字へのポインタでなければならない。この変換は、ナル文字を付加しない。
p 処理系定義の文字の列の集合。この集合は、fprintf関数での%p変換が生成する文字の列の集合と同じとする。この指定子に対応する実引数は、voidへのポインタへのポインタでなければならない。入力項目の解釈は、処理系定義とする。入力項目が、同一プログラム内で以前に変換した値である場合、結果のポインタ値は、その変換前の値と等しくなる。これ以外の場合、%p変換の動作は定義されない。
n 入力を読み取らない。この指定子に対応する実引数は、整数へのポインタでなければなりません。fscanf関数の呼出しでこれまでに入力ストリームから読み取った文字数を、その整数に書き込む。%n指令を実行しても、fscanf関数が終了時に返却する入力項目の個数は増加しない。
% 一つの%を照合する。変換も代入も起こらない。変換指定全体は、%%でなければならない。
 変換指定が無効であるときの動作は、未定義とする。
 変換指定子E、GおよびXも有効であり、それぞれe、gおよびxと同じ動作をする。
 入力中にファイルの終わりを検出すると、変換は終了する。現在の指令にマッチする文字を1文字も(先行して読み飛ばされる空白類文字が許される場合、それらを除く。)読み取らないままファイルの終わりを検出すると、その指令の実行は入力誤りで終了する。現在の指令に照合する文字を1文字でも読み取った後でファイルの終わりを検出すると、その指令が照合誤りとならない限り、それに続く指令(もし存在すれば)の実行が入力誤りによる終了となる。
 指令と矛盾する入力文字によって変換が終了した場合、その矛盾した入力文字は読まれないまま入力ストリーム上に残る。入力中で後続する(改行文字を含む)空白類は、指令に照合しない限り読み込まれないまま残る。通常の多バイト文字指令および代入抑止を含む変換指定の成功を、%n指令以外で直接判定することはできない。
返却値 変換が一つでも行われないまま入力誤りが発生すると、マクロEOFの値を返す。それ以外の場合、代入された入力項目の個数を返す。この個数は、入力中に照合誤りが発生すると、変換指定子に対応する実引数の個数よりも少なくなることもあり、0になることもある。


BohYoh.comトップページへ