curs\_get\_wch(3X) Library calls curs\_get\_wch(3X) # [NAME](#NAME) **get\_wch**, **wget\_wch**, **mvget\_wch**, **mvwget\_wch**, **unget\_wch** - get (or push back) a wide character from *curses* terminal keyboard buffer # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` int get_wch(wint_t * wch); int wget_wch(WINDOW * win, wint_t * wch); int mvget_wch(int y, int x, wint_t * wch); int mvwget_wch(WINDOW * win, int y, int x, wint_t * wch); ``` ``` int unget_wch(const wchar_t wc); ``` # [DESCRIPTION](#DESCRIPTION) ## [Reading Characters](#Reading_Characters) **wget\_wch** gathers a key event from the terminal input stream associated with a *curses* window *win*, returning **OK** if a wide character is read, **KEY\_CODE\_YES** if a function key is read, and **ERR** if no key event is available. [**ncurses**(3X)](/man/os/ncurses/ncurses.3X) describes the variants of this function. When input is pending, **wget\_wch** stores an integer identifying the key event in *wch*; for alphanumeric and punctuation keys, this value corresponds to the character encoding used by the terminal. Use of the control key as a modifier, by holding it down while pressing and releasing another key, often results in a distinct code. The behavior of other keys depends on whether *win* is in keypad mode; see subsections “Keypad Mode” and “Key Codes” in [**getch**(3X)](/man/os/ncurses/getch.3X). If no input is pending, then if the no-delay flag is set in the window (see [**nodelay**(3X)](/man/os/ncurses/nodelay.3X)), the function returns **ERR**; otherwise, *curses* waits until the terminal has input. If [**cbreak**(3X)](/man/os/ncurses/cbreak.3X) or [**raw**(3X)](/man/os/ncurses/raw.3X) has been called, this happens after one character is read. If [**nocbreak**(3X)](/man/os/ncurses/nocbreak.3X) or [**noraw**(3X)](/man/os/ncurses/noraw.3X) has been called, it occurs when the next newline is read. (Because the terminal's canonical or “cooked” mode is line-buffered, multiple **wget\_wch** calls may then be necessary to empty the input queue.) If [**halfdelay**(3X)](/man/os/ncurses/halfdelay.3X) has been called, *curses* waits until input is available or the specified delay elapses. If [**echo**(3X)](/man/os/ncurses/echo.3X) has been called, and the window is not a pad, *curses* writes the wide character from the input queue to the window (at the cursor position) per the following rules. - If the wide character matches the terminal's erase character (see [**erasewchar**(3X)](/man/os/ncurses/erasewchar.3X)), the cursor moves leftward one position and the new position is erased as if [**wmove**(3X)](/man/os/ncurses/wmove.3X) and then [**wdelch**(3X)](/man/os/ncurses/wdelch.3X) were called. When the window's keypad mode is enabled (see below), **KEY\_LEFT** and **KEY\_BACKSPACE** are handled the same way. - *curses* writes any other wide character to the window, as with [**wecho\_wchar**(3X)](/man/os/ncurses/wecho_wchar.3X). - If the window *win* has been moved or modified since the last call to [**wrefresh**(3X)](/man/os/ncurses/wrefresh.3X), *curses* calls **wrefresh** on it. If the wide character is a carriage return and [**nl**(3X)](/man/os/ncurses/nl.3X) has been called, **wget\_wch** stores the wide character code for line feed in *wch* instead. ## [Ungetting Characters](#Ungetting_Characters) **unget\_wch** places *wc* into the input queue to be retrieved by the next call to **wget\_wch**. A single input queue serves all windows associated with the screen. # [RETURN VALUE](#RETURN_VALUE) **wget\_wch** returns **OK** when it reads a wide character, **KEY\_CODE\_YES** when it reads a function key code, and **ERR** on failure. **wget\_wch** fails if its timeout expires without any data arriving, which cannot happen if [**nodelay**(3X)](/man/os/ncurses/nodelay.3X) is in effect on the window. In *ncurses*, **wget\_wch** also fails if - the *curses* screen has not been initialized, - (for functions taking a *WINDOW* pointer argument) *win* is a null pointer, - the terminal input stream is closed, in which case *errno* is set to *EBADF*, or - execution was interrupted by a signal, in which case *errno* is set to *EINTR*. Functions prefixed with “mv” first perform cursor movement and fail if the position (*y*, *x*) is outside the window boundaries. **unget\_wch** returns **OK** on success and **ERR** on failure. In *ncurses*, **unget\_wch** fails if - the *curses* screen has not been initialized, or - there is no more room in the input queue. # [NOTES](#NOTES) See the “NOTES” section of [**wgetch**(3X)](/man/os/ncurses/wgetch.3X). All of these functions except **wget\_wch** and **unget\_wch** may be implemented as macros. Unlike [**wgetch**(3X)](/man/os/ncurses/wgetch.3X), **wget\_wch** stores the value of the input character in an additional *wch* parameter instead of the return value. Unlike **ungetch**, **unget\_wch** cannot distinguish function key codes from conventional character codes. An application can overcome this limitation by pushing function key codes with **ungetch** and subsequently checking the return value of **wget\_wch** for a match with **KEY\_CODE\_YES**. # [EXTENSIONS](#EXTENSIONS) See the “EXTENSIONS” section of [**wgetch**(3X)](/man/os/ncurses/wgetch.3X). # [PORTABILITY](#PORTABILITY) Applications employing *ncurses* extensions should condition their use on the visibility of the **NCURSES\_VERSION** preprocessor macro. X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them. See the “PORTABILITY” section of [**wgetch**(3X)](/man/os/ncurses/wgetch.3X) regarding the interaction of *wget\_wch* with signal handlers. # [HISTORY](#HISTORY) X/Open Curses Issue 4 (1995) initially specified these functions. The System V Interface Definition Version 4 of the same year specified functions named *wgetwch* (with its variants) *ungetwch*. These were later additions to SVr4.*x*, not appearing in the first SVr4 (1989). They differ from X/Open's later *wget\_wch* and *unget\_wch* in that *wgetwch* takes no *wch* argument, but returns the (wide) key code as an *int* (with no provision for distinguishing a character code from a function key code); and *ungetwch* takes a non-*const* *int* argument. # [SEE ALSO](#SEE_ALSO) [**curs\_getch**(3X)](/man/os/ncurses/curs_getch.3X) describes comparable functions of the *ncurses* library in its non-wide-character configuration. [**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_add\_wch**(3X)](/man/os/ncurses/curs_add_wch.3X), [**curs\_inopts**(3X)](/man/os/ncurses/curs_inopts.3X), [**curs\_move**(3X)](/man/os/ncurses/curs_move.3X), [**curs\_refresh**(3X)](/man/os/ncurses/curs_refresh.3X) 2026-04-18 ncurses 6.6 --- Document: wget_wch(3x) from ncurses 6.6.20261017-r0 (Chainguard OS) Source: https://github.com/ThomasDickey/ncurses-snapshots