CURSES_INPUT(3)         NetBSD Library Functions Manual        CURSES_INPUT(3)

NAME
     curses_input, getch, wgetch, mvgetch, mvwgetch, define_key, keyok,
     getnstr, wgetnstr, mvgetnstr, mvwgetnstr, getstr, wgetstr, mvgetstr,
     mvwgetstr, keypad, notimeout, timeout, wtimeout, nodelay, ungetch --
     curses input stream routines

LIBRARY
     Curses Library (libcurses, -lcurses)

SYNOPSIS
     #include <curses.h>

     int
     getch(void);

     int
     wgetch(WINDOW *win);

     int
     mvgetch(int y, int x);

     int
     mvwgetch(WINDOW *win, int y, int x);

     int
     keyok(int key_symbol, bool flag);

     int
     define_key(char *sequence, int key_symbol);

     int
     getnstr(char *str, int limit);

     int
     wgetnstr(WINDOW *win, char *str, int limit);

     int
     mvgetnstr(int y, int x, char *str, int limit);

     int
     mvwgetnstr(WINDOW *win, int y, int x, char *str, int limit);

     int
     getstr(char *str);

     int
     wgetstr(WINDOW *win, char *str);

     int
     mvgetstr(int y, int x, char *str);

     int
     mvwgetstr(WINDOW *win, int y, int x, char *str);

     int
     keypad(WINDOW *win, boolf flag);

     int
     notimeout(WINDOW *win, boolf flag);

     int
     timeout(int delay);

     int
     wtimeout(WINDOW *win, int delay);

     int
     nodelay(WINDOW *win, boolf flag);

     int
     ungetch(int c);

     extern int ESCDELAY;

DESCRIPTION
     These functions read characters and strings from the window input file
     descriptor.

     The getch() function reads a character from the stdscr input file
     descriptor and returns it.  If the keypad() flag has been set to TRUE,
     then getch() will assemble multi-character key sequences into key sym-
     bols, If the terminal is resized, getch() will return KEY_RESIZE, regard-
     lesss of the setting of keypad().  Calling getch() will cause an implicit
     refresh() on stdscr.

     The wgetch() function is the same as the getch() function, excepting that
     it reads from the input file descriptor associated with the window speci-
     fied by win.

     If the keypad() flag is TRUE then the assembly of specific key symbols
     can be disabled by using the keyok() function.  If the flag is set to
     FALSE on a key symbol then getch() will behave as if the character
     sequence associated with that key symbol was not recognised and will
     return the component characters one at a time to the caller.

     Custom associations between sequences of characters and a key symbol can
     be made by using the define_key() function.  Normally, these associations
     are made by the information in the termcap(5) database but the
     define_key() function gives the capability to remove or add more associa-
     tions.  If define_key() is passed a non-NULL string in sequence it will
     associate that sequence with the key symbol passed in key_symbol.  The
     key symbol may be one of the ones listed below or a custom value that is
     application defined.  It is valid to have multiple character sequences
     map to the same key symbol and there are no constraints on the length of
     the sequence allowed.  The assembly of custom sequences follow the same
     rules for inter-character timing and so forth as the termcap(5) derived
     ones.  If define_key() is passed a NULL in sequence then all associations
     for the key symbol in key_symbol will be deleted, this includes any asso-
     ciations that were derived from termcap(5).

     The mvgetch() and mvwgetch() functions are the same as the getch() and
     wgetch() functions, respectively, excepting that wmove() is called to
     move the cursor to the position specified by y, x before the character is
     read.

     Calling getnstr(), wgetnstr(), mvgetnstr() or mvwgetnstr() is effectively
     the same as calling getch() repeatedly until a newline is received or the
     character limit limit is reached.  Once this happens the string is NULL
     terminated and returned in str.  During input, the normal curses input
     key processing is performed and affects the input buffer.  The
     mvgetnstr() function calls wmove() to move the cursor to the position
     given by y, x before getting the string, wgetnstr() reads the input from
     the designated window, mvwgetnstr() moves the cursor to the position
     given by y, x before getting the input from the designated window.

     The functions getstr(), wgetstr(), mvgetstr(), and mvwgetstr() are simi-
     lar to getnstr(), wgetnstr(), mvgetnstr(), and mvwgetnstr(), respec-
     tively, excepting that there is no limit on the number of characters that
     may be inserted into str.  This may cause the buffer to be overflowed, so
     their use is not recommended.

     The keypad() function is used to affect how getch() processes input char-
     acters.  If flag is set to TRUE, then getch() will scan the input stream
     looking for multi-character key sequences that are emitted by some termi-
     nal function keys.  If a recognised sequence of characters is found, then
     getch() will collapse that sequence into an integer key symbol, as shown
     below.  The default setting for the flag is FALSE.

     The notimeout() function controls whether or not getch() will wait indef-
     initely between characters in a multi-character key sequence or not.  If
     flag is TRUE, then there is no timeout applied between characters com-
     prising a multi-character key sequence.  If flag is FALSE, then the com-
     ponent characters of a multi-character sequence must not have an inter-
     character gap of more than ESCDELAY.  If this timing is exceeded, then
     the multi-character key assembly is deemed to have failed and the charac-
     ters read thus far are returned one at a time when getch() is called.
     The default setting for the flag is FALSE.  The default value of ESCDELAY
     is 300ms.  If ESCDELAY is negative, no timeout is applied between charac-
     ters comprising a multi-character key sequence.

     The timeout() function affects the behaviour of getch() when reading a
     character from stdscr.  If delay is negative, then getch() will block
     indefinitely on a read.  If delay is 0, then getch() will return immedi-
     ately with ERR if there are no characters immediately available.  If
     delay is a positive number, then getch() will wait for that many mil-
     liseconds before returning and, if no character was available, then ERR
     will be returned.  Note that for a positive number, the timeout is only
     accurate to the nearest tenth of a second.  Also, the maximum value of
     delay is 25500 milliseconds.  The wtimeout() function does the same as
     timeout() but applies to the specified window win.

     The nodelay() function turns on and off blocking reads for getch().  If
     flag is TRUE, then getch() will not block on reads, if flag is FALSE,
     then reads will block.  The default setting for the flag is FALSE.
     nodelay(win, TRUE) is equivalent to wtimeout(win, 0) and nodelay(win,
     FALSE) is equivalent to wtimeout(win, -1).

     ungetch() will convert c into an unsigned char and push that character
     back onto the input stream.  Only one character of push-back is guaran-
     teed to work, more may be possible depending on system resources.

RETURN VALUES
     The functions getch(), wgetch(), mvgetch(), and mvwgetch() will return
     the value of the key pressed or ERR in the case of an error or a timeout.
     Additionally, if keypad(TRUE) has been called on a window, then it may
     return one of the following values:

           Termcap entry    getch Return Value    Key Function
           !1               KEY_SSAVE             Shift Save
           !2               KEY_SSUSPEND          Shift Suspend
           !3               KEY_SUNDO             Shift Undo
           #1               KEY_SHELP             Shift Help
           #2               KEY_SHOME             Shift Home
           #3               KEY_SIC               Shift Insert Character
           #4               KEY_SLEFT             Shift Left Arrow
           %0               KEY_REDO              Redo
           %1               KEY_HELP              Help
           %2               KEY_MARK              Mark
           %3               KEY_MESSAGE           Message
           %4               KEY_MOVE              Move
           %5               KEY_NEXT              Next Object
           %6               KEY_OPEN              Open
           %7               KEY_OPTIONS           Options
           %8               KEY_PREVIOUS          Previous Object
           %9               KEY_PRINT             Print
           %a               KEY_SMESSAGE          Shift Message
           %b               KEY_SMOVE             Shift Move
           %c               KEY_SNEXT             Shift Next Object
           %d               KEY_SOPTIONS          Shift Options
           %e               KEY_SPREVIOUS         Shift Previous Object
           %f               KEY_SPRINT            Shift Print
           %g               KEY_SREDO             Shift Redo
           %h               KEY_SREPLACE          Shift Replace
           %i               KEY_SRIGHT            Shift Right Arrow
           %j               KEY_SRSUME            Shift Resume
           &0               KEY_SCANCEL           Shift Cancel
           &1               KEY_REFERENCE         Reference
           &2               KEY_REFRESH           Refresh
           &3               KEY_REPLACE           Replace
           &4               KEY_RESTART           Restart
           &5               KEY_RESUME            Resume
           &6               KEY_SAVE              Save
           &7               KEY_SUSPEND           Suspend
           &8               KEY_UNDO              Undo
           &9               KEY_SBEG              Shift Begin
           *0               KEY_SFIND             Shift Find
           *1               KEY_SCOMMAND          Shift Command
           *2               KEY_SCOPY             Shift Copy
           *3               KEY_SCREATE           Shift Create
           *4               KEY_SDC               Shift Delete Character
           *5               KEY_SDL               Shift Delete Line
           *6               KEY_SELECT            Select
           *7               KEY_SEND              Shift End
           *8               KEY_SEOL              Shift Clear to EOL
           *9               KEY_SEXIT             Shift Exit
           @0               KEY_FIND              Find
           @1               KEY_BEG               Begin
           @2               KEY_CANCEL            Cancel
           @3               KEY_CLOSE             Close
           @4               KEY_COMMAND           Command
           @5               KEY_COPY              Copy
           @6               KEY_CREATE            Create
           @7               KEY_END               End
           @8               KEY_ENTER             Enter
           @9               KEY_EXIT              Exit
           F1               KEY_F(11)             Function Key 11
           F2               KEY_F(12)             Function Key 12
           F3               KEY_F(13)             Function Key 13
           F4               KEY_F(14)             Function Key 14
           F5               KEY_F(15)             Function Key 15
           F6               KEY_F(16)             Function Key 16
           F7               KEY_F(17)             Function Key 17
           F8               KEY_F(18)             Function Key 18
           F9               KEY_F(19)             Function Key 19
           FA               KEY_F(20)             Function Key 20
           FB               KEY_F(21)             Function Key 21
           FC               KEY_F(22)             Function Key 22
           FD               KEY_F(23)             Function Key 23
           FE               KEY_F(24)             Function Key 24
           FF               KEY_F(25)             Function Key 25
           FG               KEY_F(26)             Function Key 26
           FH               KEY_F(27)             Function Key 27
           FI               KEY_F(28)             Function Key 28
           FJ               KEY_F(29)             Function Key 29
           FK               KEY_F(30)             Function Key 30
           FL               KEY_F(31)             Function Key 31
           FM               KEY_F(32)             Function Key 32
           FN               KEY_F(33)             Function Key 33
           FO               KEY_F(34)             Function Key 34
           FP               KEY_F(35)             Function Key 35
           FQ               KEY_F(36)             Function Key 36
           FR               KEY_F(37)             Function Key 37
           FS               KEY_F(38)             Function Key 38
           FT               KEY_F(39)             Function Key 39
           FU               KEY_F(40)             Function Key 40
           FV               KEY_F(41)             Function Key 41
           FW               KEY_F(42)             Function Key 42
           FX               KEY_F(43)             Function Key 43
           FY               KEY_F(44)             Function Key 44
           FZ               KEY_F(45)             Function Key 45
           Fa               KEY_F(46)             Function Key 46
           Fb               KEY_F(47)             Function Key 47
           Fc               KEY_F(48)             Function Key 48
           Fd               KEY_F(49)             Function Key 49
           Fe               KEY_F(50)             Function Key 50
           Ff               KEY_F(51)             Function Key 51
           Fg               KEY_F(52)             Function Key 52
           Fh               KEY_F(53)             Function Key 53
           Fi               KEY_F(54)             Function Key 54
           Fj               KEY_F(55)             Function Key 55
           Fk               KEY_F(56)             Function Key 56
           Fl               KEY_F(57)             Function Key 57
           Fm               KEY_F(58)             Function Key 58
           Fn               KEY_F(59)             Function Key 59
           Fo               KEY_F(60)             Function Key 60
           Fp               KEY_F(61)             Function Key 61
           Fq               KEY_F(62)             Function Key 62
           Fr               KEY_F(63)             Function Key 63
           K1               KEY_A1                Upper left key in keypad
           K2               KEY_B2                Centre key in keypad
           K3               KEY_A3                Upper right key in keypad
           K4               KEY_C1                Lower left key in keypad
           K5               KEY_C3                Lower right key in keypad
           Km               KEY_MOUSE             Mouse Event
           k0               KEY_F0                Function Key 0
           k1               KEY_F(1)              Function Key 1
           k2               KEY_F(2)              Function Key 2
           k3               KEY_F(3)              Function Key 3
           k4               KEY_F(4)              Function Key 4
           k5               KEY_F(5)              Function Key 5
           k6               KEY_F(6)              Function Key 6
           k7               KEY_F(7)              Function Key 7
           k8               KEY_F(8)              Function Key 8
           k9               KEY_F(9)              Function Key 9
           k;               KEY_F(10)             Function Key 10
           kA               KEY_IL                Insert Line
           ka               KEY_CATAB             Clear All Tabs
           kB               KEY_BTAB              Back Tab
           kb               KEY_BACKSPACE         Backspace
           kC               KEY_CLEAR             Clear
           kD               KEY_DC                Delete Character
           kd               KEY_DOWN              Down Arrow
           kE               KEY_EOL               Clear to End Of Line
           kF               KEY_SF                Scroll Forward one line
           kH               KEY_LL                Home Down
           kh               KEY_HOME              Home
           kI               KEY_IC                Insert Character
           kL               KEY_DL                Delete Line
           kl               KEY_LEFT              Left Arrow
           kM               KEY_EIC               Exit Insert Character Mode
           kN               KEY_NPAGE             Next Page
           kP               KEY_PPAGE             Previous Page
           kR               KEY_SR                Scroll One Line Back
           kr               KEY_RIGHT             Right Arrow
           kS               KEY_EOS               Clear to End Of Screen
           kT               KEY_STAB              Set Tab
           kt               KEY_CTAB              Clear Tab
           ku               KEY_UP                Up Arrow

     Note that not all terminals are capable of generating all the keycodes
     listed above nor are termcap entries normally configured with all the
     above capabilities defined.

     Other functions that return an int will return one of the following val-
     ues:

     OK   The function completed successfully.
     ERR  An error occurred in the function.

     Functions returning pointers will return NULL if an error is detected.

SEE ALSO
     curses_cursor(3), curses_keyname(3), curses_refresh(3), curses_tty(3),
     termcap(5)

STANDARDS
     The NetBSD Curses library complies with the X/Open Curses specification,
     part of the Single Unix Specification.

NOTES
     The keyok() and define_key() functions are implementations of extensions
     made by the NCurses library to the Curses standard.  Portable implementa-
     tions should avoid the use of these functions.

HISTORY
     The Curses package appeared in 4.0BSD.

NetBSD 5.0_STABLE                July 25, 2006               NetBSD 5.0_STABLE
