NAME
printf, fprintf, sprintf - Prints formatted output
LIBRARY
Standard I/O Package (libc.a)
SYNOPSIS
#include <stdio.h>
int printf (
const char *format [ , value, ... ]);
int fprintf (
FILE *stream,
const char *format [ , value, ... ] );
int sprintf (
char *string,
const char *format [ , value, ... ] );
PARAMETERS
format Specifies a character string combining literal
characters with conversion specifications.
value Specifies the data to be converted according to
the format parameter.
stream Points to a FILE structure specifying an open
stream to which converted values will be written.
string Points to a character array in which the converted
values will be stored.
DESCRIPTION
The printf() function converts, formats, and writes its
value parameters, under control of the format parameter, to
the standard output stream stdout.
The fprintf() function converts, formats, and writes its
value parameters, under control of the format parameter, to
the output stream specified by its stream parameter.
The sprintf() function converts, formats, and stores its
value parameters, under control of the format parameter,
into consecutive bytes starting at the address specified by
the string parameter. The sprintf() function places a '\0'
(null character) at the end. You must ensure that enough
storage space is available to contain the formatted string.
The format parameter is a character string that contains two
types of objects:
o Literal characters, which are copied to the output
stream.
o Conversion specifications, each of which causes zero or
more items to be fetched from the value parameter list.
If there are not enough items for format in the value param-
eter list, the results are unpredictable. If more values
remain after the entire format has been processed, they are
ignored.
Conversion Specifications
Each conversion specification in the format parameter has
the following syntax:
o A % (percent) sign.
o Zero or more options, which modify the meaning of the
conversion specification. The option characters and
their meanings are:
- Left align within the field the result of the
conversion.
+ Begin the result of a signed conversion with
a sign (+ or -).
(space) Prefix a space character to the result if the
first character of a signed conversion is not
a sign. If both the (space) and + options
appear, the (space) option is ignored.
# Convert the value to an alternate form. For
c, C, d, i, s, S, and u conversions, the
option has no effect. For o conversion, it
increases the precision to force the first
digit of the result to be a 0 (zero). For x
and X conversions, a nonzero result has 0x or
0X prefixed to it. For e, E, f, g, and G
conversions, the result always contains a
decimal point, even if no digits follow it.
For g and G conversions, trailing zeros are
not removed from the result.
0 Pad to field width using leading zeros (fol-
lowing any indication of sign or base) for d,
i, o, u, x, X, e, E, f, g, and G conversions;
no space padding is performed. If the 0 and -
(dash) flags both appear, the 0 flag will be
ignored. For d, i, o u, x, and X conver-
sions, if a precision is specified, the 0
flag is also ignored. For other conversions,
the behavior is undefined.
o An optional decimal digit string that specifies the
minimum field width. If the converted value has fewer
characters than the field width, the field is padded on
the left to the length specified by the field width. If
the left-adjustment option is specified, the field is
padded on the right.
o An optional precision. The precision is a . (dot) fol-
lowed by a decimal digit string. If no precision is
given, it is treated as 0 (zero). The precision speci-
fies:
-- The minimum number of digits to appear for the d,
u, o, x, or X conversions.
-- The number of digits to appear after the decimal
point for the e, E, and f conversions.
-- The maximum number of significant digits for the g
and G conversions.
-- The maximum number of bytes to be printed from a
string in the s or the S conversion.
o An optional h, l, or L specifying that a following d,
i, u, o, x, or X conversion character applies to,
respectively, a long integer value, a short integer
value, or a double integer value. The h and l options
can also be used with the n conversion specifier to
indicate a pointer to a short int or long int argument,
respectively.
o A character that indicates the type of conversion to be
applied:
% Performs no conversion. Prints %.
d, i Accepts an integer value and converts it to
signed decimal notation. The precision speci-
fies 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. Speci-
fying a field width with a zero as a leading
character causes the field width value to be
padded with leading zeros.
u Accepts an integer value and converts it to
unsigned decimal notation. 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. Speci-
fying a field width with a zero as a leading
character causes the field width value to be
padded with leading zeros.
o Accepts an integer value and converts it to
unsigned octal notation. The precision speci-
fies 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.
Specifying a field width with a zero as a
leading character causes the field width
value to be padded with leading zeros. An
octal value for field width is not implied.
x, X Accepts an integer value and converts it to
unsigned hexadecimal notation. The letters
"abcdef" are used for the x conversion and
the letters "ABCDEF" are used for the 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. The default precision is 1. The result
of converting a zero value with a precision
of zero is a null string. Specifying a field
width with a zero as a leading character
causes the field width value to be padded
with leading zeros.
f Accepts a float or double value and converts
it to decimal notation in the format
[-]ddd.ddd. The number of digits after the
decimal point is equal to the precision
specification. If no precision is specified,
six digits are output. If the precision is
zero, no decimal point appears. If a decimal
point is output, at least one digit is output
before it. The value is rounded to the
appropriate number of digits.
e, E Accepts a float or double value and converts
it to the exponential form [-]d.ddde+/-dd.
There is one digit before the decimal point
and the number of digits after the decimal
point is equal to the precision specifica-
tion. If no precision is specified, six
digits are output. If the precision is zero,
no decimal point appears. The E conversion
character produces a number with E instead of
e before the exponent. The exponent always
contains at least two digits. If the value
is zero, the exponent is zero.
g, G Accepts a float or double value and converts
it in the style of the e, E, or f conversion
characters, with the precision specifying the
number of significant digits. Trailing zeros
are removed from the result. A decimal point
appears only if it is followed by a digit.
The style used depends on the value con-
verted. Style e (E, if G is the flag used)
results only if the exponent resulting from
the conversion is less than -4, or if it is
greater or equal to the precision.
c Accepts and prints an integer value converted
to an unsigned char.
C Accepts a wchar_t value, converts it to mul-
tibyte character, and prints it.
s Accepts a value as a string (character
pointer), and characters from the string are
printed until a ' ' (null character) is
encountered or the number of characters indi-
cated by the precision is reached. If no pre-
cision is specified, all characters up to the
first null character are printed. If the
string pointer value has a value of 0 (zero)
or null, the results are undefined.
S Accepts a pointer to an array of wchar_t
type. Wide characters from the array are
converted to multibyte characters and the
multibyte characters up to (but not includ-
ing) the NULL character are printed.
p Accepts a pointer to void. The value of the
pointer is converted to a sequence of print-
able characters, the same as unsigned hexade-
cimal (x).
n Accepts a pointer to an integer into which is
written the number of characters written to
the output stream so far by this call. No
argument is converted.
A field width or precision can be indicated by an * (aster-
isk) instead of a digit string. In this case, an integer
value parameter supplies the field width or precision. The
value parameter converted for output is not fetched until
the conversion letter is reached, so the parameters specify-
ing field width or precision must appear before the value
(if any) to be converted.
If the result of a conversion is wider than the field width,
the field is expanded to contain the converted result. No
truncation occurs. However, a small precision can cause
truncation on the right.
The e, E, f, and g formats represent the special floating-
point values as follows:
Quiet NaN +NaNQ or -NaNQ
Signaling NaN
+NaNS or -NaNS
+/-INF +INF or -INF
+/-0 +0 or -0
The representation of the plus sign depends on whether the +
or (space) formatting option is specified.
The printf() functions can handle a format string that
enables the system to process elements of the argument list
in variable order. In such a case, the normal conversion
character % (percent sign) is replaced by "%digit"$", where
digit is a decimal number in the range [1, NL_ARGMAX].
Conversion is then applied to the argument, rather than to
the next unused argument. This feature provides for the
definition of format strings in an order appropriate to
specific languages. When variable ordering is used, the *
(asterisk) specification for field width in precision is
replaced by "%digit"$". If the variable ordering feature is
used, it must be specified for all conversions.
The * (asterisk) specification for field width or precision
is not permitted with the variable order %digit$ format.
All forms of the printf() functions allow for the insertion
of a language-dependent radix character in the output
string. The radix character is defined by langinfo data in
the program's locale (category LC_NUMERIC). In the ``C''
locale, or in a locale where the radix character is not
defined, the radix character defaults to . (decimal point).
The st_ctime and st_mtime fields of the file are marked for
update between the successful execution of the printf() or
fprintf() functions and the next successful completion of a
call to the fflush() or fclose() functions on the same
stream, or a call to the exit() or abort() functions.
AES Support Level:
Full use
RETURN VALUES
Upon successful completion, each of these functions returns
the number of display characters in the output string rather
than the number of bytes in the string. Otherwise, a nega-
tive value is returned.
The value returned by the sprintf() function does not
include the final '\0' character.
ERRORS
The printf() or fprintf() functions fail if either the
stream is unbuffered, or the stream's buffer needed to be
flushed and the function call caused an underlying write()
or lseek() function to be invoked. In addition, if the
printf() or fprintf() function fails, errno may be set to
one of the following values:
[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' file size limit or the max-
imum file size.
[EINTR] The read operation was interrupted by a signal
which was caught, and no data was transferred.
[EIO] The implementation supports job control, the pro-
cess is a member of a background process group
attempting to write to its controlling terminal,
TOSTOP is set, the process is neither ignoring nor
blocking SIGTTOU and the process group of the pro-
cess is orphaned. This error may also be returned
under implementation-defined conditions.
[ENOSPC] There was no free space remaining on the device
containing the file.
[EPIPE] An attempt was made to write to a pipe or FIFO
that is not open for reading by any process. A
SIGPIPE signal will also be sent to the process.
RELATED INFORMATION
Functions: conv(3), ecvt(3), putc(3), scanf(3), wsprintf(3)
Acknowledgement and Disclaimer