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
+10-10Lines changed: 10 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ ms.date: "10/26/2020"
5
5
helpviewer_keywords: ["format specification fields for printf function", "printf function format specification fields", "flag directives, printf function", "type fields, printf function", "width fields, printf function", "precision fields, printf function"]
6
6
ms.assetid: 664b1717-2760-4c61-bd9c-22eee618d825
7
7
---
8
-
# Format specification syntax: printf and wprintf functions
8
+
# Format specification syntax: `printf` and `wprintf` functions
9
9
10
10
The various `printf` and `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](../c-runtime-library/stream-i-o.md).
11
11
@@ -122,31 +122,31 @@ The first optional field in a conversion specification contains *flag directives
122
122
123
123
## Width specification
124
124
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.
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 provided, 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
-
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:
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
131
131
`printf("%0*d", 5, 3); /* 00003 is output */`
132
132
133
-
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.
133
+
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.
134
134
135
135
<aname="precision"></a>
136
136
137
137
## Precision specification
138
138
139
139
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.
140
140
141
-
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:
141
+
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:
142
142
143
143
`printf( "%.0d", 0 ); /* No characters output */`
144
144
145
-
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:
145
+
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:
The *type* character determines either the interpretation of *precision* or the default precision when *precision* is omitted, as shown in the following table.
149
+
The *`type`* character determines either the interpretation of *`precision`* or the default precision when *`precision`* is omitted, as shown in the following table.
150
150
151
151
### How Precision Values Affect Type
152
152
@@ -199,6 +199,6 @@ An **`hc`** or **`hC`** type specifier is synonymous with **`c`** in `printf` fu
Opens a file. These versions of [`fopen, _wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md).
14
+
Opens a file. These versions of [`fopen`, `_wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md).
15
15
16
16
## Syntax
17
17
@@ -41,7 +41,7 @@ Type of access permitted.
41
41
42
42
## Return Value
43
43
44
-
Zero if successful; an error code on failure. For more information about these error codes, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
44
+
Zero if successful; an error code on failure. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
45
45
46
46
### Error Conditions
47
47
@@ -53,15 +53,15 @@ Zero if successful; an error code on failure. For more information about these e
53
53
54
54
## Remarks
55
55
56
-
Files that are opened by **`fopen_s`** and **`_wfopen_s`** aren't sharable. If you require that a file be sharable, use [`_fsopen, _wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, **`_SH_DENYNO`** for read/write sharing.
56
+
Files that are opened by **`fopen_s`** and **`_wfopen_s`** aren't sharable. If you require that a file be sharable, use [`_fsopen`, `_wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, **`_SH_DENYNO`** for read/write sharing.
57
57
58
58
The **`fopen_s`** function opens the file that's specified by *filename*. **`_wfopen_s`** is a wide-character version of **`fopen_s`**; the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically otherwise.
59
59
60
60
**`fopen_s`** accepts paths that are valid on the file system at the point of execution; UNC paths and paths that involve mapped network drives are accepted by **`fopen_s`** as long as the system that's executing the code has access to the share or mapped network drive at the time of execution. When you construct paths for **`fopen_s`**, don't make assumptions about the availability of drives, paths, or network shares in the execution environment. You can use either forward slashes (/) or backslashes (\\) as the directory separators in a path.
61
61
62
62
These functions validate their parameters. If *`pFile`*, *`filename`*, or *`mode`* is a null pointer, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md).
63
63
64
-
Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned and the global variable **`errno`** is set. For more information, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
64
+
Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned and the global variable **`errno`** is set. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
65
65
66
66
By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md).
67
67
@@ -111,7 +111,7 @@ The character string *`mode`* specifies the kind of access that's requested for
111
111
112
112
When a file is opened by using the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out so that existing data cannot be overwritten.
113
113
114
-
The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the `CTRL+Z` EOF marker.
114
+
The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the **CTRL**+**Z** EOF marker.
115
115
116
116
When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed. (The file is said to be open for "update".) However, when you switch from reading to writing, the input operation must come across an EOF marker. If there's no EOF marker, you must use an intervening call to a file-positioning function. The file-positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file-positioning function.
117
117
@@ -124,7 +124,7 @@ In addition to the values above, the following characters can be included in *`m
124
124
|**`t`**| Open in text (translated) mode. |
125
125
|**`b`**| Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. |
126
126
127
-
In text (translated) mode, `CTRL+Z` is interpreted as an end-of-file character on input. In files opened for reading/writing with **`"a+"`**, **`fopen_s`** checks for a `CTRL+Z` at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and **`ftell`** to move within a file that ends with a `CTRL+Z`, may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file.
127
+
In text (translated) mode, **CTRL**+**Z** is interpreted as an end-of-file character on input. In files opened for reading/writing with **`"a+"`**, **`fopen_s`** checks for a **CTRL**+**Z** at the end of the file and removes it, if possible. This is done because using [`fseek`](fseek-fseeki64.md) and **`ftell`** to move within a file that ends with a **CTRL**+**Z**, may cause [`fseek`](fseek-fseeki64.md) to behave improperly near the end of the file.
128
128
129
129
Also, in text mode, carriage return/line feed combinations are translated into single line feeds on input, and line feed characters are translated to carriage return-line feed combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. The Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function).
130
130
@@ -249,10 +249,10 @@ Number of files closed by _fcloseall: 1
0 commit comments