命名空间
变体
操作

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

来自 cppreference.cn
< c‎ | io
 
C
 
文件输入/输出
类型和对象
        
函数
文件访问
(C11)
(C11)  
(C95)
无格式输入/输出
(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)  
文件定位
错误处理
文件操作
 
定义于头文件 <stdio.h>
(1)
int printf( const char*          format, ... );
 (until C99)
int printf( const char* restrict format, ... );
 (since C99)
(2)
int fprintf( FILE*          stream, const char*          format, ... );
 (until C99)
int fprintf( FILE* restrict stream, const char* restrict format, ... );
 (since C99)
(3)
int sprintf( char*          buffer, const char*          format, ... );
 (until C99)
int sprintf( char* restrict buffer, const char* restrict format, ... );
 (since C99)
int snprintf( char* restrict buffer, size_t bufsz,
              const char* restrict format, ... );
 (4) (since C99)
int printf_s( const char* restrict format, ... );
 (5) (since C11)
int fprintf_s( FILE* restrict stream, const char* restrict format, ... );
 (6) (since C11)
int sprintf_s( char* restrict buffer, rsize_t bufsz,
               const char* restrict format, ... );
 (7) (since C11)
int snprintf_s( char* restrict buffer, rsize_t bufsz,
                const char* restrict format, ... );
 (8) (since 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。
与所有边界检查函数一样，只有当实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，才能保证 printf_s、fprintf_s、sprintf_s 和 snprintf_s 可用。

目录

[编辑] 参数

stream - 要写入的输出文件流
buffer - 指向要写入的字符字符串的指针
bufsz - 最多可以写入 bufsz - 1 个字符，加上空终止符
format - 指向指定如何解释数据的空终止字节字符串的指针
... - 指定要打印的数据的参数。 如果在 默认参数提升 之后的任何参数不是相应转换规范所期望的类型（期望的类型是提升的类型或提升的类型的兼容类型），或者如果参数少于 format 所需的参数，则行为未定义。 如果参数多于 format 所需的参数，则会对多余的参数求值并忽略。

format 字符串由普通字节字符（除了 %）组成，这些字符不变地复制到输出流中，以及转换规范。 每个转换规范具有以下格式

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

以下格式说明符可用

转换
说明符		 说明 预期
参数类型
长度修饰符→ hh h 无 l ll j z t L
仅自 C99 起可用→ 是 是 是 是 是
% 写入文字 %。 完整的转换规范必须为 %%。 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​，则转换不会产生任何字符。
  • 对于 z 修饰符，预期的参数类型是 size_t 的有符号版本。
signed char
short
int
long
long long
※
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 (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 转换样式，使用 [-] 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

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

  • 对于 g 转换样式，将执行样式 e 或 f 的转换。
  • 对于 G 转换样式，将执行样式 E 或 f(until C99)F(since C99) 的转换。
  • 令 P 等于精度（如果非零），如果未指定精度，则为 6，如果精度为 ​0​，则为 1。 然后，如果使用样式 E 的转换将具有指数 X
    • 如果 P > X ≥ −4，则转换使用样式 f 或 F(since 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 系列函数不支持它(since C11)。

在每个转换说明符的操作之后都有一个 序列点； 这允许在同一变量中存储多个 %n 结果，或者作为边缘情况，在同一次调用中打印由较早的 %n 修改的字符串。

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

[编辑] 返回值

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

[编辑] 注意

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。

[编辑] 示例

运行此代码
#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

[编辑] 参考文献

  • 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 函数

[编辑] 参见

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