SunOS リファレンスマニュアル 3 : 基本ライブラリ関数

vscanf(3C)

名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 使用例 | 属性 | 関連項目

名前

scanf, fscanf, sscanf, vscanf, vfscanf, vsscanf– 書式付き入力の変換

形式

#include <stdio.h>

format

stream

format

s

format

#include <stdarg.h>
#include <stdio.h>

format

arg

stream

format

arg

s

format

arg

機能説明

scanf() 関数は、標準入力ストリーム stdin を読み取ります。

fscanf() 関数は、入力ストリーム stream を読み取ります。

sscanf() 関数は、文字列 s を読み取ります。

vscanf()、vfscanf()、および vsscanf() 関数はそれぞれ、scanf()、fscanf()、および sscanf() と同等ですが、これらの関数を呼び出すときは、可変数個の引数ではなく、<stdarg.h> ヘッダーで定義されている引数リストを使用します。これらの関数は va_end() マクロを呼び出しません。そのため、アプリケーションは、これらの関数を使用した後、va_end(ap) を呼び出してクリーンアップ作業を行う必要があります。

これらの関数は、それぞれ、バイトを読み取り、書式にしたがってそれを解釈し、その結果を引数に格納します。これらの関数には、引数として、制御文字列 format (以下で説明)、および変換された入力の格納場所を示す pointer 群を指定します。書式に対して十分な引数が指定されていない場合、変換の結果は未定義となります。書式が終了しても引数が残っている場合、残りの引数は評価されますが、評価されたとしても無視されます。

変換は、次の未使用の引数にではなく、引数リストの format のあとに続く n 番目の引数に適用されます。この場合、変換文字 % (後述を参照) は %n$ シーケンスに置換されます。ここで n は [1, NL_ARGMAX] の範囲の 10 進数の整数です。この変換機能は、特定の言語に合わせた順序で引数を選択するように、書式文字列の定義を規定します。書式文字列に変換指定の書式 %n$ が含まれる場合、引数リスト中の番号付けされた引数が、複数回、書式文字列から参照されるかどうかについては不定です。

format には、変換指定の形式、つまり % または %n$ のいずれかを含むことができます。ただし、通常は 1 つの format 文字列に % と %n$ の両方を指定することはできません。唯一の例外として、%% または %* を %n$ の形式に入れることがあります。

scanf() 関数のすべての形式において、入力文字列中の言語依存の小数点文字を検出できます。小数点文字は、プログラムのロケール (LC_NUMERIC カテゴリ) によって定義されます。POSIX ロケールおよび小数点文字が定義されていないロケールでは、小数点文字のデフォルトはピリオド (.) です。

format とは、初期シフトの状態で始まるかまたは終わる文字列で、0 個以上の指示語 (もしあれば) で構成されます。各指示語は次のいずれか 1 つで構成されます。

1 つまたは複数の空白文字 (スペース、タブ、改行文字、垂直タブ、または用紙送り (form-feed) 文字)
通常文字 (% または空白文字は含まない)
変換指定

変換指定

各変換指定は % 文字、または %n$ 文字シーケンスによって導入されます。これらの文字の後には、以下に示す (順番で) 文字列が続きます。

代入抑制文字 * (任意)
最大フィールド幅を指定する 0 以外の 10 進数 (任意)
長さ修飾子 (任意)。受け取るオブジェクトのサイズを指定します。
適用される変換形式を指定する変換指定文字 (有効な変換指定文字については、後述の説明を参照してください)。

scanf() 関数は、形式の各指示を順番に実行します。指示にエラーがあった場合、以下に詳しく記述しているように、関数はエラーを返します。エラーは、入力エラー (入力バイトが無効) またはマッチングエラー (入力が不適当) として記述されます。

1 つまたは複数の空白文字で構成される指示は、有効な入力が読み取られなくなるまで、あるいは空白文字でないために読み取れずに残る最初のバイトまで、入力を読み取って実行します。

通常文字の指示は次のように実行されます。次のバイトが入力から読み取られ、指示を含むバイトと比較されます。比較の結果、両者が同じでない場合、指示はエラーで終了し、違いのあった後続のバイトが読み取れずに残ります。

変換指定を表す指示は、一連のマッチング入力シーケンスを定義します (各変換文字については以下に記述)。変換指定は次の手順で実行されます。

変換指定に変換文字 [、c、C、または n が含まれる場合を除いて、空白文字の入力 (isspace(3C) で指定) はスキップされます。

変換指定に変換文字 n が含まれる場合を除いて、項目は入力から読み取られます。入力項目の長さは、指定した最大フィールド幅によって制限されます。同時に、入力項目の長さの単位は、指定した変換文字によって文字またはバイト数のどちらかに解釈されます。scanf() は、入力項目の終わりを判断するために、余分な文字を読み取る必要がある場合があります。デフォルトの Solaris モードでは、入力項目は「マッチングシーケンスの一部である入力バイトの最長のシーケンス」であると定義されているため、scanf() は、複数の文字を読み取る必要があります。C99/SUS v3 モードでは、入力項目は「マッチングシーケンスと同じ (あるいは、その前半部分) である入力バイトの最長のシーケンス」であると定義されているため、scanf() は、多くても 1 文字を読み取るだけでかまいません。したがって、C99/SUSv3 モードでは、strtod(3C) や strtol(3C) などの関数には受け入れられるシーケンスが scanf() では受け入れられない場合があります。どちらのモードでも、scanf() は、ungetc(3C) を使用して、超過バイトの読み取りをプッシュバックしようとします。このような試みがすべて成功したと想定した場合、入力項目の後に続く最初のバイト (もしあれば) は、読み取られずに残ります。入力項目の長さが 0 の場合、変換は失敗します。この状態はマッチングエラーです。ただし、ファイルの終わり、コード化エラー、または、読み取りエラーによって、ストリームからの入力が妨害された場合は入力エラーです。

変換文字が % ではない場合の入力項目 (あるいは変換指定が %n の場合の入力バイト数) は、変換文字に適当な形式に変換されます。入力項目がマッチングシーケンスではない場合、変換指定はエラーで終了します。この状態はマッチングエラーです。代入抑制文字が * で表された場合を除いて、変換の結果は、以前に変換結果を受け取っていない format 引数に続く最初の引数によって、ポイントされたオブジェクトに出力されます (変換指定が % によって呼び出されていない場合)。変換指定が文字シーケンス %n$ によって呼び出された場合は、n 番目の引数に出力されます。このオブジェクトが適当な形式ではない場合、または変換の結果が提供された空間に対応できない場合、動作結果は未定義です。

長さ修飾子

次に、長さ修飾子とその意味を示します。

hh: 後続の変換文字 d、i、o、u、x、X または n が signed char あるいは unsigned char へのポインタ型を持つ引数に適用されることを指定します。
h: 後続の変換文字 d、i、o、u、x、X、または n が short あるいは unsigned short へのポインタ型を持つ引数に適用されることを指定します。
l (小文字のエル): 後続の変換文字 d、i、o、u、x、X、または n が long あるいは unsigned long へのポインタ型を持つ引数に適用されることを指定します。あるいは、後続の変換文字 a、A、e、E、f、F、g、または G が double へのポインタ型を持つ引数に適用されることを指定します。あるいは、後続の変換文字 c、s、または [ が wchar_t へのポインタ型を持つ引数に適用されることを指定します。
ll (小文字のエルと小文字のエル): 後続の変換文字 d、i、o、u、x、X、または n が long long あるいは unsigned long long へのポインタ型を持つ引数に適用されることを指定します。
j: 後続の変換文字 d、i、o、u、x、X、または n が intmax_t あるいは uintmax_t へのポインタ型を持つ引数に適用されることを指定します。
z: 後続の変換文字 d、i、o、u、x、X、または n が size_t あるいは対応する符号付き整数型へのポインタ型を持つ引数に適用されることを指定します。
t: 後続の変換文字 d、i、o、u、x、X、または n が ptrdiff_t あるいは対応する unsigned 型へのポインタ型を持つ引数に適用されることを指定します。
L: 後続の変換文字 a、A、e、E、f、F、g、または G が long double へのポインタ型を持つ引数に適用されることを指定します。

長さ修飾子を上記以外の変換文字と一緒に指定した場合、その動作は未定義です。

変換文字

以下に、有効な変換文字を示します。

d

10 進数の整数 (符号は任意) と一致します。書式は、strtol(3C) の base 引数に値 10 を指定したときの変換対象となる文字コードの並びと同じものである必要があります。サイズ修飾子を指定しない場合、対応する引数は、int へのポインタである必要があります。

i

整数 (符号は任意) と一致します。書式は、strtol() の base 引数に値 0 を指定したときの変換対象となる文字コードの並びと同じものである必要があります。サイズ修飾子を指定しない場合、対応する引数は、int へのポインタである必要があります。

o

8 進数の整数 (符号は任意) と一致します。書式は、strtoul(3C) の base 引数に値 8 を指定したときの変換対象となる文字コードの並びと同じものである必要があります。サイズ修飾子を指定しない場合、対応する引数は、unsigned int へのポインタである必要があります。

u

10 進数の整数 (符号は任意) と一致します。書式は、strtoul(3C) の base 引数に値 10 を指定したときの変換対象となる文字コードの並びと同じものである必要があります。サイズ修飾子を指定しない場合、対応する引数は、unsigned int へのポインタである必要があります。

x

16 進数の整数 (符号は任意) と一致します。書式は、strtoul(3C) の base 引数に値 16 を指定したときの変換対象となる文字コードの並びと同じものである必要があります。サイズ修飾子を指定しない場合、対応する引数は、unsigned int へのポインタである必要があります。

a,e,f,g

符号付き浮動小数点数、無限、または NaN に一致します。書式は strtod(3C) の変換対象となる文字コードの並びと同じです。サイズ修飾子を指定しない場合、対応する引数は float へのポインタである必要があります。変換文字 e、f、および g は、C99/SUSv3 モード (standards(5) を参照) の場合だけ、16 進数の浮動小数点値に一致します。しかし、変換文字 a は常に、16 進数の浮動小数点値に一致します。

これらの変換文字は、strtod(3C) が受け入れる変換対象シーケンス (INF、INFINITY、NAN、および NAN (n-char-sequence) の形式を含む) にマッチングします。変換の結果は、マッチングシーケンスとともに strtod() (あるいは、strtof() または strtold()) を呼び出したときと同じで、浮動小数点の例外が発生して、(可能であれば)、errno に ERANGE が設定されます。

s

空白でないバイトシーケンスに一致します。対応する引数は、その文字シーケンスおよびその最後に自動的に追加される NULL 文字コードを十分格納できるだけの大きさの char, signed char, または unsigned char の並びの最初のバイトへのポインタである必要があります。

l (小文字のエル) 修飾子が与えられた場合、入力は初期シフト状態で始まる文字シーケンスです。それぞれの文字は、mbrtowc(3C) 関数への呼び出しと同じようにワイド文字に変換され、変換状態は、最初の文字が変換される前に 0 に初期化された mbstate_t オブジェクトによって記述されます。対応する引数は、その文字シーケンスおよびその最後に自動的に追加される NULL 文字コードを十分格納できるだけの大きさの wchar_t の配列へのポインタである必要があります。

[

複数の文字 (scanset という) からなる、空でない文字シーケンスと一致します。この場合、通常行われる先行する空白のスキップは抑制されます。対応する引数は、その文字シーケンスおよびその最後に自動的に追加される NULL バイトを十分格納できるだけの大きさの char、signed char、または unsigned char の並びの最初のバイトへのポインタである必要があります。

l (小文字のエル) 修飾子が与えられた場合、入力は初期シフト状態で始まる文字シーケンスです。その並びにあるそれぞれの文字は、mbrtowc() 関数への呼び出しと同じようにワイド文字に変換され、変換状態は、最初の文字が変換される前に 0 に初期化された mbstate_t オブジェクトによって記述されます。対応する引数は、その文字シーケンスおよびその最後に自動的に追加される NULL 文字コードを十分格納できるだけの大きさの wchar_t の配列へのポインタである必要があります。

変換指定は、format 文字列のすべての後続の文字、つまり、対応する右角括弧 (]) まで (または、その括弧も含む) が入ります。括弧内の文字 (scanlist) は scanset を構成しています。左角括弧の次の文字がサーカンフレックス (‸) の場合は、サーカンフレックスと右角括弧の間 scanlist に入っていないすべての文字が scanset を構成しています。変換指定が [ ] または [‸] で始まる場合は、この右角括弧は scanlist 内に含まれており、次の右角括弧が指定の終了を示す右角括弧になります。scanlist に – があり、その – が最初の文字ではない場合、最初の文字が ‸ で – が 2 番目の文字ではない場合、あるいは – が最後の文字ではない場合、一致する文字の範囲が表示されます。

c

フィールド幅に指定された数 (フィールド幅が変換指定にない場合は 1) の文字シーケンスと一致します。対応する引数は、その文字シーケンスを十分格納できるだけの大きさの char, signed char, または unsigned char の並びの最初のバイトへのポインタである必要があります。NULL 文字は追加されません。この場合、通常行われる先行する空白のスキップは抑制されます。

p

対応する printf(3C) 関数の %p 変換によって出力されるシーケンスと同様のシーケンスと一致します。対応する引数は void へのポインタである必要があります。入力項目が、同一プログラムの実行中で以前に変換した値である場合は、ポインタは先にその値を変換したときと同様の比較を行います。そうでない場合は、%p 変換の動作は未定義です。

n

入力は使用 (変換) されません。対応する引数は、これまでに scanf() 関数を呼び出して入力ストリームから読み取ったバイト数を示す整数へのポインタである必要があります。変換指定 %n を実行しても、この関数の実行終了時に返される代入数は増加しません。

C

lc と同じです。

S

ls と同じです。

%

単一の % と一致します。変換または代入は行われません。完全な変換指定をするには %% を指定してください。

変換指定が正しくない場合の動作は未定義です。

変換文字 A、E、F、G、および X はそれぞれ a、e、f、g、および x と同じ働きをします。

入力中にファイルの終端になると、変換は終了します。現在の変換指定 (%n を除く) に一致するバイト (先行空白を使用している場合はこれを除く) が読み取られる前にファイルが終わると、現在の変換指定の実行は入力エラーで終了します。それ以外の場合は、現在の変換指定の実行がマッチングエラーで終了しない限り、続く変換指定の実行 (もし、あれば) が入力エラーで終了します。

sscanf() の文字列の終端に到達するのは、fscanf() でファイルの終端に到達するのと同等です。

入力が衝突して終了した場合、対抗する入力は入力中で読み取られないままになります。変換指定に一致しない場合、後続の空白 (改行文字を含む) は読み取られません。リテラル一致および抑制される代入が成功したかどうかは、%n 変換指定によってのみ直接確認できます。

fscanf() および scanf() 関数は、stream に関連するファイルの st_atime フィールドを更新用にマークすることができます。st_atime フィールドは、fgetc(3C), fgets(3C), fread(3C), fscanf( ), getc(3C), getchar(3C), gets(3C), または scanf() の実行が成功したときに、ungetc(3C) への以前の呼び出しによって与えられていないデータを返す stream を使用して更新用にマークされます。

戻り値

正常終了の場合、これらの関数は一致と代入が成功した入力項目数を返します。一致が実行初期段階で失敗した場合は、 0 が返される場合もあります。最初の一致が失敗する前、または最初の変換が行われる前に入力が終わると、EOF が返されます。ストリームが設定されているというエラー表示で読み取りエラーが発生した場合、EOF が返されエラーを表示する errno が設定されます。

エラー

scanf() 関数が失敗、および失敗する可能性がある場合は、fgetc(3C) または fgetwc(3C) を参照してください。

さらに、以下の条件で fscanf() は失敗することがあります。

EILSEQ: 入力バイトシーケンスが有効な文字を形成していない。
EINVAL: 引数が不足している。

使用法

scanf() 関数を呼び出すアプリケーションに wint_t または wchar_t 型の形式のオブジェクトが存在する場合、これらのオブジェクトを定義する <wchar.h> ヘッダーも含む必要があります。

使用例

例 1 呼び出し

int i, n; float x; char name[50];
n = scanf("%d%f%s", &i, &x, name)

という呼び出しの場合、入力行は次のようになります。

25 54.32E–1 Hamster

この場合、n に値 3、i に値 25、x に値 5.432 がそれぞれ代入され、name には Hamster の文字列が入ります。

例 2 呼び出し

int i; float x; char name[50];
(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);

という呼び出しの場合、入力行は次のようになります。

56789 0123 56a72

この場合、i に 56、x に 789.0 が代入され、0123 はスキップして、name には 56\0 が入ります。getchar(3C) への次の呼び出しでは a の文字を返します。

属性

次の属性については attributes(5) のマニュアルページを参照してください。

属性タイプ	属性値
MT レベル	MT-Safe
CSI	対応済み
インタフェースの安定性	標準