vsnprintf_s、 _vsnprintf_s、 _vsnprintf_s_l、 _vsnwprintf_s、 _vsnwprintf_s_l

發行項
02/28/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小於或等於為零，會叫用無效的參數處理常式。如果執行，則允許繼續執行，這些函式會設定errno到EINVAL ，並傳回-1。

錯誤狀況

Condition	Return	errno
buffer是 NULL	-1	EINVAL
format是 NULL	-1	EINVAL
count< = 0	-1	EINVAL
sizeOfBuffertoo small (and count != _TRUNCATE)	-1 (與buffer設定為空字串)	ERANGE

備註

每個函式會使用指標引數] 清單中，然後格式化並最多可寫入count所指的記憶體給指定的資料的字元buffer ，並將結尾的 null。

如果count是_TRUNCATE，接著這些函式撰寫字串填滿的buffer而保留空間給結尾的 null。如果整個字串 (與結尾的 null) 適合於buffer，那麼這些函數會傳回寫入 (不包括結尾的 null) ；的字元數否則，這些函數會傳回-1 則表示該截斷發生。

使用這些函式的版本_l尾碼完全相同，不同之處在於它們使用傳遞中而不是目前執行緒的地區設定的地區設定參數。

安全性提示
請確定format不是使用者定義的字串。如需詳細資訊，請參閱避免緩衝區滿溢，。

注意事項
若要確定預留結尾的 null，務必讓count是絕對小於緩衝區長度或使用_TRUNCATE。

在 C++ 中，使用這些函式已經過簡化的樣板的多載；多載可以自動推斷緩衝區長度 (而不必指定 size 引數)，它們可以自動取代較舊的、不安全的函式與其較新的、安全的對應項目。如需詳細資訊，請參閱安全範本多載。

泛用文字常式對應

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