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

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

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
       format  string that specifies how subsequent arguments (or
       arguments accessed via the variable-length argument facil-
       ities 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  does  not write more than size bytes
       (including the trailing '\0'), and returns -1 if the  out-
       put was truncated due to this limit.  vsnprintf works sim-
       ilarly to snprintf, but returns the number  of  characters
       which  would have been in the final string if enough space
       had been available (excluding 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:

       +o      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.

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

       +o      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.

       +o      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.

       +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 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.

       +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
              (d,  i,  o, u, x, or X) conversion corresponds to a
              size_t argument.

       +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
       negative field width is treated as a left adjustment  flag
       followed  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  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
              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-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  con-
       tain 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
       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.

Linux Manpage            28 January 1996                        1