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  2021-03-22 "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 On success,
  56 .BR fgetwc ()
  57 returns the next wide-character from the stream.
  58 Otherwise,
  59 .B WEOF
  60 is returned, and
  61 .I errno
  62 is set to indicate the error.
  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 .ad l
  73 .nh
  74 .TS
  75 allbox;
  76 lbx lb lb
  77 l l l.
  78 Interface       Attribute       Value
  79 T{
  80 .BR fgetwc (),
  81 .BR getwc ()
  82 T}      Thread safety   MT-Safe
  83 .TE
  84 .hy
  85 .ad
  86 .sp 1
  87 .SH CONFORMING TO
  88 POSIX.1-2001, POSIX.1-2008, C99.
  89 .SH NOTES
  90 The behavior of
  91 .BR fgetwc ()
  92 depends on the
  93 .B LC_CTYPE
  94 category of the
  95 current locale.
  96 .PP
  97 In the absence of additional information passed to the
  98 .BR fopen (3)
  99 call, it is
 100 reasonable to expect that
 101 .BR fgetwc ()
 102 will actually read a multibyte sequence
 103 from the stream and then convert it to a wide character.
 104 .SH SEE ALSO
 105 .BR fgetws (3),
 106 .BR fputwc (3),
 107 .BR ungetwc (3),
 108 .BR unlocked_stdio (3)