NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf,
vsprintf, vsnprintf - formatted output conversion
SYNOPSIS
#include <stdio.h>
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format
#include <stdarg.h>
int vprintf(const char *format, va_list ap));
int vfprintf(FILE *stream, const char *format, va_list ap
int vsprintf(char *str, const char *format, va_list ap
int vsnprintf(char *str, size_t size, const char *format
DESCRIPTION
The printf family of functions produces output according to
a format as described below. The functions printf and
vprintf write output to stdout, the standard output stream;
fprintf and vfprintf write output to the given output
stream; sprintf, snprintf, vsprintf and vsnprintf write to
the character string str.
These functions write the output under the control of a for-
mat string that specifies how subsequent arguments (or argu-
ments accessed via the variable-length argument facilities
of stdarg(3)) are converted for output.
These functions return the number of characters printed (not
including the trailing `\0' used to end output to strings).
snprintf and vsnprintf do not write more than size bytes
(including the trailing '\0'), and return -1 if the output
was truncated due to this limit.
The format string is composed of zero or more directives:
ordinary characters (not %), which are copied unchanged to
the output stream; and conversion specifications, each of
which results in fetching zero or more subsequent arguments.
Each conversion specification is introduced by the character
%. The arguments must correspond properly (after type pro-
motion) with the conversion specifier. After the %, the
following appear in sequence:
o Zero or more of the following flags:
# specifying that the value should be converted to
an ``alternate form''. For c, d, i, n, p, 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 out-
put string to a zero (except if a zero value is
printed with an explicit precision of zero). For
x and X conversions, a non-zero result has the
string `0x' (or `0X' for X conversions) prepended
to it. For e, E, f, g, and G conversions, the
result will always contain a decimal point, even
if no digits follow it (normally, a decimal point
appears in the results of those conversions only
if a digit follows). For g and G conversions,
trailing zeros are not removed from the result as
they would otherwise be.
0 specifying zero padding. For all conversions
except n, the converted value is padded on the
left with zeros rather than blanks. If a preci-
sion is given with a numeric conversion i, o, u,
i, x, and X), the 0 flag is ignored.
- (a negative field width flag) indicates the con-
verted value is to be left adjusted on the field
boundary. Except for n conversions, the converted
value is padded on the right with blanks, rather
than on the left with blanks or zeros. A - over-
rides a 0 if both are given.
' ' (a space) specifying that a blank should be left
before a positive number produced by a signed
conversion e, E, f, g, G, or i).
+ specifying that a sign always be placed before a
number produced by a signed conversion. A + over-
rides a space if both are used.
' specifying that in a numerical argument the output
is to be grouped if the locale information indi-
cates any. Note that many versions of gcc cannot
parse this option and will issue a warning.
o An optional decimal digit string specifying a minimum
field width. If the converted value has fewer charac-
ters than the field width, it will be padded with
spaces on the left (or right, if the left-adjustment
flag has been given) to fill out the field width.
o An optional precision, in the form of a period (`.')
followed by an optional digit string. If the digit
string is omitted, the precision is taken as zero.
This gives the minimum number of digits to appear for
d, i, o, u, x, and X conversions, the number of digits
to appear after the decimal-point for e, E, and f
conversions, the maximum number of significant digits
for g and G conversions, or the maximum number of char-
acters to be printed from a string for s conversions.
o The optional character h, specifying that a following
d, i, o, u, x, or X conversion corresponds to a short
int or unsigned short int argument, or that a following
n conversion corresponds to a pointer to a short int
argument.
o The optional character l (ell) specifying that a fol-
lowing d, i, o, u, x, or X conversion applies to a
pointer to a long int or unsigned long int argument, or
that a following n conversion corresponds to a pointer
to a long int argument. Linux provides a non ANSI com-
pliant use of two l flags as a synonym to q or L. Thus
ll can be used in combination with float conversions.
This usage is, however, strongly discouraged.
o The character L specifying that a following e, E, f, g,
or G conversion corresponds to a long double argument,
or a following d, i, o, u, x, or X conversion
corresponds to a long long argument. Note that long
long is not specified in ANSI C and therefore not port-
able to all architectures.
o The optional character q. This is equivalent to L.
See the STANDARDS and BUGS sections for comments on the
use of ll, L, and q.
o A Z character specifying that the following integer i,
o, u, x, or X) conversion corresponds to a size_t argu-
ment.
o A character that specifies the type of conversion to be
applied.
A field width or precision, or both, may be indicated by an
asterisk `*' instead of a digit string. In this case, an
int argument supplies the field width or precision. A nega-
tive field width is treated as a left adjustment flag fol-
lowed by a positive field width; a negative precision is
treated as though it were missing.
The conversion specifiers and their meanings are:
diouxX
The int (or appropriate variant) argument is converted
to signed decimal and i), unsigned octal unsigned
decimal or unsigned hexadecimal and X) notation. The
letters abcdef are used for x conversions; the letters
ABCDEF are used for X conversions. The precision, if
any, gives the minimum number of digits that must
appear; if the converted value requires fewer digits,
it is padded on the left with zeros.
eE The double argument is rounded and converted in the
style where there is one digit before the decimal-
point character 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, no decimal-
point character appears. An E conversion uses the
letter E (rather than e) to introduce the exponent.
The exponent always contains at least two digits; if
the value is zero, the exponent is 00.
f The double argument is rounded and converted to decimal
notation in the style where the number of digits after
the decimal-point character is equal to the precision
specification. If the precision is missing, it is
taken as 6; if the precision is explicitly zero, no
decimal-point character appears. If a decimal point
appears, at least one digit appears before it.
g The double argument is converted in style f or e (or E
for G conversions). The precision specifies the number
of significant digits. If the precision is missing, 6
digits are given; if the precision is zero, it is
treated as 1. Style e is used if the exponent from its
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 appears
only if it is followed by at least one digit.
c The int argument is converted to an unsigned char, and
the resulting character is written.
s The argument is expected to be a pointer to an array
of character type (pointer to a string). Characters
from the array are written up to (but not including) a
terminating NUL character; if a precision is specified,
no more than the number specified are written. If a
precision is given, no null character need be present;
if the precision is not specified, or is greater than
the size of the array, the array must contain a ter-
minating NUL character.
p The pointer argument is printed in hexadecimal (as if
by %#x or %#lx).
n The number of characters written so far is stored into
the integer indicated by the (or variant) pointer
argument. No argument is converted.
% A `%' is written. No argument is converted. The com-
plete conversion specification is `%%'.
In no case does a non-existent or small field width 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.
EXAMPLES
To print a date and time in the form `Sunday, July 3,
10:02', where weekday and month are pointers to strings:
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
To print to five decimal places:
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
To allocate a 128 byte string and print into it:
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
char *p;
va_list ap;
if ((p = malloc(128)) == NULL)
return (NULL);
va_start(ap, fmt);
(void) vsnprintf(p, 128, fmt, ap);
va_end(ap);
return (p);
}
SEE ALSO
printf(1), scanf(3)
STANDARDS
The fprintf, printf, sprintf, vprintf, vfprintf, and
vsprintf functions conform to ANSI C3.159-1989 (``ANSI C'').
The q flag is the BSD 4.4 notation for long long, while ll
or the usage of L in integer conversions is the GNU nota-
tion.
The Linux version of these functions is based on the GNU
libio library. Take a look at the info documentation of GNU
libc (glibc-1.08) for a more concise description.
BUGS
Some floating point conversions under Linux cause memory
leaks.
All functions are fully ANSI C3.159-1989 conformant, but
provide the additional flags q, Z and ' as well as an addi-
tional behaviour of the L and l flags. The latter may be
considered to be a bug, as it changes the behaviour of flags
defined in ANSI C3.159-1989.
The effect of padding the %p format with zeros (either by
the 0 flag or by specifying a precision), and the benign
effect (i.e., none) of the # flag on %n and %p conversions,
as well as nonsensical combinations such as are not stan-
dard; such combinations should be avoided.
Some combinations of flags defined by ANSI C are not making
sense (e.g. %Ld). While they may have a well-defined
behaviour on Linux, this need not to be so on other archi-
tectures. Therefore it usually is better not to use flags
that are not defined by ANSI C at all, i.e. use q instead of
L in combination with diouxX conversions or ll.
The usage of q is not the same as on BSD 4.4, as it may be
used in float conversions equivalently to L.
Because sprintf and vsprintf assume an infinitely long
string, callers must be careful not to overflow the actual
space; this is often impossible to assure.