_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Článek
06/09/2015

Zapisuje formátovaná data do řetězce.K dispozici jsou bezpečnější verze těchto funkcí, viz _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
Umístění úložiště pro výstup
count
Maximální počet znaků, které se mají uložit
format
Řetězec řízení formátu
argument
Volitelné argumenty
locale
Národní prostředí, které se má použít

Další informace naleznete v tématu Syntaxe specifikace formátu: funkce printf a wprintf.

Vrácená hodnota

len nechť označuje délku formátovaného datového řetězce, bez ukončující hodnoty null.len a count jsou v bajtech pro _snprintf, široké znaky pro _snwprintf.

Pokud jsou do proměnné buffer uloženy znaky len < count, len, bude připojen ukončovací znak null a bude vrácena hodnota len.

Pokud jsou do proměnné buffer uloženy znaky len = count, len, nebude připojen ukončovací znak null a bude vrácena hodnota len.

Pokud jsou do proměnné buffer uloženy znaky len > count, count, nebude připojen ukončovací znak null a bude vrácena záporná hodnota.

Pokud je buffer ukazatel s hodnotou null a count je nula, len se vrátí jako počet znaků potřebných k zformátování výstupu, bez ukončovacího znaku null.K úspěšnému volání se stejnými parametry argument a locale je třeba vyhradit vyrovnávací paměť o velikosti alespoň len + 1 znak.

Pokud je buffer ukazatel s hodnotou null a hodnota count je nenulová nebo pokud je format ukazatel s hodnotou null, je vyvolána neplatná obslužná rutina parametru, jak je popsáno v tématu Ověření parametru.Pokud provádění může pokračovat, vrátí funkce hodnotu -1 a nastaví errno na EINVAL.

Další informace o tomto a dalších chybových kódech naleznete v tématu errno, _doserrno, _sys_errlist, and _sys_nerr.

Poznámky

Funkce _snprintf formátuje a ukládá do proměnné buffercount nebo méně znaků a připojí ukončovací znak null, pokud je délka formátovaného řetězce menší než count znaků.Každý argument (pokud existuje) je převeden podle odpovídající specifikace formátu v proměnné format.Formát se skládá z běžných znaků a má stejnou formu a funkci jako argument format pro printf.Pokud ke kopírování dojde mezi řetězci, které se překrývají, chování není definováno.

Poznámka k zabezpečení
Zajistěte, aby format nebyl uživatelem definovaný řetězec.Vzhledem k tomu, že tato funkce nezaručuje ukončení hodnotou NULL – zejména pokud je návratová hodnota count, ujistěte se, že po ní následuje kód, který ukončovací znak null přidá.Další informace naleznete v tématu Předcházení přetečení vyrovnávací paměti.

_snwprintf je širokoznaká verze funkce _snprintf. Argumenty ukazatele pro funkci _snwprintf jsou širokoznaké řetězce.Detekce chyb kódování ve funkci _snwprintf se může lišit od detekce ve funkci _snprintf._snwprintf, podobně jako funkce swprintf, zapíše výstup do řetězce místo do cíle typu FILE.

Verze těchto funkcí, které mají příponu _l, jsou stejné s tím rozdílem, že používají parametr předaného národního prostředí namísto národního prostředí aktuálního vlákna.

V jazyce C++ mají tyto funkce přetížení šablon, která vyvolávají novější, lépe zabezpečené protějšky těchto funkcí.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Mapování rutin obecného textu

Rutina Tchar.h	_UNICODE a _MBCS nejsou definovány.	_MBCS definováno	_UNICODE definováno
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Požadavky

Rutina	Požadovaný hlavičkový soubor
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> nebo <wchar.h>

Další informace o kompatibilitě naleznete v tématu Kompatibilita.

Příklad

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