###

###

###

###

###

###

###

###

###

###

###

###

###

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

    NAME
           printf,  fprintf,  sprintf,  vprintf, vfprintf, vsprintf -
           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, ...);

           #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, char *format, va_list ap);

    DESCRIPTION
           The  printf  family of functions produces output according
           to a format as described below.  Printf and vprintf  write
           output  to stdout, the standard output stream; fprintf and
           vfprintf write output to the given output stream; sprintf,
           and  vsprintf  write  to  the character string str.  These
           functions write the output under the control of  a  format
           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).

           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

    BSD MANPAGE              29 November 1993                       1

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

                         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.

           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.

    BSD MANPAGE              29 November 1993                       2

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

           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.

           o      The character L specifying that a following  e,  E,
                  f,  g, or G conversion corresponds to a long double
                  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 con-
                  versions.  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.

           DOU    The long int argument is converted to signed  deci-
                  mal, unsigned octal, or unsigned decimal, as if the
                  format had been ld, lo, or lu respectively.   These
                  conversion  characters  are  deprecated,  and  will
                  eventually disappear.

           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

    BSD MANPAGE              29 November 1993                       3

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

                  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  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:

    BSD MANPAGE              29 November 1993                       4

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

                  #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, scanf,

###

###

###

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

    BUGS
           Some floating point conversions under Linux  cause  memory
           leaks.

           The conversion formats %D, %O, and %U are not standard and
           are provided only for backward compatibility.   These  may
           not be provided under Linux.

           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 other nonsensical combinations  such  as
           %Ld,   are  not  standard;  such  combinations  should  be
           avoided.

           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.

    BSD MANPAGE              29 November 1993                       5

Top | Master Index | Keywords | Functions

This manual page was brought to you by mjl_man V-2.0