trusty (3) fgetwc.3posix.gz

NAME

       fgetwc - get a wide-character code from a stream

SYNOPSIS

       #include <stdio.h>
       #include <wchar.h>

       wint_t fgetwc(FILE *stream);

DESCRIPTION

       The  fgetwc()  function  shall obtain the next character (if present) from the input stream pointed to by
       stream, convert that to the corresponding wide-character code, and advance the associated  file  position
       indicator for the stream (if defined).

       If an error occurs, the resulting value of the file position indicator for the stream is unspecified.

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

RETURN VALUE

       Upon successful completion, the fgetwc() function shall return the wide-character code of  the  character
       read  from the input stream pointed to by stream converted to a type wint_t.  If the stream is at end-of-
       file, the end-of-file indicator for the stream shall be set and fgetwc() shall return  WEOF.  If  a  read
       error  occurs,  the error indicator for the stream shall be set, fgetwc() shall return WEOF,    and shall
       set errno to indicate the error.  If an encoding error occurs, the error indicator for the  stream  shall
       be set, fgetwc() shall return WEOF, and shall set errno to indicate the error.

ERRORS

       The fgetwc() function shall 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 fgetwc() operation.

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

       EILSEQ The data obtained from the input stream does not form a valid character.

       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-
              defined 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 fgetwc() function may fail if:

       ENOMEM Insufficient storage space is available.

       ENXIO  A request was made of a nonexistent device, or the request was outside  the  capabilities  of  the
              device.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  ferror()  or  feof() functions must be used to distinguish between an error condition and an end-of-
       file condition.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       feof() , ferror() , fopen() , the Base Definitions volume of IEEE Std 1003.1-2001, <stdio.h>, <wchar.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .