Repo sync for protected CLA branch

docs/assembler/masm/ml-and-ml64-command-line-reference.md

@@ -1,10 +1,9 @@
 ---
 title: "ML and ML64 command-line reference"
 description: "Reference guide to the Microsoft MASM ML and ML64 assembler command-line options."
-ms.date: 02/01/2022
+ms.date: 7/3/2023
 f1_keywords: ["ML"]
 helpviewer_keywords: ["/W* MASM compiler option", "/c MASM compiler option", "/EP MASM compiler option", "/Fe MASM compiler option", "/Zp MASM compiler option", "/AT MASM compiler option", "/Zm MASM compiler option", "/Sf MASM compiler option", "/Sp MASM compiler option", "/w MASM compiler option", "/Fl MASM compiler option", "/coff MASM compiler option", "/St MASM compiler option", "/Cx MASM compiler option", "/Sl MASM compiler option", "/Cu MASM compiler option", "MASM (Microsoft Macro Assembler), ML command-line reference", "/FPi MASM compiler option", "/Zf MASM compiler option", "ML environment variable", "/Fr MASM compiler option", "/help MASM compiler option", "/Sa MASM compiler option", "/Zd MASM compiler option", "/I MASM compiler option", "/? MASM compiler option", "/Bl MASM compiler option", "/Fm MASM compiler option", "/Fo MASM compiler option", "command-line reference [ML]", "/Sn MASM compiler option", "/Gd MASM compiler option", "/D* MASM compiler option", "environment variables, ML", "/Gc MASM compiler option", "/F* MASM compiler option", "/Sc MASM compiler option", "/H MASM compiler option", "/Zs MASM compiler option", "/omf MASM compiler option", "/Sg MASM compiler option", "/Cp MASM compiler option", "/Zi MASM compiler option", "/nologo MASM compiler option", "/Sx MASM compiler option", "/WX MASM compiler option", "/Ss MASM compiler option", "command line, reference [ML]", "/Ta MASM compiler option"]
-ms.assetid: 712623c6-f77e-47ea-a945-089e57c50b40
 ---
 # ML and ML64 command-line reference
 
@@ -45,7 +44,7 @@ The options listed in the following table:
 | **`/FR`**⟦*`filename`*⟧ | Generates an extended form of a source browser *`.sbr`* file. |
 | **`/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. |
 | **`/Gd`** | Specifies use of C-style conventions for function calls and names. Same as **`OPTION LANGUAGE:C`**.<br /> Not available in ml64.exe. |
-| **`/GZ`** | Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.<br /> Not available in ml64.exe. |
+| **`/Gz`** | Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.<br /> Not available in ml64.exe. |
 | **`/H`** *`number`* | Restricts external names to *`number`* significant characters. The default is 31 characters.<br /> Not available in ml64.exe. |
 | **`/help`** | Displays a summary of ML command-line syntax and options. |
 | **`/I`** *`pathname`* | Sets path for include file. A maximum of 10 **`/I`** options is allowed. |

docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md

@@ -1,7 +1,7 @@
 ---
 description: "Learn more about: _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l"
 title: "_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l"
-ms.date: "3/9/2021"
+ms.date: 06/27/2023
 api_name: ["_snprintf_s", "_snprintf_s_l", "_snwprintf_s", "_snwprintf_s_l"]
 api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"]
 api_type: ["DLLExport"]
@@ -11,7 +11,7 @@ helpviewer_keywords: ["_snprintf_s_l function", "_snwprintf_s_l function", "_snt
 ---
 # `_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`
 
-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).
+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).
 
 ## Syntax
 
@@ -23,6 +23,7 @@ int _snprintf_s(
    const char *format [,
    argument] ...
 );
+
 int _snprintf_s_l(
    char *buffer,
    size_t sizeOfBuffer,
@@ -31,13 +32,15 @@ int _snprintf_s_l(
    _locale_t locale [,
    argument] ...
 );
+
 int _snwprintf_s(
    wchar_t *buffer,
    size_t sizeOfBuffer,
    size_t count,
    const wchar_t *format [,
    argument] ...
 );
+
 int _snwprintf_s_l(
    wchar_t *buffer,
    size_t sizeOfBuffer,
@@ -46,13 +49,15 @@ int _snwprintf_s_l(
    _locale_t locale [,
    argument] ...
 );
+
 template <size_t size>
 int _snprintf_s(
    char (&buffer)[size],
    size_t count,
    const char *format [,
    argument] ...
 ); // C++ only
+
 template <size_t size>
 int _snwprintf_s(
    wchar_t (&buffer)[size],
@@ -68,10 +73,10 @@ int _snwprintf_s(
 Storage location for the output.
 
 *`sizeOfBuffer`*\
-The size of the storage location for output. Size in **`bytes`** for **`_snprintf_s`** or size in **`words`** for **`_snwprintf_s`**.
+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`.
 
 *`count`*\
-Maximum number of characters to store, or [`_TRUNCATE`](../truncate.md).
+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).
 
 *`format`*\
 Format-control string.
@@ -84,45 +89,64 @@ The locale to use.
 
 ## Return value
 
-**`_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.
+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.
 
-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.
+## Remarks
 
-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.
+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.
 
-For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md).
+### Behavior summary
 
-## Remarks
+For the following table:
 
-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.
+-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.
+- 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.
+- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md).
 
-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.
+| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler |
+|--|--|--|--|--|
+| 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 |
+| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ` (42) | No |
+| 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 |
+| `buffer == NULL` and `sizeOfBuffer == 0` and `count == 0` | No data is written. | 0 | N/A | No |
+| `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 |
+| `buffer != NULL` and `sizeOfBuffer == 0` | No data is written. | -1 | `EINVAL` (22) | Yes |
+| `count == 0`| A `NULL` is placed at the beginning of the buffer. | -1 | N/A | No |
+| `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 |
+| `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 |
+| `count < sizeOfBuffer` and `len > count` | The first *`count`* characters are written and a terminating `NULL` is appended. | -1 | N/A | No |
+| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written. | N/A | No |
+| `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 |
+| `count == _TRUNCATE` and `len >= sizeOfBuffer` | Writes as much of the string as fits in *`buffer`* and a terminating `NULL`. | -1 | N/A | No |
+| `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 |
+| `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 |
+
+For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md).
 
 > [!IMPORTANT]
 > Ensure that *`format`* is not a user-defined string.
 >
->
 > 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).
 
-**`_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`.
+**`_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`**.
 
 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.
 
 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).
 
 ### Generic-text routine mappings
 
-| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined |
+|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined|
 |---|---|---|---|
-| `_sntprintf_s` | **`_snprintf_s`** | **`_snprintf_s`** | **`_snwprintf_s`** |
-| `_sntprintf_s_l` | **`_snprintf_s_l`** | **`_snprintf_s_l`** | **`_snwprintf_s_l`** |
+|**`_sntprintf_s`**|**`_snprintf_s`**|**`_snprintf_s`**|**`_snwprintf_s`**|
+|**`_sntprintf_s_l`**|**`_snprintf_s_l`**|**`_snprintf_s_l`**|**`_snwprintf_s_l`**|
 
 ## Requirements
 
-| Routine | Required header |
+|Routine|Required header|
 |---|---|
-| **`_snprintf_s`**, **`_snprintf_s_l`** | `<stdio.h>` |
-| **`_snwprintf_s`**, **`_snwprintf_s_l`** | `<stdio.h>` or `<wchar.h>` |
+|**`_snprintf_s`**, **`_snprintf_s_l`**|`<stdio.h>`|
+|**`_snwprintf_s`**, **`_snwprintf_s_l`**|`<stdio.h>` or `<wchar.h>`|
 
 For more compatibility information, see [Compatibility](../compatibility.md).