other versions
SCANF(3) | Linux Programmer's Manual | SCANF(3) |
名前¶
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - 書式付き入力変換書式¶
#include <stdio.h> int scanf(const char *format, ...); int fscanf(FILE *stream, const char *format, ...); int sscanf(const char *str, const char *format, ...);#include <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);
glibc 向けの機能検査マクロの要件 ( feature_test_macros(7) 参照):
_XOPEN_SOURCE >= 600 ||
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L;
or cc -std=c99
説明¶
scanf() 関数グループは、以下に述べるように、 format に従って入力を読み込むものである。 この書式には 「変換指定」 (conversion specifications) を含めることができ、変換指定があれば、その変換の結果は format に続く pointer 引き数が指す場所に格納される。 それぞれの pointer 引き数の型は、対応する変換指定が返す値に 適合していなければならない。- •
- ホワイトスペース (スペース、タブ、改行など; isspace(3) 参照) の列。 この命令は、入力中の任意の個数のホワイトスペースに一致する。 (「何もなし」にも一致する)。
- •
- 通常文字 (つまり、ホワイトスペースと '%' 以外の文字)。 この文字は入力の次の文字に正確に一致しなければならない。
- •
- 変換指定。変換指定は '%' (パーセント) 文字で始まる。 入力された文字の系列はこの指定にもとづいて変換され、 変換結果は対応する pointer 引き数が指す場所に格納される。 入力の次の文字が変換指定と一致しない場合は、変換は失敗する —これが 「一致の失敗」 (matching failure) である。
- •
- 代入抑制文字 '*' (省略可能)。 scanf() は変換指定に指示された通り入力を読み込むが、その入力は捨てられる。 対応する pointer 引き数は必要なく、 scanf() が返す代入が成功した数にこの指定は含まれない。
- •
- 文字 'a' (省略可能)。これは文字列変換とともに使用され、これを使うと 呼び出し元が入力を保持する対応するバッファを確保する必要がなくなる。 代わりに scanf() が必要な大きさのバッファを確保し、このバッファのアドレスを 対応する pointer 引き数に代入する。 pointer 引き数は char * 型の変数へのポインタでなければならない (変数自体は呼び出し前に初期化されている必要はない)。 呼び出し元は、不要になった時点で、このバッファを free(3) すべきである。この機能は GNU による拡張である。 C99 は 'a' 文字を変換指定として使用している (こちらも GNU の実装と同じように使用することができる)。
- •
- 「最大フィールド幅」 を指定する 10進数 (省略可能)。 この最大値に達するか、一致しない文字が見つかるか、のどちらかに なると、文字の読み込みを停止する。 ほとんどの変換では、先頭のホワイトスペース文字は捨てられ (例外については後述する)、 捨てられたこれらの文字は最大フィールド幅の計算には含まれない。 文字列の入力変換では、入力の末尾を示す終端の NULL バイト ('\0') も格納されるが、最大フィールド幅にはこの終端バイトは含まれない。
- •
- 「型修飾子」 (type modifier characters) (省略可能)。 例えば、型修飾子 l を %d などの整数変換と一緒に使うと、対応する pointer 引き数が int ではなく long int を参照していることを指定できる。
- •
- 「変換指定」 : 実行すべき入力変換の種類を指定する。
変換¶
変換指定には、以下の 「型修飾子」 を入れることができる。- h
- 変換が d, i, o, u, x, X, n のいずれかであり、次のポインタが ( int ではなく) short int か unsigned short int へのポインタであることを示す。
- hh
- h と同じだが、次のポインタが signed char か unsigned char へのポインタであることを示す。
- j
- h と同じだが、次のポインタが intmax_t か uintmax_t へのポインタであることを示す。 この修飾子は C99 で導入された。
- l
- 変換が d, i, o, u, x, X, n か n のいずれかであり次のポインタが ( int ではなく) long int か unsigned long int へのポインタであること、または、変換が e, f, g のうちのひとつであり次のポインタが ( float ではなく) double へのポインタであることのいずれかであることを示す。 l 文字を二つ指定すると、 L と同じ意味となる。 %c や %s とともに使用すると、 パラメータはそれぞれワイド文字やワイド文字列へのポインタであると みなされる。
- L
- e, f, g 変換で、次のポインタが long double へのポインタであることを示す。もしくは、 d, i, o, u, x 変換で、次のポインタが long long へのポインタであることのいずれかであることを示す。
- q
- L と同一である。 この修飾子は ANSI C には存在しない。
- t
- h と同様だが、次のポインタが ptrdiff_t へのポインタであることを示す。 この修飾子は C99 で導入された。
- z
- h と同様だが、次のポインタが size_t へのポインタであることを示す。 この修飾子は C99 で導入された。
- %
- 文字 '%' に対応する。 書式文字列の中の %% は単一の文字 '%' に対応する。 変換は行われず (但し、先頭のホワイトスペース文字は捨てられる)、 変数への代入は生じない。
- d
- 符号つきの 10進の整数に対応する。 次のポインタは int へのポインタでなければならない。
- D
- ld と同一である。これは以前の仕様との互換性だけのためにある。 (注意: これは libc4 の場合だけである。 libc5 や glibc では %D は暗黙のうちに無視され、古いプログラムにおいて謎に満ちた失敗の原因となる。)
- i
- 符号つき整数に対応する。 次のポインタは int へのポインタでなければならない。 この整数は 0x または 0X で開始する場合には 16 進数、 0 で開始する場合には 8 進数、その他の場合には 10進数として読み込まれる。 この変換で使用される文字は、これらの基数に対応しているものだけである。
- o
- 符号なしの 8 進の整数に対応する。 次のポインタは unsigned int でなければならない。
- u
- 符号なしの 10進の整数に対応する。 次のポインタは unsigned int へのポインタでなければならない。
- x
- 符号なしの 16 進の整数に対応する。 次のポインタは unsigned int へのポインタでなければならない。
- X
- x と同一である。
- f
- 符号つき浮動小数点実数に対応する。 次のポインタは float へのポインタでなければならない。
- e
- f と同一である。
- g
- f と同一である。
- E
- f と同一である。
- a
- (C99) f と同一である。
- s
- ホワイトスペースではない文字で構成された文字列に対応する。 次のポインタは文字の配列へのポインタでなければならず、 その文字配列は、入力された文字列と (自動的に追加される) 終端の NULL バイト ('\0') を格納するのに十分な大きさでなければならない。 文字列の入力は、ホワイトスペースが入力されるか、最大フィールド幅に 達するか、のどちらかが起こると停止される。
- c
- 「最大フィールド幅」 (デフォルトは 1) で指定された幅の文字の列に対応する。 次のポインタは char へのポインタで、すべての文字を格納するのに十分な領域が なければならない (終端の NULL バイトは追加されない)。 通常行われる先頭のホワイトスペースの読み飛ばしは行われない。 先頭のホワイトスペースを読み飛ばすためには、 フォーマット文の中で明示的にスペースを使用すれば良い。
- [
- 格納された文字列のうちから取り出された、 指定された文字の集合で構成される空ではない文字の列に対応する。 次のポインタは char へのポインタでなければならず、 そこには文字列中のすべての文字と終端の NULL バイト を格納するための十分な領域がなければならない。 通常行われる先頭のホワイトスペースの読み飛ばしは行われない。 この文字列は特別な集合の中の文字で構成されている。 この集合は 開き括弧 [ と閉じ括弧 ] の間の文字で定義される。 開き括弧のあとの最初の文字が曲アクセント記号 ( ^) の場合、集合はこれらの文字を含まないものとなる。 閉じ括弧を集合に含ませるためには、この文字を開き括弧または 曲アクセント記号のあとの最初の文字にすればよい。 つまり、他の位置に閉じ括弧を置くと文字の集合が終る。 ハイフン - もまた特殊文字である。 二つの異なる文字の間に置かれた時、この文字は、 その間にある全ての文字を集合に加える。 ハイフン自体を含ませるためには、 括弧が閉じる前の最後の一文字をハイフンにすればよい。 例えば、 [^]0-9-] は「閉じ括弧、0 〜 9、ハイフンの 3 種類を除く全ての文字」の集合を意味する。 この文字列は 集合に含まれていない (曲アクセントの場合には含まれる) 文字の 出現または確保された領域が使い切られた時に終了する。
- p
- (printf(3) の %p で印字されるような) ポインタ値に対応する。 次のポインタは void へのポインタへのポインタでなければならない。
- n
- どんな入力も必要としない。 そのかわりに、 入力からここまで消費された文字数が次のポインタで指定された場所に 格納される。 このポインタは int へのポインタでなければならない。 変換を抑制するのであれば * 代入抑制文字を使って抑制することができるのだが、 この変換指定子は変換では「ない」。 C 言語の標準規格では「実行の完了時に返される代入の回数は %n 命令の実行では増加しない」となっているが、 正誤表の内容はこれと矛盾するようである。おそらく、 %n 変換が返り値に与える影響についてはどのような仮定もしないのが 賢明であろう。
返り値¶
これらの関数は、一致と代入が成功した入力要素の個数を返す。 返される値は渡された変換の個数よりも少ないこともあり、 最初に一致の失敗があった場合には 0 になることもある。エラー¶
- EAGAIN
- stream に対応するファイルディスクリプタが nonblocking となっており、 読み込み操作は停止 (block) することになる。
- EBADF
- stream に対応するファイルディスクリプタが無効であるが、 読み込み用にオープンされていない。
- EILSEQ
- 入力されたバイト列が有効な文字を構成していない。
- EINTR
- 読み込み操作がシグナルにより割り込まれた。 signal(7) 参照。
- EINVAL
- 引き数が十分でない。または format が NULL である。
- ENOMEM
- メモリ不足。
- ERANGE
- 整数変換の結果が、対応する整数型に格納できるサイズを越えてしまう。
準拠¶
fscanf(), scanf(), sscanf() 関数は C89, C99, POSIX.1-2001 に準拠している。 これらの標準では、エラー ERANGE は規定されていない。 q 指定子は long long の 4.4BSD での記述方法である。 一方、整数変換での ll または L の使用は GNU での拡張である。 これらの関数の Linux 版は GNU libio ライブラリーを元にしている。 より簡潔な説明には GNU libc (glibc-1.08) の info 文書に目を通すこと。注意¶
GNU C ライブラリ (glibc) では非標準のオプションをサポートしており、 このオプションを使うと変換指定子 %s や %a[range] への入力文字列に対して十分な大きさの文字列をライブラリが動的に確保する ようになる。 この機能を使用するには、長さ修飾子として a を指定する (したがって、全体としては %as や %a[range] となる)。 以下の例にあるように、呼び出し側は返された文字列を free(3) しなければならない。char *p; int n; errno = 0; n = scanf("%a[a-z]", &p); if (n == 1) { printf("read: %s\n", p); free(p); } else if (errno != 0) { perror("scanf"); } else { fprintf(stderr, "No matching characters\n"); }
上記の例にあるように、 scanf() が文字列の読み込みに成功した場合にだけ、 free(3) を呼び出す必要がある。 gcc -std=c99 や gcc -D_ISOC99_SOURCE でコンパイルしたプログラムでは ( _GNU_SOURCE も同時に指定していない場合)、 a 修飾子は利用できない。 上記の場合、 a は (上述の通り) 浮動小数点数を示す変換指定子と解釈される。
- *
- %c 変換指定子にも適用できる (例えば %3mc)。
- *
- 浮動小数点変換指定子としての %a との紛らわしさが避けられる (また gcc -std=c99 などの影響も避けられる)。
- *
- POSIX.1 標準の次の改訂版で規定される。
バグ¶
全ての関数は、完全に C89 に準拠している。しかし 追加で q と a 指定子が提供されており、同様に L と l 指定子の付加的な振る舞いもある。後者は、 C89 で定義された指定子の振る舞いを変更するものなので、 バグとみなされるかもしれない。 ANSI C で定義された型修飾子と変換指定子の組み合わせの中には 意味を なさないものがある (例えば、 %Ld)。 これらが指定された場合、 Linux 上でははっきりと定義された振る舞いをするかもしれないが、 他のアーキテクチャでも同様になっているとは限らない。 それゆえに、ほとんどの場合、 ANSI C で定義されていない修飾子を使用した 方が良い。すなわち、 d, i, o, u, x, X 変換や ll と組み合わせる場合には、 L の代わりに q を使用した方が良い。 q の使用方法は 4.4BSD と同じではない。 4.4BSD では q は L と同等に浮動小数の変換に使用される。関連項目¶
getc(3), printf(3) setlocale(3), strtod(3), strtol(3), strtoul(3),この文書について¶
この man ページは Linux man-pages プロジェクトのリリース 3.41 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。2011-09-28 | GNU |