`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`

發行項
07/04/2023

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

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

傳回值

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

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

備註

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

自 Visual Studio 2015 及 Windows 10 的 UCRT 起， vsnprintf 即不再等同於 _vsnprintf。函 vsnprintf 式符合 C99 標準; _vnsprintf 為了與舊版程式碼保持回溯相容性，差異在於，如果您用完緩衝區， vsnprintf null 會終止緩衝區的結尾，並傳回所需的字元數，但 _vsnprintf 不會以 null 終止緩衝區並傳回 -1。此外， _vsnprintf() 在輸出中包含一個以上的字元，因為它不會以 Null 結束緩衝區。

重要

若要防止特定類型的安全性風險，請確定 format 不是使用者定義的字串。如需詳細資訊，請參閱避免緩衝區溢位。從 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.350000000000000008) 會繼續四捨五入至 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 字元。
如需無效參數處理常式的詳細資訊，請參閱參數驗證。

條件	行為	傳回值	`errno`	叫用無效的參數處理常式
Success	使用指定的格式字串，將字元寫入緩衝區。	寫入的字元數，不會計算終止 Null 字元。	N/A	否
格式化期間的編碼錯誤	如果處理字串規範 `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	否
`count < 0`	不安全：此值會被視為不帶正負號，可能會建立大型值，以覆寫緩衝區後面的記憶體。	寫入的字元數。	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)	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 特定的。如需詳細的相容性資訊，請參閱 Compatibility。

範例：搭配使用寬字元 `_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_end, va_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()`