2 ****************************************************************************
3 * Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************
29 * @Id: curs_inopts.3x,v 1.20 2015/11/28 19:03:12 Benno.Schulenberg Exp @
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_inopts 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 <H1 class="no-header">curs_inopts 3x</H1>
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>
48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
49 <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>,
50 <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>,
51 <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
58 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
59 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
61 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
62 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
63 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
64 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
65 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
66 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
67 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
68 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
69 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
70 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
71 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
72 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
73 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
74 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
77 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
78 The <STRONG>ncurses</STRONG> library provides several functions which let
79 an application change the way input from the terminal is
80 handled. Some are global, applying to all windows. Oth-
81 ers apply only to a specific window. Window-specific set-
82 tings are not automatically applied to new or derived win-
83 dows. An application must apply these to each window, if
84 the same behavior is needed.
87 </PRE><H3><a name="h3-cbreak">cbreak</a></H3><PRE>
88 Normally, the tty driver buffers typed characters until a
89 newline or carriage return is typed. The <STRONG>cbreak</STRONG> routine
90 disables line buffering and erase/kill character-process-
91 ing (interrupt and flow control characters are unaffect-
92 ed), making characters typed by the user immediately
93 available to the program. The <STRONG>nocbreak</STRONG> routine returns
94 the terminal to normal (cooked) mode.
96 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode,
97 as the mode is inherited; therefore, a program should call
98 <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. Most interactive programs
99 using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode. Note that <STRONG>cbreak</STRONG> over-
100 rides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how
101 these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
104 </PRE><H3><a name="h3-echo_noecho">echo/noecho</a></H3><PRE>
105 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters
106 typed by the user are echoed by <STRONG>getch</STRONG> as they are typed.
107 Echoing by the tty driver is always disabled, but initial-
108 ly <STRONG>getch</STRONG> is in echo mode, so characters typed are echoed.
109 Authors of most interactive programs prefer to do their
110 own echoing in a controlled area of the screen, or not to
111 echo at all, so they disable echoing by calling <STRONG>noecho</STRONG>.
112 [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines
113 interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
116 </PRE><H3><a name="h3-halfdelay">halfdelay</a></H3><PRE>
117 The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which
118 is similar to <STRONG>cbreak</STRONG> mode in that characters typed by the
119 user are immediately available to the program. However,
120 after blocking for <EM>tenths</EM> tenths of seconds, ERR is re-
121 turned if nothing has been typed. The value of <EM>tenths</EM>
122 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave
126 </PRE><H3><a name="h3-intrflush">intrflush</a></H3><PRE>
127 If the <STRONG>intrflush</STRONG> option is enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), and an
128 interrupt key is pressed on the keyboard (interrupt,
129 break, quit), all output in the tty driver queue will be
130 flushed, giving the effect of faster response to the in-
131 terrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of what
132 is on the screen. Disabling the option (<EM>bf</EM> is <STRONG>FALSE</STRONG>) pre-
133 vents the flush. The default for the option is inherited
134 from the tty driver settings. The window argument is ig-
138 </PRE><H3><a name="h3-keypad">keypad</a></H3><PRE>
139 The <STRONG>keypad</STRONG> option enables the keypad of the user's termi-
140 nal. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a func-
141 tion key (such as an arrow key) and <STRONG>wgetch</STRONG> returns a sin-
142 gle value representing the function key, as in <STRONG>KEY_LEFT</STRONG>.
143 If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat function
144 keys specially and the program has to interpret the escape
145 sequences itself. If the keypad in the terminal can be
146 turned on (made to transmit) and off (made to work local-
147 ly), turning on this option causes the terminal keypad to
148 be turned on when <STRONG>wgetch</STRONG> is called. The default value for
149 keypad is <STRONG>FALSE</STRONG>.
152 </PRE><H3><a name="h3-meta">meta</a></H3><PRE>
153 Initially, whether the terminal returns 7 or 8 significant
154 bits on input depends on the control mode of the tty driv-
155 er [see <STRONG>termio(7)</STRONG>]. To force 8 bits to be returned, in-
156 voke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX, to
157 setting the CS8 flag on the terminal. To force 7 bits to
158 be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equivalent,
159 under POSIX, to setting the CS7 flag on the terminal. The
160 window argument, <EM>win</EM>, is always ignored. If the terminfo
161 capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are defined
162 for the terminal, <STRONG>smm</STRONG> is sent to the terminal when
163 <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
164 <STRONG>FALSE</STRONG>) is called.
167 </PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE>
168 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.
169 If no input is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM>
170 is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits until a key is pressed.
172 While interpreting an input escape sequence, <STRONG>wgetch</STRONG> sets a
173 timer while waiting for the next character. If <STRONG>notime-</STRONG>
174 <STRONG>out(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, then <STRONG>wgetch</STRONG> does not set a
175 timer. The purpose of the timeout is to differentiate be-
176 tween sequences received from a function key and those
180 </PRE><H3><a name="h3-raw_noraw">raw/noraw</a></H3><PRE>
181 The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out
182 of raw mode. Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that
183 characters typed are immediately passed through to the us-
184 er program. The differences are that in raw mode, the in-
185 terrupt, quit, suspend, and flow control characters are
186 all passed through uninterpreted, instead of generating a
187 signal. The behavior of the BREAK key depends on other
188 bits in the tty driver that are not set by <STRONG>curses</STRONG>.
191 </PRE><H3><a name="h3-noqiflush">noqiflush</a></H3><PRE>
192 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input
193 and output queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG>
194 characters will not be done [see <STRONG>termio(7)</STRONG>]. When <STRONG>qiflush</STRONG>
195 is called, the queues will be flushed when these control
196 characters are read. You may want to call <STRONG>noqiflush()</STRONG> in
197 a signal handler if you want output to continue as though
198 the interrupt had not occurred, after the handler exits.
201 </PRE><H3><a name="h3-timeout_wtimeout">timeout/wtimeout</a></H3><PRE>
202 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-
203 blocking read for a given window. If <EM>delay</EM> is negative,
204 blocking read is used (i.e., waits indefinitely for in-
205 put). If <EM>delay</EM> is zero, then non-blocking read is used
206 (i.e., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
207 is positive, then read blocks for <EM>delay</EM> milliseconds, and
208 returns <STRONG>ERR</STRONG> if there is still no input. Hence, these rou-
209 tines provide the same functionality as <STRONG>nodelay</STRONG>, plus the
210 additional capability of being able to block for only <EM>de-</EM>
211 <EM>lay</EM> milliseconds (where <EM>delay</EM> is positive).
214 </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE>
215 The <STRONG>curses</STRONG> library does "line-breakout optimization" by
216 looking for typeahead periodically while updating the
217 screen. If input is found, and it is coming from a tty,
218 the current update is postponed until <STRONG>refresh</STRONG> or <STRONG>doupdate</STRONG>
219 is called again. This allows faster response to commands
220 typed in advance. Normally, the input FILE pointer passed
221 to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used,
222 will be used to do this typeahead checking. The <STRONG>typeahead</STRONG>
223 routine specifies that the file descriptor <EM>fd</EM> is to be
224 used to check for typeahead instead. If <EM>fd</EM> is -1, then no
225 typeahead checking is done.
228 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
229 All routines that return an integer return <STRONG>ERR</STRONG> upon fail-
230 ure and OK (SVr4 specifies only "an integer value other
231 than <STRONG>ERR</STRONG>") upon successful completion, unless otherwise
232 noted in the preceding routine descriptions.
234 X/Open does not define any error conditions. In this im-
235 plementation, functions with a window parameter will re-
236 turn an error if it is null. Any function will also re-
237 turn an error if the terminal was not initialized. Also,
239 <STRONG>halfdelay</STRONG>
240 returns an error if its parameter is outside
244 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
245 These functions are described in the XSI Curses standard,
248 The ncurses library obeys the XPG4 standard and the his-
249 torical practice of the AT&T curses implementations, in
250 that the echo bit is cleared when curses initializes the
251 terminal state. BSD curses differed from this slightly;
252 it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG>
253 call turned it off as a side-effect. For best portabili-
254 ty, set echo or noecho explicitly just after initializa-
255 tion, even if your program remains in cooked mode.
257 When <STRONG>keypad</STRONG> is first enabled, ncurses loads the key-defi-
258 nitions for the current terminal description. If the ter-
259 minal description includes extended string capabilities,
260 e.g., from using the <STRONG>-x</STRONG> option of tic, then ncurses also
261 defines keys for the capabilities whose names begin with
262 "k". The corresponding keycodes are generated and (de-
263 pending on previous loads of terminal descriptions) may
264 differ from one execution of a program to the next. The
265 generated keycodes are recognized by the <STRONG>keyname</STRONG> function
266 (which will then return a name beginning with "k" denoting
267 the terminfo capability name rather than "K", used for
268 curses key-names). On the other hand, an application can
269 use <STRONG>define_key</STRONG> to establish a specific keycode for a given
270 string. This makes it possible for an application to
271 check for an extended capability's presence with <EM>tigetstr</EM>,
272 and reassign the keycode to match its own needs.
274 Low-level applications can use <STRONG>tigetstr</STRONG> to obtain the def-
275 inition of any particular string capability. Higher-level
276 applications which use the curses <STRONG>wgetch</STRONG> and similar func-
277 tions to return keycodes rely upon the order in which the
278 strings are loaded. If more than one key definition has
279 the same string value, then <STRONG>wgetch</STRONG> can return only one
280 keycode. Most curses implementations (including ncurses)
281 load key definitions in the order defined by the array of
282 string capability names. The last key to be loaded deter-
283 mines the keycode which will be returned. In ncurses, you
284 may also have extended capabilities interpreted as key
285 definitions. These are loaded after the predefined keys,
286 and if a capability's value is the same as a previously-
287 loaded key definition, the later definition is the one
291 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
292 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>node-</STRONG>
293 <STRONG>lay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
296 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
297 that they attempt to restore to normal (`cooked') mode
298 from raw and cbreak modes respectively. Mixing raw/noraw
299 and cbreak/nocbreak calls leads to tty driver control
300 states that are hard to predict or understand; it is not
304 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
305 <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>,
306 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG>termio(7)</STRONG>
310 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
314 <li><a href="#h2-NAME">NAME</a></li>
315 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
316 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
318 <li><a href="#h3-cbreak">cbreak</a></li>
319 <li><a href="#h3-echo_noecho">echo/noecho</a></li>
320 <li><a href="#h3-halfdelay">halfdelay</a></li>
321 <li><a href="#h3-intrflush">intrflush</a></li>
322 <li><a href="#h3-keypad">keypad</a></li>
323 <li><a href="#h3-meta">meta</a></li>
324 <li><a href="#h3-nodelay">nodelay</a></li>
325 <li><a href="#h3-raw_noraw">raw/noraw</a></li>
326 <li><a href="#h3-noqiflush">noqiflush</a></li>
327 <li><a href="#h3-timeout_wtimeout">timeout/wtimeout</a></li>
328 <li><a href="#h3-typeahead">typeahead</a></li>
331 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
332 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
333 <li><a href="#h2-NOTES">NOTES</a></li>
334 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>