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) 参照):
vscanf(), vsscanf(), vfscanf(): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE;
or cc -std=c99
scanf() 関数グループは、以下に述べるように、 format
に従って入力を読み込むものである。 この書式には (conver-
sion 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) のいずれかである。
入力の失敗は入力文字が使用でい覆ったことを意味し、
一致の失敗は入力が不適切であったこと (下技仮) を意味する。
命令は以下のいずれかである:
+o ホワイトスペース (スペース、タブ、改行など; isspace(3) 参照)
の列。
この命令は、入力中の任意の個数のホワイトスペースに一致する。
(「何もなし」にも一致する)。
+o 通常文字 (つまり、ホワイトスペースと '%' 以外の文字)。
この文字は入力の次の文字に正確に一致しなければならない。
+o 変換指定。変換指定は '%' (パーセント) 文字で始まる。
入力された文字の系列はこの指定にもとづいて変換され、
変換結果は対応する pointer 引た瑤指す場所に格納される。
入力の次の文字が変換指定と一致しない場合は、変換は失敗する --
これが (matching failure) である。
format 中の各々の は文字 '%' か文字系列 "%n$"
(違いについては後述) で始まり、以下の要素が続く。
+o 代入抑制文字 '*' (省略可能)。 scanf()
は変換指定に指示された通り入力を読み込むが、その入力は捨てられる。
対応する pointer 引た瑤鷲要なく、 scanf()
が返す代入が成功した数にこの指定は含まれない。
+o 文字 'a'
(省略可能)。これは文字列変換とともに使用され、これを使うと
呼び出し元が入力を保持する対応するバッファを確保する必要がなくなる。
代わりに scanf() が必要な大-
さのバッファを確保し、このバッファのアドレスを 対応する pointer
引た瑤紡綟する。 pointer 引た瑤 char *
型の変数へのポインタでなければならない
(変数自体は呼び出し前に初期化されている必要はない)。
呼び出し元は、不要になった時点で、このバッファを free(3) すべ-
である。この機能は GNU による拡張である。 C99 は 'a'
文字を変換指定として使用している (こちらも GNU
の実装と同じように使用することがでい)。
+o を指定する 10進数 (省略可能)。
この最大値に達するか、一致しない文字が見つかるか、のどちらかに
なると、文字の読み込みを停止する。
ほとんどの変換では、先頭のホワイトスペース文字は捨てられ
(例外については後述する)、
捨てられたこれらの文字は最大フィールド幅の計算には含まれない。
文字列の入力変換では、入力の末尾を示すヌル終端文字 ('\0')
も格納されるが、最大フィールド幅にはこの終端文字は含まれない。
+o (type modifier characters) (省略可能)。
例えば、型修飾子 l を %d などの整数変換と一緒に使うと、対応する
pointer 引た瑤 int ではなく long int
を参照していることを指定でい襦
+o : 実行すべて力変換の種類を指定する。
format 中の変換指定は、'%' で始まるか、 "%n$"
で始まるかの、いずれかの形式である。 これら 2つの形式を同じ format
文字列に混ぜることはでい覆ぁＣ△掘"%n$" を 含む文字列に %% と %*
を含めることはでい襦 format に '%' 指定が含まれている場合、各々の '%'
指定と 後続の pointer 引た瑤呂修僚臠崢未蠅紡弍する。 "%n$" 形式
(POSIX.1-2001 では規定されているが、C99 にはない) では、 n は
10進数であり、変換後の入力を format の後ろの n 番目の pointer 引-
数が参照する場所に格納することを指定する。
変儡換
変換指定には、以下の を入れることがでい襦
h 変換が diouxX または n のいずれかであり、次のポインタが (int
ではなく) short int か unsigned short int
へのポインタであることを示す。
hh h と同じだが、次のポインタが signed char か unsigned char
へのポインタであることを示す。
j h と同じだが、次のポインタが intmax_t か uintmax_t
へのポインタであることを示す。 この修飾子は C99 で導入された。
l 変換が diouxX か n のいずれかであり次のポインタが (int ではなく)
long int か unsigned long int
へのポインタであること、または、変換が efg
のうちのひとつであり次のポインタが (float ではなく) double
へのポインタであることのいずれかであることを示す。 l
文字を二つ指定すると、 L と同じ意味となる。 %c や %s
とともに使用すると、
パラメータはそれぞれワイド文字やワイド文字列へのポインタであると
みなされる。
L efg 変換で、次のポインタが long double
へのポインタであることを示す。もしくは、 dioux
変換で、次のポインタが 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 ホワイトスペースではない文字で構成された文字列に対応する。
次のポインタは文字の配列へのポインタでなければならず、
その文字配列は、入力された文字列と (自動的に追加される)
ヌル終端文字 ('\0') を格納するのに十分な大-
さでなければならない。
文字列の入力は、ホワイトスペースが入力されるか、最大フィールド幅に
達するか、のどちらかが起こると停止される。
c (デフォルトは 1)
で指定された幅の文字の列に対応する。 次のポインタは char
へのポインタで、すべての文字を格納するのに十分な領域が
なければならない (終端の NULL バイトは追加されない)。
通常行われる先頭のホワイトスペースの読み飛ばしは行われない。
先頭のホワイトスペースを読み飛ばすためには、
フォーマット文の中で明示的にスペースを使用すれば良い。
[ 格納された文字列のうちから取り出された、
指定された文字の集合で構成される空ではない文字の列に対応する。
次のポインタは char へのポインタでなければならず、
そこには文字列中のすべての文字と終端の NULL バイト
を格納するための十分な領域がなければならない。
通常行われる先頭のホワイトスペースの読み飛ばしは行われない。
この文字列は特別な集合の中の文字で構成されている。 この集合は
開こ膰 [ と閉じ括弧 ] の間の文字で定義される。 開-
括弧のあとの最初の文字が曲アクセント宜 (^)
の場合、集合はこれらの文字を含まないものとなる。
閉じ括弧を集合に含ませるためには、この文字を開こ膰未泙燭
曲アクセント宜罎里△箸虜能蕕諒源にすればよい。
つまり、他の位置に閉じ括弧を置くと文字の集合が終る。 ハイフン -
もまた特殊文字である。
二つの異なる文字の間に置かれた時、この文字は、
その間にある全ての文字を集合に加える。
ハイフン自体を含ませるためには、
括弧が閉じる前の最後の一文字をハイフンにすればよい。 例えば、
[^]0-9-] は「閉じ括弧、0 〜 9、ハイフンの 3
種類を除く全ての文字」の集合を意味する。 この文字列は
集合に含まれていない (曲アクセントの場合には含まれる) 文字の
出現または確保された領域が使い切られた時に終了する。
p (printf(3) の %p で印字されるような) ポインタ値に対応する。
次のポインタは void へのポインタへのポインタでなければならない。
n どんな入力も必要としない。 そのかわりに、
入力からここまで消費された文字数が次のポインタで指定された場所に
格納される。 このポインタは int へのポインタでなければならない。
変換を抑制するのであれば *
代入抑制文字を使って抑制することがでい襪里世、
この変換指定子は変換では「ない」。 C
言語の標準規格では「実行の完了時に返される代入の回数は %n
命令の実行では増加しない」となっているが、
正誤表の内容はこれと矛盾するようである。おそらく、 %n
変換が返り値に与える影響についてはどのような仮定もしないのが -
明であろう。
これらの関数は、一致と代入が成功した入力要素の個数を返す。
返される値は渡された変換の個数よりも少ないこともあり、
最初に一致の失敗があった場合には 0 になることもある。
最初の変換が成功する前に入力の最後に達して、一致の失敗が起こった場合には、
EOF が返される。また、 読み込みエラーが発生した場合にも EOF
が返される。読み込みエラーの場合には、そのストリームの
エラー指示子がセットされ (ferror(3) 参照)、 errno
にエラーを示す値がセットされる。
fscanf(), scanf(), sscanf() 関数は C89 と C99 に準拠している。
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
で定義されていない修飾子を使用した方が良い。 すなわち、 diouxX 変換や
ll と組み合わせる場合には、 L の代わりに q を使用した方が良い。
q の使用方法は 4.4BSD と同じではない。 4.4BSD では q は L
と同等に浮動小数の変換に使用される。
getc(3), printf(3) setlocale(3), strtod(3), strtol(3), strtoul(3),
GNU 2007-07-26 SCANF(3)