wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

来自cppreference.com
< 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)  
 
在标头 <wchar.h> 定义
(1) 
int wscanf( const wchar_t *format, ... );
(C95 起)
(C99 前) 
int wscanf( const wchar_t *restrict format, ... );
(C99 起)
(2) 
int fwscanf( FILE *stream, const wchar_t *format, ... );
(C95 起)
(C99 前) 
int fwscanf( FILE *restrict stream,
             const wchar_t *restrict format, ... );
(C99 起)
(3) 
int swscanf( const wchar_t *buffer, const wchar_t *format, ... );
(C95 起)
(C99 前) 
int swscanf( const wchar_t *restrict buffer,
             const wchar_t *restrict format, ... );
(C99 起) 
int wscanf_s( const wchar_t *restrict format, ...);
(4) (C11 起) 
int fwscanf_s( FILE *restrict stream,
               const wchar_t *restrict format, ...);
(5) (C11 起) 
int swscanf_s( const wchar_t *restrict s,
               const wchar_t *restrict format, ...);
(6) (C11 起)

从各种资源读取数据，按照 format 转译，并存储结果于给定位置。

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__，且当用户在包含 <wchar.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，wscanf_s、fwscanf_s 和 swscanf_s 才可用。

参数

stream - 要读取的输入文件流
buffer - 指向要读取的空终止宽字符串的指针
format - 指向指定读取输入方式的空终止宽字符串的指针
... - 接收各实参。


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

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

下列格式指示符可用：

 转换指示符  解释 期望的实参类型
长度修饰符→ hh h 无 l ll j z t L
仅从 C99 起可用→ 是 是 是 是 是
%
匹配字面 %。
 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用
c

匹配一个字符或字符的序列。

  • 如果使用了宽度指示符，那么匹配恰好宽度个宽字符（该实参必须是指向有充足空间的数组的指针）。
  • 与 %s 和 %[ 不同，它不会在数组后附加空字符。
 不适用 不适用
char*
wchar_t*
 不适用 不适用 不适用 不适用 不适用
s

匹配非空白字符的序列（一个字符串）。

  • 如果使用宽度指示符，那么至多匹配宽度个字符，或匹配到首个提前出现的空白符前。
  • 总是在匹配的字符后存储一个空字符（因此实参数组必须有至少宽度 +1个字符的空间）。
[集合 ]

匹配集合 中的字符的一个非空字符序列。

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

匹配一个十进制整数。

  • 该数的格式与 wcstol 以值 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*
 不适用
i

匹配一个整数。

  • 该数的格式与 wcstol 以值 0 为 base 时期望的格式相同。
u

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

  • 该数的格式与 wcstoul 以值 10 为 base 时期望的格式相同。
o

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

  • 该数的格式与 wcstoul 以值 8 为 base 时期望的格式相同。
x
X

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

  • 该数的格式与 wcstoul 以值 16 为 base 时期望的格式相同。
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 和 [ 进行宽到到多字节字符转换，如同在转换首字符前，通过用初始化为零的 mbstate_t 对象调用 wcrtomb。

转换指示符 s 与 [ 始终在匹配字符之后存储一个空字符。目标数组的大小必须至少比指定字段宽度大一。未指定目标数组大小时，对 %s 或 %[ 的使用，与 gets 同样不安全。

定宽整数类型（int8_t 等）的正确的转换指示在标头 <inttypes.h> 定义（虽然 SCNdMAX、SCNuMAX 等就是 %jd、%ju 等的别名）。

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

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

如果转换指示非法，那么行为未定义。

返回值

1-3) 成功赋值的接收参数数量，若在赋值首个接收参数前出现读取失败，则为 EOF。
4-6) 同 (1-3)，但若有运行时制约违规，则亦返回 EOF。

示例

运行此代码
#include <stdio.h>
#include <wchar.h>
#include <string.h>

#define NUM_VARS   3
#define ERR_READ   2
#define ERR_WRITE  3

int main(void) {
    wchar_t state[64];   // 州
    wchar_t capital[64]; // 首府（州的首府）
    unsigned int population = 0; // 人口
    int elevation = 0;           // 高程
    int age = 0;  // 已设立时间
    float pi = 0; // π（数学常数）
// 交互模式
#if INTERACTIVE_MODE
    // 下列英文释义：输入州名，已设立时间和 π（数学常数）
    wprintf(L"Enter state, age, and pi value: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        // 输入错误
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#else
   // 下列英文释义：加利福尼亚州 170 3.141592
    wchar_t* input = L"California 170 3.141592";
    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);

    FILE* fp = tmpfile();
    if (fp) {
        // 向临时文件写入数据
        // 下列英文释义：宽字符串内容：密西西比州 杰克逊首府 420000 807
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // 倒回（rewind）文件指针
        rewind(fp);

        // 将数据读入到变量
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        // 下列英文释义：州名 首府 杰克逊人口 (2020年) 最大高程
        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
                L"Highest elevation: %dft\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

可能的输出： 

State: California
Age  : 170 years
Pi   : 3.14159

State  : Mississippi
Capital: Jackson
Jackson population (in 2020): 420000
Highest elevation: 807ft

引用

  • C11 标准（ISO/IEC 9899:2011）：
  • 7.29.2.2 The fwscanf function （第 410-416 页）
  • 7.29.2.4 The swscanf function （第 417 页）
  • 7.29.2.12 The wscanf function （第 421 页）
  • K.3.9.1.2 The fwscanf_s function （第 628-629 页）
  • K.3.9.1.5 The swscanf_s function （第 631 页）
  • K.3.9.1.14 The wscanf_s function （第 638 页）
  • C99 标准（ISO/IEC 9899:1999）：
  • 7.24.2.2 The fwscanf function （第 356-362 页）
  • 7.24.2.4 The swscanf function （第 362 页）
  • 7.24.2.12 The wscanf function （第 366-367 页）

参阅

(C99)(C99)(C99)(C11)(C11)(C11)
 从 stdin、文件流或缓冲区读取格式化宽字符输入
使用可变参数列表
(函数)
wscanf, fwscanf, swscanf 的 C++ 文档