.\" 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
.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\" ISO/IEC 9899:1999
.\"
-.TH WPRINTF 3 2010-09-20 "GNU" "Linux Programmer's Manual"
+.TH WPRINTF 3 2014-03-19 "GNU" "Linux Programmer's Manual"
.SH NAME
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
wide-character output conversion
.\" .BR vfwprintf (),
.\" .BR vswprintf ():
_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
+.br
_POSIX_C_SOURCE\ >=\ 200112L;
.br
or
and
.BR vwprintf ()
functions
-perform wide-character output to \fIstdout\fP.
-\fIstdout\fP must not be byte oriented; see
+perform wide-character output to
+.IR stdout .
+.I stdout
+must not be byte oriented; see
.BR fwide (3)
for more information.
.PP
and
.BR vfwprintf ()
functions
-perform wide-character output to \fIstream\fP.
-\fIstream\fP must not be byte oriented; see
+perform wide-character output to
+.IR stream .
+.I stream
+must not be byte oriented; see
.BR fwide (3)
for more information.
.PP
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
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.
.BR swprintf ()
and
.BR vswprintf ()
-take a \fImaxlen\fP argument,
+take a
+.I maxlen
+argument,
.BR sprintf (3)
and
.BR vsprintf (3)
.RB ( snprintf (3)
and
.BR vsnprintf (3)
-take a \fImaxlen\fP argument, but these functions do not return \-1 upon
+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
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\\0\(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\\0\(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
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
and
.BR vswprintf ().
They return \-1 when an error occurs.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
C99.
.SH NOTES
The behavior of
category of the
current locale.
.PP
-If the \fIformat\fP string contains non-ASCII wide characters, the program
-will only work correctly if the
+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
Also, the use of C99 universal character names
of the form \\unnnn 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 (3)
.BR iconv (3),
followed by
.BR mbstowcs (3)).
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR fprintf (3),
.BR fputwc (3),
.BR fwide (3),
.BR printf (3),
.BR snprintf (3)
.\" .BR wscanf (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.