SCANF(3) Linux Programmer's Manual SCANF(3)
名前
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - 書式付き
入力変換
書式
#include
int scanf(const char *format, ...);
int fscanf(FILE *stream, const char *format, ...);
int sscanf(const char *str, const char *format, ...);
#include
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);
説明
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) のいずれかで
ある。入力の失敗は入力文字が使用できなかったことを意味し、
一致の失敗は入力が不適切であったこと (下記参照) を意 味 す
る。
命令は以下のいずれかである:
o ホ ワ イ トスペース (スペース、タブ、改行など; iss-
pace(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 1995-11-01 SCANF(3)