'\" te
.\" Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
.TH getws 3C "15 Oct 2003" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
getws, fgetws \- get a wide-character string from a stream
.SH SYNOPSIS
.LP
.nf
#include <stdio.h> 
include <widec.h> 

\fBwchar_t *\fR\fBgetws\fR(\fBwchar_t *\fR\fIws\fR);
.fi

.LP
.nf
#include <stdio.h> 
include <wchar.h> 

\fBwchar_t *\fR\fBfgetws\fR(\fBwchar_t *restrict\fR \fIws\fR, \fBint\fR \fIn\fR, \fBFILE *restrict\fR \fIstream\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetws()\fR function reads a string of characters from the standard input stream, \fBstdin\fR, converts these characters to the corresponding wide-character codes, and writes them to the array pointed to by \fIws\fR, until a newline character is read, converted and transferred to \fIws\fR or an end-of-file condition is encountered. The wide-character string, \fIws\fR, is then terminated with a null wide-character code.
.sp
.LP
The \fBfgetws()\fR function reads characters from the \fIstream\fR, converts them to the corresponding wide-character codes,  and places them in the \fBwchar_t\fR array pointed to by \fIws\fR until \fIn\fR\(mi1 characters are read, or until a newline character is read, converted and transferred to \fIws\fR, or an end-of-file condition is encountered. The wide-character string, \fIws\fR, is then terminated with a null wide-character code.
.sp
.LP
If an error occurs, the resulting value of the file position indicator for the stream is indeterminate.
.sp
.LP
The \fBfgetws()\fR function may mark the \fBst_atime\fR field of the file associated with \fIstream\fR for update. The \fBst_atime\fR field will be marked for update by the first successful execution of \fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfgetwc\fR(3C), \fBfgetws()\fR, \fBfread\fR(3C), \fBfscanf\fR(3C), \fBgetc\fR(3C), \fBgetchar\fR(3C), \fBgets\fR(3C), or \fBscanf\fR(3C) using \fIstream\fR that returns data not supplied by a prior call to \fBungetc\fR(3C) or \fBungetwc\fR(3C).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBgetws()\fR and \fBfgetws()\fR return \fIws\fR. If the stream is at end-of-file, the end-of-file indicator for the stream is set and \fBfgetws()\fR returns a null pointer. For standard-conforming (see \fBstandards\fR(5)) applications, if the end-of-file indicator for the stream is set, \fBfgetws()\fR 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 \fBfgetws()\fR returns a null pointer and sets \fBerrno\fR to indicate the error. 
.SH ERRORS
.sp
.LP
See \fBfgetwc\fR(3C) for the conditions that will cause \fBfgetws()\fR to fail.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface Stability\fBfgetws()\fR is Standard.
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBferror\fR(3C), \fBfgetwc\fR(3C), \fBfread\fR(3C), \fBgetwc\fR(3C), \fBputws\fR(3C), \fBscanf\fR(3C), \fBungetc\fR(3C), \fBungetwc\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)