sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Article
03/04/2013

Données mises en forme d'Écriture dans une chaîne.Ce sont des versions de sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument] ... 
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument]...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   locale_t locale [,
   argument]…
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only

Paramètres

buffer
emplacement de stockage pour la sortie
sizeOfBuffer
Nombre maximal de caractères à les enregistrer.
format
chaîne de contrôle de format
argument
arguments facultatifs
locale
Les paramètres régionaux à utiliser.

Pour plus d'informations, consultez Spécifications de format.

Valeur de retour

Le nombre de caractères entrés, ou - 1 si une erreur s'est produite.Si buffer ou format est un pointeur null, sprintf_s et retournent -1 d' swprintf_s et l'ensemble errno à EINVAL.

sprintf_s retourne le nombre d'octets stockés dans buffer, sans compter le caractère NULL de fin.swprintf_s retourne le nombre de caractères larges stockés dans buffer, sans compter le caractère élargi null de fin.

Notes

La fonction d' sprintf_s met en forme et enregistre une série de caractères et des valeurs dans buffer.Chaque argument (le cas échéant) est converti et de sortie en fonction de la spécification du format correspondante dans format.Le format est constituée de caractères ordinaires et a le même formulaire et fonction que l'argument d' format pour printf.Un caractère Null est ajouté après le dernier caractère écrit.Si copier se produit entre les chaînes qui se chevauchent, le comportement n'est pas défini.

Une différence entre sprintf_s et sprintf est qu' sprintf_s active la chaîne de format pour les caractères de mise en forme valides, alors qu' sprintf vérifie uniquement si la chaîne de format ou la mémoire tampon sont des pointeurs d' NULL .Si l'une ou l'autre contrôle échoue, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution de se poursuivre, la fonction retourne -1 et définit errno à EINVAL.

L'autre différence principale entre sprintf_s et sprintf est qu' sprintf_s prend un paramètre de longueur spécifiant la taille de la mémoire tampon de sortie en caractères.Si la mémoire tampon est trop petite pour le texte imprimé la mémoire tampon a pour valeur une chaîne vide et gestionnaire de paramètre non valide est appelé.Contrairement à snprintf, sprintf_s garantit que la mémoire tampon sera se terminant par null (à moins que la taille de la mémoire tampon est zéro).

swprintf_s est une version à caractère élargi d' sprintf_s; les arguments du pointeur vers swprintf_s sont des chaînes à caractères larges.La détection d'erreurs d'encodage dans swprintf_s peut différer de celle de sprintf_s.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.

Il existe des versions d' sprintf_s qui offrent un contrôle supplémentaire de ce qui se produit si la mémoire tampon est trop petite.Pour plus d'informations, consultez _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

mappages de routines de texte générique

routine de TCHAR.H	_MBCS & de _UNICODE non défini	_MBCS défini	_UNICODE défini
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Configuration requise

routine	en-tête requis
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> ou <wchar.h>

Pour des informations de compatibilité supplémentaires, consultez compatibilité dans l'introduction.

Exemple

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data: 
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}