vwscanf, vfwscanf, vswscanf, vwscanf_s, vfwscanf_s, vswscanf_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

檔案輸入/輸出

型別和物件
stdinstdoutstderr          FILE fpos_t
函式 檔案訪問 fopenfopen_s (C11) freopenfreopen_s (C11)   fwide (C95) setbuf setvbuf fclose fflush 非格式化輸入/輸出 fgetc fgets fputc fputs getchar getsgets_s (直至 C11)(C11) putchar puts ungetc fgetwcgetwc (C95)(C95) fgetws (C95) fputwcputwc (C95)(C95) fputws (C95) getwchar (C95) putwchar (C95) ungetwc (C95) 格式化輸入 scanffscanfsscanfscanf_sfscanf_ssscanf_s (C11)(C11)(C11) wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_s (C95)(C95)(C95)(C11)(C11)(C11) vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11) vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	直接輸入/輸出 fread fwrite 格式化輸出 printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11) wprintffwprintfswprintfwprintf_sfwprintf_sswprintf_ssnwprintf_s (C95)(C95)(C95)(C11)(C11)(C11)(C11)   vprintfvfprintfvsprintfvsnprintfvprintf_svfprintf_svsprintf_svsnprintf_s (C99)(C11)(C11)(C11)(C11) vwprintfvfwprintfvswprintfvwprintf_svfwprintf_svswprintf_svsnwprintf_s (C95)(C95)(C95)(C11)(C11)(C11)(C11) 檔案定位 ftell fgetpos fseek fsetpos rewind 錯誤處理 clearerr feof ferror perror 檔案操作 remove tmpfiletmpfile_s (C11) rename tmpnamtmpnam_s (C11)

 

在標頭檔案 <wchar.h> 中定義
int vwscanf( const wchar_t *restrict format, va_list vlist );	(1)	(C99 起)
int vfwscanf( FILE *restrict stream,               const wchar_t *restrict format, va_list vlist );	(2)	(C99 起)
int vswscanf( const wchar_t *restrict buffer,               const wchar_t *restrict format, va_list vlist );	(3)	(C99 起)
int vwscanf_s( const wchar_t *restrict format, va_list vlist );	(4)	(C11 起)
int vfwscanf_s( FILE *restrict stream,                 const wchar_t *restrict format, va_list vlist );	(5)	(C11 起)
int vswscanf_s( const wchar_t *restrict buffer,                 const wchar_t *restrict format, va_list vlist );	(6)	(C11 起)

從各種源讀取資料，根據 format 解釋資料，並將結果儲存到 vlist 定義的位置。

1) 從 stdin 讀取資料。

2) 從檔案流 `stream` 讀取資料。

3) 從以空字元結尾的寬字串 buffer 讀取資料。到達字串末尾等同於 fwscanf 的檔案結束條件。

4-6) 與 (1-3) 相同，但 %c、%s 和 %[ 轉換說明符每個都期望兩個引數（常規指標和型別為 rsize_t 的值，指示接收陣列的大小，當使用 %lc 讀取單個寬字元時，該值可能為 1），並且在執行時檢測到以下錯誤並呼叫當前安裝的 約束處理函式

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

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

引數

stream	-	要從中讀取的輸入檔案流
buffer	-	指向要從中讀取的以空字元結尾的寬字串的指標
format	-	指向以空字元結尾的寬字串的指標，指定如何讀取輸入
vlist	-	包含接收引數的變數引數列表。

format 字串由以下部分組成：

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

• 開頭的 % 字元。

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

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

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

• 轉換格式說明符。

以下格式說明符可用：

轉換 說明符	解釋	預期 引數型別
長度修飾符→		hh	h	無	l	ll	j	z	t	L
僅在 C99 之後可用→		是				是	是	是	是
%	匹配字面量 `%`。	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用
c	匹配一個字元或一系列字元。 如果使用了寬度說明符，則精確匹配 *寬度* 個寬字元（引數必須是指向具有足夠空間的陣列的指標）。 與 %s 和 %[ 不同，不會在陣列末尾新增空字元。	不適用	不適用	char*	wchar_t*	不適用	不適用	不適用	不適用	不適用
s	匹配一系列非空白字元（一個字串）。 如果使用寬度說明符，則匹配最多 *width* 個字元或直到第一個空白字元，以先出現的為準。 除了匹配的字元外，始終儲存一個空字元（因此引數陣列必須至少有 *width+1* 個字元的空間）。
[set ]	匹配來自字元 set 的非空字元序列。 如果集合的第一個字元是 `^`，則匹配集合中不包含的所有字元。 如果集合以 `]` 或 `^]` 開頭，則 `]` 字元也包含在集合中。 在掃描集中非起始位置的字元 `-` 是否表示範圍（如 `[0-9]`）是實現定義的。 如果使用寬度說明符，則只匹配最多 *width* 個字元。 除了匹配的字元外，始終儲存一個空字元（因此引數陣列必須至少有 *width+1* 個字元的空間）。
d	匹配一個十進位制整數。 數字的格式與 wcstol 期望的格式相同，其中 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	匹配一個整數。 數字的格式與 wcstol 期望的格式相同，其中 base 引數的值為 ​0​（基數由解析的第一個字元確定）。
u	匹配一個無符號十進位制整數。 數字的格式與 wcstoul 期望的格式相同，其中 base 引數的值為 10。
o	匹配一個無符號八進位制整數。 數字的格式與 wcstoul 期望的格式相同，其中 base 引數的值為 8。
x X	匹配一個無符號十六進位制整數。 數字的格式與 wcstoul 期望的格式相同，其中 base 引數的值為 16。
n	返回目前讀取的字元數。 不消耗輸入。不增加賦值計數。 如果說明符定義了賦值抑制運算子，則行為是未定義的。
a (C99) A (C99) e E f F (C99) g G	匹配一個浮點數。 數字的格式與 wcstof 期望的格式相同。	不適用	不適用	float*	double*	不適用	不適用	不適用	不適用	long double*
p	匹配定義指標的實現定義的字元序列。 `printf` 函式族應使用 `%p` 格式說明符生成相同的序列。	不適用	不適用	void**	不適用	不適用	不適用	不適用	不適用	不適用
注意
對於除 n 以外的所有轉換說明符，從流中消耗的字元序列是最長的輸入字元序列，它不超過任何指定的欄位寬度，並且要麼完全符合轉換說明符的期望，要麼是轉換說明符期望序列的字首。在此消耗序列之後的第一個字元（如果有）仍未讀取。如果消耗序列的長度為零，或者消耗序列無法按上述指定方式轉換，則會發生匹配失敗，除非檔案結束、編碼錯誤或讀取錯誤阻止了流輸入，在這種情況下是輸入失敗。 除 [、c 和 n 之外的所有轉換說明符都會在嘗試解析輸入之前消耗並丟棄所有前導空白字元（透過呼叫 iswspace 確定）。這些消耗的字元不計入指定的最大欄位寬度。 如果未使用長度說明符 l，則轉換說明符 c、s 和 [ 執行寬字元到多位元組字元的轉換，就像在轉換第一個字元之前呼叫 wcrtomb 並使用初始化為零的 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，必須由呼叫者完成。

參考

• C11 標準 (ISO/IEC 9899:2011)

• 7.29.2.6 vfwscanf 函式 (p: 418)

• 7.29.2.8 vswscanf 函式 (p: 419)

• 7.29.2.10 vwscanf 函式 (p: 420)

• K.3.9.1.7 vfwscanf_s 函式 (p: 632-633)

• K.3.9.1.10 vswscanf_s 函式 (p: 635-636)

• K.3.9.1.12 vwscanf_s 函式 (p: 637)

• C99 標準 (ISO/IEC 9899:1999)

• 7.24.2.6 vfwscanf 函式 (p: 364)

• 7.24.2.8 vswscanf 函式 (p: 365)

• 7.24.2.10 vwscanf 函式 (p: 366)

另請參閱

wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_s (C95)(C95)(C95)(C11)(C11)(C11)	從 stdin、檔案流或緩衝區讀取格式化的寬字元輸入 (函式)
C++ 文件 用於 vwscanf, vfwscanf, vswscanf