NAME
fgetws, fgetws_l
— get a line of wide characters
from a stream
LIBRARY
library “libc”
SYNOPSIS
#include <stdio.h>
#include <wchar.h>
wchar_t *
fgetws(wchar_t
* restrict ws, int
n, FILE * restrict
fp);
#include
<xlocale.h>
wchar_t *
fgetws_l(wchar_t
* restrict ws, int
n, FILE * restrict
fp, locale_t
locale);
DESCRIPTION
Thefgetws()
and fgetws_l() functions read at most one less than
the number of characters specified by n from the given
fp and store them in the wide character string
ws. Reading stops when a newline character is found, at
end-of-file or error. The newline, if any, is retained. If any characters are
read and there is no error, a ‘\0’
character is appended to end the string.
The
fgetws_l()
function takes an explicit locale argument, whereas
the fgetws() function uses the current global or
per-thread locale.
RETURN VALUES
Upon successful completion, fgetws() and
fgetws_l() return ws. If
end-of-file occurs before any characters are read,
fgetws() and fgetws_l()
return NULL and the buffer contents remain
unchanged. If an error occurs, fgetws() and
fgetws_l() return NULL and
the buffer contents are indeterminate. The fgetws()
and fgetws_l() functions do not distinguish between
end-of-file and error, and callers must use
feof(3) and
ferror(3) to determine which occurred.
ERRORS
The fgetws() and
fgetws_l() functions will fail if:
- [
EBADF] - The given fp argument is not a readable stream.
- [
EILSEQ] - The data obtained from the input stream does not form a valid multibyte character.
The functions fgetws() and
fgetws_l() may also fail and set
errno for any of the errors specified for the routines
fflush(3),
fstat(2),
read(2), or
malloc(3).
SEE ALSO
STANDARDS
The fgetws() function conforms to
IEEE Std 1003.1-2001 (“POSIX.1”).