Compartir a través de

vsnprintf, _vsnprintf, _vsnprintf_l, , _vsnwprintf, _vsnwprintf_l

  • Artículo

Escribe un resultado con formato mediante un puntero a una lista de argumentos. Hay disponibles versiones más seguras de estas funciones; consulte 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 del resultado.

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
Configuración regional que se va a usar.

Para obtener más información, vea sintaxis de especificación 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

Cada una de estas funciones toma un puntero a una lista de argumentos y, después, da formato a los datos y escribe hasta el número de caracteres de count en la memoria a la que apunta buffer. La función vsnprintf siempre escribe un terminador null, aunque trunque el resultado. Cuando se usa _vsnprintf y _vsnwprintf, el búfer solo termina en null si hay espacio al final (es decir, si el número de caracteres que se va 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 se ajusta al estándar C99; _vsnprintf se mantiene por motivos de compatibilidad con versiones anteriores con código anterior. La diferencia es que si se agota el búfer, vsnprintf null finaliza el final del búfer y devuelve el número de caracteres que se habrían requerido, mientras _vsnprintf que no finaliza el búfer en null 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 usar el comportamiento de redondeo de punto flotante heredado, establezca un vínculo con "legacy_stdio_float_rounding.obj".

Nota:

Para garantizar que haya espacio para el valor NULL final al llamar a _vsnprintf, _vsnprintf_l, _vsnwprintf y _vsnwprintf_l, asegúrese de que count sea estrictamente inferior a la longitud del búfer e inicialice el búfer a un valor 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 sufijo _l son idénticas salvo que usan el parámetro locale pasado en lugar de la configuración regional del subproceso actual.

En C++, estas funciones tienen sobrecargas de plantilla que invocan los homólogos seguros más recientes 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
Correcto Escribe los caracteres en el búfer mediante la cadena de formato especificada. Número de caracteres escritos, sin contar el carácter nulo de terminación. 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 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í
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 NULLy, a continuación, llamar a la función de nuevo para rellenar el búfer. 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. El número de caracteres que se han escrito. N/D 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. N/D 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. 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 No seguro: sobrescribe la memoria que sigue al búfer. Número de caracteres escritos, no incluido el terminador NULL. 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.

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

Routine Encabezado necesario (C) Encabezado necesario (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 funciones _vsnprintf, _vsnprintf_l, _vsnwprintf y _vsnwprintf_l son específicas de Microsoft. Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo: Uso de 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 usa vsnprintf en su lugar, junto con los parámetros de cadena de caracteres estrechos. El parámetro count puede ser todo el tamaño del búfer y el valor devuelto es el número de caracteres que se hubieran escrito si count fuera lo suficientemente grande:

Ejemplo: Uso de 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