HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

g
getc(3S) getc(3S)
NAME
getc( ), getc_unlocked( ), getchar(), getchar_unlocked( ), fgetc( ), getw() - 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
indicate the error, and EOF is returned.
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.
ferror() and feof() can be used to distinguish between an error condition and an end-of-file condi-
tion.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−309