man3/fwide.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .TH FWIDE 3  1999-11-17 "GNU" "Linux Programmer's Manual"
  15 .SH NAME
  16 fwide \- set and determine the orientation of a FILE stream
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <wchar.h>
  20 .sp
  21 .BI "int fwide(FILE *" stream ", int " mode );
  22 .fi
  23 .SH DESCRIPTION
  24 When \fImode\fP is zero, the
  25 .BR fwide ()
  26 function determines the current
  27 orientation of \fIstream\fP.
  28 It returns a value > 0 if \fIstream\fP is
  29 wide-character oriented, that is, if wide-character I/O is permitted but char
  30 I/O is disallowed.
  31 It returns a value < 0 if \fIstream\fP is byte oriented,
  32 i.e. if char I/O is permitted but wide-character I/O is disallowed.
  33 It
  34 returns zero if \fIstream\fP has no orientation yet; in this case the next
  35 I/O operation might change the orientation (to byte oriented if it is a char
  36 I/O operation, or to wide-character oriented if it is a wide-character I/O
  37 operation).
  38 .PP
  39 Once a stream has an orientation, it cannot be changed and persists until
  40 the stream is closed.
  41 .PP
  42 When \fImode\fP is non-zero, the
  43 .BR fwide ()
  44 function first attempts to set
  45 \fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or
  46 to byte oriented if \fImode\fP < 0).
  47 It then returns a value denoting the
  48 current orientation, as above.
  49 .SH "RETURN VALUE"
  50 The
  51 .BR fwide ()
  52 function returns the stream's orientation, after possibly
  53 changing it.
  54 A return value > 0 means wide-character oriented.
  55 A return value
  56 < 0 means byte oriented.
  57 A return value of zero means undecided.
  58 .SH "CONFORMING TO"
  59 C99, POSIX.1-2001.
  60 .SH NOTES
  61 Wide-character output to a byte oriented stream can be performed through the
  62 .BR fprintf (3)
  63 function with the %lc and %ls directives.
  64 .PP
  65 Char oriented output to a wide-character oriented stream can be performed
  66 through the
  67 .BR fwprintf (3)
  68 function with the %c and %s directives.
  69 .SH "SEE ALSO"
  70 .BR fprintf (3),
  71 .BR fwprintf (3)