`vsnprintf_s`, , `_vsnprintf_s_vsnprintf_s_l`, , `_vsnwprintf_s_vsnwprintf_s_l`

2025-06-21

Écrivez une sortie formatée à l’aide d’un pointeur vers une liste d’arguments. Ces fonctions sont des versions de , vsnprintf, _vsnprintf, _vsnprintf_l_vsnwprintf, avec des améliorations de sécurité décrites dans la section Fonctions de_vsnwprintf_lsécurité du CRT.

Syntaxe

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
);

int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);

int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
);

template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only

Paramètres

buffer
Emplacement de stockage pour la sortie.

sizeOfBuffer
Taille de la buffer sortie for. Taille en octets pour les fonctions qui prennent , et en char pour celles qui prennent wchar_t.

count
Nombre maximum de caractères à écrire, sans compter le NULL. Pour les fonctions qui prennent wchar_t, c’est le nombre de caractères larges à écrire. Ou _TRUNCATE.

format
Spécification du format.

argptr
Pointeur vers la liste des arguments.

locale
Paramètres régionaux à utiliser lors de la mise en forme de la sortie.

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

Valeur retournée

Nombre de caractères écrits, sans compter la fin NULLou une valeur négative en cas d’erreur de sortie.

Pour plus d’informations, consultez la section Résumé du comportement .

Remarques

Chacune de ces fonctions prend un pointeur vers une liste d’arguments, puis formate et écrit jusqu’aux count caractères des données données données dans la mémoire pointée par buffer et ajoute une terminaison NULL.

Dans les versions de débogage, les octets restants sizeOfBuffer après la fin NULL sont remplis avec 'xFE' comme décrit dans ._CrtSetDebugFillThreshold

Les versions de ces fonctions avec le _l suffixe sont identiques, sauf qu’elles utilisent le paramètre locale passé à la place de la locale du thread actuel.

vsnprintf_s est identique à _vsnprintf_s la norme ANSI et est incluse pour être conforme à celle-ci. _vnsprintf est conservé pour des raisons de compatibilité descendante.

Résumé du comportement

Pour le tableau suivant :

Soit len la taille des données formatées. Si la fonction prend une char mémoire tampon, la taille est exprimée en octets. Si la fonction prend une wchar_t mémoire tampon, la taille spécifie le nombre de mots de 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.

État	Comportement	Valeur retournée	`errno`	Appelle un gestionnaire de paramètres non valide
Succès	Écrit les caractères dans la mémoire tampon à l’aide de la chaîne de format spécifiée	Le nombre de caractères écrits	N/A	Non
Erreur d’encodage lors du formatage	Si le traitement du spécificateur `s`de chaîne , `S`ou `Z`, le traitement de la spécification de format s’arrête.	-1	`EILSEQ (42)`	Non
Erreur d’encodage lors du formatage	Si vous traitez le spécificateur `c` de caractères 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é, et aucune donnée n’est écrite pour celui-ci. Le traitement de la spécification de format se poursuit après avoir sauté le spécificateur avec l’erreur d’encodage.	Le nombre de caractères écrits, sans compter le `NULL`.	`EILSEQ (42)`	Non
`buffer == NULL` et `sizeOfBuffer == 0` et `count == 0`	Aucune donnée n’est écrite.	0	N/A	Non
`buffer == NULL` et soit `sizeOfBuffer != 0` ou `count != 0`	Si l’exécution se poursuit après l’exécution d’un gestionnaire de paramètres non valide, définit `errno` et renvoie une valeur négative.	-1	`EINVAL` (22)	Oui
`buffer != NULL` et `sizeOfBuffer == 0`	Aucune donnée n’est écrite. Si l’exécution se poursuit après l’exécution d’un gestionnaire de paramètres non valide, définit `errno` et renvoie une valeur négative.	-1	`EINVAL` (22)	Oui
`buffer != NULL` et `sizeOfBuffer != 0` et `count == 0`	La mémoire tampon est `NULL` terminée.	-1	N/A	Non
`count == 0`	N’écrit aucune donnée et renvoie le nombre de caractères qui auraient été écrits, sans compter la terminaison `NULL`.	Le nombre de caractères qui auraient été écrits, sans compter le `NULL`.	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 l’écrasement de la mémoire qui suit la mémoire tampon.	Le nombre de caractères écrits, sans compter le `NULL`.	N/A	Non
`count < sizeOfBuffer` et `len <= count`	Toutes les données sont écrites et une terminaison `NULL` est ajoutée.	Le nombre de caractères écrits.	N/A	Non
`count < sizeOfBuffer` et `len > count`	Les premiers `count` caractères sont écrits.	-1	N/A	Non
`count >= sizeOfBuffer` et `len < sizeOfBuffer`	Toutes les données sont écrites avec un .`NULL`	Le nombre de caractères écrits, sans compter le `NULL`.	N/A	Non
`count >= sizeOfBuffer` et `len >= sizeOfBuffer` et `count != _TRUNCATE`	Si l’exécution se poursuit après l’exécution d’un gestionnaire de paramètres non valide, définit `errno`, définit `buffer[0] == NULL`et renvoie une valeur négative.	-1	`ERANGE` (34)	Oui
`count == _TRUNCATE` et `len >= sizeOfBuffer`	Écrit autant de chaîne que possible dans `buffer`, y compris la terminaison `NULL`.	-1	N/A	Non
`count == _TRUNCATE` et `len < sizeOfBuffer`	Écrit la chaîne entière dans `buffer` avec la `NULL`terminaison .	Nombre de caractères écrits.	N/A	Non
`format == NULL`	Aucune donnée n’est écrite. Si l’exécution se poursuit après l’exécution d’un gestionnaire de paramètres non valide, définit `errno` et renvoie une valeur négative.	-1	`EINVAL` (22)	Oui

Pour plus d’informations sur ces codes d’erreur et d’autres, reportez-vous aux sections _doserrno, errno, _sys_errlistet _sys_nerr.

Important

Assurez-vous qu’il ne s’agit format pas d’une chaîne définie par l’utilisateur. Pour plus d’informations, consultez Solutions contre les dépassements de mémoire tampon. À partir de Windows 10 version 2004 (build 19041), la printf famille de fonctions imprime des nombres à virgule flottante exactement représentables selon les règles d’arrondi IEEE 754. Dans les versions précédentes de Windows, les nombres à virgule flottante se terminant par « 5 » étaient toujours arrondis à la hausse. L’IEEE 754 stipule qu’ils doivent arrondir au chiffre pair le plus proche (également connu sous le nom d'« arrondi du banquier »). Par exemple, les deux printf("%1.0f", 1.5) et printf("%1.0f", 2.5) doivent être arrondis à 2. Auparavant, 1,5 s’arrondissait à 2 et 2,5 à 3. Ce changement n’affecte que les numéros exactement représentables. Par exemple, 2,35 (qui, lorsqu’il est représenté en mémoire, est plus proche de 2,350000000000008) continue d’arrondir à 2,4. L’arrondi effectué par ces fonctions respecte désormais également le mode d’arrondi en virgule flottante défini par fesetround. Auparavant, l’arrondi choisissait toujours le FE_TONEAREST comportement. Cette modification affecte uniquement les programmes créés à l’aide de Visual Studio 2019 version 16.2 et ultérieure. Pour utiliser le comportement d’arrondi à virgule flottante héritée, liez avec legacy_stdio_float_rounding.obj.

Remarque

Pour vous assurer qu’il y a de la place pour la terminaison NULL, assurez-vous que count est strictement inférieur à la longueur de la mémoire tampon, ou utilisez _TRUNCATE.

En C++, l’utilisation de ces fonctions est simplifiée par les surcharges de modèles ; Les surcharges peuvent déduire automatiquement la longueur de la mémoire tampon (éliminant ainsi le besoin de spécifier un argument de taille) et elles peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs homologues plus récentes et sécurisées. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Conseil / Astuce

Si vous obtenez une erreur externe _vsnprintf_s non définie et que vous utilisez l’environnement d’exécution C universel, ajoutez-l’ajouter legacy_stdio_definitions.lib à l’ensemble des bibliothèques à lier. Le runtime C universel n’exporte pas directement cette fonction et est défini en ligne dans <stdio.h>. Pour plus d’informations, consultez Vue d’ensemble des problèmes de mise à niveau potentiels et des modifications de conformité à Visual Studio 2015.

Mappages de routines de texte générique

Routine `TCHAR.H`	`_UNICODE` et `_MBCS` non définis	`_MBCS` défini	`_UNICODE` défini
`_vsntprintf_s`	`_vsnprintf_s`	`_vsnprintf_s`	`_vsnwprintf_s`
`_vsntprintf_s_l`	`_vsnprintf_s_l`	`_vsnprintf_s_l`	`_vsnwprintf_s_l`

Spécifications

Routine	En-tête requis	En-têtes facultatifs
`vsnprintf_s`	`<stdio.h>` et `<stdarg.h>`	`<varargs.h>`*
`_vsnprintf_s`, `_vsnprintf_s_l`	`<stdio.h>` et `<stdarg.h>`	`<varargs.h>`*
`_vsnwprintf_s`, `_vsnwprintf_s_l`	`<stdio.h>` ou `<wchar.h>`, et `<stdarg.h>`	`<varargs.h>`*

* Requis pour la compatibilité UNIX V.

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple :

// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>

void FormatOutput(LPCSTR formatstring, ...)
{
   int nSize = 0;
   char buff[10];
   memset(buff, 0, sizeof(buff));
   va_list args;
   va_start(args, formatstring);
   nSize = vsnprintf_s( buff, _countof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
   va_end(args);
}

int main() {
   FormatOutput("%s %s", "Hi", "there");
   FormatOutput("%s %s", "Hi", "there!");
   FormatOutput("%s %s", "Hi", "there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

Voir aussi

E/S de flux
vprintf fonctions
fprintf, , _fprintf_lfwprintf, ,_fwprintf_l
printf, , _printf_lwprintf, ,_wprintf_l
sprintf, _sprintf_l, , swprintf, _swprintf_l, __swprintf_l
va_arg, , va_copyva_end, ,va_start