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