diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/printf.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/printf.3 | 1240 |
1 files changed, 1240 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/printf.3 b/upstream/opensuse-tumbleweed/man3/printf.3 new file mode 100644 index 00000000..edd6ba85 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/printf.3 @@ -0,0 +1,1240 @@ +'\" 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 2023-07-20 "Linux man-pages 6.05.01" +.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> +.PP +.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 ", ...);" +.PP +.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 +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR snprintf (), +.BR vsnprintf (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.PP +.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 . +.PP +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. +.PP +The functions +.BR snprintf () +and +.BR vsnprintf () +write at most +.I size +bytes (including the terminating null byte (\[aq]\e0\[aq])) to +.IR str . +.PP +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). +.PP +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. +.PP +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 NOTES. +.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" . +.PP +The overall syntax of a conversion specification is: +.PP +.in +4n +.nf +%[$][flags][width][.precision][length modifier]conversion +.fi +.in +.PP +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, +.PP +.in +4n +.EX +printf("%*d", width, num); +.EE +.in +.PP +and +.PP +.in +4n +.EX +printf("%2$*1$d", width, num); +.EE +.in +.PP +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. +.PP +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, +.PP +.in +4n +.EX +printf("%\[aq].2f", 1234567.89); +.EE +.in +.PP +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. +.PP +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. +.PP +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. +.PP +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 ). +.PP +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 characters +printed (excluding the null byte used to end output to strings). +.PP +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 NOTES.) +.PP +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 +.sp 1 +.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. +.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\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. +.PP +glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, +and the flag character \fBI\fP. +.PP +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 +.PP +.in +4n +.EX +sprintf(buf, "%s some further text", buf); +.EE +.in +.PP +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. +.PP +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)). +.\" .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 ); +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. +.\" .PP +.\" Some floating-point conversions under early libc4 +.\" caused memory leaks. +.SH EXAMPLES +To print +.I Pi +to five decimal places: +.PP +.in +4n +.EX +#include <math.h> +#include <stdio.h> +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.EE +.in +.PP +To print a date and time in the form "Sunday, July 3, 10:02", +where +.I weekday +and +.I month +are pointers to strings: +.PP +.in +4n +.EX +#include <stdio.h> +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.EE +.in +.PP +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: +.PP +.in +4n +.EX +#include <stdio.h> +fprintf(stdout, format, + weekday, month, day, hour, min); +.EE +.in +.PP +where +.I format +depends on locale, and may permute the arguments. +With the value: +.PP +.in +4n +.EX +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.EE +.in +.PP +one might obtain "Sonntag, 3. Juli, 10:02". +.PP +To allocate a sufficiently large string and print into it +(code correct for both glibc 2.0 and glibc 2.1): +.PP +.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 +.PP +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) |