1fgetc(3C) Standard C Library Functions fgetc(3C)
2
6 fgetc, getc, getc_unlocked, getchar, getchar_unlocked, getw - get a
7 byte from a stream
8
10 #include <stdio.h>
11 int fgetc(FILE *stream);
13 int getc(FILE *stream);
16 int getc_unlocked(FILE *stream);
19 int getchar(void);
22 int getchar_unlocked(void);
25 int getw(FILE *stream);
28
31 The fgetc() function obtains the next byte (if present) as an unsigned
32 char converted to an int, from the input stream pointed to by stream,
33 and advances the associated file position indicator for the stream (if
34 defined).
35 For standard-conforming (see standards(5)) applications, if the end-of-
38 file indicator for the stream is set, fgetc() returns EOF whether or
39 not a next byte is present.
40 The fgetc() function may mark the st_atime field of the file associated
43 with stream for update. The st_atime field will be marked for update by
44 the first successful execution of fgetc(), fgets(3C), fread(3C),
45 fscanf(3C), getc(), getchar(), gets(3C) or scanf(3C) using stream that
46 returns data not supplied by a prior call to ungetc(3C) or ungetwc(3C).
47 The getc() function is functionally identical to fgetc(), except that
50 it is implemented as a macro. It runs faster than fgetc(), but it takes
51 up more space per invocation and its name cannot be passed as an argu‐
52 ment to a function call.
53 The getchar() routine is equivalent to getc(stdin). It is implemented
56 as a macro.
57 The getc_unlocked() and getchar_unlocked() routines are variants of
60 getc() and getchar(), respectively, that do not lock the stream. It is
61 the caller's responsibility to acquire the stream lock before calling
62 these routines and releasing the lock afterwards; see flockfile(3C) and
63 stdio(3C). These routines are implemented as macros.
64 The getw() function reads the next word from the stream. The size of a
67 word is the size of an int and may vary from environment to environ‐
68 ment. The getw() function presumes no special alignment in the file.
69 The getw() function may mark the st_atime field of the file associated
72 with stream for update. The st_atime field will be marked for update by
73 the first successful execution of fgetc(), fgets(3C), fread(3C),
74 getc(), getchar(), gets(3C), fscanf(3C) or scanf(3C) using stream that
75 returns data not supplied by a prior call to ungetc(3C).
76
78 Upon successful completion, fgetc(), getc(), getc_unlocked(),
79 getchar(), getchar_unlocked(), and getw() return the next byte from the
80 input stream pointed to by stream. If the stream is at end-of-file, the
81 end-of-file indicator for the stream is set and these functions return
82 EOF. For standard-conforming (see standards(5)) applications, if the
83 end-of-file indicator for the stream is set, these functions return EOF
84 whether or not the stream is at end-of-file. If a read error occurs,
85 the error indicator for the stream is set, EOF is returned, and errno
86 is set to indicate the error.
87
89 The fgetc(), getc(), getc_unlocked(), getchar(), getchar_unlocked(),
90 and getw() functions will fail if data needs to be read and:
91 EAGAIN The O_NONBLOCK flag is set for the file descriptor under‐
93 lying stream and the process would be delayed in the
94 fgetc() operation.
95 EBADF The file descriptor underlying stream is not a valid file
98 descriptor open for reading.
99 EINTR The read operation was terminated due to the receipt of a
102 signal, and no data was transferred.
103 EIO A physical I/O error has occurred, or the process is in a
106 background process group attempting to read from its con‐
107 trolling terminal, and either the process is ignoring or
108 blocking the SIGTTIN signal or the process group is
109 orphaned. This error may also be generated for implementa‐
110 tion-dependent reasons.
111 EOVERFLOW The file is a regular file and an attempt was made to read
114 at or beyond the offset maximum associated with the corre‐
115 sponding stream.
116 The fgetc(), getc(), getc_unlocked(), getchar(), getchar_unlocked(),
120 and getw() functions may fail if:
121 ENOMEM Insufficient storage space is available.
123 ENXIO A request was made of a non-existent device, or the request
126 was outside the capabilities of the device.
127</