HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

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 char-
acter 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 argument
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 align-
ment 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 indi-
cate 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: February 2007 − 1 − Hewlett-Packard Company 499