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) 相同，但在运行时检测到以下错误时会调用当前安装的 约束处理函数 ：
  • 转换说明符 %n 出现在 format 中
  • 任何对应于 %s 的参数是空指针
  • format 或 buffer 是空指针
  • bufsz 为零或大于 RSIZE_MAX
  • 在任何字符串和字符转换说明符中出现编码错误
  • （仅适用于 vsprintf_s ），要存储到 buffer 中的字符串（包括结尾的空字符）将超过 bufsz
与所有边界检查函数一样，只有在实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 vprintf_s 、 vfprintf_s 、 vsprintf_s 和 vsnprintf_s 可用。

目录

参数

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

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

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

以下格式说明符可用：

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

写入 单个字符 。

  • 参数首先转换为 unsigned char 。
  • 若使用 l 修饰符，则参数首先转换为字符串，如同通过 %ls 及 wchar_t [ 2 ] 参数。
不适用 不适用
int
wint_t
不适用 不适用 不适用 不适用 不适用
s

写入 字符串 。

  • 参数必须是指向字符数组首元素的指针。
  • 精度 指定要写入的最大字节数。若未指定 精度 ，则写入直到首个空终止符之前的所有字节。
  • 若使用 l 说明符，则参数必须是指向 wchar_t 数组首元素的指针，该数组会通过调用 wcrtomb 转换为字符数组，转换状态初始化为零。
不适用 不适用
char *
wchar_t *
不适用 不适用 不适用 不适用 不适用
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 的无符号版本
不适用
x
X

将 无符号整数 转换为十六进制表示 hhhh 。

  • 对于 x 转换，使用字母 abcdef 。
  • 对于 X 转换，使用字母 ABCDEF 。
  • 精度 指定要出现的最小位数。默认精度为 1 。
  • 若转换后的值和精度均为 ​ 0 ​ ，则转换不产生字符。
  • 在 替代实现 中，若转换后的值非零，则结果前缀 0x 或 0X 。
不适用
u

将 无符号整数 转换为十进制表示 dddd 。

  • 精度 指定要出现的最小位数。
  • 默认精度为 1 。
  • 若转换后的值和精度均为 ​ 0 ​ ，则转换不产生字符。
不适用
f
F (C99)

将 浮点数 转换为样式为 [-]ddd.ddd 的十进制表示。

  • 精度 指定小数点后要出现的精确位数。
  • 默认精度为 6 。
  • 在 替代实现 中，即使没有数字跟随

返回值

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