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);

説明
scanf 関数グループは、以下に述べるように、 format に従って入力を読み込むものである。 この書式は 変換文字 (conversion specifiers) を含む。この変換の結果は(もしあれば) pointer 引数を通じて保存される。 scanf 関数は標準入力ストリーム stdin からの入力を読み込む。 fscanf はストリームポインタ stream からの入力を読み込む。そして sscanf は文字列ポインタ str で示された文字列からの入力を読み込む。

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

フォーマット文の後に続く pointer 引数は、ひとつひとつが 変換文字と正しく対応しなければならない (例外については以下の `抑止' をみよ)。 すべての変換は % 文字(パーセント記号)によって示される。 format 文字列は、その他の文字も含んで良い。 format 文字列の中の(空白、タブ、改行といった)ホワイトスペースは、 入力の中の(「何もなし」を含む)ゼロ個以上のホワイトスペースに対応している。 他のすべての文字は、それ自身のみに対応する。 読み込みは入力文字がフォーマット文字と合わなくなると中止する。 また、入力変換が成功しなかったときにも中止する(以下の記述を参照すること).

変換
変換を示す % 文字に続いて、以下に示すような、 フラグ 文字がある場合もある。

*   引数への代入を抑止する。 この文字につづく変換は普通に行われるが、ポインタは使用されない。 つまり、変換の結果は単に捨てられるだけである。

a   変換が s であり、文字列のために必要とされるメモリ空間がmalloc関数で 確保され、そのメモリ空間へのポインタは char ポインタ変数へ代入されることを示している。 このポインタ変数は以前に初期化されている必要はない。 このフラグは ANSI C には存在しない。

h   変換が dioux または n のいずれかであり、次のポインタが ( int ではなく) short int へのポインタであることを示している。

l   変換が dioux n のいずれかであり次のポインタが ( int ではなく) long int へのポインタであること、または、変換が efg のうちのひとつであり次のポインタが ( float ではなく) double へのポインタであることのいずれかであることを示している。 ふたつの l フラグを指定することは L フラグと等価である。

L   は、 efg 変換であり次のポインタが long double へのポインタであること、または、 dioux 変換であり次のポインタが long long へのポインタであることのいずれかであることを示している。 (long long が ANSI C の型ではないことに注意しよう。 これを用いたプログラムは全てのアーキテクチャに対して 移植可能ではない。)

q   Lと同一である。 このフラグは ANSI C には存在しない。

これらのフラグに加えて、 % と変換文字の間にオプションでつけることができる、 10進の整数で表わされた最大フィールド幅をおくこともできる。 もし幅が与えられないのなら、(以下で述べる例外を除いて) デフォルト値である`無限大'が使用される。 それ以外の場合、この数字を上限として、多くの文字が 変換の過程で読み込まれる。 変換が始まる前に、ほとんどの変換がスペースやタブを読みとばす。 このときのホワイトスペースはフィールド長に数えられない。

以下の変換が可能である。

%   文字`%'に対応する。 書式文字列の中の `%%' は単一の文字`%'に対応する。 変換は行われず、変数への代入は生じない。

d   符号つきの10進の整数に対応する。 次のポインタは int へのポインタでなければならない。

D   ld と同一である。これは以前の仕様との互換性だけのためにある。

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 と同一である。

s   ホワイトスペースではない文字で構成された文字列に対応する。 次のポインタは char へのポインタでなければならず、 すべての文字および文字列の終りをしめす NUL 文字を格納するために、配列は十分に大きくなければならない。 文字列の入力は、 ホワイトスペースまたは最大フィールド幅(ふたつのうち最初に 生じたもの)によって中止される。

c   width 個の文字の集まり(デフォルトは1)に対応する。 次のポインタは char へのポインタでなければならず、すべての文字を格納するために 十分な領域がなければならない (終端文字 NUL は添付されない)。 通常のホワイトスペースの読み飛ばしは抑制される。 はじめにホワイトスペースを読み飛ばすためには、 フォーマット文の中にあらわにスペースを使用すれば良い。

[   格納された文字列のうちから取り出された、 指定された文字の集合で構成される空ではない文字の列に対応する。 次のポインタは char へのポインタでなければならず、 そこには文字列中のすべての文字と終端文字 NUL を格納するための十分な領域がなければならない。 通常のホワイトスペースの読み飛ばしは抑制される。 この文字列は特別な集合の中の文字で構成されている。 この集合は 開き括弧 [ と閉じ括弧 ] の間の文字で定義される。 開き括弧のあとの最初の文字が曲アクセント記号 ^ の場合、集合はこれらの文字を含まないものとなる。 閉じ括弧を集合に含ませるためには、この文字を開き括弧または 曲アクセント記号のあとの最初の文字にすればよい。 つまり、他の位置に閉じ括弧を置くと文字の集合が終る。 ハイフン - もまた特殊文字である。 二つの異なる文字の間に置かれた時、この文字は、 その間にある全ての文字を集合に加える。 ハイフン自体を含ませるためには、 括弧が閉じる前の最後の一文字をハイフンにすればよい。 例えば `[^]0-9-]' は `閉じ括弧、ゼロから９そしてハイフンの３種類を除く全ての文字' という組合せを意味する。 この文字列は 集合に含まれていない(曲アクセントの場合には含まれる)文字の 出現または確保された領域が使われ尽くされた時に終了する。

p   ( printf(3) で `%p' で記されるような)ポインタ値に対応する。 次のポインタは void へのポインタでなければならない。

n   引数を必要としない。 そのかわりに、 入力からここまで消費された文字数が次のポインタを通じて 格納される。 このポインタは int へのポインタでなければならない。 * フラグをもちいて抑制することができるにもかかわらず、これは変換では ない。 C 言語の標準規格は `実行の完了時に返される代入の回数を %n 命令の実行は増加させない' と 言っているが、正誤表ではこれを否定するようである。 おそらく、返り値の %n 変換の効果についてはどのような仮定もしない ことが賢明であろう。

返り値
これらの関数は代入された入力要素の個数を返す。 代入が失敗した場合、この個数は用意されたよりも少なくも ゼロにもなり得る。 ゼロは 入力が可能である間に、どんな変換値も代入されなかったことを示している。 典型的な例としては、 `%d' 変換時にアルファベット文字が入力されたというような 入力文字が不適切であったことが挙げられる。 最初の変換の前にファイルの終端文字( end-of-file )があって、 入力の失敗が生じた場合には EOF が返される。 エラーやファイルの終端文字の出現が変換が始まった後で生じた場合には、 成功した変換の個数が返される。

関連項目
strtol(3), strtoul(3), strtod(3), getc(3), printf(3)

準拠
fscanf, scanf, そして sscanf 関数は ANSI C3.159-1989 (``ANSI C'') に準拠している。

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

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

バグ
全ての関数は、完全に ANSI C3.159-1989 に準拠している。しかし 追加の q と a フラグが提供されており、同様に L と l フラグの付加的な振る舞いもある。後者は、 ANSI C3.159-1989 で定義されたフラグの振る舞いを変更するものなので、 バグとみなされるかもしれない。

ANSI C で定義されたフラグの幾つかのフラグの組合せは、 ANSI C では意味をなさないものがある (例えば、 %Ld)。 Linux 上では定義された振る舞いを持つであろうが、 この振る舞いは他のアーキテクチャーで同様になっている必要はない。 それゆえに、ほとんどの場合、 ANSI C で定義されていないフラグを使用した方が良い。 すなわち、 diouxX 変換や ll では、 L の代わりに q を使用した方が良い。

q の使用方法は L と同一である実数の変換に使用される BSD 4.4 の場合と同じではない。