getw(3C)




NAME

     fgetc, getc, getc_unlocked, getchar, getchar_unlocked,  getw
     - get a byte from a stream


SYNOPSIS

     #include <stdio.h>

     int fgetc(FILE *stream);

     int getc(FILE *stream);

     int getc_unlocked(FILE *stream);

     int getchar(void);

     int getchar_unlocked(void);

     int getw(FILE *stream);


DESCRIPTION

     The fgetc() function obtains the next byte (if  present)  as
     an  unsigned char converted to an int, from the input stream
     pointed to by stream, and advances the associated file posi-
     tion indicator for the stream (if defined).

     The fgetc() function may mark the st_atime field of the file
     associated  with  stream for update. The st_atime field will
     be marked for update by the first  successful  execution  of
     fgetc(),   fgets(3C),   fgetwc(3C),  fgetws(3C),  fread(3C),
     fscanf(3C), getc(), getchar(), gets(3C) or  scanf(3C)  using
     stream  that  returns  data  not supplied by a prior call to
     ungetc(3C) or ungetwc(3C).

     The getc() routine is  functionally  identical  to  fgetc(),
     except  that  it  is  implemented as a macro. It runs faster
     than fgetc(), but it takes up more space per invocation  and
     its name cannot be passed as an argument to a function call.

     The getchar() routine is equivalent to  getc(stdin).  It  is
     implemented as a macro.

     The  getc_unlocked()  and  getchar_unlocked()  routines  are
     variants  of getc() and getchar(), respectively, that do not
     lock the stream.   It  is  the  caller's  responsibility  to
     acquire  the  stream  lock before calling these routines and
     releasing  the  lock  afterwards;  see   flockfile(3C)   and
     stdio(3C). These routines are implemented as macros.

     The getw() function reads the next word from the stream. The
     size  of  a  word  is  the  size of an int and may vary from
     environment to environment.  The getw() function presumes no
     special alignment in the file.
     The getw() function may mark the st_atime field of the  file
     associated  with  stream for update. The st_atime field will
     be marked for update by the first  successful  execution  of
     fgetc(),  fgets(3C), fread(3C), getc(), getchar(), gets(3C),
     fscanf(3C) or scanf(3C) using stream that returns  data  not
     supplied by a prior call to ungetc(3C).


RETURN VALUES

     Upon     successful     completion,     fgetc(),     getc(),
     getc_unlocked(),  getchar(),  getchar_unlocked(), and getw()
     return the next byte 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 these  functions  return
     EOF.  If  a  read  error occurs, the error indicator for the
     stream is set, EOF is returned, and errno is set to indicate
     the error.


ERRORS

     The    fgetc(),    getc(),    getc_unlocked(),    getchar(),
     getchar_unlocked(),  and  getw() functions will fail if data
     needs to be read and:

     EAGAIN
           The O_NONBLOCK flag is set  for  the  file  descriptor
           underlying  stream and the process would be delayed in
           the fgetc() 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 no data was transferred.

     EIO   A physical I/O error has occurred, or the  process  is
           in  a background process group attempting to read from
           its controlling terminal, and either  the  process  is
           ignoring or blocking the SIGTTIN signal or the process
           group is orphaned. This error may  also  be  generated
           for implementation-dependent reasons.

     EOVERFLOW
           The file is a regular file and an attempt was made  to
           read  at  or beyond the offset maximum associated with
           the corresponding stream.

     The    fgetc(),    getc(),    getc_unlocked(),    getchar(),
     getchar_unlocked(), and getw() functions may fail if:

     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.


USAGE

     If  the  integer  value   returned   by   fgetc(),   getc(),
     getc_unlocked(),  getchar(),  getchar_unlocked(), and getw()
     is stored into a variable of type  char  and  then  compared
     against  the  integer constant EOF, the comparison may never
     succeed, because sign-extension of a variable of  type  char
     on widening to integer is implementation-dependent.

     The ferror(3C) or feof(3C) functions must be used to distin-
     guish  between  an error condition and an end-of-file condi-
     tion.

     Functions exist for the getc(), getc_unlocked(),  getchar(),
     and getchar_unlocked() macros. To get the function form, the
     macro name must be undefined (for example, #undef getc).

     When the macro forms are used,  getc()  and  getc_unlocked()
     evaluate  the stream argument more than once. In particular,
     getc(*f++); does not work sensibly.   The  fgetc()  function
     should  be  used instead when evaluating the stream argument
     has side effects.

     Because of possible differences in word length and byte ord-
     ering, files written using getw() are machine-dependent, and
     may not be read using getw() on a different processor.

     The getw() function is inherently byte  stream-oriented  and
     is  not tenable in the context of either multibyte character
     streams or wide-character streams.  Application  programmers
     are  recommended  to  use  one  of the character-based input
     functions instead.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below.            |
    |_____________________________|_____________________________|


SEE ALSO

     intro(3),  fclose(3C),  feof(3C),   fgets(3C),   fgetwc(3C),
     fgetws(3C), flockfile(3C), fopen(3C), fread(3C), fscanf(3C),
     gets(3C),  putc(3C),   scanf(3C),   stdio(3C),   ungetc(3C),
     ungetwc(3C), attributes(5)


NOTES

     The fgetc(), getc(), getchar(), and getw() routines are  MT-
     Safe in multithreaded applications.  The getc_unlocked() and
     getchar_unlocked()  routines  are  unsafe  in  multithreaded
     applications.


Man(1) output converted with man2html