vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_l

使用指向参数列表的指针写入格式化输出。 这些函数的更安全版本可用;见 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
输出的存储位置。

count
要写入的最大字符数。 对于采用 的 wchar_t函数，它是要写入的宽字符数。

format
格式规范。

argptr
指向参数列表的指针。

locale
要使用的区域设置。

有关更多信息，请参阅 格式规范语法。

返回值

写入的字符数，不包括 terminating NULL，如果发生输出错误，则不包括负值。

有关详细信息，请参阅行为摘要。

注解

这些函数中的每一个都采用指向参数列表的指针，然后格式化数据，并将字符写入 count 指向的 buffer内存。 该 vsnprintf 函数始终写入 null 终止符，即使它截断了输出。 使用 _vsnprintf and _vsnwprintf时，仅当末尾有空间时（即，如果要写入的字符数小于 count），缓冲区才会以 null 结尾。

从 Visual Studio 2015 和 Windows 10 中的 UCRT 开始， vsnprintf 不再等于 _vsnprintf。 该 vsnprintf 函数符合 C99 标准; _vsnprintf 保留该函数是为了向后兼容较旧的代码。 区别在于，如果缓冲区用完， vsnprintf 则以 null 终止缓冲区的末尾并返回所需的字符数，而不 _vsnprintf 以 null 终止缓冲区并返回 -1。 此外，_vsnprintf() 在输出中包含一个字符，因为它不会以 null 终止缓冲区。

这些带有 _l 后缀的函数的版本是相同的，只是它们使用传入的 locale 参数，而不是当前线程区域设置。

在 C++ 中，这些函数具有模板重载，用于调用这些函数的更新、安全的对应项。 有关详细信息，请参阅安全模板重载。

行为摘要

对于下表：

• 将 sizeOfBuffer 设置为 buffer 的大小。 如果函数采用 char 缓冲区，则大小以字节为单位。 如果函数采用 wchar_t 缓冲区，则大小指定 16 位字的数目。
• 将 len 设置为格式化数据的大小。 如果函数采用 char 缓冲区，则大小以字节为单位。 如果函数采用 wchar_t 缓冲区，则大小指定 16 位字的数目。
• 字符是指采用 char 缓冲区的函数的 char 字符，以及采用 wchar_t 缓冲区的函数 wchar_t 字符。
• 有关无效参数处理程序的详细信息，请参阅参数验证。

有关这些和其他错误代码的信息，请参阅 、_doserrno、errno、_sys_errlist 和 _sys_nerr。

一般文本例程映射

要求

、 _vsnprintf_vsnprintf_l_vsnwprintf 和 _vsnwprintf_l 函数是特定于 Microsoft 的。 有关更多兼容性信息，请参阅 兼容性。

示例：使用 _vsnwprintf()

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

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

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

如果改用 vsnprintf 以及窄字符串参数，则行为会发生变化。 该 count 参数可以是缓冲区的整个大小，返回值是如果 count 足够大，将写入的字符数：

示例：与窄字符串一起使用vsnprintf()

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

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

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

另请参阅

流 I/O
vprintf 函数
格式规范语法： printf 和 wprintf 函数
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