vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Článek
06/09/2015

Zapíše formátovaný výstup pomocí ukazatele na seznam argumentů.Tyto verze funkcí vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l s rozšířeními zabezpečení jsou popsány v tématu Funkce zabezpečení v CRT.

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
Počet znaků parametru buffer pro výstup.
count
Maximální počet znaků pro zápis (nezahrnuje ukončující znak null) nebo konstanta _TRUNCATE.
format
Specifikace formátu.
argptr
Ukazatel na seznam argumentů.
locale
Použité národní prostředí.

Další informace naleznete v tématu Specifikace formátu.

Vrácená hodnota

Funkce vsnprintf_s,_vsnprintf_s a _vsnwprintf_s vrátí počet zapsaných znaků, bez ukončujícího znaku null, nebo zápornou hodnotu, dojde-li k chybě výstupu.Funkce vsnprintf_s je shodná s funkcí _vsnprintf_s.Funkce vsnprintf_s je součástí shody se standardem ANSI.Funkce _vnsprintf je zachována z důvodu zpětné kompatibility.

Pokud místo na disku požadované pro uložení dat a ukončujícího znaku null překročí velikost parametru sizeOfBuffer, je vyvolána obslužná rutina neplatného parametru, jak je popsáno v tématu Ověření parametru, pokud parametr count není konstanta _TRUNCATE, přičemž největší část řetězce, která se vejde do parametru buffer je zapsána a je vrácena hodnota -1.Pokud běh programu po obslužné rutině neplatného parametru pokračuje, nastaví tyto funkce parametr buffer na prázdný řetězec, parametr errno nastaví na hodnotu ERANGEa vrátí -1.

Pokud má parametr buffer nebo format hodnotu NULL nebo pokud je parametr count menší nebo roven nule, je vyvolána obslužná rutina neplatného parametru.Pokud smí provádění pokračovat, tyto funkce nastaví errno na EINVAL a vrátí -1.

Chybové podmínky

Condition	Výsledek	errno
Parametr buffer je NULL.	-1	EINVAL
Parametr format je NULL.	-1	EINVAL
count <= 0	-1	EINVAL
Parametr sizeOfBuffer je příliš malý (a parametr count != _TRUNCATE)	-1 (a parametr buffer nastaven na prázdný řetězec)	ERANGE

Poznámky

Každá z těchto funkcí přebírá ukazatel na seznam argumentů, potom provede formátování a zapíše počet znaků určených parametrem count do paměti, kam odkazuje parametr buffer a připojí ukončující znak null.

Pokud má parametr count hodnotu _TRUNCATE, tyto funkce zapíší co největší část řetězce, který se vejde do parametru buffer a ponechají prostor pro ukončující znak null.Pokud se do parametru buffer vejde celý řetězec (s ukončujícím znakem null), tyto funkce vrací počet zapsaných znaků (nezahrnuje ukončující znak null), v opačném případě tyto funkce vrátí -1, což označuje, že došlo ke zkrácení.

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

Poznámka k zabezpečení
Zajistěte, aby format nebyl uživatelem definovaný řetězec.Další informace naleznete v tématu Předcházení přetečení vyrovnávací paměti.

[!POZNÁMKA]

Abyste se ujistili, že existuje místo pro ukončující znak null, mějte jistotu, že parametr count je menší než velikost vyrovnávací paměti nebo použijte konstantu _TRUNCATE.

V jazyce C++ je použití těchto funkcí zjednodušeno díky přetížení šablon; přetížení dokáží odvodit velikost vyrovnávací paměti automaticky (tak, že eliminují potřebu zadat argument velikosti) a automaticky nahradit starší, nezabezpečené funkce jejími novějšími, bezpečnějšími protějšky.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Rutinní mapování obecného textu

Rutina TCHAR.H	_UNICODE & _MBCS není definováno	_MBCS definováno	_UNICODE definováno
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Ekvivalent v rozhraní .NET Framework

Nelze použít. Pokud chcete volat standardní funkci jazyka C, použijte PInvoke. Další informace naleznete v tématu Příklady vyvolání platformy.

Požadavky

Rutina	Požadované záhlaví	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>*

* Potřebné k zajištění kompatibility systému UNIX V.

Další informace o kompatibilitě naleznete v úvodu 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);
}

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