vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Écrivez la sortie mise en forme en utilisant un pointeur désignant une liste d’arguments. Ces fonctions sont des versions de , , _vsnprintf_l_vsnprintf, , _vsnwprintf, avec_vsnwprintf_ldes améliorations de sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.vsnprintf

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. 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 sans inclure la fin NULL. Pour les fonctions qui prennent wchar_t, il s’agit du nombre de caractères larges à écrire. Ou _TRUNCATE.

format
Spécification de format.

argptr
Pointeur vers la liste d'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 inclure la fin NULLou une valeur négative si une erreur de sortie se produit.

Pour plus d’informations, consultez le résumé du comportement.

Notes

vsnprintf_s est identique à _vsnprintf_s et est inclus pour la conformité à la norme ANSI. _vnsprintf est conservé à des fins de compatibilité descendante.

Chacune de ces fonctions prend un pointeur désignant une liste d’arguments, puis met en forme et écrit jusqu’à count caractères des données fournies dans la mémoire vers laquelle pointe buffer et enfin ajoute un caractère null de fin.

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.

Résumé du comportement

Pour le tableau suivant :

• Supposons len que la taille des données mises en forme soit la taille. 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	N/A	Non
Erreur d’encodage lors de la mise en forme	Si le spécificateur sde chaîne de traitement , Sou 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 == NULLet et sizeOfBuffer == 0count == 0	Aucune donnée n’est écrite.	0	N/A	Non
buffer == NULLet 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. 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
count == 0	N’écrit aucune donnée et retourne le nombre de caractères qui auraient été écrits, sans inclure la fin NULL.	Nombre de caractères qui auraient été écrits sans inclure la fin 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 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.	-1	N/A	Non
count >= sizeOfBuffer et len < sizeOfBuffer	Toutes les données sont écrites avec une fin NULL.	Nombre de caractères écrits, sans inclure la fin NULL.	N/A	Non
count >= sizeOfBufferet 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] == NULLet retourne une valeur négative.	-1	ERANGE (34)	Oui
count == _TRUNCATE et len >= sizeOfBuffer	Écrit autant de chaîne que cela correspond buffer, y compris la fin NULL.	-1	N/A	Non
count == _TRUNCATE et len < sizeOfBuffer	Écrit l’intégralité de la chaîne dans buffer laquelle se termine NULL.	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 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. Pour plus d’informations, consultez Éviter les dépassements de mémoire tampon. À 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 ».

Remarque

Pour être certain qu’il y a de l’espace pour accueillir le caractère null de fin, vérifiez 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è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.

Conseil

Si vous obtenez une erreur externe _vsnprintf_s non définie et que vous utilisez le runtime C universel, ajoutez legacy_stdio_definitions.lib à l’ensemble de 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é de Visual Studio 2015.

Mappages de routine de texte générique

TCHAR.H Routine	_UNICODE et _MBCS non défini	_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 , et <wchar.h><stdarg.h>	<varargs.h>*

* Obligatoire 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_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_start