vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Article
11/16/2012

Write formatted output using a pointer to a list of arguments. More secure versions of these functions are available; see vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

int vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
);
int _vsnwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   va_list argptr 
);
int _vsnwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
); // C++ only

Parameters

buffer
Storage location for output.
count
Maximum number of characters to write.
format
Format specification.
argptr
Pointer to list of arguments.
locale
The locale to use.

Return Value

vsnprintf,_vsnprintf, and _vsnwprintf 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. The return value does not include the terminating null, if one is written.

If buffer or format is NULL, or if count is less than or equal to zero, these functions invoke the invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, these functions return -1 and set errno to EINVAL.

Remarks

Each of these functions takes a pointer to an argument list, then formats the data, and writes up to count characters to the memory pointed to by buffer. If there is room at the end (that is, if the number of characters to write is less than count), the buffer will be null-terminated.

Security Note:
Ensure that format is not a user-defined string. For more information, see Avoiding Buffer Overruns.

Note

To ensure that there is room for the terminating null, be sure that count is strictly less than the buffer length and initialize the buffer to null prior to calling the function.

vsnprintf is identical to _vsnprintf. vsnprintf is included for compliance to the ANSI standard; _vnsprintf is retained for backward compatibility.

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.

In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_vsntprintf	_vsnprintf	_vsnprintf	_vsnwprintf
_vsntprintf_l	_vsnprintf_l	_vsnprintf_l	_vsnwprintf_l

Requirements

Routine	Required header	Optional headers
vsnprintf	<stdio.h> and <stdarg.h>	<varargs.h>*
_vsnprintf, _vsnprintf_l	<stdio.h> and <stdarg.h>	<varargs.h>*
_vsnwprintf, _vsnwprintf_l	<stdio.h> or <wchar.h>, and <stdarg.h>	<varargs.h>*

* Required for UNIX V compatibility.

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_vsnprintf.cpp
// compile with: /W3
#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( buff, sizeof(buff) - 1, formatstring, args); // C4996
// Note: vsnprintf is deprecated; consider vsnprintf_s instead
   printf("nSize: %d, buff: %s\n", nSize, buff);
}

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!

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Change History

Date	History	Reason
December 2008	Added underscore to vsnprintf_l.	Customer feedback.