`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, , `_vsnwprintf`, `_vsnwprintf_l`

2025-06-21

Escriba una salida con formato mediante un puntero a una lista de argumentos. Están disponibles versiones más seguras de estas funciones; Véase vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

Sintaxis

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

Parámetros

buffer
Ubicación de almacenamiento para la salida.

count
Número máximo de caracteres que se van a escribir. Para las funciones que toman wchar_t, es el número de caracteres anchos que se van a escribir.

format
Especificación de formato.

argptr
Puntero a la lista de argumentos.

locale
La configuración regional que se va a utilizar.

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

Valor devuelto

El número de caracteres escritos, sin incluir la terminación NULL, o un valor negativo si se produce un error de salida.

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

Observaciones

Cada una de estas funciones toma un puntero a una lista de argumentos, luego da formato a los datos y escribe en caracteres en count la memoria a la que apunta buffer. La vsnprintf función siempre escribe un terminador nulo, incluso si trunca la salida. Cuando se utiliza _vsnprintf y _vsnwprintf, el búfer termina en null solo si hay espacio al final (es decir, si el número de caracteres que se van a escribir es menor que count).

A partir del UCRT en Visual Studio 2015 y Windows 10, la palabra clave vsnprintf ya no es idéntica a _vsnprintf. La vsnprintf función cumple con el estándar C99; _vsnprintf se mantiene por compatibilidad con versiones anteriores de código antiguo. La diferencia es que si se queda sin búfer, vsnprintf termina en null el final del búfer y devuelve el número de caracteres que se habrían requerido, mientras _vsnprintf que no termina en null el búfer y devuelve -1. Además, _vsnprintf() incluye un carácter más en la salida porque no finaliza con null el búfer.

Importante

Para evitar ciertos tipos de riesgos de seguridad, asegúrese de que format no sea una cadena definida por el usuario. Para obtener más información, consulte Evitar saturaciones del 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 utilizar el comportamiento de redondeo de coma flotante heredado, vincule con 'legacy_stdio_float_rounding.obj'.

Nota:

Para asegurarse de que hay espacio para la terminación null al llamar a _vsnprintf, _vsnwprintf_vsnprintf_ly _vsnwprintf_l, asegúrese de que count sea estrictamente menor que la longitud del búfer e inicialice el búfer en null antes de llamar a la función.

Dado que vsnprintf siempre escribe un valor NULL de terminación, el count parámetro puede ser igual al tamaño del búfer.

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

En C++, estas funciones tienen sobrecargas de plantilla que invocan los homólogos más nuevos y seguros de estas funciones. Para obtener más información, consulte Sobrecargas de plantilla seguras.

Resumen del comportamiento

Para la tabla siguiente:

Deje que sizeOfBuffer sea el tamaño de buffer. 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.
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
Éxito	Escribe los caracteres en el búfer mediante la cadena de formato especificada.	El número de caracteres escritos, sin contar el carácter nulo de terminación.	No disponible	No
Error de codificación durante el formato	Si se procesa el especificador de `s`cadena , `S`, o `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 `count != 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 `count == 0`	No se escribe ningún dato	Número de caracteres que se habrían escrito, no incluido el terminador `NULL`. Puede usar este resultado para asignar suficiente espacio de búfer para la cadena y un terminado `NULL`y, a continuación, llamar a la función de nuevo para rellenar el búfer.	No disponible	No
`count == 0`	No se escribe ningún dato	-1	`ERANGE` (34)	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.	El número de caracteres que se han escrito.	No disponible	No
`count < sizeOfBuffer` y `len <= count`	Todos los datos se escriben y se anexa una terminación `NULL` .	Número de caracteres escritos, no incluido el terminador `NULL`.	No disponible	No
`count < sizeOfBuffer` y `len > count`	Los primeros `count-1` caracteres se escriben seguidos de un terminador null.	El número de caracteres que se habrían escrito coincidía `count` con el número de caracteres que se van a generar, no incluido el terminador null.	No disponible	No
`count >= sizeOfBuffer` y `len < sizeOfBuffer`	Todos los datos se escriben `NULL`con una terminación .	Número de caracteres escritos, no incluido el terminador `NULL`.	No disponible	No
`count >= sizeOfBuffer` y `len >= sizeOfBuffer`	Inseguro: sobrescribe la memoria que sigue al búfer.	Número de caracteres escritos, no incluido el terminador `NULL`.	No disponible	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.

Asignaciones de rutinas de texto genérico

Rutina `TCHAR.H`	`_UNICODE` y `_MBCS` no definidos	`_MBCS` definido	`_UNICODE` definido
`_vsntprintf`	`_vsnprintf`	`_vsnprintf`	`_vsnwprintf`
`_vsntprintf_l`	`_vsnprintf_l`	`_vsnprintf_l`	`_vsnwprintf_l`

Requisitos

Rutina	Encabezado requerido (C)	Encabezado requerido (C++)
`vsnprintf`, , `_vsnprintf`, `_vsnprintf_l`	`<stdio.h>`	`<stdio.h>` o `<cstdio>`
`_vsnwprintf`, `_vsnwprintf_l`	`<stdio.h>` o `<wchar.h>`	`<stdio.h>`, `<wchar.h>`, `<cstdio>`o `<cwchar>`

Las _vsnprintffunciones , _vsnprintf_l, _vsnwprintf y _vsnwprintf_l son específicas de Microsoft. Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo: Utilice caracteres anchos con `_vsnwprintf()`

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

El comportamiento cambia si se usa vsnprintf en su lugar, junto con parámetros de cadena estrecha. El count parámetro puede ser el tamaño completo del búfer y el valor devuelto es el número de caracteres que se habrían escrito si count fuera lo suficientemente grande:

Ejemplo: Uso `vsnprintf()` con cadenas estrechas

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

Consulte también

E/S de secuencia
Funciones vprintf
Sintaxis de especificación de formato: printf y wprintf funciones
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

Compartir a través de

vsnprintf, _vsnprintf, _vsnprintf_l, , _vsnwprintf, _vsnwprintf_l