ncurses 5.1
[ncurses.git] / 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>