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
@@ -45,7 +44,7 @@ The options listed in the following table:
45
44
|**`/FR`**⟦*`filename`*⟧ | Generates an extended form of a source browser *`.sbr`* file. |
46
45
|**`/Gc`**| Specifies use of FORTRAN- or Pascal-style conventions for function calls and names. Same as **`OPTION LANGUAGE:PASCAL`**.<br /> Not available in ml64.exe. |
47
46
|**`/Gd`**| Specifies use of C-style conventions for function calls and names. Same as **`OPTION LANGUAGE:C`**.<br /> Not available in ml64.exe. |
48
-
|**`/GZ`**| Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.<br /> Not available in ml64.exe. |
47
+
|**`/Gz`**| Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.<br /> Not available in ml64.exe. |
49
48
|**`/H`***`number`*| Restricts external names to *`number`* significant characters. The default is 31 characters.<br /> Not available in ml64.exe. |
50
49
|**`/help`**| Displays a summary of ML command-line syntax and options. |
51
50
|**`/I`***`pathname`*| Sets path for include file. A maximum of 10 **`/I`** options is allowed. |
Writes formatted data to a string. These functions are versions of [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md).
14
+
Writes formatted data to a string. These functions are versions of [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) with security enhancements described in [Security features in the CRT](../security-features-in-the-crt.md).
15
15
16
16
## Syntax
17
17
@@ -23,6 +23,7 @@ int _snprintf_s(
23
23
const char *format [,
24
24
argument] ...
25
25
);
26
+
26
27
int_snprintf_s_l(
27
28
char *buffer,
28
29
size_t sizeOfBuffer,
@@ -31,13 +32,15 @@ int _snprintf_s_l(
31
32
_locale_t locale [,
32
33
argument] ...
33
34
);
35
+
34
36
int_snwprintf_s(
35
37
wchar_t *buffer,
36
38
size_t sizeOfBuffer,
37
39
size_t count,
38
40
const wchar_t *format [,
39
41
argument] ...
40
42
);
43
+
41
44
int_snwprintf_s_l(
42
45
wchar_t *buffer,
43
46
size_t sizeOfBuffer,
@@ -46,13 +49,15 @@ int _snwprintf_s_l(
46
49
_locale_t locale [,
47
50
argument] ...
48
51
);
52
+
49
53
template <size_t size>
50
54
int_snprintf_s(
51
55
char (&buffer)[size],
52
56
size_t count,
53
57
const char *format [,
54
58
argument] ...
55
59
); // C++ only
60
+
56
61
template <size_t size>
57
62
int_snwprintf_s(
58
63
wchar_t (&buffer)[size],
@@ -68,10 +73,10 @@ int _snwprintf_s(
68
73
Storage location for the output.
69
74
70
75
*`sizeOfBuffer`*\
71
-
The size of the storage location for output. Size in **`bytes`** for **`_snprintf_s`** or size in **`words`** for **`_snwprintf_s`**.
76
+
The size of the storage location for output. Size in **bytes** for the functions that take `char`, and **words** for those that take `wchar_t`.
72
77
73
78
*`count`*\
74
-
Maximum number of characters to store, or[`_TRUNCATE`](../truncate.md).
79
+
Maximum number of characters to write. For the functions that take `wchar_t`, it's the maximum number of wide characters to write. Or[`_TRUNCATE`](../truncate.md).
75
80
76
81
*`format`*\
77
82
Format-control string.
@@ -84,45 +89,64 @@ The locale to use.
84
89
85
90
## Return value
86
91
87
-
**`_snprintf_s`** returns the number of characters stored in *`buffer`*, not counting the terminating null character. **`_snwprintf_s`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character.
92
+
The number of characters written, not including the terminating `NULL`. A negative value is returned if an output error occurs. See [Behavior summary](#behavior-summary) for details.
88
93
89
-
If the storage required to store the data and a terminating null exceeds *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *`buffer`* to an empty string, set `errno` to `ERANGE`, and return -1.
94
+
## Remarks
90
95
91
-
If *`buffer`*or *`format`*is a `NULL` pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set `errno` to `EINVAL`and return -1.
96
+
The **`_snprintf_s`** function formats and stores *`count`*or fewer characters in *`buffer`*and appends a terminating `NULL`. Each argument (if any) is converted and output according to the corresponding format specification in *`format`*. The formatting is consistent with the **`printf`** family of functions; see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). If copying occurs between strings that overlap, the behavior is undefined.
92
97
93
-
For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md).
98
+
### Behavior summary
94
99
95
-
## Remarks
100
+
For the following table:
96
101
97
-
The **`_snprintf_s`** function formats and stores *`count`* or fewer characters in *`buffer`* and appends a terminating null. Each argument (if any) is converted and output according to the corresponding format specification in *`format`*. The formatting is consistent with the **`printf`** family of functions; see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). If copying occurs between strings that overlap, the behavior is undefined.
102
+
-Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words.
103
+
- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer.
104
+
- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md).
98
105
99
-
If *`count`* is [`_TRUNCATE`](../truncate.md), then **`_snprintf_s`** writes as much of the string as will fit in *`buffer`* while leaving room for a terminating null. If the entire string (with terminating null) fits in *`buffer`*, then **`_snprintf_s`** returns the number of characters written (not including the terminating null); otherwise, **`_snprintf_s`** returns -1 to indicate that truncation occurred.
| Success | Writes the characters into the buffer using the specified format string.| The number of characters written, not including the terminating `NULL`. | N/A | No |
109
+
| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 |`EILSEQ` (42) | No |
110
+
| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. |`EILSEQ` (42) | No |
111
+
|`buffer == NULL` and `sizeOfBuffer == 0` and `count == 0`| No data is written. | 0 | N/A | No |
112
+
|`buffer == NULL` and either `sizeOfBuffer != 0` or `count != 0`| If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 |`EINVAL` (22) | Yes |
113
+
|`buffer != NULL` and `sizeOfBuffer == 0`| No data is written. | -1 |`EINVAL` (22) | Yes |
114
+
|`count == 0`| A `NULL` is placed at the beginning of the buffer. | -1 | N/A | No |
115
+
|`count < 0`| Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No |
116
+
|`count < sizeOfBuffer` and `len <= count`| All of the data is written and a terminating `NULL` is appended. | The number of characters written. | N/A | No |
117
+
|`count < sizeOfBuffer` and `len > count`| The first *`count`* characters are written and a terminating `NULL` is appended. | -1 | N/A | No |
118
+
|`count >= sizeOfBuffer` and `len < sizeOfBuffer`| All of the data is written with a terminating `NULL`. | The number of characters written. | N/A | No |
119
+
|`count >= sizeOfBuffer` and `len >= sizeOfBuffer` and `count != _TRUNCATE`| If execution continues after invalid parameter handler executes, sets `errno`, sets `buffer[0] == NULL`, and returns a negative value. | -1 |`ERANGE` (34) | Yes |
120
+
|`count == _TRUNCATE` and `len >= sizeOfBuffer`| Writes as much of the string as fits in *`buffer`* and a terminating `NULL`. | -1 | N/A | No |
121
+
|`count == _TRUNCATE` and `len < sizeOfBuffer`| Writes the entire string into *`buffer`* with a terminating `NULL`. | Number of characters written, not including the terminating `NULL`. | N/A | No |
122
+
|`format == NULL`| No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 |`EINVAL` (22) | Yes |
123
+
124
+
For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md).
100
125
101
126
> [!IMPORTANT]
102
127
> Ensure that *`format`* is not a user-defined string.
103
128
>
104
-
>
105
129
> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md).
106
130
107
-
**`_snwprintf_s`** is a wide-character version of **`_snprintf_s`**; the pointer arguments to **`_snwprintf_s`** are wide-character strings. Detection of encoding errors in **`_snwprintf_s`** might differ from the detection in **`_snprintf_s`**. **`_snwprintf_s`**, like **`swprintf_s`**, writes output to a string rather than to a destination of type `FILE`.
131
+
**`_snwprintf_s`** is a wide-character version of **`_snprintf_s`**; the pointer arguments to **`_snwprintf_s`** are wide-character strings. Detection of encoding errors in **`_snwprintf_s`** might differ from that in **`_snprintf_s`**. **`_snwprintf_s`**, like **`swprintf_s`**, writes output to a string rather than to a destination of type **`FILE`**.
108
132
109
133
The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale.
110
134
111
135
In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md).
112
136
113
137
### Generic-text routine mappings
114
138
115
-
|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined|
139
+
|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined|
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments