vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Artykuł
06/09/2015

Zapisz sformatowane dane wyjściowe za pomocą wskaźnika do listy argumentów.Są to wersje vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l ze wzmocnieniem zabezpieczeń, jak opisano w Funkcje zabezpieczeń w 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
Lokalizacja magazynowa danych wyjściowych.
sizeOfBuffer
Rozmiar buffer dla danych wyjściowych, jako liczba znaków.
count
Maksymalna liczba znaków do zapisu (z wyłączeniem zakończeń null) lub _TRUNCATE.
format
Format specyfikacji.
argptr
Wskaźnik na listę argumentów.
locale
Ustawienia regionalne do użycia.

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

Wartość zwracana

vsnprintf_s,_vsnprintf_s i _vsnwprintf_s zwraca liczbę zapisanych znaków, nie wliczając kończącego znaku null, lub wartość ujemną, jeśli wystąpi błąd danych wyjściowych.vsnprintf_s jest identyczna z _vsnprintf_s.vsnprintf_s jest dołączona dla zgodności ze standardem ANSI._vnsprintf jest zachowana dla zgodności z poprzednimi wersjami.

Jeśli magazyn wymagany do przechowywania danych i kończących znaków null przekracza sizeOfBuffer, wywołana zostanie procedura obsługi nieprawidłowego parametru, jak opisano w Sprawdzanie poprawności parametru, chyba że count jest równe _TRUNCATE, w którym to przypadku zostanie zapisana taka część ciągu, jaka zmieści się w buffer i zostanie zwrócona wartość -1.Jeśli wykonywanie jest kontynuowane po procedurze obsługi nieprawidłowego parametru, funkcje te ustawiają buffer na pusty ciąg, ustawiają errno na ERANGE i zwracają -1.

Jeśli buffer lub format jest wskaźnikiem NULL, lub jeśli count wynosi mniej niż zero, wywołana zostanie procedura obsługi nieprawidłowego parametru.Jeśli wykonanie może być kontynuowane, te funkcje ustawiają errno na EINVAL i zwracają wartość -1.

Warunki błędów

Condition	Zwrot	errno
buffer wynosi NULL	-1	EINVAL
format wynosi NULL	-1	EINVAL
count <= 0	-1	EINVAL
sizeOfBuffer jest zbyt mały (i count != _TRUNCATE)	-1 (i buffer ustawiany jest na pusty ciąg)	ERANGE

Uwagi

Każda z tych funkcji przyjmuje wskaźnik do listy argumentów, następnie formatuje i zapisuje do count znaków podanych danych do pamięci wskazywanej przez buffer i dołącza kończący znak null.

Jeśli count jest równe _TRUNCATE, funkcje te zapiszą taką część ciągu, jaka zmieści się w buffer, zostawiając miejsce na kończący znak null.Jeśli cały ciąg (z zakończeniem null) mieści się w buffer, funkcje te zwrócą liczbę zapisanych znaków (nie wliczając zakończeń null); w przeciwnym razie funkcje te zwrócą -1, aby wskazać, że wystąpiło obcięcie.

Wersje tych funkcji z przyrostkiem _l są identyczne z wyjątkiem stosowania regionalnych parametrów zamiast bieżącego ciągu.

Uwaga dotycząca zabezpieczeń
Zapewnienia, że format nie jest ciągiem zdefiniowanym przez użytkownika.Aby uzyskać więcej informacji, zobacz unikanie przekroczenia buforu.

[!UWAGA]

Aby upewnić się, że jest miejsce na kończący znak null, upewnij się, że count jest mniejsze niż długość buforu, lub użyj _TRUNCATE.

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.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE & _MBCS nie zdefiniowano	_MBCS zdefiniowano	_UNICODE zdefiniowany
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Odpowiednik w programie .NET Framework

Nie dotyczy. Aby wywołać standardową funkcję C, należy użyć PInvoke. Aby uzyskać więcej informacji, zobacz Przykłady wywoływania platformy.

Wymagania

Procedura	Wymagany nagłówek	Opcjonalne nagłówki
vsnprintf_s	<stdio.h> i <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> i <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> lub <wchar.h> i <stdarg.h>	<varargs.h>*

* Wymagane dla zgodności systemu UNIX V.

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

Przykład

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