X-Git-Url: http://git.osdn.net/view?a=blobdiff_plain;f=original%2Fman3%2Fprintf.3;h=f2ba527cd7326521961872bafce1df60a6e2b5ba;hb=110dba020f489b75aff2497105f7970c05e2b87c;hp=fc9456c166086ae9b8e4d764949eedcdc5e58cae;hpb=c03a7a882c608ebf399d1b044ce7a6daa922351a;p=linuxjm%2FLDP_man-pages.git diff --git a/original/man3/printf.3 b/original/man3/printf.3 index fc9456c1..f2ba527c 100644 --- a/original/man3/printf.3 +++ b/original/man3/printf.3 @@ -1,5 +1,12 @@ .\" 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 @@ -16,22 +23,15 @@ .\" 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 +.\" . +.\" %%%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 @@ -105,7 +105,7 @@ and .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 @@ -149,10 +149,9 @@ 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" +.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 () @@ -160,9 +159,9 @@ and .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 @@ -171,7 +170,7 @@ 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" +.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 @@ -253,7 +252,7 @@ Thus, .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 # @@ -386,7 +385,7 @@ 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" +.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 @@ -402,7 +401,7 @@ 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" +.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$" @@ -410,8 +409,9 @@ 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 , @@ -438,7 +438,7 @@ string for and .B S conversions. -.SS "The length modifier" +.SS The length modifier Here, "integer conversion" stands for .BR d , .BR i , @@ -547,7 +547,7 @@ A following integer conversion corresponds to a .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 , @@ -575,7 +575,7 @@ and .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 @@ -620,8 +620,7 @@ When 0 is printed with an explicit precision 0, the output is empty. 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 @@ -690,7 +689,7 @@ 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 @@ -729,7 +728,7 @@ resulting multibyte string is written. 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 @@ -743,7 +742,7 @@ array, the array must contain a terminating null byte. 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 @@ -781,16 +780,16 @@ 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 *" +.I "int\ *" (or variant) pointer argument. No argument is converted. .TP @@ -805,7 +804,7 @@ A \(aq%\(aq is written. No argument is converted. The complete conversion specification is \(aq%%\(aq. -.SH "CONFORMING TO" +.SH CONFORMING TO The .BR fprintf (), .BR printf (), @@ -973,8 +972,9 @@ call to write to memory and creating a security hole. .\" 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 @@ -1035,28 +1035,42 @@ To allocate a sufficiently large string and print into it 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 { @@ -1065,7 +1079,10 @@ make_message(const char *fmt, ...) } } .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), @@ -1074,3 +1091,12 @@ make_message(const char *fmt, ...) .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/.