1*ab43c492Swiz.\" $NetBSD: curses_tty.3,v 1.14 2017/09/18 08:49:20 wiz Exp $ 223b2be97Sblymn.\" 323b2be97Sblymn.\" Copyright (c) 2002 4104b35feSgrant.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) 523b2be97Sblymn.\" 623b2be97Sblymn.\" This code is donated to the NetBSD Foundation by the Author. 723b2be97Sblymn.\" 823b2be97Sblymn.\" Redistribution and use in source and binary forms, with or without 923b2be97Sblymn.\" modification, are permitted provided that the following conditions 1023b2be97Sblymn.\" are met: 1123b2be97Sblymn.\" 1. Redistributions of source code must retain the above copyright 1223b2be97Sblymn.\" notice, this list of conditions and the following disclaimer. 1323b2be97Sblymn.\" 2. Redistributions in binary form must reproduce the above copyright 1423b2be97Sblymn.\" notice, this list of conditions and the following disclaimer in the 1523b2be97Sblymn.\" documentation and/or other materials provided with the distribution. 1623b2be97Sblymn.\" 3. The name of the Author may not be used to endorse or promote 1723b2be97Sblymn.\" products derived from this software without specific prior written 1823b2be97Sblymn.\" permission. 1923b2be97Sblymn.\" 2023b2be97Sblymn.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 2123b2be97Sblymn.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 2223b2be97Sblymn.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 2323b2be97Sblymn.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 2423b2be97Sblymn.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 2523b2be97Sblymn.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2623b2be97Sblymn.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2723b2be97Sblymn.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2823b2be97Sblymn.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2923b2be97Sblymn.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 3023b2be97Sblymn.\" SUCH DAMAGE. 3123b2be97Sblymn.\" 3223b2be97Sblymn.\" 33760f355aSroy.Dd February 17, 2017 3423b2be97Sblymn.Dt CURSES_TTY 3 3523b2be97Sblymn.Os 3623b2be97Sblymn.Sh NAME 371f45225dSwiz.Nm curses_tty , 3838037cccSroy.Nm baudrate , 3923b2be97Sblymn.Nm beep , 4023b2be97Sblymn.Nm flash , 4123b2be97Sblymn.Nm curs_set , 4223b2be97Sblymn.Nm def_prog_mode , 4323b2be97Sblymn.Nm reset_prog_mode , 4423b2be97Sblymn.Nm def_shell_mode , 4523b2be97Sblymn.Nm reset_shell_mode , 4623b2be97Sblymn.Nm echo , 4723b2be97Sblymn.Nm noecho , 4823b2be97Sblymn.Nm delay_output , 4923b2be97Sblymn.Nm erasechar , 5023b2be97Sblymn.Nm flushinp , 5123b2be97Sblymn.Nm gettmode , 52a3c6a58eSblymn.Nm halfdelay , 5323b2be97Sblymn.Nm has_ic , 5423b2be97Sblymn.Nm has_il , 5523b2be97Sblymn.Nm idcok , 5623b2be97Sblymn.Nm idlok , 5723b2be97Sblymn.Nm intrflush , 5811f267a0Sjdc.Nm noqiflush , 5911f267a0Sjdc.Nm qiflush , 6023b2be97Sblymn.Nm killchar , 6123b2be97Sblymn.Nm meta , 6223b2be97Sblymn.Nm napms , 6323b2be97Sblymn.Nm nl , 6423b2be97Sblymn.Nm nonl , 6523b2be97Sblymn.Nm cbreak , 6623b2be97Sblymn.Nm nocbreak , 6723b2be97Sblymn.Nm raw , 6823b2be97Sblymn.Nm noraw , 69a5a78d3cSroy.Nm typeahead , 7023b2be97Sblymn.Nm savetty , 711f45225dSwiz.Nm resetty 7223b2be97Sblymn.Nd curses terminal manipulation routines 7323b2be97Sblymn.Sh LIBRARY 7423b2be97Sblymn.Lb libcurses 7523b2be97Sblymn.Sh SYNOPSIS 76472351e1Swiz.In curses.h 7723b2be97Sblymn.Ft int 7838037cccSroy.Fn baudrate "void" 7938037cccSroy.Ft int 8023b2be97Sblymn.Fn beep "void" 8123b2be97Sblymn.Ft int 8223b2be97Sblymn.Fn flash "void" 8323b2be97Sblymn.Ft int 8423b2be97Sblymn.Fn curs_set "int visibility" 8523b2be97Sblymn.Ft int 8623b2be97Sblymn.Fn def_prog_mode "void" 8723b2be97Sblymn.Ft int 8823b2be97Sblymn.Fn reset_prog_mode "void" 8923b2be97Sblymn.Ft int 9023b2be97Sblymn.Fn def_shell_mode "void" 9123b2be97Sblymn.Ft int 9223b2be97Sblymn.Fn reset_shell_mode "void" 9323b2be97Sblymn.Ft int 9423b2be97Sblymn.Fn echo "void" 9523b2be97Sblymn.Ft int 9623b2be97Sblymn.Fn noecho "void" 9723b2be97Sblymn.Ft int 9823b2be97Sblymn.Fn delay_output "int ms" 9923b2be97Sblymn.Ft char 10023b2be97Sblymn.Fn erasechar "void" 10123b2be97Sblymn.Ft int 10223b2be97Sblymn.Fn flushinp "void" 10323b2be97Sblymn.Ft int 10423b2be97Sblymn.Fn gettmode "void" 105c3111c04Swiz.Ft bool 10623b2be97Sblymn.Fn has_ic "void" 107c3111c04Swiz.Ft bool 10823b2be97Sblymn.Fn has_il "void" 10923b2be97Sblymn.Ft int 110c3111c04Swiz.Fn idcok "WINDOW *win" "bool flag" 11123b2be97Sblymn.Ft int 112c3111c04Swiz.Fn idlok "WINDOW *win" "bool flag" 11323b2be97Sblymn.Ft int 114c3111c04Swiz.Fn intrflush "WINDOW *win" "bool flag" 11511f267a0Sjdc.Ft void 11611f267a0Sjdc.Fn noqiflush "void" 11711f267a0Sjdc.Ft void 11811f267a0Sjdc.Fn qiflush "void" 11923b2be97Sblymn.Ft char 12023b2be97Sblymn.Fn killchar "void" 12123b2be97Sblymn.Ft int 122c3111c04Swiz.Fn meta "WINDOW *win" "bool flag" 12323b2be97Sblymn.Ft int 12423b2be97Sblymn.Fn napms "int ms" 12523b2be97Sblymn.Ft int 12623b2be97Sblymn.Fn nl "void" 12723b2be97Sblymn.Ft int 12823b2be97Sblymn.Fn nonl "void" 12923b2be97Sblymn.Ft int 13023b2be97Sblymn.Fn cbreak "void" 13123b2be97Sblymn.Ft int 13223b2be97Sblymn.Fn nocbreak "void" 13323b2be97Sblymn.Ft int 134a3c6a58eSblymn.Fn halfdelay "int" 135a3c6a58eSblymn.Ft int 13623b2be97Sblymn.Fn raw "void" 13723b2be97Sblymn.Ft int 13823b2be97Sblymn.Fn noraw "void" 13923b2be97Sblymn.Ft int 140a5a78d3cSroy.Fn typeahead "int filedes" 141a5a78d3cSroy.Ft int 14223b2be97Sblymn.Fn savetty "void" 14323b2be97Sblymn.Ft int 14423b2be97Sblymn.Fn resetty "void" 14523b2be97Sblymn.Sh DESCRIPTION 14623b2be97SblymnThese functions manipulate curses terminal settings. 14723b2be97Sblymn.Pp 14823b2be97SblymnThe 14938037cccSroy.Fn baudrate 150a21be3d2Sabhinavfunction extracts the output speed of the terminal 15138037cccSroyand returns it in bits per second. 15238037cccSroy.Pp 15338037cccSroyThe 15423b2be97Sblymn.Fn beep 15523b2be97Sblymnfunction rings the terminal bell, if this is possible. 15623b2be97SblymnFailing that, the terminal screen will be flashed. 15723b2be97SblymnIf neither of these are possible, then no action will be taken. 15823b2be97Sblymn.Fn flash 15923b2be97Sblymnwill flash the terminal screen if possible. 16023b2be97SblymnFailing that, the terminal bell will be rung. 16123b2be97SblymnIf neither of these are possible then no action will be taken. 16223b2be97Sblymn.Pp 16323b2be97SblymnThe cursor 16423b2be97Sblymnvisibility can be set by calling 16523b2be97Sblymn.Fn curs_set . 16623b2be97SblymnThe following visibility settings are valid for 16723b2be97Sblymn.Fn curs_set : 16823b2be97Sblymn.Pp 16923b2be97Sblymn.Bl -tag -width visibility -compact -offset indent 17023b2be97Sblymn.It Visibility 17123b2be97SblymnEffect 17223b2be97Sblymn.It 0 17323b2be97Sblymncursor is invisible. 17423b2be97Sblymn.It 1 17523b2be97Sblymncursor is normal visibility 17623b2be97Sblymn.It 2 17723b2be97Sblymncursor is high visibility 17823b2be97Sblymn.El 17923b2be97Sblymn.Pp 18023b2be97SblymnA successful call to 18123b2be97Sblymn.Fn curs_set 18223b2be97Sblymnwill return the previous visibility setting for the cursor. 18323b2be97Sblymn.Pp 18423b2be97SblymnThe 18523b2be97Sblymn.Fn delay_output 18623b2be97Sblymnfunction pauses the output to the terminal by sending the appropriate 18723b2be97Sblymnnumber of terminal pad characters such that the transmission time of 18823b2be97Sblymnthe pad characters will take 18923b2be97Sblymn.Fa ms 19023b2be97Sblymnmilliseconds. 19123b2be97Sblymn.Pp 19223b2be97SblymnCalling 19323b2be97Sblymn.Fn def_prog_mode 19423b2be97Sblymnwill cause the current terminal curses setting to be saved. 1959bfae9c8SsnjA subsequent call to 19623b2be97Sblymn.Fn reset_prog_mode , 19723b2be97Sblymnwill restore the saved settings. 19823b2be97SblymnThis is useful when calls to external programs are made that may 19923b2be97Sblymnreset the terminal characteristics. 20023b2be97Sblymn.Pp 20123b2be97SblymnThe 20223b2be97Sblymn.Fn def_shell_mode 20323b2be97Sblymnfunction saves the current terminal line settings. 20423b2be97SblymnThese settings are the ones that will be restored when the curses 20523b2be97Sblymnapplication exits. 20623b2be97SblymnConversely, 20723b2be97Sblymn.Fn reset_shell_mode 20823b2be97Sblymnwill save the current terminal curses settings for later restoration and 20923b2be97Sblymnrestores the previously saved terminal line settings. 21023b2be97Sblymn.Pp 21123b2be97SblymnThe 21223b2be97Sblymn.Fn echo 21323b2be97Sblymnfunction turns on curses echo mode, characters entered will be echoed 21423b2be97Sblymnto the terminal by curses. 21523b2be97SblymnThe 21623b2be97Sblymn.Fn noecho 21723b2be97Sblymnfunction disables this feature. 21823b2be97Sblymn.Pp 21923b2be97SblymnThe current erase character for the terminal can be determined by 22023b2be97Sblymncalling the 22123b2be97Sblymn.Fn erasechar 22223b2be97Sblymnfunction. 22323b2be97Sblymn.Pp 22423b2be97SblymnThe 22523b2be97Sblymn.Fn flushinp 22623b2be97Sblymnfunction discards any pending input for the current screen. 22723b2be97Sblymn.Pp 22823b2be97SblymnThe modes 22923b2be97Sblymnfor the current terminal can be reset by calling 23023b2be97Sblymn.Fn gettmode , 23123b2be97Sblymnthis will perform the initialisation on the terminal that is normally 23223b2be97Sblymndone by curses at start up. 23323b2be97Sblymn.Pp 23423b2be97SblymnThe 23523b2be97Sblymn.Fn has_ic 23623b2be97Sblymnfunction returns either 23723b2be97Sblymn.Dv TRUE 23823b2be97Sblymnor 23923b2be97Sblymn.Dv FALSE 24023b2be97Sblymndepending on whether or not the terminal has a insert character 24123b2be97Sblymncapability or not. 24223b2be97SblymnSimilarly the 24323b2be97Sblymn.Fn has_il 24423b2be97Sblymnfunction does the same test but for a insert line capability. 24523b2be97Sblymn.Pp 24623b2be97SblymnThe use of the insert character capability in curses operations can be 24723b2be97Sblymnenabled or disabled by calling 24823b2be97Sblymn.Fn idcok 24923b2be97Sblymnon the desired window. 25023b2be97SblymnSimilarly, the use of the insert line capability can be controlled using the 25123b2be97Sblymn.Fn idlok 25223b2be97Sblymnfunction. 25323b2be97Sblymn.Pp 25423b2be97SblymnThe 25523b2be97Sblymn.Fn intrflush 25623b2be97Sblymnfunction controls whether or not a flush of the input buffer is 25723b2be97Sblymnperformed when an interrupt key (kill, suspend or quit) is pressed. 25823b2be97SblymnThe 25911f267a0Sjdc.Fa win 26023b2be97Sblymnparameter is ignored. 26111f267a0SjdcThe 26211f267a0Sjdc.Fn noqiflush 26311f267a0Sjdcfunction is equivalent to 26411f267a0Sjdc.Fn intrflush stdscr FALSE . 26511f267a0SjdcThe 26611f267a0Sjdc.Fn qiflush 26711f267a0Sjdcfunction is equivalent to 26811f267a0Sjdc.Fn intrflush stdscr TRUE . 26923b2be97Sblymn.Pp 27023b2be97SblymnThe character that performs the line kill function can be determined 27123b2be97Sblymnby calling the 27223b2be97Sblymn.Fn killchar 27323b2be97Sblymnfunction. 27423b2be97Sblymn.Pp 27523b2be97SblymnThe 27623b2be97Sblymn.Fn meta 27723b2be97Sblymnfunction turns on and off the generation of 8 bit characters by the 27823b2be97Sblymnterminal, if 27923b2be97Sblymn.Fa flag 28023b2be97Sblymnis 28123b2be97Sblymn.Dv FALSE 28223b2be97Sblymnthen only 7 bit characters will be returned, if 28323b2be97Sblymn.Fa flag 28423b2be97Sblymnis 28523b2be97Sblymn.Dv TRUE 28623b2be97Sblymnthen 8 bit characters will be returned by the terminal. 28723b2be97Sblymn.Pp 28823b2be97SblymnThe 28923b2be97Sblymn.Fn napms 29023b2be97Sblymncauses the application to sleep for the number of milliseconds 29123b2be97Sblymnspecified by 29223b2be97Sblymn.Fa ms . 29323b2be97Sblymn.Pp 29423b2be97SblymnCalling 29523b2be97Sblymn.Fn nl 29623b2be97Sblymnwill cause curses to map all carriage returns to newlines on input, 29723b2be97Sblymnthis functionality is enabled by default. 29823b2be97SblymnThe 29923b2be97Sblymn.Fn nonl 30023b2be97Sblymnfunction disables this behaviour. 30123b2be97Sblymn.Pp 30223b2be97SblymnThe 30323b2be97Sblymn.Fn cbreak 30423b2be97Sblymnfunction will put the terminal into cbreak mode, which means that 30523b2be97Sblymncharacters will be returned one at a time instead of waiting for a 30623b2be97Sblymnnewline character, line discipline processing will be performed. 30723b2be97SblymnThe 30823b2be97Sblymn.Fn nocbreak 30923b2be97Sblymnfunction disables this mode. 31023b2be97Sblymn.Pp 311a3c6a58eSblymnCalling 312a3c6a58eSblymn.Fn halfdelay 313a3c6a58eSblymnputs the terminal into the same mode as 314a3c6a58eSblymn.Fn cbreak 3155cd5ff6dSwizwith the exception that if no character is received within the specified 316a3c6a58eSblymnnumber of tenths of a second then the input routine will return 317a3c6a58eSblymn.Er ERR . 318a3c6a58eSblymnThis mode can be cancelled by calling 319a3c6a58eSblymn.Fn nocbreak . 320a3c6a58eSblymnThe valid range for the timeout is from 1 to 255 tenths of a second. 321a3c6a58eSblymn.Pp 32223b2be97SblymnThe 32323b2be97Sblymn.Fn noraw 32423b2be97Sblymnfunction sets the input mode for the current terminal into Cooked mode, 32523b2be97Sblymnthat is input character translation and signal character processing is 32623b2be97Sblymnperformed. 32723b2be97SblymnThe 32823b2be97Sblymn.Fn raw 32923b2be97Sblymnfunction puts the terminal into Raw mode, no input character 33023b2be97Sblymntranslation is done nor is signal character processing. 33123b2be97Sblymn.Pp 332a5a78d3cSroyThe 333a5a78d3cSroy.Fn typeahead 334a5a78d3cSroyfunction controls the detection of typeahead during a refresh based on the 335a5a78d3cSroyvalue of 336a5a78d3cSroy.Va filedes : 337a5a78d3cSroy.Bl -bullet -compact 338a5a78d3cSroy.It 339a5a78d3cSroyIf 340a5a78d3cSroy.Ar filedes 341a5a78d3cSroyis a valid file descriptor, typeahead is enabled during refresh; 342a5a78d3cSroyCurses periodically checks 343a5a78d3cSroy.Ar filedes 344a5a78d3cSroyfor input and aborts the refresh if any character is available. 345a5a78d3cSroyThe value of 346a5a78d3cSroy.Ar filedes 347a5a78d3cSroyneed not be the file descriptor on which the refresh is occurring. 348a5a78d3cSroy.It 349a5a78d3cSroyIf 350a5a78d3cSroy.Ar filedes 351a5a78d3cSroyis \-1, Curses does not check for typeahead during refresh. 352a5a78d3cSroy.El 353a5a78d3cSroy.Pp 35423b2be97SblymnThe terminal 35523b2be97Sblymntty flags can be saved by calling 35623b2be97Sblymn.Fn savetty 35723b2be97Sblymnand may be restored by calling 35823b2be97Sblymn.Fn resetty , 35923b2be97Sblymnthe use of these functions is discouraged as they may cause the 3609bfae9c8Ssnjterminal to be put into a state that is incompatible with curses 36123b2be97Sblymnoperation. 36223b2be97Sblymn.Sh RETURN VALUES 36323b2be97SblymnFunctions returning pointers will return 36423b2be97Sblymn.Dv NULL 36523b2be97Sblymnif an error is detected. 36623b2be97SblymnThe functions that return an int will return one of the following 36723b2be97Sblymnvalues: 36823b2be97Sblymn.Pp 36923b2be97Sblymn.Bl -tag -width ERR -compact 370*ab43c492Swiz.It Dv OK 37123b2be97SblymnThe function completed successfully. 372*ab43c492Swiz.It Dv ERR 37323b2be97SblymnAn error occurred in the function. 37423b2be97Sblymn.El 37523b2be97Sblymn.Sh SEE ALSO 37623b2be97Sblymn.Xr getch 3 , 37723b2be97Sblymn.Xr termios 4 37823b2be97Sblymn.Sh NOTES 37923b2be97SblymnThe 38023b2be97Sblymn.Fn idcok 38123b2be97Sblymnand 38223b2be97Sblymn.Fn idlok 38323b2be97Sblymncurrently have no effect on the curses code at all, currently curses 38423b2be97Sblymnwill always use the terminal insert character and insert line 38523b2be97Sblymncapabilities if available. 38623b2be97Sblymn.Sh STANDARDS 38723b2be97SblymnThe 38823b2be97Sblymn.Nx 38923b2be97SblymnCurses library complies with the X/Open Curses specification, part of the 39023b2be97SblymnSingle Unix Specification. 39123b2be97Sblymn.Sh HISTORY 39223b2be97SblymnThe Curses package appeared in 39323b2be97Sblymn.Bx 4.0 . 394