man3/fwide.3

   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.
  46 It
  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)