SCANF(3)

名称
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - 入力のフォーマット変換

ライブラリ
libc

書式
<stdio.h> int scanf(const char *format, ...) int fscanf(FILE *stream, const char *format, ...) int sscanf(const char *str, const char *format, ...) <stdarg.h> int vscanf(const char *format, va_list ap) int vsscanf(const char *str, const char *format, va_list ap) int vfscanf(FILE *stream, const char *format, va_list ap)

解説
scanf() 関数ファミリは、後述する format に従って入力を走査します。 このフォーマットには 変換指示子 を含めることができます。 このような変換がある時、その結果は ポインタ 引数を介して格納されます。 scanf() 関数は入力を標準入力ストリーム stdin から読み取ります。 fscanf() は入力をストリームポインタ stream から読み取ります。 sscanf() は入力を str の指すキャラクタ文字列から読み取ります。 vfscanf() 関数は、 vfprintf(3) に類似しており、ポインタの可変引数リスト ( stdarg(3) を参照) を使用して、ストリームポインタ stream から入力を読み取ります。 vscanf() 関数は標準入力から、 vsscanf() 関数は文字列から可変引数リストを走査します。 これらの関数はそれぞれ vprintf() 関数と vsprintf() 関数に類似しています。 連続した各 ポインタ 引数は、連続したそれぞれの変換指示子と 適切に対応している必要があります (ただし、後述の `抑制' を参照)。 変換指示子はすべて % 文字 (パーセント符号) で始まります。 format 文字列には、他の文字も含めることができます。 format 文字列内の空白 (ブランクやタブ、改行など) は、 空白なしを含む任意の量の空白と一致します。 その他の文字はすべてそれ自身とだけ一致します。 入力文字がそのようなフォーマット文字と一致しなくなったときに 走査は停止します。 走査は、入力変換が行えないときにも停止します (下記参照)。

変換
変換の先頭となる % 文字に続いて、以下にあげるいくつかの フラグ 文字をおくことができます。

*   割り当ての抑制。 これに続く変換は普段通りに行われますが、ポインタは使用されません。 変換の結果は単に廃棄されます。

h   変換が dioux または n のどれかであり、次のポインタは ( int ではなく) short int を指すポインタであることを示します。

l   変換が dioux または n のどれかであり、次のポインタが ( int ではなく) long int を指すポインタであること、あるいは変換は efg のどれかであり、次のポインタは ( float ではなく) double を指すポインタであることを示します。

L   変換が efg であり、次のポインタが long double を指すポインタであることを示します (このタイプは実装されていません。 L フラグは現時点では無視されます)。

q   変換が dioux または n のどれかであり、次のポインタが ( int ではなく) long long int を指すポインタであることを示します。

これらのフラグに加えて、オプションとして 10 進整数で表される最大フィールド幅を % と変換の間に置くことも可能です。 フィールド幅を指定しない場合、デフォルトの `無限' が使用されます (例外が 1 つあります。後述)。 フィールド幅を指定した場合、 変換処理において最大でその数の文字が走査されます。 変換が始まる前に、ほとんどの変換は空白をスキップします。 この空白はフィールド幅のカウント対象にはなりません。

以下の変換を利用できます。

%   リテラルの `%' と一致します。 すなわち、フォーマット文字列内の `%%' は、 1 つの入力文字 `%' と一致します。 変換は行われず、割当ては行われません。

d   符号の有無に関わらず、10 進整数に一致します。 次のポインタは int を指すポインタである必要があります。

D   ld と同等です。 これは後方互換性のためにだけ存在しています。

i   符号の有無に関わらず、整数に一致します。 次のポインタは int を指すポインタである必要があります。 整数が ‘0x’ または ‘0X’ で始まる場合、整数を基数 16 で読み取ります。 ‘0’ で始まる場合、基数 8 で読み取ります。 それ以外の場合は、基数 10 です。 基数に対応する文字だけが使用されます。

o   8 進整数と一致します。 次のポインタは unsigned int を指すポインタである必要があります。

O   lo と同等です。 これは後方互換性のために存在しています。

u   符号の有無に関わらず、10 進整数と一致します。 次のポインタは unsigned int を指すポインタである必要があります。

x   符号の有無に関わらず、16 進整数に一致します。 次のポインタは unsigned int を指すポインタである必要があります。

X   lx と同等です。 これは isoC 違反ですが、以前の UNIX システムとは後方互換性があります。

f   符号の有無に関わらず、浮動小数点数と一致します。 次のポインタは float を指すポインタである必要があります。

e   f と同等です。

g   f と同等です。

E   lf と同等です。 これは isoC 違反ですが、以前の UNIX システムとは後方互換性があります。

F   lf と同等です。 これは後方互換性のためにだけ存在します。

s   非空白文字のシーケンスと一致します。 次のポインタは char を指すポインタである必要があり、配列はすべてのシーケンスと終端の NUL 文字を受け入れるのに十分なだけ大きい必要があります。 入力文字列は、空白、または最大フィールド幅のどちらかが 最初に発生した場所で停止します。

c   width 個 (デフォルト 1) の文字のシーケンスに一致します。 次のポインタは char を指すポインタである必要があり、 すべての文字に対して十分な余地がある必要があります (終端の NUL は追加されません)。 通常行われる先頭の空白スキップは抑制されます。 最初の空白をスキップするには、 フォーマット内に明示的なスペースを使用してください。

[   指定された受け入れ文字集合からなる、 空でない文字列と一致します。 次のポインタは、 char を指すポインタである必要があり、 文字列内のすべての文字に加えて終端の NUL 文字を入れる十分な余地がある必要があります。 通常行われる先頭の空白スキップは抑制されます。 文字列は、特定の集合内の (または集合外の) 文字で構成されます。 この集合は、開き角括弧 [ 文字と閉じ角括弧] 文字の間の文字によって定義されます。 集合は、開き角括弧の直後の文字が曲折アクセント記号 ^ である場合、これらの文字を 除外 します。 集合内に閉じ角括弧を入れるには、閉じ角括弧を 開き角括弧または曲折アクセント記号の直後の文字にします。 その他の位置に置くと集合を終了させます。 ハイフン文字 - も特殊です。 他の 2 つの文字間に置かれた場合、 ハイフンは間に入るすべての文字を集合に追加します。 ハイフンを入れるためには、 ハイフンを最後の閉じ角括弧の直前の文字にします。 たとえば、 ‘[^]0-9-]’ は、`閉じ角括弧、0 から 9、およびハイフン以外のすべて' の集合を意味します。文字列は、集合内にない (または曲折アクセント記号がある集合に含まれる) 文字が出現するか、またはフィールド幅が尽きた時に終了します。

p   ( printf(3) で ‘%p’ で印字された) ポインタの値と一致します。 次のポインタは void を指すポインタである必要があります。

n   何も予期しません。 その代わり、入力以降消費された文字の個数が 次のポインタを介して保存されます。 次のポインタは int を指すポインタである必要があります。 これは変換では ありません。 ただし * フラグで抑制できます。

後方互換性のために、他の変換文字 ( ‘\0’ を除く) は ‘%d’ であるかのように、または大文字の場合は ‘%ld’ であるかのように扱われ、 ‘%\0’ の変換はただちに EOF を戻します。 F と X の変換は、将来 ANSI C 標準に適合するように変更される予定なので、 その後では、これらの変換はそれぞれ f と x のように動作するでしょう。

戻り値
これらの関数は、割り当てられた入力項目数を返します。 一致が成功しなかった場合、この数は準備されたものよりも少なく、 または 0 になることさえあります。 0 は、利用できる入力があったものの、 変換が割り当てられなかったことを示します。 通常、これは ‘%d’ 変換に対するアルファベット文字等のような、無効な入力文字のためです。 なんらかの変換が発生する前に、 ファイルの終りのようなことで入力処理が失敗した場合は、値 EOF が返されます。 変換が開始した後で、エラーまたはファイルの終りが発生した場合、 正常に完了した変換の数が返されます。

関連項目
getc(3), printf(3), strtod(3), strtol(3), strtoul(3)

規格
関数 fscanf(), scanf() および sscanf() は isoC に適合しています。

歴史
関数 vscanf(), vsscanf() および vfscanf() はこのリリースではじめて登場しました。

バグ
変換 %F と %X の現在の状況は不都合な状態にあります。

すべての後方互換フォーマットは、将来取り除かれます。

数値文字列は 512 文字に切り捨てられます。 たとえば、 %f と %d は事実上 %512f と %512d です。