GETC(3S)                                                              GETC(3S)


NAME
     getc, getchar, fgetc, getw, getc_unlocked, getchar_unlocked - get
     character or word from a stream

SYNOPSIS
     #include <stdio.h>

     int getc (FILE *stream);

     int getchar (void);

     int fgetc (FILE *stream);

     int getw (FILE *stream);

     int getc_unlocked (FILE *stream);

     int getchar_unlocked (void);

DESCRIPTION
     Fgetc and getc return the next character (if it exists) 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).  Each of getc,getchar and fgetc exist
     as functions in the C library. Getc and getchar are also available as
     macros in <stdio.h> (see below under CAVEATS for important details on the
     implementation of these macros.)

     Getw returns the next word (i.e., integer) from the named input stream.
     Getw increments the associated file pointer, if defined, to point to the
     next integer-sized word.  Getw assumes no special alignment in the file.

     The getc_unlocked and getchar_unlocked functions are equivalent to the
     getc and getchar functions, respectively.  However, these functions are
     not thread-safe and thus must only be called under the protection of the
     flockfile (or ftrylockfile) and funlockfile functions.

SEE ALSO
     fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S),
     scanf(3S), stdio(3S), ungetc(3S).

DIAGNOSTICS
     These functions return the constant EOF at end-of-file or upon an error.
     Because EOF is a valid integer, it is not sufficient to detect getw
     errors.  ferror(3S) must be used as well.

WARNING
     If the integer value returned by getc, getchar, or fgetc is stored into a
     character variable and 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.


CAVEATS
     When using the macro versions of getc and getchar, the stream argument
     may be evaluated more than once.  Thus, it must not be an expression with
     side-effects.  In particular, getc(*f++) does not work sensibly.  In
     these situations, the macro must either be #undef'd, 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 not be read using getw
     on a different processor.

BUGS
     When using the macros for getc and getchar, hidden external names may be
     referenced. Although these names are prefixed with an underscore, they
     may conflict with names which the ANSI C Standard reserves for the user
     when appearing in a local context.  It is thus recommended that users of
     these macros reserve all names which begin with an underscore for the
     implementation, and avoid defining such names, even in a local context.


                                                                        Page 2