_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Article
03/04/2013

Données mises en forme d'Écritures en chaîne.Ce sont des versions de _snprintf, _snprintf_l, _snwprintf, _snwprintf_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ... 
);
int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int _snwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format [,
   argument] ... 
);
int _snwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
template <size_t size>
int _snprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ... 
); // C++ only

Paramètres

buffer
emplacement de stockage pour la sortie.
sizeOfBuffer
la taille de l'emplacement de stockage pour la sortie.taille dans bytes pour _snprintf_s ou taille dans words pour _snwprintf_s.
Count
Nombre maximal de caractères à les rapports, ou _TRUNCATE.
format
Chaîne de format.
argument
arguments facultatifs.
locale
Les paramètres régionaux à utiliser.

Valeur de retour

_snprintf_s retourne le nombre de caractères stockés dans buffer, sans compter le caractère NULL de fin._snwprintf_s retourne le nombre de caractères larges stockés dans buffer, sans compter le caractère élargi null de fin.

Si le stockage requis pour stocker les données et null de fin dépasse sizeOfBuffer, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si l'exécution reprend après le gestionnaire de paramètre non valide, ces fonctions définissent buffer à une chaîne vide, définissent errno à ERANGE, et retournent -1.

si buffer ou format est un pointeur d' NULL , ou si count est inférieur ou égal à zéro, le gestionnaire de paramètre non valide est appelé.Si est autorisé à l'exécution de se poursuivre, ces errno défini par fonctions à EINVAL et à retourner -1.

Pour plus d'informations sur ces éléments et d'autres codes d'erreur, consultez _doserrno, errno, _sys_errlist, et _sys_nerr.

Notes

La fonction d' _snprintf_s met en forme et enregistre count ou moins caractères dans buffer et ajoute un caractère null de fin.Chaque argument (le cas échéant) est converti et de sortie en fonction de la spécification du format correspondante dans format.La mise en forme est compatible avec la famille d' printf des fonctions ; consultez Syntaxe de spécification de format : fonctions printf et wprintf.Si copier se produit entre les chaînes qui se chevauchent, le comportement n'est pas défini.

Si count est _TRUNCATE, les écrit dans _snprintf_s autant de la chaîne que tient dans buffer tout en quittant la place pour null de fin.Si les ajustements entiers de chaîne (avec fin null) dans buffer, alors _snprintf_s retourne le nombre de caractères entrés (sans caractère null de fin) ; sinon, _snprintf_s retourne -1 pour indiquer que la troncation s'est produite.

Note de sécurité
assurez-vous qu' format n'est pas une chaîne définie par l'utilisateur.

_snwprintf_s est une version à caractère élargi d' _snprintf_s; les arguments du pointeur vers _snwprintf_s sont des chaînes à caractères larges.La détection d'erreurs d'encodage dans _snwprintf_s diffère de celui du _snprintf_s._snwprintf_s, comme swprintf_s, sortie d'écritures à une chaîne plutôt qu'à une destination de type FILE.

Les versions de ces fonctions par le suffixe d' _l sont identiques mais elles utilisent le paramètre de paramètres régionaux passé au lieu des paramètres régionaux du thread courant.

En C++, à l'aide de ces fonctions est simplifié par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement (en éliminant le besoin de spécifier un argument de taille) et peuvent remplacer automatiquement des fonctions plus anciennes et non sécurisées par leurs nouvelles, sécurisées équivalents.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

mappages de routines de texte générique

routine de Tchar.h	_UNICODE et _MBCS non définis	_MBCS défini	_UNICODE défini
_sntprintf_s	_snprintf_s	_snprintf_s	_snwprintf_s
_sntprintf_s_l	_snprintf_s_l	_snprintf_s_l	_snwprintf_s_l

Configuration requise

routine	en-tête requis
_snprintf_s, _snprintf_s_l	<stdio.h>
_snwprintf_s, _snwprintf_s_l	<stdio.h> ou <wchar.h>

Pour plus d'informations de compatibilité, consultez compatibilité dans l'introduction.

Exemple

// crt_snprintf_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

int snprintf_s_tester( const char * fmt, int x, int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%d-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %d; %d-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}


void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}