Gets a character or word from an input stream.
Standard I/O Package (libc.a)
#include <stdio.h>int getc ( Stream)
FILE *Stream;
int fgetc (Stream)
FILE *Stream;int getchar (void)int getw (Stream)
FILE *Stream;The getc macro returns the next byte as an unsigned char data type converted to an int data type from the input specified by the Stream parameter and moves the file pointer, if defined, ahead one byte in the Stream parameter. The getc macro cannot be used where a subroutine is necessary; for example, a subroutine pointer cannot point to it.
Because it is implemented as a macro, the getc macro does not work correctly with a Stream parameter value that has side effects. In particular, the following does not work:
getc(*f++)In such cases, use the fgetc subroutine.
The fgetc subroutine performs the same function as the getc macro, but fgetc is a true subroutine, not a macro. The fgetc subroutine runs more slowly than getc but takes less disk space.
The getchar macro returns the next byte from stdin (the standard input stream). The getchar macro is equivalent to getc(stdin).
The first successful run of the fgetc, fgets, fgetwc, fgetws, fread, fscanf, getc, getchar, gets or scanf subroutine using a stream that returns data not supplied by a prior call to the ungetc or ungetwc subroutine marks the st_atime field for update.
The getc and getchar macros have also been implemented as subroutines for ANSI compatibility. To access the subroutines instead of the macros, insert #undef getc or #undef getchar at the beginning of the source file.
The getw subroutine returns the next word (int) from the input specified by the Stream parameter and increments the associated file pointer, if defined, to point to the next word. The size of a word varies from one machine architecture to another. The getw subroutine returns the constant EOF at the end of the file or when an error occurs. Since EOF is a valid integer value, the feof and ferror subroutines should be used to check the success of getw. The getw subroutine assumes no special alignment in the file.
Because of additional differences in word length and byte ordering from one machine architecture to another, files written using the putw subroutine are machine-dependent and may not be readable using the getw macro on a different type of processor.
| Item | Description |
|---|---|
| Stream | Points to the file structure of an open file. |
Upon successful completion, the getc, fgetc, getchar, and getw subroutines return the next byte or int data type from the input stream pointed by the Stream parameter. If the stream is at the end of the file, an end-of-file indicator is set for the stream and the integer constant EOF is returned. If a read error occurs, the errno global variable is set to reflect the error, and a value of EOF is returned. The ferror and feof subroutines should be used to distinguish between the end of the file and an error condition.
If the stream specified by the Stream parameter is unbuffered or data needs to be read into the stream's buffer, the getc, getchar, fgetc, or getw subroutine is unsuccessful under the following error conditions:
| Item | Description |
|---|---|
| EAGAIN | Indicates that the O_NONBLOCK flag is set for the file descriptor underlying the stream specified by the Stream parameter. The process would be delayed in the fgetc subroutine operation. |
| EBADF | Indicates that the file descriptor underlying the stream specified by the Stream parameter is not a valid file descriptor opened for reading. |
| EFBIG | Indicates that an attempt was made to read a file that exceeds the process' file-size limit or the maximum file size. See the ulimit subroutine. |
| EINTR | Indicates that
the read operation was terminated due to the
receipt of a signal, and either no data was transferred, or the implementation
does not report partial transfer for this file. Note: Depending upon
which library routine the application binds to, this subroutine may
return EINTR. Refer to the signal subroutine regarding sa_restart.
|
| EIO | Indicates that a physical error has occurred, or the process is in a background process group attempting to perform a read subroutine call from its controlling terminal, and either the process is ignoring (or blocking) the SIGTTIN signal or the process group is orphaned. |
| EPIPE | Indicates that an attempt is made to read from a pipe or first-in-first-out (FIFO) that is not open for reading by any process. A SIGPIPE signal will also be sent to the process. |
| EOVERFLOW | Indicates that the file is a regular file and an attempt was made to read at or beyond the offset maximum associated with the corresponding stream. |
The getc, getchar, fgetc, or getw subroutine is also unsuccessful under the following error conditions:
| Item | Description |
|---|---|
| ENOMEM | Indicates insufficient storage space is available. |
| ENXIO | Indicates either a request was made of a nonexistent device or the request was outside the capabilities of the device. |