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
fgetws()
is a thread-safe interface. It is not async-cancel-safe.
A cancellation point may occur when a thread is executing
fgetws().
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 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)).
WARNINGS
fgetws_unlocked()
is an obsolescent interface supported only for compatibility with
existing DCE applications. New multithreaded applications should
use
fgetws().
AUTHOR
fgetws()
was developed by OSF and HP.
STANDARDS COMPLIANCE
fgetws(): XPG4
Printable version
