Debian Codegraph @

upstream/debian-trixie/man3/fwide.3

raw
1 .\" Copyright (c) Bruno Haible <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .\" References consulted:
6 .\" GNU glibc-2 source code and manual
7 .\" Dinkumware C library reference http://www.dinkumware.com/
8 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
9 .\" ISO/IEC 9899:1999
10 .\"
11 .TH fwide 3 2024-05-02 "Linux man-pages 6.9.1"
12 .SH NAME
13 fwide \- set and determine the orientation of a FILE stream
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ", " \-lc )
17 .SH SYNOPSIS
18 .nf
19 .B #include <wchar.h>
20 .P
21 .BI "int fwide(FILE *" stream ", int " mode );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR fwide ():
30 .nf
31 _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
32 || _POSIX_C_SOURCE >= 200112L
33 .fi
34 .SH DESCRIPTION
35 When \fImode\fP is zero, the
36 .BR fwide ()
37 function determines the current
38 orientation of \fIstream\fP.
39 It returns a positive value if \fIstream\fP is
40 wide-character oriented, that is, if wide-character I/O is permitted but char
41 I/O is disallowed.
42 It returns a negative value if \fIstream\fP is byte oriented\[em]that is,
43 if char I/O is permitted but wide-character I/O is disallowed.
44 It
45 returns zero if \fIstream\fP has no orientation yet; in this case the next
46 I/O operation might change the orientation (to byte oriented if it is a char
47 I/O operation, or to wide-character oriented if it is a wide-character I/O
48 operation).
49 .P
50 Once a stream has an orientation, it cannot be changed and persists until
51 the stream is closed.
52 .P
53 When \fImode\fP is nonzero, the
54 .BR fwide ()
55 function first attempts to set
56 \fIstream\fP's orientation (to wide-character oriented
57 if \fImode\fP is greater than 0, or
58 to byte oriented if \fImode\fP is less than 0).
59 It then returns a value denoting the
60 current orientation, as above.
61 .SH RETURN VALUE
62 The
63 .BR fwide ()
64 function returns the stream's orientation, after possibly
65 changing it.
66 A positive return value means wide-character oriented.
67 A negative return value means byte oriented.
68 A return value of zero means undecided.
69 .SH STANDARDS
70 C11, POSIX.1-2008.
71 .SH HISTORY
72 POSIX.1-2001, 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 .P
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)