GETWS(3C) Standard C Library Functions GETWS(3C)
NAME
getws, fgetws - get a wide-character string from a stream
SYNOPSIS
#include <stdio.h>
include <widec.h>
wchar_t *getws(
wchar_t *ws);
#include <stdio.h>
include <wchar.h>
wchar_t *fgetws(
wchar_t *restrict ws,
int n,
FILE *restrict stream);
DESCRIPTION
The
getws() function reads a string of characters from the standard input
stream,
stdin, converts these characters to the corresponding wide-
character codes, and writes them to the array pointed to by
ws, until a
newline character is read, converted and transferred to
ws or an end-of-
file condition is encountered. The wide-character string,
ws, is then
terminated with a null wide-character code.
The
fgetws() function reads characters from the
stream, converts them to
the corresponding wide-character codes, and places them in the
wchar_t array pointed to by
ws until
n-1 characters are read, or until a newline
character is read, converted and transferred to
ws, or an end-of-file
condition is encountered. The wide-character string,
ws, is then
terminated with a null wide-character code.
If an error occurs, the resulting value of the file position indicator
for the stream is indeterminate.
The
fgetws() function may mark the
st_atime field of the file associated
with
stream for update. The
st_atime field will be marked for update by
the first successful execution of
fgetc(3C),
fgets(3C),
fgetwc(3C),
fgetws(),
fread(3C),
fscanf(3C),
getc(3C),
getchar(3C),
gets(3C), or
scanf(3C) using
stream that returns data not supplied by a prior call to
ungetc(3C) or
ungetwc(3C).
RETURN VALUES
Upon successful completion,
getws() and
fgetws() return
ws. If the
stream is at end-of-file, the end-of-file indicator for the stream is set
and
fgetws() returns a null pointer. For standard-conforming (see
standards(7)) applications, if the end-of-file indicator for the stream
is set,
fgetws() returns a null pointer whether or not the stream is at
end-of-file. If a read error occurs, the error indicator for the stream
is set and
fgetws() returns a null pointer and sets
errno to indicate the
error.
ERRORS
See
fgetwc(3C) for the conditions that will cause
fgetws() to fail.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------------+
|Interface Stability |
fgetws() is Standard. |
+--------------------+-----------------------+
|MT-Level | MT-Safe |
+--------------------+-----------------------+
SEE ALSO
ferror(3C),
fgetwc(3C),
fread(3C),
getwc(3C),
putws(3C),
scanf(3C),
ungetc(3C),
ungetwc(3C),
attributes(7),
standards(7) October 15, 2003
GETWS(3C)