_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Article
06/09/2015

Écrit des données mises en forme dans une chaîne. Des versions plus sécurisées de ces fonctions sont disponibles ; consultez _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

Paramètres

buffer
Emplacement de stockage pour la sortie.
count
Nombre maximal de caractères à stocker.
format
Chaîne de contrôle de format.
argument
Arguments facultatifs.
locale
Paramètres régionaux à utiliser.

Pour plus d'informations, consultez Syntaxe de spécification de format : fonctions printf et wprintf.

Valeur de retour

Laissez len être de la longueur de la chaîne de données mise en forme, à l'exclusion de la marque de fin null. len et count sont en octets pour _snprintf, caractères larges pour _snwprintf.

Si len < count, len les caractères sont stockés dans buffer, une marque de fin null est ajoutée, et len est retourné.

Si len = count, les caractères len sont stockés dans buffer, aucune marque de fin null n'est ajoutée, et len est retourné.

Si len > count, les caractères count sont stockés dans buffer, aucune marque de fin null n'est ajoutée, et une valeur négative est retournée.

Si buffer est un pointeur null et count est égal à zéro, len est retourné comme nombre de caractères requis pour mettre en forme la sortie, à l'exception de la marque de fin null. Pour effectuer un appel réussi avec le même argument et les paramètres locale, allouez une mémoire tampon contenant au moins len + 1 caractères.

Si buffer est un pointeur null et count est différent de zéro, ou si format est un pointeur null, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent -1 et définissent errno avec la valeur EINVAL.

Pour plus d'informations sur ces codes de retour et autres, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

Notes

La fonction _snprintf met en forme et stocke count ou moins de caractères dans buffer, puis ajoute une marque de fin null si la longueur de la chaîne mise en forme est strictement inférieure aux caractères de count. Chaque argument (le cas échéant) est converti et sorti selon la spécification de format correspondante dans format. Le format se compose de caractères ordinaires et a la même forme et fonction que l'argument format pour printf. Si une copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

Note de sécurité
Assurez-vous que format n'est pas une chaîne définie par l'utilisateur.Cette fonction ne garantissant pas la marque de fin NULL, notamment lorsque la valeur de retour est count, vérifiez qu'elle est suivie du code qui ajoute la marque de fin null.Pour plus d'informations, consultez Solutions contre les dépassements de mémoire tampon.

_snwprintf est une version à caractères larges de _snprintf ; les arguments de pointeur de _snwprintf sont des chaînes à caractères larges. La détection d'erreurs d'encodage dans _snwprintf peut différer de celle dans _snprintf. _snwprintf, tout comme swprintf, écrit la sortie dans une chaîne au lieu d'une destination de type FILE.

Les versions de ces fonctions avec le suffixe _l sont identiques, sauf qu'elles utilisent les paramètres régionaux passés au lieu des paramètres régionaux du thread actuel.

En C++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Mappages de routines de texte générique

Routine Tchar.h	_UNICODE et _MBCS non définis	_MBCS défini	_UNICODE défini
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Configuration requise

Routine	En-tête requis
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

Exemple

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