Synopsis
int printf(const char *format,
...);
Description
printf writes to the standard output stream using putchar, under
control of the string pointed to by format that specifies how subsequent
arguments are converted for output.
If there are insufficient arguments for the format, the behavior is undefined.
If the format is exhausted while arguments remain, the excess arguments are
evaluated but are otherwise ignored.
printf returns the number of characters transmitted, or a negative value
if an output or encoding error occurred.
Formatted output control strings
The format is composed of zero or more directives: ordinary characters (not
‘%’, which are copied unchanged to the output
stream; and conversion specifications, each of which results in fetching zero
or more subsequent arguments, converting them, if applicable, according to the
corresponding conversion specifier, and then writing the result to the output
stream.
Each conversion specification is introduced by the character ‘%’.
After the ‘%’ the following appear in sequence:
- Zero or more flags (in any order) that modify the meaning of the
conversion specification.
- An optional minimum field width. If the converted value has fewer
characters than the field width, it is padded with spaces (by default) on
the left (or right, if the left adjustment flag has been given) to the field
width. The field width takes the form of an asterisk ‘*’ or a decimal
integer.
- An optional precision that gives the minimum number of digits to appear
for the ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, and ‘X’ conversions, the number
of digits to appear after the decimal-point character for ‘e’,
‘E’, ‘f’, and ‘F’ conversions, the maximum number of significant
digits for the ‘g’ and ‘G’ conversions, or the maximum number
of bytes to be written for ‘s’ conversions. The precision takes
the form of a period ‘.’ followed either by an asterisk ‘*’
or by an optional decimal integer; if only the period is specified,
the precision is taken as zero. If a precision appears with any other
conversion specifier, the behavior is undefined.
- An optional length modifier that specifies the size of the argument.
- A conversion specifier character that specifies the type of conversion
to be applied.
As noted above, a field width, or precision, or both, may be indicated by
an asterisk. In this case, an int argument supplies the field width or precision.
The arguments specifying field width, or precision, or both, must appear (in
that order) before the argument (if any) to be converted. A negative field width
argument is taken as a ‘-’ flag followed by a positive field width. A negative
precision argument is taken as if the precision were omitted.
Some library variants do not support width and precision specifiers
in order to reduce code and data space requirements; please ensure that you
have selected the correct library in the Printf Width/Precision Support
property of the project if you use these.
Flag characters
The flag characters and their meanings are:
- ‘-’
- The result of the conversion is left-justified within the field. The default,
if this flag is not specified, is that the result of the conversion is left-justified
within the field.
- ‘+’
- The result of a signed conversion always begins with a plus or minus
sign. The default, if this flag is not specified, is that it begins with a
sign only when a negative value is converted.
- space
- If the first character of a signed conversion is not a sign, or if a signed
conversion results in no characters, a space is prefixed to the result. If
the space and ‘+’ flags both appear, the space
flag is ignored.
- ‘#’
- The result is converted to an alternative form. For ‘o’
conversion, it increases the precision, if and only if necessary,
to force the first digit of the result to be a zero (if the value
and precision are both zero, a single ‘0’ is printed). For ‘x’
or ‘X’ conversion, a nonzero result has ‘0x’ or ‘0X’
prefixed to it. For ‘e’, ‘E’, ‘f’, ‘F’, ‘g’, and ‘G’
conversions, the result of converting a floating-point number always
contains a decimal-point character, even if no digits follow it.
(Normally, a decimal-point character appears in the result
of these conversions only if a digit follows it.) For ‘g’
and ‘F’ conversions, trailing zeros are not removed from the
result. As an extension, when used in ‘p’ conversion, the results
has ‘#’ prefixed to it. For other conversions, the behavior
is undefined.
- ‘0’
- For ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, ‘X’, ‘e’, ‘E’, ‘f’,
‘F’, ‘g’, and ‘G’ conversions, leading zeros (following any
indication of sign or base) are used to pad to the field width
rather than performing space padding, except when converting an
infinity or NaN. If the ‘0’ and ‘-’ flags both appear, the ‘0’
flag is ignored. For ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, and ‘X’
conversions, if a precision is specified, the ‘0’ flag is
ignored. For other conversions, the behavior is undefined.
Length modifiers
The length modifiers and their meanings are:
- ‘hh’
- Specifies that a following ‘d’, ‘i’,
‘o’, ‘u’,
‘x’, or ‘X’
conversion specifier applies to a signed char or unsigned char
argument (the argument will have been promoted according to the integer promotions,
but its value will be converted to signed char or unsigned char
before printing); or that a following ‘n’ conversion specifier applies
to a pointer to a signed char argument.
- ‘h’
- Specifies that a following ‘d’, ‘i’,
‘o’, ‘u’,
‘x’, or ‘X’
conversion specifier applies to a short int or unsigned short int
argument (the argument will have been promoted according to the integer
promotions, but its value is converted to short int or unsigned short int
before printing); or that a following ‘n’ conversion specifier applies
to a pointer to a short int argument.
- ‘l’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, or ‘X’
conversion specifier applies to a long int or unsigned long int
argument; that a following ‘n’ conversion specifier applies to a pointer
to a long int argument; or has no effect on a following ‘e’, ‘E’,
‘f’, ‘F’, ‘g’, or ‘G’ conversion specifier. Some
library variants do not support the ‘l’ length modifier in order to
reduce code and data space requirements; please ensure that you have
selected the correct library in the Printf Integer Support property
of the project if you use this length modifier.
- ‘ll’
- Specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, or ‘X’
conversion specifier applies to a long long int or unsigned long long int
argument; that a following ‘n’ conversion specifier applies to a
pointer to a long long int argument. Some library
variants do not support the ‘ll’ length modifier in order to reduce
code and data space requirements; please ensure that you have selected
the correct library in the Printf Integer Support property of the
project if you use this length modifier.
If a length modifier appears with any conversion specifier other than as specified
above, the behavior is undefined. Note that the C99 length modifiers ‘j’,
‘z’, ‘t’, and ‘L’ are not supported.
Conversion specifiers
The conversion specifiers and their meanings are:
- ‘d’, ‘i’
- The argument is converted to signed decimal in the style [-]dddd.
The precision specifies the minimum number of digits to appear; if the value
being converted can be represented in fewer digits, it is expanded with leading
spaces. The default precision is one. The result of converting a zero
value with a precision of zero is no characters.
- ‘o’, ‘u’, ‘x’, ‘X’
- The unsigned argument is converted to unsigned octal for ‘o’,
unsigned decimal for ‘u’, or unsigned hexadecimal notation for
‘x’ or ‘X’ in the style dddd the letters ‘abcdef’ are used
for ‘x’ conversion and the letters ‘ABCDEF’ for ‘X’ conversion.
The precision specifies the minimum number of digits to appear; if the
value being converted can be represented in fewer digits, it is expanded
with leading spaces. The default precision is one. The result of converting
a zero value with a precision of zero is no characters.
- ‘f’, ‘F’
- A double argument representing a floating-point number is converted to decimal
notation in the style [-]ddd.ddd, where the number of digits after
the decimal-point character is equal to the precision specification. If the
precision is missing, it is taken as 6; if the precision is zero and the ‘#’
flag is not specified, no decimal-point character appears. If a decimal-point
character appears, at least one digit appears before it. The value is rounded
to the appropriate number of digits. A double argument representing an infinity
is converted to ‘inf’. A double argument representing a NaN is converted to
‘nan’. The ‘F’ conversion specifier produces ‘INF’ or ‘NAN’ instead of
‘inf’ or ‘nan’, respectively. Some library variants do not
support the ‘f’ and ‘F’ conversion specifiers in order to reduce code and
data space requirements; please ensure that you have selected the correct library
in the Printf Floating Point Support property of the project if you use
these conversion specifiers.
- ‘e’, ‘E’
- A double argument representing a floating-point number is converted in the
style [-]d.ddde±dd, where there is one digit (which is
nonzero if the argument is nonzero) before the decimal-point character and the
number of digits after it is equal to the precision; if the precision is
missing, it is taken as 6; if the precision is zero and the ‘#’ flag is not
specified, no decimal-point character appears. The value is rounded to the
appropriate number of digits. The ‘E’ conversion specifier produces a number
with ‘E’ instead of ‘e’ introducing the exponent. The exponent always
contains at least two digits, and only as many more digits as necessary to
represent the exponent. If the value is zero, the exponent is zero. A double
argument representing an infinity is converted to ‘inf’. A double argument
representing a NaN is converted to ‘nan’. The ‘E’ conversion specifier
produces ‘INF’ or ‘NAN’ instead of ‘inf’ or ‘nan’, respectively.
Some library variants do not support the ‘f’ and ‘F’
conversion specifiers in order to reduce code and data space requirements;
please ensure that you have selected the correct library in the Printf Floating Point Support} property of the project if you use these conversion
specifiers.
- ‘g’, ‘G’
- A double argument representing a floating-point number is converted in
style ‘f’ or ‘e’ (or in style ‘F’ or ‘e’ in the case of a ‘G’
conversion specifier), with the precision specifying the number of
significant digits. If the precision is zero, it is taken as one. The style
used depends on the value converted; style ‘e’ (or ‘E’) is used only if
the exponent resulting from such a conversion is less than -4 or greater
than or equal to the precision. Trailing zeros are removed from the
fractional portion of the result unless the ‘#’ flag is specified; a
decimal-point character appears only if it is followed by a digit. A double
argument representing an infinity is converted to ‘inf’. A double
argument representing a NaN is converted to ‘nan’. The ‘G’ conversion
specifier produces ‘INF’ or ‘NAN’ instead of ‘inf’ or ‘nan’,
respectively. Some library variants do not support the ‘f’
and ‘F’ conversion specifiers in order to reduce code and data space
requirements; please ensure that you have selected the correct library in
the Printf Floating Point Support property of the project if you use
these conversion specifiers.
- ‘c’
- The argument is converted to an unsigned char, and the resulting
character is written.
- ‘s’
- The argument is be a pointer to the initial element of an array of character
type. Characters from the array are written up to (but not including) the
terminating null character. If the precision is specified, no more than that
many characters are written. If the precision is not specified or is greater
than the size of the array, the array must contain a null character.
- ‘p’
- The argument is a pointer to void. The value of the pointer is converted
in the same format as the ‘x’ conversion specifier
with a fixed precision of 2*sizeof(void *).
- ‘n’
- The argument is a pointer to a signed integer into which is written
the number of characters written to the output stream so far by the call to
the formatting function. No argument is converted, but one is consumed. If
the conversion specification includes any flags, a field width, or a precision,
the behavior is undefined.
- ‘%’
- A ‘%’ character is written. No argument is converted.
Note that the C99 width modifier ‘l’ used in conjunction with the ‘c’ and ‘s’
conversion specifiers is not supported and nor are the conversion specifiers
‘a’ and ‘A’.