UMBC CS 201, Spring 02
printf(1) printf(1)
NAME
printf - print formatted output
SYNOPSIS
printf format [arg . . .]
DESCRIPTION
The printf command converts, formats, and
prints its args under control of the format.
It fully supports conversion specifications
for strings (%s descriptor); however, the
results are undefined for the other conversion
specifications supported by printf(3S).
format a character string that contains
three types of objects: 1) plain
characters, which are simply copied
to the output stream; 2) conversion
specifications, each of which
results in fetching zero or more
args; and 3) C-language escape
sequences, which are translated into
the corresponding characters.
arg string(s) to be printed under the
control of format. The results are
undefined if there are insufficient
args for the format. If the format
is exhausted while args remain, the
excess args are simply ignored.
Each conversion specification is introduced by
the character %. After the %, the following
appear in sequence:
An optional field, consisting of a
decimal digit string followed by a $,
specifying the next arg to be converted.
If this field is not provided, the arg
following the last arg converted is used.
An optional decimal digit string
specifying a minimum field width.
If the converted value has fewer
characters than the field width, it is
padded on the left (or right, if the
left-adjustment flag `-' has been given)
to the field width. The padding is with
blanks unless the field width digit
string starts with a zero, in which case
the padding is with zeros.
An optional precision that gives the
maximum number of characters to
be printed from a string in %s
conversion. The precision takes the form
of a period (.) followed by a decimal
digit string; a null digit string is
treated as zero (nothing is printed).
Padding specified by the precision
overrides the padding specified by the
field width. That is, if precision is
specified, its value is used to control
the number of characters printed.
A field width or precision or both may be
indicated by an asterisk (*) instead of a
digit string. In this case, an integer
arg supplies the field width or
precision. The arg that is actually
converted is not fetched until the
conversion letter is seen, so the args
specifying field width or precision must
appear before the arg (if any) to be
converted. A negative field width
argument is taken as a `-'
(left-adjustment) flag followed by a
positive field width. If the precision
argument is negative, it is changed to
zero (nothing is printed). In no case
does a non-existent or small field width
cause truncation of a field; if the
result of a conversion is wider than the
field width, the field is simply expanded
to contain the conversion result.
The conversion characters and their meanings
are:
%s The arg is taken to be a string and
characters from the string are printed
until a null character (\0) is
encountered or the number of characters
indicated by the precision specification
is reached. If the precision is missing,
it is taken to be infinite, so all
characters up to the first null character
are printed. A null value for arg yields
undefined results.
%% Print a %; no argument is converted.
EXAMPLES
The command
printf '%s %s %s\n' Good Morning World
results in the output:
Good Morning World
The following command produces the same output.
printf '%2$s %s %1$s\n' World Good Morning
Here is an example that prints the first 6
characters of $PATH left-
adjusted in a 10-character field:
printf 'First 6 chars of %s are %-10.6s.\n' $PATH $PATH
If $PATH has the value /usr/bin:/usr/local/bin, then the above command
would print the following output:
First 6 chars of /usr/bin:/usr/local/bin are /usr/b .
SEE ALSO
printf(3S)
printf(3S) printf(3S)
NAME
printf, fprintf, sprintf - print formatted
output
SYNOPSIS
#include
int printf(const char *format, .../* args */);
int fprintf(FILE *strm, const char *format, .../* args */);
int sprintf(char *s, const char *format, .../* args */);
DESCRIPTION
printf places output on the standard output
stream stdout.
fprintf places output on strm.
sprintf places output, followed by a null
character (\0), in consecutive bytes starting
at s. It is the user's responsibility to
ensure that enough storage is available.
Each function returns the number of characters
transmitted (not including the terminating
null character in the case of sprintf) or a
negative value if an output error was
encountered.
Each of these functions converts, formats,
and prints its args under control of the
format. The results are undefined if there
are insufficient arguments for the format.
If the format is exhausted while arguments
remain, the excess arguments are simply
ignored. The format is a character string
that contains two types of objects defined
below:
1. plain characters that are simply
copied to the output stream;
2. conversion specifications.
All forms of the printf functions allow for
the insertion of a language- dependent
decimal-point character. The decimal-point
character is defined by the program's locale
(category LC_NUMERIC). In the "C" locale, or
in a locale where the decimal-point character
is not defined, the decimal-point character
defaults to a period (.).
Each conversion specification is introduced by
the character %, and takes the following
general form and sequence:
%[posp$][flags][width][.precision][size]
fmt
posp$ An optional entry, consisting of one or
more decimal digits followed by a $ character,
specifying the number of the next arg to
access. The first arg (just after format) is
numbered 1. If this field is not specified,
the arg following the most recently used arg
will be used.
printf(3S) printf(3S)
flags Zero or more characters that modify the
meaning of the conversion specification. The
flag characters and their meanings are:
- The result of the conversion will
be left-justified within the
field. (It will be right-justified
if this flag is not specified.)
+ The result of a signed conversion
will always begin with a sign (+ or
-). (It will begin with a sign only
when a negative value is converted
if this flag is not specified.)
space
If the first character of a signed
conversion is not a sign, or if a
signed conversion results in no
characters, a space will be
prefixed to the result. If the
space and + flags both appear,the
space flag will be ignored.
# The value is to be converted to an
alternate form. For an o
conversion, it increases the
precision (if necessary) to force
the first digit of the result to
be a zero. For x (or X)
conversion, a nonzero result will
have 0x (or 0X) prefixed to it.
For e, E, f, g, and G conversions,
the result will always contain a
decimal-point character, even if no
digits follow it. (Normally, a
decimal point appears in the result
of these conversions only if a
digit follows it.) For g and G
conversions, trailing zeros will
not be removed from the result (as
they normally are). For c, d, i, s,
and u conversions, the flag has no
effect.
0 For d, i, o, u, x, X, e, E, f, g,
and G conversions, leading zeros
(following any indication of sign
or base) are used to pad to the
field width; no space padding is
performed. If the 0 and flags both
appear, the 0 flag will be ignored.
For d, i, o, u, x, and X
conversions, if a precision is
specified, the 0 flag will be
ignored. For other conversions,
the behavior is undefined.
width An optional entry that consists of
either one or more decimal digits, or an
asterisk (*), or an asterisk followed by
one or more decimal digits and a $. It
specifies the minimum field width: If
the converted value has fewer characters
than the field width, it will be padded
(with space by default) on the left or
right (see the above flags description)
to the field width.
.prec An optional entry that consists of a
period (.) followed by either zero or
more decimal digits, or an asterisk (*),
or an asterisk followed by one or more
decimal digits and a $. It specifies 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 the e, E,
and f conversions, the maximum number of
significant digits for the g and G
conversions, or the maximum number of
characters to be written from a string
for an s
conversion. For other conversions, the
behavior is undefined. If only a period
is specified, the precision is taken as
zero.
size An optional h, l (ell), ll (ell ell), or
L that specifies other than the default
argument type of int for d and i;
unsigned int for o, u, x, and X; pointer
to int for n; and double for e, E, f, g,
and G. If a size appears other than in
the following combinations, the behavior
is undefined.
h For n, the argument has type
pointer to short int; for d and
i, short int; and for o, u, x, and
X, unsigned short int. (For d, i,
o, u, x, and X, the argument will
have been promoted according to
the integral promotions, and its
value will be narrowed to short or
unsigned short before printing.)
l For n, the argument has type
pointer to long int; for d and i,
long int; and for o, u, x, and X,
unsigned long int.
ll For n, the argument has type
pointer to long long int; for d and
i, long long int; and for o, u, x,
and X, unsigned long long int.
L This flag has no effect in this
implementation.
fmt A conversion character (described below)
that indicates the type of conversion to
be applied.
When a width or .prec includes an asterisk
(*), an int arg supplies the width or
precision. When they do not include a $, the
arguments specifying a field width, or
precision, or both must appear (in that order)
before the argument (if any) to be converted.
If the conversion specification includes
posp$, the field width and precision may
include a $. The decimal digits that precede
the $ similarly specify the number of the arg
that contains the field width or precision.
(In this case, posp$ specifies the number of
the arg to convert.) A negative field width
argument is taken as a - flag followed by a
positive field width. If the precision
argument is negative, it will be taken as
zero.
When numbered argument specifications are
used, specifying the Nth argument requires
that all the leading arguments, from the first
to the (N-1)th, be specified at least once, in
a consistent manner, in the format string.
The conversion characters and their meanings
are:
d, i The integer arg is converted to
signed decimal. The precision
specifies the minimum number of
digits to appear; if the value
being converted can be represented
in fewer digits, it will be
expanded with leading zeros. The
default precision is 1. The
result of converting a zero value
with a precision of zero is no
characters.
o, u, x, X
The unsigned integer arg is
converted to unsigned octal (o),
unsigned decimal (u), or unsigned
hexadecimal notation (x and X). The
x conversion uses the letters abcdef
and the X conversion uses the
letters ABCDEF. The precision
specifies the minimum number of
digits to appear; if the value being
converted can be represented in
fewer digits, it will be expanded
with leading zeros. The default
precision is 1. The result of
converting a zero value with a
precision of zero is no characters.
f The floating arg is converted to
decimal notation in the style
[-]ddd.ddd, where the number of
digits after the decimal-point
character [see setlocale(3C)] 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.
e, E The floating arg is converted to the
style [-]d.ddde_dd, where there is
one digit before the decimal-point
character (which is nonzero if the
argument is nonzero) 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 character
will produce a number with E instead
of e introducing the exponent. The
exponent always contains at least
two digits. If the value is zero,
the exponent is zero.
g, G The floating arg is converted in
style f or e (or in style E in the
case of a G conversion character),
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)
will be used only if the exponent
resulting from the conversion is
less than -4 or greater than or
equal to the precision. Trailing
zeros are removed from the
fractional part of the result; a
decimal-point character appears only
if it is followed by a digit.
c The integer arg is converted to an
unsigned char, and the
resulting character is written.
C arg is interpreted as a wchar_t,
converted to a multi-byte sequence,
and the resulting byte(s)
are written.
s The arg is taken to be a pointer to
an array of characters. Characters
from the array are written up to
(but not including) a terminating
null character; if a precision is
specified, no more than that many
characters are written. If a
precision is not specified or is
greater than the size of the array,
the array must contain a terminating
null character. (A null pointer for
arg will yield undefined results.)
S The arg is taken to be a pointer to
an array of wide characters.
(wchar_t). Each character from the
array is converted to a multi-byte
sequence and the resulting byte(s)
are written. Conversion stops when
there is a null wide character in
the array. If a precision is
specified, no more than that many
characters are written. If a
precision is not specified or is
greater than the size of the array,
the array must contain a terminating
null character. (A null pointer for
arg will yield undefined results.)
p The arg is taken to be a pointer to
void. The value of the pointer is
converted to an
implementation-defined sequence of
printable characters, which matches
those read by the %p conversion of
the scanf function.
n The arg is taken to be a pointer to
an integer into which is written the
number of characters written so far
by this call to printf, fprintf, or
sprintf. No argument is converted.
% Print a %; no argument is converted.
The complete specification must be
simply %%.
If the form of the conversion specification
does not match any of the above, the results of
the conversion are undefined. Similarly, the
results are undefined if there are insufficient
args for the format. If the format is exhausted
while args remain, the excess args are ignored.
If a floating-point value is the internal
representation for infinity, the output is [_]inf,
where inf is either inf or INF, depending on
whether the conversion character is lowercase or
uppercase. Printing of the sign follows the rules
described above.
If a floating-point value is the internal
representation for ``not-a-number,'' the output is
[_]nan0xm. Depending on the conversion character,
nan is either nan or NAN. Additionally, 0xm
represents the most significant part of the
mantissa. Again depending on the conversion
character, x will be x or X, and m will use the
letters abcdef or ABCDEF. Printing of the sign
follows the rules described above.
In no case does a nonexistent or small field
width cause truncation of a field; if the result
of a conversion is wider than the field width, the
field is expanded to contain the conversion result.
Characters generated by printf and fprintf are
printed as if the putc routine had been called
repeatedly.
EXAMPLES
To print a date and time in the form ``Sunday,
July 3, 10:02,'' where weekday and month are
pointers to null-terminated strings:
printf("%s, %s %i, %d:%.2d",
weekday, month, day, hour, min);
To print pi to 5 decimal places:
printf("pi = %.5f", 4 * atan(1.0));
The following two calls to printf both produce
the same result of
10 10 00300 10:
printf("%d %1$d %.*d %1$d", 10, 5, 300);
printf("%d %1$d %3$.*2$d %1$d", 10, 5, 300);
SEE ALSO
exit(2), lseek(2), write(2), abort(3C),
ecvt(3C), setlocale(3C),
putc(3S), scanf(3S), stdio(3S).
DIAGNOSTICS
printf, fprintf, and sprintf return the number
of characters transmitted (not counting the
terminating null character for sprintf), or return
a negative value if an error was encountered.
[an error occurred while processing this directive]
Thursday, 17-Jan-2002 13:52:06 EST