.\" 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 2013-12-30 "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 #
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 ptrdiff_t
argument.
.PP
-The SUSv2 only knows about the length modifiers
+The SUSv2 knows about 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
.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
.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 *"
+.I "int\ *"
(or variant) pointer argument.
No argument is converted.
.TP
No argument is converted.
The complete conversion
specification is \(aq%%\(aq.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The
.BR fprintf (),
.BR printf (),
.\" 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.68 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
