Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1242 insertions, 0 deletions

diff --git a/upstream/opensuse-leap-15-6/man3/printf.3 b/upstream/opensuse-leap-15-6/man3/printf.3
new file mode 100644
index 00000000..2b73deef
--- /dev/null
+++ b/upstream/opensuse-leap-15-6/man3/printf.3
@@ -0,0 +1,1242 @@
+'\" 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-04-01 "Linux man-pages 6.04"
+.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).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR printf (),
+.BR fprintf (),
+.BR sprintf (),
+.BR snprintf (),
+.BR vprintf (),
+.BR vfprintf (),
+.BR vsprintf (),
+.BR vsnprintf ()
+T}	Thread safety	MT-Safe locale
+.TE
+.hy
+.ad
+.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)