printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf
Purpose
Prints formatted output.
Library
Standard I/O Library (libc.a)
Syntax
#include <stdio.h>
int printf ( fmt [, val, ... |) int NLprintf ( fmt [, val, ... |)
char *fmt; char *fmt;
int fprintf (stream, fmt [, val, ... int NLfprintf (stream, fmt [, val, ... |)
FILE *stream; FILE *stream;
char *fmt; char *fmt;
int sprintf (s, fmt [, val, ... |) int NLsprintf (s, fmt [, val, ... |)
char *s, *fmt; char *s, *fmt;
Description
The printf subroutine converts, formats, and writes its
val parameters, under control of the fmt parameter, to
the standard output stream stdout.
The fprintf subroutine converts, formats, and writes its
val parameters, under control of the fmt parameter, to
the output stream specified by its stream parameter.
The sprintf subroutine converts, formats, and stores its
val parameters, under control of the fmt parameter, into
consecutive bytes starting at the address specified by
the s parameter. The sprintf subroutine places a "'\0'"
(null character) at the end. It is your responsibility
to ensure that enough storage space is available to
contain the formatted string.
The NLprintf, NLfprintf, and NLsprintf subroutines par-
allel their corresponding functions, providing conversion
types to handle code points and NLchars.
The fmt parameter is a character string that contains two
types of objects:
o Plain characters, which are copied to the output
stream.
o Conversion specifications, each of which causes zero
or more items to be fetched from the val parameter
list.
If there are not enough items for the fmt in the val
parameter list, then the results are unpredictable. If
more vals remain after the entire fmt has been processed,
they are ignored.
Each conversion specification in the fmt parameter has
the following syntax:
1. A "%" (percent) sign.
2. Zero or more options, which modify the meaning of the
conversion specification. The option characters and
their meanings are:
"-" The result of the conversion is left-
justified within the field.
"+" The result of a 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. If both the blank and "+" options
appear, then the blank option is ignored.
"#" This option specifies that the value is to be
converted 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 "0x" or "0X" prefixed to it. For
e, E, f, g, and G conversions, the result
always contains a decimal point, even if no
digits follow the decimal point. For g and G
conversions, trailing zeroes are not removed
from the result.
B This option affects conversions using the s
or S conversion characters of the NLprintf,
NLfprintf, and NLsprintf subroutines only.
The B flag specifies that field width and
precision are given in bytes rather than in
code points.
N This option affects the s and S conversion
characters of the NLprintf, NLfprintf, and
NLsprintf subroutines only. The N flag spec-
ifies that each international character
support code point in the converted string
converts into a printable ASCII escape
sequence that uniquely identifies the code
point.
3. 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 speci-
fied, the field is padded on the right. For the
NLprintf, NLfprintf, and NLsprintf subroutines, field
width is measured in code points rather than bytes,
unless the B flag is specified.
4. An optional precision. The precision is a "."
(period) followed by a decimal digit string. If no
precision is given, it is treated as 0. The preci-
sion specifies:
o The minimum number of digits to appear for the d,
u, o, x, or X conversions
o The number of digits to appear after the decimal
point for the e and f conversions
o The maximum number of significant digits for the
g conversion
o The maximum number of characters to be printed
from a string in the s conversion.
5. An optional l (the letter "ell") specifying that a
following d, u, o, x, or X conversion character
applies to a long integer val.
6. A character that indicates the type of conversion to
be applied:
"%" Performs no conversion. Prints a "%".
d Accepts an integer val and converts it to
signed decimal notation. The precision spec-
ifies the minimum number of digits to appear.
If the value being converted can be repres-
ented in fewer digits, it is expanded with
leading zeroes. The default precision is 1.
The result of converting a zero value with a
precision of zero is a null string. Speci-
fying a field width with a zero as a leading
character causes the field width value to be
padded with leading zeros.
u Accepts an integer 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 zeroes. The default precision
is 1. The result of converting a zero value
with a precision of zero is a null string.
Specifying a field width with a zero as a
leading character causes the field width
value to be padded with leading zeros.
o Accepts an integer val and converts it to
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
zeroes. The default precision is 1. The
result of converting a zero value with a pre-
cision of zero is a null string. Specifying
a field width with a zero as a leading char-
acter causes the field width value to be
padded with leading zeros.
An octal value for field width is not
implied.
x, X Accepts an integer val and converts it to
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 con-
verted can be represented in fewer digits, it
is expanded with leading zeroes. The default
precision is 1. The result of converting a
zero value with a precision of zero is a null
string. Specifying a field width with a zero
as a leading character causes the field width
value to be padded with leading zeros.
f Accepts a float or double val 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, then six digits
are output. If the precision is 0, then no
decimal point appears.
e, E Accepts a float or double val and converts it
to the exponential form [-]d.dddeAdd. There
is one digit before the decimal point and the
number of digits after the decimal point is
equal to the precision specification. If no
precision is specified, then six digits are
output. If the precision is 0, then 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, G Accepts a float or double val and converts it
in the style of the e, E or f conversion
characters, with the precision specifying the
number of significant digits. Trailing
zeroes 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 than or equal to the
precision.
c Accepts and prints the character val.
s Accepts a val is as a string (character
pointer) and characters from the string are
printed until a "'\0'" (null character) is
encountered or the number of characters indi-
cated by the precision is reached. If no
precision is specified, all characters up to
the first null character are printed. If the
string pointer val has a value of 0 or NULL,
the results are undefined.
S The corresponding NLprintf, NLfprintf, or
NLsprintf val is taken to be a pointer to a
string of the type NLchar. Characters from
the string are printed until a "\0" (null)
character is encountered or the number of
characters indicated by precision is reached.
If no precision is specified, all characters
up to the first null character are printed.
If the string pointer val has a value of 0 or
NULL, the results are undefined.
A field width or precision may be indicated by an *
(asterisk) instead of a digit string. In this case, an
integer val parameter supplies the field width or preci-
sion. The val parameter that is 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 result of a conversion is wider than the field
width, then the field is expanded to contain the con-
verted result. No truncation occurs. However, a small
precision may cause truncation on the right.
The e, E, f and g formats represent the special floating-
point values as follows:
Quiet NaN "+QNaN" or "-QNaN"
Signalling NaN "+SNaN" or "-SNaN"
A&infinity. "+INF" or "-INF"
A0 "+0" or "-0"
The representation of the plus sign depends on whether
the + or blank formatting option is specified.
Return Value
Upon successful completion, each of these subroutines
returns the number of display characters in the output
string rather than the number of bytes in the string.
(The NLprintf, NLfprintf and NLsprintf subroutines use
strings that may contain 2-byte NLchars.) The value
returned by sprintf and NLsprintf does not include the
final "'\0'" character. If an output error occurs, a
negative value is returned.
Related Information
In this book: "conv," "ecvt, fcvt, gcvt," "putc,
putchar, fputc, putw," "scanf, fscanf, sscanf, NLscanf,
NLfscanf, NLsscanf," and "standard i/o library."
Examples of using printf in C Language Guide and Refer-
ence.
"Overview of International Character Support" in Managing
the AIX Operating System.