printf(3S)printf(3S)NAMEprintf(), fprintf(), sprintf(), snprintf() - print formatted output
SYNOPSISDESCRIPTION
places output on the standard output stream stdout.
places output on the named output stream.
places "output", followed by the null character in consecutive bytes
starting at It is the user's responsibility to ensure that enough stor‐
age is available.
behaves like except that it limits the number of characters written to
the destination buffer to maxsize, including the terminating null char‐
acter.
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 where n
is a decimal integer in the range 1 through is defined in The construc‐
tion indicates that this conversion should be applied to the nth argu‐
ment, rather than to the next unused one.
An argument can be referenced by a specification more than once. The
two forms of introducing a conversion specification, and cannot be
mixed within a single format string. When numbered argument specifica‐
tions are used, specifying the Nth argument requires that all the lead‐
ing arguments, from the first to the (N-1)th, are specified in the for‐
mat string. The results of mixing numbered and unnumbered argument
specifications in a format string are undefined.
After the or the following appear in sequence:
1. Zero or more flags, which modify the meaning of the conver‐
sion 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,
described below).
3. A precision that gives the minimum number of digits to
appear for the or conversions, the number of digits to
appear after the radix character for the and conversions,
the maximum number of significant digits for the conver‐
sion, or the maximum number of bytes to be printed from a
string in the 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 specifica‐
tions:
· an optional specifying that a following or conver‐
sion character applies to a short integer arg
· an optional specifying that a following conversion
character applies to a pointer to a short integer
arg
· an optional specifying that a following or conver‐
sion 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 specifying that a following conversion
specifier applies to a pointer to a signed char
argument
· an optional specifying that a following or conver‐
sion wide-character applies to a type which is the
80-bit IEEE-754 double-extended type in the archi‐
tecture
· an optional specifying that a following or conver‐
sion specifier applies to an intmax_t or uintmax_t
argument
· an optional specifying that a following conversion
specifier applies to a pointer to an intmax_t argu‐
ment
· an optional (the letter "ell"), specifying that a
following or conversion character applies to a long
integer arg
· an optional specifying that a following conversion
character applies to a pointer to a long integer arg
· an optional specifying that a following or conver‐
sion character applies to a long double
· an optional specifying that a following or conver‐
sion character applies to a long long integer arg
· an optional specifying that a following or conver‐
sion specifier applies to a ptrdiff_t or the corre‐
sponding unsigned type argument
· an optional specifying that a following conversion
specifier applies to a pointer to a ptrdiff_t argu‐
ment
· an optional specifying that a following or conver‐
sion specifier applies to a size_t argument or the
corresponding signed integer type argument
· an optional specifying that a following conversion
specifier applies to a pointer to a size_t argument
arg.
For Itanium(R)-based systems if the optional decimal float‐
ing point feature is installed and enabled, the following
optional character specifications are allowed:
· an optional specifying that a following or conver‐
sion specifier applies to a argument.
· an optional specifying that a following or conver‐
sion specifier applies to a argument.
· an optional specifying that a following or conver‐
sion specifier applies to a argument.
5. An or before any other conversion character is ignored.
6. A conversion character that indicates the type of conver‐
sion 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 pre‐
cision, 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 preci‐
sion were omitted. Format strings containing conversion specifications
can also indicate a field width or precision by the sequence The n
indicates the position of an integer arg. With the 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 sep‐
arator character are determined by the "grouping" and
"thousands_sep" fields of the category respectively.
(See localedef(4)). For other conversions the behav‐
ior 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 and conversions, the flag has no effect. For con‐
version, it increases the precision to force the first
digit of the result to be a zero. For or conversion,
a nonzero result is prefixed by or For a conversion, a
nonzero result is prefixed by For and 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 and conversions, trailing zeros are
removed from the result (which they normally are).
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 and appear, the flag is ignored. For and conver‐
sions, if a precision is specified, the flag is
ignored.
The conversion characters and their meanings are:
The integer arg is converted to signed decimal and are iden‐
tical), unsigned octal decimal or hexadecimal
notation and respectively; the letters are used
for conversion and the letters for 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.
The double arg is converted to decimal notation in the style
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.
The double arg is converted in the style where 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 preci‐
sion is zero, no radix character appears. The
format code produces a number with instead of
introducing the exponent. The exponent always
contains at least two digits.
The double arg is printed in style or (or in style in the
case of a format code), with the precision speci‐
fying the number of significant digits. The
style used depends on the value converted: style
is used only if the exponent resulting from the
conversion is less than 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.
For Itanium(R)-based systems only.
The double arg is converted in the style where 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
15 for and 28 for (which is sufficient for an
exact representation of the value). If the pre‐
cision is 0, no radix character appears. The
letters are used for conversion and the letters
for conversion. The conversion specifier pro‐
duces a number with and instead of and The expo‐
nent 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.
For Itanium(R)-based systems if the optional dec‐
imal floating point feature is installed and
enabled, then for an or specifier, if an or modi‐
fier is present and the precision is missing,
then for a decimal floating type argument repre‐
sented with an integral coefficient c and quantum
exponent q, where n is the number of digits in
the coefficient c:
· If 0 >= q >= -(n+5), use style formatting
with formatting precision equal to -q.
· Otherwise, use style formatting with for‐
matting precision equal to n - 1. Except
if then the digit-sequence in the expo‐
nent-part will have the value q (rather
than 0), and that the exponent is always
expressed with the minimum number of dig‐
its required to represent its value (the
exponent never contains a leading zero).
If the precision modifier is present and at least
as large as the precision of the decimal floating
type, the conversion is as if the precision modi‐
fier were missing.
If the precision modifier is present and less
than the precision of the decimal floating type,
the conversion first rounds the input, in the
type, according to the current rounding direction
for decimal floating-point operations. The
rounding occurs to the number of digits specified
by the precision modifier, then converts the
result as if the precision modifier were missing.
The integer arg is converted to an unsigned char, and the
resulting character is printed. If an (ell)
qualifier is present, the arg is converted to an
array of bytes representing the single wide char‐
acter according to the setting of 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.
only: If an (ell) qualifier is present, the argu‐
ment is converted as if by an conversion specifi‐
cation with no precision and an argument that
points to a two-element array of type the first
element of which contains the argument to the
conversion specification and the second element
contains a null wide-character.
Same as
The arg is taken to be a string (character pointer)
and characters from the string are printed until
a null character 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 (ell) qualifier is present, the argument
must be a pointer to an array of type Wide-char‐
acters from the array are converted to characters
(each as if by a call to the function, with the
conversion state described by an object initial‐
ized 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 con‐
tain 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.
Same as
The value of a pointer to void
arg is printed as a sequence of unsigned hexadec‐
imal numbers. The precision specifies the mini‐
mum number of digits to appear. If the value
being converted can be represented in fewer dig‐
its, 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.
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 and conversions will print for infinity and for both quiet and sig‐
naling values.
The and conversions will print for infinity and for both quiet and sig‐
naling values.
For and conversions (on Itanium(R)-based systems), the value is cor‐
rectly rounded to a hexadecimal floating point number with the given
precision.
The and conversions on Itanium(R)-based systems round according to the
specification in ISO/IEC C99: if the number of significant decimal dig‐
its is at most 36, then the result is correctly rounded.
Characters generated by and are printed as if had been called (see
putc(3S)).
For Itanium(R)-based systems if the optional decimal floating point
feature is installed and enabled, the behavior of the and specifiers
for decimal floating point numbers is the same as for
Application Usage
To use the functionality, the flag must be passed as a compiler option
or defined as a macro in source files.
After or is applied to a stream, the stream becomes byte-oriented (see
orientation(5)).
EXTERNAL INFLUENCES
Environment Variables
The 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 multi‐
byte 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 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 Support
Single byte character code sets are supported. Multibyte character
code sets are also supported as described in the category above.
RETURN VALUE
Each function returns the number of bytes transmitted (excluding the
null character in the case of or a negative value if an output error
was encountered.
By default, 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 max‐
size had been sufficiently large.
ERRORS
and fail if either the stream is unbuffered or stream's buffer needed
to be flushed causing an underlying call to be invoked (see write(2)),
and:
The flag 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 (see ulimit(2)).
A signal was caught during the
system call.
The process is in a background process group
and is attempting to write to its controlling terminal,
is set, the process is neither ignoring nor blocking the
signal, and the process group of the process is
orphaned.
There was no free space remaining on the device containing the file.
An attempt is made to write to a pipe or
FIFO that is not open for reading by any process. A
signal is also sent to the process.
The data obtained from the input stream does not form a valid wide
character.
Insufficient storage space is available.
Additional values can be set by the underlying function (see write(2)).
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:
To print Pi to 5 decimal places:
To create a language independent date-and-time printing routine write:
For American usage, format would point to the string:
and result in the output:
For German usage, the string:
results in the output:
WARNINGS
Notice that with the conversion character, an int arg is converted to
an unsigned char. Hence, whole multibyte characters cannot be printed
using a single conversion character.
A precision with the conversion character might result in the trunca‐
tion of a multibyte character.
Use of a conversion character which doesn't match the type of the cor‐
responding argument passed in will result in invalid data being
returned. For example, the modifying specifying that the following or
conversion character applies to a long long integer arg, is necessary
for proper results when the argument is a long long integer.
AUTHOR
and were developed by AT&T and HP.
SEE ALSOecvt(3C), ltostr(3C), setlocale(3C), putc(3S), scanf(3S), stdio(3S),
orientation(5), standards(5), thread_safety(5), glossary(9).
STANDARDS CONFORMANCEprintf(3S)
