scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_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)

 

定義於標頭檔案 <stdio.h>
	(1)
int scanf( const char          *format, ... );			(直到 C99)
int scanf( const char *restrict format, ... );			(C99 起)
		(2)
int fscanf( FILE          *stream, const char          *format, ... );				(直到 C99)
int fscanf( FILE *restrict stream, const char *restrict format, ... );				(C99 起)
			(3)
int sscanf( const char          *buffer, const char          *format, ... );					(直到 C99)
int sscanf( const char *restrict buffer, const char *restrict format, ... );					(C99 起)
int scanf_s(const char *restrict format, ...);				(4)	(C11 起)
int fscanf_s(FILE *restrict stream, const char *restrict format, ...);				(5)	(C11 起)
int sscanf_s(const char *restrict buffer, const char *restrict format, ...);				(6)	(C11 起)

從各種來源讀取資料，根據format解釋資料並將其儲存到給定位置。

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 時，才能保證 scanf_s、fscanf_s 和 sscanf_s 可用。

引數

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

format 字串由以下部分組成：

• 非空白多位元組字元（除了 %）：格式字串中的每個此類字元都從輸入流中消耗一個完全相同的字元，如果流中的下一個字元不相等，則導致函式失敗。
• 空白字元：格式字串中的任何單個空白字元都從輸入中消耗所有可用的連續空白字元（透過迴圈呼叫 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 的非空字元序列。 如果集合的第一個字元是 `^`，則匹配集合中不包含的所有字元。 如果集合以 `]` 或 `^]` 開頭，則 `]` 字元也包含在集合中。 在掃描集中非起始位置的字元 `-` 是否表示範圍（如 `[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。

複雜度

不保證。值得注意的是，一些 sscanf 的實現是 O(N)，其中 N = strlen(buffer) [1]。

注意

因為大多數轉換說明符首先消耗所有連續的空白字元，所以諸如

scanf("%d", &a);
scanf("%d", &b);

的程式碼將讀取在不同行（第二個 %d 將消耗第一個留下的換行符）或同一行，用空格或製表符分隔的兩個整數（第二個 %d 將消耗空格或製表符）。

不消耗前導空白字元的轉換說明符，例如 %c，可以透過在格式字串中使用空白字元來使其消耗前導空白字元

scanf("%d", &a);
scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char

示例

執行此程式碼

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stddef.h>
#include <locale.h>
 
int main(void)
{
    int i, j;
    float x, y;
    char str1[10], str2[4];
    wchar_t warr[2];
    setlocale(LC_ALL, "en_US.utf8");
 
    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
    /* parse as follows:
       %d: an integer
       %f: a floating-point value
       %9s: a string of at most 9 non-whitespace characters
       %2d: two-digit integer (digits 5 and 6)
       %f:  a floating-point value (digits 7, 8, 9)
       %*d: an integer which isn't stored anywhere
       ' ': all consecutive whitespace
       %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6)
       %2lc: two wide characters, using multibyte to wide conversion  */
    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
                     &i, &x, str1, &j, &y, str2, warr);
 
    printf("Converted %d fields:\n"
           "i = %d\n"
           "x = %f\n"
           "str1 = %s\n"
           "j = %d\n"
           "y = %f\n"
           "str2 = %s\n"
           "warr[0] = U+%x\n"
           "warr[1] = U+%x\n",
           ret, i, x, str1, j, y, str2, warr[0], warr[1]);
 
#ifdef __STDC_LIB_EXT1__
    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
    // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n.
#endif
}

可能的輸出

Converted 7 fields:
i = 25
x = 5.432000
str1 = Thompson
j = 56
y = 789.000000
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

參考

• C17 標準 (ISO/IEC 9899:2018)

• 7.21.6.2 fscanf 函式 (p: 231-236)

• 7.21.6.4 scanf 函式 (p: 236-237)

• 7.21.6.7 sscanf 函式 (p: 238-239)

• K.3.5.3.2 fscanf_s 函式 (p: 430-431)

• K.3.5.3.4 scanf_s 函式 (p: 432)

• K.3.5.3.7 sscanf_s 函式 (p: 433)

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

• 7.21.6.2 fscanf 函式 (p: 317-324)

• 7.21.6.4 scanf 函式 (p: 325)

• 7.21.6.7 sscanf 函式 (p: 326)

• K.3.5.3.2 fscanf_s 函式 (p: 592-593)

• K.3.5.3.4 scanf_s 函式 (p: 594)

• K.3.5.3.7 sscanf_s 函式 (p: 596)

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

• 7.19.6.2 fscanf 函式 (p: 282-289)

• 7.19.6.4 scanf 函式 (p: 290)

• 7.19.6.7 sscanf 函式 (p: 291)

• C89/C90 標準 (ISO/IEC 9899:1990)

• 4.9.6.2 fscanf 函式

• 4.9.6.4 scanf 函式

• 4.9.6.6 sscanf 函式

另見

vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	從 stdin、檔案流或緩衝區讀取格式化輸入 使用可變引數列表 (函式)
fgets	從檔案流獲取字元字串 (函式)
printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11)	將格式化輸出列印到 stdout、檔案流或緩衝區 (函式)
C++ 文件 用於 scanf, fscanf, sscanf