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

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.

For more information, see Format Specifications.

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

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

Nota

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.

See Also

Reference

Stream I/O

vprintf Functions

Format Specification Fields: printf and wprintf Functions

fprintf, _fprintf_l, fwprintf, _fwprintf_l

printf, _printf_l, wprintf, _wprintf_l

sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l

va_arg, va_end, va_start