HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)
f
fgetws(3C) fgetws(3C)
NAME
fgetws() - 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
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 condi-
tion.
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 sig-
nal 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)).
Section 3−−262 Hewlett-Packard Company − 1 − HP-UX 11i Version 1: September 2005