scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

< c‎ | io
 
C
 
文件输入/输出
类型与对象
函数
文件访问
直接输入/输出
无格式输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)
有格式输入
scanffscanfsscanfscanf_sfscanf_ssscanf_s
(C11)(C11)(C11)
(C95)(C95)(C95)(C11)(C11)(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 ）参数
  • 可选，任何其他可检测错误，例如未知转换指定符
同所有边界检查函数， scanf_s, fscanf_s, sscanf_s 仅若实现定义了 __STDC_LIB_EXT1__ ，且用户在包含 <stdio.h> 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

stream - 要读取的输入文件流
buffer - 指向要读取的空终止字符串的指针
format - 指向指定读取输入方式的空终止字符串的指针。

格式字符串由下列内容组成

  • 非空白多字节字符，除了 % ：每个格式字符串中的这种字符处理来自输入流的准确同一字符，或若它与流的下个字符比较不相等则导致函数失败。
  • 空白符：任何格式字符串中的单个空白符处理所有来自输入的可用连续空白符（如同通过于循环中调用 isspace 确定）。注意格式字符串中 "\n" 、 " " 、 "\t\t" 或其他空白无区别。
  • 转换说明：每个转换说明拥有下列格式：
  • 引入用 % 字符
  • (可选)赋值抑制字符 * 。若存在此选项，则此函数不将结果赋值给任何接收用参数。
  • (可选)指定最大域宽的整数数字（大于零），即函数进行在当前转换说明所指定的转换时，允许处理的最大字符数。注意若不提供宽度，则 %s 和 %[ 可能导致缓冲区溢出。
  • (可选)指定接收参数大小的长度修饰符，即实际目标类型。这影响转换准确性和溢出规则。默认目标类型对每个转换类型不同（见下表）。
  • 转换格式说明符

下列格式说明符可用：

转换
说明符 		解释 参数类型
长度修饰符 →
 hh

(C99)

h （无） l ll

(C99)

j

(C99)

z

(C99)

t

(C99)

L
% 匹配字面 % 。 N/A N/A N/A N/A N/A N/A N/A N/A N/A
c
匹配一个字符或字符的序列

若使用了宽度说明符，则匹配准确的宽度个字符（该参数必须是指向有充足空间的数组的指针）。不同于 %s 和 %[ ，它不会在数组后附加空字符。

N/A N/A
char*
wchar_t*
 N/A N/A N/A N/A N/A
s
匹配非空白字符的序列（一个字符串）

若使用宽度说明符，则至多匹配宽度个字符，或匹配到首个提前出现的空白符前。总是在匹配的字符后存储一个空字符（故参数数组必须有至少宽度 +1 个字符的空间）。

[集合]
匹配一个来自 集合 的字符的非空字符序列。

若集合的首字符是 ^ ，则匹配所有不在集合中的字符。若集合以 ] 或 ^] 开始，则 ] 字符亦被包含入集合。在扫描集合的非最初位置的字符 - 是否可以指示范围，如 [0-9] ，是实现定义的。若使用宽度说明符，则最多匹配到宽度。总是在匹配的字符后存储一个空字符（故参数数组必须有至少宽度 +1 个字符的空间）。

d
匹配一个十进制整数。

该数的格式同 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*
N/A
i
匹配一个整数。

该数的格式同 strtol() 以值 ​0​ 为 base 时所期望者（基底以首个分析的字符确定）

u
匹配一个无符号十进制整数。

该数的格式同 strtoul() 以值 10 为 base 参数时所期望者。

o
匹配一个无符号八进制数。

该数的格式同 strtoul() 以值 8 为 base 参数时所期望者。

x, X
匹配一个无符号十六进制整数。

该数的格式同 strtoul() 以值 16 为 base 参数时所期望者。

n
返回迄今读取的字符数。

不消耗输出。不增加赋值计数。若此说明符拥有赋值抑制运算符，则行为未定义。

a, A(C99)
e, E
f, F
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 的转换说明符，不超过任何指定域宽，且要么是转换说明符所准确期待，要么是其所期待的前缀的最长输入字符序列，即是从流中消耗的内容。此消耗序列后的首个字符若存在，则保持未读取。若被消耗序列长度为零，或被消耗序列不能转换成上面所指定的项目，则发生匹配失败，除非遇到文件尾、编码错误，或阻止从流输入的读取错误，此情况下此为输入失败。

所有异于 [ 、 c 和 n 的转换说明符，在尝试分析输入前消耗并舍弃所有前导空白字符（如同以调用 isspace 来确定）。这些被消耗的字符不计入指定的最大域宽。

转换说明符 lc 、 ls 和 l[ 进行多字节到宽字符转换，如同如同在转换首字符前，通过用初始化到零的 mbstate_t 对象调用 mbrtowc() 。

转换说明符 s 与 [ 始终在匹配字符之后存储一个空字符。目标数组的大小必须至少比指定域宽大一。

定宽整数类型（ int8_t 等）的正确的转换说明定义于头文件 <inttypes.h> （虽然 SCNdMAX 、 SCNuMAX 等就是 %jd 、 %ju 等的别名）。

在每个转换说明符后有一个序列点；这允许存储多个域到同一“池”变量中。

在分析以无数字指数为结尾的不完整浮点值，如以转换说明符 %f 分析 "100er" 时，消耗序列 "100e" （可能为合法浮点数的最长前缀），并导致匹配错误（被消耗序列不能转换成浮点数），而留下 "r" 。某些既存实现不遵守此规则并回滚，通过消耗 "100" 而留下 "er" ，例如 glibc 漏洞 1765 。

若转换指定非法，则行为未定义。


... - 接收用参数

返回值

1-3) 成功赋值的接收参数的数量（可以为零，在首个接收用参数赋值前匹配失败的情况下），或者若输入在首个接收用参数赋值前发生失败，则为EOF。
4-6) 同 (1-3) ，除了若有运行时制约违规，亦返回 EOF 。

注意

因为多数转换指定符首先消耗掉所有连续空白符，如下的代码 

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

将读取在不同行上（第二个 %d 会消耗第一个剩下的换行符）或同一行由空格或制表符分隔（第二个 %d 会消耗空格或制表符）的整数。

不消耗前导空白符的转换指定符，如 %c ，可以通过在格式字符串中前置一个空白符令它如此： 

scanf("%d", &a);
scanf(" %c", &c); // 消耗 %d 后的所有后继空白符，然后读一个 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ß水";
    /* 按下列分析：
       %d ：整数
       %f ：浮点值
       %9s ：最多有 9 个非空白符的字符串
       %2d ： 2 位的整数（数位 5 和 6 ）
       %f ：浮点值（数位 7 、 8 、 9）
       %*d ：不存储于任何位置的整数
       ' ' ：所有连续空白符
       %3[0-9] ：至多有 3 个十进制数字的字符串（数位 5 和 6 ）
       %2lc ：二个宽字符，使用多字节到宽转换  */
    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:\ni = %d\nx = %f\nstr1 = %s\n"
           "j = %d\ny = %f\nstr2 = %s\n"
           "warr[0] = U+%x 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);
    // 写 25 到 i ， 5.432 到 x ， 9 个字节 "thompson\0" 到 str1 ，和 3 到 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

引用

  • C11 standard (ISO/IEC 9899:2011):
  • 7.21.6.2 The fscanf function (p: 317-324)
  • 7.21.6.4 The scanf function (p: 325)
  • 7.21.6.7 The sscanf function (p: 326)
  • K.3.5.3.2 The fscanf_s function (p: 592-593)
  • K.3.5.3.4 The scanf_s function (p: 594)
  • K.3.5.3.7 The sscanf_s function (p: 596)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.19.6.2 The fscanf function (p: 282-289)
  • 7.19.6.4 The scanf function (p: 290)
  • 7.19.6.7 The sscanf function (p: 291)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.9.6.2 The fscanf function
  • 4.9.6.4 The scanf function
  • 4.9.6.6 The sscanf function

参阅

(C99)(C99)(C99)(C11)(C11)(C11)
 从 stdin 、文件流或缓冲区读取格式化输入
使用可变参数列表
(函数)
从文件流获取一个字符串
(函数)
(C99)(C11)(C11)(C11)(C11)
 打印格式化输出到 stdout 、文件流或缓冲区
(函数)