You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,13 +61,13 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned`
61
61
|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and nan output is capitalized.|
62
62
|**`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.|
63
63
|**`G`**|Floating-point|Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate).|
64
-
|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0x*`h.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.|
65
-
|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [-]0X*`h.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.|
64
+
|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has 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.|
65
+
|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has 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.|
66
66
|**`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.|
67
67
|**`p`**|Pointer type|Display the argument as an address in hexadecimal digits.|
68
68
|**`s`**|String|When used with `printf` functions, specifies a single-byte or multi-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.|
69
69
|**`S`**|String|When used with `printf` functions, specifies a wide-character string; when used with `wprintf` functions, specifies a single-byte or multi-byte character string. Characters are displayed up to the first null character or until the *precision* value is reached.|
70
-
|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [ANSI_STRING](/windows/win32/api/ntdef/ns-ntdef-string) or [UNICODE_STRING](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, displays the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **w** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.<br /><br />Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`.|
70
+
|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [`ANSI_STRING`](/windows/win32/api/ntdef/ns-ntdef-string) or [`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, display the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **`w`** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.<br /><br />Typically, the **`Z`** type character is used only in driver debugging functions that use a conversion specification, such as `dbgPrint` and `kdPrint`.|
71
71
72
72
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:
73
73
@@ -89,7 +89,7 @@ Before Visual Studio 2015, the CRT used a different, non-standard format for out
89
89
|Indefinite (same as quiet NaN)|*digit*`.#IND`*random-digits*|
90
90
|NaN|*digit*`.#NAN`*random-digits*|
91
91
92
-
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.
92
+
Any of these may have been prefixed by a sign, and may have been formatted differently depending on field width and precision, sometimes with unusual effects. For example, `printf("%.2f\n", INFINITY)`prints `1.#J` because the *#INF* would be "rounded" to two digits of precision.
93
93
94
94
> [!NOTE]
95
95
> If the argument that corresponds to `%s` or `%S`, or the `Buffer` field of the argument that corresponds to `%Z`, is a null pointer, "(null)" is displayed.
@@ -113,7 +113,7 @@ The first optional field in a conversion specification contains *flag directives
113
113
|**`-`**|Left align the result within the given field width.|Right align.|
114
114
|**`+`**|Use a sign (+ or -) to prefix the output value if it's of a signed type.|Sign appears only for negative signed values (-).|
115
115
|**`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, `%04.d`—the **`0`** is ignored. If **`0`** is specified for the **`a`** or **`A`** floating-point format, leading zeros are prepended to the mantissa, after the `0x` or `0X` prefix.|No padding.|
116
-
|**blank** (' ')|Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.|
116
+
|**blank (' ')**|Use a blank to prefix the output value if it's signed and positive. The blank is ignored if both the blank and + flags appear.|No blank appears.|
117
117
|**`#`**|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.|
118
118
||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.|
119
119
||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.<br /><br /> Ignored when used with **`c`**, **`d`**, **`i`**, **`u`**, or **`s`**.|Decimal point appears only if digits follow it. Trailing zeros are truncated.|
@@ -124,7 +124,7 @@ The first optional field in a conversion specification contains *flag directives
124
124
125
125
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.
126
126
127
-
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.
127
+
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 provided, all characters of the value are output, subject to the *precision* specification.
128
128
129
129
If the width specification is an asterisk (`*`), an `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:
130
130
@@ -154,17 +154,17 @@ The *type* character determines either the interpretation of *precision* or the
154
154
|----------|-------------|-------------|
155
155
|**`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.|
156
156
|**`c`**, **`C`**|The precision has no effect.|Character is printed.|
157
-
|**`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.|
157
+
|**`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 isn't truncated when the number of digits exceeds *precision*.|Default precision is 1.|
158
158
|**`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.|
159
159
|**`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.|
160
160
|**`g`**, **`G`**|The precision specifies the maximum number of significant digits printed.|Six significant digits are printed, and any trailing zeros are truncated.|
161
-
|**`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.|
161
+
|**`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 found.|
162
162
163
163
<aname="size"></a>
164
164
165
165
## Argument size specification
166
166
167
-
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 `printf` and `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 `char`, `short`, `int`, `long`, and enumeration types—as 32-bit `int` types, and `float`, `double`, 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 Ellipsis and Default Arguments in [Postfix expressions](../cpp/postfix-expressions.md). 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.
167
+
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 `printf` and `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 `char`, `short`, `int`, `long`, and enumeration types—as 32-bit `int` types, and `float`, `double`, 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 Ellipsis and Default Arguments in [Postfix expressions](../cpp/postfix-expressions.md). 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.
168
168
169
169
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. Instead, 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.
0 commit comments