Partage via

vsnprintf, , _vsnprintf_vsnprintf_l, , _vsnwprintf_vsnwprintf_l

  • Article

Écrivez la sortie mise en forme en utilisant un pointeur désignant une liste d’arguments. Des versions plus sécurisées de ces fonctions sont disponibles ; voir vsnprintf_s, , _vsnprintf_s_l_vsnprintf_s, , . _vsnwprintf_s_l_vsnwprintf_s

Syntaxe

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

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

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

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

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

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

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

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

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

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

Paramètres

buffer
Emplacement de stockage pour la sortie.

count
Nombre maximal de caractères à écrire. Pour les fonctions qui prennent wchar_t, il s’agit du nombre de caractères larges à écrire.

format
Spécification de format.

argptr
Pointeur vers la liste d'arguments.

locale
Paramètres régionaux à utiliser.

Pour plus d’informations, consultez la syntaxe de spécification 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

Chacune de ces fonctions prend un pointeur vers une liste d’arguments, met en forme les données et écrit jusqu’à count caractères dans la mémoire vers laquelle bufferpointe. La fonction vsnprintf écrit toujours une marque de fin null, même si elle tronque le résultat. Lorsque vous utilisez _vsnprintf et _vsnwprintfque la mémoire tampon est terminée par null uniquement s’il y a de la place à la fin (autrement dit, si le nombre de caractères à écrire est inférieur countà ).

Depuis le composant UCRT dans Visual Studio 2015 et Windows 10, vsnprintf n’est plus identique à _vsnprintf. La vsnprintf fonction est conforme à la norme C99 ; _vsnprintf elle est conservée pour une compatibilité descendante avec un code plus ancien. La différence est que si vous n’avez plus de mémoire tampon, vsnprintf null met fin à la fin de la mémoire tampon et retourne le nombre de caractères qui auraient été requis, tandis que _vsnprintf ne termine pas la mémoire tampon null et retourne -1. _vsnprintf() Inclut également un caractère supplémentaire dans la sortie, car il n’arrête pas la mémoire tampon.

Important

Pour éviter certains types de risques de sécurité, assurez-vous qu’il format ne s’agit pas d’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 vous assurer qu’il existe une place pour la fin de la valeur Null lors de l’appel _vsnprintf, _vsnprintf_l_vsnwprintf et _vsnwprintf_lassurez-vous qu’elle count est strictement inférieure à la longueur de la mémoire tampon et initialise la mémoire tampon sur Null avant d’appeler la fonction.

Étant donné que vsnprintf toujours écrit une valeur null de fin, le count paramètre peut être égal à la taille de la mémoire tampon.

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++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions. Pour plus d’informations, consultez Surcharges de modèles sécurisés.

Résumé du comportement

Pour le tableau suivant :

  • Supposons sizeOfBuffer que la taille soit la taille de buffer. 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.
  • 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, sans compter le caractère null de fin. S/O 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 count != 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
count == 0 Aucune donnée n’est écrite Nombre de caractères qui auraient été écrits, sans inclure la fin NULL. Vous pouvez utiliser ce résultat pour allouer suffisamment d’espace tampon pour la chaîne et une fin NULL, puis appeler à nouveau la fonction pour remplir la mémoire tampon. S/O 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. S/O Non
count < sizeOfBuffer et len <= count Toutes les données sont écrites et une fin NULL est ajoutée. Nombre de caractères écrits, sans inclure la fin NULL. S/O Non
count < sizeOfBuffer et len > count Les premiers count-1 caractères sont écrits suivis d’un terminateur null. Le nombre de caractères qui auraient été écrits avait count mis en correspondance le nombre de caractères à générer, sans inclure le terminateur Null. S/O 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. S/O Non
count >= sizeOfBuffer et len >= sizeOfBuffer Non sécurisé : remplace la mémoire qui suit la mémoire tampon. Nombre de caractères écrits, sans inclure la fin NULL. S/O 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

Mappages de routine de texte générique

TCHAR.H Routine _UNICODE et _MBCS non défini _MBCS Défini _UNICODE Défini
_vsntprintf _vsnprintf _vsnprintf _vsnwprintf
_vsntprintf_l _vsnprintf_l _vsnprintf_l _vsnwprintf_l

Spécifications

Routine En-tête requis (C) En-tête requis (C++)
vsnprintf, , _vsnprintf_vsnprintf_l <stdio.h> <stdio.h> ou <cstdio>
_vsnwprintf, _vsnwprintf_l <stdio.h> ou <wchar.h> <stdio.h>, <wchar.h>, <cstdio>, ou <cwchar>

Les _vsnprintffonctions et les fonctions _vsnprintf_l_vsnwprintf_vsnwprintf_l sont spécifiques à Microsoft. Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple : Utiliser des caractères larges avec _vsnwprintf()

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

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

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

Le comportement change si vous utilisez à la place vsnprintf avec des paramètres à chaîne étroite. Le paramètre count peut représenter la taille totale de la mémoire tampon, et la valeur de retour correspond au nombre de caractères qui auraient été écrits si count avait une taille suffisante :

Exemple : Utiliser vsnprintf() avec des chaînes étroites

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

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

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

Voir aussi

E/S de flux
vprintf, fonctions
Syntaxe de spécification de format : printf et wprintf 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