diff --git a/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md b/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md index 74f0dd6f78..7f47f818db 100644 --- a/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md +++ b/docs/c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md @@ -84,14 +84,35 @@ 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. +**`_snprintf_s`** and **`_snwprintf_s`** return the number of characters written, not including the terminating null, or a negative value if truncation of the data occurs (for **`_snwprintf_s`**, this is a count of wide characters). -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](../../c-runtime-library/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. +If an encoding error occurs during formatting, **`errno`** is set to **`EILSEQ`**. If the encoding error occurs during formatting for a string conversion specifier (type character **`s`** , **`S`** or **`Z`**), processing of the format specification is aborted and a negative value is returned by the function. Otherwise, if an encoding error occurs during processing a character conversion specifier (type character **`c`** or **`C`**), the processing of the specifier will be aborted and the invalid character will be skipped. In particular, the number of characters written will not be incremented for this specifier, nor will any data be written for it. Processing of the format specification will continue after skipping the specifier which caused the encoding error, and the function return value will be as described further below. -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. +* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written, a terminating null is appended and the number of characters is returned. + +* If *`count`* is less than *`sizeOfBuffer`* but the data exceeds *`count`* characters, then the first *`count`* characters are written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. + +* If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data equals or exceeds *`sizeOfBuffer`*, then as much of the string as will fit in *`buffer`* (with terminating null) is written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. + +* If *`count`* is greater than or equal to *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. + +* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`* (and *`count`* is not [`_TRUNCATE`](../../c-runtime-library/truncate.md)), the invalid parameter handler is invoked — as described in [Parameter Validation](../../c-runtime-library/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. + +* If *`buffer`* is a null pointer and both *`sizeOfBuffer`* and *`count`* are equal to zero, these functions return 0. + +* If *`format`* is a null pointer, or *`buffer`* is a null pointer and either *`sizeOfBuffer`* or *`count`* are nonzero, or if *`buffer`* is not a null pointer and *`sizeOfBuffer`* is zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +### Error Conditions + +|**Condition**|Return|**`errno`**| +|-----------------|------------|-------------| +|*`buffer`* is **`NULL`** (and either *`sizeOfBuffer`* or *`count`* != 0)|-1|**`EINVAL`**| +|*`format`* is **`NULL`**|-1|**`EINVAL`**| +|*`buffer`* != **`NULL`** and *`sizeOfBuffer`* == 0|-1|**`EINVAL`**| +|*`sizeOfBuffer`* too small (and *`count`* != **`_TRUNCATE`**)|-1 (and *`buffer`* set to an empty string)|**`ERANGE`**| + ## Remarks 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](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). If copying occurs between strings that overlap, the behavior is undefined. diff --git a/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md b/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md index cfe357ab0e..7a111dda32 100644 --- a/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md +++ b/docs/c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md @@ -101,19 +101,23 @@ For more information, see [Format Specification Syntax: `printf` and `wprintf` F ## Return Value -Let **`len`** be the length of the formatted data string, not including the terminating null. Both **`len`** and **`count`** are the number of characters for **`snprintf`** and **`_snprintf`**, and the number of wide characters for **`_snwprintf`**. +Let **`len`** be the length of the formatted data string, not including the terminating null. Both **`len`** and *`count`* are the number of characters for **`snprintf`** and **`_snprintf`**, and the number of wide characters for **`_snwprintf`**. -For all functions, if **`len`** < *`count`*, **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and **`len`** is returned. +For all functions, if an encoding error occurs during formatting, **`errno`** is set to **`EILSEQ`**. If the encoding error occurs during formatting for a string conversion specifier (type character **`s`** , **`S`** or **`Z`**), processing of the format specification is aborted and a negative value is returned by the function. + +**Microsoft-specific**: if an encoding error occurs during processing a character conversion specifier (type character **`c`** or **`C`**), the processing of the specifier will be aborted and the invalid character will be skipped. In particular, the character count (**`len`**) will not be incremented for this specifier, nor will output be generated for it. Processing of the format specification will continue after skipping the specifier which caused the encoding error, and the function return value will be as described further below. -The **`snprintf`** function truncates the output when **`len`** is greater than or equal to *`count`*, by placing a null-terminator at `buffer[count-1]`. The value returned is **`len`**, the number of characters that would have been output if *`count`* was large enough. The **`snprintf`** function returns a negative value if an encoding error occurs. +For all functions, if *`buffer`* is a null pointer and *`count`* is zero, **`len`** is returned as the count of characters required to format the output — not including the terminating null. To make a successful call with the same *`argument`* and *`locale`* parameters, allocate a buffer holding at least **`len`** + 1 characters. + +For all functions, if **`len`** < *`count`*, **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and **`len`** is returned. -For all functions other than **`snprintf`**, if **`len`** = *`count`*, **`len`** characters are stored in *`buffer`*, no null-terminator is appended, and **`len`** is returned. If **`len`** > *`count`*, *`count`* characters are stored in *`buffer`*, no null-terminator is appended, and a negative value is returned. +The **`snprintf`** function truncates the output when *`count`* is nonzero and **`len`** >= *`count`*, by placing a null-terminator at `buffer[count-1]` (when *`count`* is zero, no characters are stored in *`buffer`* — whether it is a null pointer or not). In all cases where **`len`** >= *`count`*, the value returned by the **`snprintf`** function is **`len`** (the number of characters that would have been output if *`count`* was large enough). As a corollary, if **`snprintf`** returns a value > *`count`* - 1, the output has been truncated. -If *`buffer`* is a null pointer and *`count`* is zero, **`len`** is returned as the count of characters required to format the output, not including the terminating null. To make a successful call with the same *`argument`* and *`locale`* parameters, allocate a buffer holding at least **`len`** + 1 characters. +For all functions other than **`snprintf`**, if **`len`** = *`count`*, **`len`** characters are stored in *`buffer`*, no null-terminator is appended, and **`len`** is returned. If **`len`** > *`count`* and *`buffer`* is not a null pointer, *`count`* characters are stored in *`buffer`*, no null-terminator is appended, and a negative value is returned. -If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked — as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks diff --git a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md index 954e77bb95..bb1a420b9d 100644 --- a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md @@ -93,27 +93,31 @@ For more information, see [Format Specifications](../../c-runtime-library/format ## Return Value -**`vsnprintf_s`**, **`_vsnprintf_s`** and **`_vsnwprintf_s`** return the number of characters written, not including the terminating null, or a negative value if either truncation of the data or an output error occurs. +**`vsnprintf_s`**, **`_vsnprintf_s`** and **`_vsnwprintf_s`** return the number of characters written, not including the terminating null, or a negative value if truncation of the data occurs (for **`_vsnwprintf_s`**, this is a count of wide characters). -* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written and the number of characters is returned. +If an encoding error occurs during formatting, **`errno`** is set to **`EILSEQ`**. If the encoding error occurs during formatting for a string conversion specifier (type character **`s`** , **`S`** or **`Z`**), processing of the format specification is aborted and a negative value is returned by the function. Otherwise, if an encoding error occurs during processing a character conversion specifier (type character **`c`** or **`C`**), the processing of the specifier will be aborted and the invalid character will be skipped. In particular, the number of characters written will not be incremented for this specifier, nor will any data be written for it. Processing of the format specification will continue after skipping the specifier which caused the encoding error, and the function return value will be as described further below. + +* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written, a terminating null is appended and the number of characters is returned. * If *`count`* is less than *`sizeOfBuffer`* but the data exceeds *`count`* characters, then the first *`count`* characters are written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. * If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data equals or exceeds *`sizeOfBuffer`*, then as much of the string as will fit in *`buffer`* (with terminating null) is written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. -* If *`count`* is equal to or exceeds *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. +* If *`count`* is greater than or equal to *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. + +* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`* (and *`count`* is not [`_TRUNCATE`](../../c-runtime-library/truncate.md)), the invalid parameter handler is invoked — as described in [Parameter Validation](../../c-runtime-library/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. -* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/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. +* If *`buffer`* is a null pointer and both *`sizeOfBuffer`* and *`count`* are equal to zero, these functions return 0. -* 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. +* If *`format`* is a null pointer, or *`buffer`* is a null pointer and either *`sizeOfBuffer`* or *`count`* are nonzero, or if *`buffer`* is not a null pointer and *`sizeOfBuffer`* is zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. ### Error Conditions |**Condition**|Return|**`errno`**| |-----------------|------------|-------------| -|*`buffer`* is **`NULL`**|-1|**`EINVAL`**| +|*`buffer`* is **`NULL`** (and either *`sizeOfBuffer`* or *`count`* != 0)|-1|**`EINVAL`**| |*`format`* is **`NULL`**|-1|**`EINVAL`**| -|*`count`* <= 0|-1|**`EINVAL`**| +|*`buffer`* != **`NULL`** and *`sizeOfBuffer`* == 0|-1|**`EINVAL`**| |*`sizeOfBuffer`* too small (and *`count`* != **`_TRUNCATE`**)|-1 (and *`buffer`* set to an empty string)|**`ERANGE`**| ## Remarks diff --git a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md index 15b2afda7d..d2d153dfe0 100644 --- a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md @@ -104,19 +104,27 @@ Pointer to list of arguments. *`locale`*
The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). ## Return Value -The **`vsnprintf`** function returns the number of characters that are written, not counting the terminating null character. If the buffer size specified by *`count`* isn't sufficiently large to contain the output specified by *`format`* and *`argptr`*, the return value of **`vsnprintf`** is the number of characters that would be written, not counting the null character, if *`count`* were sufficiently large. If the return value is greater than *`count`* - 1, the output has been truncated. A return value of -1 indicates that an encoding error has occurred. +Let **`len`** be the length of the formatted data string specified by *`format`* and *`argptr`*, not including the terminating null. Both **`len`** and *`count`* are the number of characters for **`vsnprintf`** and **`_vsnprintf`**, and the number of wide characters for **`_vsnwprintf`**. -Both **`_vsnprintf`** and **`_vsnwprintf`** functions return the number of characters written if the number of characters to write is less than or equal to *`count`*. If the number of characters to write is greater than *`count`*, these functions return -1 indicating that output has been truncated. +For all functions, if an encoding error occurs during formatting, **`errno`** is set to **`EILSEQ`**. If the encoding error occurs during formatting for a string conversion specifier (type character **`s`** , **`S`** or **`Z`**), processing of the format specification is aborted and a negative value is returned by the function. -The value returned by all these functions doesn't include the terminating null, whether one is written or not. +**Microsoft-specific**: if an encoding error occurs during processing a character conversion specifier (type character **`c`** or **`C`**), the processing of the specifier will be aborted and the invalid character will be skipped. In particular, the character count (**`len`**) will not be incremented for this specifier, nor will output be generated for it. Processing of the format specification will continue after skipping the specifier which caused the encoding error, and the function return value will be as described further below. -- If *`count`* is zero and *`buffer`* is **`NULL`**, the value returned is the number of characters the functions would write. The value does not take into account a terminating **`NULL`**. You can use this result to allocate sufficient buffer space for the string and its terminating null, and then call the function again to fill the buffer. -- If *`count`* is zero but *`buffer`* isn't **`NULL`**, nothing is written and the function returns `-1`. -- If *`format`* is **`NULL`**, or if *`buffer`* is **`NULL`** and *count* isn't equal to zero, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +For all functions, if *`buffer`* is a null pointer and *`count`* is zero, **`len`** is returned as the count of characters required to format the output — not including the terminating null. To make a successful call with the same *`argument`* and *`locale`* parameters, allocate a buffer holding at least **`len`** + 1 characters. + +For all functions, if **`len`** < *`count`*, **`len`** characters are stored in *`buffer`*, a null-terminator is appended, and **`len`** is returned. + +The **`vsnprintf`** function truncates the output when *`count`* is nonzero and **`len`** >= *`count`*, by placing a null-terminator at `buffer[count-1]` (when *`count`* is zero, no characters are stored in *`buffer`* — whether it is a null pointer or not). In all cases where **`len`** >= *`count`*, the value returned by the **`vsnprintf`** function is **`len`** (the number of characters that would have been output if *`count`* was large enough). As a corollary, if **`vsnprintf`** returns a value > *`count`* - 1, the output has been truncated. + +For all functions other than **`vsnprintf`**, if **`len`** = *`count`*, **`len`** characters are stored in *`buffer`*, no null-terminator is appended, and **`len`** is returned. If **`len`** > *`count`* and *`buffer`* is not a null pointer, *`count`* characters are stored in *`buffer`*, no null-terminator is appended, and a negative value is returned. + +If *`buffer`* is a null pointer and *`count`* is nonzero, or if *`format`* is a null pointer, the invalid parameter handler is invoked — as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. + +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks