The behaviour of vsnprintf() with count == 0 and buffer != NULL is to return the length of the formatted data, rather than returning -1 — as the documentation currently states. I have cross-referenced the behaviour of vsnprintf() with the C specification, and confirmed that the implementation behaviour (returning the length of the formatted data) conforms to the C specification and is correct. Therefore, the current vsnprintf() documentation is incorrect and needs to be updated.

After making this observation, I conducted a broader review of the documentation for the *sn[w]printf* family of functions, making these updates as a result.

In general, I've corrected a number of errors in the description of the behaviour of the *sn[w]printf* family of functions, and have aligned the information for:

• _snprintf_s()/_snwprintf_s() and _vsnprintf_s()/_vsnwprintf_s()
• snprintf()/_snprintf()/_snwprintf() and vsnprintf()/_vsnprintf()/_vsnwprintf()

A detailed description of the problems addressed on each page is given below:

_snprintf_s()/_snwprintf_s():

• Add description of behaviour which occurs when an encoding error occurs during formatting — setting errno to EILSEQ in all cases and either returning a negative value for a string conversion specifier, or skipping the character for a character conversion specifier.

• Clarify that in cases where truncation does not occur, null-termination is performed

• Clarify truncation behaviour:

  • If count < sizeOfBuffer, but formatted data > count, then formatted data is truncated to count characters, null-terminated and -1 is returned with no error handler / update to errno
  • With count == _TRUNCATE, and formatted data >= sizeOfBuffer, then formatted data is truncated to (sizeOfBuffer - 1) characters, null-terminated and -1 is returned with no error handler / update to errno
  • If count >= sizeOfBuffer, formatted data >= sizeOfBuffer, and count != _TRUNCATE, the invalid parameter handler is invoked. If continued, the functions truncate the buffer to an empty string, return -1 and set errno to ERANGE

• Clarify error handling behaviour:

  • If buffer is NULL, an EINVAL error occurs if (and only if) either count or sizeOfBuffer are != 0 (if both are 0, no error occurs and 0 is returned)
  • An EINVAL error does not occur in all cases where count == 0, only when one of the other conditions are met (count cannot be negative, as size_t is unsigned)
  • If sizeOfBuffer (not count!) == 0, and additionally if buffer is not NULL, then an EINVAL error occurs

• Add copy of error conditions table from _vsnprintf_s()/_vsnwprintf_s().

snprintf()/_snprintf()/_snwprintf():

• Add description of behaviour which occurs when an encoding error occurs during formatting — setting errno to EILSEQ in all cases and either returning a negative value for a string conversion specifier, or skipping the character for a character conversion specifier.

• Clarify truncation behaviour:

  • For snprintf(), clarify that null-termination by writing to buffer[count-1] is only performed if count != 0.
  • For _snprintf()/_snwprintf(), clarify that non-terminated truncation is performed only when buffer != NULL (if buffer == NULL and count != 0, it is an error and if if buffer == NULL and count == 0, the length of the formatted data is returned).

_vsnprintf_s()/_vsnwprintf_s():

• Add description of behaviour which occurs when an encoding error occurs during formatting — setting errno to EILSEQ in all cases and either returning a negative value for a string conversion specifier, or skipping the character for a character conversion specifier.

• Clarify that in cases where truncation does not occur, null-termination is performed

• Clarify truncation behaviour:

  • Note that if count >= sizeOfBuffer and formatted data >= sizeOfBuffer, then only if also count != _TRUNCATE the invalid parameter handler is invoked, etc.

• Clarify error handling behaviour:

  • If buffer is NULL, an EINVAL error occurs if (and only if) either count or sizeOfBuffer are != 0 (if both are 0, no error occurs and 0 is returned)
  • An EINVAL error does not occur in all cases where count == 0, only when one of the other conditions are met (count cannot be negative, as size_t is unsigned)
  • If sizeOfBuffer (not count!) == 0, and additionally if buffer is not NULL, then an EINVAL error occurs

• Update error conditions table to correct from count == 0 to sizeOfBuffer == 0 as the condition required for an EINVAL error (when buffer != NULL).

vsnprintf()/_vsnprintf()/_vsnwprintf():

• Add description of behaviour which occurs when an encoding error occurs during formatting — setting errno to EILSEQ in all cases and either returning a negative value for a string conversion specifier, or skipping the character for a character conversion specifier.

• Clarify that in cases where truncation does not occur, null-termination is performed

• Clarify truncation behaviour:

  • For vsnprintf(), clarify that null-termination by writing to buffer[count-1] is only performed if count != 0.
  • For _vsnprintf()/_vsnwprintf(), clarify that non-terminated truncation is performed only when buffer != NULL (if buffer == NULL and count != 0, it is an error and if if buffer == NULL and count == 0, the length of the formatted data is returned).
  • For vsnprintf(), clarify that if count == 0 and buffer != NULL, the length of the formatted data is returned, rather than -1 (as is the case for _vsnprintf()/_vsnwprintf()).

To verify the behaviour of these functions, I constructed the attached test code (printf.zip). The updated descriptions of these functions' behaviour can be verified using the output from this:

C:\Temp>cl /Zi /Od /MTd printf.c && printf >printf.txt
Microsoft (R) C/C++ Optimizing Compiler Version 19.30.30528 for x86
Copyright (C) Microsoft Corporation.  All rights reserved.

printf.c
Microsoft (R) Incremental Linker Version 14.30.30528.0
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:printf.exe
/debug
printf.obj