*** UNIX MANUAL PAGE BROWSER ***

getwc(3) Library Functions Manual getwc(3) NAME getwc, getwc_unlocked, fgetwc, getwchar - Get a wide character from an input stream LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <wchar.h> wint_t getwc( FILE *stream); wint_t getwc_unlocked( FILE *stream); wint_t fgetwc( FILE *stream); wint_t getwchar(void); For the fgetwc() and getwc() functions, 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 DIGITAL UNIX systems or by ISO or X/Open standards, but may be required on other vendors' systems that conform to these standards. STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: fgetwc(), getwc(), getwchar(): XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies an input stream from a file. DESCRIPTION The fgetwc() function gets the next character from the input stream specified by the stream parameter, converts it to a wide-character code, and advances the associated file position indicator for the stream. If an error occurs, the file position indicator is indetermi- nate. This function also marks the st_atime field of the file associ- ated with stream for update. The getwc() function performs the same function as fgetwc() but can be implemented as a macro on implementations that conform to X/Open stan- dards. The getwchar() function gets the next wide character from the standard input stream. This function is equivalent to getwc(stdin). The getwc_unlocked() function is functionally identical to the getwc() function, except that getwc_unlocked() may be safely used only within a scope that is protected by the flockfile() and funlockfile() functions used as a pair. The caller must ensure that the stream is locked be- fore these functions are used. On return from calls to the preceding functions, applications should use ferror() and feof() to distinguish between error and end-of-file conditions. NOTES Because getwc() can be implemented as a macro, applications should not use it with a stream argument that is an expression with side effects (for example, getwc(*f++)). The fgetwc() function is recommended over getwc() for reading characters from a stream associated with a file. If the value returned by the getwchar() function is stored into a vari- able of type wchar_t and then compared to the macro WEOF (defined as type wint_t in the wchar.h header file), the comparison may never suc- ceed. RETURN VALUES These functions return either the resultant wide-character code or, for error and end-of-file conditions, the constant WEOF (wide-character End-Of-File). ERRORS If any of the following conditions occur, the fgetwc(), getwc(), getwc_unlocked(), and getwchar(), functions set errno to the corre- sponding value: The O_NONBLOCK flag is set for the file descriptor un- derlying the stream parameter and the process would be delayed by the read operation. The file descriptor underlying the stream parameter is not a valid file descriptor open for reading. The data obtained from the input stream does not form a valid wide character in the current locale. The read operation was interrupted by a signal that was caught, and no data was transferred. One of the following errors oc- curred: The call is attempting to read from the process's controlling terminal and either the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. [XPG4-UNIX] A physical I/O error occurred. Insufficient memory is available for the operation. The device associated with stream either does not exist or cannot han- dle the request. RELATED INFORMATION Functions: fopen(3), fread(3), fgetws(3), getc(3), gets(3), putwc(3), scanf(3), wscanf(3) Standards: standards(5) delim off getwc(3)