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

發行項
08/03/2024

使用引數清單的指標，寫入格式化輸出。這些函式有更安全的版本可供使用;請參閱、、_vsnprintf_s、、_vsnwprintf_s。vsnprintf_s_vsnwprintf_s_l_vsnprintf_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
要使用的地區設定。

如需詳細資訊，請參閱格式規格語法。

傳回值

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

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

備註

其中每個函式都會接受引數清單的指標，然後格式化資料，並將最多 count 字元寫入 buffer所指向的記憶體。 vsnprintf 函式一律會寫入 null 結束字元，即使會截斷輸出亦同。當您使用 _vsnprintf 和 _vsnwprintf時，只有在結尾有空間時，緩衝區才會以 Null 終止（也就是說，如果要寫入的字元數小於 count）。

自 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、 _vsnwprintf _vsnprintf_l和 _vsnwprintf_l時有終止 Null 的空間，請務必count嚴格小於緩衝區長度，並在呼叫函式之前將緩衝區初始化為 Null。

因為 vsnprintf 一律會寫入終止 Null， count 因此參數可能等於緩衝區的大小。

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

在 C++ 中，這些函式具有樣板多載，可以叫用這些函式的更新且安全的對應版本。如需詳細資訊，請參閱安全範本多載。

行為摘要

下表：

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

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

如需這些錯誤碼和其他錯誤碼的相關信息，請參閱_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()

另請參閱

意見反應

其他資源

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

範例：搭配使用寬字元 `_vsnwprintf()`

範例：搭配窄字串使用`vsnprintf()`