ungetwc(3C)

NAME

     ungetwc - push wide-character code back into input stream

SYNOPSIS

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

     wint_t ungetwc(wint_t wc, FILE *stream);

DESCRIPTION

     The ungetwc() function pushes the character corresponding to
     the  wide character code specified by wc back onto the input
     stream pointed to by stream. The pushed-back characters will
     be  returned  by  subsequent  reads  on  that  stream in the
     reverse order of their  pushing.  A  successful  intervening
     call  (with  the  stream  pointed  to  by stream) to a file-
     positioning function ( fseek(3C), fsetpos(3C) or rewind(3C))
     discards  any  pushed-back  characters  for  the stream. The
     external storage corresponding to the stream is unchanged.

     One character of push-back is guaranteed.  If  ungetwc()  is
     called  too  many times on the same stream without an inter-
     vening read or file-positioning operation  on  that  stream,
     the operation may fail.

     If the value of wc equals that of the macro WEOF, the opera-
     tion fails and the input stream is unchanged.

     A successful call to ungetwc() clears the end-of-file  indi-
     cator for the stream. The value of the file-position indica-
     tor for the stream after reading or discarding  all  pushed-
     back  characters will be the same as it was before the char-
     acters were pushed  back.  The  file-position  indicator  is
     decremented  (by  one  or  more)  by each successful call to
     ungetwc(); if its value was 0 before a call,  its  value  is
     indeterminate after the call.

RETURN VALUES

     Upon successful  completion,  ungetwc()  returns  the  wide-
     character  code  corresponding to the pushed-back character.
     Otherwise it returns WEOF.

ERRORS

     The ungetwc() function may fail if:

     EILSEQ
           An invalid character sequence is detected, or a  wide-
           character  code does not correspond to a valid charac-
           ter.

ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO

     read(2),  fseek(3C),  fsetpos(3C),  rewind(3C),  setbuf(3C),
     attributes(5)