printf(3S) DG/UX R4.11MU05 printf(3S)
NAME
printf, fprintf, sprintf, snprintf - print formatted output
SYNOPSIS
#include <stdio.h>
int printf(const char *format, .../* args */);
int fprintf(FILE *strm, const char *format, .../* args */);
int sprintf(char *s, const char *format, .../* args */);
int snprintf(char *s, size_t maxsize, const char *format, .../* args */);
DESCRIPTION
printf places output on the standard output stream stdout.
fprintf places output on strm.
sprintf places output, followed by a null character (\0), in
consecutive bytes starting at s. It is the user's responsibility to
ensure that enough storage is available.
snprintf behaves like sprintf, except that no more than maxsize
characters are placed into the array, including the terminating NULL
character. If the format and args require more than maxsize
characters, exactly maxsize characters (the last being a NULL) are
written, and a negative value is returned.
Each function returns the number of characters transmitted (not
including the terminating null character in the case of sprintf) or a
negative value if an output error was encountered.
Each of these functions converts, formats, and prints its args under
control of the format. The format is a character string that
contains two types of objects defined below:
1. plain characters that are simply copied to the output
stream;
2. conversion specifications.
All forms of the printf() functions allow for the insertion of a
language-dependent decimal point and thousands separator characters.
These characters are defined by the program's locale (category
LC_NUMERIC). The default decimal point is a period (.). The default
thousands separator is none.
Each conversion specification is introduced by the character %, and
takes the following general form and sequence:
%[posp$][flags][width][.preci][size]fmt
posp$ An optional entry, consisting of one or more decimal digits
followed by a $ character, specifying the number of the next
arg to access. The first arg (just after format) is numbered
1. If this field is not specified, the arg following the most
recently used arg will be used.
flags Zero or more characters that change the meaning of the
conversion specification. The flag characters and their
meanings are:
- The result of the conversion will be left-justified
within the field. (It will be right-justified if this
flag is not specified.)
+ The result of a signed conversion will always begin with
a sign (+ or -). (It will begin with a sign only when a
negative value is converted if this flag is not
specified.)
space If the first character of a signed conversion is not a
sign, or if a signed conversion results in no
characters, a space will be prefixed to the result. If
the space and + flags both appear, the space flag will
be ignored.
# The value is to be converted to an alternate form. For
an o conversion, it increases the precision to force the
first digit of the result to be a zero if necessary.
For b or B conversion, a non-zero result will have 0b or
0B prepended to it. For x or X conversion, a non-zero
result will have 0x or 0X prepended to it. For a, A, e,
E, f, F, g, and G conversions, the result will always
contain a decimal point character, even if no digits
follow the point. Normally, a decimal point appears in
the result of these conversions only if a digit follows
it. For g and G conversions, trailing zeroes will not
be removed from the result as they normally are. For
other conversions, the behavior is undefined.
0 For b, B, d, i, o, u, x, X, e, E, f, g and G
conversions, leading zeros (following any indication of
sign or base) are used to pad to the field width; no
space padding is performed. If the 0 and - flags both
appear, the 0 flag will be ignored. For d, i, o, u, x
and X conversions, if a precision is specified, the 0
flag will be ignored. For other conversions, the
behavior is undefined.
´ (an apostrophe) The integer portion of the result of a
decimal conversion ( i, d, u, f, F, g, or G) will be
grouped with thousands' separator characters.
width An optional entry that consists of either one or more decimal
digits, or an asterisk (*), or an asterisk followed by one or
more decimal digits and a $. It specifies the minimum field
width: If the converted value has fewer characters than the
field width, it will be padded (with space by default) on the
left or right (see the above flags description) to the field
width.
An optional entry that consists of a period (.)
that precedes either zero or more decimal digits, or an
asterisk (*), or an asterisk followed by one or more decimal
digits and a $. It specifies the minimum number of digits to
appear for the b, B, d, i, o, u, x, and X conversions, the
number of digits to appear after the decimal-point character
for the a, A, e, E, f and F conversions, the maximum number of
significant digits for the g and G conversions, or the maximum
number of bytes to be written from a string for an s and S
conversion. If only a period is specified, the precision is
taken as zero. For other conversions, the behavior is
undefined.
size An optional h, l (ell), or L that specifies other than the
default argument type of int for d and i; unsigned int for b,
B, o, u, x, and X; pointer to int for n; and double for a, A,
e, E, f, F, g, and G. If a size appears other than in the
following combinations, the behavior is undefined.
h For n, the argument has type pointer to short int; for d
and i, short int; and for b, B, o, u, x, and X, unsigned
short int. (For b, B, d, i, o, u, x, and X, the
argument will have been promoted according to the
integral promotions, and its value will be narrowed to
short or unsigned short before printing.)
l For n, the argument has type pointer to long int; for d
and i, long int; and for b, B, o, u, x, and X, unsigned
long int.
L For a, A, e, E, f, F, g, and G, the argument has type
long double.
fmt A conversion character (described below) that shows the type of
conversion to be applied.
When a width or .prec includes an asterisk (*), an int arg supplies
the width or precision. When they do not include a $, the arguments
specifying a field width, or precision, or both must appear (in that
order) before the argument (if any) to be converted. If the
conversion specification includes posp$, the field width and
precision may include a $. The decimal digits that precede the $
similarly specify the number of the arg that contains the field width
or precision. posp$ still specifies the number of the arg to
convert. A negative field width argument is taken as a - flag
followed by a positive field width. If the precision argument is
negative, it will be taken as zero.
When numbered argument specifications are used, specifying the Nth
argument requires that all the leading arguments, from the first to
the (N-1)th, be specified at least once, in a consistent way, in the
format string.
The conversion characters and their meanings are:
a,A The floating arg to hexadecimal floating notation in
the style [-]0xh.hhhhp+d. The exponent, d is the
decimal value of the base 2 value. The number of
hexadecimal digits h after the decimal-point character
is equal to the precision. If the precision is
missing, the result will have just enough digits to
represent the value exactly. If the precision is zero
and the # flag is not specified, no decimal point
character appears. The single digit to the left of the
decimal-point character is nonzero for normal values.
The A conversion specifier produces a value with X and
P instead of x and p.
d, i The integer arg is converted to signed decimal. The
precision specifies the minimum number of digits to
appear; if the value being converted can be represented
in fewer digits, it will be expanded with leading
zeros. The default precision is 1. The result of
converting a zero value with a precision of zero is no
characters.
b, B, o, u, x, X
The unsigned integer arg is converted to unsigned
binary (b and B), unsigned octal (o), unsigned decimal
(u), or unsigned hexadecimal notation (x and X). The x
conversion uses the letters abcdef and the X conversion
uses the letters ABCDEF. The precision specifies the
minimum number of digits to appear; if the value being
converted can be represented in fewer digits, it will
be expanded with leading zeros. The default precision
is 1. The result of converting a zero value with a
precision of zero is no characters.
e, E The floating arg is converted to the style
[-]d.ddde±dd, where there is one digit before the
decimal-point character (which is nonzero if the
argument is nonzero) and the number of digits after it
is equal to the precision. If the precision is
missing, it is taken as 6; if the precision is zero and
the # flag is not specified, no decimal-point character
appears. The value is rounded to the appropriate
number of digits. The E conversion character will
produce a number with E instead of e introducing the
exponent. The exponent always contains at least two
digits. If the value is zero, the exponent is zero.
f, F The floating arg is converted to decimal notation in
the style [-]ddd.ddd, where the number of digits after
the decimal-point character [see setlocale(3C)] is
equal to the precision specification. If the precision
is missing, it is taken as 6; if the precision is zero
and the # flag is not specified, no decimal-point
character appears. If a decimal-point character
appears, at least one digit appears before it. The
value is rounded to the appropriate number of digits.
g, G The floating arg is converted in style f or e (or in
style E in the case of a G conversion character), with
the precision specifying the number of significant
digits. If the precision is zero, it is taken as one.
The style used depends on the value converted; style e
(or E) will be used only if the exponent resulting from
the conversion is less than -4 or greater than or equal
to the precision. Trailing zeros are removed from the
fractional part of the result; a decimal-point
character appears only if it is followed by a digit.
c The integer arg is converted to an unsigned char, and
the resulting character is written.
s The arg is taken to be a pointer to an array of
characters. Characters from the array are written up
to (but not including) a terminating null character; if
a precision is specified, no more than that many
characters are written. If a precision is not
specified or is greater than the size of the array, the
array must contain a terminating null character. (A
null pointer for arg will yield undefined results.)
p The arg is taken to be a pointer to void. The value of
the pointer is converted to an implementation-defined
sequence of printable characters, which matches those
read by the %p conversion of the scanf function.
n The arg is taken to be a pointer to an integer into
which is written the number of characters written so
far by this call to printf, fprintf, snprintf or
sprintf. No argument is converted.
C The wide character arg type wchar_t is transformed into
a multibyte character and then printed.
S The arg is taken to be a wide string wchar_t and the
wide characters from the string are transformed into
multibyte characters, and printed until a null wide
character is encountered or the number of bytes given
by the precision wide is surpassed. If the precision
specification is missing, it is taken to be infinite.
A partial multibyte character will never be written in
any case.
% Print a %; no argument is converted. The complete
specification must be simply %%.
If the form of the conversion specification does not match any of the
above, the results of the conversion are undefined. Similarly, the
results are undefined if there are insufficient args for the format.
If the format is exhausted while args remain, the excess args are
ignored.
If a floating-point value represents an infinity, the output is
[±]inf, where inf is either inf or INF, depending on whether the
conversion character is lowercase or uppercase. Printing of the sign
follows the rules described above.
If a floating-point value has the internal representation for a NaN
(not-a-number), the output is [±]nan[m]. Depending on the conversion
character, nan is either nan or NAN. If the represented NaN matches
the default, no [m] will be output. Otherwise m represents the bits
from the significant in hexadecimal with abcdef or ABCDEF used,
depending on the case of the conversion character. Printing of the
sign follows the rules described previously.
A nonexistent or small field width does not cause truncation of a
field; if the result of a conversion is wider than the field width,
the field is expanded to contain the conversion result. Characters
generated by printf and fprintf are printed as if the putc routine
had been called repeatedly.
Errors
printf, fprintf, sprintf and snprintf return the number of characters
transmitted (not counting the terminating null character for
sprintf), or return a negative value if an error was encountered.
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|fprintf | Y Y N |
|printf | Y Y N |
|snprintf | Y N N |
|sprintf | Y N N |
+---------+-----------------------------+
EXAMPLES
To print a date and time in the form ``Sunday, July 3, 10:02,'' where
weekday and month are pointers to null-terminated strings:
printf("%s, %s %i, %d:%.2d",
weekday, month, day, hour, min);
To print π to 5 decimal places:
printf("pi = %.5f", 4 * atan(1.0));
The following two calls to printf both produce the same result of
10 10 00300 10:
printf("%d %1$d %.*d %1$d", 10, 5, 300);
printf("%d %1$d %3$.*2$d %1$d", 10, 5, 300);
SEE ALSO
exit(2), lseek(2), write(2), reentrant(3), abort(3C), ecvt(3C),
setlocale(3C), flockfile(3S), putc(3S), scanf(3S), stdio(3S)
Licensed material--property of copyright holder(s)