original/man3/fgetwc.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
  12 .\"      http://www.UNIX-systems.org/online.html
  13 .\"   ISO/IEC 9899:1999
  14 .\"
  15 .\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon <moz@compsoc.man.ac.uk>
  16 .TH FGETWC 3  1999-07-25 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 fgetwc, getwc \- read a wide character from a FILE stream
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdio.h>
  22 .br
  23 .B #include <wchar.h>
  24 .sp
  25 .BI "wint_t fgetwc(FILE *" stream );
  26 .BI "wint_t getwc(FILE *" stream );
  27 .fi
  28 .SH DESCRIPTION
  29 The
  30 .BR fgetwc ()
  31 function is the wide-character equivalent
  32 of the
  33 .BR fgetc (3)
  34 function.
  35 It reads a wide character from \fIstream\fP and returns it.
  36 If the end of stream is reached, or if \fIferror(stream)\fP becomes true,
  37 it returns
  38 .BR WEOF .
  39 If a wide-character conversion error occurs, it sets
  40 \fIerrno\fP to \fBEILSEQ\fP and returns
  41 .BR WEOF .
  42 .PP
  43 The
  44 .BR getwc ()
  45 function or macro functions identically to
  46 .BR fgetwc ().
  47 It may be implemented as a macro, and may evaluate its argument
  48 more than once.
  49 There is no reason ever to use it.
  50 .PP
  51 For nonlocking counterparts, see
  52 .BR unlocked_stdio (3).
  53 .SH "RETURN VALUE"
  54 The
  55 .BR fgetwc ()
  56 function returns the next wide-character
  57 from the stream, or
  58 .BR WEOF .
  59 .SH ERRORS
  60 Apart from the usual ones, there is
  61 .TP
  62 .B EILSEQ
  63 The data obtained from the input stream does not
  64 form a valid character.
  65 .SH "CONFORMING TO"
  66 C99, POSIX.1-2001.
  67 .SH NOTES
  68 The behavior of
  69 .BR fgetwc ()
  70 depends on the
  71 .B LC_CTYPE
  72 category of the
  73 current locale.
  74 .PP
  75 In the absence of additional information passed to the
  76 .BR fopen (3)
  77 call, it is
  78 reasonable to expect that
  79 .BR fgetwc ()
  80 will actually read a multibyte sequence
  81 from the stream and then convert it to a wide character.
  82 .SH "SEE ALSO"
  83 .BR fgetws (3),
  84 .BR fputwc (3),
  85 .BR ungetwc (3),
  86 .BR unlocked_stdio (3)