vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s

定義於標頭檔案 `<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 和 %[ 轉換說明符各需要兩個引數（通常的指標和型別為 rsize_t 的值，指示接收陣列的大小，當用 %c 讀取單個字元時可為 1），並且在執行時檢測到以下錯誤並呼叫當前安裝的約束處理程式函式：

任何指標型別的引數為空指標
`format`、`stream` 或 `buffer` 為空指標
由 %c、%s 或 %[ 寫入的字元數，加上終止空字元，將超過為每個這些轉換說明符提供的第二個 (rsize_t) 引數
可選地，任何其他可檢測的錯誤，例如未知轉換說明符

與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <stdio.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才保證 `vscanf_s`、`vfscanf_s` 和 `vsscanf_s` 可用。

非空白多位元組字元，除了 %：格式字串中的每個此類字元精確消耗輸入流中的一個相同字元，如果流中的下一個字元不相等則導致函式失敗。
空白字元：格式字串中的任何單個空白字元消耗輸入中所有可用的連續空白字元（透過迴圈呼叫 isspace 確定）。請注意，格式字串中的 "\n"、" "、"\t\t" 或其他空白沒有區別。
轉換說明符。每個轉換說明符具有以下格式：

開頭的 % 字元。

(可選) 抑制賦值的字元 *。如果存在此選項，函式不會將轉換結果賦值給任何接收引數。

(可選) 整數（大於零），指定 *最大欄位寬度*，即函式在進行當前轉換說明符指定的轉換時允許消耗的最大字元數。請注意，如果未提供寬度，%s 和 %[ 可能導致緩衝區溢位。

(可選) *長度修飾符*，指定接收引數的大小，即實際目標型別。這會影響轉換精度和溢位規則。預設目標型別對於每種轉換型別都不同（見下表）。

轉換格式說明符。

以下格式說明符可用：

轉換說明符	解釋	預期引數型別
長度修飾符→		`hh`	`h`	無	`l`	`ll`	`j`	`z`	`t`	`L`
僅在 C99 之後可用→		是				是	是	是	是
`%`	匹配字面量 `%`。	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用
`c`	匹配一個字元或一系列字元。如果使用寬度說明符，則精確匹配 width 個字元（引數必須是指向具有足夠空間的陣列的指標）。與 %s 和 %[ 不同，不會在陣列末尾新增空字元。	不適用	不適用	char*	wchar_t*	不適用	不適用	不適用	不適用	不適用
`s`	匹配一系列非空白字元（一個字串）。如果使用寬度說明符，則匹配最多 width 個字元或直到第一個空白字元，以先出現的為準。除了匹配的字元外，始終儲存一個空字元（因此引數陣列必須至少有 width+1 個字元的空間）。
`[`set `]`	匹配來自字元 set 的非空字元序列。如果集合的第一個字元是 `^`，則匹配集合中不包含的所有字元。如果集合以 `]` 或 `^]` 開頭，則 `]` 字元也包含在集合中。在掃描集中非起始位置的字元 `-` 是否表示範圍（如 `[0-9]`）是實現定義的。如果使用寬度說明符，則只匹配最多 width 個字元。除了匹配的字元外，始終儲存一個空字元（因此引數陣列必須至少有 width+1 個字元的空間）。
`d`	匹配一個十進位制整數。數字的格式與 strtol 期望的格式相同，`base` 引數的值為 10。	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*	不適用
`i`	匹配一個整數。數字的格式與 strtol 期望的格式相同，`base` 引數的值為 0（基數由解析的第一個字元確定）。
`u`	匹配一個無符號十進位制整數。數字的格式與 strtoul 期望的格式相同，`base` 引數的值為 10。
`o`	匹配一個無符號八進位制整數。數字的格式與 strtoul 期望的格式相同，`base` 引數的值為 8。
`x` `X`	匹配一個無符號十六進位制整數。數字的格式與 strtoul 期望的格式相同，`base` 引數的值為 16。
`n`	返回目前讀取的字元數。不消耗輸入。不增加賦值計數。如果說明符定義了賦值抑制運算子，則行為是未定義的。
`a` (C99) `A` (C99) `e` `E` `f` `F` (C99) `g` `G`	匹配一個浮點數。數字的格式與 strtof 期望的格式相同。	不適用	不適用	float*	double*	不適用	不適用	不適用	不適用	long double*
`p`	匹配定義指標的實現定義的字元序列。 `printf` 函式族應使用 `%p` 格式說明符生成相同的序列。	不適用	不適用	void**	不適用	不適用	不適用	不適用	不適用	不適用
注意
對於除 n 之外的每個轉換說明符，從流中消耗的輸入字元的最長序列不超出任何指定的欄位寬度，並且要麼與轉換說明符期望的完全相同，要麼是其期望序列的字首。消耗序列後的第一個字元（如果有）保持未讀。如果消耗序列長度為零，或者消耗序列無法按上述指定轉換，則除非檔案結束、編碼錯誤或讀取錯誤阻止了流輸入，否則會發生匹配失敗，在這種情況下是輸入失敗。除 [、c 和 n 之外的所有轉換說明符在嘗試解析輸入之前消耗並丟棄所有前導空白字元（透過呼叫 isspace 確定）。這些消耗的字元不計入指定的最大欄位寬度。轉換說明符 lc、ls 和 l[ 執行多位元組到寬字元轉換，如同在轉換第一個字元之前呼叫 mbrtowc 並將 mbstate_t 物件初始化為零一樣。轉換說明符 s 和 [ 除了匹配的字元外，總是儲存空終止符。目標陣列的大小必須至少比指定欄位寬度大一。在不指定目標陣列大小的情況下使用 %s 或 %[，與 gets 一樣不安全。固定寬度整數型別（int8_t 等）的正確轉換說明符定義在標頭檔案 `<inttypes.h>` 中（儘管 `SCNdMAX`、`SCNuMAX` 等與 %jd、%ju 等是同義詞）。每個轉換說明符的操作之後都有一個序列點；這允許在同一個“接收”變數中儲存多個欄位。當解析一個不完整的浮點值，該值以沒有數字的指數結尾時，例如用轉換說明符 %f 解析 "100er"，序列 "100e"（可能是有效浮點數的最長字首）被消耗，導致匹配錯誤（消耗的序列無法轉換為浮點數），並留下 "r"。一些現有實現不遵循此規則，而是回滾只消耗 "100"，留下 "er"，例如，glibc bug 1765。如果轉換說明符無效，則行為未定義。

[編輯] 返回值

1-3) 成功賦值的接收引數的數量，如果在第一個接收引數賦值之前發生讀取失敗，則返回 EOF。

4-6) 與 (1-3) 相同，但如果存在執行時約束違規，也返回 EOF。

[編輯] 注意

所有這些函式至少呼叫一次 va_arg，返回後 `arg` 的值是不確定的。這些函式不呼叫 va_end，這必須由呼叫者完成。

[編輯] 示例

執行此程式碼

#include <stdio.h>
#include <stdbool.h>
#include <stdarg.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

[編輯] 參考資料

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)

[編輯] 另請參閱

scanffscanfsscanfscanf_sfscanf_ssscanf_s (C11)(C11)(C11)	從 stdin、檔案流或緩衝區讀取格式化輸入 (函式) [編輯]
vprintfvfprintfvsprintfvsnprintfvprintf_svfprintf_svsprintf_svsnprintf_s (C99)(C11)(C11)(C11)(C11)	將格式化輸出列印到 stdout、檔案流或緩衝區使用可變引數列表 (函式) [編輯]
C++ 文件，關於 vscanf, vfscanf, vsscanf

編譯器支援
語言
標頭檔案
型別支援
程式工具
變參函式支援
錯誤處理
動態記憶體管理
字串庫
演算法
數值
日期和時間工具
輸入/輸出支援
本地化支援
併發支援 (C11)
技術規範
符號索引

cppreference.com

名稱空間

變體

檢視

操作