12.12.2 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 (see 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

or

% [ param-no $] flags width . * [ param-no $] 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 parts of the format must be integers 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 NL_ARGMAX is the maximum value allowed for the specification of a 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 see 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. See Declaring Attributes of Functions in Using GNU CC, for more information.