`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`

Article
10/12/2023

Écrit des données mises en forme dans une chaîne. Ces fonctions sont des versions de , , _snprintf_snprintf_l, , _snwprintfavec _snwprintf_l des améliorations de sécurité décrites dans les fonctionnalités de sécurité dans le CRT.snprintf

Syntaxe

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
Taille de l’emplacement de stockage pour la sortie. Taille en octets pour les fonctions qui prennent char, et les mots pour ceux qui prennent wchar_t.

count
Nombre maximal de caractères à écrire. Pour les fonctions qui prennent wchar_t, il s’agit du nombre maximal de caractères larges à écrire. Ou _TRUNCATE.

format
Chaîne de contrôle de format.

argument
Arguments facultatifs.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Nombre de caractères écrits, sans inclure la fin NULL. Une valeur négative est retournée si une erreur de sortie se produit. Pour plus d’informations, consultez le résumé du comportement.

Notes

La _snprintf_s fonction met en forme et stocke count ou moins de caractères et buffer ajoute une fin NULL. Chaque argument éventuel est converti et sorti selon la spécification de format correspondante dans format. La mise en forme est cohérente avec la famille de fonctions ; consultez la printf syntaxe de spécification de format : printf et wprintf les fonctions. Si une copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

Résumé du comportement

Pour le tableau suivant :

-Laissez len la taille des données mises en forme. Si la fonction prend une char mémoire tampon, la taille est en octets. Si la fonction prend une wchar_t mémoire tampon, la taille spécifie le nombre de mots 16 bits.

Les caractères font référence aux char caractères des fonctions qui prennent une char mémoire tampon et aux wchar_t caractères des fonctions qui prennent une wchar_t mémoire tampon.
Pour plus d’informations sur le gestionnaire de paramètres non valide, consultez Validation des paramètres.

Condition	Comportement	Valeur retournée	`errno`	Appelle un gestionnaire de paramètres non valides
Opération réussie	Écrit les caractères dans la mémoire tampon à l’aide de la chaîne de format spécifiée.	Nombre de caractères écrits, sans inclure la fin `NULL`.	N/A	Non
Erreur d’encodage lors de la mise en forme	Si le spécificateur `s`de chaîne de traitement , `S`ou `Z`, le traitement des spécifications de format s’arrête.	-1	`EILSEQ` (42)	Non
Erreur d’encodage lors de la mise en forme	Si le spécificateur `c` de caractère de traitement ou `C`, le caractère non valide est ignoré. Le nombre de caractères écrits n’est pas incrémenté pour le caractère ignoré, ni aucune donnée n’est écrite pour elle. Le traitement de la spécification du format se poursuit après avoir ignoré le spécificateur avec l’erreur d’encodage.	Nombre de caractères écrits, sans inclure la fin `NULL`.	`EILSEQ` (42)	Non
`buffer == NULL`et et `sizeOfBuffer == 0count == 0`	Aucune donnée n’est écrite.	0	N/A	Non
`buffer == NULL`et ou `sizeOfBuffer != 0count != 0`	Si l’exécution se poursuit après l’exécution du gestionnaire de paramètres non valide, définit `errno` et retourne une valeur négative.	-1	`EINVAL` (22)	Oui
`buffer != NULL` et `sizeOfBuffer == 0`	Aucune donnée n’est écrite.	-1	`EINVAL` (22)	Oui
`count == 0`	Un `NULL` est placé au début de la mémoire tampon.	-1	N/A	Non
`count < 0`	Non sécurisé : la valeur est traitée comme non signée, ce qui crée probablement une valeur importante qui entraîne le remplacement de la mémoire qui suit la mémoire tampon.	Nombre de caractères écrits, sans inclure la fin `NULL`.	N/A	Non
`count < sizeOfBuffer` et `len <= count`	Toutes les données sont écrites et une fin `NULL` est ajoutée.	Nombre de caractères écrits.	N/A	Non
`count < sizeOfBuffer` et `len > count`	Les premiers `count` caractères sont écrits et une fin `NULL` est ajoutée.	-1	N/A	Non
`count >= sizeOfBuffer` et `len < sizeOfBuffer`	Toutes les données sont écrites avec une fin `NULL`.	Nombre de caractères écrits.	N/A	Non
`count >= sizeOfBuffer`et et `len >= sizeOfBuffercount != _TRUNCATE`	Si l’exécution se poursuit après l’exécution du gestionnaire de paramètres non valide, définit, définit `errnobuffer[0] == NULL`et retourne une valeur négative.	-1	`ERANGE` (34)	Oui
`count == _TRUNCATE` et `len >= sizeOfBuffer`	Écrit autant de chaînes qu’il `buffer` convient et une fin `NULL`.	-1	N/A	Non
`count == _TRUNCATE` et `len < sizeOfBuffer`	Écrit l’intégralité de la chaîne avec `buffer` une fin `NULL`.	Nombre de caractères écrits, sans inclure la fin `NULL`.	N/A	Non
`format == NULL`	Aucune donnée n’est écrite. Si l’exécution se poursuit après l’exécution du gestionnaire de paramètres non valide, définit `errno` et retourne une valeur négative.	-1	`EINVAL` (22)	Oui

Pour plus d’informations sur ces codes d’erreur et d’autres codes d’erreur, consultez , , _sys_errlisterrnoet _sys_nerr._doserrno

Important

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

À compter de Windows 10 version 2004 (build 19041), la printf famille de fonctions imprime exactement des nombres à virgule flottante pouvant être représentés en fonction des règles IEEE 754 pour l’arrondi. Dans les versions précédentes de Windows, les nombres à virgule flottante qui se terminent exactement par « 5 » sont toujours arrondis. IEEE 754 indique qu’ils doivent arrondir au chiffre pair le plus proche (également appelé « Arrondi du banquier »). Par exemple, les deux printf("%1.0f", 1.5) et printf("%1.0f", 2.5) doivent arrondir à 2. Auparavant, 1,5 arrondirait à 2 et 2,5 arrondirait à 3. Cette modification affecte uniquement les nombres représentant exactement. Par exemple, la version 2.35 (qui, lorsqu’elle est représentée en mémoire, est plus proche de 2,350000000000008) continue d’arrondir jusqu’à 2,4. L’arrondi effectué par ces fonctions respecte désormais également le mode d’arrondi à virgule flottante défini par fesetround. Auparavant, l’arrondi a toujours choisi FE_TONEAREST le comportement. Cette modification affecte uniquement les programmes générés à l’aide de Visual Studio 2019 version 16.2 et ultérieures. Pour utiliser le comportement d’arrondi à virgule flottante héritée, lien avec « legacy_stdio_float_rounding.obj ».

_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. FILE, tout comme _snwprintf_s, écrit la sortie dans une chaîne plutôt que dans une destination de type swprintf_s.

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 Surcharges de modèles sécurisés.

Mappages de routine de texte générique

`Tchar.h` Routine	`_UNICODE` et `_MBCS` non défini	`_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`

Spécifications

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 Compatibility.

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, size_t count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%zd-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %zd; %zd-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();
}


count = 8; 10-byte buffer
    new contents of dest: '<<<121>>'

count = 9; 10-byte buffer
    new contents of dest: '<<<121>>>'

count = 10; 10-byte buffer
    new contents of dest: '<<<121>>>'

Destination buffer too small:

count = 10; 10-byte buffer
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Truncation examples:

10-byte buffer; truncation semantics
    new contents of dest: '<<<1221>>'
    truncation did occur

10-byte buffer; truncation semantics
    new contents of dest: '<<<121>>>'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Voir aussi

E/S de flux
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
vprintf, fonctions

`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`

Syntaxe

Paramètres

Valeur retournée

Notes

Résumé du comportement

Mappages de routine de texte générique

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Syntaxe

Paramètres

Valeur retournée

Notes

Résumé du comportement

Mappages de routine de texte générique

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`