X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_inopts.3x;h=d346017ba0ea09dba6a0e38648c06578bf23a186;hp=cbce7ef4a0ce52474136d7c096d63aef2ed5c3c2;hb=HEAD;hpb=a47b9e53836434777854387fa6f09f2137ec2111 diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index cbce7ef4..63db4967 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,283 +28,368 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.43 2023/08/19 20:55:23 tom Exp $ -.TH curs_inopts 3X 2023-08-19 "ncurses 6.4" "Library calls" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' -.na -.hy 0 +.\" $Id: curs_inopts.3x,v 1.66 2024/04/13 22:20:29 tom Exp $ +.TH curs_inopts 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} .SH NAME -\fBcbreak\fP, -\fBecho\fP, -\fBhalfdelay\fP, -\fBintrflush\fP, -\fBis_cbreak\fP, -\fBis_echo\fP, -\fBis_nl\fP, -\fBis_raw\fP, -\fBkeypad\fP, -\fBmeta\fP, -\fBnl\fP, -\fBnocbreak\fP, -\fBnodelay\fP, -\fBnoecho\fP, -\fBnonl\fP, -\fBnoqiflush\fP, -\fBnoraw\fP, -\fBnotimeout\fP, -\fBqiflush\fP, -\fBraw\fP, -\fBtimeout\fP, -\fBwtimeout\fP, -\fBtypeahead\fP \- \fBcurses\fP input options -.ad -.hy +\fB\%cbreak\fP, +\fB\%echo\fP, +\fB\%halfdelay\fP, +\fB\%intrflush\fP, +\fB\%is_cbreak\fP, +\fB\%is_echo\fP, +\fB\%is_nl\fP, +\fB\%is_raw\fP, +\fB\%keypad\fP, +\fB\%meta\fP, +\fB\%nl\fP, +\fB\%nocbreak\fP, +\fB\%nodelay\fP, +\fB\%noecho\fP, +\fB\%nonl\fP, +\fB\%noqiflush\fP, +\fB\%noraw\fP, +\fB\%notimeout\fP, +\fB\%qiflush\fP, +\fB\%raw\fP, +\fB\%timeout\fP, +\fB\%wtimeout\fP, +\fB\%typeahead\fP \- +get and set \fIcurses\fR terminal input options .SH SYNOPSIS -\fB#include \fP +.nf +\fB#include +.PP +\fBint cbreak(void); +\fBint nocbreak(void); +.PP +\fBint echo(void); +\fBint noecho(void); +.PP +\fBint intrflush(WINDOW *\fIwin\fP, bool \fIbf\fP); +\fBint keypad(WINDOW *\fIwin\fP, bool \fIbf\fP); +\fBint meta(WINDOW *\fIwin\fP, bool \fIbf\fP); +\fBint nodelay(WINDOW *\fIwin\fP, bool \fIbf\fP); +\fBint notimeout(WINDOW *\fIwin\fP, bool \fIbf\fP); +.PP +\fBint nl(void); +\fBint nonl(void); +.PP +\fBint raw(void); +\fBint noraw(void); +.PP +\fBvoid qiflush(void); +\fBvoid noqiflush(void); .PP -\fBint cbreak(void);\fP -.br -\fBint nocbreak(void);\fP -.sp -\fBint echo(void);\fP -.br -\fBint noecho(void);\fP -.sp -\fBint intrflush(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR -.br -\fBint keypad(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR -.br -\fBint meta(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR -.br -\fBint nodelay(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR -.br -\fBint notimeout(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR -.sp -\fBint nl(void);\fP -.br -\fBint nonl(void);\fP -.sp -\fBint raw(void);\fP -.br -\fBint noraw(void);\fP -.sp -\fBvoid qiflush(void);\fP -.br -\fBvoid noqiflush(void);\fP -.sp -\fBint halfdelay(int \fItenths\fB);\fR -.br -\fBvoid timeout(int \fIdelay\fB);\fR -.br -\fBvoid wtimeout(WINDOW *\fIwin\fB, int \fIdelay\fB);\fR -.sp -\fBint typeahead(int \fIfd\fB);\fR -.sp -/* extensions */ -.br -\fBint is_cbreak(void);\fP -.br -\fBint is_echo(void);\fP -.br -\fBint is_nl(void);\fP -.br -\fBint is_raw(void);\fP -.br +\fBint halfdelay(int \fItenths\fP); +\fBvoid timeout(int \fIdelay\fP); +\fBvoid wtimeout(WINDOW *\fIwin\fP, int \fIdelay\fP); +.PP +\fBint typeahead(int \fIfd\fP); +.PP +\fI/* extensions */ +\fBint is_cbreak(void); +\fBint is_echo(void); +\fBint is_nl(void); +\fBint is_raw(void); +.fi .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. +.I \%ncurses +provides several functions that 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. +An application must apply these to each window if the same behavior is +desired. .\" -.SS cbreak/nocbreak -Normally, the tty driver buffers typed characters until a newline or carriage +.SS "cbreak, nocbreak" +Normally, +the terminal driver buffers typed characters until a newline or carriage 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 +The \fB\%cbreak\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\fP routine returns the terminal to normal (cooked) +The \fB\%nocbreak\fP routine returns the terminal to normal (cooked) mode. .PP -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.] +Initially the terminal may or may not be in \fB\%cbreak\fP mode, +as the mode is inherited; +therefore, +a program should call \fB\%cbreak\fP or \fB\%nocbreak\fP explicitly. +Most interactive programs using +.I curses +set the \fB\%cbreak\fP mode. +Note that \fB\%cbreak\fP overrides \fBraw\fP. +[See \fB\%curs_getch\fP(3X) for a discussion of how these routines +interact with \fBecho\fP and \fB\%noecho\fP.] .\" -.SS echo/noecho -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. +.SS "echo, noecho" +The \fBecho\fP and \fB\%noecho\fP routines control whether characters +typed by the user are echoed by \fB\%getch\fP(3X) as they are typed. +Echoing by the terminal driver is always disabled, +but initially \fB\%getch\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\fP. -[See \fBcurs_getch\fP(3X) for a -discussion of how these routines interact with \fBcbreak\fP and -\fBnocbreak\fP.] +their own echoing in a controlled area of the screen, +or not to echo at all, +so they disable echoing by calling \fB\%noecho\fP. +[See \fB\%curs_getch\fP(3X) for a +discussion of how these routines interact with \fB\%cbreak\fP and +\fB\%nocbreak\fP.] .\" .SS halfdelay -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. +The \fB\%halfdelay\fP routine is used for half-delay mode, +which is similar to \fB\%cbreak\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 \fB\%nocbreak\fP to leave half-delay mode. .\" .SS intrflush -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\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. +If the \fB\%intrflush\fP option is enabled +.RI ( bf +is +.BR TRUE ), +and an interrupt key is pressed on the keyboard +(interrupt, +break, +quit), +all output in the terminal driver queue is flushed, +giving the effect of faster response to the interrupt, +but causing +.I curses +to have the wrong idea of what is on the screen. +Disabling the option +.RI ( bf +is +.BR FALSE ), +prevents the flush. +The default for the option is inherited from the terminal driver +settings. +The +.I win +argument is ignored. .\" .SS keypad -The \fBkeypad\fP option enables the keypad of the user's terminal. +The \fB\%keypad\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. +enabled +.RI ( bf +is +.BR TRUE ), +the user can press a function key +(such as an arrow key) +and \fB\%wgetch\fP(3X) returns a single value representing the function +key, +as in \fB\%KEY_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 -transmit) and off (made to work locally), turning on this option -causes the terminal keypad to be turned on when \fBwgetch\fP(3X) is -called. +(\fIbf\fP is \fBFALSE\fP), +.I curses +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 transmit) +and off +(made to work locally), +turning on this option causes the terminal keypad to be turned on when +\fB\%wgetch\fP(3X) is called. The default value for keypad is \fBFALSE\fP. .\" .SS meta -Initially, whether the terminal returns 7 or 8 significant bits on -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, +Initially, +whether the terminal returns 7 or 8 significant bits on input depends on +the control mode of the terminal driver [see \fI\%termios\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. +.IR win , +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 -The \fBnl\fP and \fBnonl\fP routines control whether the underlying display -device translates the return key into newline on input. +.SS "nl, nonl" +The \fBnl\fP and \fBnonl\fP routines control whether the underlying +display device translates the return key into newline on input. .\" .SS nodelay -The \fBnodelay\fP option causes \fBgetch\fP to be a non-blocking call. -If no input is ready, \fBgetch\fP returns \fBERR\fP. +The \fB\%nodelay\fP option causes \fB\%getch\fP to be a non-blocking +call. +If no input is ready, +\fB\%getch\fP returns \fBERR\fP. If disabled -(\fIbf\fP is \fBFALSE\fP), \fBgetch\fP waits until a key is pressed. +.RI ( bf +is +.BR FALSE ), +\fB\%getch\fP waits until a key is pressed. .SS notimeout -When interpreting an escape sequence, \fBwgetch\fP(3X) sets a timer +When interpreting an escape sequence, +\fB\%wgetch\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. +If +\fB\%notimeout(\fIwin\fR, \fBTRUE\fP) +is called, +then \fB\%wgetch\fP does not set a timer. +The purpose of the timeout is to distinguish sequences produced by a +function key from those typed by a user. .\" -.SS raw/noraw -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 -the BREAK key depends on other bits in the tty driver that are not set by -\fBcurses\fP. +.SS "raw, noraw" +The \fBraw\fP and \fB\%noraw\fP routines place the terminal into or out +of raw mode. +Raw mode is similar to \fB\%cbreak\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 the BREAK key depends on other bits in the terminal +driver that are not set by +.IR curses . .\" -.SS qiflush/noqiflush -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)]. +.SS "qiflush, nqiflush" +When the \fB\%noqiflush\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 \fB\%termios\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. +\fB\%qiflush\fP is called, +the queues will be flushed when these control characters are read. +You may want to call \fB\%noqiflush\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 -The \fBtimeout\fP and \fBwtimeout\fP routines set blocking or +.SS "timeout, wtimeout" +The \fB\%timeout\fP and \fB\%wtimeout\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\fP is zero, then non-blocking read is used -(i.e., read returns \fBERR\fP if no input is waiting). +a blocking read is used +(i.e., +waits indefinitely for input). +If \fIdelay\fP is zero, +then a non-blocking read is used +(i.e., +.I 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, +\fIdelay\fP is positive, +then +.I read +blocks for \fIdelay\fP milliseconds, +and returns \fBERR\fP if there is still no input. +Hence, +these routines provide the same functionality as \fB\%nodelay\fP, plus the additional capability of being able to block for only -\fIdelay\fP milliseconds (where \fIdelay\fP is positive). +\fIdelay\fP milliseconds +(where \fIdelay\fP is positive). .\" .SS typeahead -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, +.I curses +does \*(``line-breakout optimization\*('' by looking for typeahead +periodically while updating the screen. +If input is found, +and it is coming from a terminal, the current update is postponed until -\fBrefresh\fP(3X) or \fBdoupdate\fP is called again. +\fB\%refresh\fP(3X) or \fB\%doupdate\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 +Normally, +the input +.I FILE +pointer passed to \fB\%newterm\fP, +or \fBstdin\fP in the case that \fB\%initscr\fP was used, +will be used to do this typeahead checking. +The \fB\%typeahead\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. +\-1, +then no typeahead checking is done. .\" .SH RETURN VALUE -All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP +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. +X/Open Curses does not specify any error conditions. In this implementation, functions with a window parameter will return an error if it is null. -Any function will also return an error if the terminal was not initialized. +Any function will also return an error if the terminal was not +initialized. Also, .RS 3 .TP 5 -\fBhalfdelay\fP +\fB\%halfdelay\fP returns an error if its parameter is outside the range 1..255. .RE +.SH NOTES +\fBecho\fP, +\fB\%noecho\fP, +\fB\%halfdelay\fP, +\fB\%intrflush\fP, +\fBmeta\fP, +\fBnl\fP, +\fBnonl\fP, +\fB\%nodelay\fP, +\fB\%notimeout\fP, +\fB\%noqiflush\fP, +\fB\%qiflush\fP, +\fB\%timeout\fP, +and +\fB\%wtimeout\fP +may be implemented as macros. +.PP +\fB\%noraw\fP and \fB\%nocbreak\fP follow historical practice in that +they attempt to restore normal (\*(``cooked\*('') mode +from raw and cbreak modes respectively. +Mixing \fBraw\fP/\fB\%noraw\fP and \fB\%cbreak\fP/\fB\%nocbreak\fP calls +leads to terminal driver control states that are hard to predict or +understand; +doing so is not recommended. .SH EXTENSIONS -This implementation provides four functions which may be used to detect -if the corresponding flags were set or reset: +.I \%ncurses +provides four \*(``is_\*('' functions that may be used to detect if the +corresponding flags were set or reset. .PP .TS -l l l. -\fBQuery\fP \fBSet\fP \fBReset\fP +center; +Lb Lb Lb +L L L . +Query Set Reset _ is_cbreak cbreak nocbreak is_echo echo noecho @@ -312,102 +397,158 @@ is_nl nl nonl is_raw raw noraw .TE .PP -In each case, the function returns -.TP 5 +In each case, +the function returns +.TP 4 \" "-1" + 2n 1 if the flag is set, -.TP 5 +.TP 0 -if the flag is reset, or -.TP 5 --1 -if the curses library was not initialized. +if the flag is reset, +or +.TP +\-1 +if the library is not initialized. .PP -These routines are specific to ncurses. -They were not supported on Version 7, BSD or System V implementations. -It is recommended that any code depending on ncurses extensions -be conditioned using NCURSES_VERSION. +They were designed for +\fB\%ncurses\fP(3X), +and are not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous +.I curses +implementation. .SH PORTABILITY -Except as noted in the section on extensions, -these functions are described in the XSI Curses standard, Issue 4. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +Except as noted in section \*(``EXTENSIONS\*('' above, +X/Open Curses, Issue 4, Version 2 describes these functions. .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 +.I \%ncurses +follows X/Open Curses +and the historical practice of AT&T +.I curses +implementations, +in that the echo bit is cleared when +.I curses 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. +BSD +.I 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\fP or \fB\%noecho\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. +X/Open Curses is ambiguous regarding whether \fBraw\fP should disable +the CR/LF translations controlled by \fBnl\fP and \fBnonl\fP. +BSD +.I curses +did turn off these translations; +AT&T +.I curses +(at least as late as SVr1) +did not. +.I \%ncurses +does so, +on the assumption 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. +When \fB\%keypad\fP is first enabled, +.I \%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 \fB@TIC@\fP, -then ncurses also defines keys for the capabilities whose names -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 +e.g., +from using the +.B \-x +option of \fB\%@TIC@\fP, +then +.I \%ncurses +also defines keys for the capabilities whose names 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 \fB\%keyname\fP(3X) +function (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 +terminfo capability name rather than \*(``K\*('', +used for +.I curses +key names). +On the other hand, +an application can use \fB\%define_key\fP(3X) 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 \fBtigetstr\fP, +capability's presence with \fB\%tigetstr\fP, and reassign the keycode to match its own needs. .PP -Low-level applications can use \fBtigetstr\fP to obtain the definition +Low-level applications can use \fB\%tigetstr\fP to obtain the definition of any particular string capability. -Higher-level applications which use the curses \fBwgetch\fP -and similar functions to return keycodes rely upon the order in which -the strings are loaded. +Higher-level applications which use the +.I curses +\fB\%wgetch\fP and similar functions to return keycodes rely upon the +order in which the strings are loaded. If more than one key definition has the same string value, -then \fBwgetch\fP can return only one keycode. -Most curses implementations (including ncurses) +then \fB\%wgetch\fP can return only one keycode. +Most +.I curses +implementations +(including +.IR \%ncurses ) load key definitions in the order defined by the array of string capability names. The last key to be loaded determines the keycode which will be returned. -In ncurses, you may also have extended capabilities interpreted as -key definitions. +In +.IR \%ncurses , +you may also have extended capabilities interpreted as key definitions. These are loaded after the predefined keys, 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\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\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 HISTORY +Formerly, +.I \%ncurses +used +.B \%nl +and +.B \%nonl +to control the conversion of newlines to carriage return/line feed +on output as well as input. +X/Open Curses documents the use of these functions only for input. +This difference arose from converting the +.I \%pcurses +source (1986), +which used +\fI\%ioctl\fP(2) calls and the +.I \%sgttyb +structure, +to +.I \%termios +(the POSIX terminal API). +In the former, +both input and output were controlled via a single option +.BR \%CRMOD , +while the latter separates these features. +Because that conversion interferes with output optimization, +.I \%ncurses +6.2 (2020) amended +.B \%nl +and +.B \%nonl +to eliminate their effect on output. .SH SEE ALSO -\fBcurses\fP(3X), -\fBcurs_getch\fP(3X), -\fBcurs_initscr\fP(3X), -\fBcurs_util\fP(3X), -\fBdefine_key\fP(3X), -\fBtermios\fP(3) +\fB\%curses\fP(3X), +\fB\%curs_getch\fP(3X), +\fB\%curs_initscr\fP(3X), +\fB\%curs_util\fP(3X), +\fB\%define_key\fP(3X), +\fB\%termios\fP(3)