vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Artykuł
02/27/2013

Zapis sformatowane dane wyjściowe przy użyciu wskaźnika do listy argumentów.Są to wersje vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l z rozszerzeń zabezpieczeń opisane 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
Miejsca przechowywania danych wyjściowych.
sizeOfBuffer
Rozmiar buffer dla danych wyjściowych w bajtach.
count
Maksymalna liczba znaków do zapisu (nie w tym zakończeń null), lub _TRUNCATE.
format
Specyfikacja formatu.
argptr
Wskaźnik do listy argumentów.
locale
Ustawienia regionalne, aby użyć.

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

Wartość zwracana

vsnprintf_s,_vsnprintf_s i _vsnwprintf_s zwraca liczbę znaków, napisane, nie włączając zakończeń null lub wartości ujemne, jeśli wystąpi błąd wyjścia.vsnprintf_sjest taka sama, jak _vsnprintf_s.vsnprintf_sjest uwzględniony w zgodności ze standardem ANSI._vnsprintfjest zachowywana w zgodności z poprzednimi wersjami.

Jeśli przekracza pamięci potrzebnej do przechowywania danych i zakończeń null sizeOfBuffer, wywoływana jest funkcja obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru, chyba że count jest _TRUNCATE, w którym to przypadku tyle ciągu jako zmieści się w buffer jest zapisywany i zwrócił wartość -1.Jeśli wykonywanie jest kontynuowane po obsługi nieprawidłowy parametr, ustaw te funkcje buffer ciąg pusty, ustaw errno do ERANGEi zwraca –1.

Jeśli buffer lub format jest NULL wskaźnik, lub jeśli count jest mniejsza lub równa zeru, wywoływana jest funkcja obsługi nieprawidłowy parametr.Jeśli wykonanie może kontynuować, ustaw te funkcje errno do EINVAL i zwraca –1.

Warunki błędów

Condition	Zwrot	errno
bufferjest NULL	-1	EINVAL
formatjest NULL	-1	EINVAL
count< = 0	-1	EINVAL
sizeOfBuffertoo small (and count != _TRUNCATE)	-1 (i buffer ustawiona na pusty ciąg)	ERANGE

Uwagi

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

Jeśli count jest _TRUNCATE, wówczas te funkcje zapisu tyle ile zmieści się ciągu buffer , pozostawiając pomieszczenia kończącego NULL.Jeśli cały ciąg (z zakończeń null) mieści się buffer, a następnie funkcje te zwracają liczbę znaki pisane (z wyłączeniem zakończeń null); w przeciwnym razie funkcje te zwracają wartość -1, aby wskazać, że wystąpił ten obcinania.

Wersje te funkcje, z _l sufiks są identyczne, z wyjątkiem, że używają oni przekazany zamiast bieżące ustawienia regionalne wątku parametr ustawień regionalnych.

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

[!UWAGA]

W celu zapewnienia jest miejsce dla zakończeń null, upewnij się, że count jest ściśle mniejsza niż długość buforu lub użyj _TRUNCATE.

W języku C++ korzystając z tych funkcji jest uproszczona poprzez overloads szablonu; overloads można automatycznie rozpoznać długość buforu (eliminując konieczność należy określić argument rozmiar) i automatycznie można zastąpić starszych, które nie są bezpieczne funkcje z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Tekst rodzajowy rutynowych mapowania

TCHAR.Rutynowe H	_UNICODE & Nie zdefiniowano _MBCS	_MBCS, definicja	_UNICODE, definicja
_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ć standardowych funkcji C, należy użyć PInvoke. Aby uzyskać więcej informacji, zobacz Przykłady wywołać platformy.

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka	Opcjonalna 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 v systemu UNIX.

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności 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, sizeof(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!!");
}