vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l

Article
06/09/2015

Ecrit une sortie formattée en utilisant un pointeur vers une liste d'arguments. Il s'agit de versions de vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

int vsprintf_s(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   va_list argptr 
); 
int _vsprintf_s_l(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   locale_t locale,
   va_list argptr 
); 
int vswprintf_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   va_list argptr 
);
int _vswprintf_s_l(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsprintf_s(
   char (&buffer)[size],
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int vswprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   va_list argptr 
); // C++ only

Paramètres

buffer
Emplacement de stockage pour la sortie.
numberOfElements
Taille de buffer en caractères.
format
Spécification de format.
argptr
Pointeur vers la liste d'arguments.
locale
Paramètres régionaux à utiliser.

Valeur de retour

vsprintf_s et vswprintf_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. Si soit buffer est un pointeur null, soit format est un pointeur null, si le compte vaut 0, ou si le format de la chaine contient des caractères formant invalides, le gestionnaire de paramètres invalides est appelé comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, cette fonction renvoient -1 et définie errno avec la valeur EINVAL.

Pour plus d'informations sur ces codes d'erreur et autres, consultez _doserrno, errno, _sys_errlist et _sys_nerr.

Notes

Chacune de ces fonctions prend un pointeur comme liste d'arguments, et le forme ensuite puis écrit les données dans la mémoire pointée par buffer.

vswprintf_s est conforme au Standard ISO C pour vswprintf, ce qui requiert le second paramètre, count, de type size_t.

Ces fonctions diffèrent des versions non sécurisés uniquement car les versions sécurisées prennent en charge les paramètres positionnels. Pour plus d'informations, consultez Paramètres positionnels printf_p.

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++, 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
_vstprintf_s	vsprintf_s	vsprintf_s	vswprintf_s
_vstprintf_s_l	_vsprintf_s_l	_vsprintf_s_l	_vswprintf_s_l

Configuration requise

Routine	En-tête requis	En-têtes facultatifs
vsprintf_s, _vsprintf_s_l	<stdio.h> et <stdarg.h>	<varargs.h>*
vswprintf_s, _vswprintf_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_vsprintf_s.c
// This program uses vsprintf_s to write to a buffer.
// The size of the buffer is determined by _vscprintf.

#include <stdlib.h>
#include <stdarg.h>

void test( char * format, ... )
{
   va_list args;
   int len;
   char * buffer;

   va_start( args, format );
   len = _vscprintf( format, args ) // _vscprintf doesn't count
                               + 1; // terminating '\0'
   buffer = malloc( len * sizeof(char) );
   vsprintf_s( buffer, len, format, args );
   puts( buffer );
   free( buffer );
}

int main( void )
{
   test( "%d %c %d", 123, '<', 456 );
   test( "%s", "This is a string" );
}