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
130 If the integer value returned by fgetc(), getc(), getc_unlocked(),
131 getchar(), getchar_unlocked(), and getw() is stored into a variable of
132 type char and then compared against the integer constant EOF, the com‐
133 parison may never succeed, because sign-extension of a variable of type
134 char on widening to integer is implementation-dependent.
135 The ferror(3C) or feof(3C) functions must be used to distinguish
138 between an error condition and an end-of-file condition.
139 Functions exist for the getc(), getc_unlocked(), getchar(), and
142 getchar_unlocked() macros. To get the function form, the macro name
143 must be undefined (for example, #undef getc).
144 When the macro forms are used, getc() and getc_unlocked() evaluate the
147 stream argument more than once. In particular, getc(*f++); does not
148 work sensibly. The fgetc() function should be used instead when evalu‐
149 ating the stream argument has side effects.
150 Because of possible differences in word length and byte ordering, files
153 written using getw() are machine-dependent, and may not be read using
154 getw() on a different processor.
155 The getw() function is inherently byte stream-oriented and is not ten‐
158 able in the context of either multibyte character streams or wide-char‐
159 acter streams. Application programmers are recommended to use one of
160 the character-based input functions instead.
161
163 See attributes(5) for descriptions of the following attributes:
164 ┌─────────────────────────────┬─────────────────────────────┐
169 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
170 ├─────────────────────────────┼─────────────────────────────┤
171 │Interface Stability │fgetc(), getc(), │
172 │ │getc_unlocked(), getchar(), │
173 │ │and getchar_unlocked() are │
174 │ │Standard. │
175 ├─────────────────────────────┼─────────────────────────────┤
176 │MT-Level │See NOTES below. │
177 └─────────────────────────────┴─────────────────────────────┘
178
180 Intro(3), __fsetlocking(3C), fclose(3C), feof(3C), fgets(3C),
181 fgetwc(3C), fgetws(3C), flockfile(3C), fopen(3C), fread(3C),
182 fscanf(3C), gets(3C), putc(3C), scanf(3C), stdio(3C), ungetc(3C),
183 ungetwc(3C), attributes(5), standards(5)
184
186 The fgetc(), getc(), getchar(), and getw() routines are MT-Safe in mul‐
187 tithreaded applications. The getc_unlocked() and getchar_unlocked()
188 routines are unsafe in multithreaded applications.
189SunOS 5.11 15 Oct 2003 fgetc(3C)