vsnprintf, , _vsnprintf_vsnprintf_l, , _vsnwprintf_vsnwprintf_l

Écrivez une sortie formatée à l’aide d’un pointeur vers une liste d’arguments. Des versions plus sécurisées de ces fonctions sont disponibles ; voir vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

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 maximum de caractères à écrire. Pour les fonctions qui prennent wchar_t, c’est le nombre de caractères larges à écrire.

format
Spécification du format.

argptr
Pointeur vers la liste des arguments.

locale
Locale à utiliser.

Pour plus d’informations, consultez Syntaxe de spécification 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 les données et écrit jusqu’en count caractères dans la mémoire pointée par buffer. La vsnprintf fonction écrit toujours un terminateur null, même si elle tronque la sortie. Lorsque vous utilisez _vsnprintf et _vsnwprintf, la mémoire tampon n’est terminée par un caractère null que s’il y a de la place à la fin (c’est-à-dire si le nombre de caractères à écrire est inférieur à count).

À partir de l’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 des raisons de compatibilité descendante avec le code plus ancien. La différence est que si vous n’avez plus de mémoire tampon, vsnprintf la valeur null met fin à la fin de la mémoire tampon et renvoie le nombre de caractères qui auraient été nécessaires, tandis _vsnprintf que la valeur n’est pas définie sur la valeur null de la mémoire tampon et renvoie -1. Inclut également un caractère supplémentaire dans la sortie, _vsnprintf() car il ne met pas fin à la mémoire tampon de manière nulle.

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.

En C++, ces fonctions ont des surcharges de modèle qui appellent les homologues 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 :

• Soit sizeOfBuffer la taille de buffer. 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.
• 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.

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

Mappages de routines de texte générique

Spécifications

Les _vsnprintffonctions , _vsnprintf_l_vsnwprintfet _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 vsnprintf à la place, ainsi que des paramètres de chaîne étroite. Le count paramètre peut correspondre à la taille totale de la mémoire tampon, et la valeur de retour est le nombre de caractères qui auraient été écrits s’il count avait été suffisamment grand :

Exemple : Utilisation vsnprintf() avec des cordes é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
Spécification de format, printf syntaxe : et wprintf 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