[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, 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 ( WString Number Stream)
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.

Related Information

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

Related standard I/O subroutines: fdopen (fopen, fopen64, freopen, freopen64 or fdopen Subroutine) subroutine, fgetc (getc, getchar, fgetc, or getw Subroutine) subroutine, fgets (gets or fgets Subroutine) subroutine, fopen (fopen, fopen64, freopen, freopen64 or fdopen Subroutine) subroutine, fprintf (printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf Subroutine) subroutine, fputc (putc, putchar, fputc, or putw Subroutine) subroutine, fputs (puts or fputs Subroutine) subroutine, fread (fread or fwrite Subroutine) subroutine, freopen (fopen, fopen64, freopen, freopen64 or fdopen Subroutine) subroutine, fscanf subroutine, fwrite (fread or fwrite Subroutine) subroutine, getc (getc, getchar, fgetc, or getw Subroutine) subroutine, getchar (getc, getchar, fgetc, or getw Subroutine) subroutine, gets (gets or fgets Subroutine) subroutine, printf (printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf Subroutine) subroutine, putc (putc, putchar, fputc, or putw Subroutine) subroutine, putchar (putc, putchar, fputc, or putw Subroutine) subroutine, puts (puts or fputs Subroutine) subroutine, putw (putc, putchar, fputc, or putw Subroutine) subroutine, scanf subroutine, sprintf (printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf Subroutine) subroutine, ungetc subroutine.

Understanding Wide Character Input/Output Subroutines and Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview in AIX 5L Version 5.2 National Language Support Guide and Reference.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]