man/curs_inopts.3x

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2018-2022,2023 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.60 2023/12/23 16:36:18 tom Exp $
  32 .TH curs_inopts 3X 2023-12-23 "ncurses 6.4" "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 .SH NAME
  44 \fB\%cbreak\fP,
  45 \fB\%echo\fP,
  46 \fB\%halfdelay\fP,
  47 \fB\%intrflush\fP,
  48 \fB\%is_cbreak\fP,
  49 \fB\%is_echo\fP,
  50 \fB\%is_nl\fP,
  51 \fB\%is_raw\fP,
  52 \fB\%keypad\fP,
  53 \fB\%meta\fP,
  54 \fB\%nl\fP,
  55 \fB\%nocbreak\fP,
  56 \fB\%nodelay\fP,
  57 \fB\%noecho\fP,
  58 \fB\%nonl\fP,
  59 \fB\%noqiflush\fP,
  60 \fB\%noraw\fP,
  61 \fB\%notimeout\fP,
  62 \fB\%qiflush\fP,
  63 \fB\%raw\fP,
  64 \fB\%timeout\fP,
  65 \fB\%wtimeout\fP,
  66 \fB\%typeahead\fP \-
  67 get and set \fIcurses\fR terminal input options
  68 .SH SYNOPSIS
  69 .nf
  70 \fB#include <curses.h>
  71 .PP
  72 \fBint cbreak(void);
  73 \fBint nocbreak(void);
  74 .PP
  75 \fBint echo(void);
  76 \fBint noecho(void);
  77 .PP
  78 \fBint intrflush(WINDOW *\fIwin\fP, bool \fIbf\fP);
  79 \fBint keypad(WINDOW *\fIwin\fP, bool \fIbf\fP);
  80 \fBint meta(WINDOW *\fIwin\fP, bool \fIbf\fP);
  81 \fBint nodelay(WINDOW *\fIwin\fP, bool \fIbf\fP);
  82 \fBint notimeout(WINDOW *\fIwin\fP, bool \fIbf\fP);
  83 .PP
  84 \fBint nl(void);
  85 \fBint nonl(void);
  86 .PP
  87 \fBint raw(void);
  88 \fBint noraw(void);
  89 .PP
  90 \fBvoid qiflush(void);
  91 \fBvoid noqiflush(void);
  92 .PP
  93 \fBint halfdelay(int \fItenths\fP);
  94 \fBvoid timeout(int \fIdelay\fP);
  95 \fBvoid wtimeout(WINDOW *\fIwin\fP, int \fIdelay\fP);
  96 .PP
  97 \fBint typeahead(int \fIfd\fP);
  98 .PP
  99 \fI/* extensions */
 100 \fBint is_cbreak(void);
 101 \fBint is_echo(void);
 102 \fBint is_nl(void);
 103 \fBint is_raw(void);
 104 .fi
 105 .SH DESCRIPTION
 106 .I \%ncurses
 107 provides several functions that let an application change the way input
 108 from the terminal is handled.
 109 Some are global,
 110 applying to all windows.
 111 Others apply only to a specific window.
 112 Window-specific settings are not automatically applied to new or derived
 113 windows.
 114 An application must apply these to each window if the same behavior is
 115 desired.
 116 .\"
 117 .SS "cbreak, nocbreak"
 118 Normally,
 119 the terminal driver buffers typed characters until a newline or carriage
 120 return is typed.
 121 The \fB\%cbreak\fP routine disables line buffering and
 122 erase/kill character-processing
 123 (interrupt and flow control characters are unaffected),
 124 making characters typed by the user immediately available to the
 125 program.
 126 The \fB\%nocbreak\fP routine returns the terminal to normal (cooked)
 127 mode.
 128 .PP
 129 Initially the terminal may or may not be in \fB\%cbreak\fP mode,
 130 as the mode is inherited;
 131 therefore,
 132 a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly.
 133 Most interactive programs using
 134 .I curses
 135 set the \fB\%cbreak\fP mode.
 136 Note that \fB\%cbreak\fP overrides \fBraw\fP.
 137 [See \fB\%curs_getch\fP(3X) for a discussion of how these routines
 138 interact with \fBecho\fP and \fB\%noecho\fP.]
 139 .\"
 140 .SS "echo, noecho"
 141 The \fBecho\fP and \fB\%noecho\fP routines control whether characters
 142 typed by the user are echoed by \fB\%getch\fP(3X) as they are typed.
 143 Echoing by the terminal driver is always disabled,
 144 but initially \fB\%getch\fP is in echo mode,
 145 so characters typed are echoed.
 146 Authors of most interactive programs prefer to do
 147 their own echoing in a controlled area of the screen,
 148 or not to echo at all,
 149 so they disable echoing by calling \fB\%noecho\fP.
 150 [See \fB\%curs_getch\fP(3X) for a
 151 discussion of how these routines interact with \fB\%cbreak\fP and
 152 \fB\%nocbreak\fP.]
 153 .\"
 154 .SS halfdelay
 155 The \fB\%halfdelay\fP routine is used for half-delay mode,
 156 which is similar to \fB\%cbreak\fP mode in that characters typed by the
 157 user are immediately available to the program.
 158 However,
 159 after blocking for \fItenths\fP tenths of seconds,
 160 \fBERR\fP is returned if nothing has been typed.
 161 The value of \fItenths\fP must be a number between 1 and 255.
 162 Use \fB\%nocbreak\fP to leave half-delay mode.
 163 .\"
 164 .SS intrflush
 165 If the \fB\%intrflush\fP option is enabled
 166 .RI ( bf
 167 is
 168 .BR TRUE ),
 169 and an interrupt key is pressed on the keyboard
 170 (interrupt,
 171 break,
 172 quit),
 173 all output in the terminal driver queue is flushed,
 174 giving the effect of faster response to the interrupt,
 175 but causing
 176 .I curses
 177 to have the wrong idea of what is on the screen.
 178 Disabling the option
 179 .RI ( bf
 180 is
 181 .BR FALSE ),
 182 prevents the flush.
 183 The default for the option is inherited from the terminal driver
 184 settings.
 185 The
 186 .I win
 187 argument is ignored.
 188 .\"
 189 .SS keypad
 190 The \fB\%keypad\fP option enables the keypad of the user's terminal.
 191 If
 192 enabled
 193 .RI ( bf
 194 is
 195 .BR TRUE ),
 196 the user can press a function key
 197 (such as an arrow key)
 198 and \fB\%wgetch\fP(3X) returns a single value representing the function
 199 key,
 200 as in \fB\%KEY_LEFT\fP.
 201 If disabled
 202 (\fIbf\fP is \fBFALSE\fP),
 203 .I curses
 204 does not treat function keys specially and the program has to interpret
 205 the escape sequences itself.
 206 If the keypad in the terminal can be turned on
 207 (made to transmit)
 208 and off
 209 (made to work locally),
 210 turning on this option causes the terminal keypad to be turned on when
 211 \fB\%wgetch\fP(3X) is called.
 212 The default value for keypad is \fBFALSE\fP.
 213 .\"
 214 .SS meta
 215 Initially,
 216 whether the terminal returns 7 or 8 significant bits on input depends on
 217 the control mode of the terminal driver [see \fI\%termios\fP(3)].
 218 To force 8 bits to be returned,
 219 invoke
 220 \fBmeta\fP(\fIwin\fP, \fBTRUE\fP);
 221 this is equivalent,
 222 under POSIX,
 223 to setting the CS8 flag on the terminal.
 224 To force 7 bits to be returned,
 225 invoke
 226 \fBmeta\fP(\fIwin\fP, \fBFALSE\fP);
 227 this is equivalent,
 228 under POSIX,
 229 to setting the CS7 flag on the terminal.
 230 The window argument,
 231 .I win,
 232 is always ignored.
 233 If the terminfo capabilities
 234 \fBsmm\fP (meta_on) and
 235 \fBrmm\fP (meta_off) are defined for the terminal,
 236 \fBsmm\fP is sent to the terminal when
 237 \fBmeta\fP(\fIwin\fP, \fBTRUE\fP)
 238 is called and \fBrmm\fP is sent when
 239 \fBmeta\fP(\fIwin\fP, \fBFALSE\fP) is called.
 240 .\"
 241 .SS "nl, nonl"
 242 The \fBnl\fP and \fBnonl\fP routines control whether the underlying
 243 display device translates the return key into newline on input.
 244 .\"
 245 .SS nodelay
 246 The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking
 247 call.
 248 If no input is ready,
 249 \fB\%getch\fP returns \fBERR\fP.
 250 If disabled
 251 .RI ( bf
 252 is
 253 .BR FALSE ),
 254 \fB\%getch\fP waits until a key is pressed.
 255 .SS notimeout
 256 When interpreting an escape sequence,
 257 \fB\%wgetch\fP(3X) sets a timer
 258 while waiting for the next character.
 259 If
 260 \fB\%notimeout(\fIwin\fR, \fBTRUE\fP)
 261 is called,
 262 then \fB\%wgetch\fP does not set a timer.
 263 The purpose of the timeout is to distinguish sequences produced by a
 264 function key from those typed by a user.
 265 .\"
 266 .SS "raw, noraw"
 267 The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out
 268 of raw mode.
 269 Raw mode is similar to \fB\%cbreak\fP mode,
 270 in that characters typed are immediately passed through to the user
 271 program.
 272 The differences are that in raw mode,
 273 the interrupt,
 274 quit,
 275 suspend,
 276 and flow control characters are all
 277 passed through uninterpreted,
 278 instead of generating a signal.
 279 The behavior of the BREAK key depends on other bits in the terminal
 280 driver that are not set by
 281 .I curses.
 282 .\"
 283 .SS "qiflush, nqiflush"
 284 When the \fB\%noqiflush\fP routine is used,
 285 normal flush of input and output queues associated with the \fBINTR\fP,
 286 \fBQUIT\fP and \fBSUSP\fP characters will not be done
 287 [see \fB\%termios\fP(3)].
 288 When
 289 \fB\%qiflush\fP is called,
 290 the queues will be flushed when these control characters are read.
 291 You may want to call \fB\%noqiflush\fP in a signal handler if you want
 292 output to continue as though the interrupt had not occurred,
 293 after the handler exits.
 294 .\"
 295 .SS "timeout, wtimeout"
 296 The \fB\%timeout\fP and \fB\%wtimeout\fP routines set blocking or
 297 non-blocking read for a given window.
 298 If \fIdelay\fP is negative,
 299 a blocking read is used
 300 (i.e.,
 301 waits indefinitely for input).
 302 If \fIdelay\fP is zero,
 303 then a non-blocking read is used
 304 (i.e.,
 305 .I read
 306 returns \fBERR\fP if no input is waiting).
 307 If
 308 \fIdelay\fP is positive,
 309 then
 310 .I read
 311 blocks for \fIdelay\fP milliseconds,
 312 and returns \fBERR\fP if there is still no input.
 313 Hence,
 314 these routines provide the same functionality as \fB\%nodelay\fP,
 315 plus the additional capability of being able to block for only
 316 \fIdelay\fP milliseconds
 317 (where \fIdelay\fP is positive).
 318 .\"
 319 .SS typeahead
 320 .I curses
 321 does \*(``line-breakout optimization\*('' by looking for typeahead
 322 periodically while updating the screen.
 323 If input is found,
 324 and it is coming from a terminal,
 325 the current update is postponed until
 326 \fB\%refresh\fP(3X) or \fB\%doupdate\fP is called again.
 327 This allows faster response to commands typed in advance.
 328 Normally,
 329 the input
 330 .I FILE
 331 pointer passed to \fB\%newterm\fP,
 332 or \fBstdin\fP in the case that \fB\%initscr\fP was used,
 333 will be used to do this typeahead checking.
 334 The \fB\%typeahead\fP routine specifies that the file descriptor
 335 \fIfd\fP is to be used to check for typeahead instead.
 336 If \fIfd\fP is
 337 \-1,
 338 then no typeahead checking is done.
 339 .\"
 340 .SH RETURN VALUE
 341 All routines that return an integer return \fBERR\fP upon failure and
 342 \fBOK\fP
 343 (SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('')
 344 upon successful completion,
 345 unless otherwise noted in the preceding routine descriptions.
 346 .PP
 347 X/Open does not define any error conditions.
 348 In this implementation,
 349 functions with a window parameter will return an error if it is null.
 350 Any function will also return an error if the terminal was not
 351 initialized.
 352 Also,
 353 .RS 3
 354 .TP 5
 355 \fB\%halfdelay\fP
 356 returns an error
 357 if its parameter is outside the range 1..255.
 358 .RE
 359 .SH NOTES
 360 \fBecho\fP,
 361 \fB\%noecho\fP,
 362 \fB\%halfdelay\fP,
 363 \fB\%intrflush\fP,
 364 \fBmeta\fP,
 365 \fBnl\fP,
 366 \fBnonl\fP,
 367 \fB\%nodelay\fP,
 368 \fB\%notimeout\fP,
 369 \fB\%noqiflush\fP,
 370 \fB\%qiflush\fP,
 371 \fB\%timeout\fP,
 372 and
 373 \fB\%wtimeout\fP
 374 may be implemented as macros.
 375 .PP
 376 \fB\%noraw\fP and \fB\%nocbreak\fP follow historical practice in that
 377 they attempt to restore normal (\*(``cooked\*('') mode
 378 from raw and cbreak modes respectively.
 379 Mixing \fBraw\fP/\fB\%noraw\fP and \fB\%cbreak\fP/\fB\%nocbreak\fP calls
 380 leads to terminal driver control states that are hard to predict or
 381 understand;
 382 doing so is not recommended.
 383 .SH EXTENSIONS
 384 .I \%ncurses
 385 provides four \*(``is_\*('' functions that may be used to detect if the
 386 corresponding flags were set or reset.
 387 .PP
 388 .TS
 389 center;
 390 Lb Lb Lb
 391 L  L  L .
 392 Query   Set     Reset
 393 _
 394 is_cbreak       cbreak  nocbreak
 395 is_echo echo    noecho
 396 is_nl   nl      nonl
 397 is_raw  raw     noraw
 398 .TE
 399 .PP
 400 In each case,
 401 the function returns
 402 .TP 4 \" "-1" + 2n
 403 1
 404 if the flag is set,
 405 .TP
 406 0
 407 if the flag is reset,
 408 or
 409 .TP
 410 \-1
 411 if the library is not initialized.
 412 .PP
 413 They were designed for
 414 \fB\%ncurses\fP(3X),
 415 and are not found in SVr4
 416 .IR curses ,
 417 4.4BSD
 418 .IR curses ,
 419 or any other previous
 420 .I curses
 421 implementation.
 422 .SH PORTABILITY
 423 Applications employing
 424 .I \%ncurses
 425 extensions should condition their use on the visibility of the
 426 .B \%NCURSES_VERSION
 427 preprocessor macro.
 428 .PP
 429 Except as noted in section \*(``EXTENSIONS\*('' above,
 430 X/Open Curses, Issue 4, Version 2 describes these functions.
 431 .PP
 432 .I \%ncurses
 433 follows X/Open Curses
 434 and the historical practice of AT&T
 435 .I curses
 436 implementations,
 437 in that the echo bit is cleared when
 438 .I curses
 439 initializes the terminal state.
 440 BSD
 441 .I curses
 442 differed from this slightly;
 443 it left the echo bit on at initialization,
 444 but the BSD \fBraw\fP call turned it off as a side effect.
 445 For best portability,
 446 set \fBecho\fP or \fB\%noecho\fP explicitly just after initialization,
 447 even if your program remains in cooked mode.
 448 .PP
 449 X/Open Curses is ambiguous regarding whether \fBraw\fP should disable
 450 the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP.
 451 BSD
 452 .I curses
 453 did turn off these translations;
 454 AT&T
 455 .I curses
 456 (at least as late as SVr1)
 457 did not.
 458 .I \%ncurses
 459 does so,
 460 on the assumption that a programmer requesting raw input wants a clean
 461 (ideally,
 462 8-bit clean)
 463 connection that the operating system will not alter.
 464 .PP
 465 When \fB\%keypad\fP is first enabled,
 466 .I \%ncurses
 467 loads the key definitions for the current terminal description.
 468 If the terminal description includes extended string capabilities,
 469 e.g.,
 470 from using the
 471 .B \-x
 472 option of \fB\%@TIC@\fP,
 473 then
 474 .I \%ncurses
 475 also defines keys for the capabilities whose names begin with
 476 \*(``k\*(''.
 477 The corresponding keycodes are generated and
 478 (depending on previous loads of terminal descriptions)
 479 may differ from one execution of a program to the next.
 480 The generated keycodes are recognized by the \fB\%keyname\fP(3X)
 481 function
 482 (which will then return a name beginning with \*(``k\*('' denoting the
 483 terminfo capability name rather than \*(``K\*('',
 484 used for
 485 .I curses
 486 key names).
 487 On the other hand,
 488 an application can use \fB\%define_key\fP(3X) to establish
 489 a specific keycode for a given string.
 490 This makes it possible for an application to check for an extended
 491 capability's presence with \fB\%tigetstr\fP,
 492 and reassign the keycode to match its own needs.
 493 .PP
 494 Low-level applications can use \fB\%tigetstr\fP to obtain the definition
 495 of any particular string capability.
 496 Higher-level applications which use the
 497 .I curses
 498 \fB\%wgetch\fP and similar functions to return keycodes rely upon the
 499 order in which the strings are loaded.
 500 If more than one key definition has the same string value,
 501 then \fB\%wgetch\fP can return only one keycode.
 502 Most
 503 .I curses
 504 implementations
 505 (including
 506 .IR \%ncurses )
 507 load key definitions in the order
 508 defined by the array of string capability names.
 509 The last key to be loaded determines the keycode which will be returned.
 510 In
 511 .I \%ncurses,
 512 you may also have extended capabilities interpreted as key definitions.
 513 These are loaded after the predefined keys,
 514 and if a capability's value is the same as a previously-loaded
 515 key definition,
 516 the later definition is the one used.
 517 .SH SEE ALSO
 518 \fB\%curses\fP(3X),
 519 \fB\%curs_getch\fP(3X),
 520 \fB\%curs_initscr\fP(3X),
 521 \fB\%curs_util\fP(3X),
 522 \fB\%define_key\fP(3X),
 523 \fB\%termios\fP(3)