_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Article
06/09/2015

Écrit des données mises en forme dans une chaîne. Il s'agit de versions de _snprintf, _snprintf_l, _snwprintf, _snwprintf_l avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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 de la sortie. Taille en bytes pour _snprintf_s ou taille en words pour _snwprintf_s.
Count
Nombre maximal de caractères à stocker, ou _TRUNCATE.
format
Chaîne de contrôle de format.
argument
Arguments facultatifs.
locale
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 large null de fin.

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

Si buffer ou format est un pointeur NULL, ou si count est inférieur ou égal à zéro, le gestionnaire de paramètres non valides est appelé. Si l'exécution est autorisée à se poursuivre, ces fonctions définissent errno avec la valeur EINVAL et retournent -1.

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

Notes

La fonction _snprintf_s formate et stocke count ou moins caractères dans buffer et ajoute un NULL de fin. Chaque argument (le cas échéant) est converti et sorti selon la spécification de format correspondante dans format . La mise en forme est compatible avec la famille printf de fonctions ; consultez Syntaxe de spécification de format : fonctions printf et wprintf. Si une copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

Si count est _TRUNCATE, alors _snprintf_s écrit autant de la chaîne qui tient dans buffer tout en laissant de la place pour un NULL de fin. Si la chaîne entière (avec un null de fin) rentre dans buffer, alors _snprintf_s retourne le nombre de caractères écrit (sans Null de fin) ; sinon, _snprintf_s retourne -1 pour indiquer que la troncature s'est produite.

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

_snwprintf_s est une version à caractères larges de _snprintf_s ; les arguments de pointeur de _snwprintf_s sont des chaînes à caractères larges. La détection d'erreurs d'encodage dans _snwprintf_s peut différer de celle dans _snprintf_s. _snwprintf_s, comme swprintf_s, écrit la sortie dans une chaîne plutôt que dans 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++, l'utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire la longueur de la mémoire tampon automatiquement (ce qui évite d'avoir à spécifier un argument taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalentes plus récentes et sécurisées. 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_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 sur la 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();
}