Standard C Library Functions                            getws(3C)



NAME
     getws, fgetws - get a wide-character string from a stream

SYNOPSIS
     #include 
     include 

     wchart *getws(wchart *ws);


     #include 
     include 

     wchart *fgetws(wchart *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 con-
     dition  is  encountered.  The  wide-character string, ws, is
     then terminated with a null wide-character code.


     The fgetws() function reads characters from the stream, con-
     verts  them  to the corresponding wide-character codes,  and
     places them in the wchart 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 ter-
     minated 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  statime  field  of  the
     file  associated  with stream for update. The statime 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(5)) applications, if



SunOS 5.11          Last change: 15 Oct 2003                    1






Standard C Library Functions                            getws(3C)



     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.

ERORS
     See fgetwc(3C) for the conditions that will  cause  fgetws()
     to fail.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE 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(5),   stan-
     dards(5)


























SunOS 5.11          Last change: 15 Oct 2003                    2