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