_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artykuł
02/27/2013

Zapisuje sformatowane dane na ciąg.Bezpieczniejsze wersje te funkcje są dostępne; see _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 przechowywania danych wyjściowych.
count
Maksymalna liczba znaków do przechowywania.
format
Ciąg formatu formantu.
argument
Opcjonalne argumenty.
locale
Ustawienia regionalne, aby użyć.

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

Wartość zwracana

Niech len długość ciągu sformatowanych danych (z wyłączeniem zakończeń null).leni count są w bajtach dla _snprintf, szerokości znaków dla _snwprintf.

If len < count, następnie len znaki są przechowywane w buffer, jest dołączany końcowych wartości null, i len jest zwracany.

Jeśli len = count, następnie len znaki są przechowywane w buffer, końcowych wartości null nie są dołączane, i len jest zwracany.

If len > count, następnie count znaki są przechowywane w buffer, nie terminator null jest dołączany i zwracana jest wartość ujemną.

Jeśli buffer jest wskaźnik zerowy i count jest różna od zera, lub format jest wskaźnik zerowy, wywoływana jest funkcja obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru.Jeśli wykonanie może kontynuować, funkcje te zwracają wartość -1 i errno do EINVAL.

Aby uzyskać informacje na temat tych i innych kodów błędów, zobacz _doserrno, errno, _sys_errlist i _sys_nerr.

Uwagi

_snprintf Funkcji formaty i Sklepy count lub mniej znaków w bufferi dołącza kończącego znaku null, jeśli długość sformatowany ciąg znaków jest ściśle mniej niż count znaków.Każdy argument (jeśli ma zastosowanie) jest konwertowane i wyjściowe zgodnie ze specyfikacją odpowiedni format w format.Format składa się ze znaków zwykłych i ma ten sam formularz i działać jako format argument dla printf.Jeśli kopiowanie występuje między ciągami, które się pokrywają, zachowanie jest niezdefiniowane.

Uwaga dotycząca zabezpieczeń
Zapewnić, że format nie jest ciągiem zdefiniowane przez użytkownika.Ponieważ ta funkcja nie gwarantuje zakończenie NULL (w szczególności, gdy zwracana jest wartość count), zapewnić, że następuje kod, który dodaje null terminator.Aby uzyskać więcej informacji, zobacz Overruns buforu unikanie.

_snwprintfjest to wersja szerokich znaków _snprintf; argumenty wskaźnik do _snwprintf są ciągami szerokich znaków.Wykrywanie błędów kodowania _snwprintf może różnić się od tej w _snprintf._snwprintf, takich jak swprintf, zapisuje dane wyjściowe na ciąg znaków, a nie do miejsca docelowego typu FILE.

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.

W języku C++ funkcje te mają overloads szablonu, które wywołują nowsze, bezpieczne odpowiednikami tych funkcji.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Tekst rodzajowy rutynowych mapowania

Procedura TCHAR.h	_UNICODE i _MBCS nie zdefiniowane	_MBCS, definicja	_UNICODE, definicja
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> lub <wchar.h>

Informacji dotyczących zgodności, zobacz zgodności we wprowadzeniu.

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;
}