sprintf_s, , _sprintf_s_lswprintf_s, ,_swprintf_s_l
Écrire des données mises en forme dans une chaîne. Ces fonctions sont des versions de , , swprintf_sprintf_l, , _swprintf_l, avec __swprintf_ldes améliorations de sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.sprintf
Syntaxe
int sprintf_s(
char *buffer,
size_t sizeOfBuffer,
const char *format,
...
);
int _sprintf_s_l(
char *buffer,
size_t sizeOfBuffer,
const char *format,
_locale_t locale,
...
);
int swprintf_s(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
...
);
int _swprintf_s_l(
wchar_t *buffer,
size_t sizeOfBuffer,
const wchar_t *format,
_locale_t locale,
...
);
template <size_t size>
int sprintf_s(
char (&buffer)[size],
const char *format,
...
); // C++ only
template <size_t size>
int swprintf_s(
wchar_t (&buffer)[size],
const wchar_t *format,
...
); // C++ only
Paramètres
buffer
Emplacement de stockage pour la sortie
sizeOfBuffer
Nombre maximal de caractères à stocker.
format
Chaîne de contrôle de format
...
Arguments facultatifs de mise en forme
locale
Paramètres régionaux à utiliser.
Pour plus d’informations, consultez Syntaxe de spécification de format.
Valeur retournée
Nombre de caractères écrits ou -1 si une erreur s’est produite. Si buffer ou format est un pointeur null, sprintf_s et swprintf_s retournent -1 et affectent la valeur 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 large null de fin.
Notes
La fonction sprintf_s met en forme une série de caractères et de valeurs et la stocke dans buffer. 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 la même fonction que l’argument format pour printf. Un caractère null est ajouté après le dernier caractère écrit. Si une copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.
L'une des principales différences entre sprintf_s et sprintf est que sprintf_s vérifie si la chaîne de format comporte des caractères de mise en forme valides, tandis que sprintf vérifie uniquement si la chaîne de format ou la mémoire tampon est un pointeur NULL . Si l’une ou l’autre vérification échoue, le gestionnaire de paramètres non valide est appelé, comme décrit dans la validation des paramètres. Si l'exécution est autorisée à se poursuivre, la fonction retourne -1 et définit errno avec la valeur EINVAL.
L'autre différence principale entre sprintf_s et sprintf est que 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 mis en forme, y compris le caractère Null de fin, elle est définie sur une chaîne vide en plaçant un caractère Null à buffer[0], et le gestionnaire de paramètre non valide est appelé. Contrairement à _snprintf, sprintf_s garantit que la mémoire tampon se termine par Null, sauf si la taille de la mémoire tampon est égale à zéro.
swprintf_s est une version à caractères larges de sprintf_s; les arguments de pointeur de swprintf_s sont des chaînes à caractères larges. La détection des erreurs swprintf_s d’encodage peut différer de la détection dans sprintf_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 automatiquement la longueur de la mémoire tampon, ce qui élimine la nécessité de spécifier un argument de taille. Ils peuvent également remplacer automatiquement les fonctions plus anciennes et non sécurisées par des équivalents plus récents et plus sécurisés. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.
Il existe des versions qui offrent davantage de sprintf_s contrôle sur ce qui se passe si la mémoire tampon est trop petite. Pour plus d’informations, consultez , , _snwprintf_s_snprintf_s_l, _snwprintf_s_l._snprintf_s
Important
À compter de Windows 10 version 2004 (build 19041), la famille de fonctions printf imprime exactement les nombres à virgule flottante pouvant être représentés en suivant les règles IEEE 754 pour l’arrondi. Dans les versions précédentes de Windows, les nombres à virgule flottante pouvant être représentés exactement qui se terminent par « 5 » sont toujours arrondis à la valeur supérieure. IEEE 754 indique qu’ils doivent être arrondis au chiffre pair le plus proche (également appelé « arrondi du banquier »). Par exemple, printf("%1.0f", 1.5) et printf("%1.0f", 2.5) doivent être arrondis à 2. Avant, 1.5 aurait été arrondi à 2 et 2.5 à 3. Ce changement affecte uniquement les nombres représentables avec précision. Par exemple, 2.35 (qui, lorsqu’il est représenté en mémoire, est plus proche de 2.35000000000000008) continue d’être arrondi à la valeur supérieure 2.4. L’arrondi effectué par ces fonctions respecte également le mode d’arrondi à virgule flottante défini par fesetround. Avant, l’arrondi choisissait toujours le comportement FE_TONEAREST. Ce changement affecte uniquement les programmes générés à l’aide de Visual Studio 2019 versions 16.2 et ultérieures. Pour utiliser le comportement d’arrondi à virgule flottante hérité, liez avec 'legacy_stdio_float_rounding.obj'.
Mappages de routines de texte générique
| Routine TCHAR.H | _UNICODE et _MBCS non définis |
_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 |
Spécifications
| Routine | En-tête requis |
|---|---|
sprintf_s, _sprintf_s_l |
C : <stdio.h> C++ : <cstdio> ou <stdio.h> |
swprintf_s, _swprintf_s_l |
C : <stdio.h> ou <wchar.h> C++ : <cstdio>, <cwchar>, <stdio.h> ou <wchar.h> |
Pour plus d’informations sur la compatibilité, consultez Compatibility.
Exemple : Utiliser sprintf_s pour mettre en forme des données
// 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 );
}
Output:
String: computer
Character: l
Integer: 35
Real: 1.732053
character count = 79
Exemple : Gestion du code d’erreur
// 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 );
}
wrote 11 characters
wrote -1 characters
Voir aussi
E/S de flux
fprintf, , _fprintf_lfwprintf, ,_fwprintf_l
printf, , _printf_lwprintf, ,_wprintf_l
sprintf, , _sprintf_lswprintf, , _swprintf_l__swprintf_l
scanf, , _scanf_lwscanf, ,_wscanf_l
sscanf, , _sscanf_lswscanf, ,_swscanf_l
vprintf, fonctions