Provided by: manpages-es_1.55-10_all 
NOMBRE
printf, fprintf, sprintf, vprintf, vfprintf, vsprintf - conversión de salida formateada
SINOPSIS
#include <stdio.h>
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);
#include <stdarg.h>
int vprintf(const char *format, va_list ap);
int vfprintf(FILE *stream, const char *format, va_list ap);
int vsprintf(char *str, const char *format, va_list ap);
int vsnprintf(char *str, size_t size, const char *format, va_list ap);
DESCRIPCIÓN
Las funciones de la familia printf producen una salida de acuerdo a format como se describe abajo.
Printf y vprintf escriben su salida a stdout, el flujo de salida estándar. fprintf y vfprintf escriben
su salida al stream de salida dado. sprintf, snprintf, vsprintf y vsnprintf escriben a una cadena de
caracteres str.
Las funciones vprintf, vfprintf, vsprintf y vsnprintf son equivalentes a las funciones printf, fprintf,
sprintf y snprintf, respectivamente, salvo en que se las llama con un va_list en lugar de con un número
variable de argumentos. Estas funciones no llaman a la macro va_end. En consecuencia, el valor de ap
queda indefinido después de la llamada. La propia aplicación debería llamar a va_end(ap) después.
Estas ocho funciones escriben la salida bajo el control de una cadena format que especifica cómo los
argumentos posteriores (o los argumentos accedidos mediante las facilidades de argumentos de longitud
variables proporionadss por stdarg(3)) son convertidos para su salida.
Valor devuelto
En caso de éxito, estas funciones devuelven el número de caracteres impresos (no incluyendo el carácter
`\0' usado para terminar la salida de cadenas). Las funciones snprintf y vsnprintf no escriben más de
size bytes (incluyendo el carácter terminador '\0'). Si la salida fue truncada debido a este límite el
valor devuelto es el número de caracteres (no incluyendo el carácter final '\0') que se habrían escrito
en la cadena final si hubiera habido suficiente espacio. De esta manera, un valor de retorno de size o
más significa que la salida fue truncada. (Vea también debajo de OBSERVACIONES.) Si se encuentra un
error de salida, se devuelve un valor negativo.
Formato de la cadena de formato
La cadena de formato es una cadena de caracteres que comienza y termina en su estado de cambios inicial,
si lo hay. La cadena format está compuesta de cero o más directivas: caracteres ordinarios (no %) que se
copian sin cambios al flujo de salida, e indicaciones de conversión, cada uno de las cuales produce la
búsqueda de cero o más argumentos posteriores. Cada especificación de conversión se introduce mediante el
carácter % y termina con un indicador de conversión. En medio puede haber (en este orden) cero o más
opciones, una anchura de campo opcional mínima, una precisión opcional y un modificador de longitud
opcional.
Los argumentos se deben corresponder adecuadamente (después de la promoción de tipos) con el indiciador
de conversión. Por defecto, los argumentos se usan en el orden dado, donde cada `*' y cada indicador de
conversión pregunta por el siguiente argumento (y es un error si se dan de forma insuficiente muchos
argumentos). También se puede especificar explícitamente qué argumento se toma, en cada lugar donde se
necesite un argumento, escribiendo `%m$' en lugar de `%' y `*m$' en lugar de `*', donde el entero decimal
m denota la posición en la lista de argumentos del argumento deseado, empezando por 1. Por tanto,
printf("%*d", width, num);
y
printf("%2$*1$d", width, num);
son equivalentes. El segundo estilo permite referencias repetidas al mismo argumento. El estándar C99 no
incluye el estilo usando caracteres `$', que proviene de `the Single Unix Specification'. Si se utiliza
el estilo con `$', debe ser usado para todas las conversiones tomando un argumento y todos los argumentos
de anchura y precisión, pero puede mezclarse con formatos `%%' que no consumen ningún argumento. No puede
haber huecos en los números de los argumentos especificados usando `$'; por ejemplo, si se especifican
los argumentos 1 y 3, el argumento 2 debe ser también especificado en algún lugar en la cadena de
formato.
Para alguna conversión numérica se usa un carácter radical (`punto decimal') o carácter separador de
miles. El carácter real usado depende de la parte LC_NUMERIC de la localización. La localizacíon POSIX
usa `.' como carácter radical y no posee un carácter separador de miles. Por tanto,
printf("%'.2f", 1234567.89);
produce `1234567.89' en la localización POSIX, `1234567,89' en la localización nl_NL, y `1.234.567,89' en
la localización da_DK.
Los caracteres de opción
El carácter % va seguido por cero o más de las siguientes opciones:
# El valor debe ser convertido a un ``formato alternativo''. Para las conversiones o, el primer
carácter de la cadena de salida se hace 0 (prefijando un cero si ya era distinto de cero). Para
las conversiones x y X, la cadena `0x' (o `0X' para conversiones X ) precede a los resultados que
son distintos de 0. Para las conversiones a, A, e, E, f, F, g, y G, el resultado contendrá un
punto decimal, aún si ningún dígito lo sigue (normalmente, sólo aparece un punto decimal en el
resultado de aquellas conversiones que son seguidas de algún dígito). Para las conversiones g y G,
en el resultado no se eliminan los ceros del final, como ocurriría en otro caso. Para otras
conversiones, el resultado es indefinido.
0 El valor se debe rellenar con ceros. Para las conversiones d, i, o, u, x, X, a, A, e, E, f, F, g,
y G , el valor convertido es rellenado a la izquierda con ceros en vez de blancos. Si las
banderas 0 y - aparecen a la vez, la bandera 0 es ignorada. Si en una conversión numérica (d, i,
o, u, x, y X), se indica una precisión, la bandera 0 se ignora. Para otras conversiones, el
resultado es indefinido.
- El valor convertido es justificado a la izquierda sobre el límite del campo. (Por defecto, la
justificación es a la derecha). Excepto para conversiones n, el valor convertido es rellenado a la
derecha con blancos, en vez de a la izquierda con blancos o ceros. Un - sobreescribe un 0 si se
indican ambos.
(un espacio) Se debe dejar un espacio en blanco delante de un número positivo (o cadena vacía)
producido por una conversión con signo.
+ Siempre se colocará el signo (+ o -) delante de un número producido por una conversión con signo.
Por omisión, sólo se usa el signo para los números negativos. Un + sobreescribe un espacio si se
usan ambos.
Los cinco carácteres de opción anteriores se definen en el estándar C. SUSv2 especifica un carácter de
opción adicional.
' Para una conversión decimal (i, d, u, f, F, g, G) la salida se va a agrupar con caracteres de
separación de miles si la información de localización así lo indica. Dese cuenta que muchas
versiones de gcc no pueden analizar esta opción y producirán una advertencia. SUSv2 no incluye
%'F.
glibc 2.2 añada un nuevo carácter de opción adicional.
I Para una conversión decimal entera (i, d, u) la salida utiliza los dígitos de salida alternativos
de la localización, si hay (por ejemplo, dígitos árabes). Sin embargo, no incluye ninguna
definición de localización con tales dígitos de salida outdigits definidos.
La anchura de campo
Una cadena de dígitos decimales opcional (con un primer dígito distinto de cero) que especifica una
anchura de campo mínimo. Si el valor convertido tiene menos caracteres que la anchura del campo, se
rellenará con espacios a la izquierda (o a la derecha, si se da la opción de justificación a la
izquierda). En lugar de una cadena de dígitos decimales se puede escribir `*' o `*m$' (para algún entero
decimal m) para especificar que la anchura del campo se proporciona en el siguiente argumento o en el
m-ésimo argumento, respectivamente, que debe ser de tipo int. Una anchura de campo negativa se toma como
una opción `-' seguida por una anchura de campo positiva. En ningún caso, una anchura de campo
inexistente o pequeña hace que el campo se trunque. Si el resultado de la conversión es más ancho que la
anchura del campo, el campo se expande para contener el resultado de la conversión.
La precisión
Una precisión opcional, indicada por un punto (`.') seguido por una cadena de dígitos también opcional.
En lugar de una cadena de dígitos decimales se puede escribir `*' o `*m$' (para algún entero decimal m)
para especificar que la precisión se da en el siguiente argumento o en el m-ésimo argumento,
respectivamente, que debe ser de tipo int. Si la precisión se da como un simple `.', o si la precisión
es negativa, la precisión se toma como cero. Esto da el número mínimo de dígitos que deben aparecer en
las conversiones d, i, o, u, x, y X, el número de dígitos que deben aparacer tras el carácter radical en
las conversiones a, A, e, E, f y F, el máximo número de dígitos significativos para las conversiones g y
G, o el máximo número de caracteres a imprimir de una cadena en las conversiones s y S.
El indicador de longitud
Aquí, `conversión entera' significa una conversión d, i, o, u, x, o X.
hh La siguiente conversión entera se corresponde con un argumento signed char o unsigned char, o la
siguiente conversión n se corresponde a un puntero a un argumento signed char .
h La siguiente conversión entera se corresponde con un argumento short int o unsigned short int, o
que la siguiente conversión n corresponde a un puntero a un argumento short int.
l (ele) La siguiente conversión entera corresponde a un argumento long int o unsigned long int, o
que la siguiente conversión n corresponde a un puntero a un argumento long int o que la siguiente
conversión c corresponde a un argumento wint_t, o que la siguiente conversión s corresponde a un
puntero a un argumento wchar_t.
ll (ele-ele). La siguiente conversión entera corresponde a un argumento long long int o unsigned
long long int , o que la siguiente conversión n corresponde a un puntero a un argumento long long
int.
L La siguiente conversión a, A, e, E, f, F, g, o G corresponde a un argumento long double. (C99
permite %LF, pero SUSv2 no.)
q (`cuadruple'. BSD 4.4 y Linux libc5 sólo. No usar.) Esto es un sinónimo de ll.
j La siguiente conversión entera corresponde a un intmax_t o uintmax_t.
z La siguiente conversión entera corresponde a un argumento size_t o ssize_t. (Linux libc5 tiene Z
con este significado. No lo use.)
t La siguiente conversión entera corresponde a un argumento ptrdiff_t.
SUSv2 sólo conoce los indicadores de longitud h (en hd, hi, ho, hx, hX, hn), l (en ld, li, lo, lx, lX,
ln, lc, ls) y L (en Le, LE, Lf, Lg, LG).
El indicador de conversión
Un carácter que especifica el tipo de conversión a ser aplicado. Los indicadores de conversión y sus
significados son:
d,i El argumento int se convierte a la notación decimal con signo. La precisión, si la hay, da el
número mínimo de dígitos que deben aparecer. Si el valor convertido necesita menos dígitos, se
rellena a la izquierda con ceros. La precisión por omisión es 1. Cuando se imprime 0 con una
precisión explícita 0, la salida es la cadena vacía.
o,u,x,X
El argumento unsigned int se convierte a un octal sin signo (o, a decimal sin signo (u, a a
notación hexadecimal sin signo (x y X). Las letras abcdef son usadas para conversiones x. Las
letras ABCDEF son usadas para conversiones X. La precisión, si se ha indicado alguna, da el
mínimo número de dígitos que deben aparecer. Si el valor convertido requiere menos dígitos, éste
es rellenado a la izquierda con ceros. La precisión por omisión es 1. Cuando se imprime 0 con una
precisión explícita 0, la salida es la cadena vacía.
e,E El argumento double es redondeado y convertido al formato [-]d.ddde±dd donde hay un dígito delante
del carácter del punto decimal y el número de dígitos después de éste es igual a la precisión. Si
no se indica precisión, ésta es tomada como 6. Si la precisión es cero, no aparece el carácter de
punto decimal. Una conversión E usa la letra E ( en vez de e) para introducir el exponente. El
exponente siempre contiene al menos dos dígitos. Si el valor es cero, el exponente es 00.
f,F El argumento double es redondeado y convertido a una notación decimal del estilo [-]ddd.ddd, donde
el número de dígitos después del carácter del punto decimal es igual a la especificación de la
precisión. Si no se indica precisión, ésta es tomada como 6. Si la precisión es explícitamente
cero, no aparece el carácter del punto decimal. Si aparece un punto decimal, al menos aparece un
dígito delante de él.
(SUSv2 no conoce F y dice que deben estar disponibles reprentaciones como cadenas de caracteres
para infinito y NaN (Not a Number, no es un número). El estándar C00 especifica `[-]inf' o
`[-]infinity' para el infinito y una cadena que comienza por `Nan' para NaN, en el caso de una
conversión f, y `[-]INF' o `[-]INFINITY' o `NAN*' en el caso de una conversión F.)
g,G El argumento double es convertido al estilo de f o e (o F o E para conversiones G ). La precisión
especifica el número de dígitos significativos. Si no se indica precisión, se dan 6 dígitos. Si
la precisión es cero, ésta es tratada como 1. Se utiliza el formato de e si el exponente de su
conversión es menor que -4 o más grande o igual a la precisión. Los ceros finales se eliminan de
la parte fraccional del resultado. Un punto decimal sólo aparece si es seguido de al menos un
dígito.
a,A (C99. No en SUSv2) Para una conversión a, el argumento double se convierte a notación hexadecimal
(usando las letras abcdef) según el estilo [-]0xh.hhhhp±d. Para una conversión A se usan el
prefijo 0X, las letras ABCDEF y el separador de exponente P. Hay un dígito hexadecimal antes del
punto decimal y el número de dígitos tras él es igual a la precisión. La precisión por omisión es
suficiente para una representación exacta del valor si existe una representación exacta en base 2
y, en otro caso, es suficientemente grande para distinguir valores de tipo double. El dígito
antes del punto decimal queda sin especificar para números no normalizados y distinto de cero
pero, en cualquier caso, sin especificar para números normalizados.
c Si no está presente un modificador l, el argumento int es convertido a un unsigned char, y se
escribe el carácter resultante. Si está presente un modificador l, el argumento wint_t (carácter
ancho) se convierte a una secuencia multibyte llamando a la función wcrtomb, con un estado de
conversión que comienza en el estado inicial, y se escribe la cadena multibyte resultante.
s Si no está presente un modificador l: se espera que el argumento const char * sea un puntero a un
vector (array) de tipo carácter (puntero a una cadena de caracteres). Se escriben caracteres del
array hasta (pero no incluyendo) un carácter terminador NUL. Si se especifica una precisión, no
se escriben más caracteres del número especificado. Si se da una precisión, no es necesario que
aparezca ningún carácter nulo. Si no se especifica precisión, o es mayor que el tamaño de la
cadena, la cadena debe contener un carácter de terminación NUL. Si está presente un modificador
l: se espera que el argumento const wchar_t * sea un puntero a un vector de caracteres anchos. Los
caracteres anchos del array se convierten a caracteres multibyte (cada uno llamando a la función
wcrtomb, con un estado de conversión que comienza en el estado inicial antes del primer carácter
ancho) incluyendo el carácter ancho nulo terminador. Los caracteres multibyte resultantes se
escriben hasta llegar (pero sin incluir) el byte nulo terminador. Si se especifica una precisión,
no se escriben más bytes de los indica el número, aunque no se escribe ningún carácter multibyte
parcial. Advierta que la precisión determina el número de bytes escritos, no el número de
caracteres anchos o posiciones de pantalla. El vector debe contener un carácter ancho nulo
terminador, a menos que se de una precisión que sea tan pequeña que el número de bytes escritos la
exceda antes de llegar al final del vector.
C (No en C99, pero sí en SUSv2.) Sinónimo de lc. No usar.
S (No en C99, pero sí en SUSv2.) Sinónimo de ls. No usar.
p El argumento de tipo puntero void * se imprime en hexadecimal (como si se hubiera indicado %#x o
%#lx).
n El número de caracteres escritos hasta ahora se guarda en el entero indicado por el argumento de
tipo puntero int * (o una variante suya). No se convierte ningún argumento.
% Se escribe un `%'. No se convierte ningún argumento. La especificación completa de conversión es
`%%'.
EJEMPLOS
Para imprimir pi con cinco cifras decimales:
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
Para imprimir una fecha y una hora de la forma `Sunday, July 3, 10:02', donde weekday y month son
punteros a cadenas:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
Muchos países usan el orden día-mes-año. Por tanto, una versión internacionalizada debe ser capaz de
mostrar los argumentos en el orden indicado por el formato:
#include <stdio.h>
fprintf(stdout, formato,
diasemana, mes, día, hora, min);
donde formato depende de la localización y puede permutar los argumentos. Con el valor
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
se podría obtener `sonntag, 3. Juli, 10:02'.
Para reservar una cadena de 128 bytes e imprimir dentro de ella: Para reservar una cadena suficientemente
grande e imprimir dentro de ella: (código correcto tanto para glibc 2.0 como glibc 2.1):
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *
construye_mensaje(const char *fmt, ...) {
/* Suponemos que no necesitamos más de 100 bytes. */
int n, size = 100;
char *p;
va_list ap;
if ((p = malloc (size)) == NULL)
return NULL;
while (1) {
/* Intenta imprimir en el espacio reservado. */
va_start(ap, fmt);
n = vsnprintf (p, size, fmt, ap);
va_end(ap);
/* Si ha funcionado, devuelve la cadena. */
if (n > -1 && n < size)
return p;
/* Si no, inténtalo de nuevo con más espacio. */
if (n > -1) /* glibc 2.1 */
size = n+1; /* exactamente lo que se necesita */
else /* glibc 2.0 */
size *= 2; /* el doble del tamaño anterior*/
if ((p = realloc (p, size)) == NULL)
return NULL;
}
}
OBSERVACIONES
La implementación de glibc de las funciones snprintf y vsnprintf es conforme con el estándar C99, es
decir, se comporta como se describe arriba, desde la versión 2.1 de glibc. Hasta la versión 2.0.6 de
glibc devolvían -1 cuando la salida era truncada.
CONFORME A
Las funciones fprintf, printf, sprintf, vprintf, vfprintf, y vsprintf están conforme a ANSI X3.159-1989
(``ANSI C'') e ISO/IEC 9899:1999 (``ISO C99''). Las funciones snprintf y vsnprintf están conforme a
ISO/IEC 9899:1999.
Teniendo en cuenta el valor devuelto pr snprintf, SUSv2 y el estándar C99 se contradicen: cuando snprintf
se llama con size=0, SUSv2 estipula un valor devuelto sin especificar menor que 1, mientras que C99
permite que str sea NULL en este caso y da el valor devuelto (como siempre) como el número de caracteres
que habrían sido escritos en el caso de que la cadena de salida hubiera sido lo suficientemente grande.
La libc4 de Linux reconoce las cinco opciones estándares de C. Reconoce los modificadores de longitud h,
l y L, y las conversiones cdeEfFgGinopsuxX, donde F es un sinónimo de f. Adicionalmente, acepta D, O y
U, como sinónimos de ld, lo y lu. (Esto es malo y provocó serios fallos más tarde, cuando desapareció el
soporte para %D). No reconoce un carácter radical dependiente de la localización, ni un separador de
miles, ni NaN ni infinito, ni %m$ ni *m$.
La biblioteca libc5 de Linux reconoce las cinco opciones estándares de C y la opción ', locale, %m$ y
*m$. Reconoce los modificadores de longitud h, l, L, Z y q, pero acepta L y q, ambos para valores long
double y long long integer (esto es un fallo). Ya no reconoce más FDOU, pero añade un nuevo carácter de
conversión m, que produce strerror(errno).
glibc 2.0 añade los caracteres de conversión C y S.
glibc 2.1 añade los modificadores de longitud hh, j, t y z, y los caracteres de conversión a y A.
glibc 2.2 añade el carácter de conversión F con la semántica de C99, y el carácter de opción I.
HISTORIA
Unix V7 define las tres rutinas printf, fprintf, sprintf, y posee la opción -, la anchura o precisión *,
el modificador de longitud l, las conversiones doxfegcsu, y también D, O, U y X como sinónimos de ld, lo,
lu y lx. Esto todavía es cierto para BSD 2.9.1, pero BSD 2.10 tiene las opciones #, + y <space> y ya no
menciona D, O, U y X. BSD 2.11 tiene vprintf, vfprintf, vsprintf, y advierte de no usar D, O, U y X.
BSD 4.3 Reno tiene la opción 0, los modificadores de longitud h y L, las conversiones n, p, E, G, X (con
el significado actual) y hace obsoletas D, O y U. BSD 4.4 introduce las funciones snprintf y vsnprintf,
y el modificador de longitud q. FreeBSD también posee las funciones asprintf y vasprintf, que reservan
un buffer los suficientemente largo para sprintf. En glibc están las funciones dprintf y vdprintf que
imprimen en un descriptor de fichero en lugar de un flujo.
FALLOS
Ya que sprintf y vsprintf asumen una cadena de longitud arbitraria, los invocadores deben tener cuidado
de no sobrepasar el espacio real, lo que a menudo resulta imposible de garantizar. Advierta que las
longitudes de las cadenas producidas dependen de la localización y que son difíciles de predecir. Use
snprintf y vsnprintf en su lugar (o asprintf y vasprintf).
La biblioteca libc4.[45] de Linux no posee la función snprintf, pero proporciona una libbsd que contiene
una función snprintf equivalente a sprintf, es decir, una que ignora el argumento size. Por tanto, el
uso de snprintf con las primeras libc4 conduce a serios problemas de seguridad.
Fragmentos de código como printf(foo); indican a menudo un fallo, puesto que foo puede contener un
carácter %. Si foo proviene de la entrada del usuario, puede contener %n, provocando que la llamada
printf escriba en memoria y creando un agujero de seguridad.
VÉASE TAMBIÉN
printf(1), asprintf(3), dprintf(3), wcrtomb(3), wprintf(3), scanf(3), locale(5)