printf(3)printf(3)NAME
printf, fprintf, snprintf, sprintf - Print formatted output
SYNOPSIS
#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]... );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards 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.
PARAMETERS
Specifies a character string combining literal characters with conver‐
sion 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 charac‐
ter array in which the converted values will be stored. Specifies the
size of the buffer referred to by string.
DESCRIPTION
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 parame‐
ters, 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
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 % (per‐
cent sign) is replaced by %digit$, where digit is a decimal num‐
ber 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 pre‐
cision 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 group‐
ing 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 conver‐
sions 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 con‐
version 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 con‐
versions, 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 conver‐
sions; 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 out‐
put 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-align‐
ment option followed by a positive field width. When variable
ordering with the %digit$ format is used, the * (asterisk) spec‐
ification 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 con‐
versions.
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 follow‐
ing integer or floating-point conversion specifier. An h fol‐
lowed 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 indi‐
cating 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 nota‐
tion. 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 con‐
verted can be represented in fewer digits, it is expanded with
leading zeros. The default precision is 1. The result of con‐
verting 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 nota‐
tion. 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 preci‐
sion is specified, six digits are output. If the precision is 0
(zero), no radix character appears (unless the # option is spec‐
ified). 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 dou‐
ble 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 spec‐
ification. 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, dou‐
ble, or long double and converts it in the style of the e, E, or
f conversion characters, with the precision specifying the num‐
ber 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 contain‐
ing a multibyte character, and prints the character. If a mini‐
mum field width is specified and the multibyte character occu‐
pies fewer bytes than the specified width, the multibyte charac‐
ter 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 charac‐
ter is encountered or the number of characters indicated by the
precision is reached. If no precision is specified, all charac‐
ters up to the first null character are printed. If the preci‐
sion 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-charac‐
ters from the array are converted to multibyte characters. Con‐
version 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-char‐
acter is converted) up to, but not including, the terminating
null wide-character. 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 preci‐
sion, 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-charac‐
ter; 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 con‐
verted 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 com‐
plete 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. How‐
ever, a small precision can cause truncation on the right.
The e, E, f, and g formats represent the special floating-point 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 lan‐
guage-dependent radix character in the output string. The radix charac‐
ter 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
RESTRICTIONS
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 develop‐
ing portable applications that run on multiple platforms, some of which
may supply locales that do use shift-state encoding.
RETURN VALUES
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).
ERRORS
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 opera‐
tion. 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 inter‐
rupted by a signal that was caught, and no data was transferred. The
implementation supports job control; the process is a member of a back‐
ground process group and is attempting to write to its controlling ter‐
minal; 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.
SEE ALSO
Functions: conv(3), ecvt(3), putc(3), scanf(3), vprintf(3),
vwprintf(3), wprintf(3), wscanf(3)printf(3)
