`vsnprintf`, , `_vsnprintf_vsnprintf_l`, , `_vsnwprintf_vsnwprintf_l`

Article
08/03/2024

É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 Syntaxe de spécification 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

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

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
Réussite	É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 `s`de chaîne de traitement , `S`ou `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 routines de texte générique

Routine `TCHAR.H`	`_UNICODE` et `_MBCS` non définis	`_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

Partager via

`vsnprintf`, , `_vsnprintf_vsnprintf_l`, , `_vsnwprintf_vsnwprintf_l`

Syntaxe

Paramètres

Valeur retournée

Notes

Résumé du comportement

Mappages de routines de texte générique

Spécifications

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

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

Voir aussi

Commentaires

Ressources supplémentaires

Partager via

vsnprintf, , _vsnprintf_vsnprintf_l, , _vsnwprintf_vsnwprintf_l

Syntaxe

Paramètres

Valeur retournée

Notes

Résumé du comportement

Mappages de routines de texte générique

Spécifications

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

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

Voir aussi

Commentaires

Ressources supplémentaires

`vsnprintf`, , `_vsnprintf_vsnprintf_l`, , `_vsnwprintf_vsnwprintf_l`

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

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