Index for Section 3

Alphabetical listing for G

Bottom of page

getc(3)
NAME
  getc, fgetc, getc_unlocked, getchar, getchar_unlocked, getw - Get a byte or
  word from an input stream

SYNOPSIS
  #include <stdio.h>

  int getc(
	  FILE *stream );

  int fgetc(
	  FILE *stream );

  int getc_unlocked(
	  FILE *stream );

  int getchar(
	  void );

  int getchar_unlocked(
	  void );

  int getw(
	  FILE *stream );

LIBRARY
  Standard C Library (libc)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  fgetc(), getc_unlocked, getc(), getchar(), getchar_unlocked, getw(): XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  stream
      Points to the file structure of an open file.

DESCRIPTION
  The getc() function returns the next byte from the input specified by the
  stream parameter and moves the file pointer, if defined, ahead one byte in
  stream. The getc() function may be a macro (depending on compile-time
  definitions).	 See the NOTES section for more information.

  The fgetc() function performs the same function as getc().

  The getchar() function returns the next byte from stdin, the standard input
  stream. Note that getchar() can also be a macro.

  [Tru64 UNIX]	The reentrant versions of these functions are all locked
  against multiple threads calling them simultaneously. This will incur an
  overhead to ensure integrity of the stream. The unlocked versions of these
  calls, getc_unlocked() and getchar_unlocked() may be used to avoid the
  overhead. The getc_unlocked() and getchar_unlocked() functions are
  functionally identical to the getc() and getchar() functions, except that
  getc_unlocked() and getchar_unlocked() may be safely used only within a
  scope that is protected by the flockfile() and funlockfile() functions used
  as a pair.  The caller must ensure that the stream is locked before these
  functions are used. The getc() and getchar() functions can also be macros.

  The getw() function reads the next word (int) from the stream. The size of
  a word is the size of an int, which may vary from one machine architecture
  to another. The getw() function returns the constant EOF at the end of the
  file or when an error occurs. Since EOF is a valid integer value, the
  feof() and ferror() functions can be used to check the success of getw().
  The getw() function assumes no special alignment in the file.

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

NOTES
  The getc() and getchar() functions may be macros (depending on the
  compile-time definitions used in the source).	 Consequently, you cannot use
  these interfaces where a function is necessary; for example, a subroutine
  pointer cannot point to one of these interfaces.  In addition, 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 one, use the fgetc() function instead.

RETURN VALUES
  Upon successful completion, these functions and macros return the next byte
  or word from the input stream. If the stream is at end-of-file, the end-
  of-file indicator for the stream is set and the integer constant EOF is
  returned. If a read error occurs, the error indicator for the stream is
  set, EOF is returned, and errno is set to indicate the error.

  Because the EOF return is used to signal both a successful completion and
  an error (accompanied by errno), it is incumbent on the user to clear any
  pre-existing errno values before invoking these functions.

ERRORS
  The fgetc(), getc(), getc_unlocked(), getchar(), getchar_unlocked(), and
  getw() functions set errno to the specified value for the following
  conditions:

  [EAGAIN]
      The O_NONBLOCK option is set for the underlying stream and the process
      would be delayed by the read operation.

  [EBADF]
      The file descriptor underlying the stream is not a valid file
      descriptor or is not open for reading.

  [EINTR]
      The read operation was interrupted by a signal which was caught and no
      data was transferred.

  [EIO]
      The call is attempting to read from the process's controlling terminal
      and either the process is ignoring or blocking the SIGTTIN signal or
      the process group is orphaned.

      A physical I/O error has occurred. (This condition was defined for
      Issue 4 Version 2 and higher issues of the XSH specification.)

  [ENOMEM]
      Insufficient memory is available for the operation.

  [ENXIO]
      The device associated with stream does not exist.

SEE ALSO
  Functions: flockfile(3), funlockfile(3), gets(3), getwc(3), putc(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for G

Top of page