 |
» |
|
|
|
NAMEprintf(), fprintf(), sprintf(), snprintf() — print formatted output SYNOPSIS#include <stdio.h>
int printf(const char *__restrict format, /* [arg,] */ ...);
int fprintf(FILE *__restrict stream, const char *__restrict format,
/* [arg,] */ ...);
int sprintf(char *__restrict s, const char *__restrict format,
/* [arg,] */ ...);
int snprintf(char *__restrict s, size_t maxsize,
const char *__restrict format, /* [arg,] */ ...); DESCRIPTIONprintf()
places output on the standard output stream
stdout. fprintf()
places output on the named output
stream. sprintf()
places "output", followed by the null character
(\0),
in consecutive bytes starting at
*s.
It is the user's responsibility to
ensure that enough storage is available. snprintf()
behaves like
sprintf(),
except that it limits the number of characters written to the
destination buffer to
maxsize,
including the terminating null character. Each function converts, formats, and prints its
args
under control of the
format.
format
is a character string containing two types of objects:
plain characters that are copied to the output stream,
and conversion specifications, each of which results in fetching
zero or more
args.
The results are undefined if there are insufficient
args
for the format.
If the format is exhausted while
args
remain, excess
args
are ignored. Each conversion specification is introduced by the character
%
or
%n$,
where
n
is a decimal integer in the range 1 through
{NL_ARGMAX}
(NL_ARGMAX
is defined in
<limits.h>).
The
%n$
construction indicates that this conversion should be applied to the
nth
argument, rather than to the next unused one. An argument can be referenced by a
%n$
specification more than once.
The two forms of introducing a conversion specification,
%
and
%n$,
cannot be mixed within a single
format
string.
When numbered
argument specifications are used, specifying the Nth argument
requires that all the leading arguments, from the first to the
(N-1)th, are specified in the format string.
The results of mixing numbered and unnumbered argument specifications
in a format string are undefined. After the
%
or
%n$,
the following appear in sequence:
- 1.
Zero or more
flags,
which modify the meaning of the conversion specification. - 2.
An optional string of decimal digits to specify a minimum
field width
in bytes.
If the converted value has fewer characters than the field width,
it is be padded on the left (or right,
if the left-adjustment flag
(-),
described below, has been given) to the field width.
If the field width is preceded by a zero,
the string is right adjusted with zero-padding on the left
(see the leading-zero flag,
0,
described below). - 3.
A
precision
that gives the minimum number of digits to appear for the
d,
i,
o,
u,
x,
or
X
conversions, the number of digits to appear after the radix character for the
a,
e,
and
f
conversions, the maximum number of significant digits for the
g
conversion, or the maximum number of bytes to be printed from a string in the
s
conversion.
The
precision
takes the form of a period
followed by a decimal digit string; a null digit string is treated as zero. - 4.
Zero or more of the following optional character specifications:
an optional
h,
specifying that a following
d,
i,
o,
u,
x,
or
X
conversion character applies to a short integer
arg an optional
h
specifying that a following
n
conversion character applies to a pointer to a short integer
arg an optional
hh
specifying 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 short or unsigned short before printing) an optional
hh
specifying that a following
n
conversion specifier applies to a pointer to a signed char argument an optional
hL
specifying that a following
a,
e,
f,
or
g
conversion wide-character applies to a type
extended
which is the 80-bit IEEE-754 double-extended type in the
Itanium®
architecture an optional
j
specifying that a following
d,
i,
o,
u,
x
or
X
conversion specifier applies to an intmax_t or uintmax_t argument an optional
j
specifying that a following
n
conversion specifier applies to a pointer to an intmax_t argument an optional
l
(the letter "ell"), specifying that a following
d,
i,
o,
u,
x,
or
X
conversion character applies to a long integer
arg an optional
l
specifying that a following
n
conversion character applies to a pointer to a long integer
arg an optional
L
specifying that a following
a,
A,
e,
E,
f,
F,
g,
or
G
conversion character applies to a long double an optional
ll
specifying that a following
d,
i,
o,
u,
x,
or
X
conversion character applies
to a long long integer arg an optional
t
specifying that a following
d,
i,
o,
u,
x
or
X
conversion specifier applies to a ptrdiff_t or the corresponding
unsigned type argument an optional
t
specifying that a following
n
conversion specifier applies to a pointer to a ptrdiff_t argument an optional
z
specifying that a following
d,
i,
o,
u,
x
or
X
conversion specifier applies to a size_t argument or the corresponding
signed integer type argument an optional
z
specifying that a following
n
conversion specifier applies to a pointer to a size_t argument
arg.
- 5.
An
h,
hh,
j,
l,
L,
ll,
t,
or
z
before any other conversion character is ignored. - 6.
A conversion character that indicates the type of conversion to be applied.
A field width or precision can 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, or both must appear in that order
before the
arg,
if any, to be converted.
A negative field width is taken as a
-
flag followed by a positive field width.
A negative precision is taken as if the precision were omitted.
Format strings containing
%n$
conversion specifications can also indicate a field width or precision
by the sequence
*n$.
The
n
indicates the position of an integer
arg.
With the
*n$
sequence, the
args
specifying field width or precision can appear before or after the
arg
to be converted. The flag characters and their meanings are:
- '
The integer portion of the result of a decimal conversion (%i, %d, %u, %f,
%F, %g, or %G) will be formatted with thousands' grouping characters.
Thousands' grouping and the separator character are determined by the
"grouping" and "thousands_sep" fields of the
LC_NUMERIC
category
respectively.
(See
localedef(4)).
For other conversions the behavior is undefined.
The nonmonetary grouping character is used. - -
The resulting conversion is left-justified within the field. - +
The resulting signed conversion always begins with a sign
(+
or
-). - blank
If the first character of a signed conversion is not a sign, a blank
is prefixed to the result.
This implies that if the blank and
+
flags both appear, the blank flag is ignored. - #
This flag specifies that the value is converted to an "alternate form".
For
c,
d,
i,
s,
n,
and
u
conversions, the flag has no effect.
For
o
conversion, it increases the precision to force
the first digit of the result to be a zero.
For
x
or
X
conversion, a nonzero result is prefixed by
0x
or
0X.
For a
p
conversion, a nonzero result is prefixed by
0x.
For
a,
A,
e,
E,
f,
F,
g,
and
G
conversions, the result always contains a radix character,
even if no digits follow the radix.
(Normally, a radix character
appears in the resulting conversions only if followed
by a digit).
For
g
and
G
conversions, trailing zeros are
not
removed from the result (which they normally are). - 0
Leading zeros (following any indication of sign or base)
are used to pad to the field width for all conversion characters.
No space padding is performed.
If both the
0
and
-
appear, the
0
flag is ignored.
For
d,
i,
o,
u,
p,
x,
and
X,
conversions, if a precision is specified, the
0
flag is ignored.
The conversion characters and their meanings are:
- d,i,o,u,x,X
The integer
arg
is converted to signed decimal
(d
and
i
are identical), unsigned octal
(o),
decimal
(u),
or hexadecimal notation
(x
and
X),
respectively; 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 zeros.
(For compatibility with older versions,
padding with leading zeros can alternatively be specified by
inserting a zero in front of the field width.
This does not imply an octal value for the field width).
The default precision is 1.
The result of converting a zero value
with a precision of zero is a null string. - f,F
The double
arg
is converted to decimal notation
in the style
[-]dddrddd,
where
r
is the radix character.
The number of digits after the radix character
is equal to the precision specification.
If the precision is missing, six digits are output.
If the precision is explicitly zero, no radix character appears. - e,E
The double
arg
is converted in the style
[-]drddde±dd,
where
r
is the radix character.
There is one digit before the radix character and
the number of digits after it is equal to the precision;
when the precision is missing, six digits are produced;
if the precision is zero, no radix character appears.
The
E
format code produces a number with
E
instead of
e
introducing the exponent.
The exponent always contains at least two digits. - g,G
The double
arg
is printed in style
f,
F,
or
e
(or in style
E
in the case of a
G
format code),
with the precision specifying the number of significant digits.
The style used depends on the value converted:
style
e
is 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 radix character appears only if it is followed by a digit. - a,A
For Itanium(R)-based systems only.
The double
arg
is converted in the style
[-]0xhrhhhp±d,
where
r
is the radix character.
There is one digit before the radix character and
the number of digits after it is equal to the
precision; when the precision is missing,
13 digits are produced for
double,
15 for
extended,
and 28 for
long double
(which is sufficient for an exact representation of the value);
if the precision is 0, no radix character appears.
The letters
abcdef
are used for
a
conversion and the letters
ABCDEF
for
A
conversion.
The
A
conversion specifier produces a number with
X
and
P
instead of
x
and
p.
The exponent always contains at least one digit,
and only as many more digits as necessary to represent the
decimal exponent of 2.
If the value is zero, the exponent is zero. - c
The integer
arg
is converted to an unsigned char,
and the resulting character is printed.
If an
l
(ell) qualifier is present, the
wchar_t
arg
is converted to an array of bytes representing the single wide character
according to the setting of
LC_CTYPE.
Resulting bytes are printed.
If the field width would otherwise cause the wide character to be split,
the wide character is printed and the field width is adjusted upward. _INCLUDE__STDC_A1_SOURCE
only:
If an
l
(ell) qualifier is present, the
wint_t
argument is converted as if by an
ls
conversion specification with no precision and an argument that points to
a two-element array of type
wchar_t,
the first element of which contains the
wint_t
argument to the
ls
conversion specification and the second element contains a null wide-character. - C
Same as
lc. - s
The
arg
is taken to be a string (character pointer)
and characters from the string are printed until a null character
(\0)
is encountered or the number of bytes 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. If an
l
(ell) qualifier is present, the argument must be a pointer to an array of
type
wchar_t.
Wide-characters from the array are converted to characters
(each as if by a call to the
wcrtomb()
function, with the conversion state described by an
mbstate_t
object initialized to zero before the first wide-character is converted) up to
and including a terminating null wide-character.
The resulting characters are written up to (but not including)
the terminating null character (byte). If no precision is specified,
the array must contain a null wide-character.
If a precision is specified,
no more than that many characters (bytes) are written
(including shift sequences, if any), and the array must contain
a null wide-character if, to equal the character sequence length given
by the precision, the function would need to access a wide-character one past
the end of the array.
In no case is a partial character written. - S
Same as
ls. - p
The value of a pointer to void
arg
is printed as a sequence of unsigned hexadecimal numbers.
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 zeros.
The default precision is 1.
The result of converting a zero value with a precision of zero
is a null string. - n
A pointer to an integer
arg
is expected.
This pointer is used to store the number of bytes
printed on the output stream so far by this call to the function.
No argument is converted. - %
Print a
%;
no argument is converted.
The entire conversion specification must be
%%.
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. The
a,
e,
f,
and
g
conversions will print
inf
for infinity and
nan
for both quiet and signaling
NaN
values. The
A,
E,
F,
and
G
conversions will print
INF
for infinity and
NAN
for both quiet and signaling
NaN
values. For
a
and
A
conversions (on Itanium(R)-based systems),
the value is correctly rounded to a hexadecimal
floating point number with the given precision. The
e,
E,
f,
F,
g,
and
G
conversions on Itanium(R)-based systems
round according to the specification in ISO/IEC C99:
if the number of significant decimal digits is
at most 36, then the result is correctly rounded. Characters generated by
printf()
and
fprintf()
are printed as if
putc()
had been called (see
putc(3S)). Application UsageTo use the
_INCLUDE__STDC_A1_SOURCE
functionality, the
_INCLUDE__STDC_A1_SOURCE
flag must be passed as a compiler option
or defined as a macro in source files. After
printf()
or
fprintf()
is applied to a stream, the stream becomes byte-oriented (see
orientation(5)). EXTERNAL INFLUENCESEnvironment VariablesThe
LC_CTYPE
category affects the following features:
Plain characters within format strings are interpreted as
single byte and/or multibyte characters. Field width is given in terms of bytes.
As characters are placed on the output stream,
they are interpreted as single byte or multibyte characters
and the field width is decremented by the length of the character. Precision is given in terms of bytes.
As characters are placed on the output stream,
they are interpreted as single byte or multibyte characters
and the precision is decremented by the length of the character. The return value is given in terms of bytes.
As characters are placed on the output stream,
they are interpreted as single byte or multibyte characters
and the byte count that makes up the return value
is incremented by the length of the character.
The
LC_NUMERIC
category determines the radix character used to print floating-point numbers,
and the thousands' grouping characters if the grouping flag
'
is on. International Code Set SupportSingle byte character code sets are supported.
Multibyte character code sets are also supported as described in the
LC_CTYPE
category above. RETURN VALUEEach function returns the number of bytes transmitted (excluding the
\0
null character in the case of
sprintf())
or a negative value if an output error was encountered. By default,
snprintf()
returns a negative value if
maxsize
is smaller than the number of characters formatted.
In the UNIX 2003 standards environment (see
standards(5))
it returns the
the number of bytes that would have been written to buffer
s,
excluding the terminating null byte,
if
maxsize
had been sufficiently large. ERRORSprintf(),
and
fprintf()
fail if either the
stream
is unbuffered or
stream's
buffer needed to be flushed causing an underlying
write()
call to be invoked (see
write(2)),
and:
- EAGAIN
The
O_NONBLOCK
flag is set for the file descriptor underlying
stream
and the process would be delayed in the write operation. - EBADF
The file descriptor underlying
stream
is not a valid file descriptor open for writing. - EFBIG
An attempt was made to write to a file that exceeds the process's file size
limit or the maximum file size (see
ulimit(2)). - EINTR
A signal was caught during the
write()
system call. - EIO
The process is in a background process group
and is attempting to write to its controlling terminal,
TOSTOP
is set, the process is neither ignoring nor blocking the
SIGTTOU
signal, and the process group of the process is orphaned. - ENOSPC
There was no free space remaining on the device containing the file. - EPIPE
An attempt is made to write to a pipe or
FIFO
that is not open for reading by any process.
A
SIGPIPE
signal is also sent to the process. - EILSEQ
The data obtained from the input stream does not form a valid wide character. - ENOMEM
Insufficient storage space is available.
Additional
errno
values can be set by the underlying
write()
function (see
write(2)). EXAMPLESTo 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 %d, %d:%.2d", weekday, month, day, hour, min); To print
Pi
to 5 decimal places:
printf("Pi = %.5f", 4 * atan(1.0)); To create a language independent date-and-time printing routine write:
printf(format,weekday,month,day,hour,min,2,2); For American usage,
format
would point to the string:
"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d" and result in the output:
For German usage, the string:
"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d" results in the output:
WARNINGSNotice that with the
c
conversion character, an int
arg
is converted to an unsigned char.
Hence, whole multibyte characters cannot be printed using a single
c
conversion character. A precision with the
s
conversion character might result in the truncation of a multibyte character. Use of a conversion character which doesn't match the type of the
corresponding argument passed in will result in invalid data
being returned.
For example, the modifying
ll,
specifying that the following
d,
i,
o,
u,
x,
or
X
conversion character applies to a long long integer arg, is necessary for
proper results when the argument is a long long integer. AUTHORprintf(),
fprintf(),
and
sprintf()
were developed by AT&T and HP. STANDARDS CONFORMANCEprintf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C fprintf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C sprintf(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C |
Printable version
