vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Escribe un resultado con formato mediante un puntero a una lista de argumentos. Estas funciones son versiones de vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintfcon _vsnwprintf_l mejoras de seguridad, como se describe en Características de seguridad de CRT.

Sintaxis

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

Parámetros

buffer
Ubicación de almacenamiento del resultado.

sizeOfBuffer
Tamaño de para buffer la salida. Tamaño en bytes para las funciones que toman chary palabras para las que toman wchar_t.

count
Número máximo de caracteres que se van a escribir sin incluir la terminación NULL. Para las funciones que toman wchar_t, es el número de caracteres anchos que se van a escribir. O _TRUNCATE.

format
Especificación de formato.

argptr
Puntero a la lista de argumentos.

locale
Configuración regional que se va a usar al dar formato a la salida.

Para obtener más información, consulte Especificaciones de formato.

Valor devuelto

Número de caracteres escritos, sin incluir el terminado NULLo un valor negativo si se produce un error de salida.

Consulte Resumen del comportamiento para obtener más información.

Comentarios

vsnprintf_s es idéntico a _vsnprintf_s y se incluye para cumplir el estándar ANSI. La clase _vnsprintf se conserva por razones de compatibilidad con versiones anteriores.

Cada una de estas funciones toma un puntero a una lista de argumentos, después da formato a un máximo de count caracteres, y los escribe, de los datos especificados en la memoria a la que señala buffer y anexa un carácter nulo final.

Las versiones de estas funciones con el sufijo _l son idénticas salvo que usan el parámetro locale pasado en lugar de la configuración regional del subproceso actual.

Resumen del comportamiento

Para la tabla siguiente:

• Vamos len a ser el tamaño de los datos con formato. Si la función toma un char búfer, el tamaño está en bytes. Si la función toma un wchar_t búfer, el tamaño especifica el número de palabras de 16 bits.
• Los caracteres hacen referencia a char caracteres para funciones que toman un char búfer y a wchar_t caracteres para las funciones que toman un wchar_t búfer.
• Para obtener más información sobre el controlador de parámetros no válidos, vea Validación de parámetros.

Condición	Comportamiento	Valor devuelto	errno	Invoca el controlador de parámetros no válidos
Correcto	Escribe los caracteres en el búfer mediante la cadena de formato especificada.	Número de caracteres escritos	N/D	No
Error de codificación durante el formato	Si el especificador sde cadena de procesamiento , So Z, se detiene el procesamiento de la especificación de formato.	-1	EILSEQ (42)	No
Error de codificación durante el formato	Si el especificador c de caracteres de procesamiento o C, se omite el carácter no válido. El número de caracteres escritos no se incrementa para el carácter omitido, ni es ningún dato escrito para él. El procesamiento de la especificación de formato continúa después de omitir el especificador con el error de codificación.	Número de caracteres escritos, no incluido el terminador NULL.	EILSEQ (42)	No
buffer == NULL y sizeOfBuffer == 0 y count == 0	No se escriben datos.	0	N/D	No
buffer == NULLy o sizeOfBuffer != 0count != 0	Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece errno y devuelve un valor negativo.	-1	EINVAL (22)	Sí
buffer != NULL y sizeOfBuffer == 0	No se escriben datos. Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece errno y devuelve un valor negativo.	-1	EINVAL (22)	Sí
count == 0	No escribe ningún dato y devuelve el número de caracteres que se habrían escrito, sin incluir la terminación NULL.	El número de caracteres que se habrían escrito no incluye la terminación NULL.	N/D	No
count < 0	No seguro: el valor se trata como sin firmar, lo que probablemente crea un valor grande que da lugar a sobrescribir la memoria que sigue al búfer.	Número de caracteres escritos, no incluido el terminador NULL.	N/D	No
count < sizeOfBuffer y len <= count	Todos los datos se escriben y se anexa una terminación NULL .	El número de caracteres que se han escrito.	N/D	No
count < sizeOfBuffer y len > count	Los primeros count caracteres se escriben.	-1	N/D	No
count >= sizeOfBuffer y len < sizeOfBuffer	Todos los datos se escriben NULLcon una terminación .	Número de caracteres escritos, no incluido el terminador NULL.	N/D	No
count >= sizeOfBuffer y len >= sizeOfBuffer y count != _TRUNCATE	Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece , establece errnobuffer[0] == NULLy devuelve un valor negativo.	-1	ERANGE (34)	Sí
count == _TRUNCATE y len >= sizeOfBuffer	Escribe tanta cadena como se ajuste a buffer, incluido el terminador NULL.	-1	N/D	No
count == _TRUNCATE y len < sizeOfBuffer	Escribe toda la cadena en buffer con terminación NULL.	Número de caracteres escritos.	N/D	No
format == NULL	No se escriben datos. Si la ejecución continúa después de que se ejecute el controlador de parámetros no válidos, establece errno y devuelve un valor negativo.	-1	EINVAL (22)	Sí

Para información sobre estos y otros códigos de error, consulte _doserrno, errno_sys_errlist y _sys_nerr.

Importante

Asegúrese de que format no es una cadena definida por el usuario. Para obtener más información, consulte Evitar saturaciones de búfer. A partir de Windows 10 versión 2004 (compilación 19041), la familia de funciones printf imprime números de punto flotante que se pueden representar con exactitud según las reglas de redondeo de IEEE 754. En versiones anteriores de Windows, los números de punto flotante que se pueden representar de forma exacta y terminan en "5" siempre se redondean al alza. IEEE 754 indica que deben redondearse al dígito par más próximo (también conocido como "redondeo bancario"). Por ejemplo, tanto printf("%1.0f", 1.5) como printf("%1.0f", 2.5) deben redondearse a 2. Anteriormente, 1,5 se redondearía a 2 y 2,5 a 3. Este cambio solo afecta a los números que se pueden representar de forma exacta. Por ejemplo, 2,35 (que, cuando se representa en memoria, está más cerca de 2,35000000000000008) se sigue redondeando hasta 2,4. El redondeo realizado por estas funciones ahora también respeta el modo de redondeo de punto flotante que fesetround establece. Anteriormente, el redondeo siempre elegía el comportamiento FE_TONEAREST. Este cambio solo afecta a los programas compilados con Visual Studio 2019 versión 16.2 y posteriores. Para usar el comportamiento de redondeo de punto flotante heredado, establezca un vínculo con "legacy_stdio_float_rounding.obj".

Nota:

Para asegurarse de que hay espacio para el valor nulo final, asegúrese de que count es claramente menor que la longitud del búfer, o use _TRUNCATE.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, consulte Sobrecargas de plantillas seguras.

Sugerencia

Si recibe un error externo indefinido _vsnprintf_s y usa el runtime de C universal, agregue legacy_stdio_definitions.lib al conjunto de bibliotecas para vincular. El entorno de tiempo de ejecución de C de Universal no exporta esta función directamente, sino que se define en línea en <stdio.h>. Para obtener más información, vea Información general sobre posibles problemas de actualización y cambios de conformidad de Visual Studio 2015.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Requisitos

Routine	Encabezado necesario	Encabezados opcionales
vsnprintf_s	<stdio.h> y <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> y <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> o <wchar.h>, y <stdarg.h>	<varargs.h>*

* Se requiere para la compatibilidad con UNIX V.

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// 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!

Consulte también

E/S de secuencia
Funciones vprintf
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_start