Namespaces
Variants

    vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

    ja.cppreference.net より
    < c | io
     
    C
     
    ファイル入出力
    型とオブジェクト
            
    関数
    ファイルアクセス
    (C11)
    (C11)  
    (C95)
    書式なし入出力
    (C95)(C95)
    (C95)
    (C95)(C95)
    (C95)
    (C95)
    (C95)
    (C95)

    書式付き入力
    (C99)(C99)(C99)(C11)(C11)(C11)
    (C99)(C99)(C99)(C11)(C11)(C11)  
     
    ヘッダ <stdio.h> 
    int vscanf( const char* restrict format, va_list vlist );
    		で定義 (1) (C99 以降) 
    int vfscanf( FILE* restrict stream, const char* restrict format,
             va_list vlist );
    		(2) (C99 以降) 
    int vsscanf( const char* restrict buffer, const char* restrict format,
             va_list vlist );
    		(3) (C99 以降) 
    int vscanf_s(const char* restrict format, va_list vlist);
    		(4) (C11 以降) 
    int vfscanf_s( FILE* restrict stream, const char* restrict format,
               va_list vlist);
    		(5) (C11 以降) 
    int vsscanf_s( const char* restrict buffer, const char* restrict format,
               va_list vlist);
    		(6) (C11 以降)

    さまざまなソースからデータを読み取り、formatに従って解釈し、結果をvlistで指定された場所に格納します。

    1) stdin
    からデータを読み取ります。2) ファイルストリーム stream
    からデータを読み取ります。3) ヌル終端文字列 buffer からデータを読み取ります。文字列の終わりに達することは、fscanf
    のファイル終端条件に達することと同等です。4-6) (1-3) と同じですが、%c、%s、%[ 変換指定子はそれぞれ 2 つの引数（通常のポインタと、受け取り配列のサイズを示す rsize_t 型の値。%c で単一の char に読み込む場合は 1 になり得る）を期待する点、および以下のエラーが実行時に検出され、現在インストールされている 制約ハンドラ 関数を呼び出す点が異なります。
    • ポインタ型の引数のいずれかがヌルポインタである。
    • format、stream、または buffer がヌルポインタである。
    • %c、%s、または %[ によって書き込まれる文字数に終端ヌル文字を加えたものが、それらの変換指定子それぞれに指定された 2 番目 (rsize_t) の引数を超える。
    • オプションで、その他検出可能なエラー（未知の変換指定子など）。
    他のすべての境界チェック付き関数と同様、vscanf_s、vfscanf_s、vsscanf_s は、実装によって __STDC_LIB_EXT1__ が定義され、ユーザーが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義してから <stdio.h> をインクルードした場合にのみ、使用が保証されます。

    引数

    stream - 読み取り元の入力ファイルストリーム
    buffer - 読み取り元のヌル終端文字列へのポインタ
    format - 入力の読み取り方法を指定するヌル終端文字列へのポインタ
    vlist - 受け取り引数を含む可変引数リスト。


    format 文字列は以下で構成されます。

    • 空白以外のマルチバイト文字（% を除く）：書式文字列内のそのような各文字は、入力ストリームからまったく同じ 1 文字を消費するか、ストリーム上の次の文字が等しくない場合に関数を失敗させます。
    • 空白文字：書式文字列内の単一の空白文字は、入力から利用可能な連続した空白文字をすべて消費します（isspace をループで呼び出すのと同様に判定されます）。書式文字列内の "\n"、" "、"\t\t"、その他の空白文字に違いはないことに注意してください。
    • 変換指定子。各変換指定子は以下の形式を持ちます。
    • 導入の % 文字
    • (オプション) 代入抑止文字 *。このオプションが存在する場合、関数は変換結果をいかなる受け取り引数にも代入しません。
    • (オプション) 最大フィールド幅 を指定する整数（0 より大きい値）。つまり、現在の変換指定子で指定された変換を行う際に関数が消費してもよい最大文字数です。%s と %[ は、幅が指定されていない場合にバッファオーバーフローを引き起こす可能性があることに注意してください。
    • (オプション) 長さ修飾子。受け取り引数のサイズ、つまり実際の宛先の型を指定します。これは変換精度とオーバーフロールールに影響します。デフォルトの宛先型は変換の種類ごとに異なります（以下の表を参照）。
    • 変換書式指定子。

    以下の書式指定子が利用可能です。

    変換
    指定子     		説明 期待される
    引数の型
    長さ修飾子→ hh h なし l ll j z t L
    C99 以降のみ利用可能→ はい はい はい はい はい
    %
    リテラル % に一致します。
    		 N/A N/A N/A N/A N/A N/A N/A N/A N/A
    c

    文字 または 文字 のシーケンスに一致します。

    • 幅指定子が使用された場合、正確に width 文字に一致します（引数は十分な領域を持つ配列へのポインタでなければなりません）。
    • %s や %[ とは異なり、配列にヌル文字を追加しません。
    		 N/A N/A
    char*
    wchar_t*
    		 N/A N/A N/A N/A N/A
    s

    空白以外の文字のシーケンス（文字列）に一致します。

    • 幅指定子が使用された場合、最大 width まで、または最初の空白文字までのいずれか早い方に一致します。
    • 一致した文字に加えて常にヌル文字を格納します（そのため引数配列には少なくとも width+1 文字分の領域が必要です）。
    [set ]

    set の文字集合からの空でない文字シーケンスに一致します。

    • 集合の最初の文字が ^ の場合、集合に含まれないすべての文字が一致します。
    • 集合が ] または ^] で始まる場合、] 文字も集合に含まれます。
    • スキャンセット内の先頭以外の位置にある文字 - が、[0-9] のように範囲を示す可能性があるかどうかは、実装定義です。
    • 幅指定子が使用された場合、最大 width までのみ一致します。
    • 一致した文字に加えて常にヌル文字を格納します（そのため引数配列には少なくとも width+1 文字分の領域が必要です）。
    d

    10 進整数 に一致します。

    • 数値の形式は、strtol が 10 を base 引数に使用した場合に期待されるものと同じです。
    signed char* または unsigned char*
    signed short* または unsigned short*
    signed int* または unsigned int*
    signed long* または unsigned long*
    signed long long* または unsigned long long*
    intmax_t* または uintmax_t*
    size_t*
    ptrdiff_t*
    		 N/A
    b (C23)

    符号なし 2 進整数 に一致します。

    • 数値の形式は、strtoul が 2 を base 引数に使用した場合に期待されるものと同じです。
    i

    整数 に一致します。

    • 数値の形式は、strtol が 0 を base 引数に使用した場合に期待されるものと同じです（基数は最初に解析された文字によって決定されます）。
    u

    符号なし 10 進整数 に一致します。

    • 数値の形式は、strtoul が 10 を base 引数に使用した場合に期待されるものと同じです。
    o

    符号なし 8 進整数 に一致します。

    • 数値の形式は、strtoul が 8 を base 引数に使用した場合に期待されるものと同じです。
    x
    X

    符号なし 16 進整数 に一致します。

    • 数値の形式は、strtoul が 16 を base 引数に使用した場合に期待されるものと同じです。
    n

    それまでに読み取られた文字数 を返します。

    • 入力は消費されません。代入カウントは増加しません。
    • 指定子に代入抑止演算子が定義されている場合、動作は未定義です。
    a (C99)
    A (C99)
    e
    E
    f
    F (C99)
    g
    G

    浮動小数点数 に一致します。

    • 数値の形式は、strtof が期待するものと同じです。
    		 N/A N/A
    float*
    double*
    		 N/A N/A N/A N/A
    long double*
    p

    実装定義の文字シーケンスに一致し、ポインタ を定義します。

    • printf 系の関数は、%p 書式指定子を使用して同じシーケンスを生成する必要があります。
    		 N/A N/A
    void**
    		 N/A N/A N/A N/A N/A N/A
    ノート

    n 以外のすべての変換指定子について、指定されたフィールド幅を超えず、かつ変換指定子が期待するものと正確に一致するか、またはそれが期待するシーケンスの接頭辞であるような、最長の入力文字シーケンスがストリームから消費されます。この消費されたシーケンスの後の最初の文字（存在する場合）は読み取られずに残ります。消費されたシーケンスの長さがゼロであるか、または消費されたシーケンスを上記のように変換できない場合、ストリームからの入力を妨げるファイル終端、エンコーディングエラー、または読み取りエラーがない限り、マッチング失敗が発生します。その場合は入力失敗です。

    % 指定子を除き、入力アイテム（または %n の場合は入力文字数）は、最初に変換指定子に適した型に変換されます。* で代入が抑制されなかった場合、変換結果はまだ書き込まれていない次の引数が指すオブジェクトに書き込まれます。このオブジェクトが適切な型を持たない場合、または変換結果をオブジェクトで表現できない場合、動作は未定義です。

    [、c、n 以外のすべての変換指定子は、入力を解析しようとする前に、先頭の空白文字をすべて消費して破棄します（isspace を呼び出すのと同様に判定されます）。これらの消費された文字は、指定された最大フィールド幅にはカウントされません。

    変換指定子 lc、ls、l[ は、最初の文字が変換される前にゼロに初期化された mbstate_t オブジェクトを使用して mbrtowc を呼び出すのと同様に、マルチバイトからワイド文字への変換を実行します。

    変換指定子 s と [ は、一致した文字に加えて常にヌル終端文字を格納します。宛先配列のサイズは、指定されたフィールド幅より少なくとも 1 大きくなければなりません。宛先配列のサイズを指定せずに %s または %[ を使用することは、gets と同じくらい安全ではありません。

    固定幅整数型（int8_t など）の正しい変換指定は、ヘッダ <inttypes.h> で定義されています（ただし SCNdMAX、SCNuMAX などは %jd、%ju などと同義です）。

    各変換指定子の動作の後にシーケンスポイントがあります。これにより、複数のフィールドを同じ「シンク」変数に格納できます。

    指数部に数字がない不完全な浮動小数点値（例えば、変換指定子 "100er" で %f を解析する場合）を解析するとき、シーケンス "100e"（おそらく有効な浮動小数点数の最長接頭辞）が消費され、マッチングエラー（消費されたシーケンスを浮動小数点数に変換できない）が発生し、"r" が残ります。一部の既存の実装はこのルールに従わず、"100" のみを消費するようにロールバックし、"er" を残します。例：glibc バグ 1765。

    変換指定が無効な場合、動作は未定義です。

    戻り値

    1-3) 正常に代入された受け取り引数の数。最初の受け取り引数が代入される前に読み取り失敗が発生した場合は EOF。
    4-6) (1-3) と同じですが、実行時制約違反がある場合も EOF が返されます。

    ノート

    これらの関数はすべて、少なくとも 1 回 va_arg を呼び出します。戻り後の arg の値は不定です。これらの関数は va_end を呼び出さないため、呼び出し側で行う必要があります。

    例

    このコードを実行する
    #include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>

bool checked_sscanf(int count, const char* buf, const char* fmt, ...)
{
    va_list ap;
    va_start(ap, fmt);
    int rc = vsscanf(buf, fmt, ap);
    va_end(ap);
    return rc == count;
}

int main(void)
{
    int n, m;

    printf("Parsing '1 2'...");
    if (checked_sscanf(2, "1 2", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");

    printf("Parsing '1 a'...");
    if (checked_sscanf(2, "1 a", "%d %d", &n, &m))
        puts("success");
    else
        puts("failure");
}

    出力： 

    Parsing '1 2'...success
Parsing '1 a'...failure

    参考文献

    • C23 規格 (ISO/IEC 9899:2024):
    • 7.21.6.9 vfscanf 関数 (p: TBD)
    • 7.21.6.11 vscanf 関数 (p: TBD)
    • 7.21.6.14 vsscanf 関数 (p: TBD)
    • K.3.5.3.9 vfscanf_s 関数 (p: TBD)
    • K.3.5.3.11 vscanf_s 関数 (p: TBD)
    • K.3.5.3.14 vsscanf_s 関数 (p: TBD)
    • C17 規格 (ISO/IEC 9899:2018):
    • 7.21.6.9 vfscanf 関数 (p: TBD)
    • 7.21.6.11 vscanf 関数 (p: TBD)
    • 7.21.6.14 vsscanf 関数 (p: TBD)
    • K.3.5.3.9 vfscanf_s 関数 (p: TBD)
    • K.3.5.3.11 vscanf_s 関数 (p: TBD)
    • K.3.5.3.14 vsscanf_s 関数 (p: TBD)
    • C11 規格 (ISO/IEC 9899:2011):
    • 7.21.6.9 vfscanf 関数 (p: 327)
    • 7.21.6.11 vscanf 関数 (p: 328)
    • 7.21.6.14 vsscanf 関数 (p: 330)
    • K.3.5.3.9 vfscanf_s 関数 (p: 597-598)
    • K.3.5.3.11 vscanf_s 関数 (p: 599)
    • K.3.5.3.14 vsscanf_s 関数 (p: 602)
    • C99 規格 (ISO/IEC 9899:1999):
    • 7.19.6.9 vfscanf 関数 (p: 293)
    • 7.19.6.11 vscanf 関数 (p: 294)
    • 7.19.6.14 vsscanf 関数 (p: 295)

    関連項目

    (C11)(C11)(C11)
    		 stdin、ファイルストリーム、またはバッファからの書式付き入力を読み取ります
    (関数)
    (C99)(C11)(C11)(C11)(C11)
    		 stdout、ファイルストリーム、またはバッファに書式付き出力を出力します
    可変引数リストを使用
    (関数)
    C++ ドキュメント for vscanf, vfscanf, vsscanf