Gets a string from a stream.
Standard I/O Library (libc.a)
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.
| 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. |
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.
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. |