Content-type: text/html
Man page of printf
printf
Section: C Library Functions (3)
Index
Return to Main Contents
NAME
printf, fprintf, sprintf - Print formatted output
LIBRARY
Standard C Library (libc.so, 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]...);
STANDARDS
Interfaces documented on this reference page conform to industry
standards as follows:
fprintf(), printf(), 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 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.
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 the 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 null character \0 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:
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 there are not enough items for format in the
value parameter 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:
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, 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.
Zero or more flags that modify the
meaning of the conversion specification. The flag 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 rather than the
one specified for monetary values. The result of using the ' flag
with conversions other than decimal is undefined.
Left align within the field the result of the conversion.
If you do not specify this flag, 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 flag, 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 + flags appear, the (space) flag 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 flag 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) flags both appear, the 0 flag is ignored.
For d, i, o u, x, and
X conversions, if a precision is specified, the 0 flag is
also ignored. 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 flag 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) value 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 in 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, or 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 or the S conversion.
-
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 had not been specified.
When variable ordering with the %digit$ format
is used, the * (asterisk) specification for
field width in 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 a 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 a 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.
One of the following characters to indicate the type of conversion to be
applied:
Accepts an integer (int) value 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 a leading character causes the field width value
to be padded with leading zeros.
Accepts an integer (int) 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 0 (zero) value with a precision
of 0 (zero) is a null string. Specifying a field width with
a 0 (zero) as a leading character causes the field width value to be padded
with leading zeros.
Accepts an integer (int) value 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 a
leading character causes the field width value to be padded with leading
zeros. An octal value for field width is not implied.
Accepts an integer (int) 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
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 a leading character causes the field width value
to be padded with leading zeros.
Accepts a float or double value
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
# flag 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 float or double value 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 # flag 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 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.
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 that the radix character always appears if
the # flag is specified).
The style used depends on the value converted. Style e (E,
if G is the flag used) results only if the exponent resulting
from the conversion is less than -4, or if the exponent is greater or equal
to the precision.
If the l qualifier is not present, accepts and prints an
integer (int) value converted to an
unsigned char.
-
[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 wchar_t value, 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
char type. 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, then 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 an 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.
Accepts a pointer to an array of wchar_t type. 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, then 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, then 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 char type using %s conversion, an array
of 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:
+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 flag 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 . (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 sprintf() function
does not include the final '\0' (null) character.
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 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.
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.
There was no free space remaining 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.
RELATED INFORMATION
Functions:
conv(3),
ecvt(3),
putc(3),
scanf(3),
vprintf(3),
vwprintf(3),
wprintf(3),
wscanf(3)
delim off
Index
- NAME
-
- LIBRARY
-
- SYNOPSIS
-
- STANDARDS
-
- PARAMETERS
-
- DESCRIPTION
-
- Conversion Specifications
-
- RESTRICTIONS
-
- RETURN VALUES
-
- ERRORS
-
- RELATED INFORMATION
-
This document was created by
man2html,
using the manual pages.
Time: 02:41:13 GMT, October 02, 2010