summaryrefslogtreecommitdiffstats
path: root/man3/fwide.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/fwide.3')
-rw-r--r--man3/fwide.392
1 files changed, 92 insertions, 0 deletions
diff --git a/man3/fwide.3 b/man3/fwide.3
new file mode 100644
index 0000000..6b33de0
--- /dev/null
+++ b/man3/fwide.3
@@ -0,0 +1,92 @@
+.\" 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.05.01"
+.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)