.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
+.\" %%%LICENSE_END
.\"
.\" 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
+.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\" ISO/IEC 9899:1999
.\"
-.TH WPRINTF 3 1999-11-20 "GNU" "Linux Programmer's Manual"
+.TH WPRINTF 3 2019-03-06 "GNU" "Linux Programmer's Manual"
.SH NAME
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
wide-character output conversion
.nf
.B #include <stdio.h>
.B #include <wchar.h>
-.sp
+.PP
.BI "int wprintf(const wchar_t *" format ", ...);"
.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI " const wchar_t *" format ", ...);"
-.sp
-.B #include <stdarg.h>
-.sp
+.PP
.BI "int vwprintf(const wchar_t *" format ", va_list " args );
.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI " const wchar_t *" format ", va_list " args );
.fi
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.ad l
+All functions shown above:
+.RS 4
+.\" .BR wprintf (),
+.\" .BR fwprintf (),
+.\" .BR swprintf (),
+.\" .BR vwprintf (),
+.\" .BR vfwprintf (),
+.\" .BR vswprintf ():
+_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
+.br
+_POSIX_C_SOURCE\ >=\ 200112L
+.RE
+.ad
.SH DESCRIPTION
-The \fBwprintf\fP() family of functions is
+The
+.BR wprintf ()
+family of functions is
the wide-character equivalent of the
-\fBprintf\fP() family of functions.
+.BR printf (3)
+family of functions.
It performs formatted output of wide
characters.
.PP
-The \fBwprintf\fP() and \fBvwprintf\fP() functions
-perform wide-character output to \fBstdout\fP.
-\fBstdout\fP must not be byte oriented; see function
-\fBfwide\fP() for more information.
+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 \fBfwprintf\fP() and \fBvfwprintf\fP() functions
-perform wide-character output to \fIstream\fP.
-\fIstream\fP must not be byte oriented; see function
-\fBfwide\fP() for more information.
+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 \fBswprintf\fP() and \fBvswprintf\fP() functions
+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 \fImaxlen\fP wide
-characters at \fIwcs\fP.
+room for at least
+.I maxlen
+wide
+characters at
+.IR wcs .
.PP
These functions are like
-the \fBprintf\fP(), \fBvprintf\fP(), \fBfprintf\fP(),
-\fBvfprintf\fP(), \fBsprintf\fP(), \fBvsprintf\fP()
+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 \fIformat\fP string is a wide-character string.
+The
+.I format
+string is a wide-character string.
.TP
.B \(bu
The output consists of wide characters, not bytes.
.TP
.B \(bu
-\fBswprintf\fP() and \fBvswprintf\fP() take a \fImaxlen\fP argument,
-\fBsprintf\fP() and \fBvsprintf\fP() do not.
-(\fBsnprintf\fP() and \fBvsnprintf\fP()
-take a \fImaxlen\fP argument, but these functions do not return \-1 upon
+.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 \fBc\fP and \fBs\fP is different:
+The treatment of the conversion characters
+.BR c
+and
+.B s
+is different:
.TP
.B c
If no
modifier is present, the
.I int
argument is converted to a wide character by a call to the
-.BR btowc ()
+.BR btowc (3)
function, and the resulting wide character is written.
If an
.B l
.B s
If no
.B l
-modifier is present: The
-.IR "" `` "const char *" ''
+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 ()
+.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.
+(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 bytes
or
.IR "screen positions" .
-The array must contain a terminating null byte, unless a precision is given
+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
-.IR "" `` "const wchar_t *" ''
+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.
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"
+.SH RETURN VALUE
The functions return the number of wide characters written, excluding the
terminating null wide character in
-case of the functions \fBswprintf\fP() and
-\fBvswprintf\fP().
+case of the functions
+.BR swprintf ()
+and
+.BR vswprintf ().
They return \-1 when an error occurs.
-.SH "CONFORMING TO"
-C99.
-.SH "SEE ALSO"
-.BR fprintf (3),
-.BR fputwc (3),
-.BR fwide (3),
-.BR printf (3),
-.BR snprintf (3),
-.BR wscanf (3)
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw24 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR wprintf (),
+.BR fwprintf (),
+.br
+.BR swprintf (),
+.BR vwprintf (),
+.br
+.BR vfwprintf (),
+.BR vswprintf ()
+T} Thread safety MT-Safe locale
+.TE
+.sp 1
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, C99.
.SH NOTES
-The behaviour of \fBwprintf\fP() et al. depends
-on the LC_CTYPE category of the
+The behavior of
+.BR wprintf ()
+et al. depends
+on the
+.B LC_CTYPE
+category of the
current locale.
.PP
-If the \fIformat\fP string contains non-ASCII wide characters, the program
-will only work correctly if the LC_CTYPE category of the current locale at
-run time is the same as the LC_CTYPE category of the current locale at
+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 GNU libc represents
+representation is platform- and locale-dependent.
+(The glibc represents
wide characters using their Unicode (ISO-10646) code point, but other
platforms don't do this.
Also, the use of C99 universal character names
-of the form \\unnnn does not solve this problem.)
+of the form \eunnnn does not solve this problem.)
Therefore, in
-internationalized programs, the \fIformat\fP string should consist of ASCII
+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 ()
+internationalized way (e.g., using
+.BR gettext (3)
or
-.BR iconv (),
+.BR iconv (3),
followed by
-.BR mbstowcs ()).
+.BR mbstowcs (3)).
+.SH SEE ALSO
+.BR fprintf (3),
+.BR fputwc (3),
+.BR fwide (3),
+.BR printf (3),
+.BR snprintf (3)
+.\" .BR wscanf (3)
projects / thirdparty / man-pages.git / blobdiff