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