getc(3S)

getc, getc_unlocked, getchar, getchar_unlocked, fgetc, getw -- get character or word from a stream

Synopsis

   #include <stdio.h>
   
   int getc(FILE *stream);
   

   int getc_unlocked(FILE *stream);
   

   int getchar(void);
   

   int getchar_unlocked(void);
   

   int fgetc(FILE *stream);
   

   int getw(FILE *stream);

Description

getc and getc_unlocked return the next character (that is, byte) from the named input stream [see intro(3)] as an unsigned char converted to an int. It also moves the file pointer, if defined, ahead one character in stream. getchar is defined as getc(stdin).

getc_unlocked and getchar_unlocked provide unsynchronized character I/O that require explicit synchronization around their use when multiple threads are performing I/O. These two are defined as macros when cc(1) is invoked with -Kthread. getchar_unlocked is defined as getc_unlocked(stdin). They may be used safely in a multi-threaded application if and only if they are called while the calling thread has exclusive access to stream for getc_unlocked and stdin for getchar_unlocked. Exclusive access is granted using the lockfile or ftrylockfile functions.

fgetc behaves like getc, but is a function rather than a macro. fgetc runs more slowly than getc, but it takes less space per invocation and its name can be passed as an argument to a function.

getw returns the next word (that is, integer) from the named input stream. getw increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. getw assumes no special alignment in the file.

Errors

If the stream is at EOF, the EOF indicator for the stream is set and getc and getc_unlocked return EOF. If a read error occurs, the error indicator for the stream is set, getc and getc_unlocked return EOF and set errno to identify the error.

Under the following conditions, the functions getc, getchar, fgetc and getw fail and set errno to:

EAGAIN: if the O_NONBLOCK flag is set for the underlying file descriptor and the process would have blocked in the read operation.
EBADF: if the underlying file descriptor is not a valid file descriptor open for reading.
EINTR: if a signal was caught during the getc, getchar, fgetc or getw call, and no data was transferred.
EIO: if a physical I/O error has occurred, or the process is in a background process group and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned.
EOVERFLOW: The process is tryping to read at or beyond the offset maximum associated with the corresponding stream.

References

fclose(3S), ferror(3S), fopen(3S), fread(3S), fscanf(3S), ftrylockfile(3S), flockfile(3S), gets(3S), intro(3), Intro(3S), putc(3S), ungetc(3S)

Notices

If the integer value returned by all of the above routines except getw is stored into a character variable and then compared against the integer constant EOF, the comparison may never succeed, because sign-extension of a character on widening to integer is implementation dependent.

The macro version of getc evaluates a stream argument more than once and may treat side effects incorrectly. In particular, getc(*f++) does not work sensibly. Use fgetc instead.

Because of possible differences in word length and byte ordering, files written using putw are implementation dependent, and may not be read using getw on a different processor.

Functions exist for all the above-defined macros. To get the function form, the macro name must be undefined (for example, #undef getc).