X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=9433c6148583bcc421f253134e28cd27e2ea7e54;hb=HEAD;hp=642205a8c5f72082a9838c7a437371b265c065e8;hpb=5dbe81a41e3c75806996cd762b9e55dcc9edb835;p=ncurses.git diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 642205a8..bc88c0ac 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2015,2016 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 * @@ -27,372 +28,677 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.45 2016/05/15 01:05:18 tom Exp $ -.TH curs_getch 3X "" -.na -.hy 0 +.\" $Id: curs_getch.3x,v 1.95 2024/06/01 22:29:08 tom Exp $ +.TH curs_getch 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ^ \(ha +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ds ^ ^ +.\} +. +.ie \n(.g .ds : \: +.el .ds : \" empty +. .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME -\fBgetch\fR, -\fBwgetch\fR, -\fBmvgetch\fR, -\fBmvwgetch\fR, -\fBungetch\fR, -\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard -.ad -.hy +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +\fB\%ungetch\fP, +\fB\%has_key\fP \- +get (or push back) characters from \fIcurses\fR terminal keyboard .SH SYNOPSIS -\fB#include \fR -.PP -\fBint getch(void);\fR -.br -\fBint wgetch(WINDOW *\fP\fIwin);\fR -.br -\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br -\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br -\fBint ungetch(int \fP\fIch\fP\fB);\fR -.br -\fBint has_key(int \fP\fIch\fP\fB);\fR -.br +.nf +.B #include +.PP +.B int getch(void); +.B int wgetch(WINDOW *\fIwin\fP); +.B int mvgetch(int \fIy\fP, int \fIx\fP); +.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP); +.PP +.B int ungetch(int \fIc\fP); +.PP +.\" XXX: Move has_key into its own page like define_key and key_defined? +\fI/* extension */\fP +.B int has_key(int \fIc\fP); +.fi .SH DESCRIPTION -.SS Reading characters -The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read -a character from the window. -In no-delay mode, if no input is waiting, the value \fBERR\fR is returned. -In delay mode, the program waits until the system -passes text through to the program. -Depending on the setting of \fBcbreak\fR, -this is after one character (cbreak mode), -or after the first newline (nocbreak mode). -In half-delay mode, -the program waits until a character is typed or the -specified timeout has been reached. -.PP -If \fBecho\fR is enabled, and the window is not a pad, -then the character will also be echoed into the -designated window according to the following rules: -.bP -If the character is the current erase character, left arrow, or backspace, -the cursor is moved one space to the left and that screen position is erased -as if \fBdelch\fR had been called. +.SS "Reading Characters" +.B \%wgetch +gathers a key event from the terminal keyboard associated with a +.I curses +window +.IR win "." +\fB\%ncurses\fP(3X) describes the variants of this function. +.PP +When input is pending, +.B \%wgetch +returns an integer identifying the key event; +for alphanumeric and punctuation keys, +this value corresponds to the character encoding used by the terminal. +Use of the control key as a modifier, +by holding it down while pressing and releasing another key, +often results in a distinct code. +The behavior of other keys depends on whether +.I win +is in keypad mode; +see subsection \*(``Keypad Mode\*('' below. +.PP +If no input is pending, +then if the no-delay flag is set in the window +(see \fB\%nodelay\fP(3X)), +the function returns +.BR ERR ";" +otherwise, +.I curses +waits until the terminal has input. +If \fB\%cbreak\fP(3X) +has been called, +this happens after one character is read. +If \fB\%nocbreak\fP(3X) +has been called, +it occurs when the next newline is read. +If \fB\%halfdelay\fP(3X) +has been called, +.I curses +waits until input is available or the specified delay elapses. +.PP +If \fB\%echo\fP(3X) has been called, +and the window is not a pad, +.I curses +writes the returned character +.I c +to the window +(at the cursor position) +per the following rules. .bP -If the character value is any other \fBKEY_\fR define, the user is alerted -with a \fBbeep\fR call. +If +.I c +matches the terminal's erase character, +the cursor moves leftward one position +and the new position is erased +as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called. +When the window's keypad mode is enabled +(see below), +.B \%KEY_LEFT +and +.B \%KEY_BACKSPACE +are handled the same way. .bP -If the character is a carriage-return, -and if \fBnl\fP is enabled, -it is translated to a line-feed after echoing. +.I curses +writes any other +.I c +to the window, +as with \fB\%wechochar\fP(3X). .bP -Otherwise the character is simply output to the screen. -.PP -If the window is not a pad, and it has been moved or modified since the last -call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character -is read. -.SS Keypad mode +If the window +.I win +has been moved or modified since the last call to +\fB\%wrefresh\fP(3X), +.I curses +calls +.B \%wrefresh +on it. .PP -If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for -that function key is returned instead of the raw characters: +If +.I c +is a carriage return and \fBnl\fP(3X) has been called, +.B \%wgetch +returns the character code for line feed instead. +.SS "Keypad Mode" +To +.IR curses "," +key strokes not from the alphabetic section of the keyboard +(those corresponding to the ECMA-6 character set\(emsee +\fI\%ascii\fP(7)\(emoptionally modified by either the control or shift +keys) +are treated as +.I function +keys. +(In +.IR curses "," +the term \*(``function key\*('' includes but is not limited to keycaps +engraved with \*(``F1\*('', +\*(``PF1\*('', +and so on.) +If the window is in keypad mode, +these produce a numeric code corresponding to the +.B KEY_ +symbols listed in subsection \*(``Predefined Key Codes\*('' below; +otherwise, +they transmit a sequence of codes typically starting with the escape +character, +and which must be collected with multiple +.B \%wgetch +calls. .bP -The predefined function -keys are listed in \fB\fR as macros with values outside the range -of 8-bit characters. -Their names begin with \fBKEY_\fR. +The +.I \%curses.h +header file declares many +.I "predefined function keys" +whose names begin with +.BR KEY_ ";" +these object-like macros have values outside the range of eight-bit +character codes. .bP -Other (user-defined) function keys which may be defined using \fBdefine_key\fP(3X) -have no names, but also are expected to have values outside the range of -8-bit characters. -.PP -Thus, a variable -intended to hold the return value of a function key must be of short size or -larger. -.PP -When a character that could be the beginning of a function key is received -(which, on modern terminals, means an escape character), -\fBcurses\fR sets a timer. -If the remainder of the sequence does not come in within the designated -time, the character is passed through; -otherwise, the function key value is returned. -For this reason, many terminals experience a delay between the time -a user presses the escape key and the escape is returned to the program. -.SS Ungetting characters -.PP -The \fBungetch\fR routine places \fIch\fR back onto the input queue to be -returned by the next call to \fBwgetch\fR. -There is just one input queue for all windows. -.PP -.SS Predefined key-codes -The following special keys are defined in \fB\fR. +In +.IR \%ncurses "," +.I "user-defined function keys" +are configured with \fB\%define_key\fP(3X); +they have no names, +but are also expected to have values outside the range of eight-bit +codes. +.PP +A variable intended to hold a function key code must thus be of type +.I short +or larger. +.PP +Most terminals one encounters follow the ECMA-48 standard insofar as +their function keys produce character sequences prefixed with the +escape character ESC. +This fact implies that +.I curses +cannot distinguish a user's press of the escape key +(assuming it sends ESC) +from the beginning of a function key's character sequence without +waiting to see if, +and how soon, +further input arrives. +When +.I curses +reads such an ambiguous character, +it sets a timer. +If the remainder of the sequence does not arrive within the designated +time, +.B \%wgetch +returns the prefix character; +otherwise, +it returns the function key code corresponding to the unique sequence +defined by the terminal. +Consequently, +a user of a +.I curses +application may experience a delay after the escape key is pressed +while +.I curses +disambiguates the input; +see section \*(``EXTENSIONS\*('' below. +If the window is in \*(``no time-out\*('' mode, +the timer does not expire; +it is an infinite +(or very large) +value. +See \fB\%notimeout\fP(3X). +Because function key sequences usually begin with ESC, +the terminal may appear to hang in no time-out mode after the user +presses the escape key. +Generally, +further typing \*(``awakens\*('' +.IR curses "." +.SS "Ungetting Characters" +.B \%ungetch +places +.I c +into the input queue to be returned by the next call to +.BR \%wgetch "." +A single input queue serves all windows associated with the terminal. +.SS "Predefined Key Codes" +The header file +.I \%curses.h +defines the following function key codes. .bP -Except for the special case \fBKEY_RESIZE\fP, -it is necessary to enable \fBkeypad\fR for \fBgetch\fP to return these codes. +Except for the special case of +.BR \%KEY_RESIZE "," +a window's keypad mode must be enabled for +.B \%wgetch +to read these codes from it. .bP Not all of these are necessarily supported on any particular terminal. .bP -The naming convention may seem obscure, with some apparent -misspellings (such as "RSUME" for "resume"). -The names correspond to the long terminfo capability names for the keys, -and were defined long ago, in the 1980s. +The naming convention may seem obscure, +with some apparent misspellings +(such as \*(``RSUME\*('' for \*(``resume\*(''); +the names correspond to the +.I \%term\%info +capability names for the keys, +and were standardized before the IBM PC/AT keyboard layout achieved a +dominant position in industry. .PP +.RS +.\" XXX: Move this list into ncurses(3X), rather than duplicating it in +.\" get_wch(3X) or having that page cross reference this one? .TS -center tab(/) ; -l l . -\fIName\fR/\fIKey\fR \fIname\fR -_ -KEY_BREAK/Break key -KEY_DOWN/The four arrow keys ... -KEY_UP -KEY_LEFT -KEY_RIGHT -KEY_HOME/Home key (upward+left arrow) -KEY_BACKSPACE/Backspace -KEY_F0/T{ -Function keys; space for 64 keys is reserved. +Lb Lb +Lb Lx. +Symbol Key name += +KEY_BREAK Break key +KEY_DOWN Arrow keys +KEY_UP \^ +KEY_LEFT \^ +KEY_RIGHT \^ +KEY_HOME Home key (upward+left arrow) +KEY_BACKSPACE Backspace +KEY_F0 T{ +Function keys; space for 64 keys is reserved T} -KEY_F(\fIn\fR)/T{ -For 0 \(<= \fIn\fR \(<= 63 +KEY_F(\fIn\fP) T{ +Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63 T} -KEY_DL/Delete line -KEY_IL/Insert line -KEY_DC/Delete character -KEY_IC/Insert char or enter insert mode -KEY_EIC/Exit insert char mode -KEY_CLEAR/Clear screen -KEY_EOS/Clear to end of screen -KEY_EOL/Clear to end of line -KEY_SF/Scroll 1 line forward -KEY_SR/Scroll 1 line backward (reverse) -KEY_NPAGE/Next page -KEY_PPAGE/Previous page -KEY_STAB/Set tab -KEY_CTAB/Clear tab -KEY_CATAB/Clear all tabs -KEY_ENTER/Enter or send -KEY_SRESET/Soft (partial) reset -KEY_RESET/Reset or hard reset -KEY_PRINT/Print or copy -KEY_LL/Home down or bottom (lower left) -KEY_A1/Upper left of keypad -KEY_A3/Upper right of keypad -KEY_B2/Center of keypad -KEY_C1/Lower left of keypad -KEY_C3/Lower right of keypad -KEY_BTAB/Back tab key -KEY_BEG/Beg(inning) key -KEY_CANCEL/Cancel key -KEY_CLOSE/Close key -KEY_COMMAND/Cmd (command) key -KEY_COPY/Copy key -KEY_CREATE/Create key -KEY_END/End key -KEY_EXIT/Exit key -KEY_FIND/Find key -KEY_HELP/Help key -KEY_MARK/Mark key -KEY_MESSAGE/Message key -KEY_MOUSE/Mouse event read -KEY_MOVE/Move key -KEY_NEXT/Next object key -KEY_OPEN/Open key -KEY_OPTIONS/Options key -KEY_PREVIOUS/Previous object key -KEY_REDO/Redo key -KEY_REFERENCE/Ref(erence) key -KEY_REFRESH/Refresh key -KEY_REPLACE/Replace key -KEY_RESIZE/Screen resized -KEY_RESTART/Restart key -KEY_RESUME/Resume key -KEY_SAVE/Save key -KEY_SBEG/Shifted beginning key -KEY_SCANCEL/Shifted cancel key -KEY_SCOMMAND/Shifted command key -KEY_SCOPY/Shifted copy key -KEY_SCREATE/Shifted create key -KEY_SDC/Shifted delete char key -KEY_SDL/Shifted delete line key -KEY_SELECT/Select key -KEY_SEND/Shifted end key -KEY_SEOL/Shifted clear line key -KEY_SEXIT/Shifted exit key -KEY_SFIND/Shifted find key -KEY_SHELP/Shifted help key -KEY_SHOME/Shifted home key -KEY_SIC/Shifted input key -KEY_SLEFT/Shifted left arrow key -KEY_SMESSAGE/Shifted message key -KEY_SMOVE/Shifted move key -KEY_SNEXT/Shifted next key -KEY_SOPTIONS/Shifted options key -KEY_SPREVIOUS/Shifted prev key -KEY_SPRINT/Shifted print key -KEY_SREDO/Shifted redo key -KEY_SREPLACE/Shifted replace key -KEY_SRIGHT/Shifted right arrow -KEY_SRSUME/Shifted resume key -KEY_SSAVE/Shifted save key -KEY_SSUSPEND/Shifted suspend key -KEY_SUNDO/Shifted undo key -KEY_SUSPEND/Suspend key -KEY_UNDO/Undo key +KEY_DL Delete line +KEY_IL Insert line +KEY_DC Delete character +KEY_IC Insert character/Enter insert mode +KEY_EIC Exit insert character mode +KEY_CLEAR Clear screen +KEY_EOS Clear to end of screen +KEY_EOL Clear to end of line +KEY_SF Scroll one line forward +KEY_SR Scroll one line backward (reverse) +KEY_NPAGE Next page/Page up +KEY_PPAGE Previous page/Page down +KEY_STAB Set tab +KEY_CTAB Clear tab +KEY_CATAB Clear all tabs +KEY_ENTER Enter/Send +KEY_SRESET Soft (partial) reset +KEY_RESET (Hard) reset +KEY_PRINT Print/Copy +KEY_LL Home down/Bottom (lower left) +KEY_A1 Upper left of keypad +KEY_A3 Upper right of keypad +KEY_B2 Center of keypad +KEY_C1 Lower left of keypad +KEY_C3 Lower right of keypad +KEY_BTAB Back tab key +KEY_BEG Beg(inning) key +KEY_CANCEL Cancel key +KEY_CLOSE Close key +KEY_COMMAND Cmd (command) key +KEY_COPY Copy key +KEY_CREATE Create key +KEY_END End key +KEY_EXIT Exit key +KEY_FIND Find key +KEY_HELP Help key +KEY_MARK Mark key +KEY_MESSAGE Message key +KEY_MOUSE Mouse event occurred +KEY_MOVE Move key +KEY_NEXT Next object key +KEY_OPEN Open key +KEY_OPTIONS Options key +KEY_PREVIOUS Previous object key +KEY_REDO Redo key +KEY_REFERENCE Ref(erence) key +KEY_REFRESH Refresh key +KEY_REPLACE Replace key +KEY_RESIZE Screen resized +KEY_RESTART Restart key +KEY_RESUME Resume key +KEY_SAVE Save key +KEY_SELECT Select key +KEY_SUSPEND Suspend key +KEY_UNDO Undo key +_ +KEY_SBEG Shifted beginning key +KEY_SCANCEL Shifted cancel key +KEY_SCOMMAND Shifted command key +KEY_SCOPY Shifted copy key +KEY_SCREATE Shifted create key +KEY_SDC Shifted delete character key +KEY_SDL Shifted delete line key +KEY_SEND Shifted end key +KEY_SEOL Shifted clear line key +KEY_SEXIT Shifted exit key +KEY_SFIND Shifted find key +KEY_SHELP Shifted help key +KEY_SHOME Shifted home key +KEY_SIC Shifted insert key +KEY_SLEFT Shifted left arrow key +KEY_SMESSAGE Shifted message key +KEY_SMOVE Shifted move key +KEY_SNEXT Shifted next object key +KEY_SOPTIONS Shifted options key +KEY_SPREVIOUS Shifted previous object key +KEY_SPRINT Shifted print key +KEY_SREDO Shifted redo key +KEY_SREPLACE Shifted replace key +KEY_SRIGHT Shifted right arrow key +KEY_SRSUME Shifted resume key +KEY_SSAVE Shifted save key +KEY_SSUSPEND Shifted suspend key +KEY_SUNDO Shifted undo key .TE +.RE .PP -Keypad is arranged like this: -.br +Many keyboards feature a nine-key directional pad. +.PP +.RS .TS -center allbox tab(/) ; -c c c . -\fBA1\fR/\fBup\fR/\fBA3\fR -\fBleft\fR/\fBB2\fR/\fBright\fR -\fBC1\fR/\fBdown\fR/\fBC3\fR +allbox center; +C C C. +A1 up A3 +left B2 right +C1 down C3 .TE +.RE .sp -A few of these predefined values do \fInot\fP correspond to a real key: +Two of the symbols in the list above do +.I not +correspond to a physical key. .bP -.B KEY_RESIZE -is returned when the \fBSIGWINCH\fP signal has been detected -(see \fBinitscr\fP(3X) and \fBresizeterm\fR(3X)). -This code is returned whether or not \fBkeypad\fP has been enabled. +.B \%wgetch +returns +.BR \%KEY_RESIZE "," +even if the window's keypad mode is disabled, +when +.I \%ncurses +handles a +.B \%SIGWINCH +signal; +see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X). .bP -.B KEY_MOUSE -is returned for mouse-events (see \fBcurs_mouse\fR(3X)). -This code relies upon whether or not \fBkeypad\fP(3X) has been enabled, -because (e.g., with \fIxterm\fP mouse prototocol) ncurses must -read escape sequences, -just like a function key. -.SS Testing key-codes -.PP -The \fBhas_key\fR routine takes a key-code value from the above list, and -returns \fBTRUE\fP or \fBFALSE\fP according to whether -the current terminal type recognizes a key with that value. -.PP -The library also supports these extensions: -.RS 3 -.TP 5 -.B define_key -defines a key-code for a given string (see \fBdefine_key\fP(3X)). -.TP 5 -.B key_defined -checks if there is a key-code defined for a given -string (see \fBkey_defined\fP(3X)). -.RE -.PP +.B \%wgetch +returns +.B \%KEY_MOUSE +to indicate that a mouse event is pending collection; +see \fB\%curs_mouse\fP(3X). +Receipt of this code requires a window's keypad mode to be enabled, +because to interpret mouse input +(as with with \fI\%xterm\fP(1)'s mouse protocol), +.I \%ncurses +must read an escape sequence, +as with a function key. +.SS "Testing Key Codes" +In +.IR \%ncurses "," +.B \%has_key +returns a Boolean value indicating whether the terminal type recognizes +its parameter as a key code value. +See also +\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X). .SH RETURN VALUE -All routines return the integer \fBERR\fR upon failure and an integer value -other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful -completion. -.RS 3 -.TP 5 -\fBungetch\fP -returns ERR -if there is no more room in the FIFO. -.TP -\fBwgetch\fP -returns ERR -if the window pointer is null, or -if its timeout expires without having any data. -.RE +Except for +.BR \%has_key "," +these functions return +.B OK +on success and +.B ERR +on failure. +.PP +Functions taking a +.I \%WINDOW +pointer argument fail if the pointer is +.BR NULL "." +.PP +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ")" +is outside the window boundaries. .PP -Functions with a "mv" prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. +.B \%wgetch +also fails if +.bP +its timeout expires without any data arriving, +or +.bP +execution was interrupted by a signal, +in which case +.B \%errno +is set to +.BR \%EINTR "." +.PP +.B \%ungetch +fails if there is no more room in the input queue. +.PP +.B \%has_key +returns +.B TRUE +or +.BR FALSE "." .SH NOTES -Use of the escape key by a programmer for a single character function is -discouraged, as it will cause a delay of up to one second while the -keypad code looks for a following function-key sequence. -.PP -Some keys may be the same as commonly used control -keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H. -Some curses implementations may differ according to whether they -treat these control keys specially (and ignore the terminfo), or -use the terminfo definitions. -\fBNcurses\fR uses the terminfo definition. -If it says that \fBKEY_ENTER\fP is control/M, -\fBgetch\fR will return \fBKEY_ENTER\fP -when you press control/M. -.PP -Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP -key on the numeric keypad: +.BR \%getch "," +.BR \%mvgetch "," +and +.B \%mvwgetch +may be implemented as macros. +.PP +.I curses +discourages assignment of the ESC key to a discrete function by the +programmer because the library requires a delay while it awaits the +potential remainder of a terminal escape sequence. +.PP +Some key strokes are indistinguishable from control characters; +for example, +.B \%KEY_ENTER +may be the same as +.BR \*^M "," +.\" as with att630 or pccon+keys +and +.B \%KEY_BACKSPACE +may be the same as +.B \*^H +.\" as with att505 or vt52-basic +or +.BR \*^? "." +.\" as with pccon+keys or vt320 +Consult the +.I \%term\%info +entry for the terminal type to determine whether this is the case; +see \fB\%infocmp\fP(1). +Some +.I curses +implementations, +including +.IR \%ncurses "," +honor the +.I \%term\%info +key definitions; +others treat such control characters specially. +.PP +.I curses +distinguishes the Enter keys in the alphabetic and numeric keypad +sections of a keyboard because (most) terminals do. +.B \%KEY_ENTER +refers to the key on the numeric keypad and, +like other function keys, +is reliably recognized only if the window's keypad mode is enabled. .bP -the terminal description lists the most useful keys, +The +.I \%term\%info +.B \%key_enter +.RB ( kent ) +capability describes the character (sequence) sent by the Enter key of +a terminal's numeric +(or similar) +keypad. .bP -the \fIEnter\fP key on the regular keyboard is already handled by -the standard ASCII characters for carriage-return and line-feed, +\*(``Enter or send\*('' is X/Open Curses's description of this key. +.PP +.I curses +treats the Enter or Return key in the +.I alphabetic +section of the keyboard differently. .bP -depending on whether \fBnl\fP or \fBnonl\fP was called, -pressing "Enter" on the regular keyboard may return either a carriage-return -or line-feed, and finally +It usually produces a control code for carriage return +.RB ( \*^M ) +or line feed +.RB ( \*^J ). .bP -"Enter or send" is the standard description for this key. -.PP -When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or -\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode -(\fBecho\fR) should not be used at the same time. -Depending on the -state of the tty driver when each character is typed, the program may -produce undesirable results. -.PP -Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros. -.PP -Historically, the set of keypad macros was largely defined by the extremely -function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4. -Modern -personal computers usually have only a small subset of these. -IBM PC-style -consoles typically support little more than \fBKEY_UP\fR, \fBKEY_DOWN\fR, -\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR, -\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. -The Ins key -is usually mapped to \fBKEY_IC\fR. +Depending on the terminal mode +(raw, +cbreak, +or +\*(``cooked\*(''), +and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called, +.B \%wgetch +may return either a carriage return or line feed upon an Enter or Return +key stroke. +.PP +Use of +.B \%wgetch +with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X) +is not well-defined. +.PP +Historically, +the list of key code macros above was influenced by the keyboard of the +AT&T 7300 +(also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and +\*(``UNIX PC\*(''), +a 1985 machine rich in function keys. +Today's computer keyboards are based on that of the IBM PC/AT +and tend to have fewer. +A +.I curses +application can expect such a keyboard to transmit key codes +.BR \%KEY_UP "," +.BR \%KEY_DOWN "," +.BR \%KEY_LEFT "," +.BR \%KEY_RIGHT "," +.BR \%KEY_HOME "," +.BR \%KEY_END "," +.B \%KEY_PPAGE +(Page Up), +.B \%KEY_NPAGE +(Page Down), +.B \%KEY_IC +(Insert), +.B \%KEY_DC +(Delete), +and +.BI \%KEY_F( n ) +for 1 \(<= +.I n +\(<= 12. +.SH EXTENSIONS +In +.IR \%ncurses "," +when a window's \*(``no time-out\*('' mode is +.I not +set, +the +.B \%ESCDELAY +variable configures the duration of the timer used to disambiguate a +function key character sequence from a series of key strokes beginning +with ESC typed by the user; +see +\fB\%curs_variables\fP(3X). +.PP +.B \%has_key +was designed for +.IR \%ncurses "," +and is not found in SVr4 +.IR curses "," +4.4BSD +.IR curses "," +or any other previous +.I curses +implementation. .SH PORTABILITY -The *get* functions are described in the XSI Curses standard, Issue 4. -They -read single-byte characters only. -The standard specifies that they return -\fBERR\fR on failure, but specifies no error conditions. -.PP -The echo behavior of these functions on input of \fBKEY_\fR or backspace -characters was not specified in the SVr4 documentation. -This description is -adopted from the XSI Curses standard. -.PP -The behavior of \fBgetch\fR and friends in the presence of handled signals is -unspecified in the SVr4 and XSI Curses documentation. -Under historical curses -implementations, it varied depending on whether the operating system's -implementation of handled signal receipt interrupts a \fBread\fR(2) call in -progress or not, and also (in some implementations) depending on whether an -input timeout or non-blocking mode has been set. -.PP -\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related -terminfo capabilities, but no higher-level functions use the feature. -The implementation in ncurses is an extension. -.PP -\fBKEY_RESIZE\fP is an extension first implemented for ncurses. -NetBSD curses later added this extension. -.PP -Programmers concerned about portability should be prepared for either of two -cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt -interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to -\fBEINTR\fR. -Under the \fBncurses\fR implementation, handled signals never -interrupt \fBgetch\fR. -.PP -The \fBhas_key\fR function is unique to \fBncurses\fR. -We recommend that -any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro. +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 +.B \%wgetch +reads only single-byte characters. +.PP +The echo behavior of these functions on input of +.B KEY_ +or backspace characters was not specified in the SVr4 documentation. +This description is adapted from X/Open Curses. +.PP +The behavior of +.B \%wgetch +in the presence of signal handlers is unspecified in the SVr4 +documentation and X/Open Curses. +In historical +.I curses +implementations, +it varied depending on whether the operating system's dispatch of a +signal to a handler interrupted a \fIread\fP(2) call in progress, +and also +(in some implementations) +whether an input timeout or non-blocking mode had been set. +A portable +.I curses +application prepares for two cases: +(a) signal receipt does not interrupt +.BR \%wgetch ";" +or +(b) signal receipt interrupts +.B \%wgetch +and causes it to return +.B ERR +with +.B \%errno +set to +.BR \%EINTR "." +.PP +.B \%KEY_MOUSE +is mentioned in X/Open Curses, +along with a few related +.I \%term\%info +capabilities, +but no higher-level functions use the feature. +The implementation in +.I \%ncurses +is an extension. +.PP +.B \%KEY_RESIZE +and +.B \%has_key +are extensions first implemented for +.IR \%ncurses "." +By 2022, +.I \%PDCurses +.\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html +and +NetBSD +.I curses +.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3 +had added them along with +.BR \%KEY_MOUSE "." .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_inopts\fR(3X), -\fBcurs_outopts\fR(3X), -\fBcurs_mouse\fR(3X), -\fBcurs_move\fR(3X), -\fBcurs_refresh\fR(3X), -\fBresizeterm\fR(3X). -.PP -Comparable functions in the wide-character (ncursesw) library are -described in -\fBcurs_get_wch\fR(3X). +ECMA-6 \*(``7-bit coded Character Set\*('' +\% +.PP +ECMA-48 \*(``Control Functions for Coded Character Sets\*('' +\% +.PP +\fB\%curs_get_wch\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI \%( ncursesw ). +.PP +\fB\%curses\fP(3X), +\fB\%curs_addch\fP(3X), +\fB\%curs_inopts\fP(3X), +\fB\%curs_mouse\fP(3X), +\fB\%curs_move\fP(3X), +\fB\%curs_outopts\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_variables\fP(3X), +\fB\%resizeterm\fP(3X), +\fB\%ascii\fP(7)