'\" t.\"***************************************************************************.\" Copyright (c) 1998-2002,2003 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            *.\" "Software"), to deal in the Software without restriction, including      *.\" without limitation the rights to use, copy, modify, merge, publish,      *.\" distribute, distribute with modifications, sublicense, and/or sell       *.\" copies of the Software, and to permit persons to whom the Software is    *.\" furnished to do so, subject to the following conditions:                 *.\"                                                                          *.\" The above copyright notice and this permission notice shall be included  *.\" in all copies or substantial portions of the Software.                   *.\"                                                                          *.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *.\"                                                                          *.\" Except as contained in this notice, the name(s) of the above copyright   *.\" holders shall not be used in advertising or otherwise to promote the     *.\" sale, use or other dealings in this Software without prior written       *.\" authorization.                                                           *.\"***************************************************************************.\".\" $Id: curs_getch.3x,v 1.24 2003/12/27 18:46:06 tom Exp $.TH curs_getch 3X "".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.SH SYNOPSIS\fB#include <curses.h>\fR.PP\fBint getch(void);\fR.br\fBint wgetch(WINDOW *win);\fR.br\fBint mvgetch(int y, int x);\fR.br\fBint mvwgetch(WINDOW *win, int y, int x);\fR.br\fBint ungetch(int ch);\fR.br\fBint has_key(int ch);\fR.br.SH DESCRIPTIONThe \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines reada 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 systempasses 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 thespecified timeout has been reached..PPUnless \fBnoecho\fR has been set,then the character will also be echoed into thedesignated window according to the following rules: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 erasedas if \fBdelch\fR had been called.If the character value is any other \fBKEY_\fR define, the user is alertedwith a \fBbeep\fR call.Otherwise the character is simply output to the screen..PPIf the window is not a pad, and it has been moved or modified since the lastcall to \fBwrefresh\fR, \fBwrefresh\fR will be called before another characteris read..PPIf \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token forthat function key is returned instead of the raw characters.Possible functionkeys are defined in \fB<curses.h>\fR as macros with values outside the rangeof 8-bit characters whose names begin with \fBKEY_\fR. Thus, a variableintended to hold the return value of a function key must be of short size orlarger..PPWhen 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 designatedtime, the character is passed through;otherwise, the function key value is returned.For this reason, many terminals experience a delay between the timea user presses the escape key and the escape is returned to the program..PPThe \fBungetch\fR routine places \fIch\fR back onto the input queue to bereturned by the next call to \fBwgetch\fR.There is just one input queue for all windows..PP.SS Function KeysThe following function keys, defined in \fB<curses.h>\fR, might be returned by\fBgetch\fR if \fBkeypad\fR has been enabled.Note that not all of these arenecessarily supported on any particular terminal..sp.TScenter tab(/) ;l ll l .\fIName\fR/\fIKey\fR \fIname\fR.PPKEY_BREAK/Break keyKEY_DOWN/The four arrow keys ...KEY_UPKEY_LEFTKEY_RIGHTKEY_HOME/Home key (upward+left arrow)KEY_BACKSPACE/BackspaceKEY_F0/T{Function keys; space for 64 keys is reserved.T}KEY_F(\fIn\fR)/T{For 0 \(<= \fIn\fR \(<= 63T}KEY_DL/Delete lineKEY_IL/Insert lineKEY_DC/Delete characterKEY_IC/Insert char or enter insert modeKEY_EIC/Exit insert char modeKEY_CLEAR/Clear screenKEY_EOS/Clear to end of screenKEY_EOL/Clear to end of lineKEY_SF/Scroll 1 line forwardKEY_SR/Scroll 1 line backward (reverse)KEY_NPAGE/Next pageKEY_PPAGE/Previous pageKEY_STAB/Set tabKEY_CTAB/Clear tabKEY_CATAB/Clear all tabsKEY_ENTER/Enter or sendKEY_SRESET/Soft (partial) resetKEY_RESET/Reset or hard resetKEY_PRINT/Print or copyKEY_LL/Home down or bottom (lower left)KEY_A1/Upper left of keypadKEY_A3/Upper right of keypadKEY_B2/Center of keypadKEY_C1/Lower left of keypadKEY_C3/Lower right of keypadKEY_BTAB/Back tab keyKEY_BEG/Beg(inning) keyKEY_CANCEL/Cancel keyKEY_CLOSE/Close keyKEY_COMMAND/Cmd (command) keyKEY_COPY/Copy keyKEY_CREATE/Create keyKEY_END/End keyKEY_EXIT/Exit keyKEY_FIND/Find keyKEY_HELP/Help keyKEY_MARK/Mark keyKEY_MESSAGE/Message keyKEY_MOUSE/Mouse event readKEY_MOVE/Move keyKEY_NEXT/Next object keyKEY_OPEN/Open keyKEY_OPTIONS/Options keyKEY_PREVIOUS/Previous object keyKEY_REDO/Redo keyKEY_REFERENCE/Ref(erence) keyKEY_REFRESH/Refresh keyKEY_REPLACE/Replace keyKEY_RESIZE/Screen resizedKEY_RESTART/Restart keyKEY_RESUME/Resume keyKEY_SAVE/Save keyKEY_SBEG/Shifted beginning keyKEY_SCANCEL/Shifted cancel keyKEY_SCOMMAND/Shifted command keyKEY_SCOPY/Shifted copy keyKEY_SCREATE/Shifted create keyKEY_SDC/Shifted delete char keyKEY_SDL/Shifted delete line keyKEY_SELECT/Select keyKEY_SEND/Shifted end keyKEY_SEOL/Shifted clear line keyKEY_SEXIT/Shifted exit keyKEY_SFIND/Shifted find keyKEY_SHELP/Shifted help keyKEY_SHOME/Shifted home keyKEY_SIC/Shifted input keyKEY_SLEFT/Shifted left arrow keyKEY_SMESSAGE/Shifted message keyKEY_SMOVE/Shifted move keyKEY_SNEXT/Shifted next keyKEY_SOPTIONS/Shifted options keyKEY_SPREVIOUS/Shifted prev keyKEY_SPRINT/Shifted print keyKEY_SREDO/Shifted redo keyKEY_SREPLACE/Shifted replace keyKEY_SRIGHT/Shifted right arrowKEY_SRSUME/Shifted resume keyKEY_SSAVE/Shifted save keyKEY_SSUSPEND/Shifted suspend keyKEY_SUNDO/Shifted undo keyKEY_SUSPEND/Suspend keyKEY_UNDO/Undo key.TE.PPKeypad is arranged like this:.sp.TScenter allbox tab(/) ;c c c .\fBA1\fR/\fBup\fR/\fBA3\fR\fBleft\fR/\fBB2\fR/\fBright\fR\fBC1\fR/\fBdown\fR/\fBC3\fR.TE.spThe \fBhas_key\fR routine takes a key value from the above list, andreturns TRUE or FALSE according to whetherthe current terminal type recognizes a key with that value.Note that a few values do not correspond to a real key,e.g., KEY_RESIZE and KEY_MOUSE..PP.SH RETURN VALUEAll routines return the integer \fBERR\fR upon failure and an integer valueother than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successfulcompletion..SH NOTESUse of the escape key by a programmer for a single character function isdiscouraged, as it will cause a delay of up to one second while thekeypad code looks for a following function-key sequence..PPNote that some keys may be the same as commonly used controlkeys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus control/H.Some curses implementations may differ according to whether theytreat these control keys specially (and ignore the terminfo), oruse the terminfo definitions.\fBNcurses\fR uses the terminfo definition.If it says that KEY_ENTER is control/M, \fBgetch\fR will return KEY_ENTERwhen you press control/M..PPWhen 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 thestate of the tty driver when each character is typed, the program mayproduce undesirable results..PPNote that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros..PPHistorically, the set of keypad macros was largely defined by the extremelyfunction-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4.Modernpersonal computers usually have only a small subset of these.IBM PC-styleconsoles 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 keyis usually mapped to \fBKEY_IC\fR..SH PORTABILITYThe *get* functions are described in the XSI Curses standard, Issue 4.Theyread single-byte characters only.The standard specifies that they return\fBERR\fR on failure, but specifies no error conditions..PPThe echo behavior of these functions on input of \fBKEY_\fR or backspacecharacters was not specified in the SVr4 documentation.This description isadopted from the XSI Curses standard..PPThe behavior of \fBgetch\fR and friends in the presence of handled signals isunspecified in the SVr4 and XSI Curses documentation.Under historical cursesimplementations, it varied depending on whether the operating system'simplementation of handled signal receipt interrupts a \fBread\fR(2) call inprogress or not, and also (in some implementations) depending on whether aninput timeout or non-blocking mode has been set..PPProgrammers concerned about portability should be prepared for either of twocases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receiptinterrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to\fBEINTR\fR.Under the \fBncurses\fR implementation, handled signals neverinterrupt \fBgetch\fR..PPThe \fBhas_key\fR function is unique to \fBncurses\fR.We recommend thatany code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro..SH SEE ALSO\fBcurses\fR(3X),\fBcurs_inopts\fR(3X),\fBcurs_mouse\fR(3X),\fBcurs_move\fR(3X),\fBcurs_refresh\fR(3X).\fBresizeterm\fR(3X)..\"#.\"# The following sets edit modes for GNU EMACS.\"# Local Variables:.\"# mode:nroff.\"# fill-column:79.\"# End: