man/man3/ungetwc.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH ungetwc 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 ungetwc \- push back a wide character onto a FILE stream
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .P
  22 .BI "wint_t ungetwc(wint_t " wc ", FILE *" stream );
  23 .fi
  24 .SH DESCRIPTION
  25 The
  26 .BR ungetwc ()
  27 function is the wide-character equivalent of the
  28 .BR ungetc (3)
  29 function.
  30 It pushes back a wide character onto
  31 .I stream
  32 and returns it.
  33 .P
  34 If
  35 .I wc
  36 is
  37 .BR WEOF ,
  38 it returns
  39 .BR WEOF .
  40 If
  41 .I wc
  42 is an invalid wide character,
  43 it sets
  44 .I errno
  45 to
  46 .B EILSEQ
  47 and returns
  48 .BR WEOF .
  49 .P
  50 If
  51 .I wc
  52 is a valid wide character, it is pushed back onto the stream
  53 and thus becomes available for future wide-character read operations.
  54 The file-position indicator is decremented by one or more.
  55 The end-of-file
  56 indicator is cleared.
  57 The backing storage of the file is not affected.
  58 .P
  59 Note:
  60 .I wc
  61 need not be the last wide-character read from the stream;
  62 it can be any other valid wide character.
  63 .P
  64 If the implementation supports multiple push-back operations in a row, the
  65 pushed-back wide characters will be read in reverse order; however, only one
  66 level of push-back is guaranteed.
  67 .SH RETURN VALUE
  68 The
  69 .BR ungetwc ()
  70 function returns
  71 .I wc
  72 when successful, or
  73 .B WEOF
  74 upon
  75 failure.
  76 .SH ATTRIBUTES
  77 For an explanation of the terms used in this section, see
  78 .BR attributes (7).
  79 .TS
  80 allbox;
  81 lbx lb lb
  82 l l l.
  83 Interface       Attribute       Value
  84 T{
  85 .na
  86 .nh
  87 .BR ungetwc ()
  88 T}      Thread safety   MT-Safe
  89 .TE
  90 .SH STANDARDS
  91 C11, POSIX.1-2008.
  92 .SH HISTORY
  93 POSIX.1-2001, C99.
  94 .SH NOTES
  95 The behavior of
  96 .BR ungetwc ()
  97 depends on the
  98 .B LC_CTYPE
  99 category of the
 100 current locale.
 101 .SH SEE ALSO
 102 .BR fgetwc (3)