Next: fgetws, Previous: fgets, Up: Stdio

### 4.13 `fgetwc`, `getwc`, `fgetwc_unlocked`, `getwc_unlocked`—get a wide character from a file or stream

Synopsis

         #include <stdio.h>
         #include <wchar.h>
         wint_t fgetwc(FILE *fp);

         #define _GNU_SOURCE
         #include <stdio.h>
         #include <wchar.h>
         wint_t fgetwc_unlocked(FILE *fp);

         #include <stdio.h>
         #include <wchar.h>
         wint_t _fgetwc_r(struct _reent *ptr, FILE *fp);

         #include <stdio.h>
         #include <wchar.h>
         wint_t _fgetwc_unlocked_r(struct _reent *ptr, FILE *fp);

         #include <stdio.h>
         #include <wchar.h>
         wint_t getwc(FILE *fp);

         #define _GNU_SOURCE
         #include <stdio.h>
         #include <wchar.h>
         wint_t getwc_unlocked(FILE *fp);

         #include <stdio.h>
         #include <wchar.h>
         wint_t _getwc_r(struct _reent *ptr, FILE *fp);

         #include <stdio.h>
         #include <wchar.h>
         wint_t _getwc_unlocked_r(struct _reent *ptr, FILE *fp);

Description
Use `fgetwc` to get the next wide character from the file or stream identified by fp. As a side effect, `fgetwc` advances the file's current position indicator.

`fgetwc_unlocked` is a non-thread-safe version of `fgetwc`. `fgetwc_unlocked` may only safely be used within a scope protected by flockfile() (or ftrylockfile()) and funlockfile(). This function may safely be used in a multi-threaded program if and only if they are called while the invoking thread owns the (FILE *) object, as is the case after a successful call to the flockfile() or ftrylockfile() functions. If threads are disabled, then `fgetwc_unlocked` is equivalent to `fgetwc`.

The `getwc` and `getwc_unlocked` functions or macros functions identically to `fgetwc` and `fgetwc_unlocked`. It may be implemented as a macro, and may evaluate its argument more than once. There is no reason ever to use it.

`_fgetwc_r`, `_getwc_r`, `_fgetwc_unlocked_r`, and `_getwc_unlocked_r` are simply reentrant versions of the above functions that are passed the additional reentrant structure pointer argument: ptr.

Returns
The next wide character cast to `wint_t`, unless there is no more data, or the host system reports a read error; in either of these situations, `fgetwc` and `getwc` return `WEOF`.

You can distinguish the two situations that cause an `EOF` result by using the `ferror` and `feof` functions.

Portability
`fgetwc` and `getwc` are required by C99 and POSIX.1-2001.

`fgetwc_unlocked` and `getwc_unlocked` are GNU extensions.