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