vsprintf_s、_vsprintf_s_l、vswprintf_s、_vswprintf_s_l

發行項
06/09/2015

使用指向一個引數清單的指標輸出格式化的字串這些是 vsprintf、_vsprintf_l、vswprintf、_vswprintf_l、__vswprintf_l 的安全性增強版本，如 CRT 中的安全性功能中所述。

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

參數

buffer
輸出的儲存位置。
numberOfElements
buffer 的大小 (以字元為單位)。
format
格式規範。
argptr
參數清單的指標。
locale
要使用的地區設定。

傳回值

vsprintf_s 和 vswprintf_s 回傳寫入的字元數，不包含結尾的空字元，或者在輸出發生錯誤時回傳一個負值。如果 buffer 或format為 null 指標，或是如果count是零，或是如果格式字串包含無效的格式化字元，則無效的參數會叫用處理常式，如參數驗證中所述。如果允許繼續執行，函式回傳 -1 並將 errno 設置為 EINVAL 。

如需有關這些錯誤碼和其他錯誤碼的詳細資訊，請參閱 _doserrno、errno、_sys_errlist 和 _sys_nerr。

備註

這些函式接受一個指向參數清單的指標，格式化並將給定的資料寫入到 buffer 所指向的記憶體。

vswprintf_s符合為vswprintf所設的ISO C語言標準，此標準要求第二個參數 count 的類型必須為 size_t。

這些函式與不安全版本的函式只差在安全版本支援位置參數。如需詳細資訊，請參閱printf_p 位置參數。

這些有 _l 尾碼的函式版本是一樣的，不同之處在於會使用傳入的地區設定，而不使用目前的執行緒地區設定。

C++ 利用多載樣板簡化了這些函式的使用方式。多載可自動推斷緩衝區長度 (因而不須指定大小引數)，也可以將不安全的舊函式自動取代成較新且安全的對應函式。如需詳細資訊，請參閱安全範本多載。

一般文字常式對應

TCHAR.H 常式	_UNICODE &_MBCS 未定義	_MBCS 已定義	_UNICODE 已定義
_vstprintf_s	vsprintf_s	vsprintf_s	vswprintf_s
_vstprintf_s_l	_vsprintf_s_l	_vsprintf_s_l	_vswprintf_s_l

需求

常式	必要的標頭	選擇性的標頭檔
vsprintf_s, _vsprintf_s_l	<stdio.h> 和 <stdarg.h>	<varargs.h>*
vswprintf_s, _vswprintf_s_l	<stdio.h> 或 <wchar.h>, 及 <stdarg.h>	<varargs.h>*

* 要求 UNIX V 相容性。

如需其他相容性資訊，請參閱＜簡介＞中的相容性。

範例

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

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