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