 |
Index for
Section 3 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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 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.
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.
n 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:
printf()
Converts, formats, and writes its value parameters, under control of
the format parameter, to the standard output stream stdout.
fprintf()
Converts, formats, and writes its value parameters, under control of
the format parameter, to the output stream specified by the stream
parameter.
sprintf()
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.
snprintf()
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 % (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.
(space)
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.
0 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:
d or i
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.
u 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.
o 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.
x, X
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.
f 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.
e or E
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).
g or G
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.
c 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.
C 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.
s 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 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 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.
S 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.
p 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).
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.
% 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 floating-point values as
follows:
Quiet NaNi:
+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.
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
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 developing 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:
[EAGAIN]
The O_NONBLOCK option 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.
[EILSEQ]
An invalid wide-character was detected.
[EINTR]
The read operation was interrupted by a signal that was caught, and no
data was transferred.
[EIO]
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.
[ENOSPC]
No free space remained 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.
SEE ALSO
Functions: conv(3), ecvt(3), putc(3), scanf(3), vprintf(3), vwprintf(3),
wprintf(3), wscanf(3)
|
Index for
Section 3 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|