.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUARS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED A, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUARS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED A, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR ART (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)printf.3	6.14 (Berkeley) 7/30/91
.\"
.\" Converted for Linux, Mon Nov 29 12:06:07 1993, faith@cs.unc.edu
.\"
.\" Modified to resemble the GNU libio setup used in the Linux libc
.\" used in versions 4.x (x>4) and 5,  Helmut.Geyer@iwr.uni-heidelberg.de
.\"
.\" Added [v]snprintf, 1996/01/28, agulbra@troll.no
.\"
.\" Traducido al castellano (con permiso) por:
.\" Sebastian Desimone (chipy@argenet.com.ar) (desimone@fasta.edu.ar)
.\" Translation revised May 11 1998 by juanma <imontalvoo@medynet.com>
.\" Translation revised June 9 1998 by Juan Piernas <piernas@dif.um.es>
.\" Translation revised August 17 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Sat Jun 26 1999 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH PRINTF 3  "28 Enero 1996" "Linux" "Manual del Programador de Linux"
.SH NOMBRE
printf, fprintf, sprintf, vprintf, vfprintf, vsprintf \- conversin de 
salida formateada
.SH SINOPSIS
.B #include <stdio.h>
.sp
.BI "int printf(const char *" format ", ...);"
.br
.BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
.br
.BI "int sprintf(char *" str ", const char *" format ", ...);"
.br
.BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
.sp
.B #include <stdarg.h>
.sp
.BI "int vprintf(const char *" format ", va_list " ap );
.br
.BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
.br
.BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
.br
.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap );
.SH DESCRIPCIN
La familia de funciones
.B printf
produce una salida de acuerdo a
.I format
como se describe abajo.
.B Printf
y
.B vprintf
escriben su salida a
.IR stdout ,
el flujo de salida estndar;
.B fprintf
y
.B vfprintf
escriben su salida al
.IR stream 
de salida dado;
.BR sprintf ,
.BR snprintf ,
.B vsprintf
y
.B vsnprintf
escriben a una cadena de caracteres
.IR  str .
.PP
Todas estas funciones escriben la salida bajo el control de una cadena
.I format
que especifica cmo los argumentos posteriores (o los argumentos accedidos
mediante las facilidades de argumentos de longitud variables proporionadss
por
.BR stdarg (3))
son convertidos para su salida.
.PP
Estas funciones devuelven el nmero de
caracteres impresos (no incluyendo el carcter `\e0' usado para terminar
la salida de cadenas).
.BR snprintf " y " vsnprintf
no escriben ms de
.I size
bytes (incluyendo el carcter terminador '\e0'), y devuelven -1 si la salida
se ha truncado debido a esta limitacin.
(As es hasta la versin 2.0.6 de glibc. Desde la versin 2.1 la funcin
.B vsnprintf
devuelve el nmero de caracteres (excluyendo el carcter terminador '\e0')
que se habran escrito en la cadena final si hubiera habido suficiente
espacio.)
.PP
La cadena \fBformat\fP est compuesta de cero o ms directivas: caracteres
ordinarios (no
.BR % )-
que se copian sin cambios al flujo de salida, e
indicaciones de conversin, cada una de las cuales produce la bsqueda
de cero o ms argumentos posteriores. Cada especificacin de conversin se
introduce mediante el carcter 
.BR % .
Los argumentos deben corresponder adecuadamente (tras la promocin de tipos)
con el indicador de conversin. Despus de
.BR % ,
los siguientes caracteres pueden aparecer en secuencia:
.TP
.B \(bu
Cero o ms de las siguientes banderas:
.RS
.TP
.B #
indica que el valor debe ser convertido a un ``formato alternativo''.
Para las conversiones
.BR c ,
.BR d ,
.BR i ,
.BR n ,
.BR p ,
.BR s ,
y
.BR u ,
esta opcin no tiene efecto. Para la conversin
.BR o ,
se incrementa la precisin del nmero para hacer que el primer carcterer
de la cadena de salida sea cero (excepto si se imprime el valor cero con 
una precisin explcita de cero). 
Para las conversiones
.B x
y
.BR X ,
la cadena `0x' (o `0X' para conversiones
.B X
) precede a los resultados que son distintos de 0.  Para las conversiones
.BR e ,
.BR E ,
.BR f ,
.BR g ,
y
.BR G ,
el resultado contendr un punto decimal, an si ningn dgito lo
sigue (normalmente, slo aparece un punto decimal en el resultado de
aquellas conversiones que son seguidas de algn dgito). Para las conversiones 
.B g
y
.BR G ,
en el resultado no se eliminan los ceros del final, como ocurrira en otro
caso.
.TP
.B \&0
indica el relleno con ceros. Para todas las converiones excepto para
.BR n ,
el valor convertido es rellenado a la izquierda con ceros en vez de blancos.
Si en una conversin numrica
.BR "" ( d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
y
.BR X ),
se indica una precisin, la bandera
.B \&0
se ignora.
.TP
.B \-
(una bandera de ancho de campo negativo) indica que el valor convertido es
justificado a la izquierda sobre el lmite del campo. Excepto para conversiones
.BR n ,
el valor convertido es rellenado a la derecha con blancos, en vez de a la
izquierda con blancos o ceros. Un
.B \-
sobreescribe un 
.B \&0
si se indican ambos.
.TP
.B ""
(un espacio) indica que se debe dejar un espacio en blanco delante de 
un nmero positivo producido por una conversin de signo
.BR "" ( d ,
.BR e ,
.BR E ,
.BR f ,
.BR g ,
.BR G ,
o
.BR i ).
.TP
.B +
indica que siempre se colocar el signo delante de un nmero producido
por una conversin con signo.  Un
.B +
sobreescribe un espacio si se usan ambos.
.TP
.B '
indica que en un argumento numrico la salida va a ser agrupada si la
informacin de localizacin as lo indica. Dse cuenta que muchas versiones
de
.B gcc
no pueden analizar esta opcin y producirn un "warning".
.RE
.TP
.B \(bu
Una cadena de dgitos decimales opcionales indicando un ancho de campo
mnimo. Si el valor convertido tiene menos caracteres que el ancho del
campo, se rellenar con espacios a la izquierda (o a la derecha si se ha
indicado la bandera de justificacin a la izquierda) para abarcar el ancho
del campo.
.TP
.B \(bu
Una precisin opcional, indicada por un punto (`\&.') seguido por una
cadena de dgitos tambin opcional. Si se omite la cadena de dgitos, la 
precisin se toma como cero. Esto da el nmero mnimo de dgitos 
que deben aparecer en las conversiones
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
y
.BR X ,
el nmero de dgitos que deben aparacer tras el punto decimal en las 
conversiones
.BR e ,
.BR E ,
y
.BR f ,
el mximo nmero de dgitos significativos para las conversiones 
.B g
y
.BR G ,
o el mximo nmero de caracteres a imprimir de una cadena en
las conversiones 
.B s
.
.TP
.B \(bu
El carcter opcional
.BR h ,
que indica que la siguiente conversin
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
o
.BR X
corresponden a un argumento
.I short int
o
.IR "unsigned short int" ,
o que la siguiente conversin
.B n
corresponde a un puntero a un argumento
.I short int
.
.TP
.B \(bu
El caracter opcional
.B l
(ele) indica que la siguiente conversin
.BR d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
o
.BR X
se aplica a un puntero a un argumento 
.I long int
o
.IR "unsigned long int" ,
que la siguiente conversin
.B n
corresponde a un puntero a un argumento
.IR "long int" .
Linux proporciona un uso no conforme a ANSI de dos banderas
.B l
como un sinnimo de
.B q
o
.BR L.
As
.B ll
se puede usar junto a las conversiones de coma flotante.
Sin embargo este uso es fuertemente desaconsejado.
.TP
.B \(bu
El carcter
.BR L
especifica que la siguiente conversin
.BR e ,
.BR E ,
.BR f ,
.BR g ,
o
.B G
corresponde a un argumento
.IR "long double" ,
o que la siguiente conversin
.BR d,
.BR i,
.BR o,
.BR u,
.BR x,
o
.BR X
corresponden a un argumento
.I long long
Dse cuenta que 
.I long long
no est especificado en el
.I ANSI C
y, por consiguiente, no es trasladable a todas las arquitecturas.
.TP
.B \(bu
El carcter opcional 
.BR q .
Es equivalente a 
.BR L .
Vea las secciones ESTNDARES Y FALLOS para comentarios acerca del
uso de
.BR ll ,
.BR L ,
y 
.BR q ,
.TP 
.B \(bu
Un carcter
.B Z 
especificando que la siguiente conversin de enteros 
.BR "" ( d ,
.BR i ,
.BR o ,
.BR u ,
.BR x ,
o
.BR X ),
corresponde a un argumento
.IR size_t .
.TP 
.B \(bu
Un carcter que especifica el tipo de conversin a ser aplicado.
.PP
Se puede indicar un ancho de campo o una precisin, o ambos, mediante un
asterisco `*' en lugar de una cadena de dgitos. En este caso, un argumento
.I int
suministra el ancho de campo o la precisin. Un ancho de campo negativo se
trata como una bandera de justificado a la izquierda seguida por un ancho de
campo positivo; una precisin negativa se trata como si no se hubiese
indicado.
.PP
Los indicadores de conversin y sus significados son:      
.TP
.B diouxX
El argumento
.I int
( o la variante apropiada) es convertida a un decimal con signo
.BR "" ( d
y
.BR i ),
a octal sin signo
.BR "" ( o ,
a decimal sin signo
.BR "" ( u ,
a a notacin hexadecimal sin signo
.BR "" ( x
y
.BR X ).
Las letras
.B abcdef
son usadas para conversiones
.BR x ;
las letras
.B ABCDEF
son usadas para conversiones
.BR X .
La precisin, si se ha indicado alguna, da el mnimo nmero de dgitos que
deben aparecer; si el valor convertido requiere menos dgitos, ste es
rellenado a la izquierda con ceros.
.TP
.B eE
El argumento 
.I double
es redondeado y convertido al formato
.BR "" [\-]d \&. ddd e \\*(Pmdd
donde hay un dgito delante del carcter del punto decimal y el nmero de
dgitos despus de ste es igual a la precisin; si no se indica precisin,
sta es tomada como 6; si la precisin es cero, no aparece el carcter de
punto decimal. Una conversin
.B E
usa la letra
.B E
( en vez de 
.BR e )
para introducir el exponente. El exponente siempre contiene al menos dos
dgitos; si el valor es cero, el exponente es 00.
.TP
.B f
El argumento
.I double
es redondeado y convertido a una notacin decimal del estilo
.BR "" [-]ddd \&. ddd,
donde el nmero de dgitos despus del carcter del punto decimal es igual a 
la especificacin de la precisin. Si no se indica precisin, sta es
tomada como 6; si la precisin es explcitamente cero, no aparece el carcter
del punto decimal. Si aparece un punto decimal, al menos aparece un dgito
delante de l.
.TP
.B g
El argumento
.I double
es convertido al estilo de
.B f
o
.B e
(o
.B E
para conversiones
.B G
). La precisin especifica el nmero de dgitos significativos.
Si no se indica precisin, se dan 6 dgitos; si la precisin es cero,
sta es tratada como 1. Se utiliza el formato de
.B e
si el exponente de su conversin es menor que \-4 o ms grande
o igual a la precisin. Los ceros finales se eliminan de la parte fraccional
del resultado; un punto decimal slo aparece si es seguido de al menos un
dgito. 
.TP
.B c
El argumento
.I int
es convertido a un
.IR "unsigned char" ,
y se escribe el carcter resultante.
.TP
.B s
Se espera que el argumento
.IR "" `` "char *" ''
sea un puntero a un arreglo (array) de tipo carcter (puntero a una cadena de
caracteres). Se escriben caracteres del array hasta (pero no incluyendo)
un carcter terminador 
.B NUL
; si se especifica una precisin, no se escriben ms caracteres del nmero
especificado. Si se da una precisin, no es necesario que aparezca ningn
carcter nulo; si no especificada precisin, o es mayor que el tamao
de la cadena, la cadena debe contener un carcter de terminacin
.BR NUL .
.TP
.B p
El argumento de tipo puntero
.IR "" `` "void *" ''
se imprime en hexadecimal (como si se hubiera indicado
.B %#x
o
.BR  %#lx ).
.TP
.B n
El nmero de caracteres escritos hasta ahora se guarda en el entero indicado
por el argumento de tipo puntero
.IR "" `` "int *" ''
(o una variante suya). No se convierte ningn argumento.
.TP
.B %
Se escribe un `%'. No se convierte ningn argumento. La especificacin completa
de conversin es `%%'.
.PP
En ningn caso un ancho de campo pequeo o inexistente produce el
truncamiento del campo; si el resultado de una conversin es ms ancho
que el campo, el campo se expande para contener el resultado convertido.
.PP
.SH EJEMPLOS
.br
Para imprimir una fecha y una hora de la forma `Sunday, July 3, 10:02',
donde
.I weekday
y
.I month
son punteros a cadenas:
.RS
.nf
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
	weekday, month, day, hour, min);
.fi
.RE
.PP
Para imprimir \*(Pi
con cinco lugares decimales:
.RS
.nf
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
.fi
.RE
.PP
Para reservar una cadena de 128 bytes e imprimir dentro de ella:
.RS
.nf
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
		char *p;
		va_list ap;
		if ((p = malloc(128)) == NULL)
			return (NULL);
		va_start(ap, fmt);
		(void) vsnprintf(p, 128, fmt, ap);
		va_end(ap);
		return (p);
}
.fi
.RE
.SH "VASE TAMBIN"
.BR printf "(1), " scanf (3)
.SH ESTNDARES
Las funciones
.BR fprintf ,
.BR printf ,
.BR sprintf ,
.BR vprintf ,
.BR vfprintf ,
y
.B vsprintf
estn conforme a ANSI C3.159-1989 (``ANSI C'').
La bandera
.B q
es la notacin de
.I BSD 4.4
para
.IR "long long" ,
mientras que
.B ll
o el uso de
.B L
en las conversiones de enteros es la notacin GNU.
.PP
La versin de Linux de estas funciones est basada en la biblioteca
.I libio
de
.IR GNU .
Eche un vistazo a la documentacin
.I info
de la
.I libc (glibc-1.08)
de 
.I GNU
para una descripcin ms concisa.

.SH FALLOS
Algunas conversiones de coma flotante bajo Linux producen prdidas de memoria.
.PP
Todas las funciones cumplen completamente el estndar ANSI C3.159-1989,
aunque adicionalmente proporcionan las banderas
.BR q ,
.B Z
y
.B '
as como el comportamiento adicional de las banderas
.B L
y
.BR l .
Esto ltimo se puede considerar como un fallo, ya que cambia el
comportamiento de las banderas definidas en ANSI C3.159-1989.
.PP
El efecto de relleno del formato 
.B %p
con ceros (bien por la bandera 
.BR 0 ,
bien por especificar una precisin), y el efecto benigno (es decir, ninguno)
de la bandera
.B #
en las las conversiones
.B %n
y
.BR %p ,
as como las combinaciones sin sentido de las mismas,
no son estndares; dichas combinaciones debe ser evitadas.
.PP
Algunas combinaciones de banderas definidas por
.I ANSI C
no tienen sentido (por ejemplo,
.BR "%Ld" ).
Aunque pueden tener un comportamiento bien definido en Linux, esto no tiene
por qu ser as en otras arquitecturas. Por tanto, normalmente es mejor no
usar en absoluto banderas que no estn definidas en
.IR "ANSI C" ,
o sea, usar
.B q
en lugar de
.B L
en combinacin con las conversiones
.B diouxX
o
.BR ll .
.PP
El uso de
.B q
no es el mismo que en
.IR "BSD 4.4" ,
ya que puede ser utilizado en conversiones de coma flotante de forma
equivalente a
.BR L .
.PP
Ya que
.B sprintf
y
.B vsprintf
asumen una cadena de longitud infinita, los invocadores deben tener cuidado
de no sobrepasar el espacio actual; a menudo, esto es imposible de garantizar.