Go to main content

man pages section 3: Curses Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

mvgetch(3XCURSES)

Name

getch, wgetch, mvgetch, mvwgetch - get a single-byte character from the terminal

Synopsis

cc [ flag... ] file... –I /usr/xpg4/include –L /usr/xpg4/lib \
–R /usr/xpg4/lib –lcurses [ library... ]

c89 [ flag... ] file... –lcurses [ library... ]
 
#include <curses.h>

int getch(void);
int wgetch(WINDOW *win);
int mvgetch(int y, int x);
int mvwgetch(WINDOW *win, int y, int x);

Parameters

win

Is a pointer to the window associated with the terminal from which the character is to be read.

y

Is the y (row) coordinate for the position of the character to be read.

x

Is the x (column) coordinate for the position of the character to be read.

Description

These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If keypad(3XCURSES) is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in <curses.h>

Processing of terminal input is subject to the general rules described on the keypad(3XCURSES) manual page.

If echoing is enabled, then the character is echoed as though it were provided as an input argument to addch(3XCURSES), except for the following characters:

<backspace>

The input is interpreted as follows: unless the cursor already was in column 0, <backspace> moves the cursor one column toward the start of the current line and any characters after the <backspace> are added or inserted starting there. The character at the resulting cursor position it then deleted as though delch(3XCURSES) were called, except that if the cursor was originally in the first column of the line, the user is alerted as though beep(3XCURSES) were called.

Function keys

The user is alerted as though beep() were called. Information concerning the function keys is not returned to the caller.

If the current or specified window is not a pad, and it has been moved modified since the last refresh operation, then it will be refreshed before another character is read.

Constant Values for Function Keys

The following is a list of tokens for function keys that are returned by the getch() set of functions if keypad handling is enabled (some terminals may not support all tokens).

Constant
Description
KEY_BREAK
Break key
KEY_DOWN
The down arrow key
KEY_UP
The up arrow key
KEY_LEFT
The left arrow key
KEY_RIGHT
The right arrow key
KEY_HOME
Home key
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 backwards
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_BEG
Beginning 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_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
Reference key
KEY_REFRESH
Refresh key
KEY_REPLACE
Replace key
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_SMESSAGES
Shifted messages key
KEY_SMOVE
Shifted move key
KEY_SNEXT
Shifted next key
KEY_SOPTIONS
Shifted options key
KEY_SPREVIOUS
Shifted previous 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
KEY_SUSPEND
Suspend key
KEY_UNDO
Undo key

Return Values

Upon successful completion, these functions return the single-byte character, KEY_ value, or ERR. When in the nodelay mode and no data is available, ERR is returned.

Errors

No errors are defined.

USAGE

Applications should not define the escape key by itself as a single-character function.

When using these functions, nocbreak mode (cbreak(3XCURSES)) and echo mode (echo(3XCURSES)) should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe
Standard

See Also

raw(3XCURSES), cbreak(3XCURSES), echo(3XCURSES), halfdelay(3XCURSES), keypad(3XCURSES), libcurses(3XCURSES), nodelay(3XCURSES), notimeout(3XCURSES), timeout(3XCURSES), attributes(7), standards(7)