`vsnprintf`、`_vsnprintf`、`_vsnprintf_l`、`_vsnwprintf`、`_vsnwprintf_l`

2025-06-21

使用指向參數清單的指標寫入格式化輸出。這些函數的更安全版本可用;見 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
要寫入的最大字元數。對於採用的 wchar_t函數，它是要寫入的寬字元數。

format
格式規範。

argptr
指向參數清單的指標。

locale
要使用的地區設定。

有關更多資訊，請參閱格式規範語法。

返回值

寫入的字元數，不包括 terminating NULL，如果發生輸出錯誤，則不包括負值。

如需詳細資訊，請參閱行為摘要。

備註

這些函數中的每一個都採用指向參數清單的指標，然後格式化數據，並將字元寫入 count 指向的 buffer記憶體。該 vsnprintf 函數始終寫入 null 終止符，即使它截斷了輸出。使用 _vsnprintf and _vsnwprintf時，僅當末尾有空間時（即，如果要寫入的字元數小於 count），緩衝區才會以 null 結尾。

自 Visual Studio 2015 及 Windows 10 的 UCRT 起， vsnprintf 即不再等同於 _vsnprintf。該 vsnprintf 函數符合 C99 標準; _vsnprintf 保留該函數是為了向後相容較舊的代碼。區別在於，如果緩衝區用完， vsnprintf 則以 null 終止緩衝區的末尾並返回所需的字元數，而不 _vsnprintf 以 null 終止緩衝區並返回 -1。此外， _vsnprintf() 在輸出中再包含一個字元，因為它不會以 Null 結束緩衝區。

這很重要

為了防止某些類型的安全風險，請確保它 format 不是使用者定義的字串。如需詳細資訊，請參閱 Avoiding Buffer Overruns (避免緩衝區滿溢)。從 Windows 10 版本 2004 (組建 19041) 開始，函式 printf 系列會根據 IEEE 754 規則來列印可精確表示的浮點數以進行四捨五入。在舊版的 Windows 中，「5」結尾的可精確表示浮點數一律會四捨五入。 IEEE 754指出，浮點數必須四捨五入到最接近的偶數位數 (也稱為「四捨六入五成雙」)。例如，printf("%1.0f", 1.5) 和 printf("%1.0f", 2.5) 應該四捨五入為 2。先前，1.5 會四捨五入為 2，而 2.5 會四捨五入為 3。這項變更只會影響可精確表示的位數。例如，2.35 (在記憶體中表示時會接近 2.35000000000000008) 會繼續四捨五入至 2.4。這些函式所完成的四捨五入現在也會遵守 fesetround 所設定的浮點數四捨五入模式。之前，四捨五入一律會選擇 FE_TONEAREST 行為。這項變更只會影響使用 Visual Studio 2019 16.2 版和更新版本所建置的程式。若要使用舊版浮點捨入行為，請與 legacy_stdio_float_rounding.obj連結。

備註

要確保在調用 _vsnprintf、、和 _vsnprintf_l_vsnwprintf_vsnwprintf_l 時有空間終止 null，請確保 count null 嚴格小於緩衝區長度，並在調用函數之前將緩衝區初始化為 null。

由於始終寫入終止 null，因此 vsnprintf 參數 count 可能等於緩衝區的大小。

這些帶有 _l 後綴的函數的版本是相同的，只是它們使用傳入的locale參數，而不是當前線程區域設置。

在 C++ 中，這些函數具有範本重載，用於調用這些函數的更新、安全的對應項。如需詳細資訊，請參閱安全範本多載。

行為摘要

下表：

讓 sizeOfBuffer 做為的大小 buffer。如果函式接受 char 緩衝區，大小會以位元組為單位。如果函式接受 wchar_t 緩衝區，大小會指定16位單字的數目。
讓我們 len 成為格式化數據的大小。如果函式接受 char 緩衝區，大小會以位元組為單位。如果函式接受 wchar_t 緩衝區，大小會指定16位單字的數目。
字元是指 char 採用 char 緩衝區的函式字元，以及 wchar_t 採用 wchar_t 緩衝區之函式的字元。
如需無效參數處理程式的詳細資訊，請參閱參數驗證。

狀況	行為	返回值	`errno`	叫用無效的參數處理常式
成功	使用指定的格式字串，將字元寫入緩衝區。	寫入的字元數，不計算終止 null 字元。	N/A	否
格式設定期間的編碼錯誤	如果處理字串說明符 `s`、 `S`、或 `Z`格式規範處理將停止。	-1	`EILSEQ` (42)	否
格式設定期間的編碼錯誤	如果處理字元規範 `c` 或 `C`，則會略過無效的字元。寫入的字元數目不會針對略過的字元遞增，也不會為它寫入任何數據。在略過規範並出現編碼錯誤之後，處理格式規格會繼續進行。	寫入的字元數，不包括終止 `NULL`的。	`EILSEQ` (42)	否
`buffer == NULL` 和 `count != 0`	如果在無效的參數處理程式執行之後繼續執行，請設定 `errno` 並傳回負值。	-1	`EINVAL` (22)	是的
`buffer == NULL` 和 `count == 0`	不寫入任何數據	已寫入的字元數，不包括終止 `NULL`的。您可以使用此結果，為字串和終止 `NULL`配置足夠的緩衝區空間，然後再次呼叫函式以填滿緩衝區。	N/A	否
`count == 0`	不寫入任何數據	-1	`ERANGE` (34)	否
`count < 0`	Unsafe：此值會被視為不帶正負號，因此可能會建立大型值，以覆寫緩衝區後面的記憶體。	寫入的字元數。	N/A	否
`count < sizeOfBuffer` 和 `len <= count`	所有數據都會寫入，並附加終止 `NULL` 。	寫入的字元數，不包括終止 `NULL`的。	N/A	否
`count < sizeOfBuffer` 和 `len > count`	第一 `count-1` 個字元的寫入後面接著 Null 終止符。	已寫入的字元數已 `count` 符合輸出的字元數，不包括 Null 終止符。	N/A	否
`count >= sizeOfBuffer` 和 `len < sizeOfBuffer`	所有數據都會以終止 `NULL`來寫入。	寫入的字元數，不包括終止 `NULL`的。	N/A	否
`count >= sizeOfBuffer` 和 `len >= sizeOfBuffer`	Unsafe：覆蓋緩衝區後面的記憶體。	寫入的字元數，不包括終止 `NULL`的。	N/A	否
`format == NULL`	未寫入任何數據。如果在無效的參數處理程式執行之後繼續執行，請設定 `errno` 並傳回負值。	-1	`EINVAL` (22)	是的

如需這些錯誤碼和其他錯誤碼的相關信息，請參閱_doserrno、 errno_sys_errlist和 _sys_nerr。

一般文字常式對應

`TCHAR.H` 常式	`_UNICODE` 和 `_MBCS` 未定義	`_MBCS` 已定義	`_UNICODE` 已定義
`_vsntprintf`	`_vsnprintf`	`_vsnprintf`	`_vsnwprintf`
`_vsntprintf_l`	`_vsnprintf_l`	`_vsnprintf_l`	`_vsnwprintf_l`

需求

常規	必須的標頭（C）	必需的標頭（C++）
`vsnprintf`、`_vsnprintf`、`_vsnprintf_l`	`<stdio.h>`	`<stdio.h>` 或 `<cstdio>`
`_vsnwprintf`、`_vsnwprintf_l`	`<stdio.h>` 或 `<wchar.h>`	`<stdio.h>`、`<wchar.h>`、`<cstdio>`或 `<cwchar>`

、 _vsnprintf_vsnprintf_l_vsnwprintf 和 _vsnwprintf_l 函數是特定於 Microsoft 的。如需相容性詳細資訊，請參閱相容性。

範例：使用 `_vsnwprintf()`

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput(L"%ls %ls", L"Hi", L"there");
    FormatOutput(L"%ls %ls", L"Hi", L"there!");
    FormatOutput(L"%ls %ls", L"Hi", L"there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

如果改用 vsnprintf 以及窄字串參數，則行為會發生變化。該 count 參數可以是緩衝區的整個大小，返回值是如果 count 足夠大，將寫入的字元數：

示例：與窄字串一起使用`vsnprintf()`

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

void FormatOutput(char* formatstring, ...)
{
    int nSize = 0;
    char buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    nSize = vsnprintf(buff, sizeof(buff), formatstring, args);
    printf("nSize: %d, buff: %s\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

另請參閱

資料流 I/O
vprintf 函數
 格式規範語法： printf 和 wprintf 函數
 fprintf、、 _fprintf_l、 fwprintf_fwprintf_l
printf、、 _printf_l、 wprintf_wprintf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_l
va_arg、、 va_copy、 va_endva_start

共用方式為

vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_l

語法

參數

返回值

備註

行為摘要

一般文字常式對應

需求

範例：使用 _vsnwprintf()

示例：與窄字串一起使用vsnprintf()

另請參閱

意見反應

其他資源

`vsnprintf`、`_vsnprintf`、`_vsnprintf_l`、`_vsnwprintf`、`_vsnwprintf_l`

範例：使用 `_vsnwprintf()`

示例：與窄字串一起使用`vsnprintf()`