Partager via

vsnprintf_s, , _vsnprintf_s_vsnprintf_s_l, , _vsnwprintf_s_vsnwprintf_s_l

  • Article

É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
Les paramètres régionaux à utiliser lors du formatage 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 == NULL et sizeOfBuffer == 0 et count == 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 >= sizeOfBuffer et len >= sizeOfBuffer et count != _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 Solutions contre les dépassements de mémoire tampon. À 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'.

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 Sécuriser les surcharges de modèle.

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 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 , 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_lfwprintf, ,_fwprintf_l
printf, , _printf_lwprintf, ,_wprintf_l
sprintf, , _sprintf_lswprintf, , _swprintf_l__swprintf_l
va_arg, , va_copyva_end, ,va_start