SCANF(3) | FreeBSD Library Functions Manual | SCANF(3) |
名称
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf — 入力のフォーマット変換ライブラリ
Standard C Library (libc, -lc)書式
#include < stdio.h> int
scanf( const char * restrict format, ...);
int
fscanf( FILE * restrict stream, const char * restrict format, ...);
int
sscanf( const char * restrict str, const char * restrict format, ...);
#include < stdarg.h>
int
vscanf( const char * restrict format, va_list ap);
int
vsscanf( const char * restrict str, const char * restrict format, va_list ap);
int
vfscanf( FILE * restrict stream, const char * restrict format, va_list ap);
解説
scanf() 関数ファミリは、後述するように format に従って入力をスキャン (走査) します。このフォーマットには、 変換指示子 を含めることができます。そのような変換の結果があれば、ポインタ引数を介して格納されます。 scanf() 関数は標準入力ストリーム stdin から入力を読み込み、 fscanf() はストリームポインタ stream から入力を読み込み、 sscanf() は str で指される文字列から入力を読み込みます。 vfscanf() 関数は、 vfprintf(3) に類似しており、ポインタの可変引数リスト ( stdarg(3) を参照) を使用して、ストリームポインタ stream から入力を読み込みます。 vscanf() 関数は標準入力から可変引数リストをスキャン (走査) し、 vsscanf() 関数は文字列からそれをスキャン (走査) します。これらはそれぞれ vprintf() と vsprintf() 関数に類似しています。それぞれ連続したポインタ引数は、それぞれ連続した変換指示子を適切に対応しなければなりません。 (ただし、下記の * 変換を参照)。すべの変換は % (パーセント記号) 文字で始まります。 format 文字列は、さらに他の文字を含めることができます。 format 文字列内の (ブランク、タブ、改行のような) 空白類は、入力中の空白なしを含む任意の量の空白類と一致します。その他はすべてそれ自身とだけ一致します。入力文字がそのようなフォーマット文字と一致しない場合にスキャン (走査) は停止します。入力変換が行えないときにもスキャン (走査) は停止します (下記を参照)。変換
変換を導入する % 文字に続いて、次のような、いくつかのフラグ文字があります。- *
- 割り当ての抑制。これに続く変換はいつもの通りに行われますが、ポインタは使用されません。変換の結果は単に廃棄されます。
- hh
- 変換が dioux か n のうちの一つであり、次のポインタは ( int ではなく) char を指すポインタであることを示します。
- h
- 変換が dioux または n のうちの一つであり、次のポインタは ( int ではなく) short int を指すポインタであることを示します。
- l (ell)
- 変換が dioux または n のうちの一つであり、次のポインタが ( int ではなく) long int を指すポインタであること、あるいは変換が a, e, f または g のうちの一つであり、次のポインタは ( float ではなく) double を指すポインタであること、あるいは変換が c, s または [ のうちの一つであり、次のポインタは ( char ではなく) wchar_t を指すポインタであることを示します。
- ll (ell ell)
- 変換が dioux または n の一つであり、次のポインタが ( int ではなく) long long int を指すポインタであることを示します。
- L
- 変換が a, e, f または g の一つであり、次のポインタが long double を指すポインタであることを示します
- j
- 変換が dioux または n の一つであり、次のポインタが ( int ではなく) intmax_t を指すポインタであることを示します。
- t
- 変換が dioux または n の一つであり、次のポインタが ( int ではなく) ptrdiff_t を指すポインタであることを示します。
- z
- 変換が dioux または n の一つであり、次のポインタが ( int ではなく) size_t を指すポインタであることを示します。
- q
- (推奨しません。) 変換が dioux または n のうちの一つであり、次のポインタが ( int ではなく) long long int を指すポインタであることを示します。
これらのフラグに加えて、オプションとして 10 進整数で表される最大フィールド幅を % と変換の間に置くこともできます。幅が与えられない場合、デフォルトの“無限 (infinity)”が使用されます (例外が 1 つあります。後述)。そうでなければ、多くてもこの数の文字が変換処理でスキャン (走査) されます。 lc, ls および l[ 変換の場合は、フィールドの幅はスキャンされるマルチバイト文字の最大数を指定します。変換が始まる前に、ほとんどの変換は空白類をスキップします。この空白類はフィールド幅としてカウントされません。
次の変換が利用可能です。
- %
-
リテラル (文字どおり) の‘
%
’と一致します。すなわち、フォーマット文字列内の“%%
”は、 1 つの入力‘%
’文字と一致します。変換は行われず、割当ては生じません。 - d
- 任意の符号の 10 進整数に一致します。次のポインタは int を指すポインタでなければなりません。
- i
-
任意の符号の整数に一致します。次のポインタは
int を指すポインタでなければなりません。整数が‘
0x
’または‘0X
’で始まる場合、16 進数で読み込みます。‘0
’で始まる場合、8 進数で読み込みます。それ以外の場合は、10 進数です。基数 (進数) に対応する文字だけが使用されます。 - o
- 8 進整数と一致します。次のポインタは unsigned int を指すポインタでなければなりません。
- u
- 任意の符号の 10 進整数に一致します。次のポインタは unsigned int を指すポインタでなければなりません。
- x, X
- 任意の符号の 16 進整数に一致します。次のポインタは unsigned int を指すポインタでなければなりません。
- a, A, e, E, f, F, g, G
- strtod(3) のスタイルで浮動小数点数と一致します。次のポインタは ( l または L が指定されなければ) float を指すポインタでなければなりません。
- s
-
非空白類文字のシーケンスと一致します。次のポインタは
char を指すポインタでなければなりません。そして配列はすべてのシーケンスと終端のヌル文字を受け入れるために十分大きくなければなりません。入力文字列は、空白、または最大フィールド幅のどちらかが最初に発生すれば停止します。
l 修飾子が存在しているなら、次のポインタは wchar_t を指すポインタでなければなりません。入力は mbrtowc(3) によって変換した後にそこに置かれます。
- S
- ls と同等です。
- c
-
width 個 (デフォルトは 1) の文字のシーケンスに一致します。次のポインタは
char を指すポインタでなければなりません。すべての文字のために十分な余地がなければなりません。 (終端のヌル文字は加えられません)。先導する空白類の通常のスキップは抑制されます。最初の空白類をスキップするには、フォーマット内に明示的な空白を使用してください。
l 修飾子が存在しているなら、次のポインタは wchar_t を指すポインタでなければなりません。入力は mbrtowc(3) によって変換した後にそこに置かれます。
- C
- lc と同等です。
- [
-
指定された容認された文字集合からなる、空でない文字列と一致します。次のポインタは、
char を指すポインタでなければなりません。終端のヌル文字を加えて文字列内のすべての文字に十分な余地がなければなりません。先導する空白類の通常のスキップは抑制されます。文字列は、特定の集合内の (または集合外の) 文字で構成されます。集合は、開き角括弧
[ 文字と閉じ角括弧
] 文字の間の文字によって定義されます。集合は、開き角括弧の直後の文字がサーカムフレックス (曲折アクセント記号)
^ である場合、これらの文字を除外します。集合内に閉じ角括弧を含めるためには、開き角括弧またはサーカムフレックス (曲折アクセント記号) の直後の文字にします。その他の位置に置くと集合を終了させます。ハイフン文字
- もまた特別です。他の 2 つの文字間に置かれた場合、途中のすべての文字を集合に追加します。ハイフンを含めるためには、ハイフンを最後の閉じ角括弧の直前の文字にします。たとえば、‘
[^]0-9-]
’は、“閉じ角括弧、0 から 9、およびハイフン以外のすべて”の集合を意味します。文字列は、集合内にない (またはサーカムフレックス (曲折アクセント記号) がある集合に含まれる) 文字が出現するか、またはフィールド幅が尽きた時に終了します。l 修飾子が存在しているなら、次のポインタは wchar_t を指すポインタでなければなりません。入力は mbrtowc(3) によって変換した後にそこに置かれます。
- p
-
(
printf(3) で‘
%p
’で印刷されたような) ポインタの値と一致します。次のポインタは void を指すポインタでなければなりません。 - n
- 何も予期されません。その代わり、入力からここまで消費された文字の個数が次のポインタを介して格納されます。そのポインタは int を指すポインタでなければなりません。 * フラグで抑制できますが、これは変換ではありません。
小数点文字はプログラムのロケール (カテゴリ LC_NUMERIC) で定義されます。
後方互換性のために、‘ %\0
’の“変換”はただちに EOF を返します。
戻り値
これらの関数は、割り当てられた入力項目数を返します。この数は提供されたものよりも少なくでき、または、一致が成功しなかった場合、 0 なることさえあります。 0 は、利用可能な入力があった間、変換が割り当てられなかったことを示します。一般的に、これは‘%d
’変換のためのアルファベット文字のような、無効の入力文字のためです。ファイルの終りが生じるようになんらかの変換の前に入力の失敗が生じたなら、値
EOF が返されます。変換が始まった後、エラーまたはファイルの終りが生じる場合、成功して終了した変換の数が返されます。
規格
関数 fscanf(), scanf(), sscanf(), vfscanf(), vscanf() および vsscanf() は ISO/IEC 9899:1999 (“ISO C99”) に適合しています。バグ
scanf の以前の実装は l 修飾子でそれらの小文字の同等物として %D, %E, %F, %O および %X を取り扱いました。さらに、大文字小文字に依存して、 scanf は %d または %D として未知の変換文字を取り扱いました。この機能は取り除いてあります。数値文字列は 512 文字まで切り捨てられます。たとえば、 %f と %d は暗黙のうちに %512f と %512d です。
位置の引数のための %n$ 修飾子は実装されていません。
scanf 関数ファミリは、 フォーマット 引数で正しくマルチバイト文字を取り扱いません。
January 4, 2003 | FreeBSD |