fgetws.3c (2010 09)

f
fgetws(3C) fgetws(3C)
NAME
fgetws(), fgetws_unlocked() - get a wide-character string from a stream file
SYNOPSIS
#include <stdio.h>
#include <wchar.h>
wchar_t *fgetws(wchar_t *__restrict ws, int n, FILE *__restrict stream);
Obsolescent Interface
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.
Obsolescent Interface
fgetws_unlocked()
get a wide-character string from a stream file.
APPLICATION USAGE
After
fgetws() is applied to a stream, the stream becomes wide-oriented (see orientation (5)).
EXTERNAL INFLUENCES
Environment Variables
LC_CTYPE determines how wide character conversions are done.
International Code Set Support
Single- and multibyte 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.
When the file corresponding to the open stream gets extended after the end-of-file is reached, all subse-
quent calls to these functions will succeed and the end-of-file indicator will remain set. However, in the
UNIX2003 standards environment (see standards (5)), these functions will fail, and they will return a null
pointer; the end-of-file indicator will still remain set.
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() or feof() can be used to distinguish between an error condition and an end-of-file condi-
tion.
ERRORS
If
fgetws() or fgetws_unlocked() fails if data needs to be read into the stream ’s buffer and
another error occurs, errno is set to one of the following:
[EAGAIN] The
O_NONBLOCK flag is set for the file descriptor underlying stream and the pro-
cess 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.
[EILSEQ] The data obtained from the input stream do not form a valid wide-character string.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1