命名空间
变体
操作

printf、fprintf、sprintf、snprintf、printf_s、fprintf_s、sprintf_s、snprintf_s

来自 cppreference.com
< c‎ | io
 
C
 
文件输入/输出
类型和对象
函数
文件访问
直接输入/输出
无格式输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)
格式化输入
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)     
格式化输出
printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s
(C99)(C11)(C11)(C11)(C11)
(C95)(C95)(C95)(C11)(C11)(C11)(C11)    
文件定位
错误处理
文件操作
(C11)
(C11)
 
定义在头文件 <stdio.h> 中
(1)
int printf( const char*          format, ... );
 (直到 C99)
int printf( const char* restrict format, ... );
 (自 C99 起)
(2)
int fprintf( FILE*          stream, const char*          format, ... );
 (直到 C99)
int fprintf( FILE* restrict stream, const char* restrict format, ... );
 (自 C99 起)
(3)
int sprintf( char*          buffer, const char*          format, ... );
 (直到 C99)
int sprintf( char* restrict buffer, const char* restrict format, ... );
 (自 C99 起)
int snprintf( char* restrict buffer, size_t bufsz,
              const char* restrict format, ... );
 (4) (自 C99 起)
int printf_s( const char* restrict format, ... );
 (5) (自 C11 起)
int fprintf_s( FILE* restrict stream, const char* restrict format, ... );
 (6) (自 C11 起)
int sprintf_s( char* restrict buffer, rsize_t bufsz,
               const char* restrict format, ... );
 (7) (自 C11 起)
int snprintf_s( char* restrict buffer, rsize_t bufsz,
                const char* restrict format, ... );
 (8) (自 C11 起)

从给定的位置加载数据，将它们转换为字符字符串等效项，并将结果写入各种接收器/流

1) 将结果写入输出流 stdout。
2) 将结果写入输出流 stream。
3) 将结果写入字符字符串 buffer。如果要写入的字符串（加上终止的空字符）超过了 buffer 指向的数组的大小，则行为未定义。
4) 将结果写入字符字符串 buffer。最多写入 bufsz - 1 个字符。生成的字符字符串将以空字符终止，除非 bufsz 为零。如果 bufsz 为零，则不会写入任何内容，并且 buffer 可能为空指针，但是返回值（不包括空终止符的写入字节数）仍然会计算并返回。
5-8) 与 (1-4) 相同，但以下错误在运行时检测到，并调用当前安装的 约束处理程序 函数
  • 转换说明符 %n 出现在 format 中
  • 任何与 %s 相对应的参数都是空指针
  • stream 或 format 或 buffer 是空指针
  • bufsz 为零或大于 RSIZE_MAX
  • 在任何字符串和字符转换说明符中出现编码错误
  • (仅对于 sprintf_s)，要存储在 buffer 中的字符串（包括尾随空字符）将超过 bufsz。
与所有边界检查函数一样，printf_s、fprintf_s、sprintf_s 和 snprintf_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
写入单个字符。

参数首先被转换为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数组的初始元素的指针，该指针被转换为char数组，如同使用wcrtomb调用，并使用零初始化的转换状态。

 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
signed size_t
N/A
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
将浮点数转换为以[-]ddd.ddd形式的十进制表示法。

精度指定小数点后要显示的确切位数。默认精度为6。在替代实现中，即使小数点后没有数字，也会写入小数点字符。有关无穷大和小数转换的样式，请参见注释。

 N/A N/A
double
double(C99)
 N/A N/A N/A N/A
long double
e
E
将浮点数转换为十进制指数表示法。

对于e转换样式，使用[-]d.ddde±dd。
对于E转换样式，使用[-]d.dddE±dd。
指数至少包含两位数字，只有在必要时才会使用更多数字。如果值为​0​，则指数也为​0​。精度指定小数点后要显示的确切位数。默认精度为6。在替代实现中，即使小数点后没有数字，也会写入小数点字符。有关无穷大和小数转换的样式，请参见注释。

 N/A N/A N/A N/A N/A N/A
a
A

(C99)

将浮点数转换为十六进制指数表示法。

对于a转换样式，使用[-]0xh.hhhp±d。
对于A转换样式，使用[-]0Xh.hhhP±d。
如果参数是规范化的浮点数，则第一个十六进制数字不是0。如果值为​0​，则指数也为​0​。精度指定十六进制小数点后要显示的确切位数。默认精度足以精确地表示该值。在替代实现中，即使小数点后没有数字，也会写入小数点字符。有关无穷大和小数转换的样式，请参见注释。

 N/A N/A N/A N/A N/A N/A
g
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/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或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 修改的字符串。

如果转换说明符无效，则行为未定义。

[edit] 返回值

1,2) 传输到输出流的字符数，或负值（如果发生输出错误或编码错误（对于字符串和字符转换说明符））。
3) 写入 buffer 的字符数（不包括终止的空字符），或负值（如果发生编码错误（对于字符串和字符转换说明符））。
4) 如果忽略 bufsz，则将写入 buffer 的字符数（不包括终止的空字符），或负值（如果发生编码错误（对于字符串和字符转换说明符））。
5,6) 传输到输出流的字符数，或负值（如果发生输出错误、运行时约束违规错误或编码错误）。
7) 写入 buffer 的字符数，不包括空字符（只要 buffer 不是空指针，并且 bufsz 不为零且不大于 RSIZE_MAX，就会始终写入），或在运行时约束违规时为零，以及在编码错误时为负值。
8) 不包括终止的空字符（只要 buffer 不是空指针，并且 bufsz 不为零且不大于 RSIZE_MAX，就会始终写入）的字符数，如果忽略 bufsz，这些字符将被写入 buffer，或负值（如果发生运行时约束违规或编码错误）。

[edit] 注释

C 标准和 POSIX 指定，当参数与目标缓冲区重叠时，sprintf 及其变体的行为未定义。示例

sprintf(dst, "%s and %s", dst, t); // <- broken: undefined behavior

POSIX 指定，发生错误时会设置 errno。它还指定了其他转换说明符，最值得注意的是对参数重新排序的支持（n$ 紧随 % 之后表示第 n 个参数）。

使用零 bufsz 和空指针作为 buffer 调用 snprintf 对于确定包含输出所需的缓冲区大小很有用。

const char fmt[] = "sqrt(2) = %f";
int sz = snprintf(NULL, 0, fmt, sqrt(2));
char buf[sz + 1]; // note +1 for terminating null byte
snprintf(buf, sizeof buf, fmt, sqrt(2));

snprintf_s 与 snprintf 相同，但与 sprintf_s 不同，它会将输出截断以适合 bufsz - 1。

[edit] 示例

运行此代码
#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
 
int main(void)
{
    const char* s = "Hello";
    printf("Strings:\n"); // same as puts("Strings");
    printf(" padding:\n");
    printf("\t[%10s]\n", s);
    printf("\t[%-10s]\n", s);
    printf("\t[%*s]\n", 10, s);
    printf(" truncating:\n");
    printf("\t%.4s\n", s);
    printf("\t%.*s\n", 3, s);
 
    printf("Characters:\t%c %%\n", 'A');
 
    printf("Integers:\n");
    printf("\tDecimal:\t%i %d %.6i %i %.0i %+i %i\n",
                         1, 2,   3, 0,   0,  4,-4);
    printf("\tHexadecimal:\t%x %x %X %#x\n", 5, 10, 10, 6);
    printf("\tOctal:\t\t%o %#o %#o\n", 10, 10, 4);
 
    printf("Floating-point:\n");
    printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
    printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
    printf("\tScientific:\t%E %e\n", 1.5, 1.5);
    printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5);
    printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0 / 0.0, 1.0 / 0.0);
 
    printf("Fixed-width types:\n");
    printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n",
                                     UINT32_MAX,     UINT32_MAX );
}

可能的输出

Strings:
 padding:
        [     Hello]
        [Hello     ]
        [     Hello]
 truncating:
        Hell
        Hel
Characters:     A %
Integers:
        Decimal:        1 2 000003 0  +4 -4
        Hexadecimal:    5 a A 0x6
        Octal:          12 012 04
Floating-point:
        Rounding:       1.500000 2 1.30000000000000004440892098500626
        Padding:        01.50 1.50  1.50
        Scientific:     1.500000E+00 1.500000e+00
        Hexadecimal:    0x1.8p+0 0X1.8P+0
        Special values: 0/0=-nan 1/0=inf
Fixed-width types:
        Largest 32-bit value is 4294967295 or 0xffffffff

[edit] 参考资料

  • C23 标准 (ISO/IEC 9899:2024)
  • 7.21.6.1 fprintf 函数 (p: TBD)
  • 7.21.6.3 printf 函数 (p: TBD)
  • 7.21.6.5 snprintf 函数 (p: TBD)
  • 7.21.6.6 sprintf 函数 (p: TBD)
  • K.3.5.3.1 fprintf_s 函数 (p: TBD)
  • K.3.5.3.3 printf_s 函数 (p: TBD)
  • K.3.5.3.5 snprintf_s 函数 (p: TBD)
  • K.3.5.3.6 sprintf_s 函数 (p: TBD)
  • C17 标准 (ISO/IEC 9899:2018)
  • 7.21.6.1 fprintf 函数 (p: 225-230)
  • 7.21.6.3 printf 函数 (p: 236)
  • 7.21.6.5 snprintf 函数 (p: 237)
  • 7.21.6.6 sprintf 函数 (p: 237)
  • K.3.5.3.1 fprintf_s 函数 (p: 430)
  • K.3.5.3.3 printf_s 函数 (p: 432)
  • K.3.5.3.5 snprintf_s 函数 (p: 432-433)
  • K.3.5.3.6 sprintf_s 函数 (p: 433)
  • C11 标准 (ISO/IEC 9899:2011)
  • 7.21.6.1 fprintf 函数 (p: 309-316)
  • 7.21.6.3 printf 函数 (p: 324)
  • 7.21.6.5 snprintf 函数 (p: 325)
  • 7.21.6.6 sprintf 函数 (p: 325-326)
  • K.3.5.3.1 fprintf_s 函数 (p: 591)
  • K.3.5.3.3 printf_s 函数 (p: 593-594)
  • K.3.5.3.5 snprintf_s 函数 (p: 594-595)
  • K.3.5.3.6 sprintf_s 函数 (p: 595-596)
  • C99 标准 (ISO/IEC 9899:1999)
  • 7.19.6.1 fprintf 函数 (p: 274-282)
  • 7.19.6.3 printf 函数 (p: 290)
  • 7.19.6.5 snprintf 函数 (p: 290-291)
  • 7.19.6.6 sprintf 函数 (p: 291)
  • C89/C90 标准 (ISO/IEC 9899:1990)
  • 4.9.6.1 fprintf 函数
  • 4.9.6.3 printf 函数
  • 4.9.6.5 sprintf 函数

[edit] 参见

(C95)(C95)(C95)(C11)(C11)(C11)(C11)
 将格式化的宽字符输出打印到 stdout、文件流或缓冲区。
(函数) [edit]
(C99)(C11)(C11)(C11)(C11)
 将格式化的输出打印到 stdout、文件流或缓冲区。
使用可变参数列表。
(函数) [edit]
 将字符字符串写入文件流。
(函数) [edit]
(C11)(C11)(C11)
 从 stdin、文件流或缓冲区读取格式化的输入。
(函数) [edit]
C++ 文档 针对 printf, fprintf, sprintf, snprintf
取自 "https://cppreference.cn/mwiki/index.php?title=c/io/fprintf&oldid=172020"