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