fgetws

Gets a string of characters from a stream and stores them in an array.

Library:LibC
Classification:ANSI
Service:Characters and Strings

Syntax

  #include <wchar.h> 
   
  wchar_t  *fgetws (
     wchar_t         *buf,
     int              n, 
     struct _iobuf   *fp);

Parameters

buf

(OUT) Points to the array into which the wide characters are to be stored.

n

(IN) Specifies the number of characters to read.

fp

(IN) Points to the file to read.

Return Values

If successful, returns buf. If the stream is at the end-of-file, returns a NULL pointer and sets the end-of-file indicator on the stream.

If a read error occurs, returns a NULL pointer, sets the end-of-file indicator on the stream, and sets errno to one of the following:

Decimal

Constant

Description

4

EBADF

The file descriptor is not valid for reading.

5

ENOMEM

Insufficient storage space is available.

24

EAGAIN

The O_NONBLOCK flag is set for the file descriptor, and the process cannot immediately perform the read operation.

25

ENXIO

A request was made to a nonexistent device, or the request was outside the capabilities of the device.

28

EIO

The process is orphaned and cannot write to the file.

63

EINTR

A signal interrupted the read operation.

81

EOVERFLOW

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

101

EILSEQ

A wide-character code does not correspond to a valid sequence.

Remarks

The fgetws function gets a string of characters from the file designated by fp, converts them to wide characters, and stores them in the array pointed to by buf. The fgetws function stops reading characters when end-of-file is reached, when a newline character is read, or when n-1 characters have been read, whichever comes first. The newline character is not discarded. A wide-character NULL code is placed immediately after the last character read into the array.

See Also