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 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 subsequent 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 signal or the process group of the process is orphaned.

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 CONFORMANCE

fgetws(): XPG4

fgetws(3C)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Obsolescent Interface

Remarks

DESCRIPTION

Obsolescent Interface

APPLICATION USAGE

EXTERNAL INFLUENCES

Environment Variables

International Code Set Support

RETURN VALUE

ERRORS

WARNINGS

AUTHOR

SEE ALSO

STANDARDS CONFORMANCE