libc.info: printf

Go forward to scanf
Go backward to siprintf
Go up to Stdio
Go to the top op libc

`printf', `fprintf', `saprintf', `sprintf', `snprintf'--format output

*Synopsis*
     #include <stdio.h>
     int printf(const char *FORMAT [, ARG, ...]);
     int fprintf(FILE *FD, const char *FORMAT [, ARG, ...]);
     int sprintf(char *STR, const char *FORMAT [, ARG, ...]);
     int saprintf(char **STRP, const char *FORMAT [, ARG, ...]);
     int snprintf(char *STR, size_t SIZE, const char *FORMAT [, ARG, ...]);
   *Description*
`printf' accepts a series of arguments, applies to each a format
specifier from `*FORMAT', and writes the formatted data to `stdout',
terminated with a null character.  The behavior of `printf' is
undefined if there are not enough arguments for the format.  `printf'
returns when it reaches the end of the format string.  If there are
more arguments than the format requires, excess arguments are ignored.
   `fprintf', `saprintf', `sprintf' and `snprintf' are identical to
`printf', other than the destination of the formatted output: `fprintf'
sends the output to a specified file FD, while `saprintf' stores the
output in a dynamically allocated buffer, while `sprintf' stores the
output in the specified char array STR and `snprintf' limits number of
characters written to STR to at most SIZE (including terminating `0').
For `sprintf' and `snprintf', the behavior is undefined if the output
`*STR' overlaps with one of the arguments. For `saprintf', STRP points
to a pointer to char which is filled in with the dynamically allocated
buffer.  FORMAT is a pointer to a charater string containing two types
of objects: ordinary characters (other than `%'), which are copied
unchanged to the output, and conversion specifications, each of which
is introduced by `%'. (To include `%' in the output, use `%%' in the
format string.) A conversion specification has the following form:
            %[FLAGS][WIDTH][.PREC][SIZE][TYPE]
   The fields of the conversion specification have the following
meanings:
   * FLAGS
     an optional sequence of characters which control output
     justification, numeric signs, decimal points, trailing zeroes, and
     octal and hex prefixes.  The flag characters are minus (`-'), plus
     (`+'), space ( ), zero (`0'), and sharp (`#').  They can appear in
     any combination.
    `-'
          The result of the conversion is left justified, and the right
          is padded with blanks.  If you do not use this flag, the
          result is right justified, and padded on the left.
    `+'
          The result of a signed conversion (as determined by TYPE)
          will always begin with a plus or minus sign.  (If you do not
          use this flag, positive values do not begin with a plus sign.)
    `" " (space)'
          If the first character of a signed conversion specification
          is not a sign, or if a signed conversion results in no
          characters, the result will begin with a space.  If the space
          ( ) flag and the plus (`+') flag both appear, the space flag
          is ignored.
    `0'
          If the TYPE character is `d', `i', `o', `u', `x', `X', `e',
          `E', `f', `g', or `G': leading zeroes, are used to pad the
          field width (following any indication of sign or base); no
          spaces are used for padding.  If the zero (`0') and minus
          (`-') flags both appear, the zero (`0') flag will be ignored.
          For `d', `i', `o', `u', `x', and `X' conversions, if a
          precision PREC is specified, the zero (`0') flag is ignored.
          Note that `0' is interpreted as a flag, not as the beginning
          of a field width.
    `#'
          The result is to be converted to an alternative form,
          according to the next character:
         `0'
               increases precision to force the first digit of the
               result to be a zero.
         `x'
               a non-zero result will have a `0x' prefix.
         `X'
               a non-zero result will have a `0X' prefix.
         `e, E or f'
               The result will always contain a decimal point even if
               no digits follow the point.  (Normally, a decimal point
               appears only if a digit follows it.)  Trailing zeroes
               are removed.
         `g or G'
               same as `e' or `E', but trailing zeroes are not removed.

`all others'
undefined.

   * WIDTH
     WIDTH is an optional minimum field width.  You can either specify
     it directly as a decimal integer, or indirectly by using instead
     an asterisk (`*'), in which case an `int' argument is used as the
     field width.  Negative field widths are not supported; if you
     attempt to specify a negative field width, it is interpreted as a
     minus (`-') flag followed by a positive field width.
   * PREC
     an optional field; if present, it is introduced with ``.'' (a
     period). This field gives the maximum number of characters to
     print in a conversion; the minimum number of digits of an integer
     to print, for conversions with TYPE `d', `i', `o', `u', `x', and
     `X'; the maximum number of significant digits, for the `g' and `G'
     conversions; or the number of digits to print after the decimal
     point, for `e', `E', and `f' conversions.  You can specify the
     precision either directly as a decimal integer or indirectly by
     using an asterisk (`*'), in which case an `int' argument is used
     as the precision.  Supplying a negative precision is equivalent to
     omitting the precision.  If only a period is specified the
     precision is zero.  If a precision appears with any other
     conversion TYPE than those listed here, the behavior is undefined.
   * SIZE
     `h', `l', and `L' are optional size characters which override the
     default way that `printf' interprets the data type of the
     corresponding argument.  `h' forces the following `d', `i', `o',
     `u', `x' or `X' conversion TYPE to apply to a `short' or `unsigned
     short'. `h' also forces a following `n' TYPE to apply to a pointer
     to a `short'. Similarily, an `l' forces the following `d', `i',
     `o', `u', `x' or `X' conversion TYPE to apply to a `long' or
     `unsigned long'.  `l' also forces a following `n' TYPE to apply to
     a pointer to a `long'. If an `h' or an `l' appears with another
     conversion specifier, the behavior is undefined.  `L' forces a
     following `e', `E', `f', `g' or `G' conversion TYPE to apply to a
     `long double' argument.  If `L' appears with any other conversion
     TYPE, the behavior is undefined.
   * TYPE
     TYPE specifies what kind of conversion `printf' performs.  Here is
     a table of these:
    `%'
          prints the percent character (`%')
    `c'
          prints ARG as single character
    `s'
          prints characters until precision is reached or a null
          terminator is encountered; takes a string pointer
    `d'
          prints a signed decimal integer; takes an `int' (same as `i')
    `i'
          prints a signed decimal integer; takes an `int' (same as `d')
    `o'
          prints a signed octal integer; takes an `int'
    `u'
          prints an unsigned decimal integer; takes an `int'
    `x'
          prints an unsigned hexadecimal integer (using `abcdef' as
          digits beyond `9'); takes an `int'
    `X'
          prints an unsigned hexadecimal integer (using `ABCDEF' as
          digits beyond `9'); takes an `int'
    `f'
          prints a signed value of the form `[-]9999.9999'; takes a
          floating point number
    `e'
          prints a signed	value of the form
          `[-]9.9999e[+|-]999'; takes a floating point number
    `E'
          prints the same way as `e', but using `E' to introduce the
          exponent; takes a floating point number
    `g'
          prints a signed value in either `f' or `e' form, based on
          given value and precision--trailing zeros and the decimal
          point are printed only if necessary; takes a floating point
          number
    `G'
          prints the same way as `g', but using `E' for the exponent if
          an exponent is needed; takes a floating point number
    `n'
          stores (in the same object) a count of the characters written;
          takes a pointer to `int'
    `p'
          prints a pointer in an implementation-defined format.  This
          implementation treats the pointer as an `unsigned long' (same
          as `Lu').
*Returns*
`sprintf' and `saprintf' return the number of bytes in the output
string, save that the concluding `NULL' is not counted.  `printf' and
`fprintf' return the number of characters transmitted.  If an error
occurs, `printf' and `fprintf' return `EOF' and `saprintf' returns -1.
No error returns occur for `sprintf'.
*Portability*
The  ANSI C standard specifies that implementations must support at
least formatted output of up to 509 characters.
   Supporting OS subroutines required: `close', `fstat', `isatty',
`lseek', `read', `sbrk', `write'.