printf
, fprintf
, asprintf
, sprintf
, snprintf
—format output#include <stdio.h> int printf(const char *format [, arg, ...]); int fprintf(FILE *fd, const char *format [, arg, ...]); int sprintf(char *str, const char *format [, arg, ...]); int asprintf(char **strp, const char *format [, arg, ...]); int snprintf(char *str, size_t size, const char *format [, arg, ...]);
Description
printf
accepts a series of arguments, applies to each a
format specifier from *
format, and writes the
formatted data to stdout
, terminated with a null character.
The behavior of printf
is undefined if there are not enough
arguments for the format.
printf
returns when it reaches the end of the format string.
If there are more arguments than the format requires, excess
arguments are ignored.
fprintf
, asprintf
, sprintf
and snprintf
are identical
to printf
, other than the destination of the formatted output:
fprintf
sends the output to a specified file fd, while
asprintf
stores the output in a dynamically allocated buffer,
while sprintf
stores the output in the specified char array
str and snprintf
limits number of characters written to
str to at most size (including terminating 0
). For
sprintf
and snprintf
, the behavior is undefined if the
output *
str overlaps with one of the arguments. For
asprintf
, strp points to a pointer to char which is filled
in with the dynamically allocated buffer. format is a pointer
to a charater string containing two types of objects: ordinary
characters (other than %
), which are copied unchanged to the
output, and conversion specifications, each of which is introduced
by %
. (To include %
in the output, use %%
in the format
string.) A conversion specification has the following form:
%[flags][width][.prec][size][type]
The fields of the conversion specification have the following meanings:
an optional sequence of characters which control
output justification, numeric signs, decimal points,
trailing zeroes, and octal and hex prefixes.
The flag characters are minus (-
), plus (+
),
space ( ), zero (0
), and sharp (#
). They can
appear in any combination.
-
+
" " (space)
+
) flag both appear,
the space flag is ignored.
0
d
, i
, o
, u
,
x
, X
, e
, E
, f
, g
, or G
: leading zeroes,
are used to pad the field width (following any indication of sign or
base); no spaces are used for padding. If the zero (0
) and
minus (-
) flags both appear, the zero (0
) flag will
be ignored. For d
, i
, o
, u
, x
, and X
conversions, if a precision prec is specified, the zero (0
)
flag is ignored.
Note that 0
is interpreted as a flag, not as the beginning
of a field width.
#
0
x
0x
prefix.
X
0X
prefix.
e, E or f
g or G
e
or E
, but trailing zeroes
are not removed.
all others
width is an optional minimum field width. You can either
specify it directly as a decimal integer, or indirectly by
using instead an asterisk (*
), in which case an int
argument is used as the field width. Negative field widths
are not supported; if you attempt to specify a negative field
width, it is interpreted as a minus (-
) flag followed by a
positive field width.
an optional field; if present, it is introduced with `.
'
(a period). This field gives the maximum number of
characters to print in a conversion; the minimum number of
digits of an integer to print, for conversions with type
d
, i
, o
, u
, x
, and X
; the maximum number of
significant digits, for the g
and G
conversions;
or the number of digits to print after the decimal
point, for e
, E
, and f
conversions. You can specify
the precision either directly as a decimal integer or
indirectly by using an asterisk (*
), in which case
an int
argument is used as the precision. Supplying a negative
precision is equivalent to omitting the precision.
If only a period is specified the precision is zero.
If a precision appears with any other conversion type
than those listed here, the behavior is undefined.
h
, l
, and L
are optional size characters which
override the default way that printf
interprets the
data type of the corresponding argument. h
forces
the following d
, i
, o
, u
, x
or X
conversion
type to apply to a short
or unsigned short
. h
also
forces a following n
type to apply to
a pointer to a short
. Similarily, an
l
forces the following d
, i
, o
, u
,
x
or X
conversion type to apply to a long
or
unsigned long
. l
also forces a following n
type to
apply to a pointer to a long
. l
with c
, s
is
equivalent to C
, S
respectively. If an h
or an l
appears with another conversion
specifier, the behavior is undefined. L
forces a
following e
, E
, f
, g
or G
conversion type to
apply to a long double
argument. If L
appears with
any other conversion type, the behavior is undefined.
type specifies what kind of conversion printf
performs.
Here is a table of these:
%
%
)
c
C
s
S
d
int
(same as i
)
i
int
(same as d
)
o
int
u
int
x
abcdef
as
digits beyond 9
); takes an int
X
ABCDEF
as
digits beyond 9
); takes an int
f
[-]9999.9999
; takes
a floating-point number
e
[-]9.9999e[+|-]999
; takes a
floating-point number
E
e
, but using E
to introduce the
exponent; takes a floating-point number
g
f
or e
form, based on given
value and precision—trailing zeros and the decimal point are
printed only if necessary; takes a floating-point number
G
g
, but using E
for the exponent if an
exponent is needed; takes a floating-point number
n
int
p
unsigned long
(same as Lu
).
Returns
sprintf
and asprintf
return the number of bytes in the output string,
save that the concluding NULL
is not counted.
printf
and fprintf
return the number of characters transmitted.
If an error occurs, printf
and fprintf
return EOF
and
asprintf
returns -1. No error returns occur for sprintf
.
Portability
The ANSI C standard specifies that implementations must
support at least formatted output of up to 509 characters.
Supporting OS subroutines required: close
, fstat
, isatty
,
lseek
, read
, sbrk
, write
.