.\" Copyright, The contributors to the Linux man-pages project
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.TH fwide 3 2025-05-06 "Linux man-pages 6.14"
.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>
.P
.BI "int fwide(FILE *" stream ", int " mode );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR fwide ():
.nf
    _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
        || _POSIX_C_SOURCE >= 200112L
.fi
.SH DESCRIPTION
When
.I mode
is zero, the
.BR fwide ()
function determines the current
orientation of
.IR stream .
It returns a positive value if
.I stream
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
.I stream
is byte oriented\[em]that is,
if char I/O is permitted but wide-character I/O is disallowed.
It
returns zero if
.I stream
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).
.P
Once a stream has an orientation, it cannot be changed and persists until
the stream is closed.
.P
When
.I mode
is nonzero, the
.BR fwide ()
function first attempts to set
.IR stream 's
orientation (to wide-character oriented
if
.I mode
is greater than 0,
or to byte oriented if
.I mode
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.
.P
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)