vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_lvsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Écrivez la sortie mise en forme en utilisant un pointeur désignant une liste d’arguments.Write formatted output using a pointer to a list of arguments. Il existe des versions plus sécurisées de ces fonctions. Consultez vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.More secure versions of these functions are available; see vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

SyntaxeSyntax

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ètresParameters

bufferbuffer
Emplacement de stockage pour la sortie.Storage location for output.

countcount
Nombre maximal de caractères à écrire.Maximum number of characters to write.

formatformat
Spécification de format.Format specification.

argptrargptr
Pointeur vers la liste d'arguments.Pointer to list of arguments.

localelocale
Paramètres régionaux à utiliser.The locale to use.

Pour plus d'informations, consultez Spécifications de format.For more information, see Format Specifications.

Valeur de retourReturn Value

La fonction vsnprintf retourne le nombre de caractères écrits, sans compter le caractère null de fin.The vsnprintf function returns the number of characters written, not counting the terminating null character. Si la taille de la mémoire tampon spécifiée par Count n’est pas suffisamment grande pour contenir la sortie spécifiée par format et argptr, la valeur de retour de vsnprintf est le nombre de caractères qui seraient écrits, sans compter la valeur null caractère, si Count est suffisamment grand.If the buffer size specified by count is not sufficiently large to contain the output specified by format and argptr, the return value of vsnprintf is the number of characters that would be written, not counting the null character, if count were sufficiently large. Si la valeur de retour est supérieure à Count -1, la sortie a été tronquée.If the return value is greater than count - 1, the output has been truncated. La valeur de retour -1 indique qu’une erreur de codage s’est produite.A return value of -1 indicates that an encoding error has occurred.

Les fonctions _vsnprintf et _vsnwprintf retournent le nombre de caractères écrits si le nombre de caractères à écrire est inférieur ou égal à Count; Si le nombre de caractères à écrire est supérieur au nombre, cesfonctions retournent-1, ce qui indique que la sortie a été tronquée.Both _vsnprintf and _vsnwprintf functions return the number of characters written if the number of characters to write is less than or equal to count; if the number of characters to write is greater than count, these functions return -1 indicating that output has been truncated.

La valeur retournée par toutes ces fonctions n’inclut pas le caractère null de fin, qu’il soit écrit ou pas.The value returned by all these functions does not include the terminating null, whether one is written or not. Lorsque Count est égal à zéro, la valeur retournée est le nombre de caractères que les fonctions écriraient, à l’exclusion de la valeur null de fin.When count is zero, the value returned is the number of characters the functions would write, not including any terminating null. Vous pouvez utiliser ce résultat pour allouer un espace de mémoire tampon suffisant pour la chaîne et son caractère null de fin et rappeler ensuite la fonction pour remplir la mémoire tampon.You can use this result to allocate sufficient buffer space for the string and its terminating null, and then call the function again to fill the buffer.

Si format a la valeur null, ou si buffer a la valeur null et que Count n’est pas égal à zéro, ces fonctions appellent le gestionnaire de paramètres non valides, comme décrit dans validation de paramètre.If format is NULL, or if buffer is NULL and count is not equal to zero, these functions invoke the invalid parameter handler, as described in Parameter Validation. Si l’exécution est autorisée à se poursuivre, ces fonctions retournent-1 et attribuent à errno la valeur EINVAL.If execution is allowed to continue, these functions return -1 and set errno to EINVAL.

NotesRemarks

Chacune de ces fonctions prend un pointeur désignant une liste d’arguments, met en forme les données et écrit jusqu’à Count caractères dans la mémoire vers laquelle pointe la mémoire tampon.Each of these functions takes a pointer to an argument list, then formats the data, and writes up to count characters to the memory pointed to by buffer. La fonction vsnprintf écrit toujours une marque de fin null, même si elle tronque la sortie.The vsnprintf function always writes a null terminator, even if it truncates the output. Lors de l’utilisation de _vsnprintf et _vsnwprintf, la mémoire tampon se termine par un caractère NULL uniquement s’il y a de la place à la fin (autrement dit, si le nombre de caractères à écrire est inférieur à Count).When using _vsnprintf and _vsnwprintf, the buffer will be null-terminated only if there is room at the end (that is, if the number of characters to write is less than count).

Important

Pour éviter certains types de risques de sécurité, assurez-vous que le format n’est pas une chaîne définie par l’utilisateur.To prevent certain kinds of security risks, ensure that format is not a user-defined string. Pour plus d’informations, consultez Solutions contre les dépassements de mémoire tampon.For more information, see Avoiding Buffer Overruns.

Notes

Pour vous assurer qu’il y a de l’espace pour la valeur null de fin lors de l’appel de _vsnprintf, _vsnprintf_l, _vsnwprintf et _vsnwprintf_l, assurez-vous que le nombre est strictement inférieur à la longueur de la mémoire tampon et initialisez la mémoire tampon sur null avant d’appeler la fonction.To ensure that there is room for the terminating null when calling _vsnprintf, _vsnprintf_l, _vsnwprintf and _vsnwprintf_l, be sure that count is strictly less than the buffer length and initialize the buffer to null prior to calling the function.

Étant donné que vsnprintf écrit toujours la valeur null de fin, le paramètre Count peut être égal à la taille de la mémoire tampon.Because vsnprintf always writes the terminating null, the count parameter may be equal to the size of the buffer.

À compter de UCRT dans Visual Studio 2015 et Windows 10, vsnprintf n’est plus identique à _vsnprintf.Beginning with the UCRT in Visual Studio 2015 and Windows 10, vsnprintf is no longer identical to _vsnprintf. La fonction vsnprintf est conforme à la norme C99 ; _vnsprintf est conservé pour la compatibilité descendante avec les versions antérieures de Visual Studio code.The vsnprintf function complies with the C99 standard; _vnsprintf is retained for backward compatibility with older Visual Studio code.

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.The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

En C++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions.In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. Pour plus d'informations, consultez Secure Template Overloads.For more information, see Secure Template Overloads.

Mappages de routines de texte génériqueGeneric-Text Routine Mappings

Routine TCHAR.HTCHAR.H routine _UNICODE et _MBCS non définis_UNICODE & _MBCS not defined _MBCS défini_MBCS defined _UNICODE défini_UNICODE defined
_vsntprintf_vsntprintf _vsnprintf_vsnprintf _vsnprintf_vsnprintf _vsnwprintf_vsnwprintf
_vsntprintf_l_vsntprintf_l _vsnprintf_l_vsnprintf_l _vsnprintf_l_vsnprintf_l _vsnwprintf_l_vsnwprintf_l

Configuration requiseRequirements

RoutineRoutine En-tête requis (C)Required header (C) En-tête requis (C++)Required header (C++)
vsnprintf, _vsnprintf, _vsnprintf_lvsnprintf, _vsnprintf, _vsnprintf_l <stdio.h><stdio.h> <stdio.h> ou <cstdio><stdio.h> or <cstdio>
_vsnwprintf, _vsnwprintf_l_vsnwprintf, _vsnwprintf_l <stdio.h> ou <wchar.h><stdio.h> or <wchar.h> <stdio.h>, <wchar.h>, <cstdio> ou <cwchar><stdio.h>, <wchar.h>, <cstdio>, or <cwchar>

Les fonctions _vsnprintf, _vsnprintf_l, _vsnwprintf et _vsnwprintf_l sont spécifiques à Microsoft.The _vsnprintf, _vsnprintf_l, _vsnwprintf and _vsnwprintf_l functions are Microsoft specific. Pour plus d'informations sur la compatibilité, voir Compatibilité.For additional compatibility information, see Compatibility.

ExempleExample

// 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.The behavior changes if you use vsnprintf instead, along with narrow-string parameters. Le paramètre Count peut être la taille totale de la mémoire tampon, et la valeur de retour est le nombre de caractères qui auraient été écrits si Count était suffisamment grand :The count parameter can be the entire size of the buffer, and the return value is the number of characters that would have been written if count was large enough:

ExemplesExample

// 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 aussiSee also

E/S de fluxStream I/O
vprintf, fonctionsvprintf Functions
Syntaxe de spécification de format : fonctions printf et wprintfFormat Specification Syntax: printf and wprintf Functions
fprintf, _fprintf_l, fwprintf, _fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_lprintf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_startva_arg, va_copy, va_end, va_start