The printf() family of functions produce output
according to the given format as described
below. This format may contain “conversion specifiers”; the
results of such conversions, if any, depend on the arguments following the
format string.

The printf() and
vprintf() functions write output to the standard
output stream, stdout;
fprintf() and
vfprintf() write output to the supplied stream
pointer stream;
dprintf() and
vdprintf() write output to the given file
descriptor; sprintf(),
snprintf(),
vsprintf(), and
vsnprintf() write to the character string
str; asprintf()
and vasprintf() write to a dynamically allocated
string that is stored in ret.

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 facilities
of stdarg(3)) are converted for
output.

snprintf() and
vsnprintf() will write at most
size-1 of the characters printed into the
output string (the size'th character then
gets the terminating ‘\0’); if the
return value is greater than or equal to the
size argument, the string was too short and
some of the printed characters were discarded. If
size is zero,
str may be a null pointer and no characters
will be written; the number of bytes that would have been written excluding
the terminating ‘\0’ byte, or -1 on
error, will be returned.

sprintf() and
vsprintf() effectively assume an infinite
size.

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 promotion) with the conversion specifier. After the
%, the following appear in sequence:

An optional field, consisting of a decimal digit string
followed by a $ specifying the next argument
to access. If this field is not provided, the argument following the last
argument accessed will be used. Arguments are numbered starting at
1.

Zero or more of the following flags:

A hash ‘#’
character specifying that the value should be converted to an
“alternate form”. For o
conversions, the precision 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
a, A,
e, E,
f, 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. For all other formats, behaviour is
undefined.

A zero ‘0’
character specifying zero padding. For all conversions 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, 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 conversions, 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, a,
A, e,
E, f,
F, g,
G, or
i).

A ‘+’
character specifying that a sign always be placed before a number
produced by a signed conversion. A
‘+’ overrides a space if
both are used.

An optional decimal digit string specifying a minimum
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.

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
a, A,
e, E,
f, 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.

An optional length modifier, that specifies the size of
the argument. The following length modifiers are valid for the
d, i,
n, o,
u, x, or
X conversions:

Modifier

d, i

o, u, x, X

n

hh

signed char

unsigned char

signed char *

h

short

unsigned short

short *

l (ell)

long

unsigned long

long *

ll (ell ell)

long long

unsigned long long

long long *

j

intmax_t

uintmax_t

intmax_t *

t

ptrdiff_t

(see note)

ptrdiff_t *

z

(see note)

size_t

(see note)

q (deprecated)

quad_t

u_quad_t

quad_t *

Note: the t modifier, when applied to an
o, u,
x, or X
conversion, indicates that the argument is of an unsigned type equivalent
in size to a ptrdiff_t. The
z modifier, when applied to a
d or i
conversion, indicates that the argument is of a signed type equivalent in
size to a size_t. Similarly, when applied
to an n conversion, it indicates that the
argument is a pointer to a signed type equivalent in size to a
size_t.

The following length modifiers are valid for the
a, A,
e, E,
f, F,
g, or G
conversions:

Modifier

e, E, f, F, g, G

l (ell)

double (ignored: same behavior as without it)

L

long double

The following length modifier is valid for the
c or s
conversions:

Modifier

c

s

l (ell)

wint_t

wchar_t *

A character that specifies the type of conversion to be
applied.

A field width or precision, or both, may be indicated by an asterisk
‘*’ or an asterisk followed by one or
more decimal digits and a ‘$’ 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. If a single format directive mixes
positional (nn$) and non-positional arguments, the results are undefined.

The int (or appropriate variant)
argument is converted 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.

The long int argument is converted
to signed decimal, 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.

The double argument is rounded and
converted in the style
[-]d.ddde±dd 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.

If the argument is infinity, it will be converted to [-]inf
(e) or [-]INF
(E), respectively. If the argument is
not-a-number (NaN), it will be converted to [-]nan
(e) or [-]NAN
(E), respectively.

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 precision is explicitly zero, no decimal-point character appears. If a
decimal point appears, at least one digit appears before it.

If the argument is infinity, it will be converted to [-]inf
(f) or [-]INF
(F), respectively. If the argument is
not-a-number (NaN), it will be converted to [-]nan
(f) or [-]NAN
(F), respectively.

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.

If the argument is infinity, it will be converted to [-]inf
(g) or [-]INF
(G), respectively. If the argument is
not-a-number (NaN), it will be converted to [-]nan
(g) or [-]NAN
(G), respectively.

The double argument is rounded and
converted to hexadecimal notation in the style
[-]0xh.hhhp[±]d
where the number of digits after the hexadecimal-point character is equal
to the precision specification. If the precision is missing, it is taken
as enough to represent the floating-point number exactly, and no rounding
occurs. If the precision is zero, no hexadecimal-point character appears.
The p is a literal character
‘p’, and the exponent consists of a
positive or negative sign followed by a decimal number representing an
exponent of 2. The A conversion uses the
prefix “0X” (rather than
“0x”), the letters
“ABCDEF” (rather than
“abcdef”) to represent the hex
digits, and the letter ‘P’ (rather
than ‘p’) to separate the mantissa
and exponent.

Note that there may be multiple valid ways to represent floating-point
numbers in this hexadecimal format. For example,
0x3.24p+0, 0x6.48p-1 and
0xc.9p-2 are all equivalent. The format chosen
depends on the internal representation of the number, but the
implementation guarantees that the length of the mantissa will be
minimized. Zeroes are always represented with a mantissa of 0 (preceded by
a ‘-’ if appropriate) and an
exponent of +0.

If the argument is infinity, it will be converted to [-]inf
(a) or [-]INF
(A), respectively. If the argument is
not-a-number (NaN), it will be converted to [-]nan
(a) or [-]NAN
(A), respectively.

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
number specified are written. If a precision is given, no NUL character
need be present; if the precision is not specified, or is greater than the
size of the array, the array must contain a terminating NUL
character.

For all these functions if an output or encoding error occurs, a value less than
0 is returned.

The printf(),
dprintf(),
fprintf(),
sprintf(),
vprintf(),
vdprintf(),
vfprintf(),
vsprintf(),
asprintf(), and
vasprintf() functions return the number of
characters printed (not including the trailing
‘\0’ used to end output to strings).

The snprintf() and
vsnprintf() functions return the number of
characters that would have been output if the
size were unlimited (again, not including the
final ‘\0’.).

The asprintf() and
vasprintf() functions return the number of
characters that were output to the newly allocated string (excluding the final
‘\0’). A pointer to the newly allocated
string is returned in ret; it should be
passed to free(3) to release the
allocated storage when it is no longer needed. If sufficient space cannot be
allocated, these functions will return -1. The value of
ret in this situation is
implementation-dependent (on OpenBSD,
ret will be set to the null pointer, but this
behavior should not be relied upon).

The conversion formats %D,
%O, and %U are not
standard and are provided only for backward compatibility. 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 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. For safety, programmers should use the
snprintf() and
asprintf() family of interfaces instead.
Unfortunately, the asprintf() interface is not
available on all systems as it is not part of
ISO/IEC 9899:1999
(“ISO C99”).

It is important never to pass a string with user-supplied data as a format
without using ‘%s’. An attacker can put
format specifiers in the string to mangle the stack, leading to a possible
security hole. This holds true even if the string has been built “by
hand” using a function like snprintf(), as
the resulting string may still contain user-supplied conversion specifiers for
later interpolation by printf().

There is no way for printf() to know the size of
each argument passed. If positional arguments are used, care must be taken to
ensure that all parameters, up to the last positionally specified parameter,
are used in the format string. This allows for the format string to be parsed
for this information. Failure to do this will mean the code is non-portable
and liable to fail.