getc(3)getc(3)NAME
getc, fgetc, getc_unlocked, getchar, getchar_unlocked, getw - Get a
byte or word from an input stream
SYNOPSIS
#include <stdio.h>
int getc(
FILE *stream ); int fgetc(
FILE *stream ); int getc_unlocked(
FILE *stream ); int getchar(
void ); int getchar_unlocked(
void ); int getw(
FILE *stream );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fgetc(), getc_unlocked, getc(), getchar(), getchar_unlocked, getw():
XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Points to the file structure of an open file.
DESCRIPTION
The getc() function returns the next byte from the input specified by
the stream parameter and moves the file pointer, if defined, ahead one
byte in stream. The getc() function may be a macro (depending on com‐
pile-time definitions). See the NOTES section for more information.
The fgetc() function performs the same function as getc().
The getchar() function returns the next byte from stdin, the standard
input stream. Note that getchar() can also be a macro.
[Tru64 UNIX] The reentrant versions of these functions are all locked
against multiple threads calling them simultaneously. This will incur
an overhead to ensure integrity of the stream. The unlocked versions of
these calls, getc_unlocked() and getchar_unlocked() may be used to
avoid the overhead. The getc_unlocked() and getchar_unlocked() func‐
tions are functionally identical to the getc() and getchar() functions,
except that getc_unlocked() and getchar_unlocked() may be safely used
only within a scope that is protected by the flockfile() and funlock‐
file() functions used as a pair. The caller must ensure that the
stream is locked before these functions are used. The getc() and
getchar() functions can also be macros.
The getw() function reads the next word (int) from the stream. The size
of a word is the size of an int, which may vary from one machine archi‐
tecture to another. The getw() function returns the constant EOF at the
end of the file or when an error occurs. Since EOF is a valid integer
value, the feof() and ferror() functions can be used to check the suc‐
cess of getw(). The getw() function assumes no special alignment in the
file.
Because of possible differences in int length and byte ordering from
one machine architecture to another, files written using the putw()
subroutine are machine dependent and may not be readable using getw()
on a different type of processor.
NOTES
The getc() and getchar() functions may be macros (depending on the com‐
pile-time definitions used in the source). Consequently, you cannot
use these interfaces where a function is necessary; for example, a sub‐
routine pointer cannot point to one of these interfaces. In addition,
getc() does not work correctly with a stream parameter that has side
effects. In particular, the following does not work:
getc(*f++)
In cases like this one, use the fgetc() function instead.
RETURN VALUES
Upon successful completion, these functions and macros return the next
byte or word from the input stream. If the stream is at end-of-file,
the end-of-file indicator for the stream is set and the integer con‐
stant EOF is returned. If a read error occurs, the error indicator for
the stream is set, EOF is returned, and errno is set to indicate the
error.
Because the EOF return is used to signal both a successful completion
and an error (accompanied by errno), it is incumbent on the user to
clear any pre-existing errno values before invoking these functions.
ERRORS
The fgetc(), getc(), getc_unlocked(), getchar(), getchar_unlocked(),
and getw() functions set errno to the specified value for the following
conditions: The O_NONBLOCK option is set for the underlying stream and
the process would be delayed by the read operation. The file descrip‐
tor underlying the stream is not a valid file descriptor or is not open
for reading. The read operation was interrupted by a signal which was
caught and no data was transferred. The call is attempting to read
from the process's controlling terminal and either the process is
ignoring or blocking the SIGTTIN signal or the process group is
orphaned.
A physical I/O error has occurred. (This condition was defined
for Issue 4 Version 2 and higher issues of the XSH specifica‐
tion.) Insufficient memory is available for the operation. The
device associated with stream does not exist.
SEE ALSO
Functions: flockfile(3), funlockfile(3), gets(3), getwc(3), putc(3)
Standards: standards(5)getc(3)
