名前

#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) 参照):

vscanf(), vsscanf(), vfscanf():

scanf() 関数グループは、以下に述べるように、 format に従って入力を読み込むものである。 この書式には 「変換指定」 (conversion specifications) を含めることができ、変換指定があれば、その変換の結果は format に続く pointer 引き数が指す場所に格納される。 それぞれの pointer 引き数の型は、対応する変換指定が返す値に 適合していなければならない。

format 中の変換指定の個数が pointer 引き数の数より多かった場合の結果は未定義である。 pointer 引き数の数が変換指定の個数よりも多かった場合、 余分な pointer 引き数の評価は行われるが、それ以外は行われず無視される。

scanf() 関数は標準入力ストリーム stdin からの入力を読み込む。 fscanf() はストリームポインタ stream からの入力を読み込む。 sscanf() は文字列ポインタ str で示された文字列からの入力を読み込む。

vfscanf() 関数は vfprintf(3) と同様に、ストリームポインタ stream からの入力をポインタの可変長引き数リストを用いて読み込む (stdarg(3) を参照)。 vscanf() 関数は、可変長引き数のリストに基づき標準入力からの読み取りを行う。 vsscanf() 関数はそのリストに基づき文字列から読み取る。 これらの関係は vprintf(3) と vsprintf(3) 関数の関係と同様である。

format 文字列は 「命令」 (directive) の列で構成される。命令は入力文字の系列をどのように処理するかを指示する ものである。ある命令の処理が失敗すると、入力はそれ以上読み込まれず、 scanf() は返る。「失敗」は 「入力の失敗」 (input failure) と 「一致の失敗」 (matching failure) のいずれかである。 入力の失敗は入力文字が使用できなかったことを意味し、 一致の失敗は入力が不適切であったこと (下記参照) を意味する。

命令は以下のいずれかである:

• ホワイトスペース (スペース、タブ、改行など; isspace(3) 参照) の列。 この命令は、入力中の任意の個数のホワイトスペースに一致する。 (「何もなし」にも一致する)。
• 通常文字 (つまり、ホワイトスペースと '%' 以外の文字)。 この文字は入力の次の文字に正確に一致しなければならない。
• 変換指定。変換指定は '%' (パーセント) 文字で始まる。 入力された文字の系列はこの指定にもとづいて変換され、 変換結果は対応する pointer 引き数が指す場所に格納される。 入力の次の文字が変換指定と一致しない場合は、変換は失敗する —これが 「一致の失敗」 (matching failure) である。

format 中の各々の 「変換指定」 は文字 '%' か文字系列 "%n$" (違いについては後述) で始まり、以下の要素が続く。

• 代入抑制文字 '*' (省略可能)。 scanf() は変換指定に指示された通り入力を読み込むが、その入力は捨てられる。 対応する pointer 引き数は必要なく、 scanf() が返す代入が成功した数にこの指定は含まれない。
• 文字 'm' (省略可能)。これは文字列変換 (%s, %c, %[) とともに使用され、これを使うと 呼び出し元が入力を保持する対応するバッファを確保する必要がなくなる。 代わりに scanf() が必要な大きさのバッファを確保し、このバッファのアドレスを 対応する pointer 引き数に代入する。 pointer 引き数は char * 型の変数へのポインタでなければならない (変数自体は呼び出し前に初期化されている必要はない)。 呼び出し元は、不要になった時点で、このバッファを free(3) すべきである。
• 「最大フィールド幅」 を指定する 10進数 (省略可能)。 この最大値に達するか、一致しない文字が見つかるか、のどちらかに なると、文字の読み込みを停止する。 ほとんどの変換では、先頭のホワイトスペース文字は捨てられ (例外については後述する)、 捨てられたこれらの文字は最大フィールド幅の計算には含まれない。 文字列の入力変換では、入力の末尾を示す終端のヌルバイト ('\0') も格納されるが、最大フィールド幅にはこの終端バイトは含まれない。
• 「型修飾子」 (type modifier characters) (省略可能)。 例えば、型修飾子 l を %d などの整数変換と一緒に使うと、対応する pointer 引き数が int ではなく long int を参照していることを指定できる。
• 「変換指定」 : 実行すべき入力変換の種類を指定する。

format 中の変換指定は、'%' で始まるか、 "%n$" で始まるかの、いずれかの形式である。 これら 2つの形式を同じ format 文字列に混ぜることはできない。但し、"%n$" を 含む文字列に %% と %* を含めることはできる。 format に '%' 指定が含まれている場合、各々の '%' 指定と 後続の pointer 引き数はその順番通りに対応する。 "%n$" 形式 (POSIX.1-2001 では規定されているが、C99 にはない) では、 n は 10進数であり、変換後の入力を format の後ろの n 番目の pointer 引き数が参照する場所に格納することを指定する。

これらの関数は、一致と代入が成功した入力要素の個数を返す。 返される値は渡された変換の個数よりも少ないこともあり、 最初に一致の失敗があった場合には 0 になることもある。

最初の変換が成功する前に入力の最後に達して、一致の失敗が起こった場合には、 EOF が返される。また、 読み込みエラーが発生した場合にも EOF が返される。読み込みエラーの場合には、そのストリームの エラー指示子がセットされ (ferror(3) 参照)、 errno にエラーを示す値がセットされる。

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 文書に目を通すこと。

全ての関数は、完全に 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 と同等に浮動小数の変換に使用される。

動的割り当て変換指定子を使用するには、長さ修飾子として m を指定する (つまり、全体としては %ms や %m[range] となる)。以下の例にあるように、呼び出し側は返された文字列を free(3) しなければならない。

char *p;
int n;
errno = 0;
n = scanf("%m[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) を呼び出す必要がある。

getc(3), printf(3) setlocale(3), strtod(3), strtol(3), strtoul(3),

この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。