diff options
Diffstat (limited to 'man3/printf.3')
| -rw-r--r-- | man3/printf.3 | 1239 |
1 files changed, 0 insertions, 1239 deletions
diff --git a/man3/printf.3 b/man3/printf.3 deleted file mode 100644 index 15ed75439..000000000 --- a/man3/printf.3 +++ /dev/null @@ -1,1239 +0,0 @@ -'\" t -.\" 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. -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" 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 (date) "Linux man-pages (unreleased)" -.SH NAME -printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, -vsprintf, vsnprintf \- formatted output conversion -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <stdio.h> -.P -.BI "int printf(const char *restrict " format ", ...);" -.BI "int fprintf(FILE *restrict " stream , -.BI " const char *restrict " format ", ...);" -.BI "int dprintf(int " fd , -.BI " const char *restrict " format ", ...);" -.BI "int sprintf(char *restrict " str , -.BI " const char *restrict " format ", ...);" -.BI "int snprintf(char " str "[restrict ." size "], size_t " size , -.BI " const char *restrict " format ", ...);" -.P -.BI "int vprintf(const char *restrict " format ", va_list " ap ); -.BI "int vfprintf(FILE *restrict " stream , -.BI " const char *restrict " format ", va_list " ap ); -.BI "int vdprintf(int " fd , -.BI " const char *restrict " format ", va_list " ap ); -.BI "int vsprintf(char *restrict " str , -.BI " const char *restrict " format ", va_list " ap ); -.BI "int vsnprintf(char " str "[restrict ." size "], size_t " size , -.BI " const char *restrict " format ", va_list " ap ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR snprintf (), -.BR vsnprintf (): -.nf - _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE - || /* glibc <= 2.19: */ _BSD_SOURCE -.fi -.P -.BR dprintf (), -.BR vdprintf (): -.nf - Since glibc 2.10: - _POSIX_C_SOURCE >= 200809L - Before glibc 2.10: - _GNU_SOURCE -.fi -.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 . -.P -The function -.BR dprintf () -is the same as -.BR fprintf () -except that it outputs to a file descriptor, -.IR fd , -instead of to a -.BR stdio (3) -stream. -.P -The functions -.BR snprintf () -and -.BR vsnprintf () -write at most -.I size -bytes (including the terminating null byte (\[aq]\e0\[aq])) to -.IR str . -.P -The functions -.BR vprintf (), -.BR vfprintf (), -.BR vdprintf (), -.BR vsprintf (), -.BR vsnprintf () -are equivalent to the functions -.BR printf (), -.BR fprintf (), -.BR dprintf (), -.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). -.P -All of these 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. -.P -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 CAVEATS. -.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" . -.P -The overall syntax of a conversion specification is: -.P -.in +4n -.nf -%[$][flags][width][.precision][length modifier]conversion -.fi -.in -.P -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] (see -.I "Field width" -and -.I Precision -below) 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 \fIm\fP denotes -the position in the argument list of the desired argument, indexed starting -from 1. -Thus, -.P -.in +4n -.EX -printf("%*d", width, num); -.EE -.in -.P -and -.P -.in +4n -.EX -printf("%2$*1$d", width, num); -.EE -.in -.P -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. -.P -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. -(See -.BR setlocale (3).) -The POSIX locale -uses \[aq].\[aq] as radix character, and does not have a grouping character. -Thus, -.P -.in +4n -.EX -printf("%\[aq].2f", 1234567.89); -.EE -.in -.P -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 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 -.BR m , -if -.I errno -contains a valid error code, -the output of -.I strerrorname_np(errno) -is printed; -otherwise, the value stored in -.I errno -is printed as a decimal number. -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 an integer 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. -.P -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. -(See -.BR setlocale (3).) -Note that many versions of -.BR gcc (1) -cannot parse this option and will issue a warning. -(SUSv2 did not -include \fI%\[aq]F\fP, but SUSv3 added it.) -Note also that the default locale of a C program is "C" -whose locale information indicates no thousands' grouping character. -Therefore, without a prior call to -.BR setlocale (3), -no thousands' grouping characters will be printed. -.P -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 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 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 \fIm\fP) to specify that the precision -is given in the next argument, or in the \fIm\fP-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 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 -or -.I unsigned short -argument, or a following -.B n -conversion corresponds to a pointer to a -.I short -argument. -.TP -.B l -(ell) A following integer conversion corresponds to a -.I long -or -.I unsigned long -argument, or a following -.B n -conversion corresponds to a pointer to a -.I long -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. -On a following -.BR a , -.BR A , -.BR e , -.BR E , -.BR f , -.BR F , -.BR g , -or -.B G -conversion, this length modifier is ignored (C99; not in SUSv2). -.TP -.B ll -(ell-ell). -A following integer conversion corresponds to a -.I long long -or -.I unsigned long long -argument, or a following -.B n -conversion corresponds to a pointer to a -.I long long -argument. -.TP -.B q -A synonym for -.BR ll . -This is a nonstandard extension, derived from BSD; -avoid its use in new code. -.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 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. -.TP -.B Z -A nonstandard synonym for -.B z -that predates the appearance of -.BR z . -Do not use in new code. -.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. -.P -SUSv3 specifies all of the above, -except for those modifiers explicitly noted as being nonstandard extensions. -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 ). -.P -As a nonstandard extension, the GNU implementations treats -.B ll -and -.B L -as synonyms, so that one can, for example, write -.B llg -(as a synonym for the standards-compliant -.BR Lg ) -and -.B Ld -(as a synonym for the standards compliant -.BR lld ). -Such usage is nonportable. -.\" -.SS Conversion specifiers -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 (which is nonzero if the argument is nonzero) -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. -.IP -(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 \(+-d; -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. -The exponent always contains at least one -digit; if the value is zero, the exponent is 0. -.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]\e0\[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. -.IP -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 -.IR "int\ *" , -or variant whose size matches the (optionally) -supplied integer length modifier. -No argument is converted. -(This specifier is not supported by the bionic C library.) -The behavior is undefined if the conversion specification includes -any flags, a field width, or a precision. -.TP -.B m -(glibc extension; supported by uClibc and musl.) -Print output of -.I strerror(errno) -(or -.I strerrorname_np(errno) -in the alternate form). -No argument is required. -.TP -.B % -A \[aq]%\[aq] is written. -No argument is converted. -The complete conversion -specification is \[aq]%%\[aq]. -.SH RETURN VALUE -Upon successful return, these functions return the number of bytes -printed (excluding the null byte used to end output to strings). -.P -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 CAVEATS.) -.P -If an output error is encountered, a negative value is returned. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR printf (), -.BR fprintf (), -.BR sprintf (), -.BR snprintf (), -.BR vprintf (), -.BR vfprintf (), -.BR vsprintf (), -.BR vsnprintf () -T} Thread safety MT-Safe locale -.TE -.SH STANDARDS -.TP -.BR fprintf () -.TQ -.BR printf () -.TQ -.BR sprintf () -.TQ -.BR vprintf () -.TQ -.BR vfprintf () -.TQ -.BR vsprintf () -.TQ -.BR snprintf () -.TQ -.BR vsnprintf () -C11, POSIX.1-2008. -.TP -.BR dprintf () -.TQ -.BR vdprintf () -GNU, POSIX.1-2008. -.SH HISTORY -.TP -.BR fprintf () -.TQ -.BR printf () -.TQ -.BR sprintf () -.TQ -.BR vprintf () -.TQ -.BR vfprintf () -.TQ -.BR vsprintf () -C89, POSIX.1-2001. -.TP -.BR snprintf () -.TQ -.BR vsnprintf () -SUSv2, C99, POSIX.1-2001. -.IP -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. -POSIX.1-2001 and later align their specification of -.BR snprintf () -with C99. -.TP -.BR dprintf () -.TQ -.BR vdprintf () -GNU, POSIX.1-2008. -.P -.\" 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$". -.\" .P -.\" 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\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) . -.\" .P -.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. -.\" .P -glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP -and conversion characters \fBa\fP and \fBA\fP. -.P -glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, -and the flag character \fBI\fP. -.P -glibc 2.35 gives a meaning to the alternate form -.RB ( # ) -of the -.B m -conversion specifier, that is -.IR %#m . -.SH CAVEATS -Some programs imprudently rely on code such as the following -.P -.in +4n -.EX -sprintf(buf, "%s some further text", buf); -.EE -.in -.P -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. -.P -The glibc implementation of the functions -.BR snprintf () -and -.BR vsnprintf () -conforms to the C99 standard, that is, behaves as described above, -since glibc 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)). -.\" .P -.\" 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. -.P -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. -.\" .P -.\" Some floating-point conversions under early libc4 -.\" caused memory leaks. -.SH EXAMPLES -To print -.I Pi -to five decimal places: -.P -.in +4n -.EX -#include <math.h> -#include <stdio.h> -fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); -.EE -.in -.P -To print a date and time in the form "Sunday, July 3, 10:02", -where -.I weekday -and -.I month -are pointers to strings: -.P -.in +4n -.EX -#include <stdio.h> -fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", - weekday, month, day, hour, min); -.EE -.in -.P -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: -.P -.in +4n -.EX -#include <stdio.h> -fprintf(stdout, format, - weekday, month, day, hour, min); -.EE -.in -.P -where -.I format -depends on locale, and may permute the arguments. -With the value: -.P -.in +4n -.EX -"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" -.EE -.in -.P -one might obtain "Sonntag, 3. Juli, 10:02". -.P -To allocate a sufficiently large string and print into it -(code correct for both glibc 2.0 and glibc 2.1): -.P -.EX -#include <stdio.h> -#include <stdlib.h> -#include <stdarg.h> -\& -char * -make_message(const char *fmt, ...) -{ - int n = 0; - size_t size = 0; - char *p = NULL; - va_list ap; -\& - /* Determine required size. */ -\& - va_start(ap, fmt); - n = vsnprintf(p, size, fmt, ap); - va_end(ap); -\& - if (n < 0) - return NULL; -\& - size = (size_t) n + 1; /* One extra byte for \[aq]\e0\[aq] */ - p = malloc(size); - if (p == NULL) - return NULL; -\& - va_start(ap, fmt); - n = vsnprintf(p, size, fmt, ap); - va_end(ap); -\& - if (n < 0) { - free(p); - return NULL; - } -\& - return p; -} -.EE -.P -If truncation occurs in glibc versions prior to glibc 2.0.6, -this is treated as an error instead of being handled gracefully. -.SH SEE ALSO -.BR printf (1), -.BR asprintf (3), -.BR puts (3), -.BR scanf (3), -.BR setlocale (3), -.BR strfromd (3), -.BR wcrtomb (3), -.BR wprintf (3), -.BR locale (5) |