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  2007-07-26 "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 .sp
  24 .in -4n
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .in
  28 .sp
  29 .BR fwide ():
  30 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or
  31 .I cc\ -std=c99
  32 .SH DESCRIPTION
  33 When \fImode\fP is zero, the
  34 .BR fwide ()
  35 function determines the current
  36 orientation of \fIstream\fP.
  37 It returns a positive value if \fIstream\fP is
  38 wide-character oriented, that is, if wide-character I/O is permitted but char
  39 I/O is disallowed.
  40 It returns a negative value if \fIstream\fP is byte oriented,
  41 i.e. if char I/O is permitted but wide-character I/O is disallowed.
  42 It
  43 returns zero if \fIstream\fP has no orientation yet; in this case the next
  44 I/O operation might change the orientation (to byte oriented if it is a char
  45 I/O operation, or to wide-character oriented if it is a wide-character I/O
  46 operation).
  47 .PP
  48 Once a stream has an orientation, it cannot be changed and persists until
  49 the stream is closed.
  50 .PP
  51 When \fImode\fP is non-zero, the
  52 .BR fwide ()
  53 function first attempts to set
  54 \fIstream\fP's orientation (to wide-character oriented
  55 if \fImode\fP is greater than 0, or
  56 to byte oriented if \fImode\fP is less than 0).
  57 It then returns a value denoting the
  58 current orientation, as above.
  59 .SH "RETURN VALUE"
  60 The
  61 .BR fwide ()
  62 function returns the stream's orientation, after possibly
  63 changing it.
  64 A positive return value means wide-character oriented.
  65 A negative return value means byte oriented.
  66 A return value of zero means undecided.
  67 .SH "CONFORMING TO"
  68 C99, POSIX.1-2001.
  69 .SH NOTES
  70 Wide-character output to a byte oriented stream can be performed through the
  71 .BR fprintf (3)
  72 function with the
  73 .B %lc
  74 and
  75 .B %ls
  76 directives.
  77 .PP
  78 Char oriented output to a wide-character oriented stream can be performed
  79 through the
  80 .BR fwprintf (3)
  81 function with the
  82 .B %c
  83 and
  84 .B %s
  85 directives.
  86 .SH "SEE ALSO"
  87 .BR fprintf (3),
  88 .BR fwprintf (3)