1curs_inopts(3X)                                                curs_inopts(3X)
2
3
4

NAME

6       cbreak, nocbreak, echo, noecho, halfdelay, intrflush, keypad, meta,
7       nodelay, notimeout, raw, noraw, noqiflush, qiflush, timeout, wtimeout,
8       typeahead - curses input options
9

SYNOPSIS

11       #include <curses.h>
12
13       int cbreak(void);
14       int nocbreak(void);
15       int echo(void);
16       int noecho(void);
17       int halfdelay(int tenths);
18       int intrflush(WINDOW *win, bool bf);
19       int keypad(WINDOW *win, bool bf);
20       int meta(WINDOW *win, bool bf);
21       int nodelay(WINDOW *win, bool bf);
22       int raw(void);
23       int noraw(void);
24       void noqiflush(void);
25       void qiflush(void);
26       int notimeout(WINDOW *win, bool bf);
27       void timeout(int delay);
28       void wtimeout(WINDOW *win, int delay);
29       int typeahead(int fd);
30

DESCRIPTION

32       Normally,  the  tty  driver buffers typed characters until a newline or
33       carriage return is typed.  The cbreak routine disables  line  buffering
34       and erase/kill character-processing (interrupt and flow control charac‐
35       ters are unaffected), making characters typed by the  user  immediately
36       available to the program.  The nocbreak routine returns the terminal to
37       normal (cooked) mode.
38
39       Initially the terminal may or may not be in cbreak mode, as the mode is
40       inherited;  therefore, a program should call cbreak or nocbreak explic‐
41       itly.  Most interactive programs using  curses  set  the  cbreak  mode.
42       Note  that  cbreak overrides raw.  [See curs_getch(3X) for a discussion
43       of how these routines interact with echo and noecho.]
44
45       The echo and noecho routines control whether characters  typed  by  the
46       user  are echoed by getch as they are typed.  Echoing by the tty driver
47       is always disabled, but initially getch is in echo mode, so  characters
48       typed  are  echoed.   Authors of most interactive programs prefer to do
49       their own echoing in a controlled area of the screen, or not to echo at
50       all,  so  they  disable echoing by calling noecho.  [See curs_getch(3X)
51       for a discussion  of  how  these  routines  interact  with  cbreak  and
52       nocbreak.]
53
54       The  halfdelay routine is used for half-delay mode, which is similar to
55       cbreak mode in that characters typed by the user are immediately avail‐
56       able to the program.  However, after blocking for tenths tenths of sec‐
57       onds, ERR is returned if nothing has been typed.  The value  of  tenths
58       must  be  a number between 1 and 255.  Use nocbreak to leave half-delay
59       mode.
60
61       If the intrflush option is enabled, (bf is TRUE), when an interrupt key
62       is  pressed  on the keyboard (interrupt, break, quit) all output in the
63       tty driver queue will be flushed, giving the effect of faster  response
64       to  the interrupt, but causing curses to have the wrong idea of what is
65       on the screen.  Disabling (bf is FALSE), the option prevents the flush.
66       The  default  for the option is inherited from the tty driver settings.
67       The window argument is ignored.
68
69       The keypad option enables the keypad of the user's  terminal.   If  en‐
70       abled (bf is TRUE), the user can press a function key (such as an arrow
71       key) and wgetch returns a single value representing the  function  key,
72       as in KEY_LEFT.  If disabled (bf is FALSE), curses does not treat func‐
73       tion keys specially and the program has to  interpret  the  escape  se‐
74       quences  itself.   If the keypad in the terminal can be turned on (made
75       to transmit) and off (made to work locally),  turning  on  this  option
76       causes  the terminal keypad to be turned on when wgetch is called.  The
77       default value for keypad is false.
78
79       Initially, whether the terminal returns 7 or 8 significant bits on  in‐
80       put  depends on the control mode of the tty driver [see termio(7)].  To
81       force 8 bits to be returned, invoke meta(win, TRUE);  this  is  equiva‐
82       lent, under POSIX, to setting the CS8 flag on the terminal.  To force 7
83       bits to be returned, invoke meta(win, FALSE); this is equivalent, under
84       POSIX,  to  setting the CS7 flag on the terminal.  The window argument,
85       win, is always ignored.  If the terminfo capabilities smm (meta_on) and
86       rmm  (meta_off) are defined for the terminal, smm is sent to the termi‐
87       nal when meta(win, TRUE) is called  and  rmm  is  sent  when  meta(win,
88       FALSE) is called.
89
90       The nodelay option causes getch to be a non-blocking call.  If no input
91       is ready, getch returns ERR.  If disabled (bf is  FALSE),  getch  waits
92       until a key is pressed.
93
94       While  interpreting an input escape sequence, wgetch sets a timer while
95       waiting for the next character.  If  notimeout(win,  TRUE)  is  called,
96       then  wgetch  does  not  set a timer.  The purpose of the timeout is to
97       differentiate between sequences received from a function key and  those
98       typed by a user.
99
100       The  raw and noraw routines place the terminal into or out of raw mode.
101       Raw mode is similar to cbreak mode, in that characters typed are  imme‐
102       diately  passed  through to the user program.  The differences are that
103       in raw mode, the interrupt, quit, suspend, and flow control  characters
104       are  all  passed through uninterpreted, instead of generating a signal.
105       The behavior of the BREAK key depends on other bits in the  tty  driver
106       that are not set by curses.
107
108       When  the  noqiflush  routine is used, normal flush of input and output
109       queues associated with the INTR, QUIT and SUSP characters will  not  be
110       done  [see  termio(7)].   When  qiflush  is  called, the queues will be
111       flushed when these control characters are read.  You may want  to  call
112       noqiflush()  in  a  signal  handler  if  you want output to continue as
113       though the interrupt had not occurred, after the handler exits.
114
115       The timeout and wtimeout routines set blocking or non-blocking read for
116       a  given  window.   If  delay is negative, blocking read is used (i.e.,
117       waits indefinitely for input).  If delay  is  zero,  then  non-blocking
118       read is used (i.e., read returns ERR if no input is waiting).  If delay
119       is positive, then read blocks for delay milliseconds, and  returns  ERR
120       if  there  is  still  no input.  Hence, these routines provide the same
121       functionality as nodelay, plus the additional capability of being  able
122       to block for only delay milliseconds (where delay is positive).
123
124       The  curses  library does ``line-breakout optimization'' by looking for
125       typeahead periodically while updating the screen.  If input  is  found,
126       and  it is coming from a tty, the current update is postponed until re‐
127       fresh or doupdate is called again.  This allows faster response to com‐
128       mands  typed  in  advance.   Normally, the input FILE pointer passed to
129       newterm, or stdin in the case that initscr was used, will be used to do
130       this typeahead checking.  The typeahead routine specifies that the file
131       descriptor fd is to be used to check for typeahead instead.  If  fd  is
132       -1, then no typeahead checking is done.
133

RETURN VALUE

135       All  routines  that  return  an  integer return ERR upon failure and OK
136       (SVr4 specifies only "an integer value other than ERR") upon successful
137       completion,  unless  otherwise  noted in the preceding routine descrip‐
138       tions.
139
140       X/Open does not define any error conditions.  In  this  implementation,
141       functions  with  a window parameter will return an error if it is null.
142       Any function will also return an error if the terminal was not initial‐
143       ized.  Also,
144
145              halfdelay
146                   returns  an  error  if  its  parameter is outside the range
147                   1..255.
148

PORTABILITY

150       These functions are described in the XSI Curses standard, Issue 4.
151
152       The ncurses library obeys the XPG4 standard and the historical practice
153       of  the  AT&T  curses  implementations, in that the echo bit is cleared
154       when curses initializes the terminal state.  BSD curses  differed  from
155       this  slightly;  it left the echo bit on at initialization, but the BSD
156       raw call turned it off as a side-effect.   For  best  portability,  set
157       echo  or noecho explicitly just after initialization, even if your pro‐
158       gram remains in cooked mode.
159
160       When keypad is first enabled, ncurses loads the key-definitions for the
161       current terminal description.  If the terminal description includes ex‐
162       tended string capabilities, e.g., from using the -x option of tic, then
163       ncurses  also  defines keys for the capabilities whose names begin with
164       "k".  The corresponding keycodes are generated and (depending on previ‐
165       ous  loads of terminal descriptions) may differ from one execution of a
166       program to the next.  The generated keycodes are recognized by the key‐
167       name  function (which will then return a name beginning with "k" denot‐
168       ing the terminfo capability name rather than "K", used for curses  key-
169       names).  On the other hand, an application can use define_key to estab‐
170       lish a specific keycode for a given string.  This makes it possible for
171       an  application  to  check  for  an extended capability's presence with
172       tigetstr, and reassign the keycode to match its own needs.
173
174       Low-level applications can use tigetstr to obtain the definition of any
175       particular  string capability.  Higher-level applications which use the
176       curses wgetch and similar functions to return keycodes  rely  upon  the
177       order in which the strings are loaded.  If more than one key definition
178       has the same string value, then wgetch can  return  only  one  keycode.
179       Most curses implementations (including ncurses) load key definitions in
180       the order defined by the array of string capability  names.   The  last
181       key  to  be  loaded  determines the keycode which will be returned.  In
182       ncurses, you may also have extended  capabilities  interpreted  as  key
183       definitions.   These are loaded after the predefined keys, and if a ca‐
184       pability's value is the same as a previously-loaded key definition, the
185       later definition is the one used.
186

NOTES

188       Note that echo, noecho, halfdelay, intrflush, meta, nodelay, notimeout,
189       noqiflush, qiflush, timeout, and wtimeout may be macros.
190
191       The noraw and nocbreak calls follow historical practice  in  that  they
192       attempt  to restore to normal (`cooked') mode from raw and cbreak modes
193       respectively.  Mixing raw/noraw and cbreak/nocbreak calls leads to  tty
194       driver control states that are hard to predict or understand; it is not
195       recommended.
196

SEE ALSO

198       curses(3X),  curs_getch(3X),   curs_initscr(3X),   curs_util(3X),   de‐
199       fine_key(3X), termio(7)
200
201
202
203                                                               curs_inopts(3X)
Impressum