Ada95/html/man/curs_getstr.3x.html

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4        <STRONG>getstr</STRONG>,  <STRONG>wgetstr</STRONG>,  <STRONG>mvgetstr</STRONG>,  <STRONG>mvwgetstr</STRONG>, <STRONG>wgetnstr</STRONG> - accept
   5        character strings from <STRONG>curses</STRONG> terminal keyboard
   6
   7
   8 </PRE>
   9 <H2>SYNOPSIS</H2><PRE>
  10        <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
  11
  12        <STRONG>int</STRONG> <STRONG>getstr(char</STRONG> <STRONG>*str);</STRONG>
  13        <STRONG>int</STRONG> <STRONG>getnstr(char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>n);</STRONG>
  14        <STRONG>int</STRONG> <STRONG>wgetstr(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>char</STRONG> <STRONG>*str);</STRONG>
  15        <STRONG>int</STRONG> <STRONG>mvgetstr(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>char</STRONG> <STRONG>*str);</STRONG>
  16        <STRONG>int</STRONG> <STRONG>mvwgetstr(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>char</STRONG> <STRONG>*str);</STRONG>
  17        <STRONG>int</STRONG> <STRONG>mvgetnstr(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>n);</STRONG>
  18        <STRONG>int</STRONG> <STRONG>mvwgetnstr(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>n);</STRONG>
  19        <STRONG>int</STRONG> <STRONG>wgetnstr(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>n);</STRONG>
  20
  21
  22 </PRE>
  23 <H2>DESCRIPTION</H2><PRE>
  24        The function <STRONG>getstr</STRONG> is equivalent to a series of calls  to
  25        <STRONG>getch</STRONG>, until a newline or carriage return is received (the
  26        terminating character is  not  included  in  the  returned
  27        string).   The  resulting  value  is  placed  in  the area
  28        pointed to by the character pointer <EM>str</EM>.
  29
  30        <STRONG>wgetnstr</STRONG> reads at most <EM>n</EM>  characters,  thus  preventing  a
  31        possible  overflow  of  the  input buffer.  Any attempt to
  32        enter more characters (other than the terminating  newline
  33        or  carriage  return)  causes  a beep.  Function keys also
  34        cause a beep and are ignored.  The <STRONG>getnstr</STRONG> function  reads
  35        from the <EM>stdscr</EM> default window.
  36
  37        The  user's erase and kill characters are interpreted.  If
  38        keypad  mode  is  on  for   the   window,   <STRONG>KEY_LEFT</STRONG>   and
  39        <STRONG>KEY_BACKSPACE</STRONG> are both considered equivalent to the user's
  40        kill character.
  41
  42        Characters input are echoed only if <STRONG>echo</STRONG> is currently  on.
  43        In  that case, backspace is echoed as deletion of the pre-
  44        vious character (typically a left motion).
  45
  46
  47 </PRE>
  48 <H2>RETURN VALUE</H2><PRE>
  49        All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG>
  50        (SVr4  specifies  only  "an integer value other than <STRONG>ERR</STRONG>")
  51        upon successful completion.
  52
  53
  54 </PRE>
  55 <H2>NOTES</H2><PRE>
  56        Note that <STRONG>getstr</STRONG>, <STRONG>mvgetstr</STRONG>, and <STRONG>mvwgetstr</STRONG> may be macros.
  57
  58
  59 </PRE>
  60 <H2>PORTABILITY</H2><PRE>
  61        These functions are described in the XSI Curses  standard,
  62        Issue  4.   They  read  single-byte  characters only.  The
  63        standard specifies that they return <STRONG>ERR</STRONG>  on  failure,  but
  64        the  single  error  condition  <STRONG>EOVERFLOW</STRONG>  associated  with
  65        extended-level conformance is not yet  returned  (the  XSI
  66
  67        SVr3 and early SVr4 curses implementations did not  reject
  68        function keys; the SVr4.0 documentation claimed that "spe-
  69        cial keys" (such as function  keys,  "home"  key,  "clear"
  70        key,  <EM>etc</EM>.)  are  interpreted" without giving details.  It
  71        lied.  In fact, the  `character'  value  appended  to  the
  72        string  by  those  implementations was predictable but not
  73        useful (being, in fact, the low-order eight  bits  of  the
  74        key's KEY_ value).
  75
  76        The functions <STRONG>getnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, and <STRONG>mvwgetnstr</STRONG> were pre-
  77        sent but not documented in SVr4.
  78
  79
  80 </PRE>
  81 <H2>SEE ALSO</H2><PRE>
  82        <STRONG><A HREF="ncurses.3x.html">curses(3X)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3X)</A></STRONG>.
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120 </PRE>
 121 </BODY>
 122 </HTML>