|
Packit |
7cfc04 |
.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
|
|
Packit |
7cfc04 |
.\" This is free documentation; you can redistribute it and/or
|
|
Packit |
7cfc04 |
.\" modify it under the terms of the GNU General Public License as
|
|
Packit |
7cfc04 |
.\" published by the Free Software Foundation; either version 2 of
|
|
Packit |
7cfc04 |
.\" the License, or (at your option) any later version.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" References consulted:
|
|
Packit |
7cfc04 |
.\" GNU glibc-2 source code and manual
|
|
Packit |
7cfc04 |
.\" Dinkumware C library reference http://www.dinkumware.com/
|
|
Packit |
7cfc04 |
.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
|
|
Packit |
7cfc04 |
.\" ISO/IEC 9899:1999
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH WPRINTF 3 2017-09-15 "GNU" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
|
|
Packit |
7cfc04 |
wide-character output conversion
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <stdio.h>
|
|
Packit |
7cfc04 |
.B #include <wchar.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int wprintf(const wchar_t *" format ", ...);"
|
|
Packit |
7cfc04 |
.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
|
|
Packit |
7cfc04 |
.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
|
|
Packit |
7cfc04 |
.BI " const wchar_t *" format ", ...);"
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int vwprintf(const wchar_t *" format ", va_list " args );
|
|
Packit |
7cfc04 |
.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
|
|
Packit |
7cfc04 |
.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
|
|
Packit |
7cfc04 |
.BI " const wchar_t *" format ", va_list " args );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in -4n
|
|
Packit |
7cfc04 |
Feature Test Macro Requirements for glibc (see
|
|
Packit |
7cfc04 |
.BR feature_test_macros (7)):
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.ad l
|
|
Packit |
7cfc04 |
All functions shown above:
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.\" .BR wprintf (),
|
|
Packit |
7cfc04 |
.\" .BR fwprintf (),
|
|
Packit |
7cfc04 |
.\" .BR swprintf (),
|
|
Packit |
7cfc04 |
.\" .BR vwprintf (),
|
|
Packit |
7cfc04 |
.\" .BR vfwprintf (),
|
|
Packit |
7cfc04 |
.\" .BR vswprintf ():
|
|
Packit |
7cfc04 |
_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
_POSIX_C_SOURCE\ >=\ 200112L
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.ad
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR wprintf ()
|
|
Packit |
7cfc04 |
family of functions is
|
|
Packit |
7cfc04 |
the wide-character equivalent of the
|
|
Packit |
7cfc04 |
.BR printf (3)
|
|
Packit |
7cfc04 |
family of functions.
|
|
Packit |
7cfc04 |
It performs formatted output of wide
|
|
Packit |
7cfc04 |
characters.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR wprintf ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vwprintf ()
|
|
Packit |
7cfc04 |
functions
|
|
Packit |
7cfc04 |
perform wide-character output to
|
|
Packit |
7cfc04 |
.IR stdout .
|
|
Packit |
7cfc04 |
.I stdout
|
|
Packit |
7cfc04 |
must not be byte oriented; see
|
|
Packit |
7cfc04 |
.BR fwide (3)
|
|
Packit |
7cfc04 |
for more information.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR fwprintf ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vfwprintf ()
|
|
Packit |
7cfc04 |
functions
|
|
Packit |
7cfc04 |
perform wide-character output to
|
|
Packit |
7cfc04 |
.IR stream .
|
|
Packit |
7cfc04 |
.I stream
|
|
Packit |
7cfc04 |
must not be byte oriented; see
|
|
Packit |
7cfc04 |
.BR fwide (3)
|
|
Packit |
7cfc04 |
for more information.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR swprintf ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vswprintf ()
|
|
Packit |
7cfc04 |
functions
|
|
Packit |
7cfc04 |
perform wide-character output
|
|
Packit |
7cfc04 |
to an array of wide characters.
|
|
Packit |
7cfc04 |
The programmer must ensure that there is
|
|
Packit |
7cfc04 |
room for at least
|
|
Packit |
7cfc04 |
.I maxlen
|
|
Packit |
7cfc04 |
wide
|
|
Packit |
7cfc04 |
characters at
|
|
Packit |
7cfc04 |
.IR wcs .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
These functions are like
|
|
Packit |
7cfc04 |
the
|
|
Packit |
7cfc04 |
.BR printf (3),
|
|
Packit |
7cfc04 |
.BR vprintf (3),
|
|
Packit |
7cfc04 |
.BR fprintf (3),
|
|
Packit |
7cfc04 |
.BR vfprintf (3),
|
|
Packit |
7cfc04 |
.BR sprintf (3),
|
|
Packit |
7cfc04 |
.BR vsprintf (3)
|
|
Packit |
7cfc04 |
functions except for the
|
|
Packit |
7cfc04 |
following differences:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B \(bu
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I format
|
|
Packit |
7cfc04 |
string is a wide-character string.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B \(bu
|
|
Packit |
7cfc04 |
The output consists of wide characters, not bytes.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B \(bu
|
|
Packit |
7cfc04 |
.BR swprintf ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vswprintf ()
|
|
Packit |
7cfc04 |
take a
|
|
Packit |
7cfc04 |
.I maxlen
|
|
Packit |
7cfc04 |
argument,
|
|
Packit |
7cfc04 |
.BR sprintf (3)
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vsprintf (3)
|
|
Packit |
7cfc04 |
do not.
|
|
Packit |
7cfc04 |
.RB ( snprintf (3)
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vsnprintf (3)
|
|
Packit |
7cfc04 |
take a
|
|
Packit |
7cfc04 |
.I maxlen
|
|
Packit |
7cfc04 |
argument, but these functions do not return \-1 upon
|
|
Packit |
7cfc04 |
buffer overflow on Linux.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The treatment of the conversion characters
|
|
Packit |
7cfc04 |
.BR c
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B s
|
|
Packit |
7cfc04 |
is different:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B c
|
|
Packit |
7cfc04 |
If no
|
|
Packit |
7cfc04 |
.B l
|
|
Packit |
7cfc04 |
modifier is present, the
|
|
Packit |
7cfc04 |
.I int
|
|
Packit |
7cfc04 |
argument is converted to a wide character by a call to the
|
|
Packit |
7cfc04 |
.BR btowc (3)
|
|
Packit |
7cfc04 |
function, and the resulting wide character is written.
|
|
Packit |
7cfc04 |
If an
|
|
Packit |
7cfc04 |
.B l
|
|
Packit |
7cfc04 |
modifier is present, the
|
|
Packit |
7cfc04 |
.I wint_t
|
|
Packit |
7cfc04 |
(wide character) argument is written.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B s
|
|
Packit |
7cfc04 |
If no
|
|
Packit |
7cfc04 |
.B l
|
|
Packit |
7cfc04 |
modifier is present: the
|
|
Packit |
7cfc04 |
.I "const\ char\ *"
|
|
Packit |
7cfc04 |
argument is expected to be a pointer to an array of character type
|
|
Packit |
7cfc04 |
(pointer to a string) containing a multibyte character sequence beginning
|
|
Packit |
7cfc04 |
in the initial shift state.
|
|
Packit |
7cfc04 |
Characters from the array are converted to
|
|
Packit |
7cfc04 |
wide characters (each by a call to the
|
|
Packit |
7cfc04 |
.BR mbrtowc (3)
|
|
Packit |
7cfc04 |
function with a conversion state starting in the initial state before
|
|
Packit |
7cfc04 |
the first byte).
|
|
Packit |
7cfc04 |
The resulting wide characters are written up to
|
|
Packit |
7cfc04 |
(but not including) the terminating null wide character (L\(aq\\0\(aq).
|
|
Packit |
7cfc04 |
If a precision is
|
|
Packit |
7cfc04 |
specified, no more wide characters than the number specified are written.
|
|
Packit |
7cfc04 |
Note that the precision determines the number of
|
|
Packit |
7cfc04 |
.I wide characters
|
|
Packit |
7cfc04 |
written, not the number of
|
|
Packit |
7cfc04 |
.I bytes
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IR "screen positions" .
|
|
Packit |
7cfc04 |
The array must contain a terminating null byte (\(aq\\0\(aq),
|
|
Packit |
7cfc04 |
unless a precision is given
|
|
Packit |
7cfc04 |
and it is so small that the number of converted wide characters reaches it
|
|
Packit |
7cfc04 |
before the end of the array is reached.
|
|
Packit |
7cfc04 |
If an
|
|
Packit |
7cfc04 |
.B l
|
|
Packit |
7cfc04 |
modifier is present: the
|
|
Packit |
7cfc04 |
.I "const\ wchar_t\ *"
|
|
Packit |
7cfc04 |
argument is expected to be a pointer to an array of wide characters.
|
|
Packit |
7cfc04 |
Wide characters from the array are written up to (but not including) a
|
|
Packit |
7cfc04 |
terminating null wide character.
|
|
Packit |
7cfc04 |
If a precision is specified, no more than
|
|
Packit |
7cfc04 |
the number specified are written.
|
|
Packit |
7cfc04 |
The array must contain a terminating null
|
|
Packit |
7cfc04 |
wide character, unless a precision is given and it is smaller than or equal
|
|
Packit |
7cfc04 |
to the number of wide characters in the array.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
The functions return the number of wide characters written, excluding the
|
|
Packit |
7cfc04 |
terminating null wide character in
|
|
Packit |
7cfc04 |
case of the functions
|
|
Packit |
7cfc04 |
.BR swprintf ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR vswprintf ().
|
|
Packit |
7cfc04 |
They return \-1 when an error occurs.
|
|
Packit |
7cfc04 |
.SH ATTRIBUTES
|
|
Packit |
7cfc04 |
For an explanation of the terms used in this section, see
|
|
Packit |
7cfc04 |
.BR attributes (7).
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
allbox;
|
|
Packit |
7cfc04 |
lbw24 lb lb
|
|
Packit |
7cfc04 |
l l l.
|
|
Packit |
7cfc04 |
Interface Attribute Value
|
|
Packit |
7cfc04 |
T{
|
|
Packit |
7cfc04 |
.BR wprintf (),
|
|
Packit |
7cfc04 |
.BR fwprintf (),
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.BR swprintf (),
|
|
Packit |
7cfc04 |
.BR vwprintf (),
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.BR vfwprintf (),
|
|
Packit |
7cfc04 |
.BR vswprintf ()
|
|
Packit |
7cfc04 |
T} Thread safety MT-Safe locale
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.sp 1
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, C99.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The behavior of
|
|
Packit |
7cfc04 |
.BR wprintf ()
|
|
Packit |
7cfc04 |
et al. depends
|
|
Packit |
7cfc04 |
on the
|
|
Packit |
7cfc04 |
.B LC_CTYPE
|
|
Packit |
7cfc04 |
category of the
|
|
Packit |
7cfc04 |
current locale.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the
|
|
Packit |
7cfc04 |
.I format
|
|
Packit |
7cfc04 |
string contains non-ASCII wide characters, the program
|
|
Packit |
7cfc04 |
will work correctly only if the
|
|
Packit |
7cfc04 |
.B LC_CTYPE
|
|
Packit |
7cfc04 |
category of the current locale at
|
|
Packit |
7cfc04 |
run time is the same as the
|
|
Packit |
7cfc04 |
.B LC_CTYPE
|
|
Packit |
7cfc04 |
category of the current locale at
|
|
Packit |
7cfc04 |
compile time.
|
|
Packit |
7cfc04 |
This is because the
|
|
Packit |
7cfc04 |
.I wchar_t
|
|
Packit |
7cfc04 |
representation is platform- and locale-dependent.
|
|
Packit |
7cfc04 |
(The glibc represents
|
|
Packit |
7cfc04 |
wide characters using their Unicode (ISO-10646) code point, but other
|
|
Packit |
7cfc04 |
platforms don't do this.
|
|
Packit |
7cfc04 |
Also, the use of C99 universal character names
|
|
Packit |
7cfc04 |
of the form \\unnnn does not solve this problem.)
|
|
Packit |
7cfc04 |
Therefore, in
|
|
Packit |
7cfc04 |
internationalized programs, the
|
|
Packit |
7cfc04 |
.I format
|
|
Packit |
7cfc04 |
string should consist of ASCII
|
|
Packit |
7cfc04 |
wide characters only, or should be constructed at run time in an
|
|
Packit |
7cfc04 |
internationalized way (e.g., using
|
|
Packit |
7cfc04 |
.BR gettext (3)
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR iconv (3),
|
|
Packit |
7cfc04 |
followed by
|
|
Packit |
7cfc04 |
.BR mbstowcs (3)).
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR fprintf (3),
|
|
Packit |
7cfc04 |
.BR fputwc (3),
|
|
Packit |
7cfc04 |
.BR fwide (3),
|
|
Packit |
7cfc04 |
.BR printf (3),
|
|
Packit |
7cfc04 |
.BR snprintf (3)
|
|
Packit |
7cfc04 |
.\" .BR wscanf (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|