1.\" $NetBSD: curses_input.3,v 1.6 2002/10/22 12:24:03 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@netbsd.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd August 12, 2002 34.Dt CURSES_INPUT 3 35.Os 36.Sh NAME 37.Nm curses_input , 38.Nm getch , 39.Nm wgetch , 40.Nm define_key , 41.Nm keyok , 42.Nm getnstr , 43.Nm wgetnstr , 44.Nm mvgetnstr , 45.Nm mvwgetnstr , 46.Nm getstr , 47.Nm wgetstr , 48.Nm mvgetstr , 49.Nm mvwgetstr , 50.Nm keypad , 51.Nm notimeout , 52.Nm timeout , 53.Nm wtimeout , 54.Nm nodelay , 55.Nm ungetch 56.Nd curses input stream routines 57.Sh LIBRARY 58.Lb libcurses 59.Sh SYNOPSIS 60.Fd #include \*[Lt]curses.h\*[Gt] 61.Ft int 62.Fn getch "void" 63.Ft int 64.Fn wgetch "WINDOW *win" 65.Ft int 66.Fn keyok "int key_symbol" "bool flag" 67.Ft int 68.Fn define_key "char *sequence" "int key_symbol" 69.Ft int 70.Fn getnstr "char *str" "int limit" 71.Ft int 72.Fn wgetnstr "WINDOW *win" "char *str" "int limit" 73.Ft int 74.Fn mvgetnstr "int y" "int x" "char *str" "int limit" 75.Ft int 76.Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit" 77.Ft int 78.Fn getstr "char *str" 79.Ft int 80.Fn wgetstr "WINDOW *win" "char *str" 81.Ft int 82.Fn mvgetstr "int y" "int x" "char *str" "int limit" 83.Ft int 84.Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str" "int limit" 85.Ft int 86.Fn keypad "WINDOW *win" "boolf flag" 87.Ft int 88.Fn notimeout "WINDOW *win" "boolf flag" 89.Ft int 90.Fn timeout "int delay" 91.Ft int 92.Fn wtimeout "WINDOW *win" "int delay" 93.Ft int 94.Fn nodelay "WINDOW *win" "boolf flag" 95.Ft int 96.Fn ungetch "int c" 97.Sh DESCRIPTION 98These functions read characters and strings from the window input file 99descriptor. 100.Pp 101The 102.Fn getch 103function reads a character from the 104.Dv stdscr 105input file descriptor and returns it. 106If the 107.Fn keypad 108flag has been set to 109.Dv TRUE , 110then 111.Fn getch 112will assemble multi-character key sequences into key symbols, 113Calling 114.Fn getch 115will cause an implicit 116.Fn refresh 117on 118.Dv stdscr . 119.Pp 120The 121.Fn wgetch 122function is the same as the 123.Fn getch 124function, exceptng that it reads from the input file descriptor associated 125with the window specified by 126.Fa win . 127.Pp 128If the 129.Fn keypad 130flag is 131.Dv TRUE 132then the assembly of specific key symbols can be disabled by using the 133.Fn keyok 134function. 135If the 136.Fa flag 137is set to 138.Dv FALSE 139on a key symbol then 140.Fn getch 141will behave as if the character sequence associated with that key symbol 142was not recognised and will return the component characters one at a time to 143the caller. 144.Pp 145Custom associations between sequences of characters and a key symbol can 146be made by using the 147.Fn define_key 148function. 149Normally, these associations are made by the information in the 150.Xr termcap 5 151database but the 152.Fn define_key 153function gives the capability to remove or add more associations. 154If 155.Fn define_key 156is passed a non-NULL string in 157.Fa sequence 158it will associate that sequence with the key symbol passed in 159.Fa key_symbol . 160The key symbol may be one of the ones listed below or a custom value that 161is application defined. 162It is valid to have multiple character sequences map to the same key 163symbol and there are no constraints on the length of the sequence allowed. 164The assembly of custom sequences follow the same rules for inter-character 165timing and so forth as the 166.Xr termcap 5 167derived ones. 168If 169.Fn define_key 170is passed a NULL in 171.Fa sequence 172then all associations for the key symbol in 173.Fa key_symbol 174will be deleted, this includes any associations that were derived from 175.Xr termcap 5 . 176.Pp 177The 178.Fn mvgetch 179and 180.Fn mvwgetch 181functions are the same as the 182.Fn getch 183and 184.Fn wgetch 185functions, respectively, excepting that 186.Fn wmove 187is called to move the cursor to the position specified by 188.Fa y , 189.Fa x 190before the character is read. 191.Pp 192Calling 193.Fn getnstr , 194.Fn wgetnstr , 195.Fn mvgetnstr 196or 197.Fn mvwgetnstr 198is effectively the same as calling 199.Fn getch 200repeatedly until a newline is received or the character limit 201.Fa limit 202is reached. 203Once this happens the string is 204.Dv NULL 205terminated and returned in 206.Fa str . 207During input, the normal curses input key processing is performed and 208affects the input buffer. 209The 210.Fn mvgetnstr 211function calls 212.Fn wmove 213to move the cursor to the position given by 214.Fa y , 215.Fa x 216before getting the string, 217.Fn wgetnstr 218reads the input from the designated window, 219.Fn mvwgetnstr 220moves the cursor to the position given by 221.Fa y , 222.Fa x 223before getting the input from the designated window. 224.Pp 225The functions 226.Fn getstr , 227.Fn wgetstr , 228.Fn mvgetstr 229and 230.Fn mvwgetstr 231are similar to 232.Fn getnstr , 233.Fn wgetnstr , 234.Fn mvgetnstr 235and 236.Fn mvwgetnstr , 237respectively, excepting that there is no limit on the number of characters 238that may be inserted into 239.Fa str . 240This may cause the buffer to be overflowed, so their use is not recommended. 241.Pp 242The 243.Fn keypad 244function is used to affect how 245.Fn getch 246processes input characters. 247If 248.Fa flag 249is set to 250.Dv TRUE , 251then 252.Fn getch 253will scan the input stream looking for multi-character key sequences 254that are emitted by some terminal function keys. 255If a recognised sequence of characters is found, then 256.Fn getch 257will collapse that sequence into an integer key symbol, as shown below. 258The default setting for the flag is 259.Dv FALSE . 260.Pp 261The 262.Fn notimeout 263function controls whether or not 264.Fn getch 265will wait indefinitely between characters in a multi-character key 266sequence or not. 267If 268.Fa flag 269is 270.Dv TRUE , 271then there is no timeout applied between characters comprising a 272multi-character key sequence. 273If 274.Fa flag 275is 276.Dv FALSE , 277then the component characters of a multi-character sequence must not 278have an inter-character gap of more than 200ms. 279If this timing is exceeded, then the multi-character key assembly is 280deemed to have failed and the characters read thus far are returned 281one at a time when 282.Fn getch 283is called. 284The default setting for the flag is 285.Dv FALSE . 286.Pp 287The 288.Fn timeout 289function affects the behaviour of 290.Fn getch 291when reading a character from 292.Dv stdscr . 293If 294.Fa delay 295is negative, then 296.Fn getch 297will block indefinitely on a read. 298If 299.Fa delay 300is 0, then 301.Fn getch 302will return immediately with 303.Dv ERR 304if there are no characters immediately available. 305If 306.Fa delay 307is a positive number, then 308.Fn getch 309will wait for that many milliseconds before returning and, if no character 310was available, then 311.Dv ERR 312will be returned. 313Note that for a positive number, the timeout is only accurate to the nearest 314tenth of a second. 315The 316.Fn wtimeout 317function does the same as 318.Fn timeout 319but applies to the specified window 320.Fa win . 321.Pp 322The 323.Fn nodelay 324function turns on and off blocking reads for 325.Fn getch . 326If 327.Fa flag 328is 329.Dv TRUE , 330then 331.Fn getch 332will not block on reads, if 333.Fa flag 334is 335.Dv FALSE , 336then reads will block. 337The default setting for the flag is 338.Dv FALSE . 339.Fn nodelay win TRUE 340is equivalent to 341.Fn wtimeout win 0 342and 343.Fn nodelay win FALSE 344is equivalent to 345.Fn wtimeout win \-1 . 346.Pp 347.Fn ungetch 348will convert 349.Fa c 350into an unsigned char and push that character back onto the input stream. 351Only one character of push-back is guaranteed to work, more may be possible 352depending on system resources. 353.Sh RETURN VALUES 354If 355.Fn keypad TRUE 356has been called on a window, then 357.Fn getch 358may return one of the following values: 359.Pp 360.Bl -column "Termcap entry" "getch Return Value" "Key Function" -offset indent 361.It Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function" 362.It \&!1 Ta KEY_SSAVE Ta Shift Save 363.It \&!2 Ta KEY_SSUSPEND Ta Shift Suspend 364.It \&!3 Ta KEY_SUNDO Ta Shift Undo 365.It \ Ta KEY_SHELP Ta Shift Help 366.It \ Ta KEY_SHOME Ta Shift Home 367.It \ Ta KEY_SIC Ta Shift Insert Character 368.It \ Ta KEY_SLEFT Ta Shift Left Arrow 369.It \&%0 Ta KEY_REDO Ta Redo 370.It \&%1 Ta KEY_HELP Ta Help 371.It \&%2 Ta KEY_MARK Ta Mark 372.It \&%3 Ta KEY_MESSAGE Ta Message 373.It \&%4 Ta KEY_MOVE Ta Move 374.It \&%5 Ta KEY_NEXT Ta Next Object 375.It \&%6 Ta KEY_OPEN Ta Open 376.It \&%7 Ta KEY_OPTIONS Ta Options 377.It \&%8 Ta KEY_PREVIOUS Ta Previous Object 378.It \&%9 Ta KEY_PRINT Ta Print 379.It \&%a Ta KEY_SMESSAGE Ta Shift Message 380.It \&%b Ta KEY_SMOVE Ta Shift Move 381.It \&%c Ta KEY_SNEXT Ta Shift Next Object 382.It \&%d Ta KEY_SOPTIONS Ta Shift Options 383.It \&%e Ta KEY_SPREVIOUS Ta Shift Previous Object 384.It \&%f Ta KEY_SPRINT Ta Shift Print 385.It \&%g Ta KEY_SREDO Ta Shift Redo 386.It \&%h Ta KEY_SREPLACE Ta Shift Replace 387.It \&%i Ta KEY_SRIGHT Ta Shift Right Arrow 388.It \&%j Ta KEY_SRSUME Ta Shift Resume 389.It \&&0 Ta KEY_SCANCEL Ta Shift Cancel 390.It \&&1 Ta KEY_REFERENCE Ta Reference 391.It \&&2 Ta KEY_REFRESH Ta Refresh 392.It \&&3 Ta KEY_REPLACE Ta Replace 393.It \&&4 Ta KEY_RESTART Ta Restart 394.It \&&5 Ta KEY_RESUME Ta Resume 395.It \&&6 Ta KEY_SAVE Ta Save 396.It \&&7 Ta KEY_SUSPEND Ta Suspend 397.It \&&8 Ta KEY_UNDO Ta Undo 398.It \&&9 Ta KEY_SBEG Ta Shift Begin 399.It \&*0 Ta KEY_SFIND Ta Shift Find 400.It \&*1 Ta KEY_SCOMMAND Ta Shift Command 401.It \&*2 Ta KEY_SCOPY Ta Shift Copy 402.It \&*3 Ta KEY_SCREATE Ta Shift Create 403.It \&*4 Ta KEY_SDC Ta Shift Delete Character 404.It \&*5 Ta KEY_SDL Ta Shift Delete Line 405.It \&*6 Ta KEY_SELECT Ta Select 406.It \&*7 Ta KEY_SEND Ta Shift End 407.It \&*8 Ta KEY_SEOL Ta Shift Clear to EOL 408.It \&*9 Ta KEY_SEXIT Ta Shift Exit 409.It \&@0 Ta KEY_FIND Ta Find 410.It \&@1 Ta KEY_BEG Ta Begin 411.It \&@2 Ta KEY_CANCEL Ta Cancel 412.It \&@3 Ta KEY_CLOSE Ta Close 413.It \&@4 Ta KEY_COMMAND Ta Command 414.It \&@5 Ta KEY_COPY Ta Copy 415.It \&@6 Ta KEY_CREATE Ta Create 416.It \&@7 Ta KEY_END Ta End 417.It \&@8 Ta KEY_ENTER Ta Enter 418.It \&@9 Ta KEY_EXIT Ta Exit 419.It \&F1 Ta KEY_F(11) Ta Function Key 11 420.It \&F2 Ta KEY_F(12) Ta Function Key 12 421.It \&F3 Ta KEY_F(13) Ta Function Key 13 422.It \&F4 Ta KEY_F(14) Ta Function Key 14 423.It \&F5 Ta KEY_F(15) Ta Function Key 15 424.It \&F6 Ta KEY_F(16) Ta Function Key 16 425.It \&F7 Ta KEY_F(17) Ta Function Key 17 426.It \&F8 Ta KEY_F(18) Ta Function Key 18 427.It \&F9 Ta KEY_F(19) Ta Function Key 19 428.It \&FA Ta KEY_F(20) Ta Function Key 20 429.It \&FB Ta KEY_F(21) Ta Function Key 21 430.It \&FC Ta KEY_F(22) Ta Function Key 22 431.It \&FD Ta KEY_F(23) Ta Function Key 23 432.It \&FE Ta KEY_F(24) Ta Function Key 24 433.It \&FF Ta KEY_F(25) Ta Function Key 25 434.It \&FG Ta KEY_F(26) Ta Function Key 26 435.It \&FH Ta KEY_F(27) Ta Function Key 27 436.It \&FI Ta KEY_F(28) Ta Function Key 28 437.It \&FJ Ta KEY_F(29) Ta Function Key 29 438.It \&FK Ta KEY_F(30) Ta Function Key 30 439.It \&FL Ta KEY_F(31) Ta Function Key 31 440.It \&FM Ta KEY_F(32) Ta Function Key 32 441.It \&FN Ta KEY_F(33) Ta Function Key 33 442.It \&FO Ta KEY_F(34) Ta Function Key 34 443.It \&FP Ta KEY_F(35) Ta Function Key 35 444.It \&FQ Ta KEY_F(36) Ta Function Key 36 445.It \&FR Ta KEY_F(37) Ta Function Key 37 446.It \&FS Ta KEY_F(38) Ta Function Key 38 447.It \&FT Ta KEY_F(39) Ta Function Key 39 448.It \&FU Ta KEY_F(40) Ta Function Key 40 449.It \&FV Ta KEY_F(41) Ta Function Key 41 450.It \&FW Ta KEY_F(42) Ta Function Key 42 451.It \&FX Ta KEY_F(43) Ta Function Key 43 452.It \&FY Ta KEY_F(44) Ta Function Key 44 453.It \&FZ Ta KEY_F(45) Ta Function Key 45 454.It \&Fa Ta KEY_F(46) Ta Function Key 46 455.It \&Fb Ta KEY_F(47) Ta Function Key 47 456.It \&Fc Ta KEY_F(48) Ta Function Key 48 457.It \&Fd Ta KEY_F(49) Ta Function Key 49 458.It \&Fe Ta KEY_F(50) Ta Function Key 50 459.It \&Ff Ta KEY_F(51) Ta Function Key 51 460.It \&Fg Ta KEY_F(52) Ta Function Key 52 461.It \&Fh Ta KEY_F(53) Ta Function Key 53 462.It \&Fi Ta KEY_F(54) Ta Function Key 54 463.It \&Fj Ta KEY_F(55) Ta Function Key 55 464.It \&Fk Ta KEY_F(56) Ta Function Key 56 465.It \&Fl Ta KEY_F(57) Ta Function Key 57 466.It \&Fm Ta KEY_F(58) Ta Function Key 58 467.It \&Fn Ta KEY_F(59) Ta Function Key 59 468.It \&Fo Ta KEY_F(60) Ta Function Key 60 469.It \&Fp Ta KEY_F(61) Ta Function Key 61 470.It \&Fq Ta KEY_F(62) Ta Function Key 62 471.It \&Fr Ta KEY_F(63) Ta Function Key 63 472.It \&K1 Ta KEY_A1 Ta Upper left key in keypad 473.It \&K2 Ta KEY_B2 Ta Centre key in keypad 474.It \&K3 Ta KEY_A3 Ta Upper right key in keypad 475.It \&K4 Ta KEY_C1 Ta Lower left key in keypad 476.It \&K5 Ta KEY_C3 Ta Lower right key in keypad 477.It \&Km Ta KEY_MOUSE Ta Mouse Event 478.It \&k0 Ta KEY_F0 Ta Function Key 0 479.It \&k1 Ta KEY_F(1) Ta Function Key 1 480.It \&k2 Ta KEY_F(2) Ta Function Key 2 481.It \&k3 Ta KEY_F(3) Ta Function Key 3 482.It \&k4 Ta KEY_F(4) Ta Function Key 4 483.It \&k5 Ta KEY_F(5) Ta Function Key 5 484.It \&k6 Ta KEY_F(6) Ta Function Key 6 485.It \&k7 Ta KEY_F(7) Ta Function Key 7 486.It \&k8 Ta KEY_F(8) Ta Function Key 8 487.It \&k9 Ta KEY_F(9) Ta Function Key 9 488.It \&k; Ta KEY_F(10) Ta Function Key 10 489.It \&kA Ta KEY_IL Ta Insert Line 490.It \&ka Ta KEY_CATAB Ta Clear All Tabs 491.It \&kB Ta KEY_BTAB Ta Back Tab 492.It \&kb Ta KEY_BACKSPACE Ta Backspace 493.It \&kC Ta KEY_CLEAR Ta Clear 494.It \&kD Ta KEY_DC Ta Delete Character 495.It \&kd Ta KEY_DOWN Ta Down Arrow 496.It \&kE Ta KEY_EOL Ta Clear to End Of Line 497.It \&kF Ta KEY_SF Ta Scroll Forward one line 498.It \&kH Ta KEY_LL Ta Home Down 499.It \&kh Ta KEY_HOME Ta Home 500.It \&kI Ta KEY_IC Ta Insert Character 501.It \&kL Ta KEY_DL Ta Delete Line 502.It \&kl Ta KEY_LEFT Ta Left Arrow 503.It \&kM Ta KEY_EIC Ta Exit Insert Character Mode 504.It \&kN Ta KEY_NPAGE Ta Next Page 505.It \&kP Ta KEY_PPAGE Ta Previous Page 506.It \&kR Ta KEY_SR Ta Scroll One Line Back 507.It \&kr Ta KEY_RIGHT Ta Right Arrow 508.It \&kS Ta KEY_EOS Ta Clear to End Of Screen 509.It \&kT Ta KEY_STAB Ta Set Tab 510.It \&kt Ta KEY_CTAB Ta Clear Tab 511.It \&ku Ta KEY_UP Ta Up Arrow 512.El 513.Pp 514Note that not all terminals are capable of generating all the keycodes 515listed above nor are termcap entries normally configured with all the 516above capabilities defined. 517.Pp 518Functions returning pointers will return 519.Dv NULL 520if an error is detected. 521The functions that return an int will return one of the following 522values: 523.Pp 524.Bl -tag -width ERR -compact 525.It Er OK 526The function completed successfully. 527.It Er ERR 528An error occurred in the function. 529.El 530.Sh SEE ALSO 531.Xr curses_cursor 3 , 532.Xr curses_refresh 3 , 533.Xr curses_tty 3 , 534.Xr termcap 5 535.Sh STANDARDS 536The 537.Nx 538Curses library complies with the X/Open Curses specification, part of the 539Single Unix Specification. 540.Sh NOTES 541The 542.Fn keyok 543and 544.Fn define_key 545functions are implementations of extensions made by the NCurses library 546to the Curses standard. 547Portable implementations should avoid the use of these functions. 548.Sh HISTORY 549The Curses package appeared in 550.Bx 4.0 . 551