2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
|
|
|
|
.\"
|
|
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
|
|
.\" the License, or (at your option) any later version.
|
|
|
|
.\"
|
|
|
|
.\" The GNU General Public License's references to "object code"
|
|
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
|
|
.\" document formatting or typesetting system, including
|
|
|
|
.\" intermediate and printed output.
|
|
|
|
.\"
|
|
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
.\" GNU General Public License for more details.
|
|
|
|
.\"
|
|
|
|
.\" You should have received a copy of the GNU General Public
|
|
|
|
.\" License along with this manual; if not, write to the Free
|
|
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
|
|
.\" USA.
|
|
|
|
.\"
|
|
|
|
.\"
|
|
|
|
.\" Earlier versions of this page influenced the present text.
|
|
|
|
.\" It was derived from a Berkeley page with version
|
|
|
|
.\" @(#)printf.3 6.14 (Berkeley) 7/30/91
|
|
|
|
.\" converted for Linux by faith@cs.unc.edu, updated by
|
|
|
|
.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
|
|
|
|
.\"
|
|
|
|
.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
|
|
|
|
.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
|
|
|
|
.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
|
|
|
|
.\"
|
|
|
|
.TH PRINTF 3 2000-10-16 "Linux Manpage" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <stdio.h>
|
|
|
|
.sp
|
|
|
|
.BI "int printf(const char *" format ", ...);"
|
|
|
|
.br
|
|
|
|
.BI "int fprintf(FILE *" stream ", const char *" format ", ...);"
|
|
|
|
.br
|
|
|
|
.BI "int sprintf(char *" str ", const char *" format ", ...);"
|
|
|
|
.br
|
|
|
|
.BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);"
|
|
|
|
.sp
|
|
|
|
.B #include <stdarg.h>
|
|
|
|
.sp
|
|
|
|
.BI "int vprintf(const char *" format ", va_list " ap );
|
|
|
|
.br
|
|
|
|
.BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap );
|
|
|
|
.br
|
|
|
|
.BI "int vsprintf(char *" str ", const char *" format ", va_list " ap );
|
|
|
|
.br
|
|
|
|
.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap );
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The functions in the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR printf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
family produce output according to a
|
|
|
|
.I format
|
|
|
|
as described below. The functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR printf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
write output to
|
|
|
|
.IR stdout ,
|
|
|
|
the standard output stream;
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR fprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vfprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
write output to the given output
|
|
|
|
.IR stream ;
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sprintf (),
|
|
|
|
.BR snprintf (),
|
|
|
|
.BR vsprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsnprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
write to the character string
|
|
|
|
.IR str .
|
|
|
|
.PP
|
|
|
|
The functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vprintf (),
|
|
|
|
.BR vfprintf (),
|
|
|
|
.BR vsprintf (),
|
|
|
|
.BR vsnprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
are equivalent to the functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR printf (),
|
|
|
|
.BR fprintf (),
|
|
|
|
.BR sprintf (),
|
|
|
|
.BR snprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
respectively, except that they are called with a va_list instead
|
|
|
|
of a variable number of arguments. These functions do not call the
|
|
|
|
.I va_end
|
|
|
|
macro. Consequently, the value of
|
|
|
|
.I ap
|
|
|
|
is undefined after the call. The application should call
|
|
|
|
.I va_end(ap)
|
|
|
|
itself afterwards.
|
|
|
|
.PP
|
|
|
|
These eight functions write the output under the control of a
|
|
|
|
.I format
|
|
|
|
string that specifies how subsequent arguments (or arguments accessed via
|
|
|
|
the variable-length argument facilities of
|
|
|
|
.BR stdarg (3))
|
|
|
|
are converted for output.
|
|
|
|
.SS "Return value"
|
|
|
|
Upon successful return, these functions return the number of characters
|
|
|
|
printed (not including the trailing '\e0' used to end output to strings).
|
|
|
|
The functions
|
2005-10-28 13:43:45 +00:00
|
|
|
.BR snprintf ()
|
|
|
|
and
|
|
|
|
.BR vsnprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
do not write more than
|
|
|
|
.I size
|
|
|
|
bytes (including the trailing '\e0').
|
|
|
|
If the output was truncated due to this limit then the return value
|
|
|
|
is the number of characters (not including the trailing '\e0')
|
|
|
|
which would have been written to the final string if enough space
|
|
|
|
had been available. Thus, a return value of
|
|
|
|
.I size
|
|
|
|
or more means that the output was truncated. (See also below
|
|
|
|
under NOTES.)
|
|
|
|
If an output error is encountered, a negative value is returned.
|
|
|
|
.SS "Format of the format string"
|
|
|
|
The format string is a character string, beginning and ending
|
|
|
|
in its initial shift state, if any.
|
|
|
|
The format string is composed of zero or more directives: ordinary
|
|
|
|
characters (not
|
|
|
|
.BR % ),
|
|
|
|
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
|
|
|
|
.BR % ,
|
|
|
|
and ends with a
|
|
|
|
.IR "conversion specifier" .
|
|
|
|
In between there may be (in this order) zero or more
|
|
|
|
.IR flags ,
|
|
|
|
an optional minimum
|
|
|
|
.IR "field width" ,
|
|
|
|
an optional
|
|
|
|
.I precision
|
|
|
|
and an optional
|
|
|
|
.IR "length modifier" .
|
|
|
|
|
|
|
|
The arguments must correspond properly (after type promotion) with the
|
|
|
|
conversion specifier. By default, the arguments are used in the order
|
|
|
|
given, where each `*' and each conversion specifier asks for the next
|
|
|
|
argument (and it is an error if insufficiently many arguments are given).
|
|
|
|
One can also specify explicitly which argument is taken,
|
|
|
|
at each place where an argument is required, by writing `%m$' instead
|
|
|
|
of `%' and `*m$' instead of `*', where the decimal integer m denotes
|
|
|
|
the position in the argument list of the desired argument, indexed starting
|
|
|
|
from 1. Thus,
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
printf("%*d", width, num);
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
and
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
printf("%2$*1$d", width, num);
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
are equivalent. The second style allows repeated references to the
|
|
|
|
same argument. The C99 standard does not include the style using `$',
|
|
|
|
which comes from the Single Unix Specification. If the style using
|
|
|
|
`$' is used, it must be used throughout for all conversions taking an
|
|
|
|
argument and all width and precision arguments, but it may be mixed
|
|
|
|
with `%%' formats which do not consume an argument. There may be no
|
|
|
|
gaps in the numbers of arguments specified using `$'; for example, if
|
|
|
|
arguments 1 and 3 are specified, argument 2 must also be specified
|
|
|
|
somewhere in the format string.
|
|
|
|
|
|
|
|
For some numeric conversions a radix character (`decimal point') or
|
|
|
|
thousands' grouping character is used. The actual character used
|
|
|
|
depends on the LC_NUMERIC part of the locale. The POSIX locale
|
|
|
|
uses `.' as radix character, and does not have a grouping character.
|
|
|
|
Thus,
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
printf("%'.2f", 1234567.89);
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
results in `1234567.89' in the POSIX locale, in `1234567,89' in the
|
|
|
|
nl_NL locale, and in `1.234.567,89' in the da_DK locale.
|
|
|
|
.SS "The flag characters"
|
|
|
|
The character % is followed by zero or more of the following flags:
|
|
|
|
.TP
|
|
|
|
.B #
|
|
|
|
The value should be converted to an ``alternate form''.
|
|
|
|
For
|
|
|
|
.BR o
|
|
|
|
conversions, the first character of the output string is made zero
|
|
|
|
(by prefixing a 0 if it was not zero already).
|
|
|
|
For
|
|
|
|
.B x
|
|
|
|
and
|
|
|
|
.B X
|
|
|
|
conversions, a non\-zero result has the string `0x' (or `0X' for
|
|
|
|
.B X
|
|
|
|
conversions) prepended to it. For
|
|
|
|
.BR a ,
|
|
|
|
.BR A ,
|
|
|
|
.BR e ,
|
|
|
|
.BR E ,
|
|
|
|
.BR f ,
|
|
|
|
.BR F ,
|
|
|
|
.BR g ,
|
|
|
|
and
|
|
|
|
.B 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
|
|
|
|
.B g
|
|
|
|
and
|
|
|
|
.B G
|
|
|
|
conversions, trailing zeros are not removed from the result as they would
|
|
|
|
otherwise be.
|
|
|
|
For other conversions, the result is undefined.
|
|
|
|
.TP
|
|
|
|
.B \&0
|
|
|
|
The value should be zero padded. For
|
|
|
|
.BR d ,
|
|
|
|
.BR i ,
|
|
|
|
.BR o ,
|
|
|
|
.BR u ,
|
|
|
|
.BR x ,
|
|
|
|
.BR X ,
|
|
|
|
.BR a ,
|
|
|
|
.BR A ,
|
|
|
|
.BR e ,
|
|
|
|
.BR E ,
|
|
|
|
.BR f ,
|
|
|
|
.BR F ,
|
|
|
|
.BR g ,
|
|
|
|
and
|
|
|
|
.B G
|
|
|
|
conversions, the converted value is padded on the left with zeros rather
|
|
|
|
than blanks.
|
|
|
|
If the
|
|
|
|
.B \&0
|
|
|
|
and
|
|
|
|
.B \-
|
|
|
|
flags both appear, the
|
|
|
|
.B \&0
|
|
|
|
flag is ignored.
|
|
|
|
If a precision is given with a numeric conversion
|
|
|
|
.BR "" ( d ,
|
|
|
|
.BR i ,
|
|
|
|
.BR o ,
|
|
|
|
.BR u ,
|
|
|
|
.BR x ,
|
|
|
|
and
|
|
|
|
.BR X ),
|
|
|
|
the
|
|
|
|
.B \&0
|
|
|
|
flag is ignored.
|
|
|
|
For other conversions, the behavior is undefined.
|
|
|
|
.TP
|
|
|
|
.B \-
|
|
|
|
The converted value is to be left adjusted on the field boundary.
|
|
|
|
(The default is right justification.) Except for
|
|
|
|
.B n
|
|
|
|
conversions, the converted value is padded on the right with blanks, rather
|
|
|
|
than on the left with blanks or zeros. A
|
|
|
|
.B \-
|
|
|
|
overrides a
|
|
|
|
.B \&0
|
|
|
|
if both are given.
|
|
|
|
.TP
|
|
|
|
.B ' '
|
|
|
|
(a space) A blank should be left before a positive number
|
|
|
|
(or empty string) produced by a signed conversion.
|
|
|
|
.TP
|
|
|
|
.B +
|
2005-07-14 13:49:21 +00:00
|
|
|
A sign (+ or \-) should always be placed before a number produced by a signed
|
2004-11-03 13:51:07 +00:00
|
|
|
conversion. By default a sign is used only for negative numbers. A
|
|
|
|
.B +
|
|
|
|
overrides a space if both are used.
|
|
|
|
.PP
|
|
|
|
The five flag characters above are defined in the C standard.
|
|
|
|
The SUSv2 specifies one further flag character.
|
|
|
|
.TP
|
|
|
|
.B '
|
|
|
|
For decimal conversion
|
|
|
|
.BR "" ( i ,
|
|
|
|
.BR d ,
|
|
|
|
.BR u ,
|
|
|
|
.BR f ,
|
|
|
|
.BR F ,
|
|
|
|
.BR g ,
|
|
|
|
.BR G )
|
|
|
|
the output is to be grouped with thousands' grouping characters
|
|
|
|
if the locale information indicates any. Note that many versions of
|
2005-11-02 13:55:25 +00:00
|
|
|
.BR gcc (1)
|
2004-11-03 13:51:07 +00:00
|
|
|
cannot parse this option and will issue a warning. SUSv2 does not
|
|
|
|
include %'F.
|
|
|
|
.PP
|
|
|
|
glibc 2.2 adds one further flag character.
|
|
|
|
.TP
|
|
|
|
.B I
|
|
|
|
For decimal integer conversion
|
|
|
|
.BR "" ( i ,
|
|
|
|
.BR d ,
|
|
|
|
.BR u )
|
|
|
|
the output uses the locale's alternative output digits, if any.
|
|
|
|
For example, since glibc 2.2.3 this will give Arabic-Indic digits
|
|
|
|
in the Persian (`fa_IR') locale.
|
|
|
|
.\" outdigits keyword in locale file
|
|
|
|
.SS "The field width"
|
2005-06-15 13:32:34 +00:00
|
|
|
An optional decimal digit string (with non-zero first digit) specifying
|
2004-11-03 13:51:07 +00:00
|
|
|
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).
|
|
|
|
Instead of a decimal digit string one may write `*' or `*m$'
|
|
|
|
(for some decimal integer m) to specify that the field width
|
|
|
|
is given in the next argument, or in the m-th argument, respectively,
|
|
|
|
which must be of type
|
|
|
|
.IR int .
|
2005-07-07 08:27:03 +00:00
|
|
|
A negative field width is taken as a `\-' flag followed by a
|
2004-11-03 13:51:07 +00:00
|
|
|
positive field width.
|
|
|
|
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.
|
|
|
|
.SS "The precision"
|
|
|
|
An optional precision, in the form of a period (`\&.') followed by an
|
|
|
|
optional decimal digit string.
|
|
|
|
Instead of a decimal digit string one may write `*' or `*m$'
|
|
|
|
(for some decimal integer m) to specify that the precision
|
|
|
|
is given in the next argument, or in the m-th argument, respectively,
|
|
|
|
which must be of type
|
|
|
|
.IR int .
|
|
|
|
If the precision is given as just `.', or the precision is negative,
|
|
|
|
the precision is taken to be zero.
|
|
|
|
This gives the minimum number of digits to appear for
|
|
|
|
.BR d ,
|
|
|
|
.BR i ,
|
|
|
|
.BR o ,
|
|
|
|
.BR u ,
|
|
|
|
.BR x ,
|
|
|
|
and
|
|
|
|
.B X
|
|
|
|
conversions, the number of digits to appear after the radix character for
|
|
|
|
.BR a ,
|
|
|
|
.BR A ,
|
|
|
|
.BR e ,
|
|
|
|
.BR E ,
|
|
|
|
.BR f ,
|
|
|
|
and
|
|
|
|
.B F
|
|
|
|
conversions, the maximum number of significant digits for
|
|
|
|
.B g
|
|
|
|
and
|
|
|
|
.B G
|
|
|
|
conversions, or the maximum number of characters to be printed from a
|
|
|
|
string for
|
|
|
|
.B s
|
|
|
|
and
|
|
|
|
.B S
|
|
|
|
conversions.
|
|
|
|
.SS "The length modifier"
|
|
|
|
Here, `integer conversion' stands for
|
|
|
|
.BR d ,
|
|
|
|
.BR i ,
|
|
|
|
.BR o ,
|
|
|
|
.BR u ,
|
|
|
|
.BR x ,
|
|
|
|
or
|
|
|
|
.BR X
|
|
|
|
conversion.
|
|
|
|
.TP
|
|
|
|
.B hh
|
|
|
|
A following integer conversion corresponds to a
|
|
|
|
.I signed char
|
|
|
|
or
|
|
|
|
.I unsigned char
|
|
|
|
argument, or a following
|
|
|
|
.B n
|
|
|
|
conversion corresponds to a pointer to a
|
|
|
|
.I signed char
|
|
|
|
argument.
|
|
|
|
.TP
|
|
|
|
.B h
|
|
|
|
A following integer conversion corresponds to a
|
|
|
|
.I short int
|
|
|
|
or
|
|
|
|
.I unsigned short int
|
|
|
|
argument, or a following
|
|
|
|
.B n
|
|
|
|
conversion corresponds to a pointer to a
|
|
|
|
.I short int
|
|
|
|
argument.
|
|
|
|
.TP
|
|
|
|
.B l
|
|
|
|
(ell) A following integer conversion corresponds to a
|
|
|
|
.I long int
|
|
|
|
or
|
|
|
|
.I unsigned long int
|
|
|
|
argument, or a following
|
|
|
|
.B n
|
|
|
|
conversion corresponds to a pointer to a
|
|
|
|
.I long int
|
|
|
|
argument, or a following
|
|
|
|
.B c
|
|
|
|
conversion corresponds to a
|
|
|
|
.I wint_t
|
|
|
|
argument, or a following
|
|
|
|
.B s
|
|
|
|
conversion corresponds to a pointer to
|
|
|
|
.I wchar_t
|
|
|
|
argument.
|
|
|
|
.TP
|
|
|
|
.B ll
|
|
|
|
(ell-ell).
|
|
|
|
A following integer conversion corresponds to a
|
|
|
|
.I long long int
|
|
|
|
or
|
|
|
|
.I unsigned long long int
|
|
|
|
argument, or a following
|
|
|
|
.B n
|
|
|
|
conversion corresponds to a pointer to a
|
|
|
|
.I long long int
|
|
|
|
argument.
|
|
|
|
.TP
|
|
|
|
.BR L
|
|
|
|
A following
|
|
|
|
.BR a ,
|
|
|
|
.BR A ,
|
|
|
|
.BR e ,
|
|
|
|
.BR E ,
|
|
|
|
.BR f ,
|
|
|
|
.BR F ,
|
|
|
|
.BR g ,
|
|
|
|
or
|
|
|
|
.B G
|
|
|
|
conversion corresponds to a
|
|
|
|
.I long double
|
|
|
|
argument.
|
|
|
|
(C99 allows %LF, but SUSv2 does not.)
|
|
|
|
.TP
|
|
|
|
.B q
|
2005-07-18 15:05:56 +00:00
|
|
|
(`quad'. 4.4BSD and Linux libc5 only. Don't use.)
|
2004-11-03 13:51:07 +00:00
|
|
|
This is a synonym for
|
|
|
|
.BR ll .
|
|
|
|
.TP
|
|
|
|
.B j
|
|
|
|
A following integer conversion corresponds to an
|
|
|
|
.I intmax_t
|
|
|
|
or
|
|
|
|
.I uintmax_t
|
|
|
|
argument.
|
|
|
|
.TP
|
|
|
|
.B z
|
|
|
|
A following integer conversion corresponds to a
|
|
|
|
.I size_t
|
|
|
|
or
|
|
|
|
.I ssize_t
|
|
|
|
argument. (Linux libc5 has
|
|
|
|
.B Z
|
|
|
|
with this meaning. Don't use it.)
|
|
|
|
.TP
|
|
|
|
.B t
|
|
|
|
A following integer conversion corresponds to a
|
|
|
|
.I ptrdiff_t
|
|
|
|
argument.
|
|
|
|
.PP
|
|
|
|
The SUSv2 only knows about the length modifiers
|
|
|
|
.B h
|
|
|
|
(in
|
|
|
|
.BR hd ,
|
|
|
|
.BR hi ,
|
|
|
|
.BR ho ,
|
|
|
|
.BR hx ,
|
|
|
|
.BR hX ,
|
|
|
|
.BR hn )
|
|
|
|
and
|
|
|
|
.B l
|
|
|
|
(in
|
|
|
|
.BR ld ,
|
|
|
|
.BR li ,
|
|
|
|
.BR lo ,
|
|
|
|
.BR lx ,
|
|
|
|
.BR lX ,
|
|
|
|
.BR ln ,
|
|
|
|
.BR lc ,
|
|
|
|
.BR ls )
|
|
|
|
and
|
|
|
|
.B L
|
|
|
|
(in
|
|
|
|
.BR Le ,
|
|
|
|
.BR LE ,
|
|
|
|
.BR Lf ,
|
|
|
|
.BR Lg ,
|
|
|
|
.BR LG ).
|
|
|
|
|
|
|
|
.SS "The conversion specifier"
|
|
|
|
A character that specifies the type of conversion to be applied.
|
|
|
|
The conversion specifiers and their meanings are:
|
|
|
|
.TP
|
|
|
|
.BR d , i
|
|
|
|
The
|
|
|
|
.I int
|
|
|
|
argument is converted to signed decimal notation.
|
|
|
|
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 default precision is 1.
|
|
|
|
When 0 is printed with an explicit precision 0, the output is empty.
|
|
|
|
.TP
|
|
|
|
.BR o , u , x , X
|
|
|
|
The
|
|
|
|
.I "unsigned int"
|
|
|
|
argument is converted to unsigned octal
|
|
|
|
.BR "" ( o ),
|
|
|
|
unsigned decimal
|
|
|
|
.BR "" ( u ),
|
|
|
|
or unsigned hexadecimal
|
|
|
|
.BR "" ( x
|
|
|
|
and
|
|
|
|
.BR X )
|
|
|
|
notation. The letters
|
|
|
|
.B abcdef
|
|
|
|
are used for
|
|
|
|
.B x
|
|
|
|
conversions; the letters
|
|
|
|
.B ABCDEF
|
|
|
|
are used for
|
|
|
|
.B 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 default precision is 1.
|
|
|
|
When 0 is printed with an explicit precision 0, the output is empty.
|
|
|
|
.TP
|
|
|
|
.BR e , E
|
|
|
|
The
|
|
|
|
.I double
|
|
|
|
argument is rounded and converted in the style
|
|
|
|
.if \w'\*(Pm'=0 .ds Pm \(+-
|
|
|
|
.BR "" [\-]d \&. ddd e \\*(Pmdd
|
|
|
|
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
|
|
|
|
.B E
|
|
|
|
conversion uses the letter
|
|
|
|
.B E
|
|
|
|
(rather than
|
|
|
|
.BR e )
|
|
|
|
to introduce the exponent. The exponent always contains at least two
|
|
|
|
digits; if the value is zero, the exponent is 00.
|
|
|
|
.TP
|
|
|
|
.BR f , F
|
|
|
|
The
|
|
|
|
.I double
|
|
|
|
argument is rounded and converted to decimal notation in the style
|
|
|
|
.BR "" [\-]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.
|
|
|
|
|
|
|
|
(The SUSv2 does not know about
|
|
|
|
.B F
|
|
|
|
and says that character string representations for infinity and NaN
|
2005-07-07 08:27:03 +00:00
|
|
|
may be made available. The C99 standard specifies `[\-]inf' or `[\-]infinity'
|
2004-11-03 13:51:07 +00:00
|
|
|
for infinity, and a string starting with `nan' for NaN, in the case of
|
|
|
|
.B f
|
2005-07-07 08:27:03 +00:00
|
|
|
conversion, and `[\-]INF' or `[\-]INFINITY' or `NAN*' in the case of
|
2004-11-03 13:51:07 +00:00
|
|
|
.B F
|
|
|
|
conversion.)
|
|
|
|
.TP
|
|
|
|
.BR g , G
|
|
|
|
The
|
|
|
|
.I double
|
|
|
|
argument is converted in style
|
|
|
|
.B f
|
|
|
|
or
|
|
|
|
.B e
|
|
|
|
(or
|
|
|
|
.B F
|
|
|
|
or
|
|
|
|
.B E
|
|
|
|
for
|
|
|
|
.B 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
|
|
|
|
.B 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.
|
|
|
|
.TP
|
|
|
|
.BR a , A
|
|
|
|
(C99; not in SUSv2) For
|
|
|
|
.B a
|
|
|
|
conversion, the
|
|
|
|
.I double
|
|
|
|
argument is converted to hexadecimal notation (using the letters abcdef)
|
|
|
|
in the style
|
2005-07-07 08:27:03 +00:00
|
|
|
.BR "" [\-] 0x h \&. hhhh p \\*(Pmd;
|
2004-11-03 13:51:07 +00:00
|
|
|
for
|
|
|
|
.B A
|
|
|
|
conversion the prefix
|
|
|
|
.BR 0X ,
|
|
|
|
the letters ABCDEF, and the exponent separator
|
|
|
|
.B P
|
|
|
|
is used.
|
|
|
|
There is one hexadecimal digit before the decimal point,
|
|
|
|
and the number of digits after it is equal to the precision.
|
|
|
|
The default precision suffices for an exact representation of the value
|
|
|
|
if an exact representation in base 2 exists
|
|
|
|
and otherwise is sufficiently large to distinguish values of type
|
|
|
|
.IR double .
|
|
|
|
The digit before the decimal point is unspecified for non-normalized
|
2005-06-15 13:32:34 +00:00
|
|
|
numbers, and non-zero but otherwise unspecified for normalized numbers.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B c
|
|
|
|
If no
|
|
|
|
.B l
|
|
|
|
modifier is present, the
|
|
|
|
.I int
|
|
|
|
argument is converted to an
|
|
|
|
.IR "unsigned char" ,
|
|
|
|
and the resulting character is written.
|
|
|
|
If an
|
|
|
|
.B l
|
|
|
|
modifier is present, the
|
|
|
|
.I wint_t
|
|
|
|
(wide character) argument is converted to a multibyte sequence by a call
|
|
|
|
to the
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR wcrtomb ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function, with a conversion state starting in the initial state, and the
|
|
|
|
resulting multibyte string is written.
|
|
|
|
.TP
|
|
|
|
.B s
|
|
|
|
If no
|
|
|
|
.B l
|
|
|
|
modifier is present: The
|
|
|
|
.I "const 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
|
2006-01-13 02:09:44 +00:00
|
|
|
including) a terminating null byte ('\\0');
|
|
|
|
if a precision is specified, no more than the number specified
|
|
|
|
are written. If a precision is given, no null byte need be present;
|
2004-11-03 13:51:07 +00:00
|
|
|
if the precision is not specified, or is greater than the size of the
|
2006-01-13 02:09:44 +00:00
|
|
|
array, the array must contain a terminating null byte.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
If an
|
|
|
|
.B l
|
|
|
|
modifier is present: The
|
|
|
|
.I "const wchar_t *"
|
|
|
|
argument is expected to be a pointer to an array of wide characters.
|
|
|
|
Wide characters from the array are converted to multibyte characters
|
|
|
|
(each by a call to the
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR wcrtomb ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function, with a conversion state starting in the initial state before
|
|
|
|
the first wide character), up to and including a terminating null
|
|
|
|
wide character. The resulting multibyte characters are written up to
|
|
|
|
(but not including) the terminating null byte. If a precision is
|
|
|
|
specified, no more bytes than the number specified are written, but
|
|
|
|
no partial multibyte characters are written. Note that the precision
|
|
|
|
determines the number of
|
|
|
|
.I bytes
|
|
|
|
written, not the number of
|
|
|
|
.I wide characters
|
|
|
|
or
|
|
|
|
.IR "screen positions" .
|
|
|
|
The array must contain a terminating null wide character, unless a
|
|
|
|
precision is given and it is so small that the number of bytes written
|
|
|
|
exceeds it before the end of the array is reached.
|
|
|
|
.TP
|
|
|
|
.B C
|
|
|
|
(Not in C99, but in SUSv2.)
|
|
|
|
Synonym for
|
|
|
|
.BR lc .
|
|
|
|
Don't use.
|
|
|
|
.TP
|
|
|
|
.B S
|
|
|
|
(Not in C99, but in SUSv2.)
|
|
|
|
Synonym for
|
|
|
|
.BR ls .
|
|
|
|
Don't use.
|
|
|
|
.TP
|
|
|
|
.B p
|
|
|
|
The
|
|
|
|
.I "void *"
|
|
|
|
pointer argument is printed in hexadecimal (as if by
|
|
|
|
.B %#x
|
|
|
|
or
|
|
|
|
.BR %#lx ).
|
|
|
|
.TP
|
|
|
|
.B n
|
|
|
|
The number of characters written so far is stored into the integer
|
|
|
|
indicated by the
|
|
|
|
.I "int *"
|
|
|
|
(or variant) pointer argument. No argument is converted.
|
2006-06-07 22:45:42 +00:00
|
|
|
.TP
|
|
|
|
.B m
|
|
|
|
(Glibc extension.) Print output of
|
|
|
|
.IR strerror(errno) .
|
|
|
|
No argument is required.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B %
|
|
|
|
A `%' is written. No argument is converted. The complete conversion
|
|
|
|
specification is `%%'.
|
|
|
|
.PP
|
2006-05-22 19:44:47 +00:00
|
|
|
.SH EXAMPLE
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
.if \w'\*(Pi'=0 .ds Pi pi
|
|
|
|
To print \*(Pi to five decimal places:
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
#include <math.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
To print a date and time in the form `Sunday, July 3, 10:02',
|
|
|
|
where
|
|
|
|
.I weekday
|
|
|
|
and
|
|
|
|
.I month
|
|
|
|
are pointers to strings:
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
|
|
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
|
|
|
|
weekday, month, day, hour, min);
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
Many countries use the day-month-year order.
|
|
|
|
Hence, an internationalized version must be able to print
|
|
|
|
the arguments in an order specified by the format:
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
|
|
fprintf(stdout, format,
|
|
|
|
weekday, month, day, hour, min);
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
where
|
|
|
|
.I format
|
|
|
|
depends on locale, and may permute the arguments. With the value
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
one might obtain `Sonntag, 3. Juli, 10:02'.
|
|
|
|
.PP
|
|
|
|
To allocate a sufficiently large string and print into it
|
|
|
|
(code correct for both glibc 2.0 and glibc 2.1):
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <stdarg.h>
|
2004-12-14 18:25:46 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
char *
|
|
|
|
make_message(const char *fmt, ...) {
|
|
|
|
/* Guess we need no more than 100 bytes. */
|
|
|
|
int n, size = 100;
|
2004-12-14 18:25:46 +00:00
|
|
|
char *p, *np;
|
2004-11-03 13:51:07 +00:00
|
|
|
va_list ap;
|
2004-12-14 18:25:46 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
if ((p = malloc (size)) == NULL)
|
|
|
|
return NULL;
|
2004-12-14 18:25:46 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
while (1) {
|
|
|
|
/* Try to print in the allocated space. */
|
|
|
|
va_start(ap, fmt);
|
|
|
|
n = vsnprintf (p, size, fmt, ap);
|
|
|
|
va_end(ap);
|
|
|
|
/* If that worked, return the string. */
|
2005-07-06 12:57:38 +00:00
|
|
|
if (n > \-1 && n < size)
|
2004-11-03 13:51:07 +00:00
|
|
|
return p;
|
|
|
|
/* Else try again with more space. */
|
2005-07-06 12:57:38 +00:00
|
|
|
if (n > \-1) /* glibc 2.1 */
|
2004-11-03 13:51:07 +00:00
|
|
|
size = n+1; /* precisely what is needed */
|
|
|
|
else /* glibc 2.0 */
|
|
|
|
size *= 2; /* twice the old size */
|
2004-12-14 18:25:46 +00:00
|
|
|
if ((np = realloc (p, size)) == NULL) {
|
|
|
|
free(p);
|
2004-11-03 13:51:07 +00:00
|
|
|
return NULL;
|
2004-12-14 18:25:46 +00:00
|
|
|
} else {
|
|
|
|
p = np;
|
|
|
|
}
|
2004-11-03 13:51:07 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
|
|
|
|
.SH NOTES
|
|
|
|
The glibc implementation of the functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsnprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
conforms to the C99 standard, i.e., behaves as described above,
|
|
|
|
since glibc version 2.1. Until glibc 2.0.6 they would return \-1
|
|
|
|
when the output was truncated.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR fprintf (),
|
|
|
|
.BR printf (),
|
|
|
|
.BR sprintf (),
|
|
|
|
.BR vprintf (),
|
|
|
|
.BR vfprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsprintf ()
|
2006-08-03 13:57:30 +00:00
|
|
|
functions conform to C89 and C99.
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsnprintf ()
|
2006-08-03 13:57:30 +00:00
|
|
|
functions conform to C99.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Concerning the return value of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf (),
|
2006-08-03 13:57:30 +00:00
|
|
|
SUSv2 and C99 contradict each other: when
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is called with
|
|
|
|
.IR size =0
|
|
|
|
then SUSv2 stipulates an unspecified return value less than 1,
|
|
|
|
while C99 allows
|
|
|
|
.I str
|
|
|
|
to be NULL in this case, and gives the return value (as always)
|
|
|
|
as the number of characters that would have been written in case
|
|
|
|
the output string has been large enough.
|
|
|
|
.PP
|
|
|
|
Linux libc4 knows about the five C standard flags.
|
|
|
|
It knows about the length modifiers h,l,L, and the conversions
|
|
|
|
cdeEfFgGinopsuxX, where F is a synonym for f.
|
|
|
|
Additionally, it accepts D,O,U as synonyms for ld,lo,lu.
|
|
|
|
(This is bad, and caused serious bugs later, when
|
|
|
|
support for %D disappeared.) No locale-dependent radix character,
|
|
|
|
no thousands' separator, no NaN or infinity, no %m$ and *m$.
|
|
|
|
.PP
|
|
|
|
Linux libc5 knows about the five C standard flags and the ' flag,
|
|
|
|
locale, %m$ and *m$.
|
|
|
|
It knows about the length modifiers h,l,L,Z,q, but accepts L and q
|
|
|
|
both for long doubles and for long long integers (this is a bug).
|
2006-06-07 22:45:42 +00:00
|
|
|
It no longer recognizes FDOU, but adds the conversion character
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR m ,
|
|
|
|
which outputs
|
|
|
|
.IR strerror(errno) .
|
|
|
|
.PP
|
|
|
|
glibc 2.0 adds conversion characters C and S.
|
|
|
|
.PP
|
|
|
|
glibc 2.1 adds length modifiers hh,j,t,z and conversion characters a,A.
|
|
|
|
.PP
|
|
|
|
glibc 2.2 adds the conversion character F with C99 semantics, and the
|
|
|
|
flag character I.
|
|
|
|
.SH HISTORY
|
|
|
|
Unix V7 defines the three routines
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR printf (),
|
|
|
|
.BR fprintf (),
|
|
|
|
.BR sprintf (),
|
2005-07-06 08:00:30 +00:00
|
|
|
and has the flag \-, the width or precision *, the length modifier l,
|
2004-11-03 13:51:07 +00:00
|
|
|
and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
|
2005-07-18 15:05:56 +00:00
|
|
|
This is still true for 2.9.1BSD, but 2.10BSD has the flags
|
2004-11-03 13:51:07 +00:00
|
|
|
#, + and <space> and no longer mentions D,O,U,X.
|
2005-07-18 15:05:56 +00:00
|
|
|
2.11BSD has
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vprintf (),
|
|
|
|
.BR vfprintf (),
|
|
|
|
.BR vsprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and warns not to use D,O,U,X.
|
2005-07-18 15:05:56 +00:00
|
|
|
4.3BSD Reno has the flag 0, the length modifiers h and L,
|
2004-11-03 13:51:07 +00:00
|
|
|
and the conversions n, p, E, G, X (with current meaning)
|
|
|
|
and deprecates D,O,U.
|
2005-07-18 15:05:56 +00:00
|
|
|
4.4BSD introduces the functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsnprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and the length modifier q.
|
|
|
|
FreeBSD also has functions
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR asprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR vasprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
that allocate a buffer large enough for
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sprintf ().
|
2004-11-03 13:51:07 +00:00
|
|
|
In glibc there are functions
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR dprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR vdprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
that print to a file descriptor instead of a stream.
|
|
|
|
.SH BUGS
|
|
|
|
Because
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
assume an arbitrarily long string, callers must be careful not to overflow
|
|
|
|
the actual space; this is often impossible to assure. Note that the length
|
|
|
|
of the strings produced is locale-dependent and difficult to predict.
|
|
|
|
Use
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR vsnprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
instead (or
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR asprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
|
|
|
.BR vasprintf ).
|
|
|
|
.PP
|
|
|
|
Linux libc4.[45] does not have a
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
but provides a libbsd that contains an
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
equivalent to
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sprintf (),
|
2004-11-03 13:51:07 +00:00
|
|
|
i.e., one that ignores the
|
|
|
|
.I size
|
|
|
|
argument.
|
|
|
|
Thus, the use of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR snprintf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
with early libc4 leads to serious security problems.
|
|
|
|
.PP
|
|
|
|
Code such as
|
|
|
|
.BI printf( foo );
|
|
|
|
often indicates a bug, since
|
|
|
|
.I foo
|
|
|
|
may contain a % character. If
|
|
|
|
.I foo
|
|
|
|
comes from untrusted user input, it may contain %n, causing the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR printf ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call to write to memory and creating a security hole.
|
|
|
|
.\" .PP
|
|
|
|
.\" Some floating point conversions under early libc4
|
|
|
|
.\" caused memory leaks.
|
|
|
|
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR printf (1),
|
|
|
|
.BR asprintf (3),
|
|
|
|
.BR dprintf (3),
|
|
|
|
.BR scanf (3),
|
2006-05-01 01:52:57 +00:00
|
|
|
.BR setlocale (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR wcrtomb (3),
|
|
|
|
.BR wprintf (3),
|
|
|
|
.BR locale (5)
|