vsprintf_s、_vsprintf_s_l、vswprintf_s、_vswprintf_s_lvsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l

使用指向参数列表的指针写入格式化的输出。Write formatted output using a pointer to a list of arguments. 这些版本的 vsprintf、_vsprintf_l、vswprintf、_vswprintf_l、__vswprintf_l 具有安全增强功能,如 CRT 中的安全功能所述。These are versions of vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l with security enhancements as described in Security Features in the CRT.

语法Syntax

int vsprintf_s(  
   char *buffer,  
   size_t numberOfElements,  
   const char *format,  
   va_list argptr   
);   
int _vsprintf_s_l(  
   char *buffer,  
   size_t numberOfElements,  
   const char *format,  
   locale_t locale,  
   va_list argptr   
);   
int vswprintf_s(  
   wchar_t *buffer,  
   size_t numberOfElements,  
   const wchar_t *format,  
   va_list argptr   
);  
int _vswprintf_s_l(  
   wchar_t *buffer,  
   size_t numberOfElements,  
   const wchar_t *format,  
   locale_t locale,  
   va_list argptr   
);  
template <size_t size>  
int vsprintf_s(  
   char (&buffer)[size],  
   const char *format,  
   va_list argptr   
); // C++ only  
template <size_t size>  
int vswprintf_s(  
   wchar_t (&buffer)[size],  
   const wchar_t *format,  
   va_list argptr   
); // C++ only  

参数Parameters

buffer
输出的存储位置Storage location for output.

numberOfElements
buffer 的大小(以字符为单位)。Size of buffer in characters.

format
格式规范。Format specification.

argptr
指向参数列表的指针。Pointer to list of arguments.

locale
要使用的区域设置。The locale to use.

返回值Return Value

vsprintf_svswprintf_s 返回写入的字符数,不包括终止的 null 字符;如果发生输出错误,则返回负值。vsprintf_s and vswprintf_s return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. 如果 bufferformat 为 null 指针、计数为零或者格式字符串包含无效的格式字符,则将调用无效参数处理程序,如参数验证中所述。If buffer or format is a null pointer, if count is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in Parameter Validation. 如果允许执行继续,则这些函数将返回 -1 并将 errno 设置为 EINVALIf execution is allowed to continue, the functions return -1 and set errno to EINVAL.

有关这些代码及其他错误代码的信息,请参阅 _doserrno、errno、_sys_errlist 和 _sys_nerrFor information on these and other error codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

备注Remarks

这些函数中的每一个函数都将采用指向参数列表的指针,然后设置给定数据的格式并将其写入 buffer 指向的内存中。Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by buffer.

vswprintf_s 符合 vswprintf 的 ISO C 标准,它需要类型为的 size_t 第二个参数 countvswprintf_s conforms to the ISO C Standard for vswprintf, which requires the second parameter, count, of type size_t.

这些函数与不安全版本的差异仅在于安全版本支持位置参数。These functions differ from the non-secure versions only in that the secure versions support positional parameters. 有关详细信息,请参阅 printf_p 位置参数For more information, see printf_p Positional Parameters.

这些带有 _l 后缀的函数的版本相同,只不过它们使用传递的区域设置参数而不是当前线程区域设置。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.

在 C++ 中,使用这些函数由模板重载简化;重载可以自动推导出缓冲区长度 (不再需要指定大小自变量),并且它们可以自动用以更新、更安全的对应物替换旧的、不安全的函数。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

一般文本例程映射Generic-Text Routine Mappings

TCHAR.H 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_vstprintf_s vsprintf_s vsprintf_s vswprintf_s
_vstprintf_s_l _vsprintf_s_l _vsprintf_s_l _vswprintf_s_l

惠?Requirements

例程所返回的值Routine 必需的标头Required header 可选标头Optional headers
vsprintf_s, _vsprintf_s_lvsprintf_s, _vsprintf_s_l <stdio.h> 和 <stdarg.h><stdio.h> and <stdarg.h> <varargs.h>*<varargs.h>*
vswprintf_s, _vswprintf_s_lvswprintf_s, _vswprintf_s_l <stdio.h> 或 <wchar.h> 和 <stdarg.h><stdio.h> or <wchar.h>, and <stdarg.h> <varargs.h>*<varargs.h>*

\* 仅对 UNIX V 兼容性是必需的。\* Required for UNIX V compatibility.

有关其他兼容性信息,请参见“简介”中的 兼容性For additional compatibility information, see Compatibility in the Introduction.

示例Example

// crt_vsprintf_s.c  
// This program uses vsprintf_s to write to a buffer.  
// The size of the buffer is determined by _vscprintf.  

#include <stdlib.h>  
#include <stdarg.h>  

void test( char * format, ... )  
{  
   va_list args;  
   int len;  
   char * buffer;  

   va_start( args, format );  
   len = _vscprintf( format, args ) // _vscprintf doesn't count  
                               + 1; // terminating '\0'  
   buffer = malloc( len * sizeof(char) );  
   vsprintf_s( buffer, len, format, args );  
   puts( buffer );  
   free( buffer );
   va_end( args );  
}  

int main( void )  
{  
   test( "%d %c %d", 123, '<', 456 );  
   test( "%s", "This is a string" );  
}  
123 < 456  
This is a string  

请参阅See Also

流 I/O Stream I/O
vprintf 函数 vprintf Functions
格式规范语法:printf 和 wprintf 函数 Format Specification Syntax: printf and wprintf Functions
fprintf、_fprintf_l、fwprintf、_fwprintf_l fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf、_printf_l、wprintf、_wprintf_l printf, _printf_l, wprintf, _wprintf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg、va_copy、va_end、va_startva_arg, va_copy, va_end, va_start