vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Write formatted output using a pointer to a list of arguments. These functions are versions of vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l with security enhancements as described in Security features in the CRT.

Syntax

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
);

int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);

int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
);

template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only

Parameters

buffer
Storage location for output.

sizeOfBuffer
The size of the buffer 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 write not including the terminating NULL. For the functions that take wchar_t, it's the number of wide characters to write. Or _TRUNCATE.

format
Format specification.

argptr
Pointer to list of arguments.

locale
The locale to use when formatting the output.

For more information, see Format specifications.

Return value

The number of characters written, not including the terminating NULL, or a negative value if an output error occurs.

See Behavior summary for details.

Remarks

vsnprintf_s is identical to _vsnprintf_s and is included for conformance 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.

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.

Behavior summary

For the following table:

• 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.

For information about these and other error codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

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.

Generic-text routine mappings

Requirements

* Required for UNIX V compatibility.

For more compatibility information, see Compatibility.

Example

// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>

void FormatOutput(LPCSTR formatstring, ...)
{
   int nSize = 0;
   char buff[10];
   memset(buff, 0, sizeof(buff));
   va_list args;
   va_start(args, formatstring);
   nSize = vsnprintf_s( buff, _countof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
   va_end(args);
}

int main() {
   FormatOutput("%s %s", "Hi", "there");
   FormatOutput("%s %s", "Hi", "there!");
   FormatOutput("%s %s", "Hi", "there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

See also

Stream I/O
vprintf functions
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_start