Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 274 insertions, 0 deletions

diff --git a/man3/wprintf.3 b/man3/wprintf.3
new file mode 100644
index 0000000..95854a3
--- /dev/null
+++ b/man3/wprintf.3
@@ -0,0 +1,274 @@
+'\" t
+.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" References consulted:
+.\"   GNU glibc-2 source code and manual
+.\"   Dinkumware C library reference http://www.dinkumware.com/
+.\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
+.\"   ISO/IEC 9899:1999
+.\"
+.TH wprintf 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
+wide-character output conversion
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.B #include <wchar.h>
+.PP
+.BI "int wprintf(const wchar_t *restrict " format ", ...);"
+.BI "int fwprintf(FILE *restrict " stream ,
+.BI "             const wchar_t *restrict " format ", ...);"
+.BI "int swprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen ,
+.BI "             const wchar_t *restrict " format ", ...);"
+.PP
+.BI "int vwprintf(const wchar_t *restrict " format ", va_list " args );
+.BI "int vfwprintf(FILE *restrict " stream ,
+.BI "             const wchar_t *restrict " format ", va_list " args );
+.BI "int vswprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen ,
+.BI "             const wchar_t *restrict " format ", va_list " args );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+All functions shown above:
+.\" .BR wprintf (),
+.\" .BR fwprintf (),
+.\" .BR swprintf (),
+.\" .BR vwprintf (),
+.\" .BR vfwprintf (),
+.\" .BR vswprintf ():
+.nf
+    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
+        || _POSIX_C_SOURCE >= 200112L
+.fi
+.SH DESCRIPTION
+The
+.BR wprintf ()
+family of functions is
+the wide-character equivalent of the
+.BR printf (3)
+family of functions.
+It performs formatted output of wide
+characters.
+.PP
+The
+.BR wprintf ()
+and
+.BR vwprintf ()
+functions
+perform wide-character output to
+.IR stdout .
+.I stdout
+must not be byte oriented; see
+.BR fwide (3)
+for more information.
+.PP
+The
+.BR fwprintf ()
+and
+.BR vfwprintf ()
+functions
+perform wide-character output to
+.IR stream .
+.I stream
+must not be byte oriented; see
+.BR fwide (3)
+for more information.
+.PP
+The
+.BR swprintf ()
+and
+.BR vswprintf ()
+functions
+perform wide-character output
+to an array of wide characters.
+The programmer must ensure that there is
+room for at least
+.I maxlen
+wide
+characters at
+.IR wcs .
+.PP
+These functions are like
+the
+.BR printf (3),
+.BR vprintf (3),
+.BR fprintf (3),
+.BR vfprintf (3),
+.BR sprintf (3),
+.BR vsprintf (3)
+functions except for the
+following differences:
+.TP
+.B \[bu]
+The
+.I format
+string is a wide-character string.
+.TP
+.B \[bu]
+The output consists of wide characters, not bytes.
+.TP
+.B \[bu]
+.BR swprintf ()
+and
+.BR vswprintf ()
+take a
+.I maxlen
+argument,
+.BR sprintf (3)
+and
+.BR vsprintf (3)
+do not.
+.RB ( snprintf (3)
+and
+.BR vsnprintf (3)
+take a
+.I maxlen
+argument, but these functions do not return \-1 upon
+buffer overflow on Linux.)
+.PP
+The treatment of the conversion characters
+.B c
+and
+.B s
+is different:
+.TP
+.B c
+If no
+.B l
+modifier is present, the
+.I int
+argument is converted to a wide character by a call to the
+.BR btowc (3)
+function, and the resulting wide character is written.
+If an
+.B l
+modifier is present, the
+.I wint_t
+(wide character) argument 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) containing a multibyte character sequence beginning
+in the initial shift state.
+Characters from the array are converted to
+wide characters (each by a call to the
+.BR mbrtowc (3)
+function with a conversion state starting in the initial state before
+the first byte).
+The resulting wide characters are written up to
+(but not including) the terminating null wide character (L\[aq]\e0\[aq]).
+If a precision is
+specified, no more wide characters than the number specified are written.
+Note that the precision determines the number of
+.I wide characters
+written, not the number of
+.I bytes
+or
+.IR "screen positions" .
+The array must contain a terminating null byte (\[aq]\e0\[aq]),
+unless a precision is given
+and it is so small that the number of converted wide characters reaches it
+before the end of the array is reached.
+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 written up to (but not including) a
+terminating null wide character.
+If a precision is specified, no more than
+the number specified are written.
+The array must contain a terminating null
+wide character, unless a precision is given and it is smaller than or equal
+to the number of wide characters in the array.
+.SH RETURN VALUE
+The functions return the number of wide characters written, excluding the
+terminating null wide character in
+case of the functions
+.BR swprintf ()
+and
+.BR vswprintf ().
+They return \-1 when an error occurs.
+.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 wprintf (),
+.BR fwprintf (),
+.BR swprintf (),
+.BR vwprintf (),
+.BR vfwprintf (),
+.BR vswprintf ()
+T}	Thread safety	MT-Safe locale
+.TE
+.sp 1
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, C99.
+.SH NOTES
+The behavior of
+.BR wprintf ()
+et al. depends
+on the
+.B LC_CTYPE
+category of the
+current locale.
+.PP
+If the
+.I format
+string contains non-ASCII wide characters, the program
+will work correctly only if the
+.B LC_CTYPE
+category of the current locale at
+run time is the same as the
+.B LC_CTYPE
+category of the current locale at
+compile time.
+This is because the
+.I wchar_t
+representation is platform- and locale-dependent.
+(The glibc represents
+wide characters using their Unicode (ISO/IEC 10646) code point, but other
+platforms don't do this.
+Also, the use of C99 universal character names
+of the form \eunnnn does not solve this problem.)
+Therefore, in
+internationalized programs, the
+.I format
+string should consist of ASCII
+wide characters only, or should be constructed at run time in an
+internationalized way (e.g., using
+.BR gettext (3)
+or
+.BR iconv (3),
+followed by
+.BR mbstowcs (3)).
+.SH SEE ALSO
+.BR fprintf (3),
+.BR fputwc (3),
+.BR fwide (3),
+.BR printf (3),
+.BR snprintf (3)
+.\" .BR wscanf (3)