.\" 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
.\" 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.
+.\" 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 2010-09-20 "GNU" "Linux Programmer's Manual"
+.TH PRINTF 3 2014-07-08 "GNU" "Linux Programmer's Manual"
.SH NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
vsnprintf \- formatted output conversion
.BR vsnprintf ()
write at most
.I size
-bytes (including the trailing null byte (\(aq\e0\(aq)) to
+bytes (including the terminating null byte (\(aq\e0\(aq)) to
.IR str .
.PP
The functions
(e.g., if the target string array and one of the supplied input arguments
refer to the same buffer).
See NOTES.
-.SS "Return value"
+.SS Return value
Upon successful return, these functions return the number of characters
-printed (not including the
-trailing \(aq\e0\(aq used to end output to strings).
+printed (excluding the null byte used to end output to strings).
The functions
.BR snprintf ()
.BR vsnprintf ()
do not write more than
.I size
-bytes (including the trailing \(aq\e0\(aq).
-If the output was truncated due to this limit then the return value
-is the number of characters (not including the trailing \(aq\e0\(aq)
+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
(See also below under NOTES.)
If an output error is encountered, a negative value is returned.
-.SS "Format of the format string"
+.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
.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"
+.SS The flag characters
The character % is followed by zero or more of the following flags:
.TP
.B #
.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
+The converted value is padded on the right with blanks, rather
than on the left with blanks or zeros.
A
.B \-
.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.
+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
Note that many versions of
.BR gcc (1)
cannot parse this option and will issue a warning.
-SUSv2 does not
-include \fI%\(aqF\fP.
+(SUSv2 did not
+include \fI%\(aqF\fP, but SUSv3 added it.)
.PP
glibc 2.2 adds one further flag character.
.TP
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"
+.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
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"
+.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$"
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, or the precision is negative,
-the precision is taken to be zero.
+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 ,
and
.B S
conversions.
-.SS "The length modifier"
+.SS The length modifier
Here, "integer conversion" stands for
.BR d ,
.BR i ,
.I long double
argument.
(C99 allows %LF, but SUSv2 does not.)
-.TP
-.B q
-("quad". 4.4BSD and Linux libc5 only.
-Don't use.)
+.\" .TP
+.\" .B q
+.\" ("quad". 4.4BSD and Linux libc5 only.
+.\" Don't use.)
This is a synonym for
.BR ll .
.TP
.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
.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.)
+.\" (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
-The SUSv2 only knows about the length modifiers
+SUSv3 specifies all of the above.
+SUSv2 specified only the length modifiers
.B h
(in
.BR hd ,
.BR Lf ,
.BR Lg ,
.BR LG ).
-.SS "The conversion specifier"
+.SS The conversion specifier
A character that specifies the type of conversion to be applied.
The conversion specifiers and their meanings are:
.TP
The
.I double
argument is rounded and converted in the style
-.if \w'\*(Pm'=0 .ds Pm \(+-
-.RB [\-]d \&. ddd e \\*(Pmdd
+.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
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
+(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
followed by at least one digit.
.TP
.BR a ", " A
-(C99; not in SUSv2) For
+(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 \\*(Pmd;
+.RB [\-] 0x h \&. hhhh p \(+-;
for
.B A
conversion the prefix
If no
.B l
modifier is present: The
-.I "const char *"
+.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
If an
.B l
modifier is present: The
-.I "const wchar_t *"
+.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
exceeds it before the end of the array is reached.
.TP
.B C
-(Not in C99, but in SUSv2.)
+(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
Synonym for
.BR lc .
Don't use.
.TP
.B S
-(Not in C99, but in SUSv2.)
+(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.)
Synonym for
.BR ls .
Don't use.
.TP
.B p
The
-.I "void *"
+.I "void\ *"
pointer argument is printed in hexadecimal (as if by
.B %#x
or
-.BR %#lx ).
+.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.
+pointed to by the corresponding argument.
+That argument shall be an
+.IR "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.)
No argument is converted.
The complete conversion
specification is \(aq%%\(aq.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The
.BR fprintf (),
.BR printf (),
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 \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.
+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.
.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
+Until glibc 2.0.6, they would return \-1
when the output was truncated.
.\" .SH HISTORY
.\" UNIX V7 defines the three routines
.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
+.\" 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 );
.\" Some floating-point conversions under early libc4
.\" caused memory leaks.
.SH EXAMPLE
-.if \w'\*(Pi'=0 .ds Pi pi
-To print \*(Pi to five decimal places:
+To print
+.I Pi
+to five decimal places:
.in +4n
.nf
char *
make_message(const char *fmt, ...)
{
- /* Guess we need no more than 100 bytes. */
- int n, size = 100;
+ int n;
+ int size = 100; /* Guess we need no more than 100 bytes */
char *p, *np;
va_list ap;
- if ((p = malloc(size)) == NULL)
+ p = malloc(size);
+ if (p == NULL)
return NULL;
while (1) {
- /* Try to print in the allocated space. */
+
+ /* 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. */
- if (n > \-1 && n < size)
+
+ /* 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. */
- if (n > \-1) /* glibc 2.1 */
- size = n+1; /* precisely what is needed */
- else /* glibc 2.0 */
- size *= 2; /* twice the old size */
- if ((np = realloc (p, size)) == NULL) {
+
+ /* 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 {
}
}
.fi
-.SH "SEE ALSO"
+.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 wcrtomb (3),
.BR wprintf (3),
.BR locale (5)
+.SH COLOPHON
+This page is part of release 3.79 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/.
OSDN Git Service
