[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

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 (WStringNumberStream)
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

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:

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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

Other wide character I/O subroutines: fgetwc subroutine, fputwc subroutine, fputws subroutine, getwc subroutine, getwchar subroutine, putwc subroutine, putwchar subroutine, putws subroutine, ungetwc subroutine.

Related standard I/O subroutines: fdopen subroutine, fgetc subroutine, fgets subroutine, fopen subroutine, fprintf subroutine, fputc subroutine, fputs subroutine, fread subroutine, freopen subroutine, fscanf subroutine, fwrite subroutine, getc subroutine, getchar subroutine, gets subroutine, printf subroutine, putc subroutine, putchar subroutine, puts subroutine, putw subroutine, scanf subroutine, sprintf subroutine, ungetc subroutine.

National Language Support Overview for Programming, Understanding Wide Character Input/Output Subroutines, Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]