sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Článek
06/09/2015

Zapište formátovaná data do řetězce.Tyto verze sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l s rozšířeními zabezpečení jsou popsány v tématu Funkce zabezpečení v CRT.

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument] ... 
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument]...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   locale_t locale [,
   argument]…
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only

Parametry

buffer
Umístění úložiště pro výstup
sizeOfBuffer
Maximální počet znaků pro uložení.
format
Řetězec řízení formátu
argument
Volitelné argumenty
locale
Použité národní prostředí.

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

Vrácená hodnota

Počet znaků zapsaných nebo –1, pokud došlo k chybě.Pokud buffer nebo format je nulový ukazatel, sprintf_s a swprintf_s vrátí -1 a nastaví errno na EINVAL.

sprintf_s vrátí počet bajtů, které jsou uloženy v buffer mimo ukončující znaky null.swprintf_s vrátí počet širokých znaků, které jsou uloženy v buffer. Do výčtu nebudou započteny ukončující široké znaky null.

Poznámky

Funkce sprintf_s formátuje a ukládá řadu znaků a hodnot v buffer.Každý argument (pokud existuje) je převeden podle odpovídající specifikace formátu v format.Formát se skládá z běžných znaků a má stejnou formu a funkci, jako argument format pro printf.Za poslední zadaný znak je připojen znak null.Pokud ke kopírování dojde mezi řetězci, které se překrývají, chování není definováno.

Jedním z hlavních rozdílů mezi sprintf_s a sprintf je to, že sprintf_s kontroluje v řetězci formátování platnost znaků formátování, zatímco sprintf zkontroluje pouze to, zda řetězec formát nebo vyrovnávací paměť jsou ukazatele NULL.Pokud kontrola selže, je vyvolána obslužná rutina neplatného parametru, jak je popsáno v Ověření parametru.Pokud provádění může pokračovat, funkce vrátí hodnotu -1 a nastaví errno na EINVAL.

Další hlavní rozdíl mezi sprintf_s a sprintf je v tom, že sprintf_s přebírá parametr délky se zadáním velikosti výstupní vyrovnávací paměti v počtu znaků.Pokud vyrovnávací paměť je příliš malá pro tisk textu, tak vyrovnávací paměť je nastavena na prázdný řetězec a je vyvolán neplatný parametr obslužné rutiny.Na rozdíl od snprintf, sprintf_s zaručuje, že vyrovnávací paměť bude zakončena hodnotou null (pokud není velikost vyrovnávací paměti nulová).

swprintf_s je širokoznaká verze sprintf_s. Argumenty ukazatele pro swprintf_s jsou širokoznaké řetězce.Detekce chyb kódování v swprintf_s se může lišit od detekce v sprintf_s.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.

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.

Existují verze sprintf_s, které nabízejí další možnosti kontroly nad tím, co se stane, pokud je vyrovnávací paměť příliš malá.Další informace naleznete v tématu _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Rutinní mapování obecného textu

Rutina TCHAR.H	_UNICODE & _MBCS není definováno	_MBCS definováno	_UNICODE definováno
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Požadavky

Rutina	Požadované záhlaví
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> nebo <wchar.h>

Další informace o kompatibilitě naleznete v úvodu tématu Kompatibilita.

Příklad

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data: 
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}