fwprintf (File input/output) – C 中文开发手册
fwprintf (File input/output) - C 中文开发手册
| Defined in header <wchar.h> | ||
|---|---|---|
| (1) | ||
| int wprintf( const wchar_t *format, ... ); | (since C95) (until C99) | |
| int wprintf( const wchar_t *restrict format, ... ); | (since C99) | |
| (2) | ||
| int fwprintf( FILE *stream, const wchar_t* format, ... ); | (since C95) (until C99) | |
| int fwprintf( FILE *restrict stream, const wchar_t *restrict format, ... ); |
(since C99) | |
| (3) | ||
| int swprintf( wchar_t *buffer, size_t bufsz, const wchar_t* format, ... ); |
(since C95) (until C99) | |
| int swprintf( wchar_t *restrict buffer, size_t bufsz, const wchar_t *restrict format, ... ); |
(since C99) | |
| int wprintf_s( const wchar_t *restrict format, ...); | (4) | (since C11) |
| int fwprintf_s( FILE *restrict stream, const wchar_t *restrict format, ...); |
(5) | (since C11) |
| int swprintf_s( wchar_t *restrict buffer, rsize_t bufsz, const wchar_t* restrict format, ...); |
(6) | (since C11) |
| int snwprintf_s( wchar_t * restrict s, rsize_t n, const wchar_t * restrict format, ...); |
(7) | (since C11) |
从给定的位置加载数据，将它们转换为宽字符串等值并将结果写入各种接收器。1）将结果写入stdout。2）将结果写入文件流stream。3）如果bufsz大于零，则将结果写入宽字符串buffer。最bufsz-1宽字符后面跟着空宽字符。如果bufsz为零，则不会写入任何内容（并且buffer可能是空指针），但返回值（将写入的宽字符数）仍然会计算并返回。 4-6）与（1-3）相同，但在运行时检测到以下错误并调用当前安装的约束处理函数： 转换说明符%n存在于format 任何对应的参数%s都是空指针format或者buffer是空指针bufsz 是零或大于 RSIZE_MAX/sizeof(wchar_t) 编码错误出现在任何字符串和字符转换说明符中 （仅限于swprintf_s）要写入的宽字符数（包括null）将超过bufsz。7）与（6）相同，只是它会截断结果以适应s所指向的数组。由于所有的边界检查功能，wprintf_s，wfprintf_s，和wsprintf_s仅保证可供如果__STDC_LIB_EXT1__由实现所定义，并且如果用户定义__STDC_WANT_LIB_EXT1__的整数常数1，包括之前<stdio.h>。
参数
| 流 | - | 输出文件流写入 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| 缓冲 | - | 指向要写入的宽字符字符串的指针 | ||||||||
| bufsz | - | 最多bufsz-1可以编写宽字符，加上空终止符 | ||||||||
| 格式 | - | 指向以空字符结尾的宽字符串的指针，指定如何解释数据。 | ||||||||
| 格式字符串由普通的宽字符（除外%）组成，它们被不变地复制到输出流和转换规范中。每个转换规范具有以下格式： | ||||||||||
| 介绍%人物 | ||||||||||
| （可选）一个或多个修改转换行为的标志： | ||||||||||
| -：转换的结果在字段内左对齐（默认情况下它是右对齐的） | ||||||||||
| +：带符号转换的符号总是预设为转换结果的前缀（默认情况下结果前面为减号，仅当它为负值时） | ||||||||||
| 空格：如果签名转换的结果不是以符号字符开头，或者是空的，则空格会预设为结果。如果+标志存在，它将被忽略。 | ||||||||||
| #：执行转换的替代形式。请参阅下表以了解确切的效果，否则行为未定义。 | ||||||||||
| 0：对于整数和浮点数转换，前导零用于填充字段而不是空格字符。对于整数，如果明确指定了精度，它将被忽略。对于使用此标志的其他转换会导致未定义的行为。如果-标志存在，它将被忽略。 | ||||||||||
| （可选）整数值或*指定最小字段宽度。如果需要，结果会填充空格字符（默认情况下），右侧对齐时填充空白字符，左侧填充右侧填充。在使用的情况下*，宽度由类型的附加参数指定int。如果参数的值是负数，则结果是-指定的标志和正的字段宽度。（注意：这是最小宽度：该值从不被截断。） | ||||||||||
| （可选） .后面跟随整数或者*或者既不指定转换的精度。在使用的情况下*，精度由类型的附加参数指定int。如果这个参数的值是负数，它将被忽略。如果既不使用数字也不*使用，则精度取为零。请参阅下表以了解精确度的确切影响。 | ||||||||||
| （可选） 长度修饰符，用于指定参数的大小 | ||||||||||
| 转换格式说明符 | ||||||||||
| 以下格式说明符可用： | ||||||||||
| 转换 | 说明 | 参数类型 | ||||||||
| 说明符 | ||||||||||
| 长度修饰符 | hh | h | （没有） | l | ll | j | z | t | L | |
| （C99）。 | （C99）。 | （C99）。 | （C99）。 | （C99）。 | ||||||
| % | 写文字%。完整的转换规范必须是%%。 | N / A | N / A | N / A | N / A | N / A | N / A | N / A | N / A | N / A |
| c | 写一个字符。 | N / A | N / A | int | wint_t | N / A | N / A | N / A | N / A | N / A |
| 参数首先被转换wchar_t为仿佛通过调用btowc。如果使用l修饰符，wint_t则首先将参数转换为wchar_t。 | ||||||||||
| s | 写入一个字符串 | N / A | N / A | char* | wchar_t* | N / A | N / A | N / A | N / A | N / A |
| 参数必须是一个指向包含从初始转换状态开始的多字节字符序列的字符数组的初始元素的指针，该数组转换为宽字符数组，就像通过调用mbrtowc具有零初始化转换状态一样。Precision指定要写入的最大宽字符数。如果未指定Precision，则将每个宽字符写入并不包括第一个空终止符。如果使用l说明符，参数必须是指向数组的初始元素的指针wchar_t。 | ||||||||||
| d | 将有符号整数转换为十进制表示形式[ - ] dddd。 | signed char | short | int | long | long long | intmax_t | 签 size_t | ptrdiff_t | N / A |
| i | 精度指定出现的最小位数。默认的精度是1。 | |||||||||
| 如果转换后的值和精度都是0没有字符的转换结果。 | ||||||||||
| o | 将无符号整数转换为八进制表示oooo。 | unsigned char | unsigned short | unsigned int | unsigned long | unsigned long long | uintmax_t | size_t | 未签名的版本 ptrdiff_t | N / A |
| 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。在替代实现中，如果需要，可以增加精度以写入一个前导零。在这种情况下，如果转换后的值和精度都是0，0写入单个。 | ||||||||||
| x | 将无符号整数转换为十六进制表示hhhh。 | N / A | ||||||||
| X | 使用x转换字母abcdef。 | |||||||||
| 使用X转换字母ABCDEF。 | ||||||||||
| 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。在替代实现中， 0x或者0X如果转换后的值不为零，则将其作为结果的前缀。 | ||||||||||
| u | 将无符号整数转换为十进制表示形式dddd。 | N / A | ||||||||
| 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。 | ||||||||||
| f | 将浮点数转换为样式[ - ] ddd.ddd中的十进制表示法。 | N / A | N / A | double | double（C99） | N / A | N / A | N / A | N / A | long double |
| F | 精度指定小数点后面出现的最小位数。默认的精度是6。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 | |||||||||
| e | 将浮点数转换为十进制指数符号。 | N / A | N / A | N / A | N / A | N / A | N / A | |||
| E | 对于e转换样式，使用[ - ] d.ddd e±dd。 | |||||||||
| 对于E转换样式，使用[ - ] d.ddd E±dd。 | ||||||||||
| 指数至少包含两位数字，只有在必要时才使用更多数字。如果值是0，指数也是0。精度指定小数点后面出现的最小位数。默认的精度是6。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 | ||||||||||
| a | 将浮点数转换为十六进制指数表示法。 | N / A | N / A | N / A | N / A | N / A | N / A | |||
| A | 对于a转换样式，使用[ - ] 0xh.hhh p±d。 | |||||||||
| （C99）。 | 对于A转换样式，使用[ - ] 0Xh.hhh P±d。如果参数不是标准化的浮点值，则 | |||||||||
| 第一个十六进制数字是0。如果值是0，指数也是0。精度指定小数点后面出现的最小位数。默认精度足以精确表示值。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 | ||||||||||
| g | 根据值和精度将浮点数转换为十进制或十进制指数符号。 | N / A | N / A | N / A | N / A | N / A | N / A | |||
| G | 对于g风格转换的转换与风格e或f将被执行。 | |||||||||
| 对于G风格转换的转换与风格E或F将被执行。 | ||||||||||
| 让P等于精度如果非零，6如果没有指定精度，或者1如果精度是0。然后，如果具有样式的转换E将具有以下指数X： | ||||||||||
| 如果P> X≥-4，转换是用式f或F和精度P - 1 - X。 | ||||||||||
| 否则，转换采用样式e或E精度P - 1。 | ||||||||||
| 除非请求替代表示，否则尾随零将被删除，如果没有剩余小数部分，小数点字符也会被删除。对于无穷大和非数字转换风格，请参阅注释。 | ||||||||||
| n | 将此调用到目前为止写入的字符数返回给该函数。 | signed char* | short* | int* | long* | long long* | intmax_t* | 签 size_t* | ptrdiff_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在相同的调用中打印由较早修改的字符串。 | ||||||||||
| 如果转换规范无效，则行为未定义。 | ||||||||||
| ... | - | 指定要打印的数据的参数 |
介绍%人物（可选）一个或多个修改转换行为的标志： -：转换的结果在字段内左对齐（默认情况下它是右对齐的） +：带符号转换的符号总是预设为转换结果的前缀（默认情况下结果前面为减号，仅当它为负值时） 空格：如果签名转换的结果不是以符号字符开头，或者是空的，则空格会预设为结果。如果+存在标志，则忽略它。#：执行转换的替代形式。请参阅下表以了解确切的效果，否则行为未定义。0：对于整数和浮点数转换，前导零用于填充字段而不是空格字符。对于整数，如果明确指定了精度，它将被忽略。对于使用此标志的其他转换会导致未定义的行为。如果-存在标志，则忽略它。（可选）整数值或*指定最小字段宽度。如果需要，结果会填充空格字符（默认情况下），右侧对齐时填充空白字符，左侧填充右侧填充。在使用的情况下*，宽度由类型的附加参数指定int。如果参数的值是负数，则结果是-指定的标志和正的字段宽度。（注意：这是最小宽度：该值从不被截断。）（可选）.后面跟随整数或者*或者既不指定转换的精度。在使用的情况下*，精度由类型的附加参数指定int。如果这个参数的值是负数，它将被忽略。如果既不使用数字也不*使用，则精度取为零。请参阅下表以了解精确度的确切影响。（可选）长度修饰符，用于指定参数的大小转换格式说明符 以下格式说明符可用：
Conversion
说明符说明参数类型长度修饰符 hh（C99）。 h (none) l ll (C99). j (C99). z (C99). t (C99). L % 写文字%。完整的转换规范必须是%%。N / AN / AN / AN / AN / AN / AN / AN / AN / A c 写入单个字符。参数首先被转换wchar_t为仿佛通过调用btowc。如果使用l修饰符，wint_t则首先将参数转换为wchar_t。 N/A N/A int wint_t N / AN / AN / AN / AN / A s 写入字符串参数必须是一个指向字符数组初始元素的指针，该字符数组包含一个多字节字符序列，从初始移位状态开始，转换为宽字符数组，如同通过调用mbrtowc具有零初始化转换状态。Precision指定要写入的最大宽字符数。如果未指定Precision，则将每个宽字符写入并不包括第一个空终止符。如果使用l说明符，参数必须是指向数组的初始元素的指针wchar_t。 N/A N/A char* wchar_t* N/A N/A N/A N/A N/A d i 将有符号的整数转换为十进制表示形式-dddd。 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。 signed char short int long long long intmax_t signed size_t ptrdiff_t N / A o 将无符号整数转换为八进制表示oooo。 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。在替代实现中，如果需要，可以增加精度以写入一个前导零。在这种情况下，如果转换值和精度都是0，0写入单个。 unsigned char unsigned short unsigned int unsigned long unsigned long long uintmax_t size_t 未签名的版本 ptrdiff_t N/A x X 将无符号整数转换为十六进制表示hhhh。使用x转换字母abcdef。使用X转换字母ABCDEF。 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。在替代实现中， 0x或者0X如果转换后的值不为零，则将其作为结果的前缀。 N / A u 将无符号整数转换为十进制表示形式dddd。 精度指定出现的最小位数。默认的精度是1。如果转换后的值和精度都是0没有字符的转换结果。 N/A f F 将浮点数转换为样式-ddd.ddd中的小数表示法。 精度指定小数点后面出现的最小位数。默认的精度是6。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 N/A N/A double
`double` (C99)
N/A N/A N/A N/A long double
`e`
E 将浮点数转换为十进制指数符号。对于e转换样式，使用-d.ddd e±dd。对于E转换样式，使用-d.ddd E±dd。指数至少包含两位数字，只有在必要时才使用更多数字。如果值是0，指数也是0。精度指定小数点后面出现的最小位数。默认的精度是6。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 N/A N/A N/A N/A N/A N/A a A (C99). 将浮点数转换为十六进制指数表示法。对于a转换样式- 使用0xh.hhh p±d。对于A转换样式- 使用0Xh.hhh P±d。0如果参数不是标准化的浮点值，则第一个十六进制数字是。如果值是0，指数也是0。精度指定小数点后面出现的最小位数。默认精度足以精确表示值。在替代实现中，即使没有数字跟随，小数点字符也会被写入。对于无穷大和非数字转换风格，请参阅注释。 N/A N/A N/A N/A N/A N/A g G根据值和精度 将浮点数转换为十进制或十进制指数符号。对于风格转换的转换与风格或将被执行。gef对于G风格转换的转换与风格E或F将被执行。让P等于精度如果非零，6如果没有指定精度，或者1如果精度是0。然后，如果具有样式的转换E将具有以下指数X：如果P> X≥-4，转换是用式f或F和精度P - 1 - X。否则，转换采用样式e或E精度P - 1。除非请求替代表示，否则尾随零将被删除，如果没有剩余小数部分，小数点字符也会被删除。对于无穷大和非数字转换风格，请参阅注释。 不适用/不适用/不适用/不适用/ n 返回此函数迄今为止写入的字符数。结果写入参数指向的值。规范可能不包含任何标志，字段宽度或精度。 signed char* short* int* long* long long* intmax_t* signed size_t* ptrdiff_t* N / A p 写入一个实现定义的字符序列来定义一个指针。不适用不适用不适用不适用不适用不适用 void* 浮点转换函数将无穷大转换为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在同一个调用中打印由较早修改的字符串。 如果转换规范无效，则行为未定义。
... - arguments specifying data to print
返回值
1,2）如果发生错误，则成功写入宽字符数或写入负值。3）如果编码错误发生或者如果要生成的字符数等于或大于size（包括当size为零时），则写入的宽字符的数目（不包括终止空宽字符）如果成功或负值。 4,5）如果发生错误，则成功写入宽字符数或写入负值。6）写入的宽字符数（不包括终止空值）buffer。返回编码错误和溢出时的负值。对所有其他错误返回零。7）的，将已经写入宽字符（不包括终止空）数量buffer已经bufsz如果发生错误，已经足够大时，或为负值。（也就是说，只有当回报是非负的且小于时，写才能成功并且完成bufsz）
注意
虽然窄字符串提供snprintf了可以确定所需的输出缓冲区大小的可能性，但对于宽字符串没有等效（直到C11的snwprintf_s），并且为了确定缓冲区大小，程序可能需要调用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ß水?'
参考
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）
C 语言中文开发手册
