vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Article
06/09/2015

Ecrit une sortie formattée en utilisant un pointeur vers une liste d'arguments. Ce sont des versions de vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l qui présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

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

buffer
Emplacement de stockage pour la sortie.
sizeOfBuffer
La taille du buffer pour la sortie, comme le compteur de caractères.
count
Nombre maximal de caractères à écrire (sans caractère Null de fin), ou _TRUNCATE.
format
Spécification de format.
argptr
Pointeur vers la liste d'arguments.
locale
Paramètres régionaux à utiliser.

Pour plus d'informations, consultez Spécifications de format.

Valeur de retour

vsnprintf_s,_vsnprintf_s et _vsnwprintf_s renvoient le nombre de caractères écrits, sans le caractère null de fin, ou une valeur négative si une erreur de sortie se produit. vsnprintf_s est identique à _vsnprintf_s. vsnprintf_s est inclus pour la conformité à la norme ANSI. _vnsprintf est conservée pour des raisons de rétrocompatibilité.

Si le stockage requis pour stocker les données et un 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 count est _TRUNCATE, auquel cas la plus grande partie de la chaîne sera insérée dans le buffer est écrit et -1 retourné. Si l'exécution reprend après le gestionnaire de paramètres non valides, ces fonctions définissent buffer comme une chaîne vide, mettent errno à ERANGE, et retournent -1.

Si buffer ou format est un pointeur NULL, ou si count est inférieur ou égal à zéro, le gestionnaire de paramètres non valides est appelé. Si l'exécution est autorisée à se poursuivre, ces fonctions définissent errno avec la valeur EINVAL et retournent -1.

Conditions d'erreur

Condition	Return	errno
buffer est NULL	-1	EINVAL
format est NULL	-1	EINVAL
count <= 0	-1	EINVAL
sizeOfBuffer trop petit (et count != _TRUNCATE)	-1 (et buffer a la valeur d'une chaîne vide)	ERANGE

Notes

Chacune de ces fonctions prend un pointeur vers une liste d'arguments, puis le formate et écrit jusqu'à count caractères des données fournies à la mémoire pointée par buffer et ajoute Null de fin.

Si count est _TRUNCATE, alors ces fonctions écrivent autant de la chaîne que possible dans buffer tout en laissant de la place pour un Null de fin. Si la chaîne entière (avec un null de fin) rentre dans buffer, alors ces fonctions retournent le nombre de caractères écrit (sans Null de fin) ; sinon, ces fonctions retournent -1 pour indiquer que la troncature s'est produite.

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.

Note de sécurité
Assurez-vous que format n'est pas une chaîne définie par l'utilisateur.Pour plus d'informations, consultez Solutions contre les dépassements de mémoire tampon.

Notes

Pour vous assurer qu'il y a de la place pour le Null de fin, vérifiez si count est strictement inférieure à la longueur de la mémoire tampon, ou utilisez _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. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_MBCS défini	_UNICODE défini
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Équivalent .NET Framework

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

Configuration requise

Routine	En-tête requis	En-têtes facultatifs
vsnprintf_s	<stdio.h> et <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> et <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> ou <wchar.h>, et <stdarg.h>	<varargs.h>*

* Requis pour la compatibilité UNIX V.

Pour plus d'informations sur la compatibilité, consultez Compatibilité dans l'introduction.

Exemple

// 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);
}

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