getc(S)

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

Syntax

cc . . . -lc

#include  <stdio.h>

int getc (stream)
FILE *stream;

int getchar ()

int fgetc (stream)
FILE *stream;

int getw (stream)
FILE *stream;

Description

The getc function returns the next character (that is, the next byte) from the named input stream, as an integer. It also moves the file pointer, if defined, ahead one character in stream. getchar is defined as getc(stdin). getc and getchar are macros.

The fgetc function 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.

The getw function returns the next word (that is, the next 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.

Diagnostics

These functions return the constant EOF at end-of-file or upon an error. Because EOF is a valid integer, ferror(S) should be used to detect getw errors.

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.

The fgetc() function may fail if:

[ENOMEM]: Insufficient storage space is available.
[ENXIO]: A requesto was made of non-existent device, or the request was outside the capabilities of the device.

Warning

If the integer value returned by getc, getchar, or fgetc is stored into a character variable and then compared against the integer constant EOF, the comparison may never succeed, because the sign-extension of a character on widening to an integer is machine-dependent.

Notes

Because it is implemented as a macro, getc evaluates a stream argument more than once. In particular, getc(f++) does not work well. fgetc should be used instead.

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

Example

The getchar function is typically used in a conditional loop to read a string of characters from the standard input. For example, the following function reads cnt number of characters from the keyboard:

   readn (p, cnt)
   char  p[ ];
   int   cnt;
   {
           int i,c;
   
           i = 0;
           while ( i<cnt )
                   if (( p[i++] = getchar()) == EOF ) {
                           p[i] = 0;
                          return(EOF);
                   }
           return(0);
   }

Note that if getchar is reading from the keyboard, it waits for characters to be entered before returning.

Standards conformance

fgetc, getc and getchar are conformant with:

X/Open Portability Guide, Issue 3, 1989 ;
ANSI X3.159-1989 Programming Language -- C ;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

getw is conformant with:

Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;
and X/Open Portability Guide, Issue 3, 1989 .