mount_setattr.2: Minor tweaks to Christian's patch
[man-pages.git] / man3 / fwide.3
blobb6e7d4df2a6007f847d26ee6bcaee70b8bee936b
1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
8 .\" %%%LICENSE_END
9 .\"
10 .\" References consulted:
11 .\"   GNU glibc-2 source code and manual
12 .\"   Dinkumware C library reference http://www.dinkumware.com/
13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
14 .\"   ISO/IEC 9899:1999
15 .\"
16 .TH FWIDE 3  2021-03-22 "GNU" "Linux Programmer's Manual"
17 .SH NAME
18 fwide \- set and determine the orientation of a FILE stream
19 .SH SYNOPSIS
20 .nf
21 .B #include <wchar.h>
22 .PP
23 .BI "int fwide(FILE *" stream ", int " mode );
24 .fi
25 .PP
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .PP
31 .BR fwide ():
32 .nf
33     _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
34         || _POSIX_C_SOURCE >= 200112L
35 .fi
36 .SH DESCRIPTION
37 When \fImode\fP is zero, the
38 .BR fwide ()
39 function determines the current
40 orientation of \fIstream\fP.
41 It returns a positive value if \fIstream\fP is
42 wide-character oriented, that is, if wide-character I/O is permitted but char
43 I/O is disallowed.
44 It returns a negative value if \fIstream\fP is byte oriented\(emthat is,
45 if char I/O is permitted but wide-character I/O is disallowed.
47 returns zero if \fIstream\fP has no orientation yet; in this case the next
48 I/O operation might change the orientation (to byte oriented if it is a char
49 I/O operation, or to wide-character oriented if it is a wide-character I/O
50 operation).
51 .PP
52 Once a stream has an orientation, it cannot be changed and persists until
53 the stream is closed.
54 .PP
55 When \fImode\fP is nonzero, the
56 .BR fwide ()
57 function first attempts to set
58 \fIstream\fP's orientation (to wide-character oriented
59 if \fImode\fP is greater than 0, or
60 to byte oriented if \fImode\fP is less than 0).
61 It then returns a value denoting the
62 current orientation, as above.
63 .SH RETURN VALUE
64 The
65 .BR fwide ()
66 function returns the stream's orientation, after possibly
67 changing it.
68 A positive return value means wide-character oriented.
69 A negative return value means byte oriented.
70 A return value of zero means undecided.
71 .SH CONFORMING TO
72 POSIX.1-2001, POSIX.1-2008, C99.
73 .SH NOTES
74 Wide-character output to a byte oriented stream can be performed through the
75 .BR fprintf (3)
76 function with the
77 .B %lc
78 and
79 .B %ls
80 directives.
81 .PP
82 Char oriented output to a wide-character oriented stream can be performed
83 through the
84 .BR fwprintf (3)
85 function with the
86 .B %c
87 and
88 .B %s
89 directives.
90 .SH SEE ALSO
91 .BR fprintf (3),
92 .BR fwprintf (3)