1.\" $NetBSD: curses_tty.3,v 1.1 2002/10/21 13:55:23 blymn 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_TTY 3 35.Os 36.Sh NAME 37.NM curses_tty , 38.Nm beep , 39.Nm flash , 40.Nm curs_set , 41.Nm def_prog_mode , 42.Nm reset_prog_mode , 43.Nm def_shell_mode , 44.Nm reset_shell_mode , 45.Nm echo , 46.Nm noecho , 47.Nm delay_output , 48.Nm erasechar , 49.Nm flushinp , 50.Nm gettmode , 51.Nm has_ic , 52.Nm has_il , 53.Nm idcok , 54.Nm idlok , 55.Nm intrflush , 56.Nm killchar , 57.Nm meta , 58.Nm napms , 59.Nm nl , 60.Nm nonl , 61.Nm cbreak , 62.Nm nocbreak , 63.Nm raw , 64.Nm noraw , 65.Nm savetty , 66.Nm resetty , 67.Nd curses terminal manipulation routines 68.Sh LIBRARY 69.Lb libcurses 70.Sh SYNOPSIS 71.Fd #include \*[Lt]curses.h\*[Gt] 72.Ft int 73.Fn beep "void" 74.Ft int 75.Fn flash "void" 76.Ft int 77.Fn curs_set "int visibility" 78.Ft int 79.Fn def_prog_mode "void" 80.Ft int 81.Fn reset_prog_mode "void" 82.Ft int 83.Fn def_shell_mode "void" 84.Ft int 85.Fn reset_shell_mode "void" 86.Ft int 87.Fn echo "void" 88.Ft int 89.Fn noecho "void" 90.Ft int 91.Fn delay_output "int ms" 92.Ft char 93.Fn erasechar "void" 94.Ft int 95.Fn flushinp "void" 96.Ft int 97.Fn gettmode "void" 98.Ft int 99.Fn has_ic "void" 100.Ft int 101.Fn has_il "void" 102.Ft int 103.Fn idcok "WINDOW *win" "boolf flag" 104.Ft int 105.Fn idlok "WINDOW *win" "boolf flag" 106.Ft int 107.Fn intrflush "WINDOW *win" "boolf flag" 108.Ft char 109.Fn killchar "void" 110.Ft int 111.Fn meta "WINDOW *win" "boolf flag" 112.Ft int 113.Fn napms "int ms" 114.Ft int 115.Fn nl "void" 116.Ft int 117.Fn nonl "void" 118.Ft int 119.Fn cbreak "void" 120.Ft int 121.Fn nocbreak "void" 122.Ft int 123.Fn raw "void" 124.Ft int 125.Fn noraw "void" 126.Ft int 127.Fn savetty "void" 128.Ft int 129.Fn resetty "void" 130.Sh DESCRIPTION 131These functions manipulate curses terminal settings. 132.Pp 133The 134.Fn beep 135function rings the terminal bell, if this is possible. 136Failing that, the terminal screen will be flashed. 137If neither of these are possible, then no action will be taken. 138.Fn flash 139will flash the terminal screen if possible. 140Failing that, the terminal bell will be rung. 141If neither of these are possible then no action will be taken. 142.Pp 143The cursor 144visibility can be set by calling 145.Fn curs_set . 146The following visibility settings are valid for 147.Fn curs_set : 148.Pp 149.Bl -tag -width visibility -compact -offset indent 150.It Visibility 151Effect 152.It 0 153cursor is invisible. 154.It 1 155cursor is normal visibility 156.It 2 157cursor is high visibility 158.El 159.Pp 160A successful call to 161.Fn curs_set 162will return the previous visibility setting for the cursor. 163.Pp 164The 165.Fn delay_output 166function pauses the output to the terminal by sending the appropriate 167number of terminal pad characters such that the transmission time of 168the pad characters will take 169.Fa ms 170milliseconds. 171.Pp 172Calling 173.Fn def_prog_mode 174will cause the current terminal curses setting to be saved. 175A subequent call to 176.Fn reset_prog_mode , 177will restore the saved settings. 178This is useful when calls to external programs are made that may 179reset the terminal characteristics. 180.Pp 181The 182.Fn def_shell_mode 183function saves the current terminal line settings. 184These settings are the ones that will be restored when the curses 185application exits. 186Conversely, 187.Fn reset_shell_mode 188will save the current terminal curses settings for later restoration and 189restores the previously saved terminal line settings. 190.Pp 191The 192.Fn echo 193function turns on curses echo mode, characters entered will be echoed 194to the terminal by curses. 195The 196.Fn noecho 197function disables this feature. 198.Pp 199The current erase character for the terminal can be determined by 200calling the 201.Fn erasechar 202function. 203.Pp 204The 205.Fn flushinp 206function discards any pending input for the current screen. 207.Pp 208The modes 209for the current terminal can be reset by calling 210.Fn gettmode , 211this will perform the initialisation on the terminal that is normally 212done by curses at start up. 213.Pp 214The 215.Fn has_ic 216function returns either 217.Dv TRUE 218or 219.Dv FALSE 220depending on whether or not the terminal has a insert character 221capability or not. 222Similarly the 223.Fn has_il 224function does the same test but for a insert line capability. 225.Pp 226The use of the insert character capability in curses operations can be 227enabled or disabled by calling 228.Fn idcok 229on the desired window. 230Similarly, the use of the insert line capability can be controlled using the 231.Fn idlok 232function. 233.Pp 234The 235.Fn intrflush 236function controls whether or not a flush of the input buffer is 237performed when an interrupt key (kill, suspend or quit) is pressed. 238The 239.Fn win 240parameter is ignored. 241.Pp 242The character that performs the line kill function can be determined 243by calling the 244.Fn killchar 245function. 246.Pp 247The 248.Fn meta 249function turns on and off the generation of 8 bit characters by the 250terminal, if 251.Fa flag 252is 253.Dv FALSE 254then only 7 bit characters will be returned, if 255.Fa flag 256is 257.Dv TRUE 258then 8 bit characters will be returned by the terminal. 259.Pp 260The 261.Fn napms 262causes the application to sleep for the number of milliseconds 263specified by 264.Fa ms . 265.Pp 266Calling 267.Fn nl 268will cause curses to map all carriage returns to newlines on input, 269this functionality is enabled by default. 270The 271.Fn nonl 272function disables this behaviour. 273.Pp 274The 275.Fn cbreak 276function will put the terminal into cbreak mode, which means that 277characters will be returned one at a time instead of waiting for a 278newline character, line discipline processing will be performed. 279The 280.Fn nocbreak 281function disables this mode. 282.Pp 283The 284.Fn noraw 285function sets the input mode for the current terminal into Cooked mode, 286that is input character translation and signal character processing is 287performed. 288The 289.Fn raw 290function puts the terminal into Raw mode, no input character 291translation is done nor is signal character processing. 292.Pp 293The terminal 294tty flags can be saved by calling 295.Fn savetty 296and may be restored by calling 297.Fn resetty , 298the use of these functions is discouraged as they may cause the 299terminal to be put into a state that is incompatiable with curses 300operation. 301.Sh RETURN VALUES 302Functions returning pointers will return 303.Dv NULL 304if an error is detected. 305The functions that return an int will return one of the following 306values: 307.Pp 308.Bl -tag -width ERR -compact 309.It Er OK 310The function completed successfully. 311.It Er ERR 312An error occurred in the function. 313.El 314.Sh SEE ALSO 315.Xr getch 3 , 316.Xr termios 4 317.Sh NOTES 318The 319.Fn idcok 320and 321.Fn idlok 322currently have no effect on the curses code at all, currently curses 323will always use the terminal insert character and insert line 324capabilities if available. 325.Sh STANDARDS 326The 327.Nx 328Curses library complies with the X/Open Curses specification, part of the 329Single Unix Specification. 330.Sh HISTORY 331The Curses package appeared in 332.Bx 4.0 . 333