doc/html/man/curs_getstr.3x.html

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