1124 lines
27 KiB
Groff
1124 lines
27 KiB
Groff
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
.\" 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, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2014-07-08 "GNU" "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 );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.ad l
|
|
.BR snprintf (),
|
|
.BR vsnprintf ():
|
|
.RS 4
|
|
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
|
|
_POSIX_C_SOURCE\ >=\ 200112L;
|
|
.br
|
|
or
|
|
.I "cc -std=c99"
|
|
.RE
|
|
.ad
|
|
.SH DESCRIPTION
|
|
The functions in the
|
|
.BR printf ()
|
|
family produce output according to a
|
|
.I format
|
|
as described below.
|
|
The functions
|
|
.BR printf ()
|
|
and
|
|
.BR vprintf ()
|
|
write output to
|
|
.IR stdout ,
|
|
the standard output stream;
|
|
.BR fprintf ()
|
|
and
|
|
.BR vfprintf ()
|
|
write output to the given output
|
|
.IR stream ;
|
|
.BR sprintf (),
|
|
.BR snprintf (),
|
|
.BR vsprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
write to the character string
|
|
.IR str .
|
|
.PP
|
|
The functions
|
|
.BR snprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
write at most
|
|
.I size
|
|
bytes (including the terminating null byte (\(aq\e0\(aq)) to
|
|
.IR str .
|
|
.PP
|
|
The functions
|
|
.BR vprintf (),
|
|
.BR vfprintf (),
|
|
.BR vsprintf (),
|
|
.BR vsnprintf ()
|
|
are equivalent to the functions
|
|
.BR printf (),
|
|
.BR fprintf (),
|
|
.BR sprintf (),
|
|
.BR snprintf (),
|
|
respectively, except that they are called with a
|
|
.I va_list
|
|
instead of a variable number of arguments.
|
|
These functions do not call the
|
|
.I va_end
|
|
macro.
|
|
Because they invoke the
|
|
.I va_arg
|
|
macro, the value of
|
|
.I ap
|
|
is undefined after the call.
|
|
See
|
|
.BR stdarg (3).
|
|
.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.
|
|
|
|
C99 and POSIX.1-2001 specify that the results are undefined if a call to
|
|
.BR sprintf (),
|
|
.BR snprintf (),
|
|
.BR vsprintf (),
|
|
or
|
|
.BR vsnprintf ()
|
|
would cause copying to take place between objects that overlap
|
|
(e.g., if the target string array and one of the supplied input arguments
|
|
refer to the same buffer).
|
|
See NOTES.
|
|
.SS Return value
|
|
Upon successful return, these functions return the number of characters
|
|
printed (excluding the null byte used to end output to strings).
|
|
|
|
The functions
|
|
.BR snprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
do not write more than
|
|
.I size
|
|
bytes (including the terminating null byte (\(aq\e0\(aq)).
|
|
If the output was truncated due to this limit, then the return value
|
|
is the number of characters (excluding the terminating null byte)
|
|
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 \(aq*\(aq 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 \(aq%\(aq and "*m$" instead of \(aq*\(aq,
|
|
where the decimal integer m denotes
|
|
the position in the argument list of the desired argument, indexed starting
|
|
from 1.
|
|
Thus,
|
|
.in +4n
|
|
.nf
|
|
|
|
printf("%*d", width, num);
|
|
|
|
.fi
|
|
.in
|
|
and
|
|
.in +4n
|
|
.nf
|
|
|
|
printf("%2$*1$d", width, num);
|
|
|
|
.fi
|
|
.in
|
|
are equivalent.
|
|
The second style allows repeated references to the
|
|
same argument.
|
|
The C99 standard does not include the style using \(aq$\(aq,
|
|
which comes from the Single UNIX Specification.
|
|
If the style using
|
|
\(aq$\(aq 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 \(aq$\(aq; 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
|
|
.B LC_NUMERIC
|
|
part of the locale.
|
|
The POSIX locale
|
|
uses \(aq.\(aq as radix character, and does not have a grouping character.
|
|
Thus,
|
|
.in +4n
|
|
.nf
|
|
|
|
printf("%\(aq.2f", 1234567.89);
|
|
|
|
.fi
|
|
.in
|
|
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
|
|
.B 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 nonzero 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
|
|
.RB ( 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.)
|
|
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 \(aq \(aq
|
|
(a space) A blank should be left before a positive number
|
|
(or empty string) produced by a signed conversion.
|
|
.TP
|
|
.B +
|
|
A sign (+ or \-) should always be placed before a number produced by a signed
|
|
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 C99 standard.
|
|
The Single UNIX Specification specifies one further flag character.
|
|
.TP
|
|
.B \(aq
|
|
For decimal conversion
|
|
.RB ( 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
|
|
.BR gcc (1)
|
|
cannot parse this option and will issue a warning.
|
|
(SUSv2 did not
|
|
include \fI%\(aqF\fP, but SUSv3 added it.)
|
|
.PP
|
|
glibc 2.2 adds one further flag character.
|
|
.TP
|
|
.B I
|
|
For decimal integer conversion
|
|
.RB ( 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
|
|
An optional decimal digit string (with nonzero first digit) 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).
|
|
Instead of a decimal digit string one may write "*" or "*m$"
|
|
(for some decimal integer \fIm\fP) to specify that the field width
|
|
is given in the next argument, or in the \fIm\fP-th argument, respectively,
|
|
which must be of type
|
|
.IR int .
|
|
A negative field width is taken as a \(aq\-\(aq flag followed by a
|
|
positive field width.
|
|
In no case does a nonexistent 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 (\(aq.\(aq) 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 \(aq.\(aq, the precision is taken to
|
|
be zero.
|
|
A negative precision is taken as if the precision were omitted.
|
|
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
|
|
.B 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
|
|
.B 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
|
|
.\" ("quad". 4.4BSD and Linux libc5 only.
|
|
.\" Don't use.)
|
|
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, or a following
|
|
.B n
|
|
conversion corresponds to a pointer to an
|
|
.I intmax_t
|
|
argument.
|
|
.TP
|
|
.B z
|
|
A following integer conversion corresponds to a
|
|
.I size_t
|
|
or
|
|
.I ssize_t
|
|
argument, or a following
|
|
.B n
|
|
conversion corresponds to a pointer to a
|
|
.I size_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, or a following
|
|
.B n
|
|
conversion corresponds to a pointer to a
|
|
.I ptrdiff_t
|
|
argument.
|
|
.PP
|
|
SUSv3 specifies all of the above.
|
|
SUSv2 specified only 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
|
|
.RB ( o ),
|
|
unsigned decimal
|
|
.RB ( u ),
|
|
or unsigned hexadecimal
|
|
.RB ( 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
|
|
.RB [\-]d \&. ddd e \(+-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
|
|
.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
|
|
.RB [\-]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.
|
|
|
|
(SUSv2 does not know about
|
|
.B F
|
|
and says that character string representations for infinity and NaN
|
|
may be made available.
|
|
SUSv3 adds a specification for
|
|
.BR F .
|
|
The C99 standard specifies "[\-]inf" or "[\-]infinity"
|
|
for infinity, and a string starting with "nan" for NaN, in the case of
|
|
.B f
|
|
conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN*" in the case of
|
|
.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, but added in SUSv3)
|
|
For
|
|
.B a
|
|
conversion, the
|
|
.I double
|
|
argument is converted to hexadecimal notation (using the letters abcdef)
|
|
in the style
|
|
.RB [\-] 0x h \&. hhhh p \(+-;
|
|
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 nonnormalized
|
|
numbers, and nonzero but otherwise unspecified for normalized numbers.
|
|
.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
|
|
.BR wcrtomb (3)
|
|
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
|
|
including) a terminating null byte (\(aq\\0\(aq);
|
|
if a precision is specified, no more than the number specified
|
|
are written.
|
|
If a precision is given, no null byte need be present;
|
|
if the precision is not specified, or is greater than the size of the
|
|
array, the array must contain a terminating null byte.
|
|
|
|
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
|
|
.BR wcrtomb (3)
|
|
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 or C11, but in SUSv2, SUSv3, and SUSv4.)
|
|
Synonym for
|
|
.BR lc .
|
|
Don't use.
|
|
.TP
|
|
.B S
|
|
(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
|
|
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
|
|
pointed to by the corresponding argument.
|
|
That argument shall be an
|
|
.I "int\ *",
|
|
or variant whose size matches the (optionally)
|
|
supplied integer length modifier.
|
|
No argument is converted.
|
|
The behavior is undefined if the conversion specification includes
|
|
any flags, a field width, or a precision.
|
|
.TP
|
|
.B m
|
|
(Glibc extension.)
|
|
Print output of
|
|
.IR strerror(errno) .
|
|
No argument is required.
|
|
.TP
|
|
.B %
|
|
A \(aq%\(aq is written.
|
|
No argument is converted.
|
|
The complete conversion
|
|
specification is \(aq%%\(aq.
|
|
.SH CONFORMING TO
|
|
The
|
|
.BR fprintf (),
|
|
.BR printf (),
|
|
.BR sprintf (),
|
|
.BR vprintf (),
|
|
.BR vfprintf (),
|
|
and
|
|
.BR vsprintf ()
|
|
functions conform to C89 and C99.
|
|
The
|
|
.BR snprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
functions conform to C99.
|
|
.PP
|
|
Concerning the return value of
|
|
.BR snprintf (),
|
|
SUSv2 and C99 contradict each other: when
|
|
.BR snprintf ()
|
|
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.
|
|
SUSv3 and later align their specification of
|
|
.BR snprintf ()
|
|
with C99.
|
|
.\" .PP
|
|
.\" Linux libc4 knows about the five C standard flags.
|
|
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
|
|
.\" and the conversions
|
|
.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
|
|
.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
|
|
.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
|
|
.\" where \fBF\fP is a synonym for \fBf\fP.
|
|
.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
|
|
.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
|
|
.\" (This is bad, and caused serious bugs later, when
|
|
.\" support for \fB%D\fP 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 \(aq flag,
|
|
.\" locale, "%m$" and "*m$".
|
|
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
|
|
.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
|
|
.\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug).
|
|
.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
|
|
.\" but adds the conversion character
|
|
.\" .BR m ,
|
|
.\" which outputs
|
|
.\" .IR strerror(errno) .
|
|
.\" .PP
|
|
.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
|
|
.PP
|
|
glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
|
|
and conversion characters \fBa\fP and \fBA\fP.
|
|
.PP
|
|
glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
|
|
and the flag character \fBI\fP.
|
|
.SH NOTES
|
|
Some programs imprudently rely on code such as the following
|
|
|
|
sprintf(buf, "%s some further text", buf);
|
|
|
|
to append text to
|
|
.IR buf .
|
|
However, the standards explicitly note that the results are undefined
|
|
if source and destination buffers overlap when calling
|
|
.BR sprintf (),
|
|
.BR snprintf (),
|
|
.BR vsprintf (),
|
|
and
|
|
.BR vsnprintf ().
|
|
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
|
|
Depending on the version of
|
|
.BR gcc (1)
|
|
used, and the compiler options employed, calls such as the above will
|
|
.B not
|
|
produce the expected results.
|
|
|
|
The glibc implementation of the functions
|
|
.BR snprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
conforms to the C99 standard, that is, behaves as described above,
|
|
since glibc version 2.1.
|
|
Until glibc 2.0.6, they would return \-1
|
|
when the output was truncated.
|
|
.\" .SH HISTORY
|
|
.\" UNIX V7 defines the three routines
|
|
.\" .BR printf (),
|
|
.\" .BR fprintf (),
|
|
.\" .BR sprintf (),
|
|
.\" and has the flag \-, the width or precision *, the length modifier l,
|
|
.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
|
|
.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
|
|
.\" #, + and <space> and no longer mentions D,O,U,X.
|
|
.\" 2.11BSD has
|
|
.\" .BR vprintf (),
|
|
.\" .BR vfprintf (),
|
|
.\" .BR vsprintf (),
|
|
.\" and warns not to use D,O,U,X.
|
|
.\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
|
|
.\" and the conversions n, p, E, G, X (with current meaning)
|
|
.\" and deprecates D,O,U.
|
|
.\" 4.4BSD introduces the functions
|
|
.\" .BR snprintf ()
|
|
.\" and
|
|
.\" .BR vsnprintf (),
|
|
.\" and the length modifier q.
|
|
.\" FreeBSD also has functions
|
|
.\" .BR asprintf ()
|
|
.\" and
|
|
.\" .BR vasprintf (),
|
|
.\" that allocate a buffer large enough for
|
|
.\" .BR sprintf ().
|
|
.\" In glibc there are functions
|
|
.\" .BR dprintf ()
|
|
.\" and
|
|
.\" .BR vdprintf ()
|
|
.\" that print to a file descriptor instead of a stream.
|
|
.SH BUGS
|
|
Because
|
|
.BR sprintf ()
|
|
and
|
|
.BR vsprintf ()
|
|
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
|
|
.BR snprintf ()
|
|
and
|
|
.BR vsnprintf ()
|
|
instead (or
|
|
.BR asprintf (3)
|
|
and
|
|
.BR vasprintf (3)).
|
|
.\" .PP
|
|
.\" Linux libc4.[45] does not have a
|
|
.\" .BR snprintf (),
|
|
.\" but provides a libbsd that contains an
|
|
.\" .BR snprintf ()
|
|
.\" equivalent to
|
|
.\" .BR sprintf (),
|
|
.\" that is, one that ignores the
|
|
.\" .I size
|
|
.\" argument.
|
|
.\" Thus, the use of
|
|
.\" .BR snprintf ()
|
|
.\" 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 \fB%n\fP, causing the
|
|
.BR printf ()
|
|
call to write to memory and creating a security hole.
|
|
.\" .PP
|
|
.\" Some floating-point conversions under early libc4
|
|
.\" caused memory leaks.
|
|
.SH EXAMPLE
|
|
To print
|
|
.I Pi
|
|
to five decimal places:
|
|
.in +4n
|
|
.nf
|
|
|
|
#include <math.h>
|
|
#include <stdio.h>
|
|
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
|
|
.fi
|
|
.in
|
|
.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:
|
|
.in +4n
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
|
|
weekday, month, day, hour, min);
|
|
.fi
|
|
.in
|
|
.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:
|
|
.in +4n
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
fprintf(stdout, format,
|
|
weekday, month, day, hour, min);
|
|
|
|
.fi
|
|
.in
|
|
where
|
|
.I format
|
|
depends on locale, and may permute the arguments.
|
|
With the value:
|
|
.in +4n
|
|
.nf
|
|
|
|
"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
|
|
|
|
.fi
|
|
.in
|
|
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):
|
|
.nf
|
|
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <stdarg.h>
|
|
|
|
char *
|
|
make_message(const char *fmt, ...)
|
|
{
|
|
int n;
|
|
int size = 100; /* Guess we need no more than 100 bytes */
|
|
char *p, *np;
|
|
va_list ap;
|
|
|
|
p = malloc(size);
|
|
if (p == NULL)
|
|
return NULL;
|
|
|
|
while (1) {
|
|
|
|
/* Try to print in the allocated space */
|
|
|
|
va_start(ap, fmt);
|
|
n = vsnprintf(p, size, fmt, ap);
|
|
va_end(ap);
|
|
|
|
/* Check error code */
|
|
|
|
if (n < 0) {
|
|
free(p);
|
|
return NULL;
|
|
}
|
|
|
|
/* If that worked, return the string */
|
|
|
|
if (n < size)
|
|
return p;
|
|
|
|
/* Else try again with more space */
|
|
|
|
size = n + 1; /* Precisely what is needed */
|
|
|
|
|
|
np = realloc(p, size);
|
|
if (np == NULL) {
|
|
free(p);
|
|
return NULL;
|
|
} else {
|
|
p = np;
|
|
}
|
|
}
|
|
}
|
|
.fi
|
|
.PP
|
|
If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
|
|
error instead of being handled gracefully.
|
|
.SH SEE ALSO
|
|
.BR printf (1),
|
|
.BR asprintf (3),
|
|
.BR dprintf (3),
|
|
.BR scanf (3),
|
|
.BR setlocale (3),
|
|
.BR wcrtomb (3),
|
|
.BR wprintf (3),
|
|
.BR locale (5)
|
|
.SH COLOPHON
|
|
This page is part of release 3.74 of the Linux
|
|
.I man-pages
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
\%http://www.kernel.org/doc/man\-pages/.
|