This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs. 
Print Formats · Print Functions · Print Conversion Specifiers
Several library functions help you convert data values from
encoded internal representations to text sequences that are
generally readable by people. You provide a
format string as the value of the
format
argument to each of these functions, hence
the term formatted output.
The functions fall into two categories.
The byte print functions
(declared in
<stdio.h>
)
convert internal representations to sequences of type char,
and help you compose such sequences for display:
fprintf,
printf,
sprintf,
vfprintf,
vprintf, and
vsprintf.
For these function, a format string is a
multibyte string
that begins and ends in the
initial shift state.
The wide print functions
(declared in
<wchar.h>
and hence added with
Amendment 1)
convert internal representations to sequences of type
wchar_t
,
and help you compose such sequences for display:
fwprintf,
swprintf,
wprintf,
vfwprintf,
vswprintf, and
vwprintf.
For these functions, a format string is a
widecharacter string.
In the descriptions that follow, a wide character wc
from a format string or a stream is compared to a specific (byte)
character c
as if by evaluating the expression
wctob(wc) == c
.
A format string has the same syntax for both the print functions and the scan functions, as shown in the diagram.
A format string consists of zero or more
conversion specifications
interspersed with literal text and
white space.
White space is a sequence of one or more
characters c
for which the call
isspace(c)
returns nonzero.
(The characters defined as white space can change when you change the
LC_CTYPE
locale category.)
For the print functions, a conversion specification is one of the
print conversion specifications described below.
A print function scans the format string once from beginning
to end to determine what conversions to perform. Every print
function accepts a
varying number
of arguments, either directly or under control of an argument of type
va_list
.
Some print conversion specifications
in the format string use the next argument in the list.
A print function uses each successive argument no more than
once. Trailing arguments can be left unused.
In the description that follows:
d
, i
, o
, u
,
x
, or X
e
, E
, f
,
g
, or G
For the print functions, literal text or white space in a format string generates characters that match the characters in the format string. A print conversion specification typically generates characters by converting the next argument value to a corresponding text sequence. A print conversion specification has the format:
Boldface indicates a feature added with C99.
Following the percent character (%
)
in the format string, you can write zero or more
format flags:

 to leftjustify a conversion+
 to generate a plus sign for signed values that
are positivespace
 to generate a space
for signed values
that have neither a plus nor a minus sign#
 to prefix 0
on an o
conversion,
to prefix 0x
on an x
conversion,
to prefix 0X
on an X
conversion,
or to generate a decimal point and fraction
digits that are otherwise suppressed on a floatingpoint conversion0
 to pad a conversion with leading zeros after
any sign or prefix, in the absence of a minus (
)
format flag or a specified precisionFollowing any format flags, you can write a
field width that
specifies the minimum number of characters to generate for the conversion.
Unless altered by a format flag,
the default behavior is to pad a short conversion
on the left with space
characters.
If you write an asterisk (*
)
instead of a decimal number for a field width, then a print
function takes the value of the next argument (which must be of type
int) as the field width. If the argument value is negative,
it supplies a 
format flag
and its magnitude is the field width.
Following any field width, you can write a dot (.
)
followed by a
precision
that specifies one of the following:
the minimum number of digits to generate on an integer conversion;
the number of fraction digits to generate on an e
,
E
, or f
conversion;
the maximum number of significant digits to generate
on a g
or G
conversion; or the maximum number
of characters to generate from a
C string
on an s
conversion.
If you write an *
instead of
a decimal number for a precision,
a print function takes the value of the next argument (which must
be of type int) as the precision. If the argument value is
negative, the default precision applies. If you do not write either
an *
or a decimal number following the dot, the precision
is zero.
Following any precision, you must write a onecharacter print conversion specifier, possibly preceded by a one or twocharacter qualifier. Each combination determines the type required of the next argument (if any) and how the library functions alter the argument value before converting it to a text sequence. The integer and floatingpoint conversions also determine what base to use for the text representation. If a conversion specifier requires a precision p and you do not provide one in the format, then the conversion specifier chooses a default value for the precision. The following table lists all defined combinations and their properties.
Conversion Argument Converted Default Pre Specifier Type Value Base cision %a double x (double)x 10 6 added with C99 %La long double x (long double)x 10 6 added with C99 %A double x (double)x 10 6 added with C99 %LA long double x (long double)x 10 6 added with C99 %c int x (unsigned char)x %lc wint_t x wchar_t a[2] = {x} %d int x (int)x 10 1 %hd int x (short)x 10 1 %ld long x (long)x 10 1 %hhd int x (signed char)x 10 1 added with C99 %jd intmax_t x (intmax_t)x 10 1 added with C99 %lld long long x (long long)x 10 1 added with C99 %td ptrdiff_t x (ptrdiff_t)x 10 1 added with C99 %zd size_t x (ptrdiff_t)x 10 1 added with C99 %e double x (double)x 10 6 %Le long double x (long double)x 10 6 %E double x (double)x 10 6 %LE long double x (long double)x 10 6 %f double x (double)x 10 6 %Lf long double x (long double)x 10 6 %F double x (double)x 10 6 added with C99 %LF long double x (long double)x 10 6 added with C99 %g double x (double)x 10 6 %Lg long double x (long double)x 10 6 %G double x (double)x 10 6 %LG long double x (long double)x 10 6 %i int x (int)x 10 1 %hi int x (short)x 10 1 %li long x (long)x 10 1 %hhi int x (signed char)x 10 1 added with C99 %ji intmax_t x (intmax_t)x 10 1 added with C99 %lli long long x (long long)x 10 1 added with C99 %ti ptrdiff_t x (ptrdiff_t)x 10 1 added with C99 %zi size_t x (ptrdiff_t)x 10 1 added with C99 %n int *x %hn short *x %ln long *x %hhn int *x added with C99 %jn intmax_t *x added with C99 %lln long long *x added with C99 %tn ptrdiff_t *x added with C99 %zn size_t *x added with C99 %o int x (unsigned int)x 8 1 %ho int x (unsigned short)x 8 1 %lo long x (unsigned long)x 8 1 %hho int x (unsigned char)x 8 1 added with C99 %jo intmax_t x (uintmax_t)x 8 1 added with C99 %llo long long x (unsigned long long)x 8 1 added with C99 %to ptrdiff_t x (size_t)x 8 1 added with C99 %zo size_t x (size_t)x 8 1 added with C99 %p void *x (void *)x %s char x[] x[0]... large %ls wchar_t x[] x[0]... large %u int x (unsigned int)x 10 1 %hu int x (unsigned short)x 10 1 %lu long x (unsigned long)x 10 1 %hhu int x (unsigned char)x 8 1 added with C99 %ju intmax_t x (uintmax_t)x 8 1 added with C99 %llu long long x (unsigned long long)x 8 1 added with C99 %tu ptrdiff_t x (size_t)x 8 1 added with C99 %zu size_t x (size_t)x 8 1 added with C99 %x int x (unsigned int)x 16 1 %hx int x (unsigned short)x 16 1 %lx long x (unsigned long)x 16 1 %hhx int x (unsigned char)x 8 1 added with C99 %jx intmax_t x (uintmax_t)x 8 1 added with C99 %llx long long x (unsigned long long)x 8 1 added with C99 %tx ptrdiff_t x (size_t)x 8 1 added with C99 %zx size_t x (size_t)x 8 1 added with C99 %X int x (unsigned int)x 16 1 %hX int x (unsigned short)x 16 1 %lX long x (unsigned long)x 16 1 %hhX int x (unsigned char)x 8 1 added with C99 %jX intmax_t x (uintmax_t)x 8 1 added with C99 %llX long long x (unsigned long long)x 8 1 added with C99 %tX ptrdiff_t x (size_t)x 8 1 added with C99 %zX size_t x (size_t)x 8 1 added with C99 %% none '%'
The print conversion specifier determines any behavior not summarized in this table. For all floatingpoint conversions:
inf
or INF
.inf
or INF
.nan
or NAN
.The uppercase version prints only for an uppercase conversion specifier,
such as %E
but not %Lg
.
In the following descriptions, p is the precision. Examples follow each of the print conversion specifiers. A single conversion can generate up to 509 characters.
You write %a
or
%A
to generate
a signed hexadecimal fractional representation with
a decimal poweroftwo exponent. The generated text takes the form
±0Xh.hhhP±dd, where ± is either a plus or
minus sign,
X is either x
(for %a
conversion)
or X
(for %A
conversion),
h is a hexadecimal digit,
d is a decimal digit, the hexadecimal point (.)
is the decimal point for the current
locale,
and P is either p
(for %a
conversion)
or P
(for %A
conversion).
The generated text has one integer digit
which is zero only for the value zero,
a hexadecimal point if any fraction digits are present
or if you specify the #
format flag, at most p fraction digits with no trailing zeros,
and at least one exponent digit with no leading zeros.
The result is rounded. The value zero has a zero exponent.
printf("%a", 30.0) generates, e.g. 0x1ep+1 printf("%.2A", 30.0) generates, e.g. 0X1.E0P+1
You write %c
to generate a single character from the converted
value.
printf("%c", 'a') generates a printf("<%3c%3c>", 'a', 'b') generates < ab >
For a
wide stream,
conversion of the character x
occurs as if by calling
btowc(x)
.
wprintf(L"%c", 'a') generates btowc(a)
You write %lc
to generate a single character from the converted value.
Conversion of the character x
occurs as if
it is followed by a null character in an array of two elements of type
wchar_t
converted by the conversion specification
ls
.
printf("%lc", L'a') generates a wprintf(L"lc", L'a') generates L'a'
You write %d
,
%i
,
%o
,
%u
,
%x
, or
%X
to generate
a possibly signed integer representation. %d
or %i
specifies signed decimal representation, %o
unsigned octal, %u
unsigned decimal,
%x
unsigned hexadecimal using the digits 09
and af
, and %X
unsigned
hexadecimal using the digits 09
and AF
.
The conversion generates at least p digits
to represent the converted value. If p is zero,
a converted value of zero generates no digits.
printf("%d %o %x", 31, 31, 31) generates 31 37 1f printf("%hu", 0xffff) generates 65535 printf("%#X %+d", 31, 31) generates 0X1F +31
You write %e
or
%E
to generate
a signed decimal fractional representation with
a decimal poweroften exponent. The generated text takes the form
±d.dddE±dd, where ± is either a plus or
minus sign, d is a decimal digit, the decimal point (.)
is the decimal point for the current
locale,
and E is either e
(for %e
conversion)
or E
(for %E
conversion).
The generated text has one integer digit,
a decimal point if p is nonzero or if you specify the #
format flag, p fraction digits, and at least two exponent digits.
The result is rounded. The value zero has a zero exponent.
printf("%e", 31.4) generates 3.140000e+01 printf("%.2E", 31.4) generates 3.14E+01
You write %f
or %F
to generate a signed decimal fractional representation
with no exponent. The generated text takes the form ±d.ddd,
where ± is either a plus or minus sign,
d is a decimal digit, and the decimal point (.)
is the decimal point for the current
locale.
The generated text has at least one integer digit,
a decimal point if p is nonzero or if you specify
the #
format flag, and p fraction digits.
The result is rounded.
printf("%f", 31.4) generates 31.400000 printf("%.0f %#.0f", 31.0, 31.0)generates 31 31.
You write %g
or
%G
to generate
a signed decimal fractional
representation with or without a decimal poweroften exponent, as appropriate.
For %g
conversion, the generated text
takes the same form as either %e
or %f
conversion. For %G
conversion,
it takes the same form as either
%E
or
%F
conversion.
The precision p specifies the number
of significant digits generated. (If p is zero, it is changed
to 1.) If %e
conversion would yield an exponent in the range
[4, p), then %f
conversion occurs instead.
The generated text has no trailing zeros
in any fraction and has a decimal point
only if there are nonzero fraction digits, unless you specify the
#
format flag.
printf("%.6g", 31.4) generates 31.4 printf("%.1g", 31.4) generates 3.14e+01
You write %n
to store the number of characters generated
(up to this point in the format) in an integer object
whose address is the value of the next successive argument.
printf("abc%n", &x) stores 3
You write %p
to generate an external representation of a pointer to void.
The conversion is implementation defined.
printf("%p", (void *)&x) generates, e.g. F4C0
You write %s
to generate a sequence of characters from
the values stored in the argument
C string.
printf("%s", "hello") generates hello printf("%.2s", "hello") generates he
For a
wide stream, conversion
occurs as if by repeatedly calling
mbrtowc
,
beginning in the
initial conversion state.
The conversion generates no more than p characters,
up to but not including the terminating null character.
wprintf(L"%s", "hello") generates hello
You write %ls
to generate a sequence of characters from
the values stored in the argument
widecharacter string.
For a byte stream,
conversion occurs as if by repeatedly calling
wcrtomb
, beginning in the
initial conversion state,
so long as complete multibyte characters can be generated.
The conversion generates no more than
p characters, up to but not including the terminating null
character.
printf("%ls", L"hello") generates hello wprintf(L"%.2s", L"hello") generates he
You write %%
to generate
the percent character (%
).
printf("%%") generates %
See also the Table of Contents and the Index.
Copyright © 19892002 by P.J. Plauger and Jim Brodie. All rights reserved.