fgetc - get byte from stream

Syntax

#include <stdio.h>

int fgetc(FILE *stream);

Description

Description fgetc() reads the next existing byte of type unsigned char from the input stream pointed
to by stream, converts it to an int, and advances the associated file position indicator for
the stream (if defined).

fgets() can mark the structure component st_atime for the file to which stream is
assigned for changing (see sys/stat.h). The structure component st_atime is updated
as soon as fgetc(), fgets(), fgetwc(), fgetws(), fread(), fscanf(), getc(), getchar(), gets() or scanf() are called successfully for stream and return data which is not was not provided by a preceding call to ungetc() or ungetwc().

Return val.

Next byte from the input stream pointed to by stream 

upon successful completion.

 

EOF

EOF

if the stream is at end-of-file. The end-of-file indicator for the stream is set.

if a read error occurs. The error indicator for the stream is set, and errno is set to indicate the error.

Errors

fgetc() will fail if: 

 

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.

Notes

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 machine-dependent.
Portable applications should therefore always use an int variable for the result of fgetc().

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

If a comparison such as:

while((c = fgetc(dz)) != EOF)

is used in a program, the variable c must always be declared as an int value.
Otherwise, if c were defined as a char, the EOF condition would never be satisfied for the following reason: -1 is converted to the char value 0xFF (i.e. +255); however, EOF is defined as -1.

If fgetc() is reading from the standard input stdin in the POSIX environment, and EOF is the end criterion for reading, the EOF condition can be achieved by the following actions:

>	on a block-special terminal: by entering the key sequence [@][@][d]
>	on a character-special terminal: by entering [CTRL]+[D]

BS2000
If fgetc() is reading from the standard input stdin in the BS2000 environment, and EOF is the end criterion for reading, the EOF condition can be achieved by means of the following actions at the terminal:

1. by pressing the [K2] key.

2. by entering the system commands EOF and RESUME-PROGRAM.

The following applies in the case of text files with SAM access mode and variable record length for which a maximum record length is also specified: When the specification split=no was entered for fopen(), records of maximum length are not concatenated with the subsequent record when they are read. By default or with the specification split=yes, when a record with maximum record length is read, it is assumed that the following record is the continuation of this record and the records are concatenated.

For text files with access mode SAM or ISAM, fgetc() returns an additional newline character at the end of a sentence. In this case, a subsequent call to _fnlinserted() returns a value other than 0. In all other cases, a subsequent call to _fnlinserted() returns the value 0.  (End)

The program environment determines whether fgetc() is executed for a BS2000 or POSIX file.

See also

feof(), ferror(), _fnlinserted(), fopen(), getchar, getc(), stdio.h, sys/stat.h.