X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fcurs_inopts.3x;h=d346017ba0ea09dba6a0e38648c06578bf23a186;hb=HEAD;hp=7b9a1be310f1b9b713bafe57edc275d9c28dbfaf;hpb=0819b56c3096ed77dd36312b0c4e8f37e7d46c88;p=ncurses.git diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index 7b9a1be3..e915023b 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -1,5 +1,7 @@ +'\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. * +.\" 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 * .\" copy of this software and associated documentation files (the * @@ -26,322 +28,785 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inopts.3x,v 1.19 2015/04/11 10:21:38 tom Exp $ -.TH curs_inopts 3X "" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' -.na -.hy 0 +.\" $Id: curs_inopts.3x,v 1.68 2024/05/25 20:41:48 tom Exp $ +.TH curs_inopts 3X 2024-05-25 "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 '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .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 -.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 \fR +.nf +\fB#include .PP -\fBint cbreak(void);\fR -.br -\fBint nocbreak(void);\fR -.br -\fBint echo(void);\fR -.br -\fBint noecho(void);\fR -.br -\fBint halfdelay(int tenths);\fR -.br -\fBint intrflush(WINDOW *win, bool bf);\fR -.br -\fBint keypad(WINDOW *win, bool bf);\fR -.br -\fBint meta(WINDOW *win, bool bf);\fR -.br -\fBint nodelay(WINDOW *win, bool bf);\fR -.br -\fBint raw(void);\fR -.br -\fBint noraw(void);\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 -.br +\fBint cbreak(void); +\fBint nocbreak(void); +.PP +\fBint echo(void); +\fBint noecho(void); +.PP +\fBint intrflush(WINDOW * \fIwin\fP \fI/* ignored */\fP, bool \fIbf\fP); +\fBint keypad(WINDOW * \fIwin\fP, bool \fIbf\fP); +\fBint meta(WINDOW * \fIwin\fP \fI/* ignored */\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 +\fBvoid qiflush(void); +\fBvoid noqiflush(void); +.PP +\fBint raw(void); +\fBint noraw(void); +.PP +\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 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. +.I curses +offers configurable parameters permitting an application to control the +handling of input from the terminal. +Some are global, +applying to all windows; +others apply only to a specific window. +The library does not automatically apply such parameters to new or +derived windows; +an application must configure each window for the desired behavior. +.PP +Some descriptions below make reference to an +.IR "input character reading function" ":" +this is \fB\%wgetch\fP(3X) in the non-wide character +.I curses +API and \fB\%wget_wch\fP(3X) in the wide character API. +In addition to the variant forms of these described in +\fB\%ncurses\fP(3X), +the +.I curses +functions \fB\%wgetstr\fP(3X) and \fB\%wget_wstr\fP(3X) and their own +variants call the appropriate input character reading function. .\" -.SS cbreak -Normally, the tty driver buffers typed characters until a newline or carriage -return is typed. -The \fBcbreak\fR 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 +.SS "cbreak, nocbreak" +Normally, +the terminal driver buffers typed characters, +not delivering them to an application +until a line feed or carriage return is typed. +.B \%cbreak +configures the terminal in +.IR "cbreak mode" "," +which disables line buffering +and erase and kill character processing +(the interrupt, +quit, +suspend, +and flow control characters are unaffected) +and makes characters typed by the user immediately available to the program. -The \fBnocbreak\fR routine returns the terminal to normal (cooked) -mode. +.B \%nocbreak +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 +The state of the terminal is unknown to a +.I curses +application when it starts; +therefore, +a program should call +.B \%cbreak +or +.B \%nocbreak explicitly. -Most interactive programs using \fBcurses\fR set the \fBcbreak\fR +Most interactive programs using +.I curses +set \%cbreak 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.] +Calling +.B \%cbreak +overrides +.BR raw "." +The man page for the input character reading function +discusses how +.B \%cbreak +and +.B \%nocbreak +interact with +.B echo +and +.BR \%noecho "." .\" -.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 -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.] +.SS "echo, noecho" +.B echo +and +.B \%noecho +determine whether characters typed by the user are written to the +.I curses +window by the input character reading function as they are typed. +.I curses +always disables the terminal driver's own echoing. +By default, +a +.I curses +window has its echo flag set. +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 call +.BR \%noecho "." +The man page for the input character reading function +discusses how +.B echo +and +.B \%noecho +interact with +.B \%cbreak +and +.BR \%nocbreak "." .\" .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 -mode. +.B \%halfdelay +configures +.IR "half-delay mode" "," +which is similar to \%cbreak mode in that characters typed by the user +are immediately available to the program. +However, +after blocking for +.I tenths +tenths of seconds, +an input character reading function returns +.B ERR +if no input is pending. +The value of +.I tenths +must be between 1 and 255. +Use +.B \%nocbreak +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 -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 window argument is ignored. +.B \%intrflush +calls +.B \%qiflush +(see below) +if +.I bf +is +.BR TRUE "," +and +.B \%noqiflush +if +.I bf +is +.BR FALSE "." +It ignores its +.I win +argument. .\" .SS keypad -.PP -The \fBkeypad\fR option enables the keypad of the user's terminal. +.B keypad +enables recognition of a terminal's function keys. 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. +enabled +.RI ( bf +is +.BR TRUE ), +the input character reading function returns a value representing +the function key, +such as +.BR KEY_LEFT "." +(Wide-character API users: +\fB\%wget_wch\fP(3X) returns +.B \%KEY_CODE_YES +to indicate the availability of a function key code in its +.I wch +parameter.) If disabled -(\fIbf\fR is \fBFALSE\fR), \fBcurses\fR 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\fR is -called. -The default value for keypad is \fBFALSE\fP. +.RI ( bf +is +.BR FALSE ), +.I curses +does not treat function keys specially and the program has to interpret +escape sequences itself. +If the terminal's keypad can be turned on +(made to transmit) +and off +(made to work locally), +.B \%keypad +configures it consistently with the +.I bf +parameter. +By default, +a window's keypad mode is off. .\" .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, +Initially, +whether the terminal returns 7- or 8-bit character codes on input +depends on the configuration of the terminal driver; +see \fI\%termios\fP(3). +To force 8 bits to be returned, +call +.BR meta( .\|.\|. , +.BR TRUE) ; +this is equivalent, +on POSIX systems, +to setting the CS8 flag on the terminal. +To force 7 bits to be returned, +call +.BR meta( .\|.\|. , +.BR FALSE) ; +this is equivalent, +on POSIX systems, 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. +.IR win , +is always ignored. +If the +.I \%term\%info +string capabilities +.B \%meta_on +.RB ( smm ) +and +.B \%meta_off +.RB ( rmm ) +are defined for the terminal type, +enabling meta mode sends +.B smm +to the terminal and disabling it sends +.B rmm +to the terminal. +.\" +.SS "nl, nonl" +Initially, +whether the terminal reports a carriage return +using the character code for a line feed +depends on the configuration of the terminal driver; +see \fI\%termios\fP(3). +.B nl +configures the terminal to perform this translation. +.B nonl +disables it. .\" .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. +.B \%nodelay +configures the input character reading function to be non-blocking for +window +.IR "win" . +If no input is ready, +the reading function returns +.BR ERR "." If disabled -(\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed. -.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 -purpose of the timeout is to differentiate between sequences received -from a function key and those typed by a user. +.RI ( bf +is +.BR FALSE ), +the reading function does not return until it has input. +.SS notimeout +When the input character reading function reads an ESC character, +it sets a timer while waiting for the next character. +.BI \%notimeout( win , +.B TRUE) +disables this timer. +The purpose of the timeout is to distinguish sequences produced by a +function key from those typed by a user. +To configure the timeout rather than disabling it, +see +.B \%wtimeout +below. .\" -.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 -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\fR. +.SS "qiflush, noqiflush" .\" -.SS 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 -handler if you want output to continue as though the interrupt -had not occurred, after the handler exits. +.B \%qiflush +and +.B \%noqiflush +configure the terminal driver's treatment of its input and output queues +when it handles the interrupt, +suspend, +or quit characters in +.I \%cbreak +and \*(``cooked\*('' modes; +on POSIX systems, +see \fI\%termios\fP(3). +The default behavior is inherited from the terminal driver settings. +Calling +.B \%qiflush +configures the terminal to flush the queues when any of these events +occurs, +giving the impression of faster response to user input, +but making the library's model of the screen contents incorrect. +Calling +.B \%noqiflush +prevents such flushing, +but might frustrate impatient users on slow connections if a +.I curses +update of the screen is in progress when the event occurs; +see +.B \%typeahead +below for a mitigation of this problem. +You may want to call +.B \%noqiflush +in a signal handler +if you want output to continue +after the handler exits +as though the interrupt had not occurred. .\" -.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, -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). +.SS "raw, noraw" +.B raw +configures the terminal to read input in +.IR "raw mode" , +which is similar to cbreak mode +(see +.B \%cbreak +above) +except that it furthermore passes through the terminal's configured +interrupt, +quit, +suspend, +and flow control characters +uninterpreted to the application, +instead of generating a signal or acting on I/O flow. +The behavior of the terminal's \*(``Break\*('' key +(if any) +depends on terminal driver configuration parameters that +.I curses +does not handle. +.B \%noraw +exits raw mode. +.\" +.SS "timeout, wtimeout" +.B \%wtimeout +configures whether a +.I curses +input character reading function called on window +.I win +uses blocking or non-blocking reads. +If +.I delay +is negative, +a blocking read is used, +waiting indefinitely for input. 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, -plus the additional capability of being able to block for only -\fIdelay\fR milliseconds (where \fIdelay\fR is positive). +.I delay +is zero, +a non-blocking read is used; +an input character reading function returns +.B ERR +if no input is pending. +If +.I delay +is positive, +an input character reading function +blocks for +.I delay +milliseconds, +and returns +.B ERR +if the delay elapses and there is still no input pending. +.B \%timeout +calls +.B \%wtimeout +on +.BR stdscr "." .\" .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 -\-1, then no typeahead checking is done. +Normally, +a +.I curses +library checks the terminal for input while updating the screen. +If any is found, +the update is postponed until the next \fB\%wrefresh\fP(3X) or +\fB\%doupdate\fP(3X) call, +allowing faster response to user key strokes. +The library tests the file descriptor corresponding to the +.I FILE +stream pointer passed to \fB\%newterm\fP(3X) +(or +.I stdin +if \fB\%initscr\fP(3X) was called), +for pending input. +.B \%typeahead +instructs +.I curses +to test file descriptor +.I fd +instead. +An +.I fd +of +.B \-1 +disables the check. .\" .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. +.B \%timeout +and +.B \%wtimeout +return no value. +.PP +.BR \%cbreak "," +.BR \%nocbreak "," +.BR \%echo "," +.BR \%noecho "," +.BR \%halfdelay "," +.BR \%intrflush "," +.BR \%keypad "," +.BR \%meta "," +.BR \%nodelay "," +.BR \%notimeout "," +.BR \%nl "," +.BR \%nonl "," +.BR \%raw "," +.BR \%noraw "," +and +.B \%typeahead +return +.B OK +on success and +.B ERR +on failure. +.PP +In +.IR \%ncurses "," +the functions in the previous paragraph return +.B ERR +if +.bP +the terminal is not initialized or +.bP +.I win +is +.B NULL +(except for +.B \%intrflush +and +.BR meta "," +which ignore its value). +.PP +Further, +.B \%halfdelay +returns +.B ERR +if +.I delay +is outside the range 1..255. +.PP +See section \*(``EXTENSIONS\*('' below for the +return values of +.BR is_cbreak "," +.BR is_echo "," +.BR is_nl "," +and +.BR is_raw "." +.SH NOTES +.BR echo "," +.BR \%noecho "," +.BR \%halfdelay "," +.BR \%intrflush "," +.BR meta "," +.BR nl "," +.BR nonl "," +.BR \%nodelay "," +.BR \%notimeout "," +.BR \%noqiflush "," +.BR \%qiflush "," +.BR \%timeout "," +and +.B \%wtimeout +may be implemented as macros. +.PP +.B \%noraw +and +.B \%nocbreak +follow historical practice in that they attempt to restore normal +(\*(``cooked\*('') mode from raw and cbreak modes, +respectively. +Mixing +.BR raw / \%noraw +calls with +.BR cbreak / \%nocbreak +calls leads to terminal driver control states that are hard to predict +or understand; +doing so is not recommended. +.SH EXTENSIONS +.I \%ncurses +provides four \*(``is_\*('' functions corresponding to +.BR \%cbreak "," +.BR echo "," +.BR nl "," +and +.BR raw "," +permitting their states to be queried by the application. +.PP +.TS +center; +Lb Lb Lb +L L L . +Query Set Reset +_ +is_cbreak cbreak nocbreak +is_echo echo noecho +is_nl nl nonl +is_raw raw noraw +.TE .PP -X/Open does not define 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. -Also, -.RS -.TP 5 -\fBhalfdelay\fP -returns an error -if its parameter is outside the range 1..255. -.RE +In each case, +the function returns +.TP 5 \" "-1" + 2n tag separation + 1n fudge for typesetters like grops +.B 1 +if the flag is set, +.TP +.B 0 +if the flag is reset, +or +.TP +.B \-1 +if the library is not initialized. .SH PORTABILITY -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 describes these functions. +It specifies no error conditions for them. .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 -just after initialization, even if your program remains in cooked mode. +SVr4 +.I curses +describes a successful return value only as +\*(``an integer value other than +.BR ERR \*(''. .PP -When \fBkeypad\fP is first enabled, -ncurses loads the key-definitions for the current terminal description. +.I \%ncurses +follows X/Open Curses +and the historical practice of System\ V +.IR curses "," +clearing the terminal driver's \*(``echo\*('' flag when initializing the +screen. +BSD +.I curses +did not, +but its +.I raw +function turned it off as a side effect. +.\" SGTTY's sg_flags had a "RAW" symbol; termio in SVr1 for the PDP-11 +.\" did not. +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/include/curses.h +.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysv-pdp11_man/a_man/man7/termio.7 +For best portability, +call +.B echo +or +.B \%noecho +explicitly just after initialization, +even if your program remains in normal (\*(``cooked\*('') mode. +.PP +X/Open Curses is ambiguous regarding whether +.I raw +should disable the carriage return and line feed translation feature +controlled by +.I nl +and +.IR \%nonl "." +BSD +.I curses +did turn off these translations; +System\ V +.I curses +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 +.B \%keypad +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 @TIC@, -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 -(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, +for example, +by using the +.B \-x +option of \fB\%@TIC@\fP(1), +then +.I \%ncurses +also defines keys for the capabilities whose names begin with +\*(``k\*(''. +Corresponding key codes 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 then returns a name beginning with \*(``k\*('' denoting the +.I \%term\%info +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 bind +a specific key to a string of the programmer's choice. +This feature enables an application to check for an extended +capability's presence with \fB\%tigetstr\fP(3X), and reassign the keycode to match its own needs. .PP -Low-level applications can use \fBtigetstr\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. -If more than one key definition has the same string value, -then \fBwgetch\fP can return only one keycode. -Most curses implementations (including ncurses) +Low-level applications can use \fB\%tigetstr\fP(3X) to obtain the +definition of any string capability. +.I curses +applications use the input character reading function +to obtain key codes from input +and rely upon the order in which the string capabilities are loaded. +Multiple key capability strings can have the same value, +but the input character reading function can report only one key code. +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. +they appear in the +.B \%strfnames +array of string capability names; +see \fB\%term_variables\fP(3X). +.\" ncurses/tinfo/parse_entry.c:lookup_fullname, I think --GBR +The last capability read using a particular definition determines the +key code to be reported. +In +.IR \%ncurses , +extended capabilities can be interpreted as key definitions. These are loaded after the predefined keys, -and if a capability's value is the same as a previously-loaded +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. +.SH HISTORY +4BSD +.I curses +(1980) +introduced +.IR echo "," +.IR \%noecho "," +.IR nl "," +.IR \%nonl "," +.IR raw "," +and +.IR \%noraw "." \" also crmod and nocrmod, never standardized .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 -control states that are hard to predict or understand; it is not recommended. +SVr2 (1984) featured a new terminal driver, +extending the +.I curses +API to support it with +.IR \%cbreak "," +.IR \%nocbreak "," +.IR \%intrflush "," +.IR \%keypad "," +.IR \%meta "," +.IR \%nodelay "," +and +.IR \%typeahead "." +.PP +SVr3 (1987) +added +.IR \%halfdelay "," +.IR \%notimeout "," +and +.IR \%wtimeout "." +.I \%qiflush +and +.I \%noqiflush +appeared in SVr3.1 (1987), +at which point +.I \%intrflush +became a wrapper for either of these functions, +depending on the value of its Boolean argument. +SVr3.1 also added +.IR \%timeout "." +.PP +.I \%ncurses +6.5 (2024) introduced +.IR is_cbreak "," +.IR is_echo "," +.IR is_nl "," +and +.IR is_raw "." +.PP +Formerly, +.I \%ncurses +used +.I \%nl +and +.I \%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 +\*(``CRMOD\*('', +while the latter separates these features. +Because that conversion interferes with output optimization, +.I \%ncurses +6.2 (2020) amended +.I \%nl +and +.I \%nonl +to eliminate their effect on output. .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) +\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\%term_variables\fP(3X), +\fB\%termios\fP(3)