getc(3S) DG/UX R4.11MU05 getc(3S)
NAME
getc, getcunlocked, getchar, getcharunlocked, fgetc, getw - get
character or word from a stream
SYNOPSIS
#include <stdio.h>
int getc(FILE *stream);
int getcunlocked(FILE *stream);
int getchar(void);
int getcharunlocked(void);
int fgetc(FILE *stream);
int getw(FILE *stream);
DESCRIPTION
getc and getcunlocked return the next character (that is, byte) from
the named input stream [see intro(3)] as an unsigned char converted
to an int. It also moves the file pointer, if defined, ahead one
character in stream. getchar is defined as getc(stdin).
getcunlocked and getcharunlocked provide unsynchronized character
I/O that require explicit synchronization around their use when
multiple threads are performing I/O. getcharunlocked is defined as
getcunlocked(stdin). They may be used safely in a multi-threaded
application if and only if they are called while the calling thread
has exclusive access to stream for getcunlocked and stdin for
getcharunlocked. Exclusive access is granted using the flockfile or
ftrylockfile functions.
fgetc 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.
getw returns the next word (that is, 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.
Errors
If the stream is at EOF, the EOF indicator for the stream is set and
getc and getcunlocked return EOF. If a read error occurs, the error
indicator for the stream is set, getc and getcunlocked return EOF
and set errno to identify the error.
Under the following conditions, the functions getc, getchar, fgetc
and getw fail and set errno to:
EAGAIN if the ONONBLOCK 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.
Considerations for Threads Programming
+-----------------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+-----------------+-----------------------------+
|fgetc | Y Y N |
|getc | Y Y N |
|getcunlocked | N - - |
|getchar | Y Y N |
|getcharunlocked | N - - |
|getw | Y N N |
+-----------------+-----------------------------+
REFERENCES
reentrant(3), fclose(3S), ferror(3S), fopen(3S), fread(3S),
ftrylockfile(3C), flockfile(3C), gets(3S), putc(3S), scanf(3S),
stdio(3S), ungetc(3S)
NOTICES
If the integer value returned by all of the above routines except
getw is stored into a character variable and then compared against
the integer constant EOF, the comparison may never succeed, because
sign-extension of a character on widening to integer is
implementation dependent.
The macro version of getc evaluates a stream argument more than once
and may treat side effects incorrectly. In particular, getc(*f++)
does not work sensibly. Use fgetc instead.
Because of possible differences in word length and byte ordering,
files written using putw are implementation dependent, and may not be
read using getw on a different processor.
Functions exist for all the above-defined macros. To get the
function form, the macro name must be undefined (for example, #undef
getc).
Licensed material--property of copyright holder(s)