vsnprintf_s， _vsnprintf_s， _vsnprintf_s_l， _vsnwprintf_s， _vsnwprintf_s_l

项目
02/21/2013

编写格式化输出使用指针参数列表。这些是 vsnprintf， _vsnprintf， _vsnprintf_l， _vsnwprintf， _vsnwprintf_l 的版本与安全增强的 CRT中的安全功能如中所述。

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
);
int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr 
);
int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr 
); // C++ only

参数

buffer
输出的存储位置。
sizeOfBuffer
buffer 的大小导出，以字节为单位)。
count
的最大字符数编写的 (不包括终止 null)，或者 _TRUNCATE。
format
格式规范。
argptr
列表的指针参数。
locale
使用的区域设置。

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

返回值

，如果输出错误，vsnprintf_s、_vsnprintf_s和 _vsnwprintf_s返回编写的字符数，不包括终止 null 或负值。 vsnprintf_s 与 _vsnprintf_s相同。 vsnprintf_s 用于标准包括于 ANSI 标准。 _vnsprintf 备向后兼容。

如果需要存储来存储数据和终止 null 超过 sizeOfBuffer，无效参数调用处理程序，如中所述，参数验证，除非 count 是， _TRUNCATE，在返回相同的许多字符串与将适合 buffer 编写情况下和 -1。如果对无效参数处理程序后继续，这些功能集 buffer 设置为空字符串，设置 errno 到 ERANGE，并返回 -1。

如果 buffer 或 format 是 NULL 指针，或者，如果 count 小于或等于零，无效参数调用处理程序。如果执行允许继续，对 EINVAL 的这些功能集 errno 并且返回 -1。

错误状态

Condition	Return	errno
buffer 是NULL	-1	EINVAL
format 是NULL	-1	EINVAL
count AMP_LT= 0	-1	EINVAL
太小sizeOfBuffer (和 count ! = _TRUNCATE)	-1 (和 buffer 设置为空字符串)	ERANGE

备注

这些功能中的每一个采用指向参数列表，然后设置格式并记载到 count 特定数据的字符到内存指向由 buffer 并追加终止 null。

如果 count 是 _TRUNCATE，则这些功能编写尽可能多地字符串与将适合 buffer ，当出终止 null 时空间。如果整个字符串 (与终止空) 适合 buffer这些函数，然后返回编写的字符数 (不包括终止 null);否则，这些函数返回 -1 指示截断发生。

这些功能的版本与 _l 后缀的相同，只不过它们使用区域设置参数而不是当前线程区域设置。

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

备注

为了确保具有停止的空白，请确保 count 大于缓冲区长度严格小于，或者使用 _TRUNCATE。

在 C++ 中，使用这些功能由模板重载简化;重载可推断缓冲区长度 (自动不再需要指定范围参数)，并且还可以用以较新，安全重复自动替换旧，不安全的功能。有关更多信息，请参见安全模板重载。

一般文本例程映射

TCHAR.H 实例	未定义的 _UNICODE _MBCS	定义的 _MBCS	定义的 _UNICODE
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

.NET Framework 等效项

不适用。若要调用标准 C 函数，请使用 PInvoke。有关更多信息，请参见平台调用示例。

要求

实例	必需的头	可选标头
vsnprintf_s	stdio.h 和 stdarg.h	varargs.h*
_vsnprintf_s, _vsnprintf_s_l	stdio.h 和 stdarg.h	varargs.h*
_vsnwprintf_s, _vsnwprintf_s_l	stdio.h 或者 wchar.h，和 stdarg.h	varargs.h*

* 仅对 UNIX v 兼容性。

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

示例

// crt_vsnprintf_s.cpp
#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_s( buff, sizeof(buff), _TRUNCATE, formatstring, args);
   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!!");
}