X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_inopts.3x;h=e0ba270d65a0b2c46a6a75fdc668a68f11ba8f21;hb=88595a127ec2e56af0875eb04e0f2396d6d121c5;hp=372010bc337385d1ed27fbaf7a0529c19860051e;hpb=beb0f0c6911096ee19815bdf2601c4317d80341f;p=ncurses.git diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index 372010bc..e0ba270d 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2010,2012 Free Software Foundation, Inc. * +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,182 +27,262 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.17 2012/04/28 19:09:15 tom Exp $ +.\" $Id: curs_inopts.3x,v 1.36 2022/02/12 20:07:29 tom Exp $ .TH curs_inopts 3X "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' .na .hy 0 .SH NAME -\fBcbreak\fR, -\fBnocbreak\fR, -\fBecho\fR, -\fBnoecho\fR, -\fBhalfdelay\fR, -\fBintrflush\fR, -\fBkeypad\fR, -\fBmeta\fR, -\fBnodelay\fR, -\fBnotimeout\fR, -\fBraw\fR, -\fBnoraw\fR, -\fBnoqiflush\fR, -\fBqiflush\fR, -\fBtimeout\fR, -\fBwtimeout\fR, -\fBtypeahead\fR \- \fBcurses\fR input options +\fBcbreak\fP, +\fBnocbreak\fP, +\fBecho\fP, +\fBnoecho\fP, +\fBhalfdelay\fP, +\fBintrflush\fP, +\fBkeypad\fP, +\fBmeta\fP, +\fBnl\fP, +\fBnonl\fP, +\fBnodelay\fP, +\fBnotimeout\fP, +\fBraw\fP, +\fBnoraw\fP, +\fBqiflush\fP, +\fBnoqiflush\fP, +\fBtimeout\fP, +\fBwtimeout\fP, +\fBtypeahead\fP \- \fBcurses\fP input options .ad .hy .SH SYNOPSIS -\fB#include \fR +\fB#include \fP .PP -\fBint cbreak(void);\fR +\fBint cbreak(void);\fP .br -\fBint nocbreak(void);\fR +\fBint nocbreak(void);\fP +.sp +\fBint echo(void);\fP .br -\fBint echo(void);\fR +\fBint noecho(void);\fP +.sp +\fBint intrflush(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint noecho(void);\fR +\fBint keypad(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint halfdelay(int tenths);\fR +\fBint meta(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint intrflush(WINDOW *win, bool bf);\fR +\fBint nodelay(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR .br -\fBint keypad(WINDOW *win, bool bf);\fR +\fBint notimeout(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +.sp +\fBint nl(void);\fP .br -\fBint meta(WINDOW *win, bool bf);\fR +\fBint nonl(void);\fP +.sp +\fBint raw(void);\fP .br -\fBint nodelay(WINDOW *win, bool bf);\fR +\fBint noraw(void);\fP +.sp +\fBvoid qiflush(void);\fP .br -\fBint raw(void);\fR +\fBvoid noqiflush(void);\fP +.sp +\fBint halfdelay(int \fItenths\fB);\fR .br -\fBint noraw(void);\fR +\fBvoid timeout(int \fIdelay\fB);\fR .br -\fBvoid noqiflush(void);\fR -.br -\fBvoid qiflush(void);\fR -.br -\fBint notimeout(WINDOW *win, bool bf);\fR -.br -\fBvoid timeout(int delay);\fR -.br -\fBvoid wtimeout(WINDOW *win, int delay);\fR -.br -\fBint typeahead(int fd);\fR +\fBvoid wtimeout(WINDOW *\fIwin\fB, int \fIdelay\fB);\fR +.sp +\fBint typeahead(int \fIfd\fB);\fR .br .SH DESCRIPTION +The \fBncurses\fP library provides several functions which let an application +change the way input from the terminal is handled. +Some are global, applying to all windows. +Others apply only to a specific window. +Window-specific settings are not automatically applied to new or derived +windows. +An application must apply these to each window, if the same behavior +is needed. +.\" +.SS cbreak/nocbreak Normally, the tty driver buffers typed characters until a newline or carriage -return is typed. The \fBcbreak\fR routine disables line buffering and +return is typed. +The \fBcbreak\fP routine disables line buffering and erase/kill character-processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the -program. The \fBnocbreak\fR routine returns the terminal to normal (cooked) +program. +The \fBnocbreak\fP routine returns the terminal to normal (cooked) mode. .PP -Initially the terminal may or may not be in \fBcbreak\fR mode, as the mode is -inherited; therefore, a program should call \fBcbreak\fR or \fBnocbreak\fR -explicitly. Most interactive programs using \fBcurses\fR set the \fBcbreak\fR -mode. Note that \fBcbreak\fR overrides \fBraw\fR. -[See \fBcurs_getch\fR(3X) for a -discussion of how these routines interact with \fBecho\fR and \fBnoecho\fR.] +Initially the terminal may or may not be in \fBcbreak\fP mode, as the mode is +inherited; therefore, a program should call \fBcbreak\fP or \fBnocbreak\fP +explicitly. +Most interactive programs using \fBcurses\fP set the \fBcbreak\fP +mode. +Note that \fBcbreak\fP overrides \fBraw\fP. +[See \fBcurs_getch\fP(3X) for a +discussion of how these routines interact with \fBecho\fP and \fBnoecho\fP.] +.\" +.SS echo/noecho .PP -The \fBecho\fR and \fBnoecho\fR routines control whether characters typed by -the user are echoed by \fBgetch\fR as they are typed. Echoing by the tty -driver is always disabled, but initially \fBgetch\fR is in echo mode, so -characters typed are echoed. Authors of most interactive programs prefer to do +The \fBecho\fP and \fBnoecho\fP routines control whether characters typed by +the user are echoed by \fBgetch\fP(3X) as they are typed. +Echoing by the tty +driver is always disabled, but initially \fBgetch\fP is in echo mode, so +characters typed are echoed. +Authors of most interactive programs prefer to do their own echoing in a controlled area of the screen, or not to echo at all, so -they disable echoing by calling \fBnoecho\fR. -[See \fBcurs_getch\fR(3X) for a -discussion of how these routines interact with \fBcbreak\fR and -\fBnocbreak\fR.] +they disable echoing by calling \fBnoecho\fP. +[See \fBcurs_getch\fP(3X) for a +discussion of how these routines interact with \fBcbreak\fP and +\fBnocbreak\fP.] +.\" +.SS halfdelay .PP -The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to -\fBcbreak\fR mode in that characters typed by the user are immediately -available to the program. However, after blocking for \fItenths\fR tenths of -seconds, ERR is returned if nothing has been typed. The value of \fBtenths\fR -must be a number between 1 and 255. Use \fBnocbreak\fR to leave half-delay +The \fBhalfdelay\fP routine is used for half-delay mode, which is similar to +\fBcbreak\fP mode in that characters typed by the user are immediately +available to the program. +However, after blocking for \fItenths\fP tenths of +seconds, \fBERR\fP is returned if nothing has been typed. +The value of \fItenths\fP +must be a number between 1 and 255. +Use \fBnocbreak\fP to leave half-delay mode. +.\" +.SS intrflush .PP -If the \fBintrflush\fR option is enabled, (\fIbf\fR is \fBTRUE\fR), when an -interrupt key is pressed on the keyboard (interrupt, break, quit) all output in +If the \fBintrflush\fP option is enabled (\fIbf\fP is \fBTRUE\fP), and an +interrupt key is pressed on the keyboard (interrupt, break, quit), all output in the tty driver queue will be flushed, giving the effect of faster response to -the interrupt, but causing \fBcurses\fR to have the wrong idea of what is on -the screen. Disabling (\fIbf\fR is \fBFALSE\fR), the option prevents the -flush. The default for the option is inherited from the tty driver settings. +the interrupt, but causing \fBcurses\fP to have the wrong idea of what is on +the screen. +Disabling the option (\fIbf\fP is \fBFALSE\fP) prevents the +flush. +The default for the option is inherited from the tty driver settings. The window argument is ignored. +.\" +.SS keypad .PP -The \fBkeypad\fR option enables the keypad of the user's terminal. If -enabled (\fIbf\fR is \fBTRUE\fR), the user can press a function key -(such as an arrow key) and \fBwgetch\fR returns a single value -representing the function key, as in \fBKEY_LEFT\fR. If disabled -(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR does not treat function keys +The \fBkeypad\fP option enables the keypad of the user's terminal. +If +enabled (\fIbf\fP is \fBTRUE\fP), the user can press a function key +(such as an arrow key) and \fBwgetch\fP(3X) returns a single value +representing the function key, as in \fBKEY_LEFT\fP. +If disabled +(\fIbf\fP is \fBFALSE\fP), \fBcurses\fP does not treat function keys specially and the program has to interpret the escape sequences -itself. If the keypad in the terminal can be turned on (made to +itself. +If the keypad in the terminal can be turned on (made to transmit) and off (made to work locally), turning on this option -causes the terminal keypad to be turned on when \fBwgetch\fR is -called. The default value for keypad is false. +causes the terminal keypad to be turned on when \fBwgetch\fP(3X) is +called. +The default value for keypad is \fBFALSE\fP. +.\" +.SS meta .PP Initially, whether the terminal returns 7 or 8 significant bits on -input depends on the control mode of the tty driver [see termio(7)]. -To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR, -\fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag -on the terminal. To force 7 bits to be returned, invoke -\fBmeta\fR(\fIwin\fR, \fBFALSE\fR); this is equivalent, under POSIX, -to setting the CS7 flag on the terminal. The window argument, -\fIwin\fR, is always ignored. If the terminfo capabilities \fBsmm\fR -(meta_on) and \fBrmm\fR (meta_off) are defined for the terminal, -\fBsmm\fR is sent to the terminal when \fBmeta\fR(\fIwin\fR, -\fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR, -\fBFALSE\fR) is called. +input depends on the control mode of the tty driver [see \fBtermios\fP(3)]. +To force 8 bits to be returned, invoke \fBmeta\fP(\fIwin\fP, +\fBTRUE\fP); this is equivalent, under POSIX, to setting the CS8 flag +on the terminal. +To force 7 bits to be returned, invoke +\fBmeta\fP(\fIwin\fP, \fBFALSE\fP); this is equivalent, under POSIX, +to setting the CS7 flag on the terminal. +The window argument, +\fIwin\fP, is always ignored. +If the terminfo capabilities \fBsmm\fP +(meta_on) and \fBrmm\fP (meta_off) are defined for the terminal, +\fBsmm\fP is sent to the terminal when \fBmeta\fP(\fIwin\fP, +\fBTRUE\fP) is called and \fBrmm\fP is sent when \fBmeta\fP(\fIwin\fP, +\fBFALSE\fP) is called. +.\" +.SS nl/nonl +.PP +The \fBnl\fP and \fBnonl\fP routines control whether the underlying display +device translates the return key into newline on input. +.\" +.SS nodelay .PP -The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call. -If no input is ready, \fBgetch\fR returns \fBERR\fR. If disabled -(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed. +The \fBnodelay\fP option causes \fBgetch\fP to be a non-blocking call. +If no input is ready, \fBgetch\fP returns \fBERR\fP. +If disabled +(\fIbf\fP is \fBFALSE\fP), \fBgetch\fP waits until a key is pressed. +.SS notimeout .PP -While interpreting an input escape sequence, \fBwgetch\fR sets a timer -while waiting for the next character. If \fBnotimeout(\fR\fIwin\fR, -\fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer. The +When interpreting an escape sequence, \fBwgetch\fP(3X) sets a timer +while waiting for the next character. +If \fBnotimeout(\fIwin\fR, +\fBTRUE\fP) is called, then \fBwgetch\fP does not set a timer. +The purpose of the timeout is to differentiate between sequences received from a function key and those typed by a user. +.\" +.SS raw/noraw .PP -The \fBraw\fR and \fBnoraw\fR routines place the terminal into or out of raw -mode. Raw mode is similar to \fBcbreak\fR mode, in that characters typed are -immediately passed through to the user program. The differences are that in +The \fBraw\fP and \fBnoraw\fP routines place the terminal into or out of raw +mode. +Raw mode is similar to \fBcbreak\fP mode, in that characters typed are +immediately passed through to the user program. +The differences are that in raw mode, the interrupt, quit, suspend, and flow control characters are all -passed through uninterpreted, instead of generating a signal. The behavior of +passed through uninterpreted, instead of generating a signal. +The behavior of the BREAK key depends on other bits in the tty driver that are not set by -\fBcurses\fR. +\fBcurses\fP. +.\" +.SS qiflush/noqiflush .PP -When the \fBnoqiflush\fR routine is used, normal flush of input and -output queues associated with the \fBINTR\fR, \fBQUIT\fR and -\fBSUSP\fR characters will not be done [see termio(7)]. When -\fBqiflush\fR is called, the queues will be flushed when these control -characters are read. You may want to call \fBnoqiflush()\fR in a signal +When the \fBnoqiflush\fP routine is used, normal flush of input and +output queues associated with the \fBINTR\fP, \fBQUIT\fP and +\fBSUSP\fP characters will not be done [see \fBtermios\fP(3)]. +When +\fBqiflush\fP is called, the queues will be flushed when these control +characters are read. +You may want to call \fBnoqiflush\fP in a signal handler if you want output to continue as though the interrupt had not occurred, after the handler exits. +.\" +.SS timeout/wtimeout .PP -The \fBtimeout\fR and \fBwtimeout\fR routines set blocking or -non-blocking read for a given window. If \fIdelay\fR is negative, +The \fBtimeout\fP and \fBwtimeout\fP routines set blocking or +non-blocking read for a given window. +If \fIdelay\fP is negative, blocking read is used (i.e., waits indefinitely for -input). If \fIdelay\fR is zero, then non-blocking read is used -(i.e., read returns \fBERR\fR if no input is waiting). If -\fIdelay\fR is positive, then read blocks for \fIdelay\fR -milliseconds, and returns \fBERR\fR if there is still no input. -Hence, these routines provide the same functionality as \fBnodelay\fR, +input). +If \fIdelay\fP is zero, then non-blocking read is used +(i.e., read returns \fBERR\fP if no input is waiting). +If +\fIdelay\fP is positive, then read blocks for \fIdelay\fP +milliseconds, and returns \fBERR\fP if there is still no input. +Hence, these routines provide the same functionality as \fBnodelay\fP, plus the additional capability of being able to block for only -\fIdelay\fR milliseconds (where \fIdelay\fR is positive). +\fIdelay\fP milliseconds (where \fIdelay\fP is positive). +.\" +.SS typeahead .PP -The \fBcurses\fR library does ``line-breakout optimization'' by looking for -typeahead periodically while updating the screen. If input is found, -and it is coming from a tty, the current update is postponed until -\fBrefresh\fR or \fBdoupdate\fR is called again. This allows faster -response to commands typed in advance. Normally, the input FILE -pointer passed to \fBnewterm\fR, or \fBstdin\fR in the case that -\fBinitscr\fR was used, will be used to do this typeahead checking. -The \fBtypeahead\fR routine specifies that the file descriptor -\fIfd\fR is to be used to check for typeahead instead. If \fIfd\fR is +The \fBcurses\fP library does \*(``line-breakout optimization\*('' +by looking for typeahead periodically while updating the screen. +If input is found, and it is coming from a tty, +the current update is postponed until +\fBrefresh\fP(3X) or \fBdoupdate\fP is called again. +This allows faster response to commands typed in advance. +Normally, the input FILE +pointer passed to \fBnewterm\fP, or \fBstdin\fP in the case that +\fBinitscr\fP was used, will be used to do this typeahead checking. +The \fBtypeahead\fP routine specifies that the file descriptor +\fIfd\fP is to be used to check for typeahead instead. +If \fIfd\fP is \-1, then no typeahead checking is done. +.\" .SH RETURN VALUE -All routines that return an integer return \fBERR\fR upon failure and OK (SVr4 -specifies only "an integer value other than \fBERR\fR") upon successful -completion, unless otherwise noted in the preceding routine descriptions. +All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +(SVr4 specifies only \*(``an integer value other than \fBERR\fP\*('') +upon successful completion, +unless otherwise noted in the preceding routine descriptions. .PP X/Open does not define any error conditions. In this implementation, @@ -219,27 +300,37 @@ These functions are described in the XSI Curses standard, Issue 4. .PP The ncurses library obeys the XPG4 standard and the historical practice of the AT&T curses implementations, in that the echo bit is cleared when curses -initializes the terminal state. BSD curses differed from this slightly; it -left the echo bit on at initialization, but the BSD \fBraw\fR call turned it -off as a side-effect. For best portability, set echo or noecho explicitly +initializes the terminal state. +BSD curses differed from this slightly; it +left the echo bit on at initialization, but the BSD \fBraw\fP call turned it +off as a side-effect. +For best portability, set \fBecho \fPor \fBnoecho\fP explicitly just after initialization, even if your program remains in cooked mode. .PP +The XSI Curses standard is ambiguous on the question of whether \fBraw\fP +should disable the CRLF translations controlled by \fBnl\fP and \fBnonl\fP. +BSD curses did turn off these translations; AT&T curses (at least as late as +SVr1) did not. +We chose to do so, on the theory that a programmer requesting +raw input wants a clean (ideally 8-bit clean) connection that the operating +system will not alter. +.PP When \fBkeypad\fP is first enabled, ncurses loads the key-definitions for the current terminal description. If the terminal description includes extended string capabilities, -e.g., from using the \fB\-x\fP option of @TIC@, +e.g., from using the \fB\-x\fP option of \fB@TIC@\fP, then ncurses also defines keys for the capabilities whose names -begin with "k". +begin with \*(``k\*(''. The corresponding keycodes are generated and (depending on previous loads of terminal descriptions) may differ from one execution of a program to the next. The generated keycodes are recognized by the \fBkeyname\fP function -(which will then return a name beginning with "k" denoting the -terminfo capability name rather than "K", used for curses key-names). +(which will then return a name beginning with \*(``k\*('' denoting the +terminfo capability name rather than \*(``K\*('', used for curses key-names). On the other hand, an application can use \fBdefine_key\fP to establish a specific keycode for a given string. This makes it possible for an application to check for an extended -capability's presence with \fItigetstr\fP, +capability's presence with \fBtigetstr\fP, and reassign the keycode to match its own needs. .PP Low-level applications can use \fBtigetstr\fP to obtain the definition @@ -260,18 +351,30 @@ and if a capability's value is the same as a previously-loaded key definition, the later definition is the one used. .SH NOTES -Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR, -\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR, -\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros. +Note that +\fBecho\fP, +\fBnoecho\fP, +\fBhalfdelay\fP, +\fBintrflush\fP, +\fBmeta\fP, +\fBnl\fP, +\fBnonl\fP, +\fBnodelay\fP, +\fBnotimeout\fP, +\fBnoqiflush\fP, +\fBqiflush\fP, +\fBtimeout\fP, and +\fBwtimeout\fP may be macros. .PP -The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that -they attempt to restore to normal (`cooked') mode from raw and cbreak modes -respectively. Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver +The \fBnoraw\fP and \fBnocbreak\fP calls follow historical practice in that +they attempt to restore to normal (\*(``cooked\*('') mode +from raw and cbreak modes respectively. +Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver control states that are hard to predict or understand; it is not recommended. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_getch\fR(3X), -\fBcurs_initscr\fR(3X), -\fBcurs_util\fR(3X), -\fBdefine_key\fR(3X), -\fBtermio\fR(7) +\fBcurses\fP(3X), +\fBcurs_getch\fP(3X), +\fBcurs_initscr\fP(3X), +\fBcurs_util\fP(3X), +\fBdefine_key\fP(3X), +\fBtermios\fP(3)