diff options
Diffstat (limited to 'upstream/debian-unstable/man3/wprintf.3')
| -rw-r--r-- | upstream/debian-unstable/man3/wprintf.3 | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/wprintf.3 b/upstream/debian-unstable/man3/wprintf.3 new file mode 100644 index 00000000..95854a33 --- /dev/null +++ b/upstream/debian-unstable/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) |