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

DESCRIPTION

20       The functionality described on this reference page is aligned with  the
21       ISO C  standard.  Any  conflict between the requirements described here
22       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2017
23       defers to the ISO C standard.
24
25       If  the end-of-file indicator for the input stream pointed to by stream
26       is not set and a next byte  is  present,  the  fgetc()  function  shall
27       obtain  the next byte as an unsigned char converted to an int, from the
28       input stream pointed to by stream,  and  advance  the  associated  file
29       position  indicator for the stream (if defined). Since fgetc() operates
30       on bytes, reading a character consisting  of  multiple  bytes  (or  ``a
31       multi-byte character'') may require multiple calls to fgetc().
32
33       The  fgetc()  function  may  mark the last data access timestamp of the
34       file associated with stream for update. The last data access  timestamp
35       shall  be  marked  for  update  by  the  first  successful execution of
36       fgetc(), fgets(), fread(),  fscanf(),  getc(),  getchar(),  getdelim(),
37       getline(),  gets(),  or scanf() using stream that returns data not sup‐
38       plied by a prior call to ungetc().
39

RETURN VALUE

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

ERRORS

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

EXAMPLES

82       None.
83

APPLICATION USAGE

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

RATIONALE

94       None.
95

FUTURE DIRECTIONS

97       None.
98

SEE ALSO

100       Section 2.5, Standard I/O Streams, feof(), ferror(), fgets(),  fread(),
101       fscanf(), getchar(), getc(), gets(), ungetc()
102
103       The Base Definitions volume of POSIX.1‐2017, <stdio.h>
104
106       Portions  of  this text are reprinted and reproduced in electronic form
107       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
108       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
109       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
110       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
111       event of any discrepancy between this version and the original IEEE and
112       The  Open Group Standard, the original IEEE and The Open Group Standard
113       is the referee document. The original Standard can be  obtained  online
114       at http://www.opengroup.org/unix/online.html .
115
116       Any  typographical  or  formatting  errors that appear in this page are
117       most likely to have been introduced during the conversion of the source
118       files  to  man page format. To report such errors, see https://www.ker
119       nel.org/doc/man-pages/reporting_bugs.html .
120
121
122
123IEEE/The Open Group                  2017                            FGETC(3P)
Impressum