Namespaces
Variants

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
vprintf vfprintf vsprintf vsnprintf vprintf_s vfprintf_s vsprintf_s vsnprintf_s
(C99) (C11) (C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
定义于头文件 <stdio.h>
(1)
int vprintf ( const char * format, va_list vlist ) ;
(C99前)
int vprintf ( const char * restrict format, va_list vlist ) ;
(C99起)
(2)
int vfprintf ( FILE * stream, const char * format, va_list vlist ) ;
(C99前)
int vfprintf ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(C99起)
(3)
int vsprintf ( char * buffer, const char * format, va_list vlist ) ;
(C99前)
int vsprintf ( char * restrict buffer, const char * restrict format,
va_list vlist ) ;
(C99起)
int vsnprintf ( char * restrict buffer, size_t bufsz,
const char * restrict format, va_list vlist ) ;
(4) (C99起)
int vprintf_s ( const char * restrict format, va_list vlist ) ;
(5) (C11起)
int vfprintf_s ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(6) (C11起)
int vsprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(7) (C11起)
int vsnprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(8) (C11起)

从由 vlist 定义的内存位置加载数据，将其转换为等效的字符串形式，并将结果写入多种输出目标。

1) 将结果写入 stdout 。
2) 将结果写入文件流 stream 。
3) 将结果写入字符字符串 buffer 中。
4) 将结果写入字符字符串 buffer 中。最多写入 bufsz - 1 个字符。生成的字符字符串将以空字符结尾，除非 bufsz 为零。如果 bufsz 为零，则不会写入任何内容，且 buffer 可为空指针，但返回值（不包含空终止符的待写入字节数）仍会被计算并返回。
5-8) 与 (1-4) 相同，但以下错误会在运行时被检测到，并调用当前安装的 constraint handler 函数：
  • 转换说明符 %n 出现在 format 中
  • 任何对应于 %s 的参数是空指针
  • format 或 buffer 是空指针
  • bufsz 为零或大于 RSIZE_MAX
  • 在任何字符串和字符转换说明符中出现编码错误
  • （仅适用于 vsprintf_s ），要存储到 buffer 中的字符串（包括结尾的空字符）将超过 bufsz
与所有边界检查函数一样， vprintf_s 、 vfprintf_s 、 vsprintf_s 和 vsnprintf_s 仅在实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时才保证可用。

目录

参数

stream - 要写入的输出文件流
buffer - 要写入的字符串指针
bufsz - 最多可写入 bufsz - 1 个字符，外加空终止符
format - 指定数据解析方式的空终止字符串指针
vlist - 包含要打印数据的可变参数列表

格式字符串由普通字节字符（除 % 外）和转换说明组成。普通字节字符会原样复制到输出流中。每个转换说明具有以下格式：

  • 引导性的 % 字符。
  • （可选） 一个或多个用于修改转换行为的标志：
  • - ：转换结果在字段内左对齐（默认为右对齐）。
  • + ：有符号转换的符号始终预置于转换结果前（默认仅当结果为负数时前置减号）。
  • space ：若有符号转换结果不以符号字符开头或为空时，将在结果前添加空格。若存在 + 标志则此标志被忽略。
  • # ：执行转换的 替代形式 。具体效果参见下表，否则行为未定义。
  • 0 ：对于整数和浮点数转换，使用前导零而非 space 字符填充字段。对于整数，若显式指定精度则此标志被忽略。其他转换使用此标志将导致未定义行为。若存在 - 标志则此标志被忽略。
  • （可选） 整数值或 * 用于指定最小字段宽度。当需要时，默认会在右侧对齐时左侧填充 空格 字符，或在左侧对齐时右侧填充。若使用 * 时，宽度由 int 类型的附加参数指定，该参数出现在待转换参数之前（如果提供了精度参数，则出现在精度参数之前）。若参数值为负数，将导致指定 - 标志并采用正数字段宽度（注意：此为最小宽度：值永远不会被截断）。
  • （可选） . 后接整数或 * ，或两者皆无，用于指定转换的 精度 。当使用 * 时，精度由 int 类型的附加参数指定，该参数出现在待转换参数之前，但如果提供了最小字段宽度参数，则出现在该参数之后。若此参数值为负数，则被忽略。若未使用数字或 * ，则精度默认为零。具体精度效果请参阅下表。
  • （可选） 长度修饰符 用于指定参数的大小（与转换格式说明符结合使用时，可指定对应参数的类型）。
  • 转换格式说明符。

以下格式说明符可用：

转换
说明符 		说明 期望
参数类型
长度修饰符→ hh h 无 l ll j z t L
仅自C99起可用→ 是 是 是 是 是
% 输出字面量 % 。完整转换规范必须为 %% 。 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用
c

写入 单个字符 。

  • 参数首先被转换为 unsigned char 。
  • 如果使用 l 修饰符，参数首先会被转换为字符字符串，转换方式类似于使用 %ls 配合 wchar_t [ 2 ] 参数。
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

写入 字符串 。

  • 参数必须是指向字符数组首元素的指针。
  • 精度 指定要写入的最大字节数。若未指定 精度 ，则写入直至首个空终止符（不包含该终止符）的所有字节。
  • 若使用 l 限定符，则参数必须是指向 wchar_t 数组首元素的指针，该数组会通过调用 wcrtomb （使用零初始化的转换状态）转换为字符数组。
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

将 有符号整数 转换为十进制表示形式 [-]dddd 。

  • 精度 指定要显示的最小数字位数。默认精度为 1 。
  • 如果转换后的值和精度均为 ​ 0 ​ ，则转换结果不产生任何字符。
  • 对于 z 修饰符，期望的参数类型是 size_t 的有符号版本。
signed char
short
int
long
long long
※
不适用
o

将 无符号整数 转换为八进制表示形式 oooo 。

  • 精度 指定要显示的最小数字位数。默认精度为 1 。
  • 如果转换后的值和精度均为 ​ 0 ​ ，则转换结果不产生任何字符。
  • 在 替代实现 中，如需写入一个前导零，则会增加精度。在这种情况下，如果转换后的值和精度均为 ​ 0 ​ ，则会写入单个 ​ 0 ​ 。
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
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 (C99)

将 浮点数 转换为 [-]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 转换样式，使用 [-]  0x h.hhh  p ±d 格式。
  • 对于 A 转换样式，使用 [-]  0X h.hhh  P ±d 格式。
  • 如果参数是规范化浮点数值，则第一个十六进制数字不为 0 。
  • 如果值为 ​ 0 ​ ，则指数也为 ​ 0 ​ 。
  • 精度 指定十六进制小数点后应显示的确切位数。
  • 默认精度足以精确表示该值。
  • 在 替代实现 中，即使后面没有数字也会写入十进制小数点字符。
  • 关于无穷大和非数值的转换样式，请参阅 注释 。
N/A N/A N/A N/A N/A N/A
g
G

将 浮点数 根据值和 精度 转换为十进制或十进制指数表示法。

  • 对于 g 转换样式，将使用 e 或 f 样式进行转换。
  • 对于 G 转换样式，将使用 E 或 f (C99前) F (C99起) 样式进行转换。
  • 令 P 等于精度（若精度非零）、未指定精度时为 6 、或精度为 ​ 0 ​ 时为 1 。若使用 E 样式转换的指数为 X ：
    • 若 P > X ≥ −4 ，则使用 f 或 F (C99起) 样式转换，精度为 P − 1 − X 。
    • 否则使用 e 或 E 样式转换，精度为 P − 1 。
  • 除非要求 替代表示 ，否则将删除尾随零，且若无小数部分则同时删除小数点字符。
  • 无穷大和非数字的转换样式参见 注释 。
N/A N/A N/A N/A N/A N/A
n

返回此函数调用 目前已写入的字符数 。

  • 结果将 写入 到参数所指向的值中。
  • 格式说明符不得包含任何 标志 、 字段宽度 或 精度 。
  • 对于 z 修饰符，预期参数类型为 S * ，其中 S 是 size_t 的有符号版本。
signed char *
short *
int *
long *
long long *
※
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 代替。

用于打印 char 、 unsigned char 、 signed char 、 short 和 unsigned short 的转换说明符期望接收 默认参数提升 后的类型，但在打印前其值会被转换回 char 、 unsigned char 、 signed char 、 short 和 unsigned short 。由于可变参数函数调用时会发生提升，传递这些类型的值是安全的。

固定宽度字符类型（ int8_t 等）的正确转换规范定义在头文件 <inttypes.h> 中（尽管 PRIdMAX 、 PRIuMAX 等分别等同于 %jd 、 %ju 等）。

内存写入转换说明符 %n 常成为安全漏洞的攻击目标，特别是当格式字符串依赖于用户输入时 ，且不受边界检查函数族 printf_s 支持 （自C11起） 。

每个转换说明符执行后存在一个 序列点 ；这允许将多个 %n 结果存储到同一变量中，或在极端情况下，在同一调用中打印被先前 %n 修改的字符串。

如果转换规范无效，则行为未定义。

返回值

1-3) 成功时写入的字符数，若出现错误则为负值。
4) 成功时写入的字符数，若发生错误则返回负值。若结果字符串因 buf_size 限制被截断，函数将返回本应写入的字符总数（不包含终止空字节），此情况发生在未施加限制的条件下。
5,6) 传输到输出流的字符数量，若出现输出错误、运行时约束违反错误或编码错误则返回负值。
7) 写入到 buffer 的字符数量（不计算空字符，只要 buffer 不是空指针且 bufsz 不为零且不大于 RSIZE_MAX ，空字符就始终会被写入），在运行时约束违规时返回零，在编码错误时返回负值
8) 不包含终止空字符的字符数量（只要 buffer 不是空指针且 bufsz 不为零且不大于 RSIZE_MAX ，该空字符始终会被写入），这个数量是忽略 bufsz 时本应写入 buffer 的字符数，若发生运行时约束违规或编码错误则返回负值

注释

所有这些函数至少调用一次 va_arg ，返回后 arg 的值是不确定的。这些函数不会调用 va_end ，必须由调用者完成该操作。

vsnprintf_s 与 vsprintf_s 不同，它会将结果截断以适应 buffer 所指向的数组范围。

Microsoft CRT 中 vsnprintf_s 的实现不符合C语言标准。微软版本的函数在第三个参数位置额外增加了 size_t count 参数，该参数表示不包括空终止符在内的最大写入字符数。此参数可能与通过 size_t bufsz 参数提供的缓冲区大小存在差异。

示例

运行此代码 
#include <stdarg.h>
#include <stdio.h>
#include <time.h>
void debug_log(const char* 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 args1;
    va_start(args1, fmt);
    va_list args2;
    va_copy(args2, args1);
    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
    va_end(args1);
    vsnprintf(buf, sizeof buf, fmt, args2);
    va_end(args2);
    printf("%s [debug]: %s\n", time_buf, buf);
}
int main(void)
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

可能的输出： 

02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

参考文献

  • C23标准（ISO/IEC 9899:2024）：
  • 7.21.6.8 vfprintf函数（页码：待定）
  • 7.21.6.10 vprintf函数（页码：待定）
  • 7.21.6.12 vsnprintf函数（页码：待定）
  • 7.21.6.13 vsprintf函数（页码：待定）
  • K.3.5.3.8 vfprintf_s函数（页码：待定）
  • K.3.5.3.10 vprintf_s函数（页码：待定）
  • K.3.5.3.12 vsnprintf_s函数（页码：待定）
  • K.3.5.3.13 vsprintf_s函数（页码：待定）
  • C17标准（ISO/IEC 9899:2018）：
  • 7.21.6.8 vfprintf函数（页码：238）
  • 7.21.6.10 vprintf函数（页码：239）
  • 7.21.6.12 vsnprintf函数（页码：239-240）
  • 7.21.6.13 vsprintf函数（页码：240）
  • K.3.5.3.8 vfprintf_s函数（页码：434）
  • K.3.5.3.10 vprintf_s函数（页码：435）
  • K.3.5.3.12 vsnprintf_s函数（页码：436-437）
  • K.3.5.3.13 vsprintf_s函数（页码：437）
  • C11标准（ISO/IEC 9899:2011）：
  • 7.21.6.8 vfprintf函数（页码：326-327）
  • 7.21.6.10 vprintf函数（页码：328）
  • 7.21.6.12 vsnprintf函数（页码：329）
  • 7.21.6.13 vsprintf函数（页码：329）
  • K.3.5.3.8 vfprintf_s函数（页码：597）
  • K.3.5.3.10 vprintf_s函数（页码：598-599）
  • K.3.5.3.12 vsnprintf_s函数（页码：600）
  • K.3.5.3.13 vsprintf_s函数（页码：601）
  • C99标准（ISO/IEC 9899:1999）：
  • 7.19.6.8 vfprintf函数（页码：292）
  • 7.19.6.10 vprintf函数（页码：293）
  • 7.19.6.12 vsnprintf函数（页码：294）
  • 7.19.6.13 vsprintf函数（页码：295）
  • C89/C90 标准 (ISO/IEC 9899:1990):
  • 4.9.6.7 vfprintf 函数
  • 4.9.6.8 vprintf 函数
  • 4.9.6.9 vsprintf 函数

另请参阅

(C95) (C95) (C95) (C11) (C11) (C11) (C11)
使用可变参数列表将格式化宽字符输出打印到 stdout 、文件流
或缓冲区
（函数）
(C99) (C11) (C11) (C11) (C11)
将格式化输出打印到 stdout 、文件流或缓冲区
（函数）
(C99) (C99) (C99) (C11) (C11) (C11)
使用可变参数列表从 stdin 、文件流或缓冲区
读取格式化输入
（函数）
C++ 文档 关于 vprintf 、 vfprintf 、 vsprintf 、 vsnprintf