sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Artykuł
06/09/2015

Wpisz sformatowane dane do ciągu.Są to wersje sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l ze wzmocnieniem zabezpieczeń, jak opisano w Funkcje zabezpieczeń w 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
Lokalizacja magazynowa danych wyjściowych
sizeOfBuffer
Maksymalna liczba znaków do zapisania.
format
Ciąg formantu formatu
argument
Argumenty opcjonalne
locale
Ustawienia regionalne do użycia.

Aby uzyskać więcej informacji na temat ciągów formatujących, zobacz Specyfikacje formatu.

Wartość zwracana

Liczba napisanych znaków lub –1, jeżeli wystąpił błąd.Jeśli buffer lub format jest wskaźnikiem zerowym, sprintf_s i swprintf_s zwracają -1 i ustawiają errno na EINVAL.

sprintf_s zwraca liczbę bajtów przechowywanych w buffer, nie licząc zamykającego znaku pustego.Funkcja swprintf_s zwraca liczbę znaków szerokich przechowywanych w parametrze buffer, nie licząc zamykającego dwubajtowego znaku pustego.

Uwagi

Funkcja sprintf_s formatuje i przechowuje serie znaków i wartości w buffer.Każdy argument (jeśli istnieje) jest konwertowaya i wychodzi według specyfikacji formatu w format.Format składa się ze znaków zwykłych i ma ten sam formularz i funkcję jak format argument dla printf.Znak null jest dołączany po ostatnim napisanym znaku.Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

Jedną z głównych różnic między sprintf_s i sprintf jest to, że sprintf_s sprawdza ciąg formatu dla prawidłowych znaków formatowania, podczas gdy sprintf sprawdza tylko, czy ciąg formatu lub bufor to wskaźniki NULL.Jeśli sprawdzenie zakończy się niepowodzeniem, zostanie wywołana procedura obsługi nieprawidłowego parametru, zgodnie z opisem w temacie Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, funkcja zwraca wartość -1 i ustawia errno na EINVAL.

Inną główną różnicą między sprintf_s i sprintf jest to, że sprintf_s przyjmuje parametr długości określający rozmiar bufora wyjściowego w znakach.Jeśli bufor jest za mały dla drukowanego tekstu, bufor zostaje ustawiony na ciąg pusty i zostaje wywołany program obsługi nieprawidłowego parametru.W przeciwieństwie do snprintf, sprintf_s gwarantuje, że bufor będzie zakończony zerem (chyba że rozmiar buforu jest równy zero).

swprintf_s jest to wersja szerokich znaków sprintf_s; argumenty wskaźnika do swprintf_s są ciągami szerokich znaków.Wykrywanie kodowania błędów w swprintf_s może się różnić w sprintf_s.Wersje tych funkcji z przyrostkiem _l są identyczne z wyjątkiem stosowania regionalnych parametrów zamiast bieżącego ciągu.

W języku programowania C++ korzystanie z tych funkcji jest uproszczone przez przeciążania szablonu; przeciążania mogą automatycznie wywnioskować długość buforu (tak, aby nie było konieczne określenie argumentu rozmiaru), ponadto te funkcje mogą automatycznie zastąpić starsze, niezabezpieczone funkcje nowszymi, bardziej bezpiecznymi odpowiednikami.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Istnieją wersje sprintf_s, które oferują dodatkową kontrolę nad tym, co się stanie, jeśli bufor jest za mały.Aby uzyskać więcej informacji, zobacz _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Wymagania

Procedura	Wymagany nagłówek
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> lub <wchar.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność we Wprowadzeniu.

Przykład

// 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 );
}