GETC(3s,L)                  AIX Technical Reference                  GETC(3s,L)



-------------------------------------------------------------------------------
getc, fgetc, getchar, getw, getwc, fgetwc, getwchar



PURPOSE

Gets a character, a wide character, or word from an input stream.

LIBRARY

Standard I/O Library (libc.a)

SYNTAX

#include <stdio.h>




                int getc (stream)           int getchar ( )
                FILE *stream;
                                            int getw (stream)
                int fgetc (stream)          FILE *stream;
                FILE *stream;
                                            wchar_t getwchar ( )
                wchar_t getwc (stream)
                FILE *stream;

                wchar_t fgetwc (stream)
                FILE *stream;



DESCRIPTION

The getc macro returns the next character (byte) from the input specified by
the stream parameter and moves the file pointer, if defined, ahead one
character in stream.  getc is a macro and cannot be used where a subroutine is
necessary; for example, a subroutine pointer cannot point to it.

Because it is implemented as a macro, getc does not work correctly with a
stream parameter that has side effects.  In particular, the following does not
work:

  getc(*f++)

In cases like this, use the fgetc subroutine instead.

The fgetc subroutine performs the same function as getc, but fgetc is a genuine
subroutine, not a macro.  The fgetc subroutine runs more slowly than getc, but
takes less space.



Processed November 7, 1990        GETC(3s,L)                                  1






GETC(3s,L)                  AIX Technical Reference                  GETC(3s,L)




The getchar macro returns the next character from the standard input stream,
stdin.  Note that getchar is also a macro.

The getw subroutine returns the next word (int) from the input specified by the
stream parameter and increments the associated file pointer, if defined, to
point to the next word.  The size of a word varies from one machine
architecture to another.  The getw subroutine returns the constant EOF at
end-of-file or when an error occurs.  Since EOF is a valid integer value, feof
and ferror should be used to check the success of getw.  The getw subroutine
assumes no special alignment in the file.

Because of possible differences in word length and byte ordering from one
machine architecture to another, files written using putw are machine-dependent
and may not be readable using getw on a different type of processor.

The getwchar subroutine is equivalent to getwc with the argument stdin.

The fgetwc subroutine is equivalent to fgetc except a wide character is
returned.

The getwc function obtains the next wide character, if present, from the input
stream pointed to by stream, and advances the associated file position
indicator for the stream, if defined.  The file position indicator is advanced
for each multibyte character obtained.

The fgetwc and the getwchar subroutines return the next wide character which
corresponds to a multibyte character 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 fgetwc returns WEOF.  If a read error occurs, the error
indicator for the stream is set and fgetwc returns WEOF.

RETURN VALUE

The getc, fgetc, getchar, and getw return the integer constant EOF at
end-of-file or error, while the getwc, fgetwc, and getwchar return WEOF at
end-of-file or error.

ERROR CONDITIONS

These subroutines fail if one or more of the following are true:

EAGAIN    The O_NONBLOCK flag is set for the file descriptor underlying stream
          and the process is delayed in the fgetc() operation.

EBADF     The file descriptor underlying stream is not a valid file descriptor
          open for reading.

          Note:  If a wide character routine fails and errno is not set, this
                 indicates that the translation from file code to wide code has
                 failed.




Processed November 7, 1990        GETC(3s,L)                                  2






GETC(3s,L)                  AIX Technical Reference                  GETC(3s,L)



EINTR     The read operation was terminated due to the receipt of a signal and
          no data was transferred.

EIO       The process is a member of a background process attempting to read
          from its controlling terminal, the process is either ignoring or
          blocking the SIGTTIN signal or the process group is orphaned.

ENOMEM    Insufficient storage space is available.

ENXIO     A request was made of a non-existent device, or the request was
          outside the capabilities of the device.

RELATED INFORMATION

In this book:  "feof, ferror, clearerr, fileno," "fopen, freopen, fdopen,"
"fread, fwrite," "gets, fgets, getws, fgetws," "NLgetctab," "putc, putchar,
fputc, putw, putwc, putwchar, fputwc," "scanf, fscanf, sscanf, NLscanf,
NLfscanf, NLsscanf, wsscanf," and "stdio."





































Processed November 7, 1990        GETC(3s,L)                                  3