function
<cwchar>

fgetwc

wint_t fgetwc (FILE * stream);
Get wide character from stream
Returns the wide character currently pointed by the internal position indicator of the specified stream. The internal position indicator is then advanced to the next wide character.

Because wide characters are represented by multibyte characters in external files, the function may involve reading several bytes from the file, which are interpreted as a single character as if mbrtowc was called with the stream's internal mbstate_t object.

If the sequence of bytes read cannot be interpreted as a valid multibyte character (or there were too few bytes available to compose a wide character), the function returns WEOF and sets EILSEQ as the value of errno.

If the stream is at the end-of-file when called, the function returns WEOF and sets the end-of-file indicator for the stream (feof).

If a read error occurs, the function returns WEOF and sets the error indicator for the stream (ferror).

fgetwc and getwc are equivalent, except that getwc may be implemented as a macro in some libraries.

This is the wide character equivalent of fgetc (<cstdio>).

Parameters

stream
Pointer to a FILE object that identifies an input stream.
The stream shall not have an orientation yet, or be wide-oriented (the first i/o operation on a stream determines whether it is byte- or wide- oriented, see fwide).

Return Value

On success, the character read is returned (promoted to a value of type wint_t).
The return type is wint_t to accommodate for the special value WEOF, which indicates failure:
If the sequence of bytes read cannot be interpreted as a valid wide character, the function returns WEOF and sets errno to EILSEQ.
If the position indicator was at the end-of-file, the function returns WEOF and sets the eof indicator (feof) of stream.
If a reading error happens, the function also returns WEOF, but sets its error indicator (ferror) instead.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/* fgetwc example */
#include <stdio.h>
#include <wchar.h>

int main ()
{
  FILE * pFile;
  wint_t wc;
  int n = 0;
  pFile=fopen ("myfile.txt","r");
  if (pFile!=NULL)
  {
    do {
      wc = fgetwc (pFile);
      if (wc == L'$') n++;
    } while (wc != WEOF);
    fclose (pFile);
    wprintf (L"The file contains %d dollar sign characters ($).\n",n);
  }
  return 0;
}

This program reads an existing file called myfile.txt character by character and uses the n variable to count how many dollar characters ($) does the file contain.

See also