| 1 |
'\" t |
| 2 |
.\"*************************************************************************** |
| 3 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 4 |
.\" Copyright 1998-2016,2017 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 |
.\" |
| 31 |
.\" $Id: curs_inopts.3x,v 1.116 2025/10/04 20:15:02 tom Exp $ |
| 32 |
.TH inopts 3NCURSES 2025-10-04 "ncurses 6.6" "Library calls" |
| 33 |
.ie \n(.g \{\ |
| 34 |
.ds `` \(lq |
| 35 |
.ds '' \(rq |
| 36 |
.\} |
| 37 |
.el \{\ |
| 38 |
.ie t .ds `` `` |
| 39 |
.el .ds `` "" |
| 40 |
.ie t .ds '' '' |
| 41 |
.el .ds '' "" |
| 42 |
.\} |
| 43 |
. |
| 44 |
.de bP |
| 45 |
.ie n .IP \(bu 4 |
| 46 |
.el .IP \(bu 2 |
| 47 |
.. |
| 48 |
.SH NAME |
| 49 |
\fB\%cbreak\fP, |
| 50 |
\fB\%echo\fP, |
| 51 |
\fB\%halfdelay\fP, |
| 52 |
\fB\%intrflush\fP, |
| 53 |
\fB\%is_cbreak\fP, |
| 54 |
\fB\%is_echo\fP, |
| 55 |
\fB\%is_nl\fP, |
| 56 |
\fB\%is_raw\fP, |
| 57 |
\fB\%keypad\fP, |
| 58 |
\fB\%meta\fP, |
| 59 |
\fB\%nl\fP, |
| 60 |
\fB\%nocbreak\fP, |
| 61 |
\fB\%nodelay\fP, |
| 62 |
\fB\%noecho\fP, |
| 63 |
\fB\%nonl\fP, |
| 64 |
\fB\%noqiflush\fP, |
| 65 |
\fB\%noraw\fP, |
| 66 |
\fB\%notimeout\fP, |
| 67 |
\fB\%qiflush\fP, |
| 68 |
\fB\%raw\fP, |
| 69 |
\fB\%timeout\fP, |
| 70 |
\fB\%wtimeout\fP, |
| 71 |
\fB\%typeahead\fP \- |
| 72 |
get and set \fIcurses\fR terminal input options |
| 73 |
.SH SYNOPSIS |
| 74 |
.nf |
| 75 |
\fB#include <curses.h> |
| 76 |
.PP |
| 77 |
\fBint cbreak(void); |
| 78 |
\fBint nocbreak(void); |
| 79 |
.PP |
| 80 |
\fBint echo(void); |
| 81 |
\fBint noecho(void); |
| 82 |
.PP |
| 83 |
\fBint intrflush(WINDOW * \fIwin\fP \fI/* ignored */\fP, bool \fIbf\fP); |
| 84 |
\fBint keypad(WINDOW * \fIwin\fP, bool \fIbf\fP); |
| 85 |
\fBint meta(WINDOW * \fIwin\fP \fI/* ignored */\fP, bool \fIbf\fP); |
| 86 |
\fBint nodelay(WINDOW * \fIwin\fP, bool \fIbf\fP); |
| 87 |
\fBint notimeout(WINDOW * \fIwin\fP, bool \fIbf\fP); |
| 88 |
.PP |
| 89 |
\fBint nl(void); |
| 90 |
\fBint nonl(void); |
| 91 |
.PP |
| 92 |
\fBvoid qiflush(void); |
| 93 |
\fBvoid noqiflush(void); |
| 94 |
.PP |
| 95 |
\fBint raw(void); |
| 96 |
\fBint noraw(void); |
| 97 |
.PP |
| 98 |
\fBint halfdelay(int \fItenths\fP); |
| 99 |
\fBvoid timeout(int \fIdelay\fP); |
| 100 |
\fBvoid wtimeout(WINDOW * \fIwin\fP, int \fIdelay\fP); |
| 101 |
.PP |
| 102 |
\fBint typeahead(int \fIfd\fP); |
| 103 |
.PP |
| 104 |
\fI/* extensions */ |
| 105 |
\fBint is_cbreak(void); |
| 106 |
\fBint is_echo(void); |
| 107 |
\fBint is_nl(void); |
| 108 |
\fBint is_raw(void); |
| 109 |
.fi |
| 110 |
.SH DESCRIPTION |
| 111 |
.I curses |
| 112 |
offers configurable parameters permitting an application to control the |
| 113 |
handling of input from the terminal. |
| 114 |
Some, |
| 115 |
such as those affecting the terminal's |
| 116 |
.I mode |
| 117 |
or line discipline, |
| 118 |
are global, |
| 119 |
applying to all windows; |
| 120 |
others apply only to a specific window. |
| 121 |
The library does not automatically apply such parameters to new or |
| 122 |
derived windows; |
| 123 |
an application must configure each window for the desired behavior. |
| 124 |
.PP |
| 125 |
Some descriptions below make reference to an |
| 126 |
.IR "input character reading function" ":" |
| 127 |
this is \fB\%wgetch\fP(3NCURSES) in the non-wide character |
| 128 |
.I curses |
| 129 |
API and \fB\%wget_wch\fP(3NCURSES) in the wide character API. |
| 130 |
In addition to the variant forms of these described in |
| 131 |
\fB\%ncurses\fP(3NCURSES), |
| 132 |
the |
| 133 |
.I curses |
| 134 |
functions \fB\%wgetstr\fP(3NCURSES) and \fB\%wget_wstr\fP(3NCURSES) and their own |
| 135 |
variants call the appropriate input character reading function. |
| 136 |
.\" |
| 137 |
.SS "cbreak, nocbreak" |
| 138 |
Normally, |
| 139 |
the terminal driver buffers typed characters, |
| 140 |
not delivering them to an application |
| 141 |
until a line feed or carriage return is typed. |
| 142 |
This canonical (\*(``cooked\*('') line discipline also supports |
| 143 |
software flow control, |
| 144 |
simple line editing functions |
| 145 |
(character and word erase, |
| 146 |
and whole-line erasure or \*(``kill\*(''), |
| 147 |
and job control. |
| 148 |
.B \%cbreak |
| 149 |
configures the terminal in |
| 150 |
.IR "cbreak mode" "," |
| 151 |
which disables line buffering |
| 152 |
and erase and kill character processing \(em |
| 153 |
the interrupt, |
| 154 |
quit, |
| 155 |
suspend, |
| 156 |
and flow control characters are unaffected \(em |
| 157 |
and makes characters typed by the user immediately available to the |
| 158 |
program. |
| 159 |
.B \%nocbreak |
| 160 |
restores canonical (\*(``cooked\*('') mode. |
| 161 |
.PP |
| 162 |
The state of the terminal is unknown to a |
| 163 |
.I curses |
| 164 |
application when it starts; |
| 165 |
therefore, |
| 166 |
a program should call |
| 167 |
.B \%cbreak |
| 168 |
or |
| 169 |
.B \%nocbreak |
| 170 |
explicitly. |
| 171 |
Most interactive programs using |
| 172 |
.I curses |
| 173 |
set \%cbreak |
| 174 |
mode. |
| 175 |
Calling |
| 176 |
.B \%cbreak |
| 177 |
overrides |
| 178 |
.BR raw "." |
| 179 |
The man page for the input character reading function |
| 180 |
discusses how |
| 181 |
.B \%cbreak |
| 182 |
and |
| 183 |
.B \%nocbreak |
| 184 |
interact with |
| 185 |
.B echo |
| 186 |
and |
| 187 |
.BR \%noecho "." |
| 188 |
.\" |
| 189 |
.SS "echo, noecho" |
| 190 |
.B echo |
| 191 |
and |
| 192 |
.B \%noecho |
| 193 |
determine whether characters typed by the user are written to the |
| 194 |
.I curses |
| 195 |
window by the input character reading function as they are typed. |
| 196 |
.I curses |
| 197 |
always disables the terminal driver's own echoing. |
| 198 |
By default, |
| 199 |
a |
| 200 |
.I curses |
| 201 |
screen's echo option is set. |
| 202 |
Authors of most interactive programs prefer |
| 203 |
to do their own echoing in a controlled area of the screen, |
| 204 |
or not to echo at all, |
| 205 |
so they call |
| 206 |
.BR \%noecho "." |
| 207 |
The man page for the input character reading function |
| 208 |
discusses how |
| 209 |
.B echo |
| 210 |
and |
| 211 |
.B \%noecho |
| 212 |
interact with |
| 213 |
.B \%cbreak |
| 214 |
and |
| 215 |
.BR \%nocbreak "." |
| 216 |
.\" |
| 217 |
.SS halfdelay |
| 218 |
.B \%halfdelay |
| 219 |
configures |
| 220 |
.IR "half-delay mode" "," |
| 221 |
which is similar to \%cbreak mode in that characters typed by the user |
| 222 |
are immediately available to the program. |
| 223 |
However, |
| 224 |
after blocking for |
| 225 |
.I tenths |
| 226 |
tenth-seconds, |
| 227 |
an input character reading function returns |
| 228 |
.B ERR |
| 229 |
if no input is pending. |
| 230 |
The value of |
| 231 |
.I tenths |
| 232 |
must be between 1 and 255. |
| 233 |
Use |
| 234 |
.B \%nocbreak |
| 235 |
to leave half-delay mode. |
| 236 |
.\" |
| 237 |
.SS intrflush |
| 238 |
.B \%intrflush |
| 239 |
calls |
| 240 |
.B \%qiflush |
| 241 |
(see below) |
| 242 |
if |
| 243 |
.I bf |
| 244 |
is |
| 245 |
.BR TRUE "," |
| 246 |
and |
| 247 |
.B \%noqiflush |
| 248 |
if |
| 249 |
.I bf |
| 250 |
is |
| 251 |
.BR FALSE "." |
| 252 |
It ignores its |
| 253 |
.I win |
| 254 |
argument. |
| 255 |
.\" |
| 256 |
.SS keypad |
| 257 |
.B keypad |
| 258 |
enables recognition of a terminal's function keys. |
| 259 |
If |
| 260 |
enabled |
| 261 |
.RI ( bf |
| 262 |
is |
| 263 |
.BR TRUE ")" |
| 264 |
then when an input character reading function reads ESC, |
| 265 |
it waits for further input corresponding to an escape sequence |
| 266 |
defined by the terminal type description. |
| 267 |
If a valid sequence populates the input stream, |
| 268 |
the input character reading function |
| 269 |
returns a value representing the function key, |
| 270 |
such as |
| 271 |
.BR KEY_LEFT "." |
| 272 |
(Wide-character API users: |
| 273 |
\fB\%wget_wch\fP(3NCURSES) returns |
| 274 |
.B \%KEY_CODE_YES |
| 275 |
to indicate the availability of a function key code in its |
| 276 |
.I wch |
| 277 |
parameter.) |
| 278 |
If the sequence is invalid, |
| 279 |
the input character reading function returns only its last character. |
| 280 |
If disabled |
| 281 |
.RI ( bf |
| 282 |
is |
| 283 |
.BR FALSE ), |
| 284 |
.I curses |
| 285 |
does not treat function keys specially and the program has to interpret |
| 286 |
escape sequences itself. |
| 287 |
If the terminal type description defines the |
| 288 |
.B \%keypad_local |
| 289 |
.RB ( rmkx ) |
| 290 |
and |
| 291 |
.B \%keypad_xmit |
| 292 |
.RB ( smkx ) |
| 293 |
capabilities, |
| 294 |
enabling a window's keypad mode |
| 295 |
sets the terminal's keypad to transmit, |
| 296 |
and disabling keypad mode |
| 297 |
sets the terminal's keypad to work locally. |
| 298 |
By default, |
| 299 |
a window's keypad mode is off. |
| 300 |
.\" |
| 301 |
.SS meta |
| 302 |
Initially, |
| 303 |
whether the terminal returns 7- or 8-bit character codes on input |
| 304 |
depends on the configuration of the terminal driver; |
| 305 |
on POSIX systems, |
| 306 |
see \fI\%termios\fP(3). |
| 307 |
To force 8 bits to be returned, |
| 308 |
call |
| 309 |
.BR meta( .\|.\|. , |
| 310 |
.BR TRUE) ; |
| 311 |
this is equivalent, |
| 312 |
on POSIX systems, |
| 313 |
to setting the CS8 flag on the terminal. |
| 314 |
To force 7 bits to be returned, |
| 315 |
call |
| 316 |
.BR meta( .\|.\|. , |
| 317 |
.BR FALSE) ; |
| 318 |
this is equivalent, |
| 319 |
on POSIX systems, |
| 320 |
to setting the CS7 flag on the terminal. |
| 321 |
.I curses |
| 322 |
ignores the window argument |
| 323 |
.IR win "." |
| 324 |
If the |
| 325 |
.I \%term\%info |
| 326 |
string capabilities |
| 327 |
.B \%meta_on |
| 328 |
.RB ( smm ) |
| 329 |
and |
| 330 |
.B \%meta_off |
| 331 |
.RB ( rmm ) |
| 332 |
are defined for the terminal type, |
| 333 |
enabling meta mode sends |
| 334 |
.BR smm 's |
| 335 |
value to the terminal and disabling it sends that of |
| 336 |
.B rmm |
| 337 |
to the terminal. |
| 338 |
.\" |
| 339 |
.SS "nl, nonl" |
| 340 |
Initially, |
| 341 |
whether the terminal reports a carriage return |
| 342 |
using the character code for a line feed |
| 343 |
in cbreak or raw modes |
| 344 |
depends on the configuration of the terminal driver; |
| 345 |
see \fI\%termios\fP(3). |
| 346 |
.B nl |
| 347 |
configures the terminal to perform this translation. |
| 348 |
.B nonl |
| 349 |
disables it. |
| 350 |
Under its canonical (\*(``cooked\*('') line discipline, |
| 351 |
the terminal driver always translates carriage returns to line feeds. |
| 352 |
.\" |
| 353 |
.SS nodelay |
| 354 |
.B \%nodelay |
| 355 |
configures the input character reading function to be non-blocking for |
| 356 |
window |
| 357 |
.IR "win" . |
| 358 |
If no input is ready, |
| 359 |
the reading function returns |
| 360 |
.BR ERR "." |
| 361 |
If disabled |
| 362 |
.RI ( bf |
| 363 |
is |
| 364 |
.BR FALSE ), |
| 365 |
the reading function does not return until it has input. |
| 366 |
.SS notimeout |
| 367 |
When |
| 368 |
.B \%keypad |
| 369 |
has been called on a window |
| 370 |
and the input character reading function reads an ESC character from it, |
| 371 |
.I curses |
| 372 |
sets a timer while waiting for the next character. |
| 373 |
If the timer elapses, |
| 374 |
.I curses |
| 375 |
interprets the ESC as an explicit press of the terminal's Escape key |
| 376 |
(or equivalent). |
| 377 |
.\" like Control+[ |
| 378 |
.BI \%notimeout( win , |
| 379 |
.B TRUE) |
| 380 |
disables this timer. |
| 381 |
The purpose of the timeout is to distinguish sequences produced by a |
| 382 |
function key from those typed by a user. |
| 383 |
If this timer is disabled, |
| 384 |
.I curses |
| 385 |
waits forever for subsequent keystrokes |
| 386 |
until it determines the escape sequence to be valid or invalid. |
| 387 |
.\" |
| 388 |
.SS "qiflush, noqiflush" |
| 389 |
.\" |
| 390 |
.B \%qiflush |
| 391 |
and |
| 392 |
.B \%noqiflush |
| 393 |
configure the terminal driver's treatment of its input and output queues |
| 394 |
when it handles the interrupt, |
| 395 |
suspend, |
| 396 |
or quit characters under the canonical (\*(``cooked\*('') |
| 397 |
or cbreak line disciplines on POSIX systems; |
| 398 |
see \fI\%termios\fP(3). |
| 399 |
The default behavior is inherited from the terminal driver settings. |
| 400 |
Calling |
| 401 |
.B \%qiflush |
| 402 |
configures the terminal to |
| 403 |
.I flush |
| 404 |
the queues |
| 405 |
(discarding their contents) |
| 406 |
when any of these events occurs, |
| 407 |
giving the impression of faster response to user input, |
| 408 |
but making the library's model of the screen contents incorrect. |
| 409 |
Calling |
| 410 |
.B \%noqiflush |
| 411 |
prevents such flushing, |
| 412 |
but might frustrate impatient users on slow connections if a |
| 413 |
.I curses |
| 414 |
update of the screen is in progress when the event occurs; |
| 415 |
see |
| 416 |
.B \%typeahead |
| 417 |
below for a mitigation of this problem. |
| 418 |
You may want to call |
| 419 |
.B \%noqiflush |
| 420 |
in a signal handler if, |
| 421 |
after the handler exits, |
| 422 |
you want output to continue |
| 423 |
as though the signal had not occurred. |
| 424 |
.\" |
| 425 |
.SS "raw, noraw" |
| 426 |
.B raw |
| 427 |
configures the terminal to read input in |
| 428 |
.IR "raw mode" , |
| 429 |
which is similar to cbreak mode |
| 430 |
(see |
| 431 |
.B \%cbreak |
| 432 |
above) |
| 433 |
except that it furthermore passes through the terminal's configured |
| 434 |
interrupt, |
| 435 |
quit, |
| 436 |
suspend, |
| 437 |
and flow control characters |
| 438 |
uninterpreted to the application, |
| 439 |
instead of generating a signal or acting on I/O flow. |
| 440 |
The behavior of the terminal's \*(``Break\*('' key |
| 441 |
(if any) |
| 442 |
depends on terminal driver configuration parameters that |
| 443 |
.I curses |
| 444 |
does not handle. |
| 445 |
.B \%noraw |
| 446 |
restores the terminal's canonical (\*(``cooked\*('') line discipline. |
| 447 |
.\" |
| 448 |
.SS "timeout, wtimeout" |
| 449 |
.B \%wtimeout |
| 450 |
configures whether a |
| 451 |
.I curses |
| 452 |
input character reading function called on window |
| 453 |
.I win |
| 454 |
uses blocking or non-blocking reads. |
| 455 |
If |
| 456 |
.I delay |
| 457 |
is negative, |
| 458 |
.I curses |
| 459 |
uses a blocking read, |
| 460 |
waiting indefinitely for input. |
| 461 |
If |
| 462 |
.I delay |
| 463 |
is zero, |
| 464 |
the read is non-blocking; |
| 465 |
an input character reading function returns |
| 466 |
.B ERR |
| 467 |
if no input is pending. |
| 468 |
If |
| 469 |
.I delay |
| 470 |
is positive, |
| 471 |
an input character reading function |
| 472 |
blocks for |
| 473 |
.I delay |
| 474 |
milliseconds, |
| 475 |
and returns |
| 476 |
.B ERR |
| 477 |
if the delay elapses and there is still no input pending. |
| 478 |
.B \%timeout |
| 479 |
calls |
| 480 |
.B \%wtimeout |
| 481 |
on |
| 482 |
.BR stdscr "." |
| 483 |
.\" |
| 484 |
.SS typeahead |
| 485 |
Normally, |
| 486 |
a |
| 487 |
.I curses |
| 488 |
library checks the terminal's input file descriptor for activity |
| 489 |
with \fIpoll\fP(2) or \fI\%select\fP(2) |
| 490 |
while updating the screen; |
| 491 |
if it finds any, |
| 492 |
it postpones output |
| 493 |
until the next \fB\%wrefresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES) call, |
| 494 |
allowing faster response to user key strokes. |
| 495 |
The library tests the file descriptor corresponding to the |
| 496 |
.I FILE |
| 497 |
stream pointer passed to \fB\%newterm\fP(3NCURSES) |
| 498 |
(or |
| 499 |
.I stdin |
| 500 |
if \fB\%initscr\fP(3NCURSES) was called), |
| 501 |
for pending input. |
| 502 |
.B \%typeahead |
| 503 |
instructs |
| 504 |
.I curses |
| 505 |
to test file descriptor |
| 506 |
.I fd |
| 507 |
instead. |
| 508 |
An |
| 509 |
.I fd |
| 510 |
of |
| 511 |
.B \-1 |
| 512 |
disables the check. |
| 513 |
.\" |
| 514 |
.SH RETURN VALUE |
| 515 |
.B \%timeout |
| 516 |
and |
| 517 |
.B \%wtimeout |
| 518 |
return no value. |
| 519 |
.PP |
| 520 |
.BR \%cbreak "," |
| 521 |
.BR \%nocbreak "," |
| 522 |
.BR \%echo "," |
| 523 |
.BR \%noecho "," |
| 524 |
.BR \%halfdelay "," |
| 525 |
.BR \%intrflush "," |
| 526 |
.BR \%keypad "," |
| 527 |
.BR \%meta "," |
| 528 |
.BR \%nodelay "," |
| 529 |
.BR \%notimeout "," |
| 530 |
.BR \%nl "," |
| 531 |
.BR \%nonl "," |
| 532 |
.BR \%raw "," |
| 533 |
.BR \%noraw "," |
| 534 |
and |
| 535 |
.B \%typeahead |
| 536 |
return |
| 537 |
.B OK |
| 538 |
on success and |
| 539 |
.B ERR |
| 540 |
on failure. |
| 541 |
.PP |
| 542 |
In |
| 543 |
.IR \%ncurses "," |
| 544 |
the functions in the previous paragraph return |
| 545 |
.B ERR |
| 546 |
if |
| 547 |
.bP |
| 548 |
the library's |
| 549 |
.I \%TERMINAL |
| 550 |
structure for the device has not been initialized with |
| 551 |
\fB\%initscr\fP(3NCURSES), |
| 552 |
\fB\%newterm\fP(3NCURSES), |
| 553 |
or |
| 554 |
\fB\%setupterm\fP(3NCURSES), |
| 555 |
or |
| 556 |
.bP |
| 557 |
.I win |
| 558 |
is a null pointer |
| 559 |
(except with |
| 560 |
.B \%intrflush |
| 561 |
and |
| 562 |
.BR meta "," |
| 563 |
which ignore its value). |
| 564 |
.PP |
| 565 |
Further, |
| 566 |
.B \%halfdelay |
| 567 |
returns |
| 568 |
.B ERR |
| 569 |
if |
| 570 |
.I delay |
| 571 |
is outside the range 1..255. |
| 572 |
.PP |
| 573 |
See section \*(``EXTENSIONS\*('' below for the |
| 574 |
return values of |
| 575 |
.BR is_cbreak "," |
| 576 |
.BR is_echo "," |
| 577 |
.BR is_nl "," |
| 578 |
and |
| 579 |
.BR is_raw "." |
| 580 |
.SH NOTES |
| 581 |
.BR echo "," |
| 582 |
.BR \%noecho "," |
| 583 |
.BR \%halfdelay "," |
| 584 |
.BR \%intrflush "," |
| 585 |
.BR meta "," |
| 586 |
.BR nl "," |
| 587 |
.BR nonl "," |
| 588 |
.BR \%nodelay "," |
| 589 |
.BR \%notimeout "," |
| 590 |
.BR \%noqiflush "," |
| 591 |
.BR \%qiflush "," |
| 592 |
.BR \%timeout "," |
| 593 |
and |
| 594 |
.B \%wtimeout |
| 595 |
may be implemented as macros. |
| 596 |
.PP |
| 597 |
.B \%noraw |
| 598 |
and |
| 599 |
.B \%nocbreak |
| 600 |
follow historical practice in that they attempt to restore |
| 601 |
the terminal's canonical (\*(``cooked\*('') line discipline |
| 602 |
from raw and cbreak, |
| 603 |
respectively. |
| 604 |
Mixing |
| 605 |
.BR \%raw / noraw |
| 606 |
calls with |
| 607 |
.BR \%cbreak / nocbreak |
| 608 |
calls leads to terminal driver control states that are hard to predict |
| 609 |
or understand; |
| 610 |
doing so is not recommended. |
| 611 |
.PP |
| 612 |
.I curses |
| 613 |
documentation uses the terms \*(``delay\*('' and \*(``timeout\*('' |
| 614 |
freely to describe two related but distinct aspects of input handling, |
| 615 |
at the risk of confusing the user. |
| 616 |
The functions |
| 617 |
.BR \%halfdelay "," |
| 618 |
.BR \%nodelay "," |
| 619 |
.BR \%timeout "," |
| 620 |
and |
| 621 |
.B \%wtimeout |
| 622 |
configure whether the input character reading function |
| 623 |
\%(\fBwgetch\fP(3NCURSES) or \fB\%wget_wch\fP(3NCURSES)) |
| 624 |
waits for keyboard input to begin, |
| 625 |
and for how long. |
| 626 |
.B \%keypad |
| 627 |
configures whether that function waits for further input |
| 628 |
if the first character it reads is ESC. |
| 629 |
Calling |
| 630 |
.BR \%notimeout "," |
| 631 |
which has nothing to do with |
| 632 |
.B \%timeout |
| 633 |
or |
| 634 |
.BR \%wtimeout "," |
| 635 |
makes this delay in expectation of further characters |
| 636 |
effectively infinite. |
| 637 |
X/Open Curses affords no means of otherwise configuring |
| 638 |
the length of this second delay, |
| 639 |
but an AIX and |
| 640 |
.I \%ncurses |
| 641 |
extension, |
| 642 |
.BR \%ESCDELAY , |
| 643 |
is available both as an environment variable and a global symbol |
| 644 |
permitting the user and application, |
| 645 |
respectively, |
| 646 |
to do so; |
| 647 |
see \fB\%ncurses\fP(3NCURSES) and \fB\%curses_variables\fP(3NCURSES). |
| 648 |
.SH EXTENSIONS |
| 649 |
.I \%ncurses |
| 650 |
provides four \*(``is_\*('' functions corresponding to |
| 651 |
.BR \%cbreak "," |
| 652 |
.BR echo "," |
| 653 |
.BR nl "," |
| 654 |
and |
| 655 |
.BR raw "," |
| 656 |
permitting their states to be queried by the application. |
| 657 |
.PP |
| 658 |
.TS |
| 659 |
center; |
| 660 |
Lb Lb Lb |
| 661 |
L L L . |
| 662 |
Query Set Reset |
| 663 |
_ |
| 664 |
is_cbreak cbreak nocbreak |
| 665 |
is_echo echo noecho |
| 666 |
is_nl nl nonl |
| 667 |
is_raw raw noraw |
| 668 |
.TE |
| 669 |
.PP |
| 670 |
In each case, |
| 671 |
the function returns |
| 672 |
.TP 5 \" "-1" + 2n tag separation + 1n fudge for typesetters like grops |
| 673 |
.B 1 |
| 674 |
if the option is set, |
| 675 |
.TP |
| 676 |
.B 0 |
| 677 |
if the option is unset, |
| 678 |
or |
| 679 |
.TP |
| 680 |
.B \-1 |
| 681 |
if the library's |
| 682 |
.I \%TERMINAL |
| 683 |
structure for the device has not been initialized. |
| 684 |
.SH PORTABILITY |
| 685 |
Applications employing |
| 686 |
.I \%ncurses |
| 687 |
extensions should condition their use on the visibility of the |
| 688 |
.B \%NCURSES_VERSION |
| 689 |
preprocessor macro. |
| 690 |
.PP |
| 691 |
Except as noted in section \*(``EXTENSIONS\*('' above, |
| 692 |
X/Open Curses Issue\ 4 describes these functions. |
| 693 |
It specifies no error conditions for them. |
| 694 |
.PP |
| 695 |
SVr4 describes a successful return value only as |
| 696 |
\*(``an integer value other than |
| 697 |
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 508 |
| 698 |
.\" It continues "unless otherwise noted in the preceding routine |
| 699 |
.\" descriptions", but no notes otherwise are present; the man page |
| 700 |
.\" discusses getch()'s return value repeatedly, but never those of the |
| 701 |
.\" functions the page ostensibly documents. |
| 702 |
.PP |
| 703 |
.I \%ncurses |
| 704 |
follows X/Open Curses |
| 705 |
and the historical practice of System\ V |
| 706 |
.IR curses "," |
| 707 |
clearing the terminal driver's \*(``echo\*('' flag when initializing the |
| 708 |
screen. |
| 709 |
BSD |
| 710 |
.I curses |
| 711 |
did not, |
| 712 |
but its |
| 713 |
.I raw |
| 714 |
function turned it off as a side effect. |
| 715 |
.\" SGTTY's sg_flags had a "RAW" symbol; termio in SVr1 for the PDP-11 |
| 716 |
.\" did not. |
| 717 |
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/include/curses.h |
| 718 |
.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysv-pdp11_man/a_man/man7/termio.7 |
| 719 |
For best portability, |
| 720 |
call |
| 721 |
.I echo |
| 722 |
or |
| 723 |
.I \%noecho |
| 724 |
explicitly just after initialization, |
| 725 |
even if your program retains the terminal's canonical (\*(``cooked\*('') |
| 726 |
line discipline. |
| 727 |
.PP |
| 728 |
X/Open Curses is ambiguous regarding whether |
| 729 |
.I raw |
| 730 |
should disable the carriage return and line feed translation feature |
| 731 |
controlled by |
| 732 |
.I nl |
| 733 |
and |
| 734 |
.IR \%nonl "." |
| 735 |
BSD |
| 736 |
.I curses |
| 737 |
turned off these translations; |
| 738 |
System\ V |
| 739 |
.I curses |
| 740 |
did not. |
| 741 |
.I \%ncurses |
| 742 |
does so, |
| 743 |
on the assumption that a programmer requesting raw input wants a clean |
| 744 |
(ideally, |
| 745 |
8-bit clean) |
| 746 |
connection that the operating system will not alter. |
| 747 |
.PP |
| 748 |
When |
| 749 |
.B \%keypad |
| 750 |
is first enabled for a window, |
| 751 |
.I \%ncurses |
| 752 |
loads the standard function key string capabilities |
| 753 |
for the terminal type description of its screen; |
| 754 |
see the entries beginning with \*(``key_\*('' in \fB\%terminfo\fP(5). |
| 755 |
If that description includes extended string capabilities, |
| 756 |
produced by the |
| 757 |
.B \-x |
| 758 |
option of \fB\%tic\fP(1), |
| 759 |
for example, |
| 760 |
then |
| 761 |
.I \%ncurses |
| 762 |
also defines keys for the capabilities whose codes begin with |
| 763 |
\*(``k\*(''. |
| 764 |
.I \%ncurses |
| 765 |
generates a numeric key code for each such extended capability; |
| 766 |
depending on previous loads of terminal type descriptions, |
| 767 |
these may differ from one execution of a program to the next. |
| 768 |
\fB\%keyname\fP(3NCURSES) recognizes the generated key codes |
| 769 |
and returns a name beginning with \*(``k\*('' denoting the |
| 770 |
.I \%term\%info |
| 771 |
capability name rather than \*(``KEY_\*('', |
| 772 |
used for |
| 773 |
.I curses |
| 774 |
key names. |
| 775 |
On the other hand, |
| 776 |
an application can use \fB\%define_key\fP(3NCURSES) to bind |
| 777 |
a selected key to a string of the programmer's choice. |
| 778 |
This feature enables an application to check for its presence |
| 779 |
with \fB\%tigetstr\fP(3NCURSES), |
| 780 |
and reassign the numeric key code to match its own needs. |
| 781 |
.PP |
| 782 |
Low-level applications can use \fB\%tigetstr\fP(3NCURSES) to obtain the |
| 783 |
definition of any string capability. |
| 784 |
.I curses |
| 785 |
applications use the input character reading function |
| 786 |
to obtain key codes from input |
| 787 |
and rely upon the order in which the string capabilities are loaded. |
| 788 |
Multiple key capability strings can have the same value, |
| 789 |
but the input character reading function can report only one key code. |
| 790 |
Most |
| 791 |
.I curses |
| 792 |
implementations |
| 793 |
(including |
| 794 |
.IR \%ncurses ) |
| 795 |
load key definitions in the order |
| 796 |
they appear in the |
| 797 |
.B \%strfnames |
| 798 |
array of string capability names; |
| 799 |
see \fB\%terminfo_variables\fP(3NCURSES). |
| 800 |
.\" ncurses/tinfo/parse_entry.c:lookup_fullname, I think --GBR |
| 801 |
The last capability read using a particular definition determines the |
| 802 |
key code to be reported. |
| 803 |
In |
| 804 |
.IR \%ncurses , |
| 805 |
extended capabilities can be interpreted as key definitions. |
| 806 |
The library loads these after its built-in definitions, |
| 807 |
and if an extended capability's value |
| 808 |
is the same as one previously loaded, |
| 809 |
the library uses the later definition. |
| 810 |
.SH HISTORY |
| 811 |
4BSD (1980) |
| 812 |
introduced |
| 813 |
.IR echo "," |
| 814 |
.IR \%noecho "," |
| 815 |
.IR nl "," |
| 816 |
.IR \%nonl "," |
| 817 |
.IR raw "," |
| 818 |
and |
| 819 |
.IR \%noraw "." \" also crmod and nocrmod, never standardized |
| 820 |
.PP |
| 821 |
SVr2 (1984) |
| 822 |
featured a new terminal driver, |
| 823 |
extending the |
| 824 |
.I curses |
| 825 |
API to support it with |
| 826 |
.IR \%cbreak "," |
| 827 |
.IR \%nocbreak "," |
| 828 |
.IR \%intrflush "," |
| 829 |
.IR \%keypad "," |
| 830 |
.IR \%meta "," |
| 831 |
.IR \%nodelay "," |
| 832 |
and |
| 833 |
.IR \%typeahead "." |
| 834 |
.PP |
| 835 |
SVr3 (1987) |
| 836 |
added |
| 837 |
.IR \%halfdelay "," |
| 838 |
.IR \%notimeout "," |
| 839 |
and |
| 840 |
.IR \%wtimeout "." |
| 841 |
.I \%qiflush |
| 842 |
and |
| 843 |
.I \%noqiflush |
| 844 |
appeared in SVr3.1 (1987), |
| 845 |
at which point |
| 846 |
.I \%intrflush |
| 847 |
became a wrapper for either of these functions, |
| 848 |
depending on the value of its Boolean argument. |
| 849 |
SVr3.1 also added |
| 850 |
.IR \%timeout "." |
| 851 |
.PP |
| 852 |
.I \%ncurses |
| 853 |
6.5 (2024) introduced |
| 854 |
.IR is_cbreak "," |
| 855 |
.IR is_echo "," |
| 856 |
.IR is_nl "," |
| 857 |
and |
| 858 |
.IR is_raw "." |
| 859 |
.PP |
| 860 |
Formerly, |
| 861 |
.I \%ncurses |
| 862 |
used |
| 863 |
.I \%nl |
| 864 |
and |
| 865 |
.I \%nonl |
| 866 |
to control the conversion of newlines to carriage return/line feed |
| 867 |
on output as well as input. |
| 868 |
X/Open Curses documents the use of these functions only for input. |
| 869 |
This difference arose from converting the |
| 870 |
.I \%pcurses |
| 871 |
source (1986), |
| 872 |
which used |
| 873 |
\fI\%ioctl\fP(2) calls and the |
| 874 |
.I \%sgttyb |
| 875 |
structure, |
| 876 |
to |
| 877 |
.I \%termios |
| 878 |
(the POSIX terminal API). |
| 879 |
In the former, |
| 880 |
both input and output conversions were controlled via a single option |
| 881 |
\%\*(``CRMOD\*('', |
| 882 |
while the latter separates these features. |
| 883 |
Because that conversion interferes with output optimization, |
| 884 |
.I \%ncurses |
| 885 |
6.2 (2020) amended |
| 886 |
.I \%nl |
| 887 |
and |
| 888 |
.I \%nonl |
| 889 |
to eliminate their effect on output. |
| 890 |
.SH SEE ALSO |
| 891 |
\fB\%ncurses\fP(3NCURSES), |
| 892 |
\fB\%getch\fP(3NCURSES), |
| 893 |
\fB\%initscr\fP(3NCURSES), |
| 894 |
\fB\%util\fP(3NCURSES), |
| 895 |
\fB\%define_key\fP(3NCURSES), |
| 896 |
\fB\%termios\fP(3), |
| 897 |
\fB\%terminfo_variables\fP(3NCURSES) |