2 ****************************************************************************
3 * Copyright (c) 1998-2018,2019 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.28 2019/01/20 20:39:35 tom 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 https://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_inopts 3x</TITLE>
37 <link rel="author" 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>, <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>,
50 <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>,
51 <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input options
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
58 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
59 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
61 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
62 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
63 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
64 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
65 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
66 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
67 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
68 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
69 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
70 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
71 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
72 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
73 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
76 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
77 The <STRONG>ncurses</STRONG> library provides several functions which let an application
78 change the way input from the terminal is handled. Some are global,
79 applying to all windows. Others apply only to a specific window. Win-
80 dow-specific settings are not automatically applied to new or derived
81 windows. An application must apply these to each window, if the same
85 </PRE><H3><a name="h3-cbreak">cbreak</a></H3><PRE>
86 Normally, the tty driver buffers typed characters until a newline or
87 carriage return is typed. The <STRONG>cbreak</STRONG> routine disables line buffering
88 and erase/kill character-processing (interrupt and flow control charac-
89 ters are unaffected), making characters typed by the user immediately
90 available to the program. The <STRONG>nocbreak</STRONG> routine returns the terminal to
93 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode, as the mode is
94 inherited; therefore, a program should call <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explic-
95 itly. Most interactive programs using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode.
96 Note that <STRONG>cbreak</STRONG> overrides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion
97 of how these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
100 </PRE><H3><a name="h3-echo_noecho">echo/noecho</a></H3><PRE>
101 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters typed by the
102 user are echoed by <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG> as they are typed. Echoing by the tty
103 driver is always disabled, but initially <STRONG>getch</STRONG> is in echo mode, so
104 characters typed are echoed. Authors of most interactive programs pre-
105 fer to do their own echoing in a controlled area of the screen, or not
106 to echo at all, so they disable echoing by calling <STRONG>noecho</STRONG>. [See
107 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines interact with
108 <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
111 </PRE><H3><a name="h3-halfdelay">halfdelay</a></H3><PRE>
112 The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which is similar to
113 <STRONG>cbreak</STRONG> mode in that characters typed by the user are immediately avail-
114 able to the program. However, after blocking for <EM>tenths</EM> tenths of sec-
115 onds, <STRONG>ERR</STRONG> is returned if nothing has been typed. The value of <EM>tenths</EM>
116 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave half-delay
120 </PRE><H3><a name="h3-intrflush">intrflush</a></H3><PRE>
121 If the <STRONG>intrflush</STRONG> option is enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), and an interrupt key
122 is pressed on the keyboard (interrupt, break, quit), all output in the
123 tty driver queue will be flushed, giving the effect of faster response
124 to the interrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of what is
125 on the screen. Disabling the option (<EM>bf</EM> is <STRONG>FALSE</STRONG>) prevents the flush.
126 The default for the option is inherited from the tty driver settings.
127 The window argument is ignored.
130 </PRE><H3><a name="h3-keypad">keypad</a></H3><PRE>
131 The <STRONG>keypad</STRONG> option enables the keypad of the user's terminal. If en-
132 abled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a function key (such as an arrow
133 key) and <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> returns a single value representing the function
134 key, as in <STRONG>KEY_LEFT</STRONG>. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat
135 function keys specially and the program has to interpret the escape se-
136 quences itself. If the keypad in the terminal can be turned on (made
137 to transmit) and off (made to work locally), turning on this option
138 causes the terminal keypad to be turned on when <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> is called.
139 The default value for keypad is <STRONG>FALSE</STRONG>.
142 </PRE><H3><a name="h3-meta">meta</a></H3><PRE>
143 Initially, whether the terminal returns 7 or 8 significant bits on in-
144 put depends on the control mode of the tty driver [see <STRONG>termios(3)</STRONG>]. To
145 force 8 bits to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equiva-
146 lent, under POSIX, to setting the CS8 flag on the terminal. To force 7
147 bits to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equivalent, under
148 POSIX, to setting the CS7 flag on the terminal. The window argument,
149 <EM>win</EM>, is always ignored. If the terminfo capabilities <STRONG>smm</STRONG> (meta_on) and
150 <STRONG>rmm</STRONG> (meta_off) are defined for the terminal, <STRONG>smm</STRONG> is sent to the termi-
151 nal when <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
152 <STRONG>FALSE</STRONG>) is called.
155 </PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE>
156 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call. If no input
157 is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits
158 until a key is pressed.
160 While interpreting an input escape sequence, <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> sets a timer
161 while waiting for the next character. If <STRONG>notimeout(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is
162 called, then <STRONG>wgetch</STRONG> does not set a timer. The purpose of the timeout
163 is to differentiate between sequences received from a function key and
164 those typed by a user.
167 </PRE><H3><a name="h3-raw_noraw">raw/noraw</a></H3><PRE>
168 The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out of raw mode.
169 Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that characters typed are imme-
170 diately passed through to the user program. The differences are that
171 in raw mode, the interrupt, quit, suspend, and flow control characters
172 are all passed through uninterpreted, instead of generating a signal.
173 The behavior of the BREAK key depends on other bits in the tty driver
174 that are not set by <STRONG>curses</STRONG>.
177 </PRE><H3><a name="h3-noqiflush">noqiflush</a></H3><PRE>
178 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input and output
179 queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG> characters will not be
180 done [see <STRONG>termios(3)</STRONG>]. When <STRONG>qiflush</STRONG> is called, the queues will be
181 flushed when these control characters are read. You may want to call
182 <STRONG>noqiflush</STRONG> in a signal handler if you want output to continue as though
183 the interrupt had not occurred, after the handler exits.
186 </PRE><H3><a name="h3-timeout_wtimeout">timeout/wtimeout</a></H3><PRE>
187 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-blocking read for
188 a given window. If <EM>delay</EM> is negative, blocking read is used (i.e.,
189 waits indefinitely for input). If <EM>delay</EM> is zero, then non-blocking
190 read is used (i.e., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
191 is positive, then read blocks for <EM>delay</EM> milliseconds, and returns <STRONG>ERR</STRONG>
192 if there is still no input. Hence, these routines provide the same
193 functionality as <STRONG>nodelay</STRONG>, plus the additional capability of being able
194 to block for only <EM>delay</EM> milliseconds (where <EM>delay</EM> is positive).
197 </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE>
198 The <STRONG>curses</STRONG> library does "line-breakout optimization" by looking for ty-
199 peahead periodically while updating the screen. If input is found, and
200 it is coming from a tty, the current update is postponed until <STRONG>re-</STRONG>
201 <STRONG><A HREF="refresh.3x.html">fresh(3x)</A></STRONG> or <STRONG>doupdate</STRONG> is called again. This allows faster response to
202 commands typed in advance. Normally, the input FILE pointer passed to
203 <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used, will be used to do
204 this typeahead checking. The <STRONG>typeahead</STRONG> routine specifies that the file
205 descriptor <EM>fd</EM> is to be used to check for typeahead instead. If <EM>fd</EM> is
206 -1, then no typeahead checking is done.
209 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
210 All routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG>
211 (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
212 completion, unless otherwise noted in the preceding routine descrip-
215 X/Open does not define any error conditions. In this implementation,
216 functions with a window parameter will return an error if it is null.
217 Any function will also return an error if the terminal was not initial-
220 <STRONG>halfdelay</STRONG>
221 returns an error if its parameter is outside the range
225 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
226 These functions are described in the XSI Curses standard, Issue 4.
228 The ncurses library obeys the XPG4 standard and the historical practice
229 of the AT&T curses implementations, in that the echo bit is cleared
230 when curses initializes the terminal state. BSD curses differed from
231 this slightly; it left the echo bit on at initialization, but the BSD
232 <STRONG>raw</STRONG> call turned it off as a side-effect. For best portability, set
233 echo or noecho explicitly just after initialization, even if your pro-
234 gram remains in cooked mode.
236 When <STRONG>keypad</STRONG> is first enabled, ncurses loads the key-definitions for the
237 current terminal description. If the terminal description includes ex-
238 tended string capabilities, e.g., from using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>, then
239 ncurses also defines keys for the capabilities whose names begin with
240 "k". The corresponding keycodes are generated and (depending on previ-
241 ous loads of terminal descriptions) may differ from one execution of a
242 program to the next. The generated keycodes are recognized by the <STRONG>key-</STRONG>
243 <STRONG>name</STRONG> function (which will then return a name beginning with "k" denot-
244 ing the terminfo capability name rather than "K", used for curses key-
245 names). On the other hand, an application can use <STRONG>define_key</STRONG> to estab-
246 lish a specific keycode for a given string. This makes it possible for
247 an application to check for an extended capability's presence with
248 <STRONG>tigetstr</STRONG>, and reassign the keycode to match its own needs.
250 Low-level applications can use <STRONG>tigetstr</STRONG> to obtain the definition of any
251 particular string capability. Higher-level applications which use the
252 curses <STRONG>wgetch</STRONG> and similar functions to return keycodes rely upon the
253 order in which the strings are loaded. If more than one key definition
254 has the same string value, then <STRONG>wgetch</STRONG> can return only one keycode.
255 Most curses implementations (including ncurses) load key definitions in
256 the order defined by the array of string capability names. The last
257 key to be loaded determines the keycode which will be returned. In
258 ncurses, you may also have extended capabilities interpreted as key
259 definitions. These are loaded after the predefined keys, and if a ca-
260 pability's value is the same as a previously-loaded key definition, the
261 later definition is the one used.
264 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
265 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>,
266 <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be macros.
268 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in that they
269 attempt to restore to normal ("cooked") mode from raw and cbreak modes
270 respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty
271 driver control states that are hard to predict or understand; it is not
275 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
276 <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="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG>de-</STRONG>
277 <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>, <STRONG>termios(3)</STRONG>
281 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
285 <li><a href="#h2-NAME">NAME</a></li>
286 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
287 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
289 <li><a href="#h3-cbreak">cbreak</a></li>
290 <li><a href="#h3-echo_noecho">echo/noecho</a></li>
291 <li><a href="#h3-halfdelay">halfdelay</a></li>
292 <li><a href="#h3-intrflush">intrflush</a></li>
293 <li><a href="#h3-keypad">keypad</a></li>
294 <li><a href="#h3-meta">meta</a></li>
295 <li><a href="#h3-nodelay">nodelay</a></li>
296 <li><a href="#h3-raw_noraw">raw/noraw</a></li>
297 <li><a href="#h3-noqiflush">noqiflush</a></li>
298 <li><a href="#h3-timeout_wtimeout">timeout/wtimeout</a></li>
299 <li><a href="#h3-typeahead">typeahead</a></li>
302 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
303 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
304 <li><a href="#h2-NOTES">NOTES</a></li>
305 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>