man3p/ungetwc.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "UNGETWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" ungetwc
   4 .SH NAME
   5 ungetwc \- push wide-character code back into the input stream
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <stdio.h>
   9 .br
  10 #include <wchar.h>
  11 .br
  12 .sp
  13 wint_t ungetwc(wint_t\fP \fIwc\fP\fB, FILE *\fP\fIstream\fP\fB);
  14 .br
  15 \fP
  16 .SH DESCRIPTION
  17 .LP
  18 The \fIungetwc\fP() function shall push the character corresponding
  19 to the wide-character code specified by \fIwc\fP back onto
  20 the input stream pointed to by \fIstream\fP. The pushed-back characters
  21 shall be returned by subsequent reads on that stream in
  22 the reverse order of their pushing. A successful intervening call
  23 (with the stream pointed to by \fIstream\fP) to a
  24 file-positioning function ( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP())
  25 discards any
  26 pushed-back characters for the stream. The external storage corresponding
  27 to the stream is unchanged.
  28 .LP
  29 At least one character of push-back shall be provided. If \fIungetwc\fP()
  30 is called too many times on the same stream without
  31 an intervening read or file-positioning operation on that stream,
  32 the operation may fail.
  33 .LP
  34 If the value of \fIwc\fP equals that of the macro WEOF, the operation
  35 shall fail and the input stream shall be left
  36 unchanged.
  37 .LP
  38 A successful call to \fIungetwc\fP() shall clear the end-of-file indicator
  39 for the stream. The value of the file-position
  40 indicator for the stream after reading or discarding all pushed-back
  41 characters shall be the same as it was before the characters
  42 were pushed back. The file-position indicator is decremented (by one
  43 or more) by each successful call to \fIungetwc\fP(); if its
  44 value was 0 before a call, its value is unspecified after the call.
  45 .SH RETURN VALUE
  46 .LP
  47 Upon successful completion, \fIungetwc\fP() shall return the wide-character
  48 code corresponding to the pushed-back character.
  49 Otherwise, it shall return WEOF.
  50 .SH ERRORS
  51 .LP
  52 The \fIungetwc\fP() function may fail if:
  53 .TP 7
  54 .B EILSEQ
  55 An
  56 invalid character sequence is detected, or a wide-character code does
  57 not correspond to a valid character.
  58 .sp
  59 .LP
  60 \fIThe following sections are informative.\fP
  61 .SH EXAMPLES
  62 .LP
  63 None.
  64 .SH APPLICATION USAGE
  65 .LP
  66 None.
  67 .SH RATIONALE
  68 .LP
  69 None.
  70 .SH FUTURE DIRECTIONS
  71 .LP
  72 None.
  73 .SH SEE ALSO
  74 .LP
  75 \fIfseek\fP() , \fIfsetpos\fP() , \fIread\fP() ,
  76 \fIrewind\fP() , \fIsetbuf\fP() , the Base Definitions volume of
  77 IEEE\ Std\ 1003.1-2001, \fI<stdio.h>\fP, \fI<wchar.h>\fP
  78 .SH COPYRIGHT
  79 Portions of this text are reprinted and reproduced in electronic form
  80 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  81 -- Portable Operating System Interface (POSIX), The Open Group Base
  82 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  83 Electrical and Electronics Engineers, Inc and The Open Group. In the
  84 event of any discrepancy between this version and the original IEEE and
  85 The Open Group Standard, the original IEEE and The Open Group Standard
  86 is the referee document. The original Standard can be obtained online at
  87 http://www.opengroup.org/unix/online.html .