vsprintf

PRINTF(3)                Manual del Programador de Linux               PRINTF(3)



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



GNU                             1 Noviembre 2020                       PRINTF(3)