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 \fBfgetwc\fP function is the wide-character equivalent of the \fBfgetc\fP
  30 function. It reads a wide character from \fIstream\fP and returns it. If
  31 the end of stream is reached, or if \fIferror(stream)\fP becomes true,
  32 it returns WEOF. If a wide character conversion error occurs, it sets
  33 \fBerrno\fP to \fBEILSEQ\fP and returns WEOF.
  34 .PP
  35 The \fBgetwc\fP function or macro functions identically to \fBfgetwc\fP.
  36 It may be implemented as a macro, and may evaluate its argument
  37 more than once. There is no reason ever to use it.
  38 .PP
  39 For non-locking counterparts, see
  40 .BR unlocked_stdio (3).
  41 .SH "RETURN VALUE"
  42 The \fBfgetwc\fP function returns the next wide-character from the stream, or
  43 WEOF.
  44 .SH ERRORS
  45 Apart from the usual ones, there is
  46 .TP
  47 .B EILSEQ
  48 The data obtained from the input stream does not
  49 form a valid character.
  50 .SH "CONFORMING TO"
  51 ISO/ANSI C, UNIX98
  52 .SH NOTES
  53 The behaviour of \fBfgetwc\fP depends on the LC_CTYPE category of the
  54 current locale.
  55 .PP
  56 In the absence of additional information passed to the fopen call, it is
  57 reasonable to expect that \fBfgetwc\fP will actually read a multibyte sequence
  58 from the stream and then convert it to a wide character.
  59 .SH "SEE ALSO"
  60 .BR fgetws (3),
  61 .BR fputwc (3),
  62 .BR ungetwc (3),
  63 .BR unlocked_stdio (3)