_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artykuł
06/09/2015

Zapisuje sformatowane dane do ciągu.Dostępne są bezpieczniejsze wersje tych funkcji, zobacz _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

int _snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ... 
);
int _snprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int _snwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument] ... 
);
int _snwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
template <size_t size>
int _snprintf(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
); // C++ only

Parametry

buffer
Lokalizacja w pamięci dla danych wyjściowych.
count
Maksymalna liczba znaków do zapisania.
format
Ciąg kontroli formatu.
argument
Argumenty opcjonalne.
locale
Ustawienia regionalne do użycia.

Aby uzyskać więcej informacji, zobacz Składnia specyfikacji formatu: funkcje printf i wprintf.

Wartość zwracana

Niech len będzie długością sformatowanego ciągu danych, nie wliczając końcowej wartości null.len i count są w bajtach dla _snprintf, znaki dwubajtowe dla _snwprintf.

Jeśli znaki len < count, len są przechowywane w buffer, dołączany jest terminator o wartości null i zwracana jest wartość len.

Jeśli znaki len = count, len są przechowywane w buffer, nie jest dołączany terminator o wartości null i zwracana jest wartość len.

Jeśli znaki len > count, count są przechowywane w buffer, nie jest dołączany terminator o wartości null i zwracana jest wartość ujemna.

Jeśli buffer jest pustym wskaźnikiem i count wynosi zero, len jest zwracany jako liczba znaków wymaganych do sformatowania danych wyjściowych, nie wliczając zakończenia o wartości null.Aby prawidłowo wywołać z tymi samymi parametrami argument i locale, przydziel bufor mieszczący co najmniej len + 1 znaków.

Jeśli buffer jest pustym wskaźnikiem i count jest różny od zera, lub jeśli format jest pustym wskaźnikiem, wywoływany jest program obsługi nieprawidłowego parametru, 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.

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

Uwagi

Funkcja _snprintf formatuje i zapisuje count lub mniej znaków w buffer i dołącza kończący znak null, jeśli długość sformatowanego ciągu jest mniejsza niż count znaków.Każdy argument (jeśli istnieje) jest konwertowany i formatowany według specyfikacji formatu w format.Format składa się ze znaków zwykłych i ma taką samą formę i funkcję, jak argument format dla printf.Jeśli kopiowanie odbywa się między nakładającymi się ciągami, zachowanie jest niezdefiniowane.

Uwaga dotycząca zabezpieczeń
Zapewnia, że format nie jest ciągiem zdefiniowanym przez użytkownika.Ponieważ ta funkcja nie gwarantuje zakończenia NULL — w szczególności, kiedy wartość zwracana to count— upewnij się, że następuje po niej kod, który dodaje terminator o wartości zerowej.Aby uzyskać więcej informacji, zobacz Unikanie przepełnień bufora.

_snwprintf to dwubajtowa wersja znaków _snprintf; argumenty wskaźnika do _snwprintf są ciągami dwubajtowych znaków.Wykrywanie błędów kodowania w _snwprintf może się różnić od tego w _snprintf._snwprintf, podobnie jak swprintf, zapisuje dane wyjściowe do ciągu, a nie miejsca docelowego typu FILE.

Wersje tych funkcji, które mają przyrostek _l, są identyczne, z tą różnicą, że korzystają z przekazanego parametru ustawień regionalnych, a nie z ustawień regionalnych bieżącego wątku.

W C++ te funkcje mają przeciążenia szablonu, które wywołują ich nowsze, bezpieczniejsze odpowiedniki.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Mapowania procedur zwykłego tekstu

Procedura tchar.h	_UNICODE i _MBCS niezdefiniowane	_MBCS zdefiniowano	_UNICODE zdefiniowano
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Wymagania

Procedura	Wymagany nagłówek
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> lub <wchar.h>

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

Przykład

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l'; 
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal nul! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed], 
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed], 
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is 
       * like going one element beyond a buffer, but in this case 
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}