sscanf(3)

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf − 入力のフォーマット変換

標準 C ライブラリ (libc, −lc)

#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 に従って入力を走査します。この フォーマットには 変換指示子を含めることができます。このような変換がある 時、その結果は ポインタ引数を介して格納されます。 scanf() 関数は入力を標 準入力ストリーム stdin から読み取ります。 fscanf() は入力をストリームポイ ンタ stream から読み取ります。 sscanf() は入力を str の指すキャラクタ文字 列から読み取ります。 vfscanf() 関数は、 vfprintf(3) に類似しており、ポイ ンタの可変引数リスト ( stdarg(3) を参照) を使用して、ストリームポインタ stream から入力を読み取ります。 vscanf() 関数は標準入力から、 vsscanf() 関数は文字列から可変引数リストを走査します。これらの関数はそれぞれ vprintf() 関数と vsprintf() 関数に類似しています。連続した各 ポインタ引数 は、連続したそれぞれの変換指示子と適切に対応している必要があります (ただ し、後述の ‘抑制’ を参照)。変換指示子はすべて % 文字 (パーセント符号) で 始まります。 format 文字列には、他の文字も含めることができます。 format 文字列内の空白 (ブランクやタブ、改行など) は、空白なしを含む任意の量の空 白と一致します。その他の文字はすべてそれ自身とだけ一致します。入力文字が そのようなフォーマット文字と一致しなくなったときに走査は停止します。走査 は、入力変換が行えないときにも停止します (下記参照)。

変換の先頭となる % 文字に続いて、以下にあげるいくつかの フラグ文字をおく ことができます。

割り当ての抑制。これに続く変換は普段通りに行われますが、ポインタ は使用されません。変換の結果は単に廃棄されます。

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

l
変換が dioux または n のどれかであり、次のポインタが ( int ではな く) long int を指すポインタであること、あるいは変換は efg のどれ かであり、次のポインタは ( float ではなく) double を指すポインタ であることを示します。

L
変換が efg であり、次のポインタが long double を指すポインタであ ることを示します (このタイプは実装されていません。 L フラグは現時 点では無視されます)。

q
変換が dioux または n のどれかであり、次のポインタが ( int ではな く) long long int を指すポインタであることを示します。

これらのフラグに加えて、オプションとして 10 進整数で表される最大フィール ド幅を % と変換の間に置くことも可能です。フィールド幅を指定しない場合、デ フォルトの ‘無限’ が使用されます (例外が 1 つあります。後述)。フィールド 幅を指定した場合、変換処理において最大でその数の文字が走査されます。変換 が始まる前に、ほとんどの変換は空白をスキップします。この空白はフィールド 幅のカウント対象にはなりません。

以下の変換を利用できます。

%
リテラルの ‘%’ と一致します。すなわち、フォーマット文字列内の ‘%%’ は、 1 つの入力文字 ‘%’ と一致します。変換は行われず、割当ては行わ れません。

d
符号の有無に関わらず、10 進整数に一致します。次のポインタは int を 指すポインタである必要があります。

D
ld と同等です。これは後方互換性のためにだけ存在しています。

i
符号の有無に関わらず、整数に一致します。次のポインタは int を指すポ インタである必要があります。整数が ‘0x’ または ‘0X’ で始まる場合、 整数を基数 16 で読み取ります。 ‘0’ で始まる場合、基数 8 で読み取り ます。それ以外の場合は、基数 10 です。基数に対応する文字だけが使用 されます。

o
8 進整数と一致します。次のポインタは unsigned int を指すポインタで ある必要があります。

O
lo と同等です。これは後方互換性のために存在しています。

u
符号の有無に関わらず、10 進整数と一致します。次のポインタは unsigned int を指すポインタである必要があります。

x
符号の有無に関わらず、16 進整数に一致します。次のポインタは unsigned int を指すポインタである必要があります。

X
lx と同等です。これは ISO/IEC 9899:1990 (‘‘ISO C89’’) 違反ですが、 以前の UNIX システムとは後方互換性があります。

f
符号の有無に関わらず、浮動小数点数と一致します。次のポインタは float を指すポインタである必要があります。

e
f と同等です。

g
f と同等です。

E
lf と同等です。これは ISO/IEC 9899:1990 (‘‘ISO C89’’) 違反ですが、 以前の UNIX システムとは後方互換性があります。

F
lf と同等です。これは後方互換性のためにだけ存在します。

s
非空白文字のシーケンスと一致します。次のポインタは char を指すポイ ンタである必要があり、配列はすべてのシーケンスと終端の NUL 文字を受 け入れるのに十分なだけ大きい必要があります。入力文字列は、空白、ま たは最大フィールド幅のどちらかが最初に発生した場所で停止します。

c
width 個 (デフォルト 1) の文字のシーケンスに一致します。次のポイン タは char を指すポインタである必要があり、すべての文字に対して十分 な余地がある必要があります (終端の NUL は追加されません)。通常行わ れる先頭の空白スキップは抑制されます。最初の空白をスキップするに は、フォーマット内に明示的なスペースを使用してください。

[
指定された受け入れ文字集合からなる、空でない文字列と一致します。次 のポインタは、 char を指すポインタである必要があり、文字列内のすべ ての文字に加えて終端の NUL 文字を入れる十分な余地がある必要がありま す。通常行われる先頭の空白スキップは抑制されます。文字列は、特定の 集合内の (または集合外の) 文字で構成されます。この集合は、開き角括 弧 [ 文字と閉じ角括弧 ] 文字の間の文字によって定義されます。集合 は、開き角括弧の直後の文字が曲折アクセント記号 ^ である場合、これら の文字を 除外します。集合内に閉じ角括弧を入れるには、閉じ角括弧を開 き角括弧または曲折アクセント記号の直後の文字にします。その他の位置 に置くと集合を終了させます。ハイフン文字 - も特殊です。他の 2 つの 文字間に置かれた場合、ハイフンは間に入るすべての文字を集合に追加し ます。ハイフンを入れるためには、ハイフンを最後の閉じ角括弧の直前の 文字にします。たとえば、 ‘[^]0-9-]’ は、‘閉じ角括弧、0 から 9、およ びハイフン以外のすべて’ の集合を意味します。文字列は、集合内にない (または曲折アクセント記号がある集合に含まれる) 文字が出現するか、ま たはフィールド幅が尽きた時に終了します。

p
( printf(3) で ‘%p’ で印字された) ポインタの値と一致します。次のポ インタは void を指すポインタである必要があります。

n
何も予期しません。その代わり、入力以降消費された文字の個数が次のポ インタを介して保存されます。次のポインタは int を指すポインタである 必要があります。これは変換では ありません。ただし * フラグで抑制で きます。

後方互換性のために、他の変換文字 ( ‘\0’ を除く) は ‘%d’ であるかのよう に、または大文字の場合は ‘%ld’ であるかのように扱われ、 ‘%\0’ の変換はた だちに EOF を戻します。 F と X の変換は、将来 ANSI C 標準に適合するように 変更される予定なので、その後では、これらの変換はそれぞれ f と x のように 動作するでしょう。

戻り値

これらの関数は、割り当てられた入力項目数を返します。一致が成功しなかった 場合、この数は準備されたものよりも少なく、または 0 になることさえありま す。 0 は、利用できる入力があったものの、変換が割り当てられなかったことを 示します。通常、これは ‘%d’ 変換に対するアルファベット文字等のような、無 効な入力文字のためです。なんらかの変換が発生する前に、ファイルの終りのよ うなことで入力処理が失敗した場合は、値 EOF が返されます。変換が開始した後 で、エラーまたはファイルの終りが発生した場合、正常に完了した変換の数が返 されます。

getc(3), printf(3), strtod(3), strtol(3), strtoul(3)

関数 fscanf(), scanf() および sscanf() は ISO/IEC 9899:1990 (‘‘ISO C89’’) に適合しています。

関数 vscanf(), vsscanf() および vfscanf() はこのリリースではじめて登場し ました。

変換 %F と %X の現在の状況は不都合な状態にあります。

すべての後方互換フォーマットは、将来取り除かれます。

数値文字列は 512 文字に切り捨てられます。たとえば、 %f と %d は事実上 %512f と %512d です。

FreeBSD 10.0 December 11, 1993 FreeBSD 10.0