vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Artykuł
06/09/2015

Zapisywanie sformatowanych danych wyjściowych za pomocą wskaźnika do listy argumentów.Bardziej bezpieczne wersje tych funkcji są dostępne w vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

int vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
);
int _vsnwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   va_list argptr 
);
int _vsnwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
); // C++ only

Parametry

buffer
Lokalizacja magazynowa danych wyjściowych.
count
Maksymalna liczba znaków do zapisu.
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, _vsnprintf, i _vsnwprintf zwraca liczbę znaków napisane, jeśli liczba znaków do zapisu jest mniejsza niż lub równa count; Jeśli jest większa niż liczba znaków do zapisu count, te funkcje zwrotu -1 wskazująca dane wyjściowe została obcięta.Wartość zwracana nie obejmuje zakończeń wartość null, jeśli jeden został napisany.

Jeśli buffer lub format jest NULL, lub jeśli liczba jest mniejsza niż lub równa zero, tych funkcji Wywołaj obsługę nieprawidłowy parametr, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje zwracają wartość -1 i ustawiają errno na EINVAL.

Uwagi

Każda z tych funkcji ma wskaźnik do listy argumentów, a następnie formatuje dane i zapisuje do count znaków do pamięci wskazywanej przez buffer.Czy jest miejsce na końcu (tzn. Jeśli liczba znaków do pisania jest mniejsza niż count), bufor będzie zakończony znakiem null.

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]

W celu zapewnienia, że ma miejsca na zakończenie null, upewnij się, że count jest ściśle mniej niż długość buforu i zainicjować bufor null przed wywołaniem funkcji.

vsnprintf jest identyczna z _vsnprintf.vsnprintfjest włączone dla zgodności na ANSI standardowych; _vnsprintf na zgodność ze starszymi wersjami.

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++ funkcje te mają przeciążenia szablonu, które wywołują nowsze, bezpieczne odpowiedniki tych funkcji.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	_vsnprintf	_vsnprintf	_vsnwprintf
_vsntprintf_l	_vsnprintf_l	_vsnprintf_l	_vsnwprintf_l

Wymagania

Procedura	Wymagany nagłówek	Opcjonalne nagłówki
vsnprintf	<stdio.h> i <stdarg.h>	<varargs.h>*
_vsnprintf, _vsnprintf_l	<stdio.h> i <stdarg.h>	<varargs.h>*
_vsnwprintf, _vsnwprintf_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.cpp
// compile with: /W3
#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( buff, sizeof(buff) - 1, formatstring, args); // C4996
// Note: vsnprintf is deprecated; consider vsnprintf_s instead
   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!!");
}