PRINTF(3S) BSD PRINTF(3S)
NAME
printf, fprintf, sprintf - formatted output conversion
SYNOPSIS
#include <stdio.h>
int printf(format [, arg ] ... )
const char *format;
int fprintf(stream, format [, arg ] ... )
FILE *stream;
const char *format;
int sprintf(s, format [, arg ] ... )
char *s;
const char *format;
#include <varargs.h>
_doprnt(format, args, stream)
char *format;
va_list *args;
FILE *stream;
DESCRIPTION
printf places output on the standard output stream stdout. fprintf
places output on the named output stream. sprintf places "output" in the
string s, followed by the character "\0". All of these routines work by
calling the internal routine _doprnt, using the variable-length argument
facilities of varargs(3).
Each of these functions converts, formats, and prints its arguments after
the first under control of the first argument. The first argument is a
multibyte character sequence, beginning and ending in its initial shift
state. It contains two types of objects: plain multibyte characters,
which are simply copied to the output stream, and conversion
specifications, each of which causes conversion and printing of the next
successive arg.
Each conversion specification is introduced by the percent character (%).
The remainder of the conversion specification includes in the following
order:
o Zero or more of following flags:
# (Sharp sign.) Specifies that the value should be converted to
an "alternate form." For c, d, s, and u conversions, this
option has no effect. For o conversions, the precision of the
number is increased to force the first character of the output
string to a 0. For x(X) conversion, a nonzero result has the
string 0x(0X) prepended to it. For e, E, f, g, and G
conversions, the result will always contain a decimal point,
even if no digits follow the point (normally, a decimal point
only appears in the results of those conversions if a digit
follows the decimal point). For g and G conversions, trailing
0s are not removed from the result as they would otherwise be.
- (Minus sign.) Specifies left adjustment of the converted
value in the indicated field.
+ (Plus sign.) Specifies that there should always be a sign
placed before the number when using signed conversions.
space (A space character.) Specifies that a blank should be left
before a positive number during a signed conversion. A "+"
overrides a space if both are used.
o An optional digit string specifying a field width; if the converted
value has fewer characters than the field width, it will be blank-
padded on the left (or right, if the left-adjustment indicator has
been given) to make up the field width; if the field width begins with
a 0, zero-padding will be done instead of blank-padding.
o An optional period (.), which serves to separate the field width from
the next digit string.
o An optional digit string specifying a precision which specifies the
number of digits to appear after the decimal point, for e, E, and f
conversions, the minimum number of digits to appear, for d, i, o, u,
x, and X conversions, or the maximum number of characters to be
printed from a string. If the precision is missing, the precision is
taken as zero. If a precision appears with any other conversion
specifier, the behavior is undefined.
o The character "h," specifying that a following d, i, o, u, x, or X
conversion specifier applies to a short int or unsigned short int arg,
or specifying that a following n conversion specifier applies to a
pointer to a short int. If an h appears with any other conversion
specifier, the behavior is undefined.
o The character "l" ("ell"), specifying that a following d, i, o, u, x,
or X corresponds to a long int or unsigned long int arg. If an l
appears with any other conversion specifier, the behavior is
undefined.
o The character "L," specifying that a following e, E, f, g, or G
conversion specifier applies to a long double argument. If an L
appears with any other conversion specifier, the behavior is
undefined.
o A character which indicates the type of conversion to be applied.
A field width or precision can be an asterisk (*) instead of a digit
string. In this case, an int arg supplies the field width or precision.
The conversion characters and their meanings are
d,i The int arg is converted to signed decimal in the style
"[-]dddd". 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.
o,u,x,X The unsigned int arg is converted to unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X)
in the style "dddd"; the letters abcdef are used for x
conversion and the letters ABCDEF for X conversion. 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.
f The float or double arg is converted to decimal notation in the
style "[-]ddd.ddd" where the number of d's after the decimal
point is equal to the precision specification for the argument.
If the precision is missing, 6 digits are given; if the
precision is 0 and the # flag is not specified, no digits and
no decimal point are printed. If a decimal-point character
appears, at least one digit appears before it. The value is
rounded to the appropriate number of digits.
e,E The float or double arg is converted in the style
"[-]d.ddde+dd" where there is one digit before the decimal
point (which is nonzero if the argument is nonzero) and the
number after is equal to the precision specification for the
argument; when the precision is missing, 6 digits are produced.
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 specifier 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.
g,G The float or double arg is printed in style f or e (or style E
in the case of a G conversion specifier), whichever gives full
precision in minimum space. If the precision is zero, it is
taken as 1. Trailing zeros are removed from the fractional
portion of the result; a decimal-point character appears only
if it is followed by a digit.
c The int arg is converted to an unsigned char and printed.
s arg is taken to be a pointer to a character array. Characters
from the array are printed until a null character or until the
number of characters indicated by the precision specification
is reached. If the precision is zero or not specified, the
field is treated as having zero width. If the precision is not
specified or is greater than the size of the array, the array
must contain a null character or the behavior is undefined.
p The value of the pointer-to-void arg is written out as
0xXXXXXXXX, where XXXXXXXX is an eight-digit hexadecimal number
in which any alphabetic digits appear in lowercase.
n arg points to an integer into which is copied the number of
characters written to the output stream so far by this call.
No argument is converted.
% Print a percent sign (%); no argument is converted.
If any argument is, or points to, a union or an aggregate (except for an
array of character type using %s conversion, or a pointer using %p
conversion), the behavior is undefined. If, in the case of sprintf,
copying takes place between objects that overlap, the behavior is
undefined.
In no case does a non-existent or small field width cause truncation of a
field; padding takes place only if the specified field width exceeds the
actual width. Characters generated by printf are printed by putc(3S).
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, do this:
printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
To print pi to 5 decimals, do this:
printf("pi = %.5f", 4*atan(1.0));
SEE ALSO
putc(3S), scanf(3S), ecvt(3)
DIAGNOSTICS
These functions return the number of characters transmitted, or a
negative value if an output error occurred. sprintf does not count the
terminating null character among the characters transmitted.
NOTE
Parts of this discussion are adapted from ANS X3.159-1989.