Skip to content

Clarify return values of vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l #2349

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ktoliver merged 8 commits into from
Sep 28, 2020
Merged

Clarify return values of vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l #2349

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
375ef22
Merge pull request #1 from MicrosoftDocs/master
definedrisk Aug 4, 2020
c944dc9
Update vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-…
definedrisk Aug 4, 2020
e687aa2
Merge remote-tracking branch 'upstream/master'
definedrisk Sep 23, 2020
9334bdb
Merge branch 'master' into vsnprintf_s
definedrisk Sep 23, 2020
133e3c7
Clarification to return value.
definedrisk Sep 23, 2020
5e82bc8
Merge remote-tracking branch 'upstream/master'
definedrisk Sep 25, 2020
e2c1411
Merge branch 'master' into vsnprintf_s
definedrisk Sep 25, 2020
0ebd918
Edits to Return Value section following review comments
definedrisk Sep 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions .../reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,11 +93,19 @@ 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 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 *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 *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* 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.

### Error Conditions

Expand All @@ -110,6 +118,8 @@ If *buffer* or *format* is a **NULL** pointer, or if *count* is less than or equ

## 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.
Expand Down