.\" 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 FWIDE 3  1999-11-17 "GNU" "Linux Programmer's Manual"
.SH NAME
fwide \- set and determine the orientation of a FILE stream
.SH SYNOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "int fwide(FILE *" stream ", int " mode );
.fi
.SH DESCRIPTION
When \fImode\fP is zero, the \fBfwide\fP() function determines the current
orientation of \fIstream\fP. It returns a value > 0 if \fIstream\fP is
wide-character oriented, i.e. if wide character I/O is permitted but char
I/O is disallowed. It returns a value < 0 if \fIstream\fP is byte oriented,
i.e. if char I/O is permitted but wide character I/O is disallowed. It
returns zero if \fIstream\fP has no orientation yet; in this case the next
I/O operation might change the orientation (to byte oriented if it is a char
I/O operation, or to wide-character oriented if it is a wide character I/O
operation).
.PP
Once a stream has an orientation, it cannot be changed and persists until
the stream is closed.
.PP
When \fImode\fP is non-zero, the \fBfwide\fP() function first attempts to set
\fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or
to byte oriented if \fImode\fP < 0). It then returns a value denoting the
current orientation, as above.
.SH "RETURN VALUE"
The \fBfwide\fP() function returns the stream's orientation, after possibly
changing it. A return value > 0 means wide-character oriented. A return value
< 0 means byte oriented. A return value of zero means undecided.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR fprintf (3),
.BR fwprintf (3)
.SH NOTES
Wide-character output to a byte oriented stream can be performed through the
\fBfprintf\fP() function with the %lc and %ls directives.
.PP
Char oriented output to a wide-character oriented stream can be performed
through the \fBfwprintf\fP() function with the %c and %s directives.