wprintf、fwprintf、swprintf、wprintf_s、fwprintf_s、swprintf_s、snwprintf_s
定义在头文件 <wchar.h> 中 |
||
(1) | ||
int wprintf( const wchar_t* format, ... ); |
(自 C95) (直到 C99) |
|
int wprintf( const wchar_t* restrict format, ... ); |
(自 C99) | |
(2) | ||
int fwprintf( FILE* stream, const wchar_t* format, ... ); |
(自 C95) (直到 C99) |
|
int fwprintf( FILE* restrict stream, const wchar_t* restrict format, ... ); |
(自 C99) | |
(3) | ||
int swprintf( wchar_t* buffer, size_t bufsz, const wchar_t* format, ... ); |
(自 C95) (直到 C99) |
|
int swprintf( wchar_t* restrict buffer, size_t bufsz, const wchar_t* restrict format, ... ); |
(自 C99) | |
int wprintf_s( const wchar_t* restrict format, ... ); |
(4) | (自 C11) |
int fwprintf_s( FILE* restrict stream, const wchar_t* restrict format, ... ); |
(5) | (自 C11) |
int swprintf_s( wchar_t* restrict buffer, rsize_t bufsz, const wchar_t* restrict format, ... ); |
(6) | (自 C11) |
int snwprintf_s( wchar_t* restrict s, rsize_t n, const wchar_t* restrict format, ... ); |
(7) | (自 C11) |
从给定位置加载数据,将其转换为宽字符串等效项,并将结果写入各种接收器。
- 转换说明符
%n
存在于 format 中 - 任何对应于
%s
的参数都是空指针 - format 或 buffer 是空指针
- bufsz 为零或大于 RSIZE_MAX / sizeof(wchar_t)
- 在任何字符串和字符转换说明符中发生编码错误
- (仅适用于
swprintf_s
) 要写入的宽字符数量(包括空字符)将超过 bufsz。
- 转换说明符
- 与所有边界检查函数一样,
wprintf_s
、fwprintf_s
、swprintf_s
和snwprintf_s
仅在实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时才保证可用。
内容 |
[编辑] 参数
stream | - | 要写入的输出文件流 |
buffer | - | 指向要写入的宽字符字符串的指针 |
bufsz | - | 最多可以写入 bufsz - 1 个宽字符,加上空终止符 |
format | - | 指向指定如何解释数据的空终止宽字符串的指针 |
... | - | 指定要打印的数据的参数。如果任何参数在 默认参数提升 之后不是相应转换说明符预期的类型,或者参数少于 format 所需的数量,则行为未定义。如果参数多于 format 所需的数量,则会对多余的参数进行评估并忽略。 |
format 字符串由普通宽字符(除了 %
)组成,这些字符将不加修改地复制到输出流中,以及转换说明符。每个转换说明符都具有以下格式
- 介绍性
%
字符。
- 介绍性
- (可选) 一或多个标志,它们会修改转换的行为
-
-
:转换的结果在字段内左对齐(默认情况下右对齐)。 -
+
:带符号转换的符号始终前缀到转换结果(默认情况下,结果仅在为负数时才以减号开头)。 - 空格:如果带符号转换的结果不是以符号字符开头,或者为空,则空格会前缀到结果中。如果存在
+
标志,则会忽略它。 -
#
:执行转换的替代形式。有关确切效果,请参见下表,否则行为未定义。 -
0
:对于整数和浮点数转换,使用前导零来填充字段,而不是使用空格字符。对于整数,如果显式指定了精度,则会忽略它。对于使用此标志的其他转换,会导致未定义的行为。如果存在-
标志,则会忽略它。
-
- (可选) 整数值或 `*`,指定最小字段宽度。如果需要,结果会在右对齐时用空格字符(默认)在左侧填充,或者在左对齐时用空格字符在右侧填充。当使用 `*` 时,宽度由一个额外的类型为 int 的参数指定,该参数出现在要转换的参数之前,以及如果提供则提供精度的参数之前。如果参数的值为负数,则会导致指定 `-` 标志和正字段宽度(注意:这是最小宽度:值永远不会被截断)。
- (可选) `.` 后面跟着整数或 `*`,或者两者都不存在,指定转换的精度。当使用 `*` 时,精度由一个额外的类型为 int 的参数指定,该参数出现在要转换的参数之前,但在提供最小字段宽度的参数之后(如果提供)。如果该参数的值为负数,则会被忽略。如果没有使用数字或 `*`,则精度取为零。有关精度的确切效果,请参见下表。
- (可选) 长度修饰符,指定参数的大小(与转换格式说明符结合使用,它指定了相应参数的类型)。
- 转换格式说明符。
以下格式说明符可用
转换 说明符 |
解释 | 预期 参数类型 | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
长度 →
修饰符 |
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
|
参数首先被转换为 wchar_t,就像通过调用 btowc 一样。如果使用了l修饰符,则 `wint_t` 参数首先被转换为 wchar_t。 |
N/A | N/A | int |
wint_t |
N/A | N/A | N/A | N/A | N/A |
s
|
参数必须是指向字符数组的初始元素的指针,该字符数组包含以初始移位状态开始的多字节字符序列,该序列被转换为宽字符数组,就像通过调用 mbrtowc(使用零初始化的转换状态)一样。精度指定要写入的最大宽字符数。如果未指定精度,则写入直到但不包括第一个空终止符的所有宽字符。如果使用了l说明符,则参数必须是指向 wchar_t 数组的初始元素的指针。 |
N/A | N/A | char* |
wchar_t* |
N/A | N/A | N/A | N/A | N/A |
d i
|
精度指定要显示的最小位数。默认精度为 1。 |
signed char |
short |
int |
long |
long long |
signed size_t |
N/A | ||
o
|
精度指定要显示的最小位数。默认精度为 1。如果转换后的值和精度都为 0,则转换结果不会产生任何字符。在备用实现中,如果需要,精度会增加,以写入一个前导零。在这种情况下,如果转换后的值和精度都为 0,则会写入单个 0。 |
unsigned char |
unsigned short |
unsigned int |
unsigned long |
unsigned long long |
ptrdiff_t 的无符号版本 |
N/A | ||
x X
|
对于 `x` 转换,使用字母 `abcdef`。 |
N/A | ||||||||
u
|
精度指定要显示的最小位数。默认精度为 1。如果转换后的值和精度都为 0,则转换结果不会产生任何字符。 |
N/A | ||||||||
f F
|
精度指定小数点后要显示的确切位数。默认精度为 6。在备用实现中,即使没有数字跟随,也会写入小数点字符。有关无穷大和非数字转换风格,请参见说明。 |
N/A | N/A | double |
double(C99) |
N/A | N/A | N/A | N/A | long double |
e E
|
对于 `e` 转换风格,使用[-]d.ddd |
N/A | N/A | N/A | N/A | N/A | N/A | |||
a A
(C99) |
对于 `a` 转换风格,使用[-] |
N/A | N/A | N/A | N/A | N/A | N/A | |||
g G
|
对于 `g` 转换风格,将使用 `e` 或 `f` 风格进行转换。
除非请求备用表示,否则会删除尾随零,如果未保留小数部分,也会删除小数点字符。有关无穷大和非数字转换风格,请参见说明。 |
N/A | N/A | N/A | N/A | N/A | N/A | |||
n
|
结果写入指向参数的指针的值。规范不能包含任何标志、字段宽度或精度。 |
signed char* |
short* |
int* |
long* |
long long* |
signed size_t* |
N/A | ||
p
|
写入定义指针的实现定义的字符序列。 | N/A | N/A | void* | N/A | N/A | N/A | N/A | N/A | N/A |
浮点转换函数将无穷大转换为 `inf` 或 `infinity`。使用哪一个由实现定义。
非数字转换为 `nan` 或 `nan(char_sequence)`。使用哪一个由实现定义。
转换 `F`、`E`、`G`、`A` 输出 `INF`、`INFINITY`、`NAN`。
虽然 `%c` 预期 `int` 参数,但传递 `char` 是安全的,因为在调用可变参数函数时会进行整数提升。
固定宽度字符类型(int8_t 等)的正确转换规范在头文件 <inttypes.h>
中定义(虽然 PRIdMAX、PRIuMAX 等与 `%jd`、`%ju` 等同义)。
内存写入转换说明符 %n 是安全漏洞的常见目标,其中格式字符串依赖于用户输入,并且不受边界检查的 printf_s
函数系列支持。
每个转换说明符操作之后都有一个 顺序点;这允许将多个 %n 结果存储在同一个变量中,或者作为一种边缘情况,在同一个调用中打印由先前 %n 修改的字符串。
如果转换说明符无效,则行为未定义。
[编辑] 返回值
[编辑] 注释
虽然窄字符串提供 snprintf,这使得确定所需的输出缓冲区大小成为可能,但没有等效的宽字符串(直到 snwprintf_s
)(自 C11),为了确定缓冲区大小,程序可能需要调用 swprintf
,检查结果值,并重新分配一个更大的缓冲区,直到成功为止。
snwprintf_s
与 swprintf_s
不同,它会将结果截断以适合 buffer 指向的数组,即使大多数边界检查函数将截断视为错误。
[编辑] 示例
#include <locale.h> #include <wchar.h> int main(void) { char narrow_str[] = "z\u00df\u6c34\U0001f34c"; // or "zß水🍌" // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c"; wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator setlocale(LC_ALL, "en_US.utf8"); swprintf(warr, sizeof warr / sizeof* warr, L"Converted from UTF-8: '%s'", narrow_str); wprintf(L"%ls\n", warr); }
输出
Converted from UTF-8: 'zß水🍌'
[编辑] 参考文献
- C23 标准 (ISO/IEC 9899:2024)
- 7.29.2.1 fwprintf 函数 (p: TBD)
- 7.29.2.3 swprintf 函数 (p: TBD)
- 7.29.2.11 wprintf 函数 (p: TBD)
- K.3.9.1.1 fwprintf_s 函数 (p: TBD)
- K.3.9.1.4 swprintf_s 函数 (p: TBD)
- K.3.9.1.13 wprintf_s 函数 (p: TBD)
- C17 标准 (ISO/IEC 9899:2018)
- 7.29.2.1 fwprintf 函数 (p: TBD)
- 7.29.2.3 swprintf 函数 (p: TBD)
- 7.29.2.11 wprintf 函数 (p: TBD)
- K.3.9.1.1 fwprintf_s 函数 (p: TBD)
- K.3.9.1.4 swprintf_s 函数 (p: TBD)
- K.3.9.1.13 wprintf_s 函数 (p: TBD)
- C11 标准 (ISO/IEC 9899:2011)
- 7.29.2.1 fwprintf 函数 (p: 403-410)
- 7.29.2.3 swprintf 函数 (p: 416)
- 7.29.2.11 wprintf 函数 (p: 421)
- K.3.9.1.1 fwprintf_s 函数 (p: 628)
- K.3.9.1.4 swprintf_s 函数 (p: 630-631)
- K.3.9.1.13 wprintf_s 函数 (p: 637-638)
- C99 标准 (ISO/IEC 9899:1999)
- 7.24.2.1 fwprintf 函数 (p: 349-356)
- 7.24.2.3 swprintf 函数 (p: 362)
- 7.24.2.11 wprintf 函数 (p: 366)
[编辑] 另请参见
(C99)(C11)(C11)(C11)(C11) |
将格式化的输出打印到 stdout、文件流或缓冲区 (函数) |
(C95)(C95)(C95)(C11)(C11)(C11)(C11) |
将格式化的宽字符输出打印到 stdout、文件流 或使用可变参数列表的缓冲区 (函数) |
(C95) |
将宽字符串写入文件流 (函数) |
C++ 文档 for wprintf, fwprintf, swprintf
|