C参考手册
文件输入/输出 | File input/output
vfwprintf
在标题中定义 <wchar.h> | |
---|---|
int vwprintf( const wchar_t *format, va_list vlist ); |
(since C95) |
int vwprintf( const wchar_t *restrict format, va_list vlist ); |
(until C99) |
int vfwprintf( FILE* stream, const wchar_t *format, va_list vlist ); |
(since C99) |
int vfwprintf( FILE *restrict stream, const wchar_t *restrict format, va_list vlist ); |
(since C95) (until C99) |
int vswprintf( wchar_t *buffer, size_t bufsz, const wchar_t *format, va_list vlist ); |
(since C99) |
int vswprintf( wchar_t *restrict buffer, size_t bufsz, const wchar_t *restrict format, va_list vlist ); |
(since C95) (until C99) |
int vwprintf_s( const wchar_t *restrict format, va_list vlist); |
(since C99) |
int vfwprintf_s( FILE * restrict stream, const wchar_t *restrict format, va_list vlist); |
(since C11) |
int vswprintf_s( wchar_t *restrict buffer, rsize_t bufsz, const wchar_t * restrict format, va_list vlist); |
(since C11) |
int vsnwprintf_s( wchar_t *restrict buffer, rsize_t bufsz, const wchar_t *restrict format, va_list vlist); |
(since C11) |
加载来自定义位置的数据vlist
,将它们转换为宽字符串,并将结果写入各种接收器。
1)将结果写入stdout
。
2)将结果写入文件流stream
。
3)将结果写入一个宽字符串buffer
。最bufsz-1
宽字符后面跟着空宽字符。生成的宽字符串将以空宽字符结尾,除非bufsz
为零。
4-7)与(1-3)相同,只是在运行时检测到以下错误并调用当前安装的约束处理函数:
- 转换说明符
%n
存在于format
- 任何对应的参数
%s
都是空指针 -
format
或者buffer
是空指针 -
bufsz
是零或大于RSIZE_MAX/sizeof(wchar_t)
- 编码错误出现在任何字符串和字符转换说明符中
- (
vswprintf_s
仅限于),要存储的字符串buffer
(包括后面的宽空)将会超过bufsz
8)与(7)相同,除了它会截断结果以适应s所指向的数组。由于所有的边界检查功能,vwprintf_s
,vfwprintf_s
,vswprintf_s
,和vsnwprintf_s
仅保证可供如果__STDC_LIB_EXT1__
由实现所定义,并且如果用户定义__STDC_WANT_LIB_EXT1__
的整数常数1
,包括之前<wchar.h>
。
参数
参数
流 |
- |
输出宽流写入 |
---|---|---|
缓冲 |
- |
指向要写入的宽字符串的指针 |
bufsz |
- |
要写入的最大宽字符数 |
格式 |
- |
指向以空字符结尾的宽字符串的指针,指定如何解释数据。格式字符串由普通的宽字符(除外%)组成,它们被不变地复制到输出流和转换规范中。每个转换规范具有以下格式:介绍%人物(可选)一个或多个修改转换行为的标志:-:转换的结果在字段内左对齐(默认情况下它是右对齐的)+:带符号转换的符号总是预设为转换结果的前缀(默认情况下结果前面为减号,仅当它为负值时)空格:如果签名转换的结果不是以符号字符开头,或者是空的,则空格会预设为结果。如果+标志存在,它将被忽略。# :执行转换的替代形式。请参阅下表以了解确切的效果,否则行为未定义。0 :对于整数和浮点数转换,前导零用于填充字段而不是空格字符。对于整数,如果明确指定了精度,它将被忽略。对于使用此标志的其他转换会导致未定义的行为。如果-标志存在,它将被忽略。(可选)整数值或*指定最小字段宽度。如果需要,结果会填充空格字符(默认情况下),右侧对齐时填充空白字符,左侧填充右侧填充。在使用的情况下*,宽度由类型为int的附加参数指定。如果参数的值是负数,则结果是-指定的标志和正的字段宽度。(注意:这是最小宽度:该值从不被截断。)(可选) .后面跟随整数或者*或者既不指定转换的精度。在使用的情况下*,精度由类型为int的附加参数指定。如果这个参数的值是负数,它将被忽略。如果既不使用数字也不*使用,则精度取为零。请参阅下表以了解精确度的确切影响。(可选) 长度修饰符,用于指定参数的大小转换格式说明符以下格式说明符可用: |
- introductory
%
character - (可选)一个或多个修改转换行为的标志:
-
-
:转换的结果在字段内左对齐(默认情况下它是右对齐的) -
+
:带符号转换的符号总是预设为转换结果的前缀(默认情况下结果前面为减号,仅当它为负值时) -
空格:如果签名转换的结果不是以符号字符开头,或者是空的,则空格会预设为结果。如果
+
标志存在,它将被忽略。 -
#
:执行转换的替代形式。请参阅下表以了解确切的效果,否则行为未定义。 -
0
:对于整数和浮点数转换,前导零用于填充字段而不是空格字符。对于整数,如果明确指定了精度,它将被忽略。对于使用此标志的其他转换会导致未定义的行为。如果-
标志存在,它将被忽略。 - (可选)整数值或
*
指定最小字段宽度。如果需要,结果会填充空格字符(默认情况下),右侧对齐时填充空白字符,左侧填充右侧填充。在使用的情况下*
,宽度由类型为int的附加参数指定。如果参数的值是负数,则结果是-
指定的标志和正的字段宽度。(注意:这是最小宽度:该值从不被截断。) - (可选)
.
后面跟随整数或者*
或者既不指定转换的精度。在使用的情况下*
,精度由类型为int的附加参数指定。如果这个参数的值是负数,它将被忽略。如果既不使用数字也不*
使用,则精度取为零。请参阅下表以了解精确度的确切影响。 - (可选) 长度修饰符,用于指定参数的大小
- 转换格式说明符
以下格式说明符可用:
转换说明符 |
说明 |
参数类型 |
||||||||
---|---|---|---|---|---|---|---|---|---|---|
长度修饰符 |
hh(C99) |
h |
(none) |
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 |
写一个字符。 |
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数组的初始元素的指针。 | ||||||||||
di |
将有符号整数转换为十进制表示形式[ - ] dddd。 |
签名 字符 |
短 |
INT |
长 |
久 长 |
还会将intmax_t |
签名size_t |
ptrdiff_t的 |
N / A |
精度指定出现的最小位数。默认精度为1。 | ||||||||||
如果这两个转换值和精度是0在没有字符转换结果。 | ||||||||||
o |
将无符号整数转换为八进制表示oooo。 |
无符号 字符 |
无符号 短 |
无符号 整数 |
无符号 长整数 |
无符号 long long |
uintmax_t型 |
为size_t |
未签名的ptrdiff_t版本 |
N / A |
精度指定出现的最小位数。默认精度为1。如果这两个转换值和精度是0在没有字符转换结果。在替代实现中,如果需要,可以增加精度以写入一个前导零。在这种情况下,如果两个转换值和精度是0,单个0被写入。 | ||||||||||
xX |
将无符号整数转换为十六进制表示hhhh。 |
N / A |
||||||||
使用x转换字母abcdef。 | ||||||||||
使用X转换字母ABCDEF。 | ||||||||||
精度指定出现的最小位数。默认精度为1。如果这两个转换值和精度是0在没有字符转换结果。在替代实现中,或者如果转换后的值不为零,则将其作为结果的前缀。 0x0X | ||||||||||
u |
将无符号整数转换为十进制表示形式dddd。 |
N / A |
||||||||
精度指定出现的最小位数。默认精度为1。如果这两个转换值和精度是0在没有字符转换结果。 | ||||||||||
f F |
将浮点数转换为样式[ - ] ddd.ddd中的十进制表示法。 |
N / A |
N / A |
双 |
双 (C99) |
N / A |
N / A |
N / A |
N / A |
长 双 |
精度指定小数点后面出现的最小位数。默认精度为6。在替代实现中,即使没有数字跟随,小数点字符也会被写入。对于无穷大和非数字转换风格,请参阅注释。 | ||||||||||
e E |
将浮点数转换为十进制指数符号。 |
N / A |
N / A |
N / A |
N / A |
N / A |
N / A |
|||
对于e转换样式,使用[ - ] d.ddd e±dd。 | ||||||||||
对于E转换样式,使用[ - ] d.ddd E±dd。 | ||||||||||
指数至少包含两位数字,只有在必要时才使用更多数字。如果该值为0,指数是也0。 精度指定小数点后面出现的最小位数。默认精度为6。在替代实现中,即使没有数字跟随,小数点字符也会被写入。对于无穷大和非数字转换风格,请参阅注释。 | ||||||||||
a A (C99) |
将浮点数转换为十六进制指数表示法。 |
N / A |
N / A |
N / A |
N / A |
N / A |
N / A |
|||
对于a转换样式,使用[ - ] 0xh.hhh p±d。 | ||||||||||
对于A转换样式,使用[ - ] 0Xh.hhh P±d。如果参数不是标准化的浮点值,则 | ||||||||||
第一个十六进制数字是0。如果该值为0,指数是也0。 精度指定小数点后面出现的最小位数。默认精度足以精确表示值。在替代实施中即使没有数字跟随,小数点字符也会被写入。对于无穷大和非数字转换风格,请参阅注释。 |
||||||||||
g G |
根据值和精度将浮点数转换为十进制或十进制指数符号。 |
N / A |
N / A |
N / A |
N / A |
N / A |
N / A |
|||
对于g风格转换的转换与风格e或f将被执行。 | ||||||||||
对于G风格转换的转换与风格E或F将被执行。 | ||||||||||
让P等于如果非零,精度6如果精度没有指定,或1,如果精度为0。然后,如果具有样式的转换将具有以下指数: EX | ||||||||||
如果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 |
写一个实现定义的字符序列来定义一个指针。 |
N/A |
N/A |
void * |
N/A |
N/A |
N/A |
N/A |
N/A |
N/A |
返回值
1-3)如果发生错误,则成功写入宽字符数或写入宽字符数。
4)如果发生错误,则成功写入宽字符数或写入宽字符数。如果由于bufsz
限制而导致结果字符串被截断,则函数将返回如果未强加限制,则会写入的字符总数(不包括终止空宽字符)。
5,6)传输到输出流的宽字符数,如果发生输出错误,运行时约束违规错误或编码错误,则输出负值。
7)写入的宽字符数buffer
,不包括空宽字符(只要buffer
不是空指针,bufsz
且不为零且不大于RSIZE_MAX/sizeof(wchar_t)
),则为空宽字符,或者在运行时约束违规时为零,并且编码为负值错误
8)不包括终止空字符的宽字符数(只要buffer
不是空指针bufsz
且不为零且不大于RSIZE_MAX/sizeof(wchar_t)
),buffer
如果bufsz
被忽略,则写入的宽字符数或负值if发生运行时约束违规或编码错误
注意
所有这些函数va_arg
至少调用一次,arg
返回后的值是不确定的。这些函数不会调用va_end
,并且它必须由调用者完成。
虽然窄字符串提供了vsnprintf
,这使得可以确定所需的输出缓冲区大小,但对于宽字符串没有等效(直到C11的vsnwprintf_s),并且为了确定缓冲区大小,程序可能需要调用vswprintf
,检查结果值,并重新分配一个更大的缓冲区,再次尝试直到成功。
vsnwprintf_s
不同vswprintf_s
,将截断结果以适应指向的数组buffer
,即使截断被大多数边界检查函数视为错误。
例
#include <stdio.h>
#include <time.h>
#include <locale.h>
void debug_wlog(const wchar_t *fmt, ...)
{
struct timespec ts;
timespec_get(&ts, TIME_UTC);
char time_buf[100];
size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
va_list args;
va_start(args, fmt);
wchar_t buf[1000];
int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
va_end(args);
if(rc2 > 0)
wprintf(L"%s [debug]: %ls\n", time_buf, buf);
else
wprintf(L"%s [debug]: (string too long)\n", time_buf);
}
int main(void)
{
setlocale(LC_ALL, "");
debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
}
可能的输出:
02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3