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 不是使用者定義的字串。如需詳細資訊，請參閱 Avoiding Buffer Overruns 。

注意事項
若要確保會終止的空白空間，請確定 count 明顯小於緩衝區長度並初始化緩衝區初始化為空在呼叫函式之前。

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