PRINTF(3) Linux Programmer's Manual PRINTF(3)
NAME
printf, fprintf, sprintf, vprintf, vfprintf, vsprintf -
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, ...);
#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, char *format, va_list ap);
DESCRIPTION
The printf family of functions produces output according
to a format as described below. Printf and vprintf write
output to stdout, the standard output stream; fprintf and
vfprintf write output to the given output stream; sprintf,
and vsprintf write to the character string str. These
functions write the output under the control of a format
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).
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 argu-
ments. Each conversion specification is introduced by the
character %. The arguments must correspond properly
(after type promotion) 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 con-
verted to an ``alternate form''. For c, d,
i, n, p, s, and u conversions, this option
has no effect. For o conversions, the pre-
cision of the number is increased to force
the first character of the output 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 con-
versions, the result will always contain a
BSD MANPAGE 29 November 1993 1
PRINTF(3) Linux Programmer's Manual PRINTF(3)
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 conver-
sions except n, the converted value is
padded on the left with zeros rather than
blanks. If a precision is given with a
numeric conversion (d, i, o, u, i, x, and
X), the 0 flag is ignored.
- (a negative field width flag) indicates the
converted value is to be left adjusted on
the field boundary. Except for n conver-
sions, the converted value is padded on the
right with blanks, rather than on the left
with blanks or zeros. A - overrides a 0 if
both are given.
(a space) specifying that a blank should be
left before a positive number produced by a
signed conversion (d, e, E, f, g, G, or i).
+ specifying that a sign always be placed
before a number produced by a signed conver-
sion. A + overrides a space if both are
used.
o An optional decimal digit string specifying a mini-
mum field width. If the converted value has fewer
characters 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 characters to be printed from a
string for s conversions.
o The optional character h, specifying that a follow-
ing 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.
BSD MANPAGE 29 November 1993 2
PRINTF(3) Linux Programmer's Manual PRINTF(3)
o The optional character l (ell) specifying that a
following d, i, o, u, x, or X conversion applies to
a pointer to a long int or unsigned long int argu-
ment, or that a following n conversion corresponds
to a pointer to a long int argument.
o The character L specifying that a following e, E,
f, g, or G conversion corresponds to a long double
argument.
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
negative field width is treated as a left adjustment flag
followed 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 con-
verted to signed decimal (d and i), unsigned octal
(o, unsigned decimal (u, or unsigned hexadecimal (x
and X) notation. The letters abcdef are used for x
conversions; the letters ABCDEF are used for X con-
versions. 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.
DOU The long int argument is converted to signed deci-
mal, unsigned octal, or unsigned decimal, as if the
format had been ld, lo, or lu respectively. These
conversion characters are deprecated, and will
eventually disappear.
eE The double argument is rounded and converted in the
style [-]d.dddedd where there is one digit before
the decimal-point character and the number of dig-
its after it is equal to the precision; if the pre-
cision is missing, it is taken as 6; if the preci-
sion 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 [-]ddd.ddd, 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
BSD MANPAGE 29 November 1993 3
PRINTF(3) Linux Programmer's Manual PRINTF(3)
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 fol-
lowed by at least one digit.
c The int argument is converted to an unsigned char,
and the resulting character is written.
s The ``char *'' 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 num-
ber 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 termi-
nating NUL character.
p The ``void *'' pointer argument is printed in hex-
adecimal (as if by %#x or %#lx).
n The number of characters written so far is stored
into the integer indicated by the ``int *'' (or
variant) pointer argument. No argument is con-
verted.
% A `%' is written. No argument is converted. The
complete 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 con-
tain 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:
BSD MANPAGE 29 November 1993 4
PRINTF(3) Linux Programmer's Manual PRINTF(3)
#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,
scanf,
STANDARDS
The fprintf, printf, sprintf, vprintf, vfprintf, and
vsprintf functions conform to ANSI C3.159-1989 (``ANSI
C'').
BUGS
Some floating point conversions under Linux cause memory
leaks.
The conversion formats %D, %O, and %U are not standard and
are provided only for backward compatibility. These may
not be provided under Linux.
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 conver-
sions, as well as other nonsensical combinations such as
%Ld, are not standard; such combinations should be
avoided.
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.
BSD MANPAGE 29 November 1993 5
This manual page was brought to you by mjl_man V-2.0