Provided by: manpages-es-dev_4.13-4_all 
NOMBRE
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf -
conversión de salida formateada
SINOPSIS
#include <stdio.h> int printf(const char *format, ...); int fprintf(FILE *stream, const char *format, ...); int dprintf(int fd, 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 vdprintf(int fd, 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); Requisitos de Macros de Prueba de Características para glibc (véase feature_test_macros(7)): snprintf(), vsnprintf(): _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE || || /* Glibc versions <= 2.19: */ _BSD_SOURCE dprintf(), vdprintf(): Desde glibc 2.10: _POSIX_C_SOURCE >= 200809L Antes de glibc 2.10: _GNU_SOURCE
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.
The function dprintf() is the same as fprintf() except that it outputs to a file descriptor, fd,
instead of to a stdio stream.
The functions snprintf() and vsnprintf() write at most size bytes (including the terminating null byte
('\0')) to str.
The functions vprintf(), vfprintf(), vdprintf(), vsprintf(), vsnprintf() are equivalent to the functions
printf(), fprintf(), dprintf(), sprintf(), snprintf(), respectively, except that they are called with a
va_list instead of a variable number of arguments. These functions do not call the va_end macro.
Because they invoke the va_arg macro, the value of ap is undefined after the call. See stdarg(3).
All of these functions write the output under the control of a format string that specifies how
subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg(3))
are converted for output.
C99 and POSIX.1-2001 specify that the results are undefined if a call to sprintf(), snprintf(),
vsprintf(), or vsnprintf() would cause copying to take place between objects that overlap (e.g., if the
target string array and one of the supplied input arguments refer to the same buffer). See NOTES.
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.
The arguments must correspond properly (after type promotion) with the conversion specifier. By default,
the arguments are used in the order given, where each '*' (see Field width and Precision below) and each
conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are
given). One can also specify explicitly which argument is taken, at each place where an argument is
required, by writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes
the position in the argument list of the desired argument, indexed starting from 1. Thus,
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. (Vea setlocale(3).) 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.
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). 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.
+ A sign (+ or -) should always be placed before a number produced by a signed conversion. By
default, a sign is used only for negative numbers. A + overrides a space if both are used.
The five flag characters above are defined in the C99 standard. The Single UNIX Specification specifies
one further flag character.
' For decimal conversion (i, d, u, f, F, g, G) the output is to be grouped with thousands' grouping
characters if the locale information indicates any. (See setlocale(3).) Note that many versions
of gcc(1) cannot parse this option and will issue a warning. (SUSv2 did not include %'F, but
SUSv3 added it.)
glibc 2.2 añada un nuevo carácter de opción adicional.
I For decimal integer conversion (i, d, u) the output uses the locale's alternative output digits,
if any. For example, since glibc 2.2.3 this will give Arabic-Indic digits in the Persian
("fa_IR") locale.
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.
Precisión
An optional precision, in the form of a period ('.') followed by an optional decimal digit string.
Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that
the precision is given in the next argument, or in the m-th argument, respectively, which must be of type
int. If the precision is given as just '.', the precision is taken to be zero. A negative precision is
taken as if the precision were omitted. This gives the minimum number of digits to appear for d, i, o,
u, x, and X conversions, the number of digits to appear after the radix character for a, A, e, E, f, and
F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of
characters to be printed from a string for s and S conversions.
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 o unsigned short, o que la
siguiente conversión n corresponde a un puntero a un argumento short.
l (ele) La siguiente conversión entera corresponde a un argumento long o unsigned long, o que la
siguiente conversión n corresponde a un puntero a un argumento long 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 o unsigned long
long, o que la siguiente conversión n corresponde a un puntero a un argumento long long.
q A synonym for ll. This is a nonstandard extension, derived from BSD; avoid its use in new code.
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.)
j La siguiente conversión entera se corresponde con un argumento intmax_t o uintmax_t, o que la
siguiente conversión n corresponde a un puntero a un argumento intmax_t.
z La siguiente conversión entera se corresponde con un argumento size_t o ssize_t, o que la
siguiente conversión n corresponde a un puntero a un argumento size_t.
Z A nonstandard synonym for z that predates the appearance of z. Do not use in new code.
t La siguiente conversión entera se corresponde con un argumento ptrdiff_t, o que la siguiente
conversión n corresponde a un puntero a un argumento ptrdiff_t.
SUSv3 specifies all of the above, except for those modifiers explicitly noted as being nonstandard
extensions. SUSv2 specified only the length modifiers h (in hd, hi, ho, hx, hX, hn) and l (in ld, li,
lo, lx, lX, ln, lc, ls) and L (in Le, LE, Lf, Lg, LG).
As a nonstandard extension, the GNU implementations treats ll and L as synonyms, so that one can, for
example, write llg (as a synonym for the standards-compliant Lg) and Ld (as a synonym for the standards
compliant lld). Such usage is nonportable.
Conversion specifiers
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 The double argument is rounded and converted in the style [-]d.ddde±dd where there is one digit
(which is nonzero if the argument is nonzero) before the decimal-point character and the number
of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if
the precision is zero, no decimal-point character appears. An E conversion uses the letter E
(rather than e) to introduce the exponent. The exponent always contains at least two digits; if
the value is zero, the exponent is 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 does not know about F and says that character string representations for infinity and NaN
may be made available. SUSv3 adds a specification for F. The C99 standard specifies "[-]inf" or
"[-]infinity" for infinity, and a string starting with "nan" for NaN, in the case of f conversion,
and "[-]INF" or "[-]INFINITY" or "NAN" in the case of F conversion.)
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; not in SUSv2, but added in SUSv3) For a conversion, the double argument is converted to
hexadecimal notation (using the letters abcdef) in the style [-]0xh.hhhhp±d; for A conversion the
prefix 0X, the letters ABCDEF, and the exponent separator P is used. There is one hexadecimal
digit before the decimal point, and the number of digits after it is equal to the precision. The
default precision suffices for an exact representation of the value if an exact representation in
base 2 exists and otherwise is sufficiently large to distinguish values of type double. The digit
before the decimal point is unspecified for nonnormalized numbers, and nonzero but otherwise
unspecified for normalized numbers. The exponent always contains at least one digit; if the value
is zero, the exponent is 0.
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(3), con un estado de
conversión que comienza en el estado inicial, y se escribe la cadena multibyte resultante.
s If no l modifier is present: the const char * argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up to (but not
including) a terminating null byte ('\0'); if a precision is specified, no more than the number
specified are written. If a precision is given, no null byte need be present; if the precision is
not specified, or is greater than the size of the array, the array must contain a terminating null
byte.
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(3), 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 o C11, pero sí en SUSv2, SUSv3 y SUSv4.) Sinónimo de lc. No usar.
S (No en C99 o C11, pero sí en SUSv2, SUSv3 y SUSv4.) 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 The number of characters written so far is stored into the integer pointed to by the corresponding
argument. That argument shall be an int *, or variant whose size matches the (optionally)
supplied integer length modifier. No argument is converted. (This specifier is not supported by
the bionic C library.) The behavior is undefined if the conversion specification includes any
flags, a field width, or a precision.
m (Glibc extension; supported by uClibc and musl.) Print output of strerror(errno). No argument is
required.
% Se escribe un `%'. No se convierte ningún argumento. La especificación completa de conversión es
`%%'.
VALOR DEVUELTO
Upon successful return, these functions return the number of characters printed (excluding the null byte
used to end output to strings).
The functions snprintf() and vsnprintf() do not write more than size bytes (including the terminating
null byte ('\0')). If the output was truncated due to this limit, then the return value is the number of
characters (excluding the terminating null byte) which would have been written to the final string if
enough space had been available. Thus, a return value of size or more means that the output was
truncated. (See also below under NOTES.)
If an output error is encountered, a negative value is returned.
ATRIBUTOS
Para obtener una explicación de los términos usados en esta sección, véase attributes(7). ┌────────────────────────┬────────────────────┬─────────────────────────────────────────────┐ │Interfaz │ Atributo │ Valor │ ├────────────────────────┼────────────────────┼─────────────────────────────────────────────┤ │printf(), fprintf(), │ Seguridad del hilo │ Configuración regional de multi-hilo seguro │ │sprintf(), snprintf(), │ │ │ │vprintf(), vfprintf(), │ │ │ │vsprintf(), vsnprintf() │ │ │ └────────────────────────┴────────────────────┴─────────────────────────────────────────────┘
CONFORME A
fprintf(), printf(), sprintf(), vprintf(), vfprintf(), vsprintf(): POSIX.1-2001, POSIX.1-2008, C89, C99.
snprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.
The dprintf() and vdprintf() functions were originally GNU extensions that were later standardized in
POSIX.1-2008.
Concerning the return value of snprintf(), SUSv2 and C99 contradict each other: when snprintf() is
called with size=0 then SUSv2 stipulates an unspecified return value less than 1, while C99 allows str to
be NULL in this case, and gives the return value (as always) as the number of characters that would have
been written in case the output string has been large enough. POSIX.1-2001 and later align their
specification of snprintf() with C99.
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.
NOTAS
Some programs imprudently rely on code such as the following
sprintf(buf, "%s some further text", buf);
to append text to buf. However, the standards explicitly note that the results are undefined if source
and destination buffers overlap when calling sprintf(), snprintf(), vsprintf(), and vsnprintf().
Depending on the version of gcc(1) used, and the compiler options employed, calls such as the above will
not produce the expected results.
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.
ERRORES
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(3) y vasprintf(3)).
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.
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 *
make_message(const char *fmt, ...)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;
/* Determine required size */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
/* One extra byte for '\0' */
size = (size_t) n + 1;
p = malloc(size);
if (p == NULL)
return NULL;
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0) {
free(p);
return NULL;
}
return p;
}
If truncation occurs in glibc versions prior to 2.0.6, this is treated as an error instead of being
handled gracefully.
VÉASE TAMBIÉN
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)
COLOFÓN
Esta página es parte de la versión 5.10 del proyecto Linux man-pages. Puede encontrar una descripción del
proyecto, información sobre cómo informar errores y la última versión de esta página en
https://www.kernel.org/doc/man-pages/.
TRADUCCIÓN
La traducción al español de esta página del manual fue creada por Sebastian Desimone
<chipy@argenet.com.ar>, juanma <imontalvoo@medynet.com>, Juan Piernas <piernas@ditec.um.es> y Miguel
Pérez Ibars <mpi79470@alu.um.es>
Esta traducción es documentación libre; lea la GNU General Public License Version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ o posterior con respecto a las condiciones de copyright. No
existe NINGUNA RESPONSABILIDAD.
Si encuentra algún error en la traducción de esta página del manual, envíe un correo electrónico a
debian-l10n-spanish@lists.debian.org ⟨⟩.