GNU Info

(libc.info)Output Conversion Syntax

---

Next: Table of Output Conversions Prev: Formatted Output Basics Up: Formatted Output

---

Enter node , (file) or (file)node

Output Conversion Syntax
------------------------

   This section provides details about the precise syntax of conversion
specifications that can appear in a `printf' template string.

   Characters in the template string that are not part of a conversion
specification are printed as-is to the output stream.  Multibyte
character sequences (Note: Character Set Handling) are permitted in a
template string.

   The conversion specifications in a `printf' template string have the
general form:

     % [ PARAM-NO $] FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION

   For example, in the conversion specifier `%-10.8ld', the `-' is a
flag, `10' specifies the field width, the precision is `8', the letter
`l' is a type modifier, and `d' specifies the conversion style.  (This
particular type specifier says to print a `long int' argument in
decimal notation, with a minimum of 8 digits left-justified in a field
at least 10 characters wide.)

   In more detail, output conversion specifications consist of an
initial `%' character followed in sequence by:

   * An optional specification of the parameter used for this format.
     Normally the parameters to the `printf' function are assigned to
     the formats in the order of appearance in the format string.  But
     in some situations (such as message translation) this is not
     desirable and this extension allows an explicit parameter to be
     specified.

     The PARAM-NO part of the format must be an integer in the range of
     1 to the maximum number of arguments present to the function call.
     Some implementations limit this number to a certainly upper
     bound.  The exact limit can be retrieved by the following constant.

      - Macro: NL_ARGMAX
          The value of `ARGMAX' is the maximum value allowed for the
          specification of an positional parameter in a `printf' call.
          The actual value in effect at runtime can be retrieved by
          using `sysconf' using the `_SC_NL_ARGMAX' parameter Note:
          Sysconf Definition.

          Some system have a quite low limit such as 9 for System V
          systems.  The GNU C library has no real limit.

     If any of the formats has a specification for the parameter
     position all of them in the format string shall have one.
     Otherwise the behavior is undefined.

   * Zero or more "flag characters" that modify the normal behavior of
     the conversion specification.

   * An optional decimal integer specifying the "minimum field width".
     If the normal conversion produces fewer characters than this, the
     field is padded with spaces to the specified width.  This is a
     _minimum_ value; if the normal conversion produces more characters
     than this, the field is _not_ truncated.  Normally, the output is
     right-justified within the field.

     You can also specify a field width of `*'.  This means that the
     next argument in the argument list (before the actual value to be
     printed) is used as the field width.  The value must be an `int'.
     If the value is negative, this means to set the `-' flag (see
     below) and to use the absolute value as the field width.

   * An optional "precision" to specify the number of digits to be
     written for the numeric conversions.  If the precision is
     specified, it consists of a period (`.') followed optionally by a
     decimal integer (which defaults to zero if omitted).

     You can also specify a precision of `*'.  This means that the next
     argument in the argument list (before the actual value to be
     printed) is used as the precision.  The value must be an `int',
     and is ignored if it is negative.  If you specify `*' for both the
     field width and precision, the field width argument precedes the
     precision argument.  Other C library versions may not recognize
     this syntax.

   * An optional "type modifier character", which is used to specify the
     data type of the corresponding argument if it differs from the
     default type.  (For example, the integer conversions assume a type
     of `int', but you can specify `h', `l', or `L' for other integer
     types.)

   * A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they use.

   With the `-Wformat' option, the GNU C compiler checks calls to
`printf' and related functions.  It examines the format string and
verifies that the correct number and types of arguments are supplied.
There is also a GNU C syntax to tell the compiler that a function you
write uses a `printf'-style format string.  Note: Declaring Attributes
of Functions, for more information.


automatically generated by info2www version 1.2.2.9