getc(3S)                                                    getc(3S)


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

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

       DESCRIPTION
             getc and getc_unlocked return the next character (that is,
             byte) from the named input stream [see intro(3)] as an
             unsigned char converted to an int.  It also moves the file
             pointer, if defined, ahead one character in stream.  getchar
             is defined as getc(stdin).

             getc_unlocked and getchar_unlocked provide unsynchronized
             character I/O that require explicit synchronization around
             their use when multiple threads are performing I/O.  These two
             are defined as macros when cc(1) is invoked with -Kthread.
             getchar_unlocked is defined as getc_unlocked(stdin).  They may
             be used safely in a multi-threaded application if and only if
             they are called while the calling thread has exclusive access
             to stream for getc_unlocked and stdin for getchar_unlocked.
             Exclusive access is granted using the lockfile or ftrylockfile
             functions.

             fgetc behaves like getc, but is a function rather than a
             macro.  fgetc runs more slowly 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 (that is, integer) 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.

          Errors
             If the stream is at EOF, the EOF indicator for the stream is
             set and getc and getc_unlocked return EOF.  If a read error
             occurs, the error indicator for the stream is set, getc and


                           Copyright 1994 Novell, Inc.               Page 1

      getc(3S)                                                    getc(3S)


            getc_unlocked return EOF and set errno to identify the error.

            Under the following conditions, the functions getc, getchar,
            fgetc and getw fail and set errno to:

            EAGAIN    if the O_NONBLOCK flag is set for the underlying
                      file descriptor and the process would have blocked
                      in the read operation.

            EBADF     if the underlying file descriptor is not a valid
                      file descriptor open for reading.

            EINTR     if a signal was caught during the getc, getchar,
                      fgetc or getw call, and no data was transferred.

            EIO       if a physical I/O error has occurred, or the process
                      is in a background process group 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.

      REFERENCES
            fclose(3S), ferror(3S), fopen(3S), fread(3S), fscanf(3S),
            ftrylockfile(3S), flockfile(3S), gets(3S), putc(3S),
            stdio(3S), ungetc(3S)

      NOTICES
            If the integer value returned by all of the above routines
            except getw 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 implementation dependent.

            The macro version of getc evaluates a stream argument more
            than once and may treat side effects incorrectly.  In
            particular, getc(*f++) does not work sensibly.  Use fgetc
            instead.

            Because of possible differences in word length and byte
            ordering, files written using putw are implementation
            dependent, and may not be read using getw on a different
            processor.





                          Copyright 1994 Novell, Inc.               Page 2

       getc(3S)                                                    getc(3S)


             Functions exist for all the above-defined macros.  To get the
             function form, the macro name must be undefined (for example,
             #undef getc).













































                           Copyright 1994 Novell, Inc.               Page 3