File: *manpages*,  Node: fprintf,  Up: (dir)



PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

NAME
       printf,  fprintf,  sprintf,  snprintf,  vprintf, vfprintf,
       vsprintf, vsnprintf - formatted output conversion

SYNOPSIS
       #include <stdio.h>

       int printf(const char *format, ...);
       int fprintf(FILE *stream, const char *format, ...);
       int sprintf(char *str, const char *format, ...);
       int snprintf(char *str, size_t size, const  char  *format,
       ...);
       int asprintf(char **strp, const char *format, ...);
       int dprintf(int d, const char *format, ...);

       #include <stdarg.h>

       int vprintf(const char *format, va_list ap);
       int  vfprintf(FILE  *stream,  const  char *format, va_list
       ap);
       int vsprintf(char *str, const char *format, va_list ap);
       int vsnprintf(char *str, size_t size, const char  *format,
       va_list ap);
       int  vasprintf(char  **strp,  const  char *format, va_list
       ap);
       int vdprintf(int d, const char *format, va_list ap);

DESCRIPTION
       The printf family of functions produces  output  according
       to  a  format as described below. The functions printf and
       vprintf  write  output  to  stdout,  the  standard  output
       stream;  fprintf  and  vfprintf  write output to the given
       output stream; sprintf, snprintf, vsprintf  and  vsnprintf
       write  to the character string str; asprintf and vasprintf
       write to a dynamically allocated buffer, whose address  is
       returned in *strp; dprintf and vdprintf write to the given
       file descriptor.

       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 facil
       ities of stdarg(3)) are converted for output.

       snprintf  and  vsnprintf do not write more than size bytes
       (including the trailing '\0').

       The format string is composed of zero or more  directives:
       ordinary characters (not %), which are copied unchanged to
       the output stream; and conversion specifications, each  of
       which  results  in  fetching zero or more subsequent argu
       ments.  Each conversion specification is introduced by the
       character  %.   The  arguments  must  correspond  properly
       (after type  promotion)  with  the  conversion  specifier.
       After the %, the following appear in sequence:

Linux Manpage            28 January 1996                        1

PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

             Zero or more of the following flags:

              #      specifying  that  the  value  should be con
                     verted to an ``alternate form''.  For c,  d,
                     i,  n,  p, s, and u conversions, this option
                     has no effect.  For o conversions, the  pre
                     cision  of  the number is increased to force
                     the first character of the output string  to
                     a  zero  (except  if a zero value is printed
                     with an explicit precision of zero).  For  x
                     and X conversions, a non-zero result has the
                     string `0x'  (or  `0X'  for  X  conversions)
                     prepended to it.  For e, E, f, g, and G con
                     versions, the result will always  contain  a
                     decimal  point,  even if no digits follow it
                     (normally, a decimal point  appears  in  the
                     results of those conversions only if a digit
                     follows).  For g and G conversions, trailing
                     zeros  are  not  removed  from the result as
                     they would otherwise be.

              0      specifying zero padding.   For  all  conver
                     sions  except  n,  the  converted  value  is
                     padded on the left with  zeros  rather  than
                     blanks.   If  a  precision  is  given with a
                     numeric conversion (d, i, o, u,  i,  x,  and
                     X), the 0 flag is ignored.

              -      (a  negative field width flag) indicates the
                     converted value is to be  left  adjusted  on
                     the  field  boundary.   Except for n conver
                     sions, the converted value is padded on  the
                     right  with  blanks, rather than on the left
                     with blanks or zeros.  A - overrides a 0  if
                     both are given.

                   (a  space) specifying that a blank should be
                     left before a positive number produced by  a
                     signed  conversion (d, e, E, f, g, G, or i).

              +      specifying that  a  sign  always  be  placed
                     before a number produced by a signed conver
                     sion.  A + overrides a  space  if  both  are
                     used.

              '      specifying  that in a numerical argument the
                     output is to be grouped if the locale infor
                     mation  indicates  any.  Note that many ver
                     sions of gcc cannot parse  this  option  and
                     will issue a warning.

             An optional decimal digit string specifying a mini
              mum field width.  If the converted value has  fewer
              characters  than the field width, it will be padded

Linux Manpage            28 January 1996                        2

PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

              with  spaces  on  the  left  (or  right,   if   the
              left-adjustment  flag  has  been given) to fill out
              the field width.

             An optional precision, in  the  form  of  a  period
              (`.')   followed  by  an optional digit string.  If
              the digit string is omitted, the precision is taken
              as  zero.   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 decimal-point
              for e, E, 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 conversions.

             The optional character h, specifying that a follow
              ing d, i, o, u, x, or X conversion corresponds to a
              short int or unsigned short int argument, or that a
              following n conversion corresponds to a pointer  to
              a short int argument.

             The  optional  character  l (ell) specifying that a
              following d, i, o, u, x, or X conversion applies to
              a  pointer to a long int or unsigned long int argu
              ment, or that a following n conversion  corresponds
              to  a  pointer  to a long int argument.  Linux pro
              vides a non ANSI compliant use of two l flags as  a
              synonym to q or L.  Thus ll can be used in combina
              tion with float conversions.  This usage  is,  how
              ever, strongly discouraged.

             The  character  L specifying that a following e, E,
              f, g, or G conversion corresponds to a long  double
              argument,  or  a following d, i, o, u, x, or X con
              version corresponds to a long long argument.   Note
              that  long  long  is  not  specified  in ANSI C and
              therefore not portable to all architectures.

             The optional character q.  This is equivalent to L.
              See  the  CONFORMING  TO and BUGS sections for com
              ments on the use of ll, L, and q.

             A Z character specifying that the following integer
              (d,  i,  o, u, x, or X) conversion corresponds to a
              size_t argument.

             A character that specifies the type  of  conversion
              to be applied.

       A  field  width or precision, or both, may be indicated by
       an asterisk `*' instead of a digit string.  In this  case,
       an  int argument supplies the field width or precision.  A
       negative field width is treated as a left adjustment  flag
       followed  by  a positive field width; a negative precision

Linux Manpage            28 January 1996                        3

PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

       is treated as though it were missing.

       The conversion specifiers and their meanings are:

       diouxX The int (or appropriate variant) argument  is  con
              verted  to signed decimal (d and i), unsigned octal
              (o), unsigned decimal (u), or unsigned  hexadecimal
              (x  and  X)  notation.  The letters abcdef are used
              for x conversions; the letters ABCDEF are used  for
              X  conversions.   The  precision, if any, gives the
              minimum number of digits that must appear;  if  the
              converted value requires fewer digits, it is padded
              on the left with zeros.

       eE     The double argument is rounded and converted in the
              style  [-]d.dddedd  where there is one digit before
              the decimal-point character and the number of  dig
              its after it is equal to the precision; if the pre
              cision is missing, it is taken as 6; if the  preci
              sion  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      The  double  argument  is  rounded and converted to
              decimal notation in the style [-]ddd.ddd, where the
              number  of digits after the decimal-point character
              is equal to the precision  specification.   If  the
              precision is missing, it is taken as 6; if the pre
              cision is explicitly zero, no decimal-point charac
              ter  appears.  If a decimal point appears, at least
              one digit appears before it.

       g      The double argument is converted in style  f  or  e
              (or  E for G conversions).  The precision specifies
              the number of significant digits.  If the precision
              is missing, 6 digits are given; if the precision is
              zero, it is treated as 1.  Style e is used  if  the
              exponent  from  its  conversion  is less than -4 or
              greater than or equal to the  precision.   Trailing
              zeros  are  removed from the fractional part of the
              result; a decimal point appears only if it is  fol
              lowed by at least one digit.

       c      The  int argument is converted to an unsigned char,
              and the resulting character is written.

       s      The ``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 NUL character;
              if a precision is specified, no more than the  num
              ber  specified  are  written.   If  a  precision is

Linux Manpage            28 January 1996                        4

PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

              given, no null character need be  present;  if  the
              precision  is not specified, or is greater than the
              size of the array, the array must contain a  termi
              nating NUL character.

       p      The  ``void *'' pointer argument is printed in hex
              adecimal (as if by %#x or %#lx).

       n      The number of characters written so far  is  stored
              into  the  integer  indicated  by the ``int *'' (or
              variant) pointer argument.   No  argument  is  con
              verted.

       %      A  `%'  is  written.  No argument is converted. The
              complete conversion specification is `%%'.

       In no case does a non-existant or small field width  cause
       truncation  of  a  field; if the result of a conversion is
       wider than the field width, the field is expanded to  con
       tain the conversion result.

RETURN VALUES
       These  functions  return  the number of characters printed
       (not including the trailing `\0' used  to  end  output  to
       strings).   snprintf and vsnprintf return -1 if the output
       was truncated due to  the  limit  specified  in  the  size
       parameter.

EXAMPLES
       To  print  a  date  and  time in the form `Sunday, July 3,
       10:02', where weekday and month are pointers to strings:
              #include <stdio.h>
              fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                   weekday, month, day, hour, min);

       To print to five decimal places:
              #include <math.h>
              #include <stdio.h>
              fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

       To allocate a 128 byte string and print into it:
              #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);

Linux Manpage            28 January 1996                        5

PRINTF(3)           Linux Programmer's Manual           PRINTF(3)

                        return (p);
              }

SEE ALSO
       printf(1), scanf(3)

CONFORMING TO
       The  fprintf,  printf,  sprintf,  vprintf,  vfprintf,  and
       vsprintf  functions  conform  to  ANSI C3.159-1989 (``ANSI
       C'').

       The q flag is the BSD 4.4 notation for long long, while ll
       or  the usage of L in integer conversions is the GNU nota
       tion.

BUGS
       All functions are fully ANSI C3.159-1989  conformant,  but
       provide  the  additional  flags  q,  Z and ' as well as an
       additional behaviour of the L and l flags.  The latter may
       be  considered to be a bug, as it changes the behaviour of
       flags defined in ANSI C3.159-1989.

       The effect of padding the %p format with zeros (either  by
       the  0  flag or by specifying a precision), and the benign
       effect (i.e., none) of the # flag on  %n  and  %p  conver
       sions, as well as nonsensical combinations such as are not
       standard; such combinations should be avoided.

       Some combinations of flags defined by ANSI C are not  mak
       ing sense (e.g.  %Ld).  While they may have a well-defined
       behaviour on Linux, this need not to be so on other archi
       tectures.  Therefore it usually is better not to use flags
       that are not defined by ANSI C at all, i.e. use q  instead
       of L in combination with diouxX conversions or ll.

       The usage of q is not the same as on BSD 4.4, as it may be
       used in float conversions equivalently to L.

       Because sprintf and vsprintf  assume  an  infinitely  long
       string, callers must be careful not to overflow the actual
       space; this is often impossible to assure. You should  use
       asprintf or vasprintf instead.

Linux Manpage            28 January 1996                        6

