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);

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(), getchar_unlocked(), and getw_unlocked() are identical to getc(), getchar(), and getw() respectively except they do not perform any internal locking of the stream for multi-thread applications. The _unlocked routines can be used by multi-thread applications which have already used flockfile() to acquire a mutual exclusion lock for the stream (see flockfile(3S)).

RETURN VALUE

Upon sucessful 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 sucessful 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() (or their _unlocked versions) 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)).

WARNING

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>
#undefgetc
...
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. For multi-thread applications, if _STDIO_UNLOCK_CHAR_IO is also defined before including <stdio.h>, the unlocked macro versions will be used by default for getc() and getchar().

STANDARDS CONFORMANCE

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

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

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

Hewlett-Packard Company — HP-UX Release 10.20: July 1996

Museum

Related Articles