getch, mvgetch, mvwgetch, or wgetch Subroutine

Purpose

Gets a single-byte character from the terminal.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>

int getch(void)

int mvgetch(int y,
int x);

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

int wgetch(WINDOW *win);

Description

The getch, wgetch, mvgetch, and mvwgetch subroutines 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 the keypad subroutine is enabled, these subroutines respond to the corresponding KEY_ value defined in <curses.h>.

Processing of terminal input is subject to the general rules described in Section 3.5 on page 34.

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

<backspace>,

<left-arrow> and 

the current erase character:

The input is interpreted as specified in Section 3.4.3 on page 31 and then the character at the resulting cursor position is deleted as though the delch subroutine was called, except that if the cursor was originally in the first column of the line, then the user is alerted as though the beep subroutine was called.

The user is alerted as though the beep subroutine was called. Information concerning the function keys is not returned to the caller.

Function Keys

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

The Importance of Terminal Modes

The output of the getch subroutines is, in part, determined by the mode of the terminal. The following describes the action of the getch subroutines in each type of terminal mode:

Getting Function Keys

If your program enables the keyboard with the keypad subroutine, and the user presses a function key, the token for that function key is returned instead of raw characters. The possible function keys are defined in the /usr/include/curses.h file. Each #define macro begins with a KEY_ prefix.

If a character is received that could be the beginning of a function key (such as an Escape character) curses sets a timer. If the remainder of the sequence is not received before the timer expires, the character is passed through. Otherwise, the function key's value is returned. For this reason, after a user presses the Esc key there is a delay before the escape is returned to the program. Programmers should not use the Esc key for a single character routine.

Within the getch subroutine, a structure of type timeval, defined in the /usr/include/sys/time.h file, indicates the maximum number of microseconds to wait for the key response to complete.

The ESCDELAY environment variable sets the length of time to wait before timing out and treating the ESC keystroke as the ESC character rather than combining it with other characters in the buffer to create a key sequence. The ESCDELAY environment variable is measured in fifths of a millisecond. If ESCDELAY is 0, the system immediately composes the ESCAPE response without waiting for more information from the buffer. The user may choose any value between 0 and 99,999, inclusive. The default setting for the ESCDELAY environment variable is 500 (one tenth of a second).

Programs that do not want the getch subroutines to set a timer can call the notimeout subroutine. If notimeout is set to TRUE, curses does not distinguish between function keys and characters when retrieving data.

The getch subroutines might not be able to return all function keys because they are not defined in the terminfo database or because the terminal does not transmit a unique code when the key is pressed. The following function keys may be returned by the getch subroutines:

Parameters

Return Values

Upon successful completion, the getch, mvwgetch, and wgetch subroutines, CURSES, and Curses Interface return the single-byte character, KEY_ value, or ERR. When in the nodelay mode and no data is available, ERR is returned.

Examples

1. To get a character and echo it to the stdscr, use:

   mvgetch();

2. To get a character and echo it into stdscr at the coordinates y=20, x=30, use:

   mvgetch(20, 30);

3. To get a character and echo it into the user-defined window my_window at coordinates y=20, x=30, use:

   WINDOW *my_window;
   mvwgetch(my_window, 20, 30);