`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, , `_vsnwprintf_s_vsnwprintf_s_l`

2025-06-21

Formátovaný výstup zapište pomocí ukazatele na seznam argumentů. Jedná se o vsnprintfverze , _vsnprintf, , _vsnprintf_l_vsnwprintf, s _vsnwprintf_l vylepšeními zabezpečení, jak je popsáno v části Funkce zabezpečení v CRT.

Syntaxe

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

Parametry

buffer
Umístění úložiště pro výstup.

sizeOfBuffer
buffer Velikost výstupu for. Velikost v bajtech pro funkce, které berou char, a slova pro ty, které berou wchar_t.

count
Maximální počet znaků k zápisu bez ukončujícího NULL. U funkcí, které berou wchar_t, je to počet širokých znaků, které se mají zapsat. Nebo _TRUNCATE.

format
Specifikace formátu.

argptr
Ukazatel na seznam argumentů.

locale
Národní prostředí, které se má použít při formátování výstupu.

Další informace naleznete v části Specifikace formátu.

Návratová hodnota

Počet zapsaných znaků, bez započtení ukončující NULL, nebo záporné hodnoty, pokud dojde k chybě výstupu.

Podrobnosti najdete v souhrnu chování.

Poznámky

Každá z těchto funkcí přebírá ukazatel na seznam argumentů, poté formátuje a zapisuje až znaky count daných dat do paměti, na kterou odkazuje, buffer a připojuje ukončující NULL.

V sestaveních ladění jsou zbývající sizeOfBuffer bajty následující po ukončení NULL vyplněny 'xFE', jak je popsáno v ._CrtSetDebugFillThreshold

Verze těchto funkcí s příponou _l jsou identické s tím rozdílem, že používají předaný parametr locale namísto aktuálního národního prostředí vlákna.

vsnprintf_s je identický s _vsnprintf_s normou ANSI a je zahrnut pro shodu s ní. _vnsprintf je zachován kvůli zpětné kompatibilitě.

Souhrn chování

Pro následující tabulku:

Nechte len velikost formátovaných dat. Pokud funkce vezme char vyrovnávací paměť, velikost je v bajtech. Pokud funkce vezme wchar_t vyrovnávací paměť, velikost určuje počet 16bitových slov.
Znaky odkazují na char znaky pro funkce, které přebírají char vyrovnávací paměť, a na wchar_t znaky pro funkce, které přebírají wchar_t vyrovnávací paměť.
Další informace o neplatné obslužné rutině parametru naleznete v tématu Ověření parametru.

Podmínka	Chování	Návratová hodnota	`errno`	Vyvolá neplatnou obslužnou rutinu parametru.
Úspěch	Zapíše znaky do vyrovnávací paměti pomocí určeného formátovacího řetězce	Počet zapsaných znaků	není k dispozici	Ne
Chyba kódování během formátování	Pokud zpracováváte specifikátor `s`řetězce , `S`, nebo `Z`, zpracování specifikace formátu se zastaví.	-1	`EILSEQ (42)`	Ne
Chyba kódování během formátování	Pokud specifikátor `c` znaku zpracování nebo `C`, je neplatný znak vynechán. Počet zapsaných znaků se pro přeskočený znak nezvýšuje, ani se pro něj nezapisují žádná data. Zpracování specifikace formátu pokračuje po vynechání specifikátoru s chybou kódování.	Počet zapsaných znaků, včetně ukončení `NULL`.	`EILSEQ (42)`	Ne
`buffer == NULL` a `sizeOfBuffer == 0` dále `count == 0`	Nezapisuje se žádná data.	0	není k dispozici	Ne
`buffer == NULL` a buď `sizeOfBuffer != 0` nebo `count != 0`	Pokud provádění pokračuje po spuštění neplatné obslužné rutiny parametru, nastaví `errno` a vrátí zápornou hodnotu.	-1	`EINVAL` (22)	Ano
`buffer != NULL` a `sizeOfBuffer == 0`	Nezapisuje se žádná data. Pokud provádění pokračuje po spuštění neplatné obslužné rutiny parametru, nastaví `errno` a vrátí zápornou hodnotu.	-1	`EINVAL` (22)	Ano
`buffer != NULL` a `sizeOfBuffer != 0` dále `count == 0`	Vyrovnávací paměť je `NULL` ukončena.	-1	není k dispozici	Ne
`count == 0`	Nezapisuje žádná data a vrací počet znaků, které by byly zapsány, bez ukončujícího `NULL`znaku .	Počet znaků, které by byly zapsány bez ukončujícího `NULL`znaku .	není k dispozici	Ne
`count < 0`	Nebezpečné: Hodnota je považována za nepodepsanou, což pravděpodobně vytvoří velkou hodnotu, která vede k přepsání paměti, která následuje za vyrovnávací pamětí.	Počet zapsaných znaků, včetně ukončení `NULL`.	není k dispozici	Ne
`count < sizeOfBuffer` a `len <= count`	Všechna data se zapíšou a připojí se ukončení `NULL` .	Počet zapsaných znaků.	není k dispozici	Ne
`count < sizeOfBuffer` a `len > count`	Zapíšou se první `count` znaky.	-1	není k dispozici	Ne
`count >= sizeOfBuffer` a `len < sizeOfBuffer`	Všechna data jsou zapsána s ukončením `NULL`.	Počet zapsaných znaků, včetně ukončení `NULL`.	není k dispozici	Ne
`count >= sizeOfBuffer` a `len >= sizeOfBuffer` dále `count != _TRUNCATE`	Pokud provádění pokračuje i po provedení neplatného parametru, obslužná `errno`rutina nastaví , nastaví `buffer[0] == NULL`a vrátí zápornou hodnotu.	-1	`ERANGE` (34)	Ano
`count == _TRUNCATE` a `len >= sizeOfBuffer`	Zapíše tolik řetězce, kolik se do `buffer`něj vejde, včetně ukončovacího `NULL`.	-1	není k dispozici	Ne
`count == _TRUNCATE` a `len < sizeOfBuffer`	Zapíše celý řetězec do `buffer` s ukončujícím `NULL`.	Počet zapsaných znaků.	není k dispozici	Ne
`format == NULL`	Nezapisuje se žádná data. Pokud provádění pokračuje po spuštění neplatné obslužné rutiny parametru, nastaví `errno` a vrátí zápornou hodnotu.	-1	`EINVAL` (22)	Ano

Informace o těchto a dalších kódech chyb naleznete v tématu _doserrnoerrno . _sys_errlist_sys_nerr

Důležité

Ujistěte se, že format není uživatelem definovaný řetězec. Další informace najdete v tématu Zabránění přetečení vyrovnávací paměti. Počínaje Windows 10 verze 2004 (build 19041) printf vytiskne řada funkcí přesně reprezentovatelná čísla s plovoucí desetinnou čárkou podle pravidel IEEE 754 pro zaokrouhlování. V předchozích verzích Windows by se vždy zaokrouhlila přesně reprezentovatelná čísla s plovoucí desetinnou čárkou končící na 5. IEEE 754 uvádí, že musí zaokrouhlit na nejbližší sudou číslici (označované také jako "Zaokrouhlování bankera"). Například obě printf("%1.0f", 1.5) a printf("%1.0f", 2.5) měly by se zaokrouhlit na 2. Dříve by se 1,5 zaokrouhlo na 2 a 2,5 by se zaokrouhlilo na 3. Tato změna má vliv jenom na přesně reprezentovatelná čísla. Například hodnota 2,35 (která je při znázornění v paměti blíže 2,350000000000008) pokračuje zaokrouhlit nahoru na 2,4. Zaokrouhlování provedené těmito funkcemi nyní respektuje také režim zaokrouhlování s plovoucí desetinou čárkou nastavený .fesetround Dříve bylo zaokrouhlení vždy zvoleno FE_TONEAREST chování. Tato změna má vliv jenom na programy vytvořené pomocí sady Visual Studio 2019 verze 16.2 a novější. Chcete-li použít starší chování zaokrouhlování s plovoucí desetinou čárkou, propojte s legacy_stdio_float_rounding.obj.

Poznámka:

Abyste zajistili, že je zde prostor pro zakončení NULL, ujistěte se, že count je striktně menší než délka vyrovnávací paměti, nebo použijte _TRUNCATE.

V jazyce C++ je používání těchto funkcí zjednodušeno přetížením šablony; Přetížení mohou automaticky odvodit délku vyrovnávací paměti (což eliminuje potřebu specifikovat argument velikosti) a mohou automaticky nahradit starší, nezabezpečené funkce jejich novějšími a bezpečnými protějšky. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Návod

Pokud se zobrazí nedefinovaná externí _vsnprintf_s chyba a používáte modul Universal C Runtime, přidejte legacy_stdio_definitions.lib ji do sady knihoven, které chcete propojit. Modul Universal C Runtime tuto funkci neexportuje přímo, ale je definován jako vložený v <stdio.h>. Další informace naleznete v tématu Přehled potenciálních problémů s upgradem a změny shody sady Visual Studio 2015.

Mapování rutin obecného textu

`TCHAR.H` rutina	`_UNICODE` a `_MBCS` není definován	`_MBCS` definovaný	`_UNICODE` definovaný
`_vsntprintf_s`	`_vsnprintf_s`	`_vsnprintf_s`	`_vsnwprintf_s`
`_vsntprintf_s_l`	`_vsnprintf_s_l`	`_vsnprintf_s_l`	`_vsnwprintf_s_l`

Požadavky

Rutina	Požadovaný hlavičkový soubor	Volitelná záhlaví
`vsnprintf_s`	`<stdio.h>` a `<stdarg.h>`	`<varargs.h>`*
`_vsnprintf_s`, `_vsnprintf_s_l`	`<stdio.h>` a `<stdarg.h>`	`<varargs.h>`*
`_vsnwprintf_s`, `_vsnwprintf_s_l`	`<stdio.h>` nebo `<wchar.h>`, a `<stdarg.h>`	`<varargs.h>`*

* Vyžadováno pro kompatibilitu se systémem UNIX V.

Další informace o kompatibilitě najdete v tématu Kompatibilita.

Příklad

// 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, _countof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
   va_end(args);
}

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

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

Viz také

Vstupně-výstupní operace streamu
vprintf funkce
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