The GNU C Programming Tutorial - Formatted output conversion specifiers

Node:Formatted output conversion specifiers, Previous:printf, Up:Formatted string output

Formatted output conversion specifiers

There are many different conversion specifiers that can be used for various data types. Conversion specifiers can become quite complex; for example, %-17.7ld specifies that printf should print the number left-justified (-), in a field at least seventeen characters wide (17), with a minimum of seven digits (.7), and that the number is a long integer (l) and should be printed in decimal notation (%d).

In this section, we will examine the basics of printf and its conversion specifiers. (For even more detail, Formatted Output.)

A conversion specifier begins with a percent sign, and ends with one of the following output conversion characters. The most basic conversion specifiers simply use a percent sign and one of these characters, such as %d to print an integer. (Note that characters in the template string that are not part of a conversion specifier are printed as-is.)

c: Print a single character.
d: Print an integer as a signed decimal number.
e: Print a floating-point number in exponential notation, using lower-case letters. The exponent always contains at least two digits. Example: 6.02e23.
E: Same as e, but uses upper-case letters. Example: 6.02E23.
f: Print a floating-point number in normal, fixed-point notation.
i: Same as d.
m: Print the string corresponding to the specified value of the system errno variable. (See Usual file name errors.) GNU systems only.
s: Print a string.
u: Print an unsigned integer.
x: Print an integer as an unsigned hexadecimal number, using lower-case letters.
X: Same as x, but uses upper-case letters.
%: Print a percent sign (%).

In between the percent sign (%) and the output conversion character, you can place some combination of the following modifiers. (Note that the percent sign conversion (%%) doesn't use arguments or modifiers.)

Zero or more flag characters, from the following table:

-
Left-justify the number in the field (right justification is the default). Can also be used for string and character conversions (%s and %c).
+
Always print a plus or minus sign to indicate whether the number is positive or negative. Valid for %d, %e, %E, and %i.
Space character
If the number does not start with a plus or minus sign, prefix it with a space character instead. This flag is ignored if the + flag is specified.
#
For %e, %E, and %f, forces the number to include a decimal point, even if no digits follow. For %x and %X, prefixes 0x or 0X, respectively.
'
Separate the digits of the integer part of the number into groups, using a locale-specific character. In the United States, for example, this will usually be a comma, so that one million will be rendered 1,000,000. GNU systems only.
0
Pad the field with zeroes instead of spaces; any sign or indication of base (such as 0x) will be printed before the zeroes. This flag is ignored if the - flag or a precision is specified.

In the example given above, %-17.7ld, the flag given is -.
An optional non-negative decimal integer specifying the minimum field width within which the conversion will be printed. If the conversion contains fewer characters, it will be padded with spaces (or zeroes, if the 0 flag was specified). If the conversion contains more characters, it will not be truncated, and will overflow the field. The output will be right-justified within the field, unless the - flag was specified. In the example given above, %-17.7ld, the field width is 17.
For numeric conversions, an optional precision that specifies the number of digits to be written. If it is specified, it consists of a dot character (.), followed by a non-negative decimal integer (which may be omitted, and defaults to zero if it is). In the example given above, %-17.7ld, the precision is .7. Leading zeroes are produced if necessary. If you don't specify a precision, the number is printed with as many digits as necessary (with a default of six digits after the decimal point). If you supply an argument of zero with and explicit precision of zero, printf will not print any characters. Specifying a precision for a string conversion (%s) indicates the maximum number of characters to write.
An optional type modifier character from the table below. This character specifies the data type of the argument if it is different from the default. In the example given above, %-17.7ld, the type modifier character is l; normally, the d output conversion character expects a data type of int, but the l specifies that a long int is being used instead.
The numeric conversions usually expect an argument of either type int, unsigned int, or double. (The %c conversion converts its argument to unsigned char.) For the integer conversions (%d and %i), char and short arguments are automatically converted to type int, and for the unsigned integer conversions (%u, %x, and %X), they are converted to type unsigned int. For the floating-point conversions (%e, %E, and %f), all float arguments are converted to type double. You can use one of the type modifiers from the table below to specify another type of argument.

l
Specifies that the argument is a long int (for %d and %i), or an unsigned long int (for %u, %x, and %X).
L
Specifies that the argument is a long double for the floating-point conversions (%e, %E, and %f). Same as ll, for integer conversions (%d and %i).
ll
Specifies that the argument is a long long int (for %d and %i). On systems that do not have extra-long integers, this has the same effect as l.
q
Same as ll; comes from calling extra-long integers "quad ints".
z
Same as Z, but GNU only, and deprecated.
Z
Specifies that the argument is of type size_t. (The size_t type is used to specify the sizes of blocks of memory, and many functions in this chapter use it.)

Make sure that your conversion specifiers use valid syntax; if they do not, if you do not supply enough arguments for all conversion specifiers, or if any arguments are of the wrong type, unpredictable results may follow. Supplying too many arguments is not a problem, however; the extra arguments are simply ignored.

Here is a code example that shows various uses of printf.

#include <stdio.h>
#include <errno.h>

int main()
{
  int my_integer = -42;
  unsigned int my_ui = 23;
  float my_float = 3.56;
  double my_double = 424242.171717;
  char my_char = 'w';
  char my_string[] = "Pardon me, may I borrow your nose?";

  printf ("Integer: %d\n", my_integer);
  printf ("Unsigned integer: %u\n", my_ui);

  printf ("The same, as hexadecimal: %#x %#x\n", my_integer, my_ui);

  printf ("Floating-point: %f\n", my_float);
  printf ("Double, exponential notation: %17.11e\n", my_double);

  printf ("Single character: %c\n", my_char);
  printf ("String: %s\n", my_string);

  errno = EACCES;
  printf ("errno string (EACCES): %m\n");

  return 0;
}

The code example above produces the following output on a GNU system:

Integer: -42
Unsigned integer: 23
The same, as hexadecimal: 0xffffffd6 0x17
Floating-point: 3.560000
Double, exponential notation: 4.24242171717e+05
Single character: w
String: Pardon me, may I borrow your nose?
errno string (EACCES): Permission denied