getws or fgetws Subroutine

Purpose

Gets a string from a stream.

Library

Standard I/O Library (libc.a)

Syntax

#include <stdio.h>

wchar_t *fgetws ( WString Number Stream)
wchar_t *WString;
int Number;
FILE *Stream;

wchar_t *getws (WString)
wchar_t *WString;

Description

The fgetws subroutine reads characters from the input stream, converts them to the corresponding wide character codes, and places them in the array pointed to by the WString parameter. The subroutine continues until either the number of characters specified by the Number parameter minus 1 are read or the subroutine encounters a new-line or end-of-file character. The fgetws subroutine terminates the wide character string specified by the WString parameter with a null wide character.

The getws subroutine reads wide characters from the input stream pointed to by the standard input stream (stdin) into the array pointed to by the WString parameter. The subroutine continues until it encounters a new-line or the end-of-file character, then it discards any new-line character and places a null wide character after the last character read into the array.

Parameters

Item Description
WString Points to a string to receive characters.
Stream Points to the FILE structure of an open file.
Number Specifies the maximum number of characters to read.

Return Values

If the getws or fgetws subroutine reaches the end of the file without reading any characters, it transfers no characters to the String parameter and returns a null pointer. If a read error occurs, the getws or fgetws subroutine returns a null pointer and sets the errno global variable to indicate the error.

Error Codes

If the getws or fgetws subroutine is unsuccessful because the stream is not buffered or data needs to be read into the stream's buffer, it returns one or more of the following error codes:

Item Description
EAGAIN Indicates that the O_NONBLOCK flag is set for the file descriptor underlying the Stream parameter, and the process is delayed in the fgetws subroutine.
EBADF Indicates that the file descriptor specifying the Stream parameter is not a read-access file.
EINTR Indicates that the read operation is 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 Indicates that insufficient storage space is available.
ENOMEM Indicates that insufficient storage space is available.
EILSEQ Indicates that the data read from the input stream does not form a valid character.