NAME

fgetws − Gets a string from a stream

LIBRARY

Standard C Library (libc.so, libc.a)

SYNOPSIS

#include <wchar.h>

wchar_t ∗fgetws(
wchar_t ∗wcs,
int number,
FILE ∗stream);

Application developers may want to specify an #include statement for <stdio.h> before the one for <wchar.h> if programs are being developed for multiple platforms. The additional #include statement is not required on DIGITAL UNIX systems or by ISO or X/Open standards, but may be required on other vendors’ systems that conform to these standards. 

STANDARDS

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

fgetws:  XPG4, XPG4−UNIX

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. 

streamPoints to the FILE structure of an open file. 

numberSpecifies 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. 

       •[Digital]  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 flag 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. 

       •[XPG4−UNIX]  A physical I/O error occurred. 

RELATED INFORMATION

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)