This topic describes the syntax for format specifications fields, used in printf, wprintf and related functions. More secured versions of these functions are available, see printf_s, _printf_s_l, wprintf_s, _wprintf_s_l. For details on the individual functions, see the documentation for those specific functions. For a complete listing of these functions, see Stream I/O.
A format specification, which consists of optional and required fields, has the following form:
%[flags] [width] [.precision] [{h | l | ll | I | I32 | I64}]type
Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is copied to stdout. For example, to print a percent-sign character, use %%.
The optional fields, which appear before the type character, control other aspects of the formatting, as follows:
type
-
Required character that determines whether the associated argument is interpreted as a character, a string, or a number (see the "printf Type Field Characters" table in printf Type Field Characters).
flags
-
Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes (see the "Flag Characters" table in Flag Directives). More than one flag can appear in a format specification.
width
-
Optional number that specifies the minimum number of characters output (see printf Width Specification).
precision
-
Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values (see the "How Precision Values Affect Type" table in Precision Specification).
h|
l|
ll|
I|
I32|
I64
-
Optional prefixes to type-that specify the size of argument (see the "Size Prefixes" table in Size Specification).
note: printf( name ); // Danger! If name contains "%s", program will crash
type
The type character of the format specification indicates that the corresponding argument is to be interpreted as a character, string, or number. The typecharacter is the only required format field, and it appears after any optional format fields.
Character | Type | Output format |
---|
c | int or wint_t | When used with printf functions, specifies a single-byte character; when used with wprintf functions, specifies a wide character. |
C | int or wint_t | When used with printf functions, specifies a wide character; when used with wprintf functions, specifies a single-byte character. |
d | int | Signed decimal integer. |
i | int | Signed decimal integer. |
o | int | Unsigned octal integer. |
u | int | Unsigned decimal integer. |
x | int | Unsigned hexadecimal integer, using "abcdef." |
X | int | Unsigned hexadecimal integer, using "ABCDEF." |
e | double | Signed value having the form [ – ]d.dddd e [sign]dd[d] where d is a single decimal digit, dddd is one or more decimal digits, dd[d]is two or three decimal digits depending on the output format and size of the exponent, and sign is + or –. |
E | double | Identical to the e format except that E rather than e introduces the exponent. |
f | double | Signed value having 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. |
g | double | Signed value 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 | double | Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate). |
a | double | Signed hexadecimal double precision floating point value having the form [−]0xh.hhhh p±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 | double | Signed hexadecimal double precision floating point value having the form [−]0Xh.hhhh P±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 successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument. See Security Note below. |
p | Pointer to void | Displays the argument as an address in hexadecimal digits. |
s | String | When used with printf functions, specifies a single-byte–character string; when used with wprintf functions, specifies a wide-character string. Characters are displayed up to the first null character or until the precision value is reached. |
S | String | When used with printf functions, specifies a wide-character string; when used with wprintf functions, specifies a single-byte–character string. Characters are displayed up to the first null character or until the precision value is reached. |
Z | UNICODE_STRING structure | When the address of a UNICODE_STRING structure is passed as the argument, displays the Unicode string that is contained in the buffer pointed to by the Buffer field of the structure. The Length field of the structure must be set to the length, in bytes, of the Unicode string. The MaximumLength field of the structure must be set to the length, in bytes, of the buffer. The Z type character is typically used only in driver debugging functions that use a format specification, such as dbgPrint andkdPrint. |
Note If the argument corresponding to %s or %S is a null pointer, "(null)" will be displayed.
Note In all exponential formats, the default number of digits of exponent to display is three. Using the _set_output_format function, the number of digits displayed may be set to two, expanding to three if demanded by the size of exponent.
Security Note The %n format is inherently insecure and 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.
flags
The first optional field of the format specification is flags. A flag directive is a character that justifies output and prints signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag directive may appear in a format specification.
Fl ag | Meaning | Default |
---|
– | Left align the result within the given field width. | Right align. |
+ | Prefix the output value with a sign (+ or –) if the output value is of a signed type. | Sign appears only for negative signed values (–). |
0 | If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) and a precision specification is also present (for example,%04.d), the 0 is ignored. | No padding. |
blank(' ') | Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. | No blank appears. |
# | When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. | No blank appears. |
| When used with the e, E, f, a or A format, the # flag forces the output value to contain a decimal point in all cases. | Decimal point appears only if digits follow it. |
| When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases 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. |