FGETC(3C) Standard C Library Functions FGETC(3C)
NAME
fgetc, getc, getc_unlocked, getchar, getchar_unlocked, getw - get a byte
from a stream
SYNOPSIS
#include <stdio.h>
int fgetc(
FILE *stream);
int getc(
FILE *stream);
int getc_unlocked(
FILE *stream);
int getchar(
void);
int getchar_unlocked(
void);
int getw(
FILE *stream);
DESCRIPTION
The
fgetc() function obtains the next byte (if present) as an
unsigned char converted to an
int, from the input stream pointed to by
stream, and
advances the associated file position indicator for the stream (if
defined).
For standard-conforming (see
standards(7)) applications, if the end-of-
file indicator for the stream is set,
fgetc() returns
EOF whether or not
a next byte is present.
The
fgetc() function may mark the
st_atime field of the file associated
with
stream for update. The
st_atime field will be marked for update by
the first successful execution of
fgetc(),
fgets(3C),
fread(3C),
fscanf(3C),
getc(),
getchar(),
gets(3C) or
scanf(3C) using
stream that
returns data not supplied by a prior call to
ungetc(3C) or
ungetwc(3C).
The
getc() function is functionally identical to
fgetc(), except that it
is implemented as a macro. It runs faster than
fgetc(), but it takes up
more space per invocation and its name cannot be passed as an argument to
a function call.
The
getchar() routine is equivalent to
getc(stdin). It is implemented as
a macro.
The
getc_unlocked() and
getchar_unlocked() routines are variants of
getc() and
getchar(), respectively, that do not lock the stream. It is
the caller's responsibility to acquire the stream lock before calling
these routines and releasing the lock afterwards; see
flockfile(3C) and
stdio(3C). These routines are implemented as macros.
The
getw() function reads the next word from the
stream. The size of a
word is the size of an
int and may vary from environment to environment.
The
getw() function presumes no special alignment in the file.
The
getw() function may mark the
st_atime field of the file associated
with
stream for update. The
st_atime field will be marked for update by
the first successful execution of
fgetc(),
fgets(3C),
fread(3C),
getc(),
getchar(),
gets(3C),
fscanf(3C) or
scanf(3C) using
stream that returns
data not supplied by a prior call to
ungetc(3C).
RETURN VALUES
Upon successful completion,
fgetc(),
getc(),
getc_unlocked(),
getchar(),
getchar_unlocked(), and
getw() return the next byte from the input stream
pointed to by
stream. If the stream is at end-of-file, the end-of-file
indicator for the stream is set and these functions return
EOF. For
standard-conforming (see
standards(7)) applications, if the end-of-file
indicator for the stream is set, these functions return
EOF whether or
not the stream is at end-of-file. If a read error occurs, the error
indicator for the stream is set,
EOF is returned, and
errno is set to
indicate the error.
ERRORS
The
fgetc(),
getc(),
getc_unlocked(),
getchar(),
getchar_unlocked(), and
getw() functions will 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-dependent 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(),
getc(),
getc_unlocked(),
getchar(),
getchar_unlocked(), and
getw() functions may fail if:
ENOMEM Insufficient storage space is available.
ENXIO A request was made of a non-existent device, or the request was
outside the capabilities of the device.
USAGE
If the integer value returned by
fgetc(),
getc(),
getc_unlocked(),
getchar(),
getchar_unlocked(), and
getw() 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-dependent.
The
ferror(3C) or
feof(3C) functions must be used to distinguish between
an error condition and an end-of-file condition.
Functions exist for the
getc(),
getc_unlocked(),
getchar(), and
getchar_unlocked() macros. To get the function form, the macro name must
be undefined (for example,
#undef getc).
When the macro forms are used,
getc() and
getc_unlocked() evaluate the
stream argument more than once. In particular,
getc(*f++); does not work
sensibly. The
fgetc() function should be used instead when evaluating
the
stream argument has side effects.
Because of possible differences in word length and byte ordering, files
written using
getw() are machine-dependent, and may not be read using
getw() on a different processor.
The
getw() function is inherently byte stream-oriented and is not tenable
in the context of either multibyte character streams or wide-character
streams. Application programmers are recommended to use one of the
character-based input functions instead.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------------------+
|Interface Stability |
fgetc(),
getc(), |
| |
getc_unlocked(),
getchar(), |
| | and
getchar_unlocked() are |
| | Standard. |
+--------------------+-----------------------------+
|MT-Level | See
NOTES below. |
+--------------------+-----------------------------+
SEE ALSO
Intro(3),
__fsetlocking(3C),
fclose(3C),
feof(3C),
fgets(3C),
fgetwc(3C),
fgetws(3C),
flockfile(3C),
fopen(3C),
fread(3C),
fscanf(3C),
gets(3C),
putc(3C),
scanf(3C),
stdio(3C),
ungetc(3C),
ungetwc(3C),
attributes(7),
standards(7)NOTES
The
fgetc(),
getc(),
getchar(), and
getw() routines are MT-Safe in
multithreaded applications. The
getc_unlocked() and
getchar_unlocked() routines are unsafe in multithreaded applications.
October 15, 2003
FGETC(3C)