.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.\" 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 2023-03-30 "Linux man-pages 6.04"
.SH NAME
fwide \- set and determine the orientation of a FILE stream
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <wchar.h>
.PP
.BI "int fwide(FILE *" stream ", int " mode );
.fi
.PP
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.PP
.BR fwide ():
.nf
    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
        || _POSIX_C_SOURCE >= 200112L
.fi
.SH DESCRIPTION
When \fImode\fP is zero, the
.BR fwide ()
function determines the current
orientation of \fIstream\fP.
It returns a positive value if \fIstream\fP is
wide-character oriented, that is, if wide-character I/O is permitted but char
I/O is disallowed.
It returns a negative value if \fIstream\fP is byte oriented\[em]that is,
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 nonzero, the
.BR fwide ()
function first attempts to set
\fIstream\fP's orientation (to wide-character oriented
if \fImode\fP is greater than 0, or
to byte oriented if \fImode\fP is less than 0).
It then returns a value denoting the
current orientation, as above.
.SH RETURN VALUE
The
.BR fwide ()
function returns the stream's orientation, after possibly
changing it.
A positive return value means wide-character oriented.
A negative return value means byte oriented.
A return value of zero means undecided.
.SH STANDARDS
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C99.
.SH NOTES
Wide-character output to a byte oriented stream can be performed through the
.BR fprintf (3)
function with the
.B %lc
and
.B %ls
directives.
.PP
Char oriented output to a wide-character oriented stream can be performed
through the
.BR fwprintf (3)
function with the
.B %c
and
.B %s
directives.
.SH SEE ALSO
.BR fprintf (3),
.BR fwprintf (3)