SCANF

名前

書式

#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  

説明

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() が返す代入が成功した数にこの指定は含まれない。

*

文字 'a' (省略可能)。これは文字列変換とともに使用され、これを使うと 呼び出し元が入力を保持する対応するバッファを確保する必要がなくなる。 代わりに scanf() が必要な大きさのバッファを確保し、このバッファのアドレスを 対応する pointer 引き数に代入する。 pointer 引き数は char * 型の変数へのポインタでなければならない (変数自体は呼び出し前に初期化されている必要はない)。 呼び出し元は、不要になった時点で、このバッファを free(3) すべきである。この機能は GNU による拡張である。 C99 は 'a' 文字を変換指定として使用している (こちらも GNU の実装と同じように使用することができる)。

*

「最大フィールド幅」 を指定する 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 引き数が参照する場所に格納することを指定する。  

変換

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 変換が返り値に与える影響についてはどのような仮定もしないのが 賢明であろう。

返り値

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

準拠

q 指定子は long long の 4.4BSD での記述方法である。 一方、整数変換での ll または L の使用は GNU での拡張である。

これらの関数の Linux 版は GNU libio ライブラリーを元にしている。 より簡潔な説明には GNU libc (glibc-1.08) の info 文書に目を通すこと。  

バグ

ANSI C で定義された型修飾子と変換指定子の組み合わせの中には 意味をなさないものがある (例えば、 %Ld)。 これらが指定された場合、 Linux 上でははっきりと定義された振る舞いをするかもしれないが、 他のアーキテクチャでも同様になっているとは限らない。 それゆえに、ほとんどの場合、 ANSI C で定義されていない修飾子を使用した方が良い。 すなわち、 diouxX 変換や ll と組み合わせる場合には、 L の代わりに q を使用した方が良い。

q の使用方法は 4.4BSD と同じではない。 4.4BSD では q は L と同等に浮動小数の変換に使用される。  

関連項目

Index

名前

書式

説明

変換

返り値

準拠

バグ

関連項目