getc.3s (2010 09)

g
getc(3S) getc(3S)
NAME
getc(), getc_unlocked(), getchar(), getchar_unlocked(), fgetc(), getw(), getw_unlocked() - get character or
word from a stream file
SYNOPSIS
#include <stdio.h>
int getc(FILE *stream);
int getc_unlocked(FILE *stream);
int getchar(void);
int getchar_unlocked(void);
int fgetc(FILE *stream);
int getw(FILE *stream);
Obsolescent Interface
int getw_unlocked(FILE *stream);
DESCRIPTION
getc() Returns the next character (i.e., byte) from the named input stream , as an unsigned
character converted to an integer. It also moves the file pointer, if defined, ahead one
character in stream . getchar() is defined as getc(stdin). getc() and
getchar() are defined both as macros and as functions.
fgetc() Same as getc(), but is a function rather than a macro. fgetc() is slower than
getc(), but it takes less space per invocation and its name can be passed as an argu-
ment to a function.
getw() returns the next word (i.e., int in C) 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.
getc_unlocked() and getchar_unlocked()
are identical to getc() and getchar() respec-
tively except they do not perform any internal locking of the stream for multithreaded applications.
Obsolescent Interface
getw_unlocked() gets character or word from a stream file.
APPLICATION USAGE
getc_unlocked() and
getchar_unlocked() interfaces should be used by multithread applica-
tions which have already used
flockfile() to acquire a mutual exclusion lock for the stream (see
flockfile (3S)).
After
getc(), getc_unlocked(), getchar(), getchar_unlocked()
, fgetc(),orgetw() is
applied to a stream, the stream becomes byte-oriented (see orientation (5)).
RETURN VALUE
Upon successful completion,
getc(), getc_unlocked(), getchar(), getchar_unlocked()
,
and
fgetc() return the next byte from the input stream pointed to by stream (stdin for getchar()
and getchar_unlocked()). If the stream is at end-of-file, the end-of-file indicator for the stream is
set and EOF is returned. If a read error occurs, the error indicator for the stream is set, errno is set to
indicate the error and EOF is returned.
When the file corresponding to an open stream gets extended after the end-of-file is reached, any subse-
quent calls to these functions will succeed and the end-of-file indicator will remain set. However, in the
UNIX2003 standards environment (see standards (5)), these functions will return EOF and the end-of-file
indicator will still remain set.
Upon successful completion,
getw() and getw_unlocked() return the next word 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 getw() and getw_unlocked() return EOF. If a read error occurs, the error indicator for the
stream is set, and getw() and getw_unlocked() return EOF and set errno to indicate the error.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1