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