printf, fprintf, snprintf, sprintf - Print formatted output
#include <stdio.h>
int printf(
const char *format,
[,value]... ); int fprintf(
FILE *stream,
const char *format,
[,value]... ); int snprintf(
char *string,
size_t *n,
const char *format,
[,value]... ); int sprintf(
char *string,
const char *format,
[,value]... );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
fprintf(), printf(), snprintf(), sprintf(): ISO C, XPG4,
XPG4-UNIX
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies a character string combining literal characters
with conversion specifications. Specifies the data to be
converted according to the format parameter. Points to a
FILE structure specifying an open stream to which converted
values will be written. Points to a character
array in which the converted values will be stored. Specifies
the size of the buffer referred to by string.
The format parameter is a character string that contains
two types of objects: Literal characters, which are copied
to the output stream. Conversion specifications, each of
which causes zero or more items to be fetched from the
value parameter list.
If the value parameter list does not contain enough items
to process all of the conversion specifications in the
format parameter, the results are unpredictable. If more
value items remain after the entire format has been processed,
they are ignored.
Function descriptions: Converts, formats, and writes its
value parameters, under control of the format parameter,
to the standard output stream stdout. Converts, formats,
and writes its value parameters, under control of the format
parameter, to the output stream specified by the
stream parameter. 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 null
character (\0) at the end. You must ensure that enough
storage space is available to contain the formatted
string. Identical to sprintf() with the addition of the n
argument, which states the size of the buffer referred to
by string.
Conversion Specifications [Toc] [Back]
Each conversion specification in the format parameter has
the following syntax: A % (percent sign).
The printf() functions can handle a format string
that enables the system to process elements of the
parameter 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 from 1 to NL_ARGMAX. Conversion is
then applied to the specified argument instead of
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 or precision is replaced by *digit$. If
the variable ordering feature is used, it must be
specified for all conversions. Zero or more
options that modify the meaning of the conversion
specification. The option characters and their
meanings are as follows: Format the integer portion
of a decimal conversion (%i, %d, %u, %f, %g, %G)
with the thousands grouping character. The thousands
grouping character used in the result is the
one specified by the current locale for numeric
values, not the one specified for monetary values.
The result of using the ' option with conversions
other than decimal is undefined. Left align within
the field the result of the conversion. If you do
not specify this option, the converted value is
right aligned within the field. Begin the result
of a signed conversion with a sign (+ or -). If
you do not specify this option, the converted value
begins with a sign only when the value is negative.
Prefix a space character to the result if the first
character of a signed conversion is not a sign or
if a signed conversion results in no characters. If
both the (space) and + options appear, the (space)
option is ignored. Convert the value to an alternative
form. For o conversion, the function
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 radix character, even if no digits
follow it. For g and G conversions, trailing
zeros are not removed from the result. For c, C, d,
i, s, S, and u conversions, the option has no
effect. Pad to field width using leading zeros
(following 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)
options both appear, the 0 option is ignored. The 0
option is also ignored if a precision is specified
for d, i, o u, x, and X conversions. For other conversions,
the behavior is undefined. 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.
A field width can be indicated by an * (asterisk)
instead of a digit string. In this case, an integer
(int) *Vvalue parameter supplies the field width.
The value parameter converted for output is not
fetched until the conversion letter is reached, so
the parameters specifying field width or precision
must appear before the value (if any) to be converted.
If the corresponding parameter has a negative
value, it is treated as a - left-alignment
option followed by a positive field width. When
variable ordering with the %digit$ format is used,
the * (asterisk) specification for field width or
precision is replaced by *digit$. An optional precision.
The precision is a (dot) followed by a decimal
digit string. If no precision is given, the
decimal digit string is treated as 0 (zero). The
precision specifies: The minimum number of digits
to appear for the d, u, o, x, and X conversions.
The number of digits to appear after the radix
character 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 and S conversions.
A field precision can be indicated by an * (asterisk)
instead of a digit string. In this case, an
integer (int) value parameter supplies the field
precision. The value parameter converted for output
is not fetched until the conversion letter is
reached, so the parameters specifying field width
or precision must appear before the value (if any)
to be converted. If the value of the corresponding
parameter is negative, the value is treated as if
the precision was not specified. When variable
ordering with the %digit$ format is used, the *
(asterisk) specification for field width or precision
is replaced by *digit$. An optional h or l
indicating the size of the argument corresponding
to the following integer or floating-point conversion
specifier. An h followed by a d, i, o, u, x,
or X conversion specifier indicates that the argument
will be treated as a short int or unsigned
short int. An h followed by an n indicates that the
argument will be treated as a pointer to a short
int. An l followed by a d, i, o, u, x, or X conversion
specifier indicates that the argument will
be treated as a long int or unsigned long int. An l
followed by an n indicates that the argument will
be treated as a pointer to a long int.
[ISO C] An l followed by a c conversion specifier
applies to a wint_t argument. An l followed by an
s conversion specifier applies to a pointer to a
wchar_t argument. An optional L indicating that
the argument corresponding to the floating-point
conversion specifier will be treated as a long double.
One of the following characters that indicate
the type of conversion to be applied: Accepts a
value of type int and converts it to signed 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 0 (zero) value
with a precision of 0 (zero) is a null string.
Specifying a field width with a 0 (zero) as the
leading character causes the field width value to
be padded with leading zeros. Accepts a value of
type int 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 0 (zero) value with a precision
of 0 (zero) is a null string. Specifying a
field width with a 0 (zero) as the leading character
causes the field width value to be padded with
leading zeros. Accepts a value of type int and
converts it to unsigned octal 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 0 (zero) value with a precision of 0
(zero) is a null string. Specifying a field width
with a 0 (zero) as the leading character causes the
field width value to be padded with leading zeros.
An octal value for field width is not implied.
Accepts a value of type int 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 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 0 (zero) value with a precision of 0 (zero)
is a null string. Specifying a field width with a 0
(zero) as the leading character causes the field
width value to be padded with leading zeros.
Accepts a value of type float, double, or long double
and converts it to decimal notation in the format
[-]ddd.ddd. The number of digits after the
radix character is equal to the precision specification.
If no precision is specified, six digits
are output. If the precision is 0 (zero), no radix
character appears (unless the # option is specified).
If a radix character is output, at least one
digit is output before it. The value is rounded to
the appropriate number of digits. Accepts a value
of type float, double, or long double and converts
it to the exponential form [-]d.ddde+/-dd. There is
one digit before the radix character and the number
of digits after the radix character is equal to the
precision specification. If no precision is specified,
six digits are output. If the precision is 0
(zero), no radix character appears (unless the #
option is specified). 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 0 (zero), the exponent is 0
(zero). Accepts a value of type float, double, or
long double and converts it in the style of the e,
E, or f conversion characters, with the precision
specifying the number of significant digits. If an
explicit precision is zero, it is ignored (treated
as 1). Trailing zeros are removed from the result.
A radix character appears only if it is followed by
a digit (except the case in which the radix character
always appears if the # option is specified).
The style used depends on the value converted.
Style e (E, if the G option is used) results only
if the exponent resulting from the conversion is
less than -4 or if the exponent is greater than or
equal to the precision. If the l qualifier is not
present, accepts a value of type int, converts it
to an unsigned char, and prints it.
[ISO C] If the l qualifier is present, treats the
c argument as wint_t, converts it to a two-element
wchar_t array (the first element being the wint_t
argument and the second being a null wide-character),
and prints the converted value. Accepts a
value of type wchar_t, converts it to an array of
bytes containing a multibyte character, and prints
the character. If a minimum field width is specified
and the multibyte character occupies fewer
bytes than the specified width, the multibyte character
is padded with space characters to the specified
width. If the l qualifier is not present,
accepts a pointer to an array of type char. Bytes
from the array are printed until a null character
is encountered or the number of characters indicated
by the precision is reached. If no precision
is specified, all characters up to the first null
character are printed. If the precision is not
specified or is greater than the size of the array,
the array must be terminated by a null byte. If the
string pointer value has a value of 0 (zero) or
null, the results are undefined.
[ISO C] If the l qualifier is present, the s argument
is treated as a pointer to an array of type
wchar_t. Wide-characters from the array are converted
to multibyte characters. Conversion of each
wide-character is done as if by a call to the wcrtomb()
function (with the conversion state
described by a mbstate_t object initialized to zero
before the first wide-character is converted) up
to, but not including, the terminating null widecharacter.
The resulting bytes (including shift
sequences) are written up to, but not including,
the terminating null byte. If no precision is specified,
the wide-character array contains a null
wide-character. If, for a specified precision, the
function would need to access one wide-character
past the end of the array to equal the length of a
complete multibyte character sequence, the array
also contains a null wide-character; in other
words, the function does not output a partial
multibyte character sequence. Accepts a pointer to
an array of type wchar_t. Wide-characters from the
array are converted to an array of bytes containing
multibyte characters and the multibyte characters
up to, but not including, the null character are
printed. If a precision is specified, no more than
the number of bytes specified by the precision are
printed. If the precision is not specified or is
greater than the size of the array of bytes, the
array of wide-characters must be terminated by a
null wide-character. If a minimum field width is
specified and the array of bytes occupy fewer bytes
than the specified width, the array is padded with
space characters to the specified width. Accepts a
pointer to void. The value of the pointer is converted
to a sequence of printable characters, the
same as unsigned long hexadecimal (lx). 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.
Prints a % wide-character. No argument is converted.
The complete conversion specification is
%%.
If a conversion specification is invalid, results are
undefined.
If any argument is, or points to, a union or an aggregate
(except for an array of type char using %s conversion, an
array of type wchar_t using %s conversion, or a pointer
using %p conversion), the function's behavior is undefined.
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 floatingpoint
values as follows: +NaNQ or -NaNQ +NaNS or -NaNS
+INF or -INF +0 or -0
The representation of the + (plus sign) depends on whether
the + or (space) formatting option is specified.
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 POSIX
(C) locale or in a locale where the radix character is not
defined, the radix character defaults to a period (.).
The st_ctime and st_mtime fields of the file are marked
for update between the successful execution of the
printf() or fprintf() function and the next successful
completion of a call to one of the following: The fflush()
or fclose() function on the same stream The exit() or
abort() function
Currently, the Tru64 UNIX product does not include locales
that use shift-state encoding. Some sections of this reference
page refer to the mb_state object or describe
behavior that is dependent on shift-state encoding. This
information is included for your convenience in developing
portable applications that run on multiple platforms, some
of which may supply locales that do use shift-state encoding.
Upon successful completion, each of these functions
returns the number of bytes in the output string. Otherwise,
a negative value is returned.
The value returned by the snprintf() or sprintf() function
does not include the final null character (\0).
The printf() or fprintf() functions fail if either stream
is unbuffered or 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 is set to one of the following
values: The O_NONBLOCK option is set for the file
descriptor underlying stream and the process would be
delayed in the write operation. The file descriptor
underlying stream is not a valid file descriptor open for
writing. An attempt was made to write to a file that
exceeds the process's file size limit or the maximum file
size. An invalid wide-character was detected. The read
operation was interrupted by a signal that was caught, and
no data was transferred. The implementation supports job
control; the process is a member of a background process
group and is attempting to write to its controlling terminal;
TOSTOP is set; the process is neither ignoring nor
blocking SIGTTOU; and the process group of the process is
orphaned. This error may also be returned under implementation-defined
conditions. No free space remained on the
device containing the file. 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.
Functions: conv(3), ecvt(3), putc(3), scanf(3),
vprintf(3), vwprintf(3), wprintf(3), wscanf(3)
printf(3)
[ Back ] |
