2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\" 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 1999-11-20 "GNU" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted wide character output conversion
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <stdio.h>
|
|
|
|
.B #include <wchar.h>
|
|
|
|
.sp
|
|
|
|
.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
|
|
|
|
.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
|
|
|
|
.SH DESCRIPTION
|
2005-10-19 06:54:38 +00:00
|
|
|
The \fBwprintf\fP() family of functions is the wide-character equivalent of the
|
2005-10-19 08:35:30 +00:00
|
|
|
\fBprintf\fP() family of functions. It performs formatted output of wide
|
2004-11-03 13:51:07 +00:00
|
|
|
characters.
|
|
|
|
.PP
|
2005-10-19 06:54:38 +00:00
|
|
|
The \fBwprintf\fP() and \fBvwprintf\fP() functions perform wide character output
|
2004-11-03 13:51:07 +00:00
|
|
|
to \fBstdout\fP. \fBstdout\fP must not be byte oriented; see function
|
2005-10-19 08:35:30 +00:00
|
|
|
\fBfwide\fP() for more information.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2005-10-19 06:54:38 +00:00
|
|
|
The \fBfwprintf\fP() and \fBvfwprintf\fP() functions perform wide character output
|
2004-11-03 13:51:07 +00:00
|
|
|
to \fIstream\fP. \fIstream\fP must not be byte oriented; see function
|
2005-10-19 08:35:30 +00:00
|
|
|
\fBfwide\fP() for more information.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2005-10-19 06:54:38 +00:00
|
|
|
The \fBswprintf\fP() and \fBvswprintf\fP() functions perform wide character output
|
2004-11-03 13:51:07 +00:00
|
|
|
to an array of wide characters.
|
|
|
|
The programmer must ensure that there is room for at least \fImaxlen\fP wide
|
|
|
|
characters at \fIwcs\fP.
|
|
|
|
.PP
|
2005-10-19 08:35:30 +00:00
|
|
|
These functions are like the \fBprintf\fP(), \fBvprintf\fP(), \fBfprintf\fP(),
|
|
|
|
\fBvfprintf\fP(), \fBsprintf\fP(), \fBvsprintf\fP() functions except for the
|
2004-11-03 13:51:07 +00:00
|
|
|
following differences:
|
|
|
|
.TP
|
|
|
|
.B \(bu
|
|
|
|
The \fIformat\fP string is a wide character string.
|
|
|
|
.TP
|
|
|
|
.B \(bu
|
|
|
|
The output consists of wide characters, not bytes.
|
|
|
|
.TP
|
|
|
|
.B \(bu
|
2005-10-19 06:54:38 +00:00
|
|
|
\fBswprintf\fP() and \fBvswprintf\fP() take a \fImaxlen\fP argument,
|
2005-10-19 08:35:30 +00:00
|
|
|
\fBsprintf\fP() and \fBvsprintf\fP() do not. (\fBsnprintf\fP() and \fBvsnprintf\fP()
|
2004-11-03 13:51:07 +00:00
|
|
|
take a \fImaxlen\fP 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:
|
|
|
|
.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
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR btowc ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
.IR "" `` "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
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR mbrtowc ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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. 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, unless a precision is given
|
|
|
|
and it is so small that the number of converted wide characters reaches it
|
2005-07-06 07:41:37 +00:00
|
|
|
before the end of the array is reached. If an
|
2004-11-03 13:51:07 +00:00
|
|
|
.B l
|
|
|
|
modifier is present: The
|
|
|
|
.IR "" `` "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
|
2005-10-19 06:54:38 +00:00
|
|
|
terminating null wide character in case of the functions \fBswprintf\fP() and
|
|
|
|
\fBvswprintf\fP(). They return \-1 when an error occurs.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:30 +00:00
|
|
|
C99.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR fprintf (3),
|
|
|
|
.BR fputwc (3),
|
|
|
|
.BR fwide (3),
|
|
|
|
.BR printf (3),
|
|
|
|
.BR snprintf (3),
|
|
|
|
.BR wscanf (3)
|
|
|
|
.SH NOTES
|
2005-10-19 06:54:38 +00:00
|
|
|
The behaviour of \fBwprintf\fP() et al. depends on the LC_CTYPE category of the
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
compile time. This is because the
|
2006-02-09 20:24:53 +00:00
|
|
|
.I wchar_t
|
2004-11-03 13:51:07 +00:00
|
|
|
representation is platform and locale dependent. (The GNU libc represents
|
|
|
|
wide characters using their Unicode (ISO-10646) code point, but other
|
2006-08-03 13:57:30 +00:00
|
|
|
platforms don't do this.
|
|
|
|
Also, the use of C99 universal character names
|
2004-11-03 13:51:07 +00:00
|
|
|
of the form \\unnnn does not solve this problem.) Therefore, in
|
|
|
|
internationalized programs, the \fIformat\fP string should consist of ASCII
|
|
|
|
wide characters only, or should be constructed at run time in an
|
|
|
|
internationalized way (e.g. using
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR gettext ()
|
2004-11-03 13:51:07 +00:00
|
|
|
or
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR iconv (),
|
2004-11-03 13:51:07 +00:00
|
|
|
followed by
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR mbstowcs ()).
|