Copyright (c) 2002
Brett Lymn (blymn (at] NetBSD.org, brett_lymn (at] yahoo.com.au)
This code is donated to the NetBSD Foundation by the Author.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The name of the Author may not be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd May 14, 2024 .Dt CURSES_INPUT 3 .Os .Sh NAME .Nm curses_input , .Nm getch , .Nm wgetch , .Nm mvgetch , .Nm mvwgetch , .Nm define_key , .Nm keyok , .Nm has_key , .Nm getnstr , .Nm wgetnstr , .Nm mvgetnstr , .Nm mvwgetnstr , .Nm getstr , .Nm wgetstr , .Nm mvgetstr , .Nm mvwgetstr , .Nm keypad , .Nm is_keypad , .Nm notimeout , .Nm timeout , .Nm wtimeout , .Nm nodelay , .Nm ungetch , .Nm set_escdelay .Nd curses input stream routines .Sh LIBRARY .Lb libcurses .Sh SYNOPSIS n curses.h .Ft int .Fn getch "void" .Ft int .Fn wgetch "WINDOW *win" .Ft int .Fn mvgetch "int y" "int x" .Ft int .Fn mvwgetch "WINDOW *win" "int y" "int x" .Ft int .Fn keyok "int key_symbol" "bool flag" .Ft int .Fn has_key "int key_symbol" .Ft int .Fn define_key "const char *sequence" "int key_symbol" .Ft int .Fn getnstr "char *str" "int limit" .Ft int .Fn wgetnstr "WINDOW *win" "char *str" "int limit" .Ft int .Fn mvgetnstr "int y" "int x" "char *str" "int limit" .Ft int .Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit" .Ft int .Fn getstr "char *str" .Ft int .Fn wgetstr "WINDOW *win" "char *str" .Ft int .Fn mvgetstr "int y" "int x" "char *str" .Ft int .Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str" .Ft int .Fn keypad "WINDOW *win" "bool flag" .Ft bool .Fn is_keypad "const WINDOW *win" .Ft int .Fn notimeout "WINDOW *win" "bool flag" .Ft void .Fn timeout "int delay" .Ft void .Fn wtimeout "WINDOW *win" "int delay" .Ft int .Fn nodelay "WINDOW *win" "bool flag" .Ft int .Fn ungetch "int c" .Ft int .Fn set_escdelay "int escdelay"
p .Va extern int ESCDELAY ; .Sh DESCRIPTION These functions read characters and strings from the window input file descriptor.
p The .Fn getch function reads a character from the .Va stdscr input file descriptor and returns it. If the .Fn keypad flag has been set to .Dv TRUE , then .Fn getch will assemble multi-character key sequences into key symbols, If the terminal is resized, .Fn getch will return .Dv KEY_RESIZE , regardless of the setting of .Fn keypad . Calling .Fn getch will cause an implicit .Fn refresh on .Va stdscr .
p The .Fn wgetch function is the same as the .Fn getch function, excepting that it reads from the input file descriptor associated with the window specified by .Fa win .
p If the .Fn keypad flag is .Dv TRUE then the assembly of specific key symbols can be disabled by using the .Fn keyok function. If the .Fa flag is set to .Dv FALSE on a key symbol then .Fn getch will behave as if the character sequence associated with that key symbol was not recognised and will return the component characters one at a time to the caller. The .Fn is_keypad function returns .Dv TRUE if the .Fn keypad flag is set for the window specified by .Fa win .
p The .Fn has_key function takes a key value and returns .Dv TRUE if the current terminal recognises a key with that value, otherwise .Dv FALSE .
p Custom associations between sequences of characters and a key symbol can be made by using the .Fn define_key function. Normally, these associations are made by the information in the .Xr terminfo 5 database but the .Fn define_key function gives the capability to remove or add more associations. If .Fn define_key is passed a non-NULL string in .Fa sequence it will associate that sequence with the key symbol passed in .Fa key_symbol . The key symbol may be one of the ones listed below or a custom value that is application defined. It is valid to have multiple character sequences map to the same key symbol and there are no constraints on the length of the sequence allowed. The assembly of custom sequences follow the same rules for inter-character timing and so forth as the .Xr terminfo 5 derived ones. If .Fn define_key is passed a NULL in .Fa sequence then all associations for the key symbol in .Fa key_symbol will be deleted, this includes any associations that were derived from .Xr terminfo 5 .
p The .Fn mvgetch and .Fn mvwgetch functions are the same as the .Fn getch and .Fn wgetch functions, respectively, excepting that .Fn wmove is called to move the cursor to the position specified by .Fa y , .Fa x before the character is read.
p Calling .Fn getnstr , .Fn wgetnstr , .Fn mvgetnstr or .Fn mvwgetnstr is effectively the same as calling .Fn getch repeatedly until a newline is received or the character limit .Fa limit is reached. Once this happens the string is .Dv NULL terminated and returned in .Fa str . During input, the normal curses input key processing is performed and affects the input buffer. The .Fn mvgetnstr function calls .Fn wmove to move the cursor to the position given by .Fa y , .Fa x before getting the string, .Fn wgetnstr reads the input from the designated window, .Fn mvwgetnstr moves the cursor to the position given by .Fa y , .Fa x before getting the input from the designated window.
p The functions .Fn getstr , .Fn wgetstr , .Fn mvgetstr , and .Fn mvwgetstr are similar to .Fn getnstr , .Fn wgetnstr , .Fn mvgetnstr , and .Fn mvwgetnstr , respectively, excepting that there is no limit on the number of characters that may be inserted into .Fa str . This may cause the buffer to be overflowed, so their use is not recommended.
p The .Fn keypad function is used to affect how .Fn getch processes input characters. If .Fa flag is set to .Dv TRUE , then .Fn getch will scan the input stream looking for multi-character key sequences that are emitted by some terminal function keys. If a recognised sequence of characters is found, then .Fn getch will collapse that sequence into an integer key symbol, as shown below. The default setting for the flag is .Dv FALSE .
p The .Fn notimeout function controls whether or not .Fn getch will wait indefinitely between characters in a multi-character key sequence or not. If .Fa flag is .Dv TRUE , then there is no timeout applied between characters comprising a multi-character key sequence. If .Fa flag is .Dv FALSE , then the component characters of a multi-character sequence must not have an inter-character gap of more than .Va ESCDELAY . If this timing is exceeded, then the multi-character key assembly is deemed to have failed and the characters read thus far are returned one at a time when .Fn getch is called. The default setting for the flag is .Dv FALSE . The default value of .Va ESCDELAY is 300ms. If .Va ESCDELAY is negative, no timeout is applied between characters comprising a multi-character key sequence.
p The .Fn timeout function affects the behaviour of .Fn getch when reading a character from .Va stdscr . If .Fa delay is negative, then .Fn getch will block indefinitely on a read. If .Fa delay is 0, then .Fn getch will return immediately with .Dv ERR if there are no characters immediately available. If .Fa delay is a positive number, then .Fn getch will wait for that many milliseconds before returning and, if no character was available, then .Dv ERR will be returned. Note that for a positive number, the timeout is only accurate to the nearest tenth of a second. Also, the maximum value of .Fa delay is 25500 milliseconds. The .Fn wtimeout function does the same as .Fn timeout but applies to the specified window .Fa win .
p The .Fn nodelay function turns on and off blocking reads for .Fn getch . If .Fa flag is .Dv TRUE , then .Fn getch will not block on reads, if .Fa flag is .Dv FALSE , then reads will block. The default setting for the flag is .Dv FALSE . .Fn nodelay win TRUE is equivalent to .Fn wtimeout win 0 and .Fn nodelay win FALSE is equivalent to .Fn wtimeout win -1 .
p .Fn ungetch will convert .Fa c into an unsigned char and push that character back onto the input stream. Only one character of push-back is guaranteed to work, more may be possible depending on system resources.
p The .Fn set_escdelay function sets the .Va ESCDELAY value of the current screen to .Fa escdelay . .Sh RETURN VALUES The functions .Fn getch , .Fn wgetch , .Fn mvgetch , and .Fn mvwgetch will return the value of the key pressed or .Dv ERR in the case of an error or a timeout. Additionally, if .Fn keypad TRUE has been called on a window, then it may return one of the following values:
p l -column "Termcap entry" "getch Return Value" "Key Function" -offset indent t Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function" t !1 Ta KEY_SSAVE Ta Shift Save t !2 Ta KEY_SSUSPEND Ta Shift Suspend t !3 Ta KEY_SUNDO Ta Shift Undo t #1 Ta KEY_SHELP Ta Shift Help t #2 Ta KEY_SHOME Ta Shift Home t #3 Ta KEY_SIC Ta Shift Insert Character t #4 Ta KEY_SLEFT Ta Shift Left Arrow t %0 Ta KEY_REDO Ta Redo t %1 Ta KEY_HELP Ta Help t %2 Ta KEY_MARK Ta Mark t %3 Ta KEY_MESSAGE Ta Message t %4 Ta KEY_MOVE Ta Move t %5 Ta KEY_NEXT Ta Next Object t %6 Ta KEY_OPEN Ta Open t %7 Ta KEY_OPTIONS Ta Options t %8 Ta KEY_PREVIOUS Ta Previous Object t %9 Ta KEY_PRINT Ta Print t %a Ta KEY_SMESSAGE Ta Shift Message t %b Ta KEY_SMOVE Ta Shift Move t %c Ta KEY_SNEXT Ta Shift Next Object t %d Ta KEY_SOPTIONS Ta Shift Options t %e Ta KEY_SPREVIOUS Ta Shift Previous Object t %f Ta KEY_SPRINT Ta Shift Print t %g Ta KEY_SREDO Ta Shift Redo t %h Ta KEY_SREPLACE Ta Shift Replace t %i Ta KEY_SRIGHT Ta Shift Right Arrow t %j Ta KEY_SRSUME Ta Shift Resume t &0 Ta KEY_SCANCEL Ta Shift Cancel t &1 Ta KEY_REFERENCE Ta Reference t &2 Ta KEY_REFRESH Ta Refresh t &3 Ta KEY_REPLACE Ta Replace t &4 Ta KEY_RESTART Ta Restart t &5 Ta KEY_RESUME Ta Resume t &6 Ta KEY_SAVE Ta Save t &7 Ta KEY_SUSPEND Ta Suspend t &8 Ta KEY_UNDO Ta Undo t &9 Ta KEY_SBEG Ta Shift Begin t *0 Ta KEY_SFIND Ta Shift Find t *1 Ta KEY_SCOMMAND Ta Shift Command t *2 Ta KEY_SCOPY Ta Shift Copy t *3 Ta KEY_SCREATE Ta Shift Create t *4 Ta KEY_SDC Ta Shift Delete Character t *5 Ta KEY_SDL Ta Shift Delete Line t *6 Ta KEY_SELECT Ta Select t *7 Ta KEY_SEND Ta Shift End t *8 Ta KEY_SEOL Ta Shift Clear to EOL t *9 Ta KEY_SEXIT Ta Shift Exit t @0 Ta KEY_FIND Ta Find t @1 Ta KEY_BEG Ta Begin t @2 Ta KEY_CANCEL Ta Cancel t @3 Ta KEY_CLOSE Ta Close t @4 Ta KEY_COMMAND Ta Command t @5 Ta KEY_COPY Ta Copy t @6 Ta KEY_CREATE Ta Create t @7 Ta KEY_END Ta End t @8 Ta KEY_ENTER Ta Enter t @9 Ta KEY_EXIT Ta Exit t F1 Ta KEY_F(11) Ta Function Key 11 t F2 Ta KEY_F(12) Ta Function Key 12 t F3 Ta KEY_F(13) Ta Function Key 13 t F4 Ta KEY_F(14) Ta Function Key 14 t F5 Ta KEY_F(15) Ta Function Key 15 t F6 Ta KEY_F(16) Ta Function Key 16 t F7 Ta KEY_F(17) Ta Function Key 17 t F8 Ta KEY_F(18) Ta Fugle Unix Specification. .Sh NOTES The .Fn keyok and .Fn define_key functions are implementations of extensions made by the NCurses library to the Curses standard. Portable implementations should avoid the use of these functions. .Sh HISTORY The Curses package appeared in x 4.0 . The .Fn is_keypad and .Fn set_tabsize functions are .Em ncurses extension to the Curses library and was added in .Nx 8.0 .
Indexes created Sat Sep 20 22:09:52 GMT 2025