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 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 alignment in the file.

getc_unlocked() and getchar_unlocked() are identical to getc() and getchar() respectively 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 applications 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(), or getw() 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 subsequent 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.

ferror() and feof() can be used to distinguish between an error condition and an end-of-file condition.

ERRORS

getc(), getc_unlocked(), getchar(), getchar_unlocked(), getw(), getw_unlocked(), and fgetc() fail if data needs to be read into the stream's buffer, and:

EAGAIN: The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the read operation.
EBADF: The file descriptor underlying stream is not a valid file descriptor open for reading.
EINTR: The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file.
EIO: A physical I/O error has occurred, or the process is a member of a background process 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.

Additional errno values may be set by the underlying read() function (see read(2)).

WARNINGS

getc() and getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in <stdio.h>. To obtain the library function either use a #undef to remove the macro definition or, if compiling in ANSI-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods :

#include <stdio.h> 
#undef getc 
    ...
main()
{
    int (*get_char()) ();
    ...
    return_val=getc(c,fd);
    ...
    return_val=(getc)(c,fd1);
    ...
    get_char = getchar;
};

If the integer value returned by getc(), getc_unlocked(), getchar(), getchar_unlocked(), or fgetc() is stored into a character variable then compared against the integer constant EOF, the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent.

The macro version of getc() incorrectly treats a stream argument with side effects. In particular, getc(*f++) does not work sensibly. The function version of getc() or fgetc() should be used instead.

Because of possible differences in word length and byte ordering, files written using putw() are machine-dependent, and may be unreadable by getw() on a different processor.

Reentrant Interfaces

If _REENTRANT is defined before including <stdio.h>, the locked versions of the library functions for getc() and getchar() are used by default.

getw_unlocked() is an obsolescent interface supported only for compatibility with existing DCE applications. New multithreaded applications should use getw().

STANDARDS CONFORMANCE

getc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

getc_unlocked(): POSIX.1C

fgetc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C

getchar(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

getchar_unlocked(): POSIX.1C

getw(): AES, SVID2, SVID3, XPG2, XPG3, XPG4

getc(3S)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interface

DESCRIPTION

Obsolescent Interface

APPLICATION USAGE

RETURN VALUE

ERRORS

WARNINGS

Reentrant Interfaces

SEE ALSO

STANDARDS CONFORMANCE