ungetwc() — Push a wide character onto a stream

Standards

Standards / Extensions C or C++ Dependencies
XPG4
XPG4.2
Single UNIX Specification, Version 3 Language Environment®
 both  

Format

#include <wchar.h>

wint_t ungetwc(wint_t wc, FILE *stream);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

wint_t ungetwc_unlocked(wint_t wc, FILE *stream);

General description

Pushes the wide character specified by wc back onto the input stream pointed to by stream. The pushed-back wide 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(), fsetpos(), or rewind()) discards any pushed-back wide characters for the stream. The external storage corresponding to the stream is unchanged. There is always at least one wide character of push-back.

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

A successful call to the ungetwc() function clears the EOF indicator for the stream. The value of the file position indicator for the stream after reading or discarding all pushed-back wide characters is the same as it was before the wide characters were pushed back.

For a text stream, the file position indicator is backed up by one wide character. This affects ftell(), fflush(), fseek() using SEEK_CUR, and fgetpos(). The environment variable, _EDC_COMPAT can be used to cause a pushed-back wide char to be ignored by fflush(), fseek() with SEEK_CUR, and fgetpos(). For details, see z/OS XL C/C++ Programming Guide.

For a binary stream, the position indicator is unspecified until all characters are read or discarded, unless the last character is pushed back, in which case the file position indicator is backed up by one wide character. This affects ftell() and fseek() with SEEK_CUR, fgetpos(), and fflush(). The environment variable _EDC_COMPAT can be used to cause the pushed-back wide character to be ignored by fflush(), fgetpos(), and fseek().

ungetwc() is not supported for files opened with type=record or type=blocked.

ungetwc() has the same restriction as any read operation for a read immediately following a write, or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.

ungetwc_unlocked() is functionally equivalent to ungetwc() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

Returned value

If successful, ungetwc() returns the wide character pushed back after conversion.

If unsuccessful, ungetwc() returns WEOF.

Notes:
  1. For z/OS® XL C/C++ applications, only 1 wide character can be pushed back.
  2. The position on the stream after a successful ungetwc() is one wide character before the current position. See z/OS XL C/C++ Programming Guide for details on backing up a wide char.

Example

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

int main(void)
{
   FILE    *stream;
   wint_t   wc;
   unsigned int result = 0;
⋮
   while ((wc = fgetwc(stream)) != WEOF && iswdigit(wc))
      result = result * 10 + wc - L'0';

   if (wc != WEOF)
      ungetwc(wc, stream);
         /* Put the nondigit wide character back */
}

Related information