Guardian Native C Library Calls Reference Manual (G06.28+, H06.04+)

Guardian Native C Library Calls (g - i) getws(3)
NAME
getws - Gets a wide character string from the standard input stream
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
H-series OSS processes: /G/system/zdllnnn/zcrtldll
SYNOPSIS
#include <wchar.h>
wchar_t *getws(
wchar_t *string);
PARAMETERS
wstring Points to a string to receive characters.
DESCRIPTION
The getws() function reads characters from the standard input stream, stdin, converts them into
the corresponding wide character codes, and stores them into the wchar_t array pointed by by
the wstring parameter. The getws() function reads characters until it reads a newline character
or encounters the end of file. It discards the newline character and writes a null wide character
immediately after the last character stored in the wstring array.
This function parallels the gets() function.
CAUTIONS
The getws() function does not check the input for a maximum size. Consequently, if more char-
acters are entered than will fit in the space allocated for the wstring parameter, getws() will write
beyond the end of the allocated space, producing indeterminate results. To avoid this condition,
you should use fgetws( ) instead of getws().
RETURN VALUE
If the end of the file is encountered and no characters were read, no characters are transferred to
the wstring parameter and a null pointer is returned. If a read error occurs or the function cannot
convert the character to a wide character code, a NULL pointer is returned. Otherwise, wstring is
returned.
ERRORS
If any of the following conditions occur, the getws() function fails and sets errno to the
corresponding value.
[EILSEQ] The data obtained from stdin did not contain valid characters in the current
locale.
RELATED INFORMATION
Functions: clearerr(3), feof(3), ferror(3), fgetws(3), fileno(3), fopen(3), fread(3), getc(3),
gets(3), getwc(3), mbtowc(3), puts(3), putws(3), scanf(3).
527192-005 Hewlett-Packard Company 3−45