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

     #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


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.

     These functions write the output under the control of a for-
     mat string that specifies how subsequent arguments (or argu-
     ments accessed via the variable-length  argument  facilities
     of stdarg(3)) are converted for output.

     These functions return the number of characters printed (not
     including  the trailing `\0' used to end output to strings).
     snprintf and vsnprintf do not write  more  than  size  bytes
     (including  the  trailing '\0'), and return -1 if the output
     was truncated due to this limit.

     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 arguments.
     Each conversion specification is introduced by the character
     %.   The arguments must correspond properly (after type pro-
     motion) with the conversion specifier.   After  the  %,  the
     following appear in sequence:

     o    Zero or more of the following flags:

          #    specifying that the value should be  converted  to
               an  ``alternate form''.  For c, d, i, n, p, s, and
               u conversions, this option has no effect.   For  o
               conversions,   the  precision  of  the  number  is
               increased to force the first character of the out-
               put  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 conversions, 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  conversions
               except  n,  the  converted  value is padded on the
               left with zeros rather than blanks.  If  a  preci-
               sion  is given with a numeric conversion  i, o, u,
               i, x, and X), the 0 flag is ignored.

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

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

          +    specifying that a sign always be placed  before  a
               number produced by a signed conversion.  A + over-
               rides a space if both are used.

          '    specifying that in a numerical argument the output
               is  to  be grouped if the locale information indi-
               cates any.  Note that many versions of gcc  cannot
               parse this option and will issue a warning.

     o    An optional decimal digit string specifying  a  minimum
          field  width.  If the converted value has fewer charac-
          ters than the field  width,  it  will  be  padded  with
          spaces  on  the  left (or right, if the left-adjustment
          flag has been given) to fill out the field width.

     o    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 char-
          acters to be printed from a string for s conversions.

     o    The optional character h, specifying that  a  following
          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.

     o    The optional character l (ell) specifying that  a  fol-
          lowing  d,  i,  o,  u,  x, or X conversion applies to a
          pointer to a long int or unsigned long int argument, or
          that  a following n conversion corresponds to a pointer
          to a long int argument.  Linux provides a non ANSI com-
          pliant use of two l flags as a synonym to q or L.  Thus
          ll can be used in combination with  float  conversions.
          This usage is, however, strongly discouraged.

     o    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  conversion
          corresponds  to  a  long long argument.  Note that long
          long is not specified in ANSI C and therefore not port-
          able to all architectures.

     o    The optional character q.  This  is  equivalent  to  L.
          See the STANDARDS and BUGS sections for comments on the
          use of ll, L, and q.

     o    A Z character specifying that the following integer  i,
          o, u, x, or X) conversion corresponds to a size_t argu-
          ment.

     o    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 nega-
     tive  field  width is treated as a left adjustment flag fol-
     lowed by a positive field width;  a  negative  precision  is
     treated as though it were missing.

     The conversion specifiers and their meanings are:

     diouxX
          The int (or appropriate variant) argument is  converted
          to  signed  decimal    and i), unsigned octal  unsigned
          decimal  or unsigned hexadecimal  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    where  there  is one digit 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    The double argument is rounded and converted to decimal
          notation in the style  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 precision  is  explicitly  zero,  no
          decimal-point  character  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 followed by at least one digit.

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

     s    The  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 number specified are  written.   If  a
          precision  is 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 ter-
          minating NUL character.

     p    The  pointer argument is printed in hexadecimal (as  if
          by %#x or %#lx).

     n    The number of characters written so far is stored  into
          the  integer  indicated  by  the   (or variant) pointer
          argument.  No argument is converted.

     %    A `%' is written. No argument is  converted.  The  com-
          plete conversion specification is `%%'.

     In no case does a non-existent 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 contain
     the conversion result.


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);
                    return (p);
          }


SEE ALSO

     printf(1), scanf(3)


STANDARDS

     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.

     The Linux version of these functions is  based  on  the  GNU
     libio library.  Take a look at the info documentation of GNU
     libc (glibc-1.08) for a more concise description.



BUGS

     Some floating point conversions  under  Linux  cause  memory
     leaks.

     All functions are fully  ANSI  C3.159-1989  conformant,  but
     provide  the additional flags q, Z and ' as well as an addi-
     tional 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  conversions,
     as  well  as  nonsensical combinations such as are not stan-
     dard; such combinations should be avoided.

     Some combinations of flags defined by ANSI C are not  making
     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.