Format specification syntax: printf and wprintf functions
wprintf functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more directives, which are either literal characters for output or encoded conversion specifications that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see Stream I/O.
A conversion specification consists of optional and required fields in this form:
Each field of the conversion specification is a character or a number that signifies a particular format option or conversion specifier. The required type field specifies the kind of conversion to be applied to an argument. The optional flags, width, and precision fields control additional format aspects such as leading spaces or zeroes, justification, and displayed precision. The size field specifies the size of the argument consumed and converted.
A basic conversion specification contains only the percent sign and a type character. For example,
%s specifies a string conversion. To print a percent-sign character, use
%%. If a percent sign is followed by a character that has no meaning as a format field, the invalid parameter handler is invoked. For more information, see Parameter Validation.
For security and stability, ensure that conversion specification strings are not user-defined. For example, consider a program that prompts the user to enter a name and stores the input in a string variable that's named
user_name. To print
user_name, do not do this:
printf( user_name ); /* Danger! If user_name contains "%s", program will crash */
Instead, do this:
printf( "%s", user_name );
Type conversion specifier
The type conversion specifier character specifies whether to interpret the corresponding argument as a character, a string, a pointer, an integer, or a floating-point number. The type character is the only required conversion specification field, and it appears after any optional fields.
The arguments that follow the format string are interpreted according to the corresponding type character and the optional size prefix. Conversions for character types
wchar_t are specified by using c or C, and single-byte and multi-byte or wide character strings are specified by using s or S, depending on which formatting function is being used. Character and string arguments that are specified by using c and s are interpreted as
printf family functions, or as
wprintf family functions. Character and string arguments that are specified by using C and S are interpreted as
printf family functions, or as
wprintf family functions. This behavior is Microsoft specific.
Integer types such as
long long, and their
unsigned variants, are specified by using d, i, o, u, x, and X. Floating-point types such as
long double, are specified by using a, A, e, E, f, F, g, and G. By default, unless they are modified by a size prefix, integer arguments are coerced to
int type, and floating-point arguments are coerced to
double. On 64-bit systems, an
int is a 32-bit value; therefore, 64-bit integers will be truncated when they are formatted for output unless a size prefix of ll or I64 is used. Pointer types that are specified by p use the default pointer size for the platform.
The Z type character, and the behavior of the c, C, s, and S type characters when they are used with the
wprintf functions, are Microsoft extensions. The ISO C standard uses c and s consistently for narrow characters and strings, and C and S for wide characters and strings, in all formatting functions.
Type field characters
|Type character||Argument||Output format|
|c||Character||When used with
|C||Character||When used with
|d||Integer||Signed decimal integer.|
|i||Integer||Signed decimal integer.|
|o||Integer||Unsigned octal integer.|
|u||Integer||Unsigned decimal integer.|
|x||Integer||Unsigned hexadecimal integer; uses "abcdef."|
|X||Integer||Unsigned hexadecimal integer; uses "ABCDEF."|
|e||Floating-point||Signed value that has the form [-]d.dddde±dd[d], where d is one decimal digit, dddd is one or more decimal digits depending on the specified precision, or six by default, and dd[d] is two or three decimal digits depending on the output format and size of the exponent.|
|E||Floating-point||Identical to the e format except that E rather than e introduces the exponent.|
|f||Floating-point||Signed value that has the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default.|
|F||Floating-point||Identical to the f format except that infinity and nan output is capitalized.|
|g||Floating-point||Signed values are displayed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than -4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.|
|G||Floating-point||Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).|
|a||Floating-point||Signed hexadecimal double-precision floating-point value that has the form [-]0xh.hhhhp±dd, where h.hhhh are the hex digits (using lower case letters) of the mantissa, and dd are one or more digits for the exponent. The precision specifies the number of digits after the point.|
|A||Floating-point||Signed hexadecimal double-precision floating-point value that has the form [-]0Xh.hhhhP±dd, where h.hhhh are the hex digits (using capital letters) of the mantissa, and dd are one or more digits for the exponent. The precision specifies the number of digits after the point.|
|n||Pointer to integer||Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed at can be controlled by an argument size specification prefix. The n specifier is disabled by default; for information see the important security note.|
|p||Pointer type||Displays the argument as an address in hexadecimal digits.|
|s||String||When used with
|S||String||When used with
||When the address of an ANSI_STRING or UNICODE_STRING structure is passed as the argument, displays the string contained in the buffer pointed to by the
Typically, the Z type character is used only in driver debugging functions that use a conversion specification, such as
Starting in Visual Studio 2015, if the argument that corresponds to a floating-point conversion specifier (a, A, e, E, f, F, g, G) is infinite, indefinite, or NaN, the formatted output conforms to the C99 standard. This table lists the formatted output:
Any of these values may be prefixed by a sign. If a floating-point type conversion specifier character is a capital letter, then the output is also formatted in capital letters. For example, if the format specifier is
%F instead of
%f, an infinity is formatted as
INF instead of
scanf functions can also parse these strings, so these values can make a round trip through
Before Visual Studio 2015, the CRT used a different, non-standard format for output of infinite, indefinite, and NaN values:
|Indefinite (same as quiet NaN)||digit
Any of these may have been prefixed by a sign, and may have been formatted slightly differently depending on field width and precision, sometimes with unusual effects. For example,
printf("%.2f\n", INFINITY) would print
1.#J because the #INF would be "rounded" to 2 digits of precision.
If the argument that corresponds to
%S, or the
Buffer field of the argument that corresponds to
%Z, is a null pointer, "(null)" is displayed.
In all exponential formats, the minimum number of digits of exponent to display is two, using three only if necessary. By using the _set_output_format function, you can set the number of digits displayed to three for backward compatibility with code written for Visual Studio 2013 and before.
%n format is inherently insecure, it is disabled by default. If
%n is encountered in a format string, the invalid parameter handler is invoked, as described in Parameter Validation. To enable
%n support, see _set_printf_count_output.
The first optional field in a conversion specification contains flag directives, zero or more flag characters that specify output justification and control output of signs, blanks, leading zeros, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a conversion specification, and the flag characters can appear in any order.
|-||Left align the result within the given field width.||Right align.|
|+||Use a sign (+ or -) to prefix the output value if it is of a signed type.||Sign appears only for negative signed values (-).|
|0||If width is prefixed by 0, leading zeros are added until the minimum width is reached. If both 0 and - appear, the 0 is ignored. If 0 is specified for an integer format (i, u, x, X, o, d) and a precision specification is also present—for example,
|blank (' ')||Use a blank to prefix the output value if it is signed and positive. The blank is ignored if both the blank and + flags appear.||No blank appears.|
|#||When it's used with the o, x, or X format, the # flag uses 0, 0x, or 0X, respectively, to prefix any nonzero output value.||No blank appears.|
|When it's used with the e, E, f, F, a, or A format, the # flag forces the output value to contain a decimal point.||Decimal point appears only if digits follow it.|
|When it's used with the g or G format, the # flag forces the output value to contain a decimal point and prevents the truncation of trailing zeros.
Ignored when used with c, d, i, u, or s.
|Decimal point appears only if digits follow it. Trailing zeros are truncated.|
In a conversion specification, the optional width specification field appears after any flags characters. The width argument is a non-negative decimal integer that controls the minimum number of characters that are output. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values—depending on whether the left-alignment flag (-) is specified—until the minimum width is reached. If width is prefixed by 0, leading zeros are added to integer or floating-point conversions until the minimum width is reached, except when conversion is to an infinity or NaN.
The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width isn't given, all characters of the value are output, subject to the precision specification.
If the width specification is an asterisk (
int argument from the argument list supplies the value. The width argument must precede the value that's being formatted in the argument list, as shown in this example:
printf("%0*d", 5, 3); /* 00003 is output */
A missing or small width value in a conversion specification doesn't cause the truncation of an output value. If the result of a conversion is wider than the width value, the field expands to contain the conversion result.
In a conversion specification, the third optional field is the precision specification. It consists of a period (.) followed by a non-negative decimal integer that, depending on the conversion type, specifies the number of string characters, the number of decimal places, or the number of significant digits to be output.
Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0, and the value to be converted is 0, the result is no characters output, as shown in this example:
printf( "%.0d", 0 ); /* No characters output */
If the precision specification is an asterisk (*), an
int argument from the argument list supplies the value. In the argument list, the precision argument must precede the value that's being formatted, as shown in this example:
printf( "%.*f", 3, 3.14159265 ); /* 3.142 output */
The type character determines either the interpretation of precision or the default precision when precision is omitted, as shown in the following table.
How Precision Values Affect Type
|a, A||The precision specifies the number of digits after the point.||Default precision is 13. If precision is 0, no decimal point is printed unless the # flag is used.|
|c, C||The precision has no effect.||Character is printed.|
|d, i, o, u, x, X||The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.||Default precision is 1.|
|e, E||The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.||Default precision is 6. If precision is 0 or the period (.) appears without a number following it, no decimal point is printed.|
|f, F||The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.||Default precision is 6. If precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.|
|g, G||The precision specifies the maximum number of significant digits printed.||Six significant digits are printed, and any trailing zeros are truncated.|
|s, S||The precision specifies the maximum number of characters to be printed. Characters in excess of precision aren't printed.||Characters are printed until a null character is encountered.|
Argument size specification
In a conversion specification, the size field is an argument length modifier for the type conversion specifier. The size field prefixes to the type field—hh, h, j, l (lowercase L), L, ll, t, w, z, I (uppercase i), I32, and I64—specify the "size" of the corresponding argument—long or short, 32-bit or 64-bit, single-byte character or wide character—depending on the conversion specifier that they modify. These size prefixes are used with type characters in the
wprintf families of functions to specify the interpretation of argument sizes, as shown in the following table. The size field is optional for some argument types. When no size prefix is specified, the formatter consumes integer arguments—for example, signed or unsigned
long, and enumeration types—as 32-bit
int types, and
long double floating-point arguments are consumed as 64-bit
double types. This behavior matches the default argument promotion rules for variable argument lists. For more information about argument promotion, see Ellipses and Default Arguments in Postfix expressions. On both 32-bit and 64-bit systems, the conversion specification of a 64-bit integer argument must include a size prefix of ll or I64. Otherwise, the behavior of the formatter is undefined.
Some types are different sizes in 32-bit and 64-bit code. For example,
size_t is 32 bits long in code compiled for x86, and 64 bits in code compiled for x64. To create platform-agnostic formatting code for variable-width types, you can use a variable-width argument size modifier. Alternatively, use a 64-bit argument size modifier and explicitly promote the variable-width argument type to 64 bits. The Microsoft-specific I (uppercase i) argument size modifier handles variable-width integer arguments, but we recommend the type-specific j, t, and z modifiers for portability.
Size Prefixes for printf and wprintf Format-Type Specifiers
|To specify||Use prefix||With type specifier|
||hh||d, i, o, u, x, or X|
||h||d, i, o, u, x, or X|
||I32||d, i, o, u, x, or X|
||I64||d, i, o, u, x, or X|
||j or I64||d, i, o, u, x, or X|
||l (lowercase L) or L||a, A, e, E, f, F, g, or G|
||l (lowercase L)||d, i, o, u, x, or X|
||ll (lowercase LL)||d, i, o, u, x, or X|
||t or I (uppercase i)||d, i, o, u, x, or X|
||z or I (uppercase i)||d, i, o, u, x, or X|
|Single-byte character||h||c or C|
|Wide character||l (lowercase L) or w||c or C|
|Single-byte character string||h||s, S, or Z|
|Wide-character string||l (lowercase L) or w||s, S, or Z|
size_t types are
unsigned __int32 on 32-bit platforms, and
unsigned __int64 on 64-bit platforms. The I (uppercase i), j, t, and z size prefixes take the correct argument width for the platform.
In Visual C++, although
long double is a distinct type, it has the same internal representation as
An hc or hC type specifier is synonymous with c in
printf functions and with C in
wprintf functions. An lc, lC, wc, or wC type specifier is synonymous with C in
printf functions and with c in
wprintf functions. An hs or hS type specifier is synonymous with s in
printf functions and with S in
wprintf functions. An ls, lS, ws or wS type specifier is synonymous with S in
printf functions and with s in
The I (uppercase i), I32, I64, and w argument size modifier prefixes are Microsoft extensions and are not ISO C-compatible. The h prefix when it's used with data of type
char and the l (lowercase L) prefix when it's used with data of type
double are Microsoft extensions.