.\" 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 2011-09-28 "GNU" "Linux Programmer's Manual"
+.TH PRINTF 3 2013-03-05 "GNU" "Linux Programmer's Manual"
.SH NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
vsnprintf \- formatted output conversion
(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 (excluding the null byte used to end output to strings).
(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$"
and
.B S
conversions.
-.SS "The length modifier"
+.SS The length modifier
Here, "integer conversion" stands for
.BR d ,
.BR i ,
.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
No argument is converted.
The complete conversion
specification is \(aq%%\(aq.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The
.BR fprintf (),
.BR printf (),
.PP
To allocate a sufficiently large string and print into it
(code correct for both glibc 2.0 and glibc 2.1):
+.PP
+If truncation occurs in glibc versions prior to 2.0.6, this is treated as an
+error instead of being handled gracefully.
.nf
#include <stdio.h>
make_message(const char *fmt, ...)
{
int n;
- int size = 100; /* Guess we need no more than 100 bytes. */
+ int size = 100; /* Guess we need no more than 100 bytes */
char *p, *np;
va_list ap;
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. */
+ /* Check error code */
- if (n > \-1 && n < size)
+ if (n < 0)
+ return NULL;
+
+ /* If that worked, return the string */
+
+ if (n < size)
return p;
- /* Else try again with more space. */
+ /* Else try again with more space */
+
+ size = n + 1; /* Precisely what is needed */
- 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) {
free(p);
}
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR printf (1),
.BR asprintf (3),
.BR dprintf (3),