NAME

fgetws − Get a string from a stream

SYNOPSIS

#include <stdio.h>
#include <wchar.h>
wchar_t ∗fgetws(
        wchar_t ∗wcs,
        int number,
        FILE ∗stream );

LIBRARY

Standard C Library (libc)

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

fgetws: XSH5.0

Refer to the standards(5) reference page for more information about industry standards and associated tags. 

PARAMETERS

wcsPoints to a buffer where output wide characters are stored. 

stream
Points to the FILE structure of an open file. 

number
Specifies an upper bound (number−1) on the number of characters to read. 

DESCRIPTION

The fgetws() function reads characters from stream, converts them into the corresponding wide characters, and stores the result in the wchar_t array pointed to by the wcs parameter. The function reads until number−1 characters have been read, it has read and stored in the buffer the \n (newline) character, or it has encountered the end-of-file condition. The function then appends a null wide character to the result stored in wcs. 

The fgetws() function parallels the fgets() function. 

RETURN VALUES

On successful completion, the fgetws() function returns a pointer to wcs. Under the following conditions, the function returns a null pointer:

       •The function encounters the end of the file before any characters are read. In this case, fgetws() does not store any wide characters in wcs and sets the end-of-file indicator for the stream. 

       •A read error occurs. In this case, fgetws() sets both errno and the error indicator for stream. After a read error, the value of the file-position indicator for stream is indeterminate. 

       •[Tru64 UNIX]  The function could not convert the input character to a wide character. 

ERRORS

If any of the following conditions occur, the fgetws() sets errno to the corresponding value:

[EAGAIN]
The O_NONBLOCK option is set for the file descriptor underlying stream and the process would be delayed in the fgetws() call. 

[EBADF]
The file descriptor underlying stream is not a valid file descriptor that is open for reading. 

[EILSEQ]
The data obtained from stdin or the stream did not contain valid characters in the current locale. 

[EINTR]
The read operation was terminated by a signal, and no data was transferred.

[EIO]
One of the following conditions was encountered:

       •The process is in a background process group that is attempting to read from its controlling terminal and either the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. 

       •A physical I/O error occurred. This condition was defined starting with XSH Issue 4 Version 2. 

[EOVERFLOW]
The file is a regular file and an attempt was made to read at or beyond the offset maximum that is associated with the corresponding stream.

SEE ALSO

Functions: clearerr(3), feof(3), ferror(3), fileno(3), fopen(3), fputws(3), fread(3), getc(3), gets(3), getwc(3), mbtowc(3), puts(3), scanf(3), wscanf(3)

Standards: standards(5)