NAME

       fgetc - get a byte from a stream

SYNOPSIS

       #include <stdio.h>

       int fgetc(FILE *stream);

DESCRIPTION

       If  the  end-of-file  indicator  for  the input stream pointed to by stream is not set and a next byte is
       present, the fgetc() function shall obtain the next byte as an unsigned char converted to  an  int,  from
       the  input stream pointed to by stream, and advance the associated file position indicator for the stream
       (if defined). Since fgetc() operates on bytes, reading a character consisting of multiple  bytes  (or  "a
       multi-byte character") may require multiple calls to fgetc().

       The  fgetc()  function  may  mark  the  st_atime field of the file associated with stream for update. The
       st_atime field shall be marked for  update  by  the  first  successful  execution  of  fgetc(),  fgets(),
       fgetwc(),  fgetws(),  fread(),  fscanf(), getc(), getchar(), gets(), or scanf() using stream that returns
       data not supplied by a prior call to ungetc() or ungetwc().

RETURN VALUE

       Upon successful completion, fgetc() shall return the next byte  from  the  input  stream  pointed  to  by
       stream.  If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-
       of-file indicator for the stream shall be set and fgetc() shall return EOF. If a read error  occurs,  the
       error indicator for the stream shall be set, fgetc() shall return EOF,    and shall set errno to indicate
       the error.

ERRORS

       The fgetc() function shall fail if data needs to be read and:

       EAGAIN The O_NONBLOCK flag is set for the file descriptor underlying stream  and  the  process  would  be
              delayed in the fgetc() operation.

       EBADF  The file descriptor underlying stream is not a valid file descriptor open for reading.

       EINTR  The read operation was terminated due to the receipt of a signal, and no data was transferred.

       EIO    A  physical  I/O error has occurred, or the process is in a background process group attempting to
              read from its controlling terminal, and either the process is ignoring  or  blocking  the  SIGTTIN
              signal  or  the  process  group  is orphaned. This error may also be generated for implementation-
              defined reasons.

       EOVERFLOW
              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 fgetc() function may fail if:

       ENOMEM Insufficient storage space is available.

       ENXIO  A  request  was  made  of a nonexistent device, or the request was outside the capabilities of the
              device.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       If the integer value returned by fgetc() is stored into a variable of type char and then compared against
       the  integer constant EOF, the comparison may never succeed, because sign-extension of a variable of type
       char on widening to integer is implementation-defined.

       The ferror() or feof() functions must be used to distinguish between an error condition  and  an  end-of-
       file condition.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       feof()  ,  ferror() , fopen() , getchar() , getc() , the Base Definitions volume of IEEE Std 1003.1-2001,
       <stdio.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .