Export (0) Print
Expand All
div
eof
Expand Minimize

vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

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

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.

For more information, see Format Specifications.

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.

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 Security Note

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

Note 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

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.

// 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!

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

Show:
© 2014 Microsoft