vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_lvsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_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. Ces versions de vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l intègrent les améliorations de sécurité décrites dans Fonctionnalités de sécurité dans le CRT.These are versions of vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l with security enhancements as described in Security Features in the CRT.

SyntaxeSyntax

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

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

sizeOfBuffersizeOfBuffer
Taille de la mémoire tampon pour la sortie, en tant que nombre de caractères.The size of the buffer for output, as the character count.

countcount
Nombre maximal de caractères à écrire (à l’exclusion du caractère null de fin) ou _TRUNCATE.Maximum number of characters to write (not including the terminating null), or _TRUNCATE.

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

vsnprintf_s, _vsnprintf_s et _vsnwprintf_s retournent le nombre de caractères écrits, à l’exclusion de la valeur null de fin, ou une valeur négative si une erreur de sortie se produit.vsnprintf_s, _vsnprintf_s and _vsnwprintf_s return the number of characters written, not including the terminating null, or a negative value if an output error occurs. vsnprintf_s est identique à _vsnprintf_s.vsnprintf_s is identical to _vsnprintf_s. vsnprintf_s est inclus pour la conformité à la norme ANSI.vsnprintf_s is included for compliance to the ANSI standard. _vnsprintf est conservé pour la compatibilité descendante._vnsprintf is retained for backward compatibility.

Si le stockage requis pour stocker les données et une valeur null de fin dépasse sizeOfBuffer, le gestionnaire de paramètres non valides est appelé, comme décrit dans validation de paramètre, sauf si le nombre est _TRUNCATE, auquel cas la plus grande partie de la une chaîne telle qu’elle sera contenue dans la mémoire tampon est écrite et-1 est retourné.If the storage required to store the data and a terminating null exceeds sizeOfBuffer, the invalid parameter handler is invoked, as described in Parameter Validation, unless count is _TRUNCATE, in which case as much of the string as will fit in buffer is written and -1 returned. Si l’exécution se poursuit après le gestionnaire de paramètres non valides, ces fonctions définissent la mémoire tampon sur une chaîne vide, attribuent à errno la valeur ERANGEet retournent-1.If execution continues after the invalid parameter handler, these functions set buffer to an empty string, set errno to ERANGE, and return -1.

Si la mémoire tampon ou le format est un pointeur null , ou si Count est inférieur ou égal à zéro, le gestionnaire de paramètre non valide est appelé.If buffer or format is a NULL pointer, or if count is less than or equal to zero, the invalid parameter handler is invoked. Si l’exécution est autorisée à se poursuivre, ces fonctions définissent errno sur EINVAL et retournent-1.If execution is allowed to continue, these functions set errno to EINVAL and return -1.

Conditions d’erreurError Conditions

ConditionCondition RenvoieReturn errnoerrno
la mémoire tampon est nullbuffer is NULL -1-1 EINVALEINVAL
le format est nullformat is NULL -1-1 EINVALEINVAL
count <= 0count <= 0 -1-1 EINVALEINVAL
sizeOfBuffer trop petit (et Count ! = _TRUNCATE)sizeOfBuffer too small (and count != _TRUNCATE) -1 (et la mémoire tampon est définie sur une chaîne vide)-1 (and buffer set to an empty string) ERANGEERANGE

NotesRemarks

Chacune de ces fonctions prend un pointeur vers une liste d’arguments, puis met en forme et écrit jusqu’à compter les caractères des données spécifiées dans la mémoire vers laquelle pointe la mémoire tampon et ajoute une valeur null de fin.Each of these functions takes a pointer to an argument list, then formats and writes up to count characters of the given data to the memory pointed to by buffer and appends a terminating null.

Si le nombre est _TRUNCATE, ces fonctions écrivent autant de chaînes que possible dans la mémoire tampon tout en laissant de l’espace pour une valeur null de fin.If count is _TRUNCATE, then these functions write as much of the string as will fit in buffer while leaving room for a terminating null. Si la chaîne entière (avec une valeur null de fin) s’ajuste à la mémoire tampon, ces fonctions retournent le nombre de caractères écrits (à l’exclusion de la valeur null de fin); Sinon, ces fonctions retournent-1 pour indiquer que la troncation s’est produite.If the entire string (with terminating null) fits in buffer, then these functions return the number of characters written (not including the terminating null); otherwise, these functions return -1 to indicate that truncation occurred.

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.

Important

Assurez-vous que format n'est pas une chaîne définie par l'utilisateur.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, assurez-vous que le nombre est strictement inférieur à la longueur de la mémoire tampon, ou utilisez _TRUNCATE.To ensure that there is room for the terminating null, be sure that count is strictly less than the buffer length, or use _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.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 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_s_vsntprintf_s _vsnprintf_s_vsnprintf_s _vsnprintf_s_vsnprintf_s _vsnwprintf_s_vsnwprintf_s
_vsntprintf_s_l_vsntprintf_s_l _vsnprintf_s_l_vsnprintf_s_l _vsnprintf_s_l_vsnprintf_s_l _vsnwprintf_s_l_vsnwprintf_s_l

Configuration requiseRequirements

RoutineRoutine En-tête requisRequired header En-têtes facultatifsOptional headers
vsnprintf_svsnprintf_s <stdio.h> et <stdarg.h><stdio.h> and <stdarg.h> <varargs.h>*<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l_vsnprintf_s, _vsnprintf_s_l <stdio.h> et <stdarg.h><stdio.h> and <stdarg.h> <varargs.h>*<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l_vsnwprintf_s, _vsnwprintf_s_l <stdio.h> ou <wchar.h> et <stdarg.h><stdio.h> or <wchar.h>, and <stdarg.h> <varargs.h>*<varargs.h>*

* Nécessaire pour la compatibilité avec UNIX V.* Required for UNIX V compatibility.

Pour plus d'informations sur la compatibilité, voir Compatibilité.For additional compatibility information, see Compatibility.

ExemplesExample

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

E/S de fluxStream I/O
vprintf, fonctionsvprintf 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