ungetwc() — Push Wide Character onto Input Stream
Format
#include <wchar.h>
#include <stdio.h>
wint_t ungetwc(wint_t wc, FILE *stream);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE category of the current locale. The behavior might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Integrated File System Interface
This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.
Wide Character Function
See Wide Characters for more information.
Description
The ungetwc()
function
pushes the wide character wc back onto the input 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 (on the 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 is
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. However, only one consecutive wide character is guaranteed
to be pushed back onto the input stream if you call ungetwc()
consecutively.
For a text stream, the file position indicator is backed
up by one wide character. This affects the ftell()
, fflush()
, fseek()
(with
SEEK_CUR), and fgetpos()
function.
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 the ftell()
, fseek()
(with
SEEK_CUR), fgetpos()
,
and fflush()
function.
Return Value
The ungetwc()
function
returns the wide character pushed back after conversion, or WEOF if
the operation fails.
Example
#include <wchar.h>
#include <wctype.h>
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
FILE *stream;
wint_t wc;
wint_t wc2;
unsigned int result = 0;
if (NULL == (stream = fopen("ungetwc.dat", "r+"))) {
printf("Unable to open file.\n");
exit(EXIT_FAILURE);
}
while (WEOF != (wc = fgetwc(stream)) && iswdigit(wc))
result = result * 10 + wc - L'0';
if (WEOF != wc)
ungetwc(wc, stream); /* Push the nondigit wide character back */
/* get the pushed back character */
if (WEOF != (wc2 = fgetwc(stream))) {
if (wc != wc2) {
printf("Subsequent fgetwc does not get the pushed back character.\n");
exit(EXIT_FAILURE);
}
printf("The digits read are '%i'\n"
"The character being pushed back is '%lc'", result, wc2);
}
return 0;
/****************************************************************************
Assuming the file ungetwc.dat contains:
12345ABCDE67890XYZ
The output should be similar to :
The digits read are '12345'
The character being pushed back is 'A'
****************************************************************************/
}