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 functions in the printf family produce 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.

       The functions vprintf, vfprintf, vsprintf, vsnprintf are equivalent  to
       the  functions printf, fprintf, 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. Consequently,
       the value of ap is undefined after the  call.  The  application  should
       call va_end(ap) itself afterwards.

       These  eight  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.

   Return value
       Upon successful return, these functions return the number of characters
       printed  (not  including  the  trailing  '\0'  used  to  end  output to
       strings).  The functions snprintf and vsnprintf do not write more  than
       size  bytes (including the trailing '\0').  If the output was truncated
       due to this limit then the return value is  the  number  of  characters
       (not  including the trailing '\0') 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.

   Format of the format string
       The  format  string  is a character string, beginning and ending in its
       initial shift state, if any.  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
       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);
       and
                   printf("%2$*1$d", width, num);
       are equivalent. The second style allows repeated references to the same
       argument. The C99 standard does not include the style using `$',  which
       comes  from  the  Single Unix Specification.  If the style using `$' is
       used, it must be used throughout for all conversions taking an argument
       and  all  width  and precision arguments, but it may be mixed with `%%'
       formats which do not consume an argument.  There may be no gaps in  the
       numbers  of  arguments specified using `$'; for example, if arguments 1
       and 3 are specified, argument 2 must also be specified somewhere in the
       format string.

       For  some  numeric  conversions  a radix character (`decimal point') or
       thousands' grouping  character  is  used.  The  actual  character  used
       depends on the LC_NUMERIC part of the locale. The POSIX locale uses `.'
       as radix character, and does not have a grouping character.  Thus,
                   printf("%'.2f", 1234567.89);
       results in `1234567.89' in the POSIX locale,  in  `1234567,89'  in  the
       nl_NL locale, and in `1.234.567,89' in the da_DK locale.

   The flag characters
       The character % is followed by zero or more of the following flags:

       #      The  value  should be converted to an ``alternate form''.  For o
              conversions, the first character of the output  string  is  made
              zero (by prefixing a 0 if it was not zero already).  For x and X
              conversions, a non-zero result has the string `0x' (or `0X'  for
              X  conversions) prepended to it.  For a, A, e, E, f, 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.  For other  conversions,  the
              result is undefined.

       0      The value should be zero padded.  For d, i, o, u, x, X, a, A, e,
              E, f, F, g, and G conversions, the converted value is padded  on
              the  left  with  zeros rather than blanks.  If the 0 and - flags
              both appear, the 0 flag is ignored.  If  a  precision  is  given
              with  a numeric conversion (d, i, o, u, x, and X), the 0 flag is
              ignored.  For other conversions, the behavior is undefined.

       -      The converted value is to be left adjusted on the  field  bound-
              ary.  (The default is right justification.) 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) A blank should be left before a  positive  number  (or
              empty string) produced by a signed conversion.
              grouped with thousands' grouping characters if the locale infor-
              mation indicates any.  Note that many  versions  of  gcc  cannot
              parse  this  option  and  will  issue a warning.  SUSv2 does not
              include %'F.

       glibc 2.2 adds one further flag character.

       I      For decimal integer conversion (i, d, u)  the  output  uses  the
              locale's  alternative output digits, if any (for example, Arabic
              digits).  However, it does not include  any  locale  definitions
              with such outdigits defined.

   The field width
       An  optional decimal digit string (with nonzero first digit) specifying
       a minimum 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).  Instead of a deci-
       mal  digit  string one may write `*' or `*m$' (for some decimal integer
       m) to specify that the field width is given in the next argument, or in
       the m-th argument, respectively, which must be of type int.  A negative
       field width is taken as a `-' flag followed by a positive field  width.
       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.

   The precision
       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 `.', or the precision is negative, the precision is  taken  to  be
       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 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.

   The length modifier
       Here, `integer conversion' stands for d, i, o, u, x, or X conversion.

       hh     A  following  integer conversion corresponds to a signed char or
              unsigned char argument, or a following n conversion  corresponds
              to a pointer to a signed char argument.

       h      A  following  integer  conversion  corresponds to a short int or
              unsigned short int argument, or a following n conversion  corre-
              sponds to a pointer to a short int argument.

       l      (ell)  A  following integer conversion corresponds to a long int
              or unsigned long int argument, or a following n conversion  cor-
              responds  to  a pointer to a long int argument, or a following c
              conversion corresponds to a wint_t argument, or  a  following  s
              conversion corresponds to a pointer to wchar_t argument.

       ll     (ell-ell).  A following integer conversion corresponds to a long
              long int or unsigned long long int argument, or  a  following  n
              uintmax_t argument.

       z      A  following  integer  conversion  corresponds  to  a  size_t or
              ssize_t argument. (Linux libc5 has Z with  this  meaning.  Don't
              use it.)

       t      A  following integer conversion corresponds to a ptrdiff_t argu-
              ment.

       The SUSv2 only knows about 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).

   The conversion specifier
       A character that specifies the type of conversion to be  applied.   The
       conversion specifiers and their meanings are:

       d,i    The  int  argument is converted to signed decimal notation.  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. The default precision is 1.  When
              0  is printed with an explicit precision 0, the output is empty.

       o,u,x,X
              The unsigned int argument is converted to  unsigned  octal  (o),
              unsigned  decimal  (u),  or unsigned hexadecimal (x and X) nota-
              tion.  The letters abcdef are used for x conversions;  the  let-
              ters  ABCDEF are used for X conversions.  The precision, if any,
              gives the minimum number of digits that must appear; if the con-
              verted  value  requires  fewer  digits, it is padded on the left
              with zeros. The default precision is 1.  When 0 is printed  with
              an explicit precision 0, the output is empty.

       e,E    The double argument is rounded and converted in the style

Linux Manpage                     2000-10-16                         printf(3)