Namespaces
Variants

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
vprintf vfprintf vsprintf vsnprintf vprintf_s vfprintf_s vsprintf_s vsnprintf_s
(C99) (C11) (C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
Definido en el encabezado <stdio.h>
(1)
int vprintf ( const char * format, va_list vlist ) ;
(hasta C99)
int vprintf ( const char * restrict format, va_list vlist ) ;
(desde C99)
(2)
int vfprintf ( FILE * stream, const char * format, va_list vlist ) ;
(hasta C99)
int vfprintf ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(desde C99)
(3)
int vsprintf ( char * buffer, const char * format, va_list vlist ) ;
(hasta C99)
int vsprintf ( char * restrict buffer, const char * restrict format,
va_list vlist ) ;
(desde C99)
int vsnprintf ( char * restrict buffer, size_t bufsz,
const char * restrict format, va_list vlist ) ;
(4) (desde C99)
int vprintf_s ( const char * restrict format, va_list vlist ) ;
(5) (desde C11)
int vfprintf_s ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(6) (desde C11)
int vsprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(7) (desde C11)
int vsnprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(8) (desde C11)

Carga los datos desde las ubicaciones, definidas por vlist , los convierte a equivalentes de cadena de caracteres y escribe los resultados a una variedad de destinos.

1) Escribe los resultados en stdout .
2) Escribe los resultados a un flujo de archivo stream .
3) Escribe los resultados en una cadena de caracteres buffer .
4) Escribe los resultados en una cadena de caracteres buffer . Se escriben como máximo bufsz - 1 caracteres. La cadena de caracteres resultante terminará con un carácter nulo, a menos que bufsz sea cero. Si bufsz es cero, no se escribe nada y buffer puede ser un puntero nulo, sin embargo el valor de retorno (número de bytes que se escribirían sin incluir el terminador nulo) aún se calcula y devuelve.
5-8) Igual que (1-4) , excepto que los siguientes errores se detectan en tiempo de ejecución y llaman a la función manejador de restricciones actualmente instalada:
  • el especificador de conversión %n está presente en format
  • cualquiera de los argumentos correspondientes a %s es un puntero nulo
  • format o buffer es un puntero nulo
  • bufsz es cero o mayor que RSIZE_MAX
  • ocurren errores de codificación en cualquiera de los especificadores de conversión de cadena y carácter
  • (solo para vsprintf_s ), la cadena a almacenar en buffer (incluyendo el nulo final) excedería bufsz
Como con todas las funciones con verificación de límites, vprintf_s , vfprintf_s , vsprintf_s , y vsnprintf_s solo están garantizadas de estar disponibles si __STDC_LIB_EXT1__ está definido por la implementación y si el usuario define __STDC_WANT_LIB_EXT1__ como la constante entera 1 antes de incluir <stdio.h> .

Contenidos

Parámetros

stream - flujo de archivo de salida donde escribir
buffer - puntero a una cadena de caracteres donde escribir
bufsz - hasta bufsz - 1 caracteres pueden escribirse, más el terminador nulo
format - puntero a una cadena de caracteres terminada en nulo que especifica cómo interpretar los datos
vlist - lista de argumentos variables que contiene los datos a imprimir

La cadena de formato consiste en caracteres de byte ordinarios (excepto % ), que se copian sin cambios en el flujo de salida, y especificaciones de conversión. Cada especificación de conversión tiene el siguiente formato:

  • carácter introductorio % .
  • (opcional) uno o más indicadores que modifican el comportamiento de la conversión:
  • - : el resultado de la conversión se justifica a la izquierda dentro del campo (por defecto se justifica a la derecha).
  • + : el signo de las conversiones con signo siempre se antepone al resultado de la conversión (por defecto el resultado se precede con un signo menos solo cuando es negativo).
  • space : si el resultado de una conversión con signo no comienza con un carácter de signo, o está vacío, se antepone un espacio al resultado. Se ignora si el indicador + está presente.
  • # : se realiza la forma alternativa de la conversión. Consulte la tabla a continuación para conocer los efectos exactos; de lo contrario, el comportamiento es indefinido.
  • 0 : para conversiones de números enteros y de punto flotante, se utilizan ceros iniciales para rellenar el campo en lugar de caracteres de space . Para números enteros se ignora si la precisión se especifica explícitamente. Para otras conversiones, el uso de este indicador resulta en un comportamiento indefinido. Se ignora si el indicador - está presente.
  • (opcional) valor entero o * que especifica el ancho mínimo del campo. El resultado se rellena con caracteres de espacio (por defecto), si es necesario, a la izquierda cuando está justificado a la derecha, o a la derecha si está justificado a la izquierda. En el caso cuando se utiliza * , el ancho se especifica mediante un argumento adicional de tipo int , que aparece antes del argumento a convertir y del argumento que proporciona la precisión si se suministra uno. Si el valor del argumento es negativo, resulta con el indicador - especificado y ancho de campo positivo (Nota: Este es el ancho mínimo: El valor nunca se trunca.).
  • (opcional) . seguido por un número entero o * , o ninguno que especifique la precisión de la conversión. En el caso cuando se usa * , la precisión se especifica mediante un argumento adicional de tipo int , que aparece antes del argumento a convertir, pero después del argumento que suministra el ancho mínimo del campo si se suministra uno. Si el valor de este argumento es negativo, se ignora. Si no se usa ni un número ni * , la precisión se toma como cero. Consulte la tabla siguiente para conocer los efectos exactos de la precisión .
  • (opcional) modificador de longitud que especifica el tamaño del argumento (en combinación con el especificador de formato de conversión, especifica el tipo del argumento correspondiente).
  • especificador de formato de conversión.

Los siguientes especificadores de formato están disponibles:

Especificador
de Conversión 		Explicación Tipo de
Argumento Esperado
Modificador de Longitud→ hh h ninguno l ll j z t L
Solo disponible desde C99→ Sí Sí Sí Sí Sí
% Escribe literalmente % . La especificación de conversión completa debe ser %% . N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Escribe un carácter único .

  • El argumento se convierte primero a unsigned char .
  • Si se utiliza el modificador l , el argumento se convierte primero a una cadena de caracteres como si fuera mediante %ls con un argumento wchar_t [ 2 ] .
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Escribe una cadena de caracteres .

  • El argumento debe ser un puntero al elemento inicial de un arreglo de caracteres.
  • Precisión especifica el número máximo de bytes a escribir. Si Precisión no se especifica, escribe cada byte hasta el primer terminador nulo (sin incluirlo).
  • Si se utiliza el especificador l , el argumento debe ser un puntero al elemento inicial de un arreglo de wchar_t , que se convierte a un arreglo de caracteres como si fuera mediante una llamada a wcrtomb con estado de conversión inicializado a cero.
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

Convierte un entero con signo a representación decimal [-]dddd .

  • Precisión especifica el número mínimo de dígitos a mostrar. La precisión por defecto es 1 .
  • Si tanto el valor convertido como la precisión son ​ 0 ​ , la conversión no produce ningún carácter.
  • Para el modificador z , el tipo de argumento esperado es la versión con signo de size_t .
signed char
short
int
long
long long
※
N/A
o

Convierte un entero sin signo a representación octal oooo .

  • Precisión especifica el número mínimo de dígitos a mostrar. La precisión por defecto es 1 .
  • Si tanto el valor convertido como la precisión son ​ 0 ​ , la conversión no produce caracteres.
  • En la implementación alternativa la precisión se incrementa si es necesario para escribir un cero inicial. En ese caso, si tanto el valor convertido como la precisión son ​ 0 ​ , se escribe un único ​ 0 ​ .
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
versión sin signo de ptrdiff_t
N/A
x
X

Convierte un entero sin signo a representación hexadecimal hhhh .

  • Para la conversión x se utilizan las letras abcdef .
  • Para la conversión X se utilizan las letras ABCDEF .
  • Precisión especifica el número mínimo de dígitos a mostrar. La precisión por defecto es 1 .
  • Si tanto el valor convertido como la precisión son ​ 0 ​ la conversión no produce caracteres.
  • En la implementación alternativa se antepone 0x o 0X a los resultados si el valor convertido es distinto de cero.
N/A
u

Convierte un entero sin signo a representación decimal dddd .

  • Precisión especifica el número mínimo de dígitos a mostrar.
  • La precisión por defecto es 1 .
  • Si tanto el valor convertido como la precisión son ​ 0 ​ la conversión no produce ningún carácter.
N/A
f
F (C99)

Convierte un número de punto flotante a notación decimal en el estilo [-]ddd.ddd .

  • Precisión especifica el número exacto de dígitos que aparecen después del carácter de punto decimal.
  • La precisión por defecto es 6 .
  • En la implementación alternativa el carácter de punto decimal se escribe incluso si no le siguen dígitos.
  • Para el estilo de conversión de infinito y no-numérico consulte las notas .
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

Convierte números de punto flotante a la notación exponencial decimal.

  • Para el estilo de conversión e se utiliza [-]d.ddd  e ±dd .
  • Para el estilo de conversión E se utiliza [-]d.ddd  E ±dd .
  • El exponente contiene al menos dos dígitos, se utilizan más dígitos solo si es necesario.
  • Si el valor es ​ 0 ​ , el exponente también es ​ 0 ​ .
  • Precisión especifica el número exacto de dígitos que aparecen después del carácter de punto decimal.
  • La precisión por defecto es 6 .
  • En la implementación alternativa el carácter de punto decimal se escribe incluso si no le siguen dígitos.
  • Para la conversión de infinito y no-número consultar las notas .
N/A N/A N/A N/A N/A N/A
a
A

(C99)

Convierte números de punto flotante a la notación exponencial hexadecimal.

  • Para el estilo de conversión a se utiliza [-]  0x h.hhh  p ±d .
  • Para el estilo de conversión A se utiliza [-]  0X h.hhh  P ±d .
  • El primer dígito hexadecimal no es 0 si el argumento es un valor de punto flotante normalizado.
  • Si el valor es ​ 0 ​ , el exponente también es ​ 0 ​ .
  • Precisión especifica el número exacto de dígitos que aparecen después del carácter de punto hexadecimal.
  • La precisión predeterminada es suficiente para la representación exacta del valor.
  • En la implementación alternativa el carácter de punto decimal se escribe incluso si no le siguen dígitos.
  • Para el estilo de conversión de infinito y no-número, consulte las notas .
N/A N/A N/A N/A N/A N/A
g
G

Convierte un número de punto flotante a notación decimal o notación exponencial decimal dependiendo del valor y la precisión .

  • Para el estilo de conversión g se realizará la conversión con estilo e o f .
  • Para el estilo de conversión G se realizará la conversión con estilo E o f (hasta C99) F (desde C99) .
  • Sea P igual a la precisión si es distinta de cero, 6 si la precisión no está especificada, o 1 si la precisión es ​ 0 ​ . Entonces, si una conversión con estilo E tendría un exponente de X :
    • Si P > X ≥ −4 , la conversión es con estilo f o F (desde C99) y precisión P − 1 − X .
    • En caso contrario, la conversión es con estilo e o E y precisión P − 1 .
  • A menos que se solicite la representación alternativa , se eliminan los ceros finales y también se elimina el carácter de punto decimal si no queda parte fraccionaria.
  • Para la conversión de infinito y no-número, consulte las notas .
N/A N/A N/A N/A N/A N/A
n

Devuelve el número de caracteres escritos hasta ahora por esta llamada a la función.

  • El resultado se escribe en el valor apuntado por el argumento.
  • La especificación no puede contener ningún indicador , ancho de campo , o precisión .
  • Para el modificador z , el tipo de argumento esperado es S * , donde S es la versión con signo de size_t .
signed char *
short *
int *
long *
long long *
※
N/A
p

Escribe una secuencia de caracteres definida por la implementación que define un pointer .

N/A N/A
void *
N/A N/A N/A N/A N/A N/A
Notas

Las funciones de conversión de punto flotante convierten infinito a inf o infinity . Cuál se utiliza está definido por la implementación.

No-es-un-número se convierte a nan o nan( char_sequence ) . Cuál se utiliza está definido por la implementación.

Las conversiones F , E , G , A generan INF , INFINITY , NAN en su lugar.

El especificador de conversión utilizado para imprimir char , unsigned char , signed char , short , y unsigned short espera tipos promocionados de promociones de argumentos por defecto , pero antes de imprimir su valor será convertido a char , unsigned char , signed char , short , y unsigned short . Es seguro pasar valores de estos tipos debido a la promoción que tiene lugar cuando se llama a una función variádica.

Las especificaciones de conversión correctas para los tipos de caracteres de ancho fijo ( int8_t , etc) están definidas en el encabezado <inttypes.h> (aunque PRIdMAX , PRIuMAX , etc son sinónimos de %jd , %ju , etc).

El especificador de conversión de escritura en memoria %n es un objetivo común de exploits de seguridad donde las cadenas de formato dependen de entrada del usuario y no es compatible con la familia de funciones con verificación de límites printf_s (desde C11) .

Hay un punto de secuencia después de la acción de cada especificador de conversión; esto permite almacenar múltiples resultados %n en la misma variable o, como caso extremo, imprimir una cadena modificada por un %n anterior dentro de la misma llamada.

Si una especificación de conversión es inválida, el comportamiento es indefinido.

Valor de retorno

1-3) El número de caracteres escritos si es exitoso o valor negativo si ocurrió un error.
4) El número de caracteres escritos si es exitoso o un valor negativo si ocurrió un error. Si la cadena resultante se trunca debido al límite de buf_size , la función devuelve el número total de caracteres (sin incluir el byte nulo terminador) que se habrían escrito, si no se hubiera impuesto el límite.
5,6) número de caracteres transmitidos al flujo de salida o valor negativo si ocurrió un error de salida, un error de violación de restricciones en tiempo de ejecución, o un error de codificación.
7) número de caracteres escritos en buffer , sin contar el carácter nulo (el cual siempre se escribe siempre que buffer no sea un puntero nulo y bufsz no sea cero ni mayor que RSIZE_MAX ), o cero en caso de violaciones de restricciones en tiempo de ejecución, y valor negativo en errores de codificación
8) número de caracteres sin incluir el carácter nulo terminador (el cual siempre se escribe siempre que buffer no sea un puntero nulo y bufsz no sea cero y no sea mayor que RSIZE_MAX ), que habría sido escrito en buffer si bufsz fuera ignorado, o un valor negativo si ocurrió una violación de restricciones en tiempo de ejecución o un error de codificación

Notas

Todas estas funciones invocan va_arg al menos una vez, el valor de arg es indeterminado después del retorno. Estas funciones no invocan va_end , y debe ser realizado por el llamador.

vsnprintf_s , a diferencia de vsprintf_s , truncará el resultado para ajustarse dentro del array apuntado por buffer .

La implementación de vsnprintf_s en el Microsoft CRT no cumple con el estándar C. La versión de Microsoft tiene un parámetro adicional size_t count en tercera posición que contiene la cantidad máxima de caracteres a escribir, sin incluir el terminador nulo. Este parámetro posiblemente difiera del tamaño del búfer proporcionado mediante el parámetro size_t bufsz .

Ejemplo

Ejecutar este código 
#include <stdarg.h>
#include <stdio.h>
#include <time.h>
void debug_log(const char* fmt, ...)
{
    struct timespec ts;
    timespec_get(&ts, TIME_UTC);
    char time_buf[100];
    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
    va_list args1;
    va_start(args1, fmt);
    va_list args2;
    va_copy(args2, args1);
    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
    va_end(args1);
    vsnprintf(buf, sizeof buf, fmt, args2);
    va_end(args2);
    printf("%s [debug]: %s\n", time_buf, buf);
{
int main(void)
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

Salida posible: 

02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

Referencias

  • Estándar C23 (ISO/IEC 9899:2024):
  • 7.21.6.8 La función vfprintf (p: TBD)
  • 7.21.6.10 La función vprintf (p: TBD)
  • 7.21.6.12 La función vsnprintf (p: TBD)
  • 7.21.6.13 La función vsprintf (p: TBD)
  • K.3.5.3.8 La función vfprintf_s (p: TBD)
  • K.3.5.3.10 La función vprintf_s (p: TBD)
  • K.3.5.3.12 La función vsnprintf_s (p: TBD)
  • K.3.5.3.13 La función vsprintf_s (p: TBD)
  • Estándar C17 (ISO/IEC 9899:2018):
  • 7.21.6.8 La función vfprintf (p: 238)
  • 7.21.6.10 La función vprintf (p: 239)
  • 7.21.6.12 La función vsnprintf (p: 239-240)
  • 7.21.6.13 La función vsprintf (p: 240)
  • K.3.5.3.8 La función vfprintf_s (p: 434)
  • K.3.5.3.10 La función vprintf_s (p: 435)
  • K.3.5.3.12 La función vsnprintf_s (p: 436-437)
  • K.3.5.3.13 La función vsprintf_s (p: 437)
  • Estándar C11 (ISO/IEC 9899:2011):
  • 7.21.6.8 La función vfprintf (p: 326-327)
  • 7.21.6.10 La función vprintf (p: 328)
  • 7.21.6.12 La función vsnprintf (p: 329)
  • 7.21.6.13 La función vsprintf (p: 329)
  • K.3.5.3.8 La función vfprintf_s (p: 597)
  • K.3.5.3.10 La función vprintf_s (p: 598-599)
  • K.3.5.3.12 La función vsnprintf_s (p: 600)
  • K.3.5.3.13 La función vsprintf_s (p: 601)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 7.19.6.8 La función vfprintf (p: 292)
  • 7.19.6.10 La función vprintf (p: 293)
  • 7.19.6.12 La función vsnprintf (p: 294)
  • 7.19.6.13 La función vsprintf (p: 295)
  • Estándar C89/C90 (ISO/IEC 9899:1990):
  • 4.9.6.7 La función vfprintf
  • 4.9.6.8 La función vprintf
  • 4.9.6.9 La función vsprintf

Véase también

(C95) (C95) (C95) (C11) (C11) (C11) (C11)
imprime salida formateada de caracteres anchos hacia stdout , un flujo de archivo
o un búfer usando una lista de argumentos variable
(función)
(C99) (C11) (C11) (C11) (C11)
imprime salida formateada hacia stdout , un flujo de archivo o un búfer
(función)
(C99) (C99) (C99) (C11) (C11) (C11)
lee entrada formateada desde stdin , un flujo de archivo o un búfer
usando una lista de argumentos variable
(función)
Documentación de C++ para vprintf , vfprintf , vsprintf , vsnprintf