Ubuntu Manpage: printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf,

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);

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 ⟨⟩.