"printf" writes formatted output to "stdout". The result of
"printf" is the number of characters written. If a write error occurs,
"printf" returns a negative number.
The output is formatted according to the "format" string. This string may
contain two kinds of objects:
Each placeholder starts with the character '%' and ends with one or two letters that
indicate what "type" of formatting is necessary. Between the '%' and the
"type" field may appear "modifiers", "width", and
"precision" fields. An ANSI placeholder has the form
Because '%' has a special meaning to "printf", you must use two of them to
stand for a literal per cent character. For example, you would use
Below we list the recognized "type" fields. Note that each "type"
requires that the output value associated with the placeholder have a particular data
type. Note also that the standard rules for passing arguments in a variable argument list
automatically convert "char" and "short" values to "int",
and "float" values to "double", so "char",
"short", and "float" arguments are not possible.
is relevant only for some output types. If "type" is 'o', all non-zero
values will have a leading 0; normally, octal output has no leading zero.
If "type" is 'x' or 'X', all non-zero values will have a leading 0x or 0X
respectively; normally, such prefixes are omitted.
If "type" is 'e', 'E' or 'f', "printf" will always print out a
decimal point (normally, the decimal point is omitted if the number has no fractional
part).
If "type" is '_f', trailing zeros are printed after a decimal point, even if
the fractional part of the number is zero.
If "type" is 'g' or 'G', "printf" will always print out a decimal
point and trailing zeros will not be removed; usually 'g' and 'G' remove trailing zeros.
If "type" is '_s' or '_S', trailing blanks are not trimmed.
If "type" is '_a', the output is enclosed in double quotes.
The Width Field
The width field is a non-negative decimal integer giving the minimum number of
characters to be printed. If the output value is shorter than the given width, it is
padded to the appropriate width by putting blanks on the right (or on the left, if the '-'
"modifier" character is specified).
With numeric placeholders, the number in the width field may have a leading 0. With
this, the output value will be expanded with zeros to give the number the specified width.
For example, with "%05d" the value -1 will be printed as "-0001".
The width field can also be the character '*', in which case "printf" will
take the next argument in the argument list and take that as the width value. For example,
printf("%*d",4,X);
prints the value of X with a width of 4. Note that the width value is obtained from the
argument list BEFORE the output value is obtained.
The width field specifies the MINIMUM number of characters to be output. If more
characters are needed, the output will be wider than width (unless the precision value
dictates otherwise).
The Precision Field
The precision field is a dot '.' followed by a non-negative decimal integer. Its
meaning depends on the "type" field as given below.
If the "type" is 'd', 'o', 'u', 'x' or 'X', the precision number is the
smallest number of digits that may appear in the output value. If necessary, the number
will be padded on the left with leading zeros. If the precision number is 0 or the field
is just a '.' with no number following, an output value of 0 will result in no characters
being printed.
If the "type" is 'e', 'E', or 'f', the precision number is the number of
digits printed after the decimal point. If the precision number is 0 or the field is just
a '.' with no number following, no decimal point is printed.
If the "type" is 'g' or 'G', the precision number is the maximum number of
significant digits to be printed. If no precision field is specified, six significant
digits are printed.
If the "type" is 's', the precision number gives the maximum number of
characters to be printed.
If the "type" is an 'h', 'l' or 'L' type, the precision field has the same
effect as it has for the type without the 'h', 'l' or 'L'.
If the "type" is "_e", "_E", "_f", or
"_F", the precision number is the number of digits printed after the decimal
point. If no precision is specified, the width will dictate the precision. If no width is
specified either, the value will be printed to full precision.
If the "type" is "_g" or "_G", the precision is the
maximum number of significant digits to be printed. If no precision field is specified,
all significant digits are printed.
The precision field can also be the character '*', in which case "printf"
will take the next argument in the argument list and take that as the precision value. For
example,
printf("%*.*f",8,3,Y);
prints the value of Y with a width of 8 and a precision of 3.
Fill Characters
As a non-ANSI extension, all placeholders may specify a "fill character" by
putting ",F" in front of the type designator (where F is any character). In any
situation where "printf" would normally fill out a field with blanks, the fill
character will be used instead. For example, with
printf("%5,#d",20);
the output would be
###20
The "#" after the comma is used as a fill character.
As with width and precision, the fill field can also be the character '*', in which
case "printf" will take the next argument in the argument list and take that as
the fill value. For example,
printf("%,*d",'*',20);
will fill with asterisks. If you want to fill with asterisks, you have to take this
approach.
Defaults
Below we list the defaults when width and/or precision fields are omitted.
"%1c" "%1.1d" "%11.6e" "%11.6E"
"%8.6f" "%1.6g" "%1.6G" "%1.1o"
"%0s" "%1.1x" "%1.1X" "%1.1ld"
"%1.1lo" "%1.1lx" "%1.1lX" "%6.6Le"
"%6.6LE" "%6.6Lf" "%6.6Lg" "%6.6LG"
Examples:
#include <stdio.h>
int i = 3, j = -1, k = 4;
char *s = "string";
float x = 3.14159265;
printf("j = %.*d, %.3s x = %10.*f",i,j,s,k,x);
/* prints: j = -001, str x = 3.1416 */
In the next examples, we use the letter 'b' to show where spaces are printed out. In
all cases, the value printed is the integer -1.
Format Output
%5d bbb-1
%05d -0001
%5.5d -00001 (precision requires 5 sig. digits)
%5,0d 000-1 (zero is fill character)
Notes:
The "printf" function does almost no validity checking on the format string.
Therefore, if you specify an invalid format, you will probably get invalid output without
any diagnostic message. You may also get more serious errors (e.g. memory faults).
Most users will find that "%g" is the best format for printing out single
floating point numbers, since it tries to choose the most readable format. For columns of
floating point numbers, "%_f" is usually better than "%f" because
"%_f" makes more of an effort to provide the precise width requested (or as
close as possible to that width).
See Also:
expl nsc lib fprintf
expl nsc lib scanf
expl nsc lib sprintf