mvwgetch man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

curs_getch(3)							 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 program waits until the system passes
       text through to the program.  Depending on the setting of cbreak, 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.

       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 modified 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 characters.	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 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.

       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
       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

       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 integer 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 ignore 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 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 usually have only a small subset
       of these.  IBM PC-style consoles 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 standard, 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 documentation.	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 documentation.  Under historical
       curses implementations, it varied depending on whether the operating
       system's implementation of handled signal receipt interrupts a read(2)
       call in progress 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 interrupt 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).

       Comparable functions in the wide-character (ncursesw) library are
       described in curs_get_wch(3).

								 March 1, 2011
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net