cursgetwstr(3X) cursgetwstr(3X)

NAME
       ggeettwwssttrr, ggeettnnwwssttrr, wwggeettwwssttrr, wwggeettnnwwssttrr, mmvvggeettwwssttrr, mmvvggeettnnwwssttrr,
       mmvvwwggeettwwssttrr, mmvvwwggeettnnwwssttrr - get an array of wide characters from a
       curses terminal keyboard

SYNOPSIS
       ##iinncclluuddee <>

       iinntt ggeettwwssttrr((wwiinntttt **wstr));;
       iinntt ggeettnnwwssttrr((wwiinntttt **wstr,, iinntt n));;
       iinntt wwggeettwwssttrr((WWIINNDDOOWW **win,, wwiinntttt **wstr));;
       iinntt wwggeettnnwwssttrr((WWIINNDDOOWW **win,, wwiinntttt **wstr,, iinntt n));;
       iinntt mmvvggeettwwssttrr((iinntt y,, iinntt x,, wwiinntttt **wstr));;
       iinntt mmvvggeettnnwwssttrr((iinntt y,, iinntt x,, wwiinntttt **wstr,, iinntt n));;
       iinntt mmvvwwggeettwwssttrr((WWIINNDDOOWW **win,, iinntt y,, iinntt x,, wwiinntttt **wstr));;
       iinntt mmvvwwggeettnnwwssttrr((WWIINNDDOOWW **win,, iinntt y,, iinntt x,, wwiinntttt **wstr,, iinntt n));;

DESCRIPTION
       The  effect  of ggeettwwssttrr is as though a series of calls to ggeettwwcchh were
       made, until a newline, other end-of-line, or end-of-file  condition  is
       processed.  An end-of-file condition is represented by WWEEOOFF, as defined
       in <>.  The newline and end-of-line conditions  are  represented
       by  the  \\nn  wwcchhaarrtt value.  In all instances, the end of the string is
       terminated by a null wwcchhaarrtt.  The routine places resulting  values  in
       the area pointed to by wstr.

       The  user's  erase and kill characters are interpreted.  If keypad mode
       is on for the window, KKEEYYLLEEFFTT and KKEEYYBBAACCKKSSPPAACCEE  are  both  considered
       equivalent to the user's kill character.

       Characters  input  are  echoed  only  if eecchhoo is currently on.  In that
       case, backspace is echoed as deletion of the previous character  (typi-
       cally a left motion).

       The effect of wwggeettwwssttrr is as though a series of calls to wwggeettwwcchh were
       made.

       The effect of mmvvggeettwwssttrr is as though a call to mmoovvee and then a  series
       of calls to ggeettwwcchh were made.

       The  effect  of mmvvwwggeettwwssttrr is as though a call to wwmmoovvee and then a se-
       ries of calls to wwggeettwwcchh were made.

       The ggeettnnwwssttrr, mmvvggeettnnwwssttrr, mmvvwwggeettnnwwssttrr, and wwggeettnnwwssttrr functions  are
       identical to the ggeettwwssttrr, mmvvggeettwwssttrr, mmvvwwggeettwwssttrr, and wwggeettwwssttrr func-
       tions, respectively, except that the **nn** versions read at most n char-
       acters, letting the application prevent overflow of the input buffer.

NNOOTTEESS
       Using  ggeettwwssttrr,  mmvvggeettwwssttrr,  mmvvwwggeettwwssttrr, or wwggeettwwssttrr to read a line
       that overflows the array pointed to by wwssttrr causes  undefined  results.
       The use of ggeettnnwwssttrr, mmvvggeettnnwwssttrr, mmvvwwggeettnnwwssttrr, or wwggeettnnwwssttrr, respec-
       tively, is recommended.

       These functions cannot return KKEEYY values because there is  no  way  to
       distinguish a KKEEYY value from a valid wwcchhaarrtt value.

       All of these routines except wwggeettnnwwssttrr may be macros.

RETURN VALUES
       All  of  these  functions return OOKK upon successful completion.  Other-
       wise, they return EERRRR.

       Functions using a window parameter return an error if it is null.

              wwggeettnnwwssttrr
                   returns an error if the associated call to wwggeettwwcchh failed.

PPOORRTTAABBIILLIITTYY
       These functions are described in The Single Unix Specification, Version
       2.  No error conditions are defined.  This implementation  returns  ERR
       if  the window pointer is null, or if the lower-level wwggeettwwcchh call re-
       turns an ERR.  In the latter case, an ERR return without other data  is
       treated  as an end-of-file condition, and the returned array contains a
       WWEEOOFF followed by a null wwcchhaarrtt.

       X/Open curses documents these functions to pass an  array  of  wwcchhaarrtt,
       but all of the vendors implement this using wwiinntttt.

SEE ALSO
       Functions: ccuurrsseess(3X), ccuurrssggeettwwcchh(3X), ccuurrssggeettssttrr(3X).



                                                             cursgetwstr(3X)