HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

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 *ws, int n, FILE *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. 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 condi-
tion.
ERRORS
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.
[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)).
HP-UX 11i Version 2: September 2004 − 1 − Hewlett-Packard Company Section 3−−319