Purpose
Prints
formatted output.
Library
Standard
C Library (libc.a) or the Standard C Library with 128-Bit long
doubles (libc128.a)
Syntax
#include <stdio.h>
int printf (Format, [Value, ...])
const char *Format;
int fprintf (Stream, Format, [Value, ...])
FILE *Stream;
const char *Format;
int sprintf (String, Format, [Value, ...])
char *String;
const char *Format;
int snprintf (String, Number, Format, [Value, . . .])
char *String;
int Number;
const char *Format;
#include <stdarg.h>
int vprintf (Format, Value)
const char *Format;
va_list Value;
int vfprintf (Stream, Format, Value)
FILE *Stream;
const char *Format;
va_list Value;
int vsprintf (String, Format, Value)
char *String;
const char *Format;
va_list Value;
int vdprintf (fildes, Format, Value);
int fildes;
const char *Format;
va_list Value;
#include <wchar.h>
int vwsprintf (String, Format, Value)
wchar_t *String;
const char *Format;
va_list Value;
int wsprintf (String, Format, [Value, ...])
wchar_t *String;
const char *Format;
Description
The printf subroutine converts, formats,
and writes the Value parameter values, under control of the Format parameter,
to the standard output stream. The printf subroutine provides
conversion types to handle code points and wchar_t wide character
codes.
The fprintf subroutine
converts, formats, and writes the Value parameter values, under
control of the Format parameter, to the output stream specified
by the Stream parameter. This subroutine provides conversion
types to handle code points and wchar_t wide character codes.
The sprintf subroutine converts, formats,
and stores the Value parameter values, under control of the Format parameter,
into consecutive bytes, starting at the address specified by the String parameter.
The sprintf subroutine places a null character (\0) at the
end. You must ensure that enough storage space is available to contain
the formatted string. This subroutine provides conversion types to
handle code points and wchar_t wide character codes.
The snprintf subroutine
converts, formats, and stores the Value parameter values, under
control of the Format parameter, into consecutive bytes, starting
at the address specified by the String parameter. The snprintf subroutine
places a null character (\0) at the end. You must ensure that enough
storage space is available to contain the formatted string. This subroutine
provides conversion types to handle code points and wchar_t wide
character codes. The snprintf subroutine is identical to the sprintf subroutine
with the addition of the Number parameter, which states the
size of the buffer referred to by the String parameter.
The wsprintf subroutine converts, formats,
and stores the Value parameter values, under control of the Format parameter,
into consecutive wchar_t characters starting at the address
specified by the String parameter. The wsprintf subroutine
places a null character (\0) at the end. The calling process should
ensure that enough storage space is available to contain the formatted
string. The field width unit is specified as the number of wchar_t characters.
The wsprintf subroutine is the same as the printf subroutine,
except that the String parameter for the wsprintf subroutine
uses a string of wchar_t wide-character codes.
All of
the above subroutines work by calling the _doprnt subroutine,
using variable-length argument facilities of the varargs macros.
The vdprintf, vprintf, vfprintf, vsprintf,
and vwsprintf subroutines format and write varargs macros
parameter lists. These subroutines are the same as the drpintf, printf, fprintf, sprintf, snprintf,
and wsprintf subroutines, respectively, except that they are
not called with a variable number of parameters. Instead, they are
called with a parameter-list pointer as defined by the varargs macros.
Parameters
- Number
- Specifies the number of bytes in a string to be copied or transformed.
- Value
- Specifies 0 or more arguments that map directly to the objects
in the Format parameter.
- Stream
- Specifies the output stream.
- String
- Specifies the starting address.
- Format
- A character string that contains two types of objects:
- Plain characters, which
are copied to the output stream.
- Conversion specifications,
each of which causes 0 or more items to be retrieved from the Value parameter
list. In the case of the vprintf, vfprintf, vsprintf,
and vwsprintf subroutines, each conversion specification causes
0 or more items to be retrieved from the varargs macros parameter
lists.
If the Value parameter list does not contain enough
items for the Format parameter, the results are unpredictable.
If more parameters remain after the entire Format parameter
has been processed, the subroutine ignores them.
Each conversion
specification in the Format parameter has the following elements:
- A % (percent sign).
- 0 or more options, which
modify the meaning of the conversion specification. The option characters
and their meanings are:
- '
- Formats the integer portions resulting from i, d, u, f, g and G decimal
conversions with thousands_sep grouping characters. For other
conversions the behavior is undefined. This option uses the nonmonetary
grouping character.
- -
- Left-justifies the result of the conversion within the field.
- +
- Begins the result of a signed conversion with a + (plus sign)
or - (minus sign).
- space character
- Prefixes a space character to the result if the first character
of a signed conversion is not a sign. If both the space-character
and + option characters appear, the space-character option
is ignored.
- #
- Converts the value to an alternate form. For c, d, s,
and u conversions, the option has no effect. For o conversion,
it increases the precision to force the first digit of the result
to be a 0. For x and X conversions, a nonzero result
has a 0x or 0X prefix. For e, E, f, g,
and G conversions, the result always contains a decimal point,
even if no digits follow it. For g and G conversions,
trailing 0's are not removed from the result.
- 0
- Pads to the field width with leading 0's (following any indication
of sign or base) for d, i, o, u, x, X, e, E, f, g,
and G conversions; the field is not space-padded. If the 0 and - options
both appear, the 0 option is ignored. For d, i, o u, x,
and X conversions, if a precision is specified, the 0 option
is also ignored. If the 0 and ' options both appear,
grouping characters are inserted before the field is padded. For other
conversions, the results are unreliable.
- B
- Specifies a no-op character.
- N
- Specifies a no-op character.
- J
- Specifies a no-op character.
- 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-justify)
option is specified, the field is padded on the right.
- An optional precision.
The precision is a . (dot) followed by a decimal digit string.
If no precision is specified, the default value is 0. The precision
specifies the following limits:
- Minimum number of digits
to appear for the d, i, o, u, x,
or X conversions.
- Number of digits
to appear after the decimal point for the e, E, and f conversions.
- Maximum number of
significant digits for g and G conversions.
- Maximum number of
bytes to be printed from a string in s and S conversions.
- Maximum number of bytes,
converted from the wchar_t array, to be printed from the S conversions.
Only complete characters are printed.
- An optional l (lowercase L), ll (lowercase LL), h,
or L specifier indicates one of the following:
- An optional h specifying
that a subsequent d, i, u, o, x,
or X conversion specifier applies to a short int or unsigned
short int Value parameter (the parameter will have been
promoted according to the integral promotions, and its value will
be converted to a short int or unsigned short int before
printing).
- An optional h specifying
that a subsequent n conversion specifier applies to a pointer
to a short int parameter.
- An optional l (lowercase L)
specifying that a subsequent d, i, u, o, x,
or X conversion specifier applies to a long int or unsigned
long int parameter .
- An optional l (lowercase L)
specifying that a subsequent n conversion specifier applies
to a pointer to a long int parameter.
- An optional ll (lowercase LL)
specifying that a subsequent d, i, u, o, x,
or X conversion specifier applies to a long long int or unsigned
long long int parameter.
- An optional ll (lowercase LL)
specifying that a subsequent n conversion specifier applies
to a pointer to a long long int parameter.
- An optional L specifying
that a following e, E, f, g, or G conversion
specifier applies to a long double parameter. If linked with libc.a, long
double is the same as double (64bits). If linked with libc128.a and libc.a, long
double is 128 bits.
- An optional H, D, or DD specifier indicates
one of the following conversions:
- An optional H specifying that a following e, E, f, F, g,
or G conversion specifier applies to a _Decimal32 parameter.
- An optional D specifying that a following e, E, f, F, g,
or G conversion specifier applies to a _Decimal64 parameter.
- An optional DD specifying that a following e, E, f, F, g,
or G conversion specifier applies to a _Decimal128 parameter.
- An optional vl, lv, vh, hv or v specifier
indicates one of the following vector data type conversions:
- An optional v specifying that a following e, E, f, g, G, a,
or A conversion specifier applies to a vector
float parameter. It consumes one argument and interprets
the data as a series of four 4-byte floating point components.
- An optional v specifying that a following c, d, i, u, o, x,
or X conversion specifier applies to a vector
signed char, vector unsigned char,
or vector bool char parameter. It consumes
one argument and interprets the data as a series of sixteen 1-byte
components.
- An optional vl or lv specifying
that a following d, i, u, o, x,
or X conversion specifier applies to a vector
signed int, vector unsigned int,
or vector bool parameter. It consumes one
argument and interprets the data as a series of four 4-byte integer
components.
- An optional vh or hv specifying
that a following d, i, u, o, x,
or X conversion specifier applies to a vector
signed short or vector unsigned short parameter.
It consumes one argument and interprets the data as a series of eight
2-byte integer components.
- For any of the preceding specifiers, an optional separator character
can be specified immediately preceding the vector size specifier.
If no separator is specified, the default separator is a space unless
the conversion is c, in which case the default
separator is null. The set of supported optional separators are , (comma), ; (semicolon), : (colon),
and _ (underscore).
- The following characters
indicate the type of conversion to be applied:
- %
- Performs no conversion. Prints (%).
- d or i
- Accepts a Value parameter specifying an integer 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 0's. The default precision
is 1. The result of converting a value of 0 with a precision of 0
is a null string. Specifying a field width with a 0 as a leading character
causes the field-width value to be padded with leading 0's.
- u
- Accepts a Value parameter specifying an unsigned integer
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 0's.
The default precision is 1. The result of converting a value of 0
with a precision of 0 is a null string. Specifying a field width with
a 0 as a leading character causes the field-width value to be padded
with leading 0's.
- o
- Accepts a Value parameter specifying an unsigned integer
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 0's.
The default precision is 1. The result of converting a value of 0
with a precision of 0 is a null string. Specifying a field-width with
a 0 as a leading character causes the field width value to be padded
with leading 0's. An octal value for field width is not implied.
- x or X
- Accepts a Value parameter specifying an unsigned integer
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 of digits to appear. If the value being converted can be represented
in fewer digits, it is expanded with leading 0's. The default precision
is 1. The result of converting a value of 0 with a precision of 0
is a null string. Specifying a field width with a 0 as a leading character
causes the field-width value to be padded with leading 0's.
- f
- Accepts a Value parameter specifying a double and converts
it to decimal notation in the format [-]ddd.ddd.
The number of digits after the decimal point is equal to the precision
specification. If no precision is specified, six digits are output.
If the precision is 0, no decimal point appears.
- e or E
- Accepts a Value parameter specifying a double and converts
it to the exponential form [-]d.ddde+/-dd. One
digit exists before the decimal point, and the number of digits after
the decimal point is equal to the precision specification. The precision
specification can be in the range of 0-17 digits. If no precision
is specified, six digits are output. If the precision is 0, no decimal
point appears. The E conversion character produces a number
with E instead of e before the exponent. The exponent
always contains at least two digits.
- g or G
- Accepts a Value parameter specifying a double and converts
it in the style of the e, E, or f conversion
characters, with the precision specifying the number of significant
digits. Trailing 0's are removed from the result. A decimal point
appears only if it is followed by a digit. 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 it is greater or equal to the precision. If
an explicit precision is 0, it is taken as 1.
- c
- Accepts and prints a Value parameter specifying an integer
converted to an unsigned char data type.
- C
- Accepts and prints a Value parameter specifying a wchar_t wide
character code. The wchar_t wide character code specified by
the Value parameter is converted to an array of bytes representing
a character and that character is written; the Value parameter
is written without conversion when using the wsprintf subroutine.
- s
- Accepts a Value parameter as a string (character pointer),
and characters from the string are printed until a null character
(\0) is encountered or the number of bytes indicated by the precision
is reached. If no precision is specified, all bytes up to the first
null character are printed. If the string pointer specified by the Value parameter
has a null value, the results are unreliable.
- S
- Accepts a corresponding Value parameter as a pointer to
a wchar_t string. Characters from the string are printed (without
conversion) until a null character (\0) is encountered or the number
of wide characters indicated by the precision is reached. If no precision
is specified, all characters up to the first null character are printed.
If the string pointer specified by the Value parameter has
a value of null, the results are unreliable.
- p
- Accepts a pointer to void. The value of the pointer is converted
to a sequence of printable characters, the same as an unsigned hexadecimal
(x).
- n
- Accepts a pointer to an integer into which is written the number
of characters (wide-character codes in the case of the wsprintf subroutine)
written to the output stream by this call. No argument is converted.
-
A field width or precision
can be indicated by an * (asterisk) instead of a digit string. In
this case, an integer Value parameter supplies the field width
or precision. The Value parameter converted for output is not
retrieved 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 result of
a conversion is wider than the field width, the field is expanded
to contain the converted result and no truncation occurs. However,
a small field width or precision can cause truncation on the right.
The printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf,
or vwsprintf subroutine allows the insertion of a language-dependent
radix character in the output string. The radix character is defined
by language-specific data in the LC_NUMERIC category of the
program's locale. In the C locale, or in a locale where the radix
character is not defined, the radix character defaults to a . (dot).
After any of these subroutines runs successfully,
and before the next successful completion of a call to the fclose (fclose or fflush Subroutine) or fflush subroutine on
the same stream or to the exit (exit, atexit, unatexit, _exit, or _Exit Subroutine)
or abort (abort Subroutine) subroutine,
the st_ctime and st_mtime fields of the file are
marked for update.
The e, E, f, g,
and G conversion specifiers represent the special floating-point
values as follows:
| Item |
Description |
|---|
| Quiet NaN |
+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-character formatting
option is specified.
These subroutines
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 the NL_ARGMAX value.
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
you use the variable-ordering feature, you must specify it for all
conversions.
The following criteria apply:
- The format passed to
the NLS extensions can contain either the format of the conversion
or the explicit or implicit argument number. However, these forms
cannot be mixed within a single format string, except for %% (double
percent sign).
- The n value
must have no leading zeros.
- If %n$ is
used, %1$ to %n - 1$ inclusive
must be used.
- The n in %n$ is
in the range from 1 to the NL_ARGMAX value, inclusive. See
the limits.h file
for more information about the NL_ARGMAX value.
- Numbered arguments
in the argument list can be referenced as many times as required.
- The * (asterisk) specification
for field width or precision is not permitted with the variable order %n$ format;
instead, the *m$ format is used.
Return Values
Upon successful completion, the printf, fprintf, vprintf,
and vfprintf subroutines return the number of bytes transmitted
(not including the null character [\0] in the case of the sprintf,
and vsprintf subroutines). If an error was encountered, a negative
value is output.
Upon successful completion, the snprintf subroutine
returns the number of bytes written to the String parameter
(excluding the terminating null byte). If output characters are discarded
because the output exceeded the Number parameter in length,
then the snprintf subroutine returns the number of bytes that
would have been written to the String parameter if the Number parameter
had been large enough (excluding the terminating null byte).
Upon successful completion, the wsprintf and vwsprintf subroutines
return the number of wide characters transmitted (not including the
wide character null character [\0]). If an error was encountered,
a negative value is output.
Error Codes
The printf, fprintf, sprintf, snprintf,
or wsprintf subroutine is unsuccessful if the file specified
by the Stream parameter is unbuffered or the buffer needs to
be flushed and one or more of the following are true:
| Item |
Description |
|---|
| EAGAIN |
The O_NONBLOCK or O_NDELAY flag
is set for the file descriptor underlying the file specified by the Stream or String parameter
and the process would be delayed in the write operation. |
| EBADF |
The file descriptor underlying the file specified by the Stream or String parameter
is not a valid file descriptor open for writing. |
| EFBIG |
An attempt was made to write to a file that exceeds the file
size limit of this process or the maximum file size. For more information,
refer to the ulimit subroutine. |
| EINTR |
The write operation terminated due to receipt of a signal,
and either no data was transferred or a partial transfer was not reported. |
Note: Depending upon which library routine the application
binds to, this subroutine may return
EINTR. Refer to the
signal subroutine regarding
sa_restart.
| Item |
Description |
|---|
| EIO |
The process is a member of a background process group attempting
to perform a write to its controlling terminal, the TOSTOP flag
is set, the process is neither ignoring nor blocking the SIGTTOU signal,
and the process group of the process has no parent process. |
| ENOSPC |
No free space remains on the device that contains the file. |
| EPIPE |
An attempt was made to write to a pipe or first-in-first-out
(FIFO) that is not open for reading by any process. A SIGPIPE signal
is sent to the process. |
The printf, fprintf, sprintf, snprintf,
or wsprintf subroutine may be unsuccessful if one or more of
the following are true:
| Item |
Description |
|---|
| EILSEQ |
An invalid character sequence was detected. |
| EINVAL |
The Format parameter received insufficient arguments. |
| ENOMEM |
Insufficient storage space is available. |
| ENXIO |
A request was made of a nonexistent device, or the request
was outside the capabilities of the device. |
Examples
The
following example demonstrates how the vfprintf subroutine
can be used to write an error routine:
#include <stdio.h>
#include <stdarg.h>
/* The error routine should be called with the
syntax: */
/* error(routine_name, Format
[, value, . . . ]); */
/*VARARGS0*/
void error(char *fmt, . . .);
/* ** Note that the function name and
Format arguments cannot be **
separately declared because of the **
definition of varargs. */ {
va_list args;
va_start(args, fmt);
/*
** Display the name of the function
that called the error routine */
fprintf(stderr, "ERROR in %s: ",
va_arg(args, char *)); /*
** Display the remainder of the message
*/
fmt = va_arg(args, char *);
vfprintf(fmt, args);
va_end(args);
abort(); }