1FGETC(3P)                  POSIX Programmer's Manual                 FGETC(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fgetc - get a byte from a stream
13

SYNOPSIS

15       #include <stdio.h>
16
17       int fgetc(FILE *stream);
18
19

DESCRIPTION

21       If the end-of-file indicator for the input stream pointed to by  stream
22       is  not  set  and  a  next  byte is present, the fgetc() function shall
23       obtain the next byte as an unsigned char converted to an int, from  the
24       input  stream  pointed  to  by  stream, and advance the associated file
25       position indicator for the stream (if defined). Since fgetc()  operates
26       on  bytes,  reading  a  character  consisting  of multiple bytes (or "a
27       multi-byte character") may require multiple calls to fgetc().
28
29       The fgetc() function may mark the st_atime field of the file associated
30       with  stream  for update. The st_atime field shall be marked for update
31       by the  first  successful  execution  of  fgetc(),  fgets(),  fgetwc(),
32       fgetws(),  fread(),  fscanf(),  getc(),  getchar(),  gets(), or scanf()
33       using stream that returns data not supplied by a prior call to ungetc()
34       or ungetwc().
35

RETURN VALUE

37       Upon successful completion, fgetc() shall return the next byte from the
38       input stream pointed to by stream. If the end-of-file indicator for the
39       stream  is  set,  or  if  the stream is at end-of-file, the end-of-file
40       indicator for the stream shall be set and fgetc() shall return EOF.  If
41       a  read  error occurs, the error indicator for the stream shall be set,
42       fgetc() shall return EOF,  and shall set errno to indicate the error.
43

ERRORS

45       The fgetc() function shall fail if data needs to be read and:
46
47       EAGAIN The O_NONBLOCK flag is set for the  file  descriptor  underlying
48              stream  and  the  process would be delayed in the fgetc() opera‐
49              tion.
50
51       EBADF  The file descriptor  underlying  stream  is  not  a  valid  file
52              descriptor open for reading.
53
54       EINTR  The  read  operation was terminated due to the receipt of a sig‐
55              nal, and no data was transferred.
56
57       EIO    A physical I/O error has occurred, or the process is in a  back‐
58              ground  process  group  attempting  to read from its controlling
59              terminal, and either the process is  ignoring  or  blocking  the
60              SIGTTIN  signal or the process group is orphaned. This error may
61              also be generated for implementation-defined reasons.
62
63       EOVERFLOW
64              The file is a regular file and an attempt was made to read at or
65              beyond  the  offset  maximum  associated  with the corresponding
66              stream.
67
68
69       The fgetc() function may fail if:
70
71       ENOMEM Insufficient storage space is available.
72
73       ENXIO  A request was made of a nonexistent device, or the  request  was
74              outside the capabilities of the device.
75
76
77       The following sections are informative.
78

EXAMPLES

80       None.
81

APPLICATION USAGE

83       If  the  integer value returned by fgetc() is stored into a variable of
84       type char and then compared against the integer constant EOF, the  com‐
85       parison may never succeed, because sign-extension of a variable of type
86       char on widening to integer is implementation-defined.
87
88       The ferror() or feof() functions must be used to distinguish between an
89       error condition and an end-of-file condition.
90

RATIONALE

92       None.
93

FUTURE DIRECTIONS

95       None.
96

SEE ALSO

98       feof(), ferror(), fopen(), getchar(), getc(), the Base Definitions vol‐
99       ume of IEEE Std 1003.1-2001, <stdio.h>
100

102       Portions of this text are reprinted and reproduced in  electronic  form
103       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
104       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
105       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
106       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
107       event of any discrepancy between this version and the original IEEE and
108       The Open Group Standard, the original IEEE and The Open Group  Standard
109       is  the  referee document. The original Standard can be obtained online
110       at http://www.opengroup.org/unix/online.html .
111
112
113
114IEEE/The Open Group                  2003                            FGETC(3P)
Impressum