--- name: "get_wch" section: "3ncurses" platform: "linux" package: "ncurses-doc" version: "6.5+20250216-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/get_wch/3ncurses" --- # get\_wch(3ncurses) get (or push back) a wide character from curses terminal keyboard buffer ## NAME **get\_wch**, **wget\_wch**, **mvget\_wch**, **mvwget\_wch**, **unget\_wch** - get (or push back) a wide character from *curses* terminal keyboard buffer ## 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 ### Reading Characters **wget\_wch** **gathers a key event from the terminal keyboard 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(3NCURSES) 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 “Predefined Key Codes”** **in getch(3NCURSES).** **If no input is pending,** **then if the no-delay flag is set in the window** **(see nodelay(3NCURSES)),** **the function returns** **ERR**; **otherwise,** *curses* **waits until the terminal has input.** **If cbreak(3NCURSES) or raw(3NCURSES)** **has been called,** **this happens after one character is read.** **If nocbreak(3NCURSES) or noraw(3NCURSES)** **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(3NCURSES)** **has been called,** *curses* **waits until input is available or the specified delay elapses.** **If echo(3NCURSES) 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(3NCURSES)),** **the cursor moves leftward one position** **and the new position is erased** **as if wmove(3NCURSES) and then wdelch(3NCURSES) 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(3NCURSES).** - • **If the window** *win* **has been moved or modified since the last call to** **wrefresh(3NCURSES),** *curses* **calls** **wrefresh** **on it.** **If the wide character** **is a carriage return and nl(3NCURSES) has been called,** **wget\_wch** **stores the wide character code for line feed in** *wch* **instead.** ### 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 **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,** **or** - • **execution was interrupted by a signal,** **in which case** *errno* **is set to** *EINTR*. **Functions taking a** *WINDOW* **pointer argument fail if** *win* **is a null pointer.** **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** **if there is no more room in the input queue.** ## NOTES **See the “NOTES” section of wgetch(3NCURSES).** **All of these functions except** **wget\_wch** **and** **unget\_wch** **may be implemented as macros.** **Unlike wgetch(3NCURSES),** **wget\_wch** **and its variants store 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 **See the “EXTENSIONS” section of wgetch(3NCURSES).** ## 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(3NCURSES) regarding** **the interaction of** *wget\_wch* **with signal handlers.** ## 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 **getch(3NCURSES) describes comparable functions of the** *ncurses* **library in its non-wide-character configuration.** **ncurses(3NCURSES),** **add\_wch(3NCURSES),** **inopts(3NCURSES),** **move(3NCURSES),** **refresh(3NCURSES)**