MirOS Manual: curs_getch(3), getch(3), has_key(3), mvgetch(3), mvwgetch(3), ungetch(3), wgetch(3)


curs_getch(3)       UNIX Programmer's Manual        curs_getch(3)

NAME

     getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get (or
     push back) characters from curses terminal keyboard

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 ungetch(int ch);
     int has_key(int ch);

DESCRIPTION

     The getch, wgetch, mvgetch and  mvwgetch,  routines  read  a
     character  from the window. In no-delay mode, if no input is
     waiting, the value ERR is returned. In delay mode, the  pro-
     gram  waits until the system passes text through to the pro-
     gram. Depending on the setting of cbreak, this is after  one
     character  (cbreak  mode),  or after the first newline (noc-
     break mode). In half-delay mode, the program waits  until  a
     character  is  typed  or  the  specified  timeout  has  been
     reached.

     Unless noecho has been set, then the character will also  be
     echoed into the designated 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 erased as if delch had been
     called. If the character value is any other KEY_ define, the
     user is alerted with a beep call. Otherwise the character is
     simply output to the screen.

     If the window is not a pad, and it has been moved  or  modi-
     fied  since  the  last  call  to  wrefresh, wrefresh will be
     called before another character is read.

     If keypad is TRUE, and a function key is pressed, the  token
     for that function key is returned instead of the raw charac-
     ters. Possible function keys are defined  in  <curses.h>  as
     macros  with  values  outside  the range of 8-bit characters
     whose names begin with KEY_. Thus, a  variable  intended  to
     hold  the  return  value  of a function key must be of short
     size or larger.

     When a character that could be the beginning of  a  function
     key is received (which, on modern terminals, means an escape
     character), curses sets a timer. If the remainder of the se-
     quence  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 experi-

MirOS BSD #10-current  Printed 03.04.2017                       1

curs_getch(3)       UNIX Programmer's Manual        curs_getch(3)

     ence a delay between the time a user presses the escape  key
     and the escape is returned to the program.

     The ungetch routine places ch back onto the input  queue  to
     be  returned  by  the next call to wgetch. There is just one
     input queue for all windows.

     Function Keys
     The following function keys, defined in <curses.h>, might be
     returned  by getch if keypad has been enabled. Note that not
     all of these are necessarily  supported  on  any  particular
     terminal.

           Name            Key name
           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          Function keys; space for 64 keys
                           is reserved.
           KEY_F(n)        For 0 ≤ n ≤ 63
           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

MirOS BSD #10-current  Printed 03.04.2017                       2

curs_getch(3)       UNIX Programmer's Manual        curs_getch(3)

           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

MirOS BSD #10-current  Printed 03.04.2017                       3

curs_getch(3)       UNIX Programmer's Manual        curs_getch(3)

           KEY_SUNDO       Shifted undo key
           KEY_SUSPEND     Suspend key
           KEY_UNDO        Undo key

     Keypad is arranged like this:

                        _____________________
                       |  A1 |   up |   A3  |
                       |_____|______|_______|
                       | left|   B2 |  right|
                       |_____|______|_______|
                       |  C1 |  down|   C3  |
                       |_____|______|_______|

     The has_key routine takes a key value from the  above  list,
     and  returns  TRUE or FALSE according to whether the 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. See  resizeterm(3)  for  more  details  about
     KEY_RESIZE, and curs_mouse(3) for a discussion of KEY_MOUSE.

RETURN VALUE

     All routines return the integer ERR upon failure and an  in-
     teger  value  other  than  ERR (OK in the case of ungetch())
     upon successful completion.

          ungetch
               returns an error if there is no more room  in  the
               FIFO.

          wgetch
               returns an error if the window pointer is null, or
               if its timeout expires without having any data.

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.

     Note that some keys may be the same as commonly used control
     keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus
     control/H. Some curses implementations may differ  according
     to  whether they treat these control keys specially (and ig-
     nore the terminfo), or use the terminfo definitions. Ncurses
     uses  the  terminfo definition. If it says that KEY_ENTER is
     control/M,  getch  will  return  KEY_ENTER  when  you  press
     control/M.

     When using getch, wgetch,  mvgetch,  or  mvwgetch,  nocbreak
     mode  (nocbreak)  and echo mode (echo) should not be used at
     the same time. Depending on the state of the tty driver when

MirOS BSD #10-current  Printed 03.04.2017                       4

curs_getch(3)       UNIX Programmer's Manual        curs_getch(3)

     each character is typed, the program may produce undesirable
     results.

     Note that getch, mvgetch, and mvwgetch may be macros.

     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  usu-
     ally  have  only  a small subset of these. IBM PC-style con-
     soles typically support little more than  KEY_UP,  KEY_DOWN,
     KEY_LEFT,    KEY_RIGHT,    KEY_HOME,   KEY_END,   KEY_NPAGE,
     KEY_PPAGE, and function keys 1 through 12. The  Ins  key  is
     usually mapped to KEY_IC.

PORTABILITY

     The *get* functions are described in the  XSI  Curses  stan-
     dard,  Issue  4.  They read single-byte characters only. The
     standard specifies that they  return  ERR  on  failure,  but
     specifies no error conditions.

     The echo behavior of these functions on  input  of  KEY_  or
     backspace  characters was not specified in the SVr4 documen-
     tation. This description is  adopted  from  the  XSI  Curses
     standard.

     The behavior of getch and friends in the presence of handled
     signals is unspecified in the SVr4 and XSI Curses documenta-
     tion. Under historical  curses  implementations,  it  varied
     depending  on  whether the operating system's implementation
     of handled signal receipt interrupts a read(2) call in  pro-
     gress  or  not, and also (in some implementations) depending
     on whether an input timeout or non-blocking  mode  has  been
     set.

     Programmers concerned about portability should  be  prepared
     for  either of two cases: (a) signal receipt does not inter-
     rupt getch; (b) signal receipt interrupts getch  and  causes
     it  to return ERR with errno set to EINTR. Under the ncurses
     implementation, handled signals never interrupt getch.

     The has_key function is unique to ncurses. We recommend that
     any  code using it be conditionalized on the NCURSES_VERSION
     feature macro.

SEE ALSO

     curses(3),  curs_inopts(3),   curs_mouse(3),   curs_move(3),
     curs_refresh(3), resizeterm(3).

MirOS BSD #10-current  Printed 03.04.2017                       5

Generated on 2017-04-03 16:26:17 by $MirOS: src/scripts/roff2htm,v 1.88 2017/01/29 00:51:06 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002–2017 The MirOS Project, Germany.
This product includes material provided by mirabilos.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.