From c944dc90525fc4df2a8c35954f305a8395afcc4e Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 4 Aug 2020 22:43:02 +0100 Subject: [PATCH 1/3] Update vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md Clarification of return values. --- ...f-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 e6a172673e7..28ff8f5962d 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 @@ -95,7 +95,7 @@ For more information, see [Format Specifications](../../c-runtime-library/format **vsnprintf_s**, **_vsnprintf_s** and **_vsnwprintf_s** return the number of characters written, not including the terminating null, or a negative value if an output error occurs. **vsnprintf_s** is identical to **_vsnprintf_s**. **vsnprintf_s** is included for compliance to the ANSI standard. **_vnsprintf** is retained for backward compatibility. -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), unless *count* is [_TRUNCATE](../../c-runtime-library/truncate.md), in which case as much of the string as will fit in *buffer* is written and -1 returned. If execution continues after the invalid parameter handler, these functions set *buffer* to an empty string, set **errno** to **ERANGE**, and return -1. +If the storage required to store *count* characters of 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. Otherwise, if *count* is less than the number of characters of data or if *count* is [_TRUNCATE](../../c-runtime-library/truncate.md) then *count* characters or as much of the string as will fit in *buffer* is written and -1 is returned without invoking the invalid parameter handler. 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. From 133e3c7d286e6547b40732670c2ac62f3924126f Mon Sep 17 00:00:00 2001 From: Defined Risk Date: Wed, 23 Sep 2020 19:00:22 +0100 Subject: [PATCH 2/3] Clarification to return value. --- ...vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 28ff8f5962d..5320d0b3851 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 @@ -95,9 +95,11 @@ For more information, see [Format Specifications](../../c-runtime-library/format **vsnprintf_s**, **_vsnprintf_s** and **_vsnwprintf_s** return the number of characters written, not including the terminating null, or a negative value if an output error occurs. **vsnprintf_s** is identical to **_vsnprintf_s**. **vsnprintf_s** is included for compliance to the ANSI standard. **_vnsprintf** is retained for backward compatibility. -If the storage required to store *count* characters of 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. Otherwise, if *count* is less than the number of characters of data or if *count* is [_TRUNCATE](../../c-runtime-library/truncate.md) then *count* characters or as much of the string as will fit in *buffer* is written and -1 is returned without invoking the invalid parameter handler. +* If the storage required to store the data with 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 *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 [_TRUNCATE](../../c-runtime-library/truncate.md) and the data with a terminating null exceeds *sizeOfBuffer*, then as much of the string as will fit in *buffer* is written. If *count* is less than *sizeOfBuffer* but the data exceeds *count* characters, then the first *count* characters are written. Either way some truncation of the data occurs and -1 is returned without invoking the invalid parameter handler. + +* 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. ### Error Conditions From 0ebd918b3df00f3124a11e5152d559cfcc1018f8 Mon Sep 17 00:00:00 2001 From: Defined Risk Date: Fri, 25 Sep 2020 22:03:30 +0100 Subject: [PATCH 3/3] Edits to Return Value section following review comments --- ...-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) 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 5320d0b3851..605965d87f8 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,11 +93,17 @@ 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 an output error occurs. **vsnprintf_s** is identical to **_vsnprintf_s**. **vsnprintf_s** is included for compliance to the ANSI standard. **_vnsprintf** is retained for backward compatibility. +**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. -* If the storage required to store the data with 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 *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 *count* is [_TRUNCATE](../../c-runtime-library/truncate.md) and the data with a terminating null exceeds *sizeOfBuffer*, then as much of the string as will fit in *buffer* is written. If *count* is less than *sizeOfBuffer* but the data exceeds *count* characters, then the first *count* characters are written. Either way some truncation of the data occurs and -1 is returned without invoking the invalid parameter handler. +* 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* 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* 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. @@ -112,6 +118,8 @@ For more information, see [Format Specifications](../../c-runtime-library/format ## Remarks +**vsnprintf_s** is identical to **_vsnprintf_s**. **vsnprintf_s** is included for compliance to the ANSI standard. **_vnsprintf** is retained for backward compatibility. + Each of these functions takes a pointer to an argument list, then formats and writes up to *count* characters of the given data to the memory pointed to by *buffer* and appends a terminating null. If *count* is [_TRUNCATE](../../c-runtime-library/truncate.md), then these functions write 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 these functions return the number of characters written (not including the terminating null); otherwise, these functions return -1 to indicate that truncation occurred.