Provided by:
manpages-es_1.55-10_all 
NOMBRE
printf, fprintf, sprintf, vprintf, vfprintf, vsprintf - conversion 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'ON
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 estandar. 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 numero
variable de argumentos. Estas funciones no llaman a la macro va_end.
En consecuencia, el valor de ap queda indefinido despues de la llamada.
La propia aplicacion deberia llamar a va_end(ap) despues.
Estas ocho funciones escriben la salida bajo el control de una cadena
format que especifica como 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 exito, estas funciones devuelven el numero de caracteres
impresos (no incluyendo el caracter `\0' usado para terminar la salida
de cadenas). Las funciones snprintf y vsnprintf no escriben mas de
size bytes (incluyendo el caracter terminador '\0'). Si la salida fue
truncada debido a este limite el valor devuelto es el numero de
caracteres (no incluyendo el caracter final '\0') que se habrian
escrito en la cadena final si hubiera habido suficiente espacio. De
esta manera, un valor de retorno de size o mas significa que la salida
fue truncada. (Vea tambien 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 esta
compuesta de cero o mas directivas: caracteres ordinarios (no %) que se
copian sin cambios al flujo de salida, e indicaciones de conversion,
cada uno de las cuales produce la busqueda de cero o mas argumentos
posteriores. Cada especificacion de conversion se introduce mediante el
caracter % y termina con un indicador de conversi'on. En medio puede
haber (en este orden) cero o mas opciones, una anchura de campo
opcional minima, una precisi'on opcional y un modificador de longitud
opcional.
Los argumentos se deben corresponder adecuadamente (despues de la
promocion de tipos) con el indiciador de conversion. Por defecto, los
argumentos se usan en el orden dado, donde cada `*' y cada indicador de
conversion pregunta por el siguiente argumento (y es un error si se dan
de forma insuficiente muchos argumentos). Tambien se puede especificar
explicitamente que 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 posicion 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 estandar 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 precision, pero puede
mezclarse con formatos `%%' que no consumen ningun argumento. No puede
haber huecos en los numeros de los argumentos especificados usando `$';
por ejemplo, si se especifican los argumentos 1 y 3, el argumento 2
debe ser tambien especificado en algun lugar en la cadena de formato.
Para alguna conversion numerica se usa un caracter radical (`punto
decimal') o caracter separador de miles. El caracter real usado depende
de la parte LC_NUMERIC de la localizacion. La localizacion POSIX usa
`.' como caracter radical y no posee un caracter separador de miles.
Por tanto,
printf("%'.2f", 1234567.89);
produce `1234567.89' en la localizacion POSIX, `1234567,89' en la
localizacion nl_NL, y `1.234.567,89' en la localizacion da_DK.
Los caracteres de opci'on
El caracter % va seguido por cero o mas de las siguientes opciones:
# El valor debe ser convertido a un ``formato alternativo''. Para
las conversiones o, el primer caracter 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 contendra un
punto decimal, aun si ningun digito lo sigue (normalmente, solo
aparece un punto decimal en el resultado de aquellas
conversiones que son seguidas de algun digito). Para las
conversiones g y G, en el resultado no se eliminan los ceros del
final, como ocurriria 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 conversion numerica (d, i, o, u, x, y X), se indica una
precision, la bandera 0 se ignora. Para otras conversiones, el
resultado es indefinido.
- El valor convertido es justificado a la izquierda sobre el
limite del campo. (Por defecto, la justificacion 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
numero positivo (o cadena vacia) producido por una conversion
con signo.
+ Siempre se colocara el signo (+ o -) delante de un numero
producido por una conversion con signo. Por omision, solo se
usa el signo para los numeros negativos. Un + sobreescribe un
espacio si se usan ambos.
Los cinco caracteres de opcion anteriores se definen en el estandar C.
SUSv2 especifica un caracter de opcion adicional.
' Para una conversion decimal (i, d, u, f, F, g, G) la salida se
va a agrupar con caracteres de separacion de miles si la
informacion de localizacion asi lo indica. Dese cuenta que
muchas versiones de gcc no pueden analizar esta opcion y
produciran una advertencia. SUSv2 no incluye %'F.
glibc 2.2 anada un nuevo caracter de opcion adicional.
I Para una conversion decimal entera (i, d, u) la salida utiliza
los digitos de salida alternativos de la localizacion, si hay
(por ejemplo, digitos arabes). Sin embargo, no incluye ninguna
definicion de localizacion con tales digitos de salida outdigits
definidos.
La anchura de campo
Una cadena de digitos decimales opcional (con un primer digito distinto
de cero) que especifica una anchura de campo minimo. Si el valor
convertido tiene menos caracteres que la anchura del campo, se
rellenara con espacios a la izquierda (o a la derecha, si se da la
opcion de justificacion a la izquierda). En lugar de una cadena de
digitos decimales se puede escribir `*' o `*m$' (para algun entero
decimal m) para especificar que la anchura del campo se proporciona en
el siguiente argumento o en el m-esimo argumento, respectivamente, que
debe ser de tipo int. Una anchura de campo negativa se toma como una
opcion `-' seguida por una anchura de campo positiva. En ningun caso,
una anchura de campo inexistente o pequena hace que el campo se
trunque. Si el resultado de la conversion es mas ancho que la anchura
del campo, el campo se expande para contener el resultado de la
conversion.
La precisi'on
Una precision opcional, indicada por un punto (`.') seguido por una
cadena de digitos tambien opcional. En lugar de una cadena de digitos
decimales se puede escribir `*' o `*m$' (para algun entero decimal m)
para especificar que la precision se da en el siguiente argumento o en
el m-esimo argumento, respectivamente, que debe ser de tipo int. Si la
precision se da como un simple `.', o si la precision es negativa, la
precision se toma como cero. Esto da el numero minimo de digitos que
deben aparecer en las conversiones d, i, o, u, x, y X, el numero de
digitos que deben aparacer tras el caracter radical en las conversiones
a, A, e, E, f y F, el maximo numero de digitos significativos para las
conversiones g y G, o el maximo numero de caracteres a imprimir de una
cadena en las conversiones s y S.
El indicador de longitud
Aqui, `conversion entera' significa una conversion d, i, o, u, x, o X.
hh La siguiente conversion entera se corresponde con un argumento
signed char o unsigned char, o la siguiente conversion n se
corresponde a un puntero a un argumento signed char .
h La siguiente conversion entera se corresponde con un argumento
short int o unsigned short int, o que la siguiente conversion n
corresponde a un puntero a un argumento short int.
l (ele) La siguiente conversion entera corresponde a un argumento
long int o unsigned long int, o que la siguiente conversion n
corresponde a un puntero a un argumento long int o que la
siguiente conversion c corresponde a un argumento wint_t, o que
la siguiente conversion s corresponde a un puntero a un
argumento wchar_t.
ll (ele-ele). La siguiente conversion entera corresponde a un
argumento long long int o unsigned long long int , o que la
siguiente conversion n corresponde a un puntero a un argumento
long long int.
L La siguiente conversion 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 solo. No usar.) Esto es un
sinonimo de ll.
j La siguiente conversion entera corresponde a un intmax_t o
uintmax_t.
z La siguiente conversion entera corresponde a un argumento size_t
o ssize_t. (Linux libc5 tiene Z con este significado. No lo
use.)
t La siguiente conversion entera corresponde a un argumento
ptrdiff_t.
SUSv2 solo 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'on
Un caracter que especifica el tipo de conversion a ser aplicado. Los
indicadores de conversion y sus significados son:
d,i El argumento int se convierte a la notacion decimal con signo.
La precision, si la hay, da el numero minimo de digitos que
deben aparecer. Si el valor convertido necesita menos digitos,
se rellena a la izquierda con ceros. La precision por omision es
1. Cuando se imprime 0 con una precision explicita 0, la salida
es la cadena vacia.
o,u,x,X
El argumento unsigned int se convierte a un octal sin signo (o,
a decimal sin signo (u, a a notacion hexadecimal sin signo (x y
X). Las letras abcdef son usadas para conversiones x. Las
letras ABCDEF son usadas para conversiones X. La precision, si
se ha indicado alguna, da el minimo numero de digitos que deben
aparecer. Si el valor convertido requiere menos digitos, este es
rellenado a la izquierda con ceros. La precision por omision es
1. Cuando se imprime 0 con una precision explicita 0, la salida
es la cadena vacia.
e,E El argumento double es redondeado y convertido al formato
[-]d.ddde+-dd donde hay un digito delante del caracter del punto
decimal y el numero de digitos despues de este es igual a la
precision. Si no se indica precision, esta es tomada como 6. Si
la precision es cero, no aparece el caracter de punto decimal.
Una conversion E usa la letra E ( en vez de e) para introducir
el exponente. El exponente siempre contiene al menos dos
digitos. Si el valor es cero, el exponente es 00.
f,F El argumento double es redondeado y convertido a una notacion
decimal del estilo [-]ddd.ddd, donde el numero de digitos
despues del caracter del punto decimal es igual a la
especificacion de la precision. Si no se indica precision, esta
es tomada como 6. Si la precision es explicitamente cero, no
aparece el caracter del punto decimal. Si aparece un punto
decimal, al menos aparece un digito delante de el.
(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 numero). El estandar C00 especifica
`[-]inf' o `[-]infinity' para el infinito y una cadena que
comienza por `Nan' para NaN, en el caso de una conversion f, y
`[-]INF' o `[-]INFINITY' o `NAN*' en el caso de una conversion
F.)
g,G El argumento double es convertido al estilo de f o e (o F o E
para conversiones G ). La precision especifica el numero de
digitos significativos. Si no se indica precision, se dan 6
digitos. Si la precision es cero, esta es tratada como 1. Se
utiliza el formato de e si el exponente de su conversion es
menor que -4 o mas grande o igual a la precision. Los ceros
finales se eliminan de la parte fraccional del resultado. Un
punto decimal solo aparece si es seguido de al menos un digito.
a,A (C99. No en SUSv2) Para una conversion a, el argumento double se
convierte a notacion hexadecimal (usando las letras abcdef)
segun el estilo [-]0xh.hhhhp+-d. Para una conversion A se usan
el prefijo 0X, las letras ABCDEF y el separador de exponente P.
Hay un digito hexadecimal antes del punto decimal y el numero de
digitos tras el es igual a la precision. La precision por
omision es suficiente para una representacion exacta del valor
si existe una representacion exacta en base 2 y, en otro caso,
es suficientemente grande para distinguir valores de tipo
double. El digito antes del punto decimal queda sin especificar
para numeros no normalizados y distinto de cero pero, en
cualquier caso, sin especificar para numeros normalizados.
c Si no esta presente un modificador l, el argumento int es
convertido a un unsigned char, y se escribe el caracter
resultante. Si esta presente un modificador l, el argumento
wint_t (caracter ancho) se convierte a una secuencia multibyte
llamando a la funcion wcrtomb, con un estado de conversion que
comienza en el estado inicial, y se escribe la cadena multibyte
resultante.
s Si no esta presente un modificador l: se espera que el argumento
const char * sea un puntero a un vector (array) de tipo caracter
(puntero a una cadena de caracteres). Se escriben caracteres del
array hasta (pero no incluyendo) un caracter terminador NUL. Si
se especifica una precision, no se escriben mas caracteres del
numero especificado. Si se da una precision, no es necesario que
aparezca ningun caracter nulo. Si no se especifica precision, o
es mayor que el tamano de la cadena, la cadena debe contener un
caracter de terminacion NUL. Si esta 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
funcion wcrtomb, con un estado de conversion que comienza en el
estado inicial antes del primer caracter ancho) incluyendo el
caracter ancho nulo terminador. Los caracteres multibyte
resultantes se escriben hasta llegar (pero sin incluir) el byte
nulo terminador. Si se especifica una precision, no se escriben
mas bytes de los indica el numero, aunque no se escribe ningun
caracter multibyte parcial. Advierta que la precision determina
el numero de bytes escritos, no el numero de caracteres anchos o
posiciones de pantalla. El vector debe contener un caracter
ancho nulo terminador, a menos que se de una precision que sea
tan pequena que el numero de bytes escritos la exceda antes de
llegar al final del vector.
C (No en C99, pero si en SUSv2.) Sinonimo de lc. No usar.
S (No en C99, pero si en SUSv2.) Sinonimo 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 numero 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 ningun argumento.
% Se escribe un `%'. No se convierte ningun argumento. La
especificacion completa de conversion 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 paises usan el orden dia-mes-ano. Por tanto, una version
internacionalizada debe ser capaz de mostrar los argumentos en el orden
indicado por el formato:
#include <stdio.h>
fprintf(stdout, formato,
diasemana, mes, dia, hora, min);
donde formato depende de la localizacion y puede permutar los
argumentos. Con el valor
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
se podria 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:
(codigo 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 mas 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, intentalo de nuevo con mas espacio. */
if (n > -1) /* glibc 2.1 */
size = n+1; /* exactamente lo que se necesita */
else /* glibc 2.0 */
size *= 2; /* el doble del tamano anterior*/
if ((p = realloc (p, size)) == NULL)
return NULL;
}
}
OBSERVACIONES
La implementacion de glibc de las funciones snprintf y vsnprintf es
conforme con el estandar C99, es decir, se comporta como se describe
arriba, desde la version 2.1 de glibc. Hasta la version 2.0.6 de glibc
devolvian -1 cuando la salida era truncada.
CONFORME A
Las funciones fprintf, printf, sprintf, vprintf, vfprintf, y vsprintf
estan conforme a ANSI X3.159-1989 (``ANSI C'') e ISO/IEC 9899:1999
(``ISO C99''). Las funciones snprintf y vsnprintf estan conforme a
ISO/IEC 9899:1999.
Teniendo en cuenta el valor devuelto pr snprintf, SUSv2 y el estandar
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 numero de caracteres que habrian sido escritos en el caso de
que la cadena de salida hubiera sido lo suficientemente grande.
La libc4 de Linux reconoce las cinco opciones estandares de C. Reconoce
los modificadores de longitud h, l y L, y las conversiones
cdeEfFgGinopsuxX, donde F es un sinonimo de f. Adicionalmente, acepta
D, O y U, como sinonimos de ld, lo y lu. (Esto es malo y provoco serios
fallos mas tarde, cuando desaparecio el soporte para %D). No reconoce
un caracter radical dependiente de la localizacion, ni un separador de
miles, ni NaN ni infinito, ni %m$ ni *m$.
La biblioteca libc5 de Linux reconoce las cinco opciones estandares de
C y la opcion ', 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 mas
FDOU, pero anade un nuevo caracter de conversion m, que produce
strerror(errno).
glibc 2.0 anade los caracteres de conversion C y S.
glibc 2.1 anade los modificadores de longitud hh, j, t y z, y los
caracteres de conversion a y A.
glibc 2.2 anade el caracter de conversion F con la semantica de C99, y
el caracter de opcion I.
HISTORIA
Unix V7 define las tres rutinas printf, fprintf, sprintf, y posee la
opcion -, la anchura o precision *, el modificador de longitud l, las
conversiones doxfegcsu, y tambien D, O, U y X como sinonimos de ld, lo,
lu y lx. Esto todavia 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 opcion 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 tambien posee las
funciones asprintf y vasprintf, que reservan un buffer los
suficientemente largo para sprintf. En glibc estan 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 localizacion y que
son dificiles de predecir. Use snprintf y vsnprintf en su lugar (o
asprintf y vasprintf).
La biblioteca libc4.[45] de Linux no posee la funcion snprintf, pero
proporciona una libbsd que contiene una funcion 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 codigo como printf(foo); indican a menudo un fallo,
puesto que foo puede contener un caracter %. 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'EASE TAMBI'EN
printf(1), asprintf(3), dprintf(3), wcrtomb(3), wprintf(3), scanf(3),
locale(5)
Pagina man de Linux 16 octubre 2000 PRINTF(3)