NAME

fgetws(), fgetws_unlocked() − get a wide character string from a stream file

SYNOPSIS

#include <wchar.h>

wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);

wchar_t *fgetws_unlocked(wchar_t *ws, int n, FILE *stream);

Remarks:

fgetws() is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions.  It parallels the 8-bit character I/O function defined in gets(3S).

DESCRIPTION

fgetws() Reads characters from the stream, converts them into corresponding wide characters, and places them into the array pointed to by ws, until n − 1 characters are read, a new-line character is read and transferred to ws, or an end-of-file condition is encountered. The wide string is then terminated with a null wide character.

The definition for this functions and the type wchar_t are provided in the <wchar.h> header. 

fgetws_unlocked() is identical to fgetws() except it does not perform any internal locking of the stream for multi-thread applications.  fgetws_unlocked can be used by multi-thread applications which have already used flockfile() to acquire a mutual exclusion lock for the stream (see flockfile(3S)).

EXTERNAL INFLUENCES

Locale

The LC_CTYPE category determines how wide character conversions are done. 

International Code Set Support

Single- and multi-byte character code sets are supported. 

RETURN VALUE

Upon successful completion, fgetws() and fgetws_unlocked() return ws. If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, errno is set to indicate the error, and a null pointer is returned. 

ferror() and feof() can be used to distinguish between an error condition and an end-of-file condition. 

ERRORS

fgetws() and fgetws_unlocked() fail if data needs to be read into the stream’s buffer, and:

[EAGAIN] The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the read operation. 

[EBADF] The file descriptor underlying stream is not a valid file descriptor open for reading. 

[EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. 

[EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is orphaned. 

[EILSEQ] The data obtained from the input stream do not form a valid wide character string. 

Additional errno values can be set by the underlying read() function (see read(2)).

AUTHOR

fgetws() was developed by OSF and HP. 

SEE ALSO

ferror(3S), flockfile(3S), fopen(3S), fread(3S), getwc(3C), putws(3C), scanf(3S). 

STANDARDS COMPLIANCE

fgetws(): XPG4

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996