Index for Section 3

Alphabetical listing for U

Bottom of page

ungetc(3)
NAME
  ungetc, ungetwc - Push a byte or wide-character code back into the input
  stream

SYNOPSIS
  #include <stdio.h>

  int ungetc(
	  int c,
	  FILE *stream );

  #include <wchar.h>

  wint_t ungetwc(
	  wint_t wchar,
	  FILE *stream );

  For the ungetwc() function, application developers may want to specify an
  #include statement for <stdio.h> before the one for <wchar.h> if programs
  are being developed for multiple platforms. The additional #include
  statement is not required on Tru64 UNIX systems or by ISO or X/Open
  standards, but may be required on other vendors' systems that conform to
  these standards.

LIBRARY
  Standard C Library (libc)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  ungetc(), ungetwc():	ISO C, XPG4, XPG4-UNIX

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  c   Specifies a byte to be inserted into the input stream.

  stream
      Specifies the input stream.

  wchar
      Specifies a wide-character code.

DESCRIPTION
  The ungetc() function converts the byte specified by the c parameter into
  an unsigned char and inserts it into the buffer associated with the input
  stream specified by the stream parameter.  This causes the next call to the
  getc() function to return c.

  If the c parameter has a value equal to EOF, the ungetc() function does not
  place anything in the buffer and the input stream is unchanged.

  The ungetwc() function inserts the wide character specified by wchar into
  the buffer associated with the input stream. The wide character may consist
  of one or more bytes. This causes the next call to the getwc() function to
  return the value of the wchar parameter.

  If the ungetwc() wchar parameter is WEOF, the ungetwc() function does not
  place anything in the buffer and the input stream is unchanged.

  A call to one of the file-positioning functions (fseek(), fsetpos(), or
  rewind()), if it uses the same stream and intervenes between a call to
  ungetc() or ungetwc() and getc() or getwc(), discards any pushed back bytes
  for the stream. The value of the file-position indicator after reading or
  discarding pushed-back bytes will be the same as it was before the bytes
  were pushed back.

  A successful call to ungetc() or ungetwc() clears the end-of-file indicator
  and decrements the file-position indicator for the stream. If the value of
  the file-position indicator is zero before the call, the value is
  indeterminate after the call. These functions do not have any effect on the
  external storage corresponding to the stream.

  One character of push back is guaranteed (this corresponds to one byte for
  ungetc()) and one or more bytes for ungetwc()); however, if one of these
  functions is called too many times on the same stream without an
  intervening read or file-positioning operation on that stream, industry
  standards specify that the functions may fail. (Applications do not
  encounter this failure on Tru64 UNIX systems. However, results are
  unpredictable if applications intermix calls to ungetc() and ungetwc() on
  the same stream.)

RETURN VALUES
  On successful insertion of the converted byte into the stream, the ungetc()
  function returns the value of c.  Otherwise, the function returns EOF.

  On successful insertion of the converted wide character into the stream,
  the ungetwc() function returns the value of wchar. Otherwise, the function
  returns WEOF.

ERRORS
  If the following condition occurs, the ungetwc() function sets errno to the
  corresponding value:

  [EILSEQ]
      An invalid byte sequence is detected, or a wide-character code does not
      correspond to a valid single-byte or multibyte character in the current
      locale.

SEE ALSO
  Functions: fseek(3), getc(3), getwc(3), setbuf(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for U

Top of page