HP-UX Reference (11i v3 07/02) - 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 *__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 newline char-
acter 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 condition.
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 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.
[EILSEQ] The data obtained from the input stream do not form a valid wide-character string.
[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
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 447