2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
4 <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>key-</STRONG>
5 <STRONG>pad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, <STRONG>noqiflush</STRONG>,
6 <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, <STRONG>wtimeout</STRONG>, <STRONG>typeahead</STRONG> - <STRONG>curses</STRONG> input
11 <H2>SYNOPSIS</H2><PRE>
12 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
14 <STRONG>int</STRONG> <STRONG>cbreak(void);</STRONG>
15 <STRONG>int</STRONG> <STRONG>nocbreak(void);</STRONG>
16 <STRONG>int</STRONG> <STRONG>echo(void);</STRONG>
17 <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG>
18 <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <STRONG>tenths);</STRONG>
19 <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
20 <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
21 <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
22 <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
23 <STRONG>int</STRONG> <STRONG>raw(void);</STRONG>
24 <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG>
25 <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG>
26 <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG>
27 <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
28 <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <STRONG>delay);</STRONG>
29 <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>delay);</STRONG>
30 <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <STRONG>fd);</STRONG>
34 <H2>DESCRIPTION</H2><PRE>
35 Normally, the tty driver buffers typed characters until a
36 newline or carriage return is typed. The <STRONG>cbreak</STRONG> routine
37 disables line buffering and erase/kill character-process-
38 ing (interrupt and flow control characters are unaf-
39 fected), making characters typed by the user immediately
40 available to the program. The <STRONG>nocbreak</STRONG> routine returns
41 the terminal to normal (cooked) mode.
43 Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode,
44 as the mode is inherited; therefore, a program should call
45 <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. Most interactive programs
46 using <STRONG>curses</STRONG> set the <STRONG>cbreak</STRONG> mode. Note that <STRONG>cbreak</STRONG> over-
47 rides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3X)</A></STRONG> for a discussion of how
48 these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.]
50 The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters
51 typed by the user are echoed by <STRONG>getch</STRONG> as they are typed.
52 Echoing by the tty driver is always disabled, but ini-
53 tially <STRONG>getch</STRONG> is in echo mode, so characters typed are
54 echoed. Authors of most interactive programs prefer to do
55 their own echoing in a controlled area of the screen, or
56 not to echo at all, so they disable echoing by calling
57 <STRONG>noecho</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3X)</A></STRONG> for a discussion of how these
58 routines interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.]
60 user are immediately available to the program. However,
61 after blocking for <EM>tenths</EM> tenths of seconds, ERR is
62 returned if nothing has been typed. The value of <STRONG>tenths</STRONG>
63 must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave
66 If the <STRONG>intrflush</STRONG> option is enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), when an
67 interrupt key is pressed on the keyboard (interrupt,
68 break, quit) all output in the tty driver queue will be
69 flushed, giving the effect of faster response to the
70 interrupt, but causing <STRONG>curses</STRONG> to have the wrong idea of
71 what is on the screen. Disabling (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the
72 option prevents the flush. The default for the option is
73 inherited from the tty driver settings. The window argu-
76 The <STRONG>keypad</STRONG> option enables the keypad of the user's termi-
77 nal. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a func-
78 tion key (such as an arrow key) and <STRONG>wgetch</STRONG> returns a sin-
79 gle value representing the function key, as in <STRONG>KEY_LEFT</STRONG>.
80 If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>curses</STRONG> does not treat function
81 keys specially and the program has to interpret the escape
82 sequences itself. If the keypad in the terminal can be
83 turned on (made to transmit) and off (made to work
84 locally), turning on this option causes the terminal key-
85 pad to be turned on when <STRONG>wgetch</STRONG> is called. The default
86 value for keypad is false.
88 Initially, whether the terminal returns 7 or 8 significant
89 bits on input depends on the control mode of the tty
90 driver [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. To force 8 bits to be returned,
91 invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); this is equivalent, under POSIX,
92 to setting the CS8 flag on the terminal. To force 7 bits
93 to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); this is equiva-
94 lent, under POSIX, to setting the CS8 flag on the termi-
95 nal. The window argument, <EM>win</EM>, is always ignored. If the
96 terminfo capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are
97 defined for the terminal, <STRONG>smm</STRONG> is sent to the terminal when
98 <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>,
99 <STRONG>FALSE</STRONG>) is called.
101 The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call.
102 If no input is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM>
103 is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits until a key is pressed.
105 While interpreting an input escape sequence, <STRONG>wgetch</STRONG> sets a
106 timer while waiting for the next character. If <STRONG>notime-</STRONG>
107 <STRONG>out(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, then <STRONG>wgetch</STRONG> does not set a
108 timer. The purpose of the timeout is to differentiate
109 between sequences received from a function key and those
112 characters typed are immediately passed through to the
113 user program. The differences are that in raw mode, the
114 interrupt, quit, suspend, and flow control characters are
115 all passed through uninterpreted, instead of generating a
116 signal. The behavior of the BREAK key depends on other
117 bits in the tty driver that are not set by <STRONG>curses</STRONG>.
119 When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input
120 and output queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG>
121 characters will not be done [see <STRONG><A HREF="termio.7.html">termio(7)</A></STRONG>]. When <STRONG>qiflush</STRONG>
122 is called, the queues will be flushed when these control
123 characters are read. You may want to call <STRONG>noqiflush()</STRONG> in
124 a signal handler if you want output to continue as though
125 the interrupt had not occurred, after the handler exits.
127 The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-
128 blocking read for a given window. If <EM>delay</EM> is negative,
129 blocking read is used (<EM>i</EM>.<EM>e</EM>., waits indefinitely for
130 input). If <EM>delay</EM> is zero, then non-blocking read is used
131 (<EM>i</EM>.<EM>e</EM>., read returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM>
132 is positive, then read blocks for <EM>delay</EM> milliseconds, and
133 returns <STRONG>ERR</STRONG> if there is still no input. Hence, these rou-
134 tines provide the same functionality as <STRONG>nodelay</STRONG>, plus the
135 additional capability of being able to block for only
136 <EM>delay</EM> milliseconds (where <EM>delay</EM> is positive).
138 The <STRONG>curses</STRONG> library does ``line-breakout optimization'' by
139 looking for typeahead periodically while updating the
140 screen. If input is found, and it is coming from a tty,
141 the current update is postponed until <STRONG>refresh</STRONG> or <STRONG>doupdate</STRONG>
142 is called again. This allows faster response to commands
143 typed in advance. Normally, the input FILE pointer passed
144 to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used,
145 will be used to do this typeahead checking. The <STRONG>typeahead</STRONG>
146 routine specifies that the file descriptor <EM>fd</EM> is to be
147 used to check for typeahead instead. If <EM>fd</EM> is -1, then no
148 typeahead checking is done.
152 <H2>RETURN VALUE</H2><PRE>
153 All routines that return an integer return <STRONG>ERR</STRONG> upon fail-
154 ure and OK (SVr4 specifies only "an integer value other
155 than <STRONG>ERR</STRONG>") upon successful completion, unless otherwise
156 noted in the preceding routine descriptions.
160 <H2>PORTABILITY</H2><PRE>
161 These functions are described in the XSI Curses standard,
164 The ncurses library obeys the XPG4 standard and the his-
165 torical practice of the AT&T curses implementations, in
166 that the echo bit is cleared when curses initializes the
167 terminal state. BSD curses differed from this slightly;
168 ity, set echo or noecho explicitly just after initializa-
169 tion, even if your program remains in cooked mode.
174 Note that <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>node-</STRONG>
175 <STRONG>lay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG>
178 The <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> calls follow historical practice in
179 that they attempt to restore to normal (`cooked') mode
180 from raw and cbreak modes respectively. Mixing raw/noraw
181 and cbreak/nocbreak calls leads to tty driver control
182 states that are hard to predict or understand; it is not
187 <H2>SEE ALSO</H2><PRE>
188 <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>