Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all 
名前
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) 参照):
vscanf(), vsscanf(), vfscanf():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
説明
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() が返す代入が
成功した数にこの指定は含まれない。
• For decimal conversions, an optional quote character ('). This specifies that the
input number may include thousands' separators as defined by the LC_NUMERIC
category of the current locale. (See setlocale(3).) The quote character may
precede or follow the '*' assignment-suppression character.
• 文字 'm' (省略可能)。これは文字列変換 (%s, %c, %[) とともに使用され、これを使うと
呼び出し元が入力を保持する対応するバッファーを確保する必要がなくなる。 代わりに
scanf() が必要な大きさのバッファーを確保し、このバッファーのアドレスを 対応する
pointer 引数に代入する。 pointer 引数は char * 型の変数へのポインターでなければなら
ない (変数自体は呼び出し前に初期化されている必要はない)。 呼び出し元は、不要になっ
た時点で、このバッファーを free(3) すべきである。
• 「最大フィールド幅」 を指定する 10進数 (省略可能)。 この最大値に達するか、一致しな
い文字が見つかるか、のどちらかに なると、文字の読み込みを停止する。 ほとんどの変換
では、先頭のホワイトスペース文字は捨てられ (例外については後述する)、 捨てられたこ
れらの文字は最大フィールド幅の計算には含まれない。 文字列の入力変換では、入力の末尾
を示す終端のヌルバイト ('\0') も格納されるが、最大フィールド幅にはこの終端バイトは
含まれない。
• 「型修飾子」 (type modifier characters) (省略可能)。 例えば、型修飾子 l を %d など
の整数変換と一緒に使うと、対応する pointer 引数が int ではなく long を参照している
ことを指定できる。
• 「変換指定」 : 実行すべき入力変換の種類を指定する。
format 中の変換指定は、'%' で始まるか、 "%n$" で始まるかの、いずれかの形式である。 これら
2つの形式を同じ format 文字列に混ぜることはできない。但し、"%n$" を 含む文字列に %% と %*
を含めることはできる。 format に '%' 指定が含まれている場合、各々の '%' 指定と 後続の
pointer 引数はその順番通りに対応する。 "%n$" 形式 (POSIX.1-2001 では規定されているが、C99
にはない) では、 n は 10進数であり、変換後の入力を format の後ろの n 番目の pointer 引数
が参照する場所に格納することを指定する。
変換
変換指定には、以下の 「型修飾子」 を入れることができる。
h 変換が d, i, o, u, x, X, n のいずれかであり、次のポインターが (int ではなく) short
か unsigned short へのポインターであることを示す。
hh h と同じだが、次のポインターが signed char か unsigned char へのポインターであるこ
とを示す。
j h と同じだが、次のポインターが intmax_t か uintmax_t へのポインターであることを示
す。 この修飾子は C99 で導入された。
l 変換が d, i, o, u, x, X, n か n のいずれかであり次のポインターが (int ではなく)
long か unsigned long へのポインターであること、または、変換が 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 へのポインターでなければなら
ない。
i 符号つき整数に対応する。 次のポインターは int へのポインターでなければならない。 こ
の整数は 0x または 0X で開始する場合には 16 進数、 0 で開始する場合には 8 進数、そ
の他の場合には 10進数として読み込まれる。 この変換で使用される文字は、これらの基数
に対応しているものだけである。
o 符号なしの 8 進の整数に対応する。 次のポインターは unsigned int でなければならな
い。
u 符号なしの 10進の整数に対応する。 次のポインターは unsigned int へのポインターでな
ければならない。
x Matches an unsigned hexadecimal integer (that may optionally begin with a prefix of
0x or 0X, which is discarded); the next pointer must be a pointer to unsigned int.
X x と同一である。
f 符号つき浮動小数点実数に対応する。 次のポインターは float へのポインターでなければ
ならない。
e f と同一である。
g f と同一である。
E f と同一である。
a (C99) f と同一である。
s Matches a sequence of non-white-space characters; the next pointer must be a
pointer to the initial element of a character array that is long enough to hold the
input sequence and the terminating null byte ('\0'), which is added automatically.
The input string stops at white space or at the maximum field width, whichever
occurs first.
c 「最大フィールド幅」 (デフォルトは 1) で指定された幅の文字の列に対応する。 次のポイ
ンターは char へのポインターで、すべての文字を格納するのに十分な領域が なければなら
ない (終端のヌルバイトは追加されない)。 通常行われる先頭のホワイトスペースの読み飛
ばしは行われない。 先頭のホワイトスペースを読み飛ばすためには、 フォーマット文の中
で明示的にスペースを使用すれば良い。
[ 格納された文字列のうちから取り出された、 指定された文字の集合で構成される空ではない
文字の列に対応する。 次のポインターは char へのポインターでなければならず、 そこに
は文字列中のすべての文字と終端のヌルバイト を格納するための十分な領域がなければなら
ない。 通常行われる先頭のホワイトスペースの読み飛ばしは行われない。 この文字列は特
別な集合の中の文字で構成されている。 この集合は 開き括弧 [ と閉じ括弧 ] の間の文字
で定義される。 開き括弧のあとの最初の文字が曲アクセント記号 (^) の場合、集合はこれ
らの文字を含まないものとなる。 閉じ括弧を集合に含ませるためには、この文字を開き括弧
または 曲アクセント記号のあとの最初の文字にすればよい。 つまり、他の位置に閉じ括弧
を置くと文字の集合が終る。 ハイフン - もまた特殊文字である。 二つの異なる文字の間に
置かれた時、この文字は、 その間にある全ての文字を集合に加える。 ハイフン自体を含ま
せるためには、 括弧が閉じる前の最後の一文字をハイフンにすればよい。 例えば、
[^]0-9-] は「閉じ括弧、0 〜 9、ハイフンの 3 種類を除く全ての文字」の集合を意味す
る。 この文字列は 集合に含まれていない (曲アクセントの場合には含まれる) 文字の 出現
または確保された領域が使い切られた時に終了する。
p (printf(3) の %p で印字されるような) ポインター値に対応する。 次のポインターは
void へのポインターへのポインターでなければならない。
n Nothing is expected; instead, the number of characters consumed thus far from the
input is stored through the next pointer, which must be a pointer to int. This is
not a conversion and does not increase the count returned by the function. The
assignment can be suppressed with the * assignment-suppression character, but the
effect on the return value is undefined. Therefore %*n conversions should not be
used.
返り値
成功すると、これらの関数は、一致と代入が成功した入力要素の個数を返す。 返される値は渡され
た変換の個数よりも少ないこともあり、 最初に一致の失敗があった場合には 0 になることもある。
最初の変換が成功する前に入力の最後に達して、一致の失敗が起こった場合には、 EOF が返され
る。また、 読み込みエラーが発生した場合にも EOF が返される。読み込みエラーの場合には、その
ストリームの エラー指示子がセットされ (ferror(3) 参照)、 errno にエラーを示す値がセットさ
れる。
エラー
EAGAIN stream に対応するファイルディスクリプターが nonblocking となっており、 読み込み操作
は停止 (block) することになる。
EBADF stream に対応するファイルディスクリプターが無効であるが、 読み込み用にオープンされ
ていない。
EILSEQ 入力されたバイト列が有効な文字を構成していない。
EINTR 読み込み操作がシグナルにより割り込まれた。 signal(7) 参照。
EINVAL 引数が十分でない。または format が NULL である。
ENOMEM メモリー不足。
ERANGE 整数変換の結果が、対応する整数型に格納できるサイズを越えてしまう。
属性
この節で使用されている用語の説明については、 attributes(7) を参照。
┌─────────────────────┬───────────────┬────────────────┐
│インターフェース │ 属性 │ 値 │
├─────────────────────┼───────────────┼────────────────┤
│ scanf(), fscanf(), │ Thread safety │ MT-Safe locale │
│ sscanf(), vscanf(), │ │ │
│ vsscanf(), │ │ │
│vfscanf() │ │ │
└─────────────────────┴───────────────┴────────────────┘
準拠
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 文書に目を通すこと。
注意
'a' 代入割り当て (assignment-allocation) 修飾子
元々、 GNU C ライブラリ (glibc) では、 a 文字による文字列入力に対する動的割り当て変換指定
子 (dynamic allocation conversion specifier) を (非標準の拡張として) サポートしている。こ
の機能は少なくとも glibc 2.0 の時点ではすでに存在している。 したがって、以下のようにして、
scanf() に入力文字列に対してバッファーを割り当てさせることができる。割り当てられたバッ
ファーは *buf で返される。
char *buf;
scanf("%as", &buf);
この目的で文字 a を使うのは問題をはらんでいる。 なぜなら、 a は ISO C 標準では (浮動小数点
入力を表す) の f の同義語として定義されているからである。 その代わり、 POSIX.1-2008 で
は、(上記の「説明」に書かれている通り) 代入割り当てを行う修飾子として m が規定されている。
a 修飾子は gcc -std=c99 や gcc -D_ISOC99_SOURCE でコンパイルしたプログラムでは
(_GNU_SOURCE も同時に指定していない場合) 利用できない点に注意。この場合、 a は (上述の通
り) 浮動小数点数を示す変換指定子と解釈される。
m 修飾子への対応はバージョン 2.7 以降の glibc で追加されている。新しいプログラムでは a の
代わりに m を使用すべきである。
POSIX で標準化されているだけでなく、 m 修飾子には a を利用する場合に比べて以下のような利点
がある。
* %c 変換指定子にも適用できる (例えば %3mc)。
* 浮動小数点変換指定子としての %a との紛らわしさが避けられる (また gcc -std=c99 などの影響
も避けられる)。
バグ
全ての関数は、完全に 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 プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。