vsnprintf_s, , _vsnprintf_s, _vsnprintf_s_l, , _vsnwprintf_s_vsnwprintf_s_l

Zapis sformatowanych danych wyjściowych przy użyciu wskaźnika do listy argumentów. Te funkcje to wersje , vsnprintf, _vsnprintf_l_vsnprintf, _vsnwprintf_vsnwprintf_l z ulepszeniami zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w środowisku CRT.

Składnia

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 magazynu dla danych wyjściowych.

sizeOfBuffer
Rozmiar elementu dla danych wyjściowych buffer . Rozmiar w bajtach dla funkcji, które przyjmują char, i wyrazy dla tych, które przyjmują wchar_t.

count
Maksymalna liczba znaków do zapisu, które nie obejmują zakończenia .NULL W przypadku funkcji, które przyjmują wchar_t, jest to liczba znaków szerokich do zapisania. Lub _TRUNCATE.

format
Specyfikacja formatu.

argptr
Wskaźnik do listy argumentów.

locale
Ustawienia regionalne do użycia podczas formatowania danych wyjściowych.

Aby uzyskać więcej informacji, zobacz Specyfikacje formatu.

Wartość zwracana

Liczba zapisanych znaków, a nie w tym zakończenie NULLlub wartość ujemna, jeśli wystąpi błąd wyjściowy.

Aby uzyskać szczegółowe informacje, zobacz Podsumowanie zachowania.

Uwagi

vsnprintf_s jest identyczny z _vsnprintf_s i jest dołączony do zgodności ze standardem ANSI. _vnsprintf jest zachowywany w celu zachowania zgodności z poprzednimi wersjami.

Każda z tych funkcji przyjmuje wskaźnik do listy argumentów, a następnie formatuje i zapisuje count znaki danych do pamięci wskazywanej przez buffer i dołącza wartość null zakończenia.

Wersje tych funkcji z sufiksem _l są identyczne, z tą różnicą, że używają parametru ustawień regionalnych przekazanych zamiast bieżących ustawień regionalnych wątku.

Podsumowanie zachowania

W poniższej tabeli:

• Pozwól len na rozmiar sformatowanych danych. Jeśli funkcja przyjmuje char bufor, rozmiar jest w bajtach. Jeśli funkcja przyjmuje wchar_t bufor, rozmiar określa liczbę 16-bitowych wyrazów.
• Znaki odwołują się do char znaków funkcji, które przyjmują char bufor, oraz do wchar_t znaków funkcji, które przyjmują wchar_t bufor.
• Aby uzyskać więcej informacji na temat nieprawidłowej procedury obsługi parametrów, zobacz Walidacja parametrów.

Stan	Zachowanie	Wartość zwracana	errno	Wywołuje nieprawidłową procedurę obsługi parametrów
Powodzenie	Zapisuje znaki w buforze przy użyciu określonego ciągu formatu	Liczba zapisanych znaków	Nie dotyczy	Nie.
Błąd kodowania podczas formatowania	Jeśli przetwarzanie specyfikatora sciągów , Slub Z, przetwarzanie specyfikacji formatu zatrzymuje się.	-1	EILSEQ (42)	Nie.
Błąd kodowania podczas formatowania	Jeśli specyfikator c znaków przetwarzania lub C, jest pomijany nieprawidłowy znak. Liczba zapisanych znaków nie jest zwiększana dla pominiętego znaku ani żadnych zapisanych dla niego danych. Przetwarzanie specyfikacji formatu jest kontynuowane po pomijaniu specyfikatora z błędem kodowania.	Liczba zapisanych znaków, a nie łącznie z kończeniem NULL.	EILSEQ (42)	Nie.
buffer == NULLi i sizeOfBuffer == 0count == 0	Żadne dane nie są zapisywane.	0	Nie dotyczy	Nie.
buffer == NULL i albo sizeOfBuffer != 0 lub count != 0	Jeśli wykonanie będzie kontynuowane po wykonaniu nieprawidłowego programu obsługi parametrów, ustawia errno i zwraca wartość ujemną.	-1	EINVAL (22)	Tak
buffer != NULL i sizeOfBuffer == 0	Żadne dane nie są zapisywane. Jeśli wykonanie będzie kontynuowane po wykonaniu nieprawidłowego programu obsługi parametrów, ustawia errno i zwraca wartość ujemną.	-1	EINVAL (22)	Tak
count == 0	Nie zapisuje żadnych danych i zwraca liczbę znaków, które zostałyby zapisane, a nie w tym terminowanie NULL.	Liczba znaków, które zostałyby zapisane, nie obejmują zakończenia NULL.	Nie dotyczy	Nie.
count < 0	Niebezpieczne: wartość jest traktowana jako niepodpisane, prawdopodobnie tworząc dużą wartość, która powoduje zastąpienie pamięci, która następuje po buforze.	Liczba zapisanych znaków, a nie łącznie z kończeniem NULL.	Nie dotyczy	Nie.
count < sizeOfBuffer i len <= count	Wszystkie dane są zapisywane i dołączane są kończenie NULL .	Liczba zapisanych znaków.	Nie dotyczy	Nie.
count < sizeOfBuffer i len > count	count Pierwsze znaki są zapisywane.	-1	Nie dotyczy	Nie.
count >= sizeOfBuffer i len < sizeOfBuffer	Wszystkie dane są zapisywane z kończeniem NULL.	Liczba zapisanych znaków, a nie łącznie z kończeniem NULL.	Nie dotyczy	Nie.
count >= sizeOfBufferi i len >= sizeOfBuffercount != _TRUNCATE	Jeśli wykonanie będzie kontynuowane po wykonaniu nieprawidłowego programu obsługi parametrów, ustawia errno, ustawia buffer[0] == NULLwartości i zwraca wartość ujemną.	-1	ERANGE (34)	Tak
count == _TRUNCATE i len >= sizeOfBuffer	Zapisuje tyle ciągów, ile pasuje do ciągu , w buffertym zakończenia .NULL	-1	Nie dotyczy	Nie.
count == _TRUNCATE i len < sizeOfBuffer	Zapisuje cały ciąg w pliku buffer z kończeniem NULL.	Liczba zapisanych znaków.	Nie dotyczy	Nie.
format == NULL	Żadne dane nie są zapisywane. Jeśli wykonanie będzie kontynuowane po wykonaniu nieprawidłowego programu obsługi parametrów, ustawia errno i zwraca wartość ujemną.	-1	EINVAL (22)	Tak

Aby uzyskać informacje o tych i innych kodach błędów, zobacz _doserrno, errno, _sys_errlisti _sys_nerr.

Ważne

Upewnij się, że format nie jest to ciąg zdefiniowany przez użytkownika. Aby uzyskać więcej informacji, zobacz Unikanie przekroków buforu. Począwszy od systemu Windows 10 w wersji 2004 (kompilacja 19041), printf rodzina funkcji drukuje dokładnie możliwe liczby zmiennoprzecinkowe zgodnie z regułami IEEE 754 dotyczącymi zaokrąglania. W poprzednich wersjach systemu Windows dokładnie reprezentowane liczby zmiennoprzecinkowe kończące się na "5" zawsze zaokrągla się w górę. IEEE 754 stwierdza, że muszą zaokrąglić do najbliższej parzysta cyfra (znana również jako "Zaokrąglanie Bankiera"). Na przykład oba printf("%1.0f", 1.5) printf("%1.0f", 2.5) elementy i powinny być zaokrąglone do 2. Wcześniej 1,5 zaokrągliłoby się do 2 i 2,5 do 3. Ta zmiana dotyczy tylko dokładnie możliwych do reprezentowania liczb. Na przykład 2,35 (który, gdy jest reprezentowany w pamięci, jest bliżej 2,350000000000000008) nadal zaokrągla się do 2,4. Zaokrąglanie wykonywane przez te funkcje jest teraz również zgodne z trybem zaokrąglania zmiennoprzecinkowego ustawionym przez fesetround. Wcześniej zaokrąglanie zawsze wybierało FE_TONEAREST zachowanie. Ta zmiana dotyczy tylko programów utworzonych przy użyciu programu Visual Studio 2019 w wersji 16.2 lub nowszej. Aby użyć starszego zachowania zaokrąglania zmiennoprzecinkowego, połącz się z elementem "legacy_stdio_float_rounding.obj".

Uwaga

Aby upewnić się, że istnieje miejsce na zakończenie wartości null, upewnij się, że count jest ona ściśle mniejsza niż długość buforu lub użyj polecenia _TRUNCATE.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Napiwek

Jeśli wystąpi niezdefiniowany błąd zewnętrzny _vsnprintf_s i używasz uniwersalnego środowiska uruchomieniowego języka C, dodaj legacy_stdio_definitions.lib do zestawu bibliotek, aby utworzyć link. Środowisko uruchomieniowe uniwersalnego języka C nie eksportuje tej funkcji bezpośrednio i zamiast tego jest definiowane w tekście w pliku <stdio.h>. Aby uzyskać więcej informacji, zobacz Omówienie potencjalnych problemów z uaktualnieniem i zmian zgodności programu Visual Studio 2015.

Mapowania procedur tekstu ogólnego

TCHAR.H rutyna	_UNICODE i _MBCS niezdefiniowane	_MBCS zdefiniowany	_UNICODE zdefiniowany
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

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 do zachowania zgodności z systemem UNIX V.

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

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);
   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!

Zobacz też

We/Wy strumienia
vprintf, funkcje
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