vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_l

项目
06/09/2015

编写使用指针参数列表的格式化输出。提供这些函数的更多安全版本；请参见 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
可写的最多字符数。
format
格式规范。
argptr
指向参数列表的指针。
locale
要使用的区域设置。

有关更多信息，请参见格式规范。

返回值

vsnprintf、_vsnprintf和 _vsnwprintf 返回的字符的数量，则编写字符的数目小于或等于 count;如果编写的字符数大于 count，这些函数返回 -1 指示输出被截断。如果一种编写，返回值不包括终止 null。

如果buffer 或 format 是NULL，或数目小于等于零，这些函数将调用无效参数处理程序，正如参数验证所述。如果允许执行继续，则这些函数返回 -1 并将 errno 设置为 EINVAL。

备注

这些功能中的每一个采用指向参数列表的指针，然后布局和编写特定数据到count 字符由 buffer指向的内存。如果末尾有空间 (即，如果编写字符的数目小于 count)，将缓冲区以 null 结尾。

安全说明
确保 format 不是用户定义的字符串。有关更多信息，请参见避免缓冲区溢出。

备注

为了确保具有终止 null 的空间，请确保 count 大于缓冲区长度严格小于缓冲区并在调用函数之前 null。

vsnprintf 等同于 _vsnprintf。 vsnprintf 对于符合包括 ANSI 标准 _vnsprintf 用于保留向后兼容性。

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

在 C++ 中，这些函数具有模板重载，以调用这些函数的更新、更安全副本。有关更多信息，请参见安全模板重载。

一般文本例程映射

TCHAR.H 例程	未定义的 _UNICODE & 和 _MBCS	已定义 _MBCS	已定义 _UNICODE
_vsntprintf	_vsnprintf	_vsnprintf	_vsnwprintf
_vsntprintf_l	_vsnprintf_l	_vsnprintf_l	_vsnwprintf_l

要求

例程	必需的标头	可选标头
vsnprintf	<stdio.h> 和 <stdarg.h>	<varargs.h>*
_vsnprintf, _vsnprintf_l	<stdio.h> 和 <stdarg.h>	<varargs.h>*
_vsnwprintf, _vsnwprintf_l	<stdio.h> 或 <wchar.h> 和 <stdarg.h>	<varargs.h>*

* 仅对 UNIX V 兼容性是必需的。

有关其他兼容性信息，请参见“简介”中的兼容性。

示例

// 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!!");
}