Computer Science
PRINTF(3) Linux Programmer's Manual PRINTF(3)
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,
va_list ap);
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
format string that specifies how subsequent arguments (or
arguments accessed via the variable-length argument facil-
ities 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 does not write more than size bytes
(including the trailing '\0'), and returns -1 if the out-
put was truncated due to this limit. vsnprintf works sim-
ilarly to snprintf, but returns the number of characters
which would have been in the final string if enough space
had been available (excluding the trailing '\0').
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
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.
' specifying that in a numerical argument the
output is to be grouped if the locale infor-
mation indicates any. Note that many ver-
sions of gcc cannot parse this option and
will issue a warning.
+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.
+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. Linux pro-
vides a non ANSI compliant use of two l flags as a
synonym to q or L. Thus ll can be used in combina-
tion with float conversions. This usage is, how-
ever, 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 con-
version corresponds to a long long argument. Note
that long long is not specified in ANSI C and
therefore not portable 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
(d, i, o, u, x, or X) conversion corresponds to a
size_t 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 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 [-]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 pre-
cision is explicitly zero, no decimal-point charac-
ter 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:
#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
additional 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 conver-
sions, as well as nonsensical combinations such as are not
standard; such combinations should be avoided.
Some combinations of flags defined by ANSI C are not mak-
ing 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.
Linux Manpage 28 January 1996 1
Back to the index
