Gitiles
Code Review Sign In
gerrit.omnirom.org / android_external_libncurses / c1bcd6dd9af6865867a3d6716e4c1a45021a90e5 / . / doc / html / man / curs_inopts.3x.html
blob: 7eec3eda04c43de636fc0ff5dbd4556c622a2d60 [file] [log] [blame]
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2<!--
3 ****************************************************************************
4 * Copyright (c) 1998-2003,2005 Free Software Foundation, Inc. *
5 * *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
13 * *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
16 * *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
28 * authorization. *
29 ****************************************************************************
30 * @Id: curs_inopts.3x,v 1.13 2005/05/15 16:18:07 tom Exp @
31-->
32<HTML>
33<HEAD>
34<TITLE>curs_inopts 3x</TITLE>
35<link rev=made href="mailto:bug-ncurses@gnu.org">
36<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
37</HEAD>
38<BODY>
39<H1>curs_inopts 3x</H1>
40<HR>
41<PRE>
42<!-- Manpage converted by man2html 3.0.1 -->
43<STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
44
45
46
47
48</PRE>
49<H2>NAME</H2><PRE>
50 <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>,
51 <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>,
52 <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input
53 options
54
55
56</PRE>
57<H2>SYNOPSIS</H2><PRE>
58 <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
59
60 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
61 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
64 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
65 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
66 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
67 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
68 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
69 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
70 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
71 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
72 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
73 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
74 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
75 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
76 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
77
78
79</PRE>
80<H2>DESCRIPTION</H2><PRE>
81 Normally, the tty driver buffers typed characters until a
82 newline or carriage return is typed. The <STRONG>cbreak</STRONG> routine
83 disables line buffering and erase/kill character-process-
84 ing (interrupt and flow control characters are unaffect-
85 ed), making characters typed by the user immediately
86 available to the program. The <STRONG>nocbreak</STRONG> routine returns
87 the terminal to normal (cooked) mode.
88
89 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode,
90 as the mode is inherited; therefore, a program should call
91 <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. Most interactive programs
92 using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode. Note that <STRONG>cbreak</STRONG> over-
93 rides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how
94 these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
95
96 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters
97 typed by the user are echoed by <STRONG>getch</STRONG> as they are typed.
98 Echoing by the tty driver is always disabled, but initial-
99 ly <STRONG>getch</STRONG> is in echo mode, so characters typed are echoed.
100 Authors of most interactive programs prefer to do their
101 own echoing in a controlled area of the screen, or not to
102 echo at all, so they disable echoing by calling <STRONG>noecho</STRONG>.
103 [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines
104 interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
105
106 The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which
107 is similar to <STRONG>cbreak</STRONG> mode in that characters typed by the
108 user are immediately available to the program. However,
109 after blocking for <EM>tenths</EM> tenths of seconds, ERR is re-
110 turned if nothing has been typed. The value of <STRONG>tenths</STRONG>
111 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave
112 half-delay mode.
113
114 If the <STRONG>intrflush</STRONG> option is enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), when an
115 interrupt key is pressed on the keyboard (interrupt,
116 break, quit) all output in the tty driver queue will be
117 flushed, giving the effect of faster response to the in-
118 terrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of what
119 is on the screen. Disabling (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the option
120 prevents the flush. The default for the option is inher-
121 ited from the tty driver settings. The window argument is
122 ignored.
123
124 The <STRONG>keypad</STRONG> option enables the keypad of the user's termi-
125 nal. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a func-
126 tion key (such as an arrow key) and <STRONG>wgetch</STRONG> returns a sin-
127 gle value representing the function key, as in <STRONG>KEY_LEFT</STRONG>.
128 If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat function
129 keys specially and the program has to interpret the escape
130 sequences itself. If the keypad in the terminal can be
131 turned on (made to transmit) and off (made to work local-
132 ly), turning on this option causes the terminal keypad to
133 be turned on when <STRONG>wgetch</STRONG> is called. The default value for
134 keypad is false.
135
136 Initially, whether the terminal returns 7 or 8 significant
137 bits on input depends on the control mode of the tty driv-
138 er [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. To force 8 bits to be returned, in-
139 voke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX, to
140 setting the CS8 flag on the terminal. To force 7 bits to
141 be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equivalent,
142 under POSIX, to setting the CS7 flag on the terminal. The
143 window argument, <EM>win</EM>, is always ignored. If the terminfo
144 capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are defined
145 for the terminal, <STRONG>smm</STRONG> is sent to the terminal when
146 <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
147 <STRONG>FALSE</STRONG>) is called.
148
149 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.
150 If no input is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM>
151 is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits until a key is pressed.
152
153 While interpreting an input escape sequence, <STRONG>wgetch</STRONG> sets a
154 timer while waiting for the next character. If <STRONG>notime-</STRONG>
155 <STRONG>out(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, then <STRONG>wgetch</STRONG> does not set a
156 timer. The purpose of the timeout is to differentiate be-
157 tween sequences received from a function key and those
158 typed by a user.
159
160 The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out
161 of raw mode. Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that
162 characters typed are immediately passed through to the us-
163 er program. The differences are that in raw mode, the in-
164 terrupt, quit, suspend, and flow control characters are
165 all passed through uninterpreted, instead of generating a
166 signal. The behavior of the BREAK key depends on other
167 bits in the tty driver that are not set by <STRONG>curses</STRONG>.
168
169 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input
170 and output queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG>
171 characters will not be done [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. When <STRONG>qiflush</STRONG>
172 is called, the queues will be flushed when these control
173 characters are read. You may want to call <STRONG>noqiflush()</STRONG> in
174 a signal handler if you want output to continue as though
175 the interrupt had not occurred, after the handler exits.
176
177 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-
178 blocking read for a given window. If <EM>delay</EM> is negative,
179 blocking read is used (i.e., waits indefinitely for in-
180 put). If <EM>delay</EM> is zero, then non-blocking read is used
181 (i.e., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
182 is positive, then read blocks for <EM>delay</EM> milliseconds, and
183 returns <STRONG>ERR</STRONG> if there is still no input. Hence, these rou-
184 tines provide the same functionality as <STRONG>nodelay</STRONG>, plus the
185 additional capability of being able to block for only <EM>de-</EM>
186 <EM>lay</EM> milliseconds (where <EM>delay</EM> is positive).
187
188 The <STRONG>curses</STRONG> library does ``line-breakout optimization'' by
189 looking for typeahead periodically while updating the
190 screen. If input is found, and it is coming from a tty,
191 the current update is postponed until <STRONG>refresh</STRONG> or <STRONG>doupdate</STRONG>
192 is called again. This allows faster response to commands
193 typed in advance. Normally, the input FILE pointer passed
194 to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used,
195 will be used to do this typeahead checking. The <STRONG>typeahead</STRONG>
196 routine specifies that the file descriptor <EM>fd</EM> is to be
197 used to check for typeahead instead. If <EM>fd</EM> is -1, then no
198 typeahead checking is done.
199
200
201</PRE>
202<H2>RETURN VALUE</H2><PRE>
203 All routines that return an integer return <STRONG>ERR</STRONG> upon fail-
204 ure and OK (SVr4 specifies only "an integer value other
205 than <STRONG>ERR</STRONG>") upon successful completion, unless otherwise
206 noted in the preceding routine descriptions.
207
208 X/Open does not define any error conditions. In this im-
209 plementation, functions with a window parameter will re-
210 turn an error if it is null. Any function will also re-
211 turn an error if the terminal was not initialized. Also,
212
213 <STRONG>halfdelay</STRONG>
214 returns an error if its parameter is outside
215 the range 1..255.
216
217
218</PRE>
219<H2>PORTABILITY</H2><PRE>
220 These functions are described in the XSI Curses standard,
221 Issue 4.
222
223 The ncurses library obeys the XPG4 standard and the his-
224 torical practice of the AT&amp;T curses implementations, in
225 that the echo bit is cleared when curses initializes the
226 terminal state. BSD curses differed from this slightly;
227 it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG>
228 call turned it off as a side-effect. For best portabili-
229 ty, set echo or noecho explicitly just after initializa-
230 tion, even if your program remains in cooked mode.
231
232
233</PRE>
234<H2>NOTES</H2><PRE>
235 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>node-</STRONG>
236 <STRONG>lay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
237 may be macros.
238
239 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
240 that they attempt to restore to normal (`cooked') mode
241 from raw and cbreak modes respectively. Mixing raw/noraw
242 and cbreak/nocbreak calls leads to tty driver control
243 states that are hard to predict or understand; it is not
244 recommended.
245
246
247</PRE>
248<H2>SEE ALSO</H2><PRE>
249 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>
250
251
252
253 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
254</PRE>
255<HR>
256<ADDRESS>
257Man(1) output converted with
258<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
259</ADDRESS>
260</BODY>
261</HTML>