1*11f267a0Sjdc.\" $NetBSD: curses_tty.3,v 1.6 2003/06/20 06:58:54 jdc 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.\" 33*11f267a0Sjdc.Dd June 13, 2003 3423b2be97Sblymn.Dt CURSES_TTY 3 3523b2be97Sblymn.Os 3623b2be97Sblymn.Sh NAME 3723b2be97Sblymn.NM curses_tty , 3823b2be97Sblymn.Nm beep , 3923b2be97Sblymn.Nm flash , 4023b2be97Sblymn.Nm curs_set , 4123b2be97Sblymn.Nm def_prog_mode , 4223b2be97Sblymn.Nm reset_prog_mode , 4323b2be97Sblymn.Nm def_shell_mode , 4423b2be97Sblymn.Nm reset_shell_mode , 4523b2be97Sblymn.Nm echo , 4623b2be97Sblymn.Nm noecho , 4723b2be97Sblymn.Nm delay_output , 4823b2be97Sblymn.Nm erasechar , 4923b2be97Sblymn.Nm flushinp , 5023b2be97Sblymn.Nm gettmode , 51a3c6a58eSblymn.Nm halfdelay , 5223b2be97Sblymn.Nm has_ic , 5323b2be97Sblymn.Nm has_il , 5423b2be97Sblymn.Nm idcok , 5523b2be97Sblymn.Nm idlok , 5623b2be97Sblymn.Nm intrflush , 57*11f267a0Sjdc.Nm noqiflush , 58*11f267a0Sjdc.Nm qiflush , 5923b2be97Sblymn.Nm killchar , 6023b2be97Sblymn.Nm meta , 6123b2be97Sblymn.Nm napms , 6223b2be97Sblymn.Nm nl , 6323b2be97Sblymn.Nm nonl , 6423b2be97Sblymn.Nm cbreak , 6523b2be97Sblymn.Nm nocbreak , 6623b2be97Sblymn.Nm raw , 6723b2be97Sblymn.Nm noraw , 6823b2be97Sblymn.Nm savetty , 6923b2be97Sblymn.Nm resetty , 7023b2be97Sblymn.Nd curses terminal manipulation routines 7123b2be97Sblymn.Sh LIBRARY 7223b2be97Sblymn.Lb libcurses 7323b2be97Sblymn.Sh SYNOPSIS 74472351e1Swiz.In curses.h 7523b2be97Sblymn.Ft int 7623b2be97Sblymn.Fn beep "void" 7723b2be97Sblymn.Ft int 7823b2be97Sblymn.Fn flash "void" 7923b2be97Sblymn.Ft int 8023b2be97Sblymn.Fn curs_set "int visibility" 8123b2be97Sblymn.Ft int 8223b2be97Sblymn.Fn def_prog_mode "void" 8323b2be97Sblymn.Ft int 8423b2be97Sblymn.Fn reset_prog_mode "void" 8523b2be97Sblymn.Ft int 8623b2be97Sblymn.Fn def_shell_mode "void" 8723b2be97Sblymn.Ft int 8823b2be97Sblymn.Fn reset_shell_mode "void" 8923b2be97Sblymn.Ft int 9023b2be97Sblymn.Fn echo "void" 9123b2be97Sblymn.Ft int 9223b2be97Sblymn.Fn noecho "void" 9323b2be97Sblymn.Ft int 9423b2be97Sblymn.Fn delay_output "int ms" 9523b2be97Sblymn.Ft char 9623b2be97Sblymn.Fn erasechar "void" 9723b2be97Sblymn.Ft int 9823b2be97Sblymn.Fn flushinp "void" 9923b2be97Sblymn.Ft int 10023b2be97Sblymn.Fn gettmode "void" 10123b2be97Sblymn.Ft int 10223b2be97Sblymn.Fn has_ic "void" 10323b2be97Sblymn.Ft int 10423b2be97Sblymn.Fn has_il "void" 10523b2be97Sblymn.Ft int 10623b2be97Sblymn.Fn idcok "WINDOW *win" "boolf flag" 10723b2be97Sblymn.Ft int 10823b2be97Sblymn.Fn idlok "WINDOW *win" "boolf flag" 10923b2be97Sblymn.Ft int 11023b2be97Sblymn.Fn intrflush "WINDOW *win" "boolf flag" 111*11f267a0Sjdc.Ft void 112*11f267a0Sjdc.Fn noqiflush "void" 113*11f267a0Sjdc.Ft void 114*11f267a0Sjdc.Fn qiflush "void" 11523b2be97Sblymn.Ft char 11623b2be97Sblymn.Fn killchar "void" 11723b2be97Sblymn.Ft int 11823b2be97Sblymn.Fn meta "WINDOW *win" "boolf flag" 11923b2be97Sblymn.Ft int 12023b2be97Sblymn.Fn napms "int ms" 12123b2be97Sblymn.Ft int 12223b2be97Sblymn.Fn nl "void" 12323b2be97Sblymn.Ft int 12423b2be97Sblymn.Fn nonl "void" 12523b2be97Sblymn.Ft int 12623b2be97Sblymn.Fn cbreak "void" 12723b2be97Sblymn.Ft int 12823b2be97Sblymn.Fn nocbreak "void" 12923b2be97Sblymn.Ft int 130a3c6a58eSblymn.Fn halfdelay "int" 131a3c6a58eSblymn.Ft int 13223b2be97Sblymn.Fn raw "void" 13323b2be97Sblymn.Ft int 13423b2be97Sblymn.Fn noraw "void" 13523b2be97Sblymn.Ft int 13623b2be97Sblymn.Fn savetty "void" 13723b2be97Sblymn.Ft int 13823b2be97Sblymn.Fn resetty "void" 13923b2be97Sblymn.Sh DESCRIPTION 14023b2be97SblymnThese functions manipulate curses terminal settings. 14123b2be97Sblymn.Pp 14223b2be97SblymnThe 14323b2be97Sblymn.Fn beep 14423b2be97Sblymnfunction rings the terminal bell, if this is possible. 14523b2be97SblymnFailing that, the terminal screen will be flashed. 14623b2be97SblymnIf neither of these are possible, then no action will be taken. 14723b2be97Sblymn.Fn flash 14823b2be97Sblymnwill flash the terminal screen if possible. 14923b2be97SblymnFailing that, the terminal bell will be rung. 15023b2be97SblymnIf neither of these are possible then no action will be taken. 15123b2be97Sblymn.Pp 15223b2be97SblymnThe cursor 15323b2be97Sblymnvisibility can be set by calling 15423b2be97Sblymn.Fn curs_set . 15523b2be97SblymnThe following visibility settings are valid for 15623b2be97Sblymn.Fn curs_set : 15723b2be97Sblymn.Pp 15823b2be97Sblymn.Bl -tag -width visibility -compact -offset indent 15923b2be97Sblymn.It Visibility 16023b2be97SblymnEffect 16123b2be97Sblymn.It 0 16223b2be97Sblymncursor is invisible. 16323b2be97Sblymn.It 1 16423b2be97Sblymncursor is normal visibility 16523b2be97Sblymn.It 2 16623b2be97Sblymncursor is high visibility 16723b2be97Sblymn.El 16823b2be97Sblymn.Pp 16923b2be97SblymnA successful call to 17023b2be97Sblymn.Fn curs_set 17123b2be97Sblymnwill return the previous visibility setting for the cursor. 17223b2be97Sblymn.Pp 17323b2be97SblymnThe 17423b2be97Sblymn.Fn delay_output 17523b2be97Sblymnfunction pauses the output to the terminal by sending the appropriate 17623b2be97Sblymnnumber of terminal pad characters such that the transmission time of 17723b2be97Sblymnthe pad characters will take 17823b2be97Sblymn.Fa ms 17923b2be97Sblymnmilliseconds. 18023b2be97Sblymn.Pp 18123b2be97SblymnCalling 18223b2be97Sblymn.Fn def_prog_mode 18323b2be97Sblymnwill cause the current terminal curses setting to be saved. 18423b2be97SblymnA subequent call to 18523b2be97Sblymn.Fn reset_prog_mode , 18623b2be97Sblymnwill restore the saved settings. 18723b2be97SblymnThis is useful when calls to external programs are made that may 18823b2be97Sblymnreset the terminal characteristics. 18923b2be97Sblymn.Pp 19023b2be97SblymnThe 19123b2be97Sblymn.Fn def_shell_mode 19223b2be97Sblymnfunction saves the current terminal line settings. 19323b2be97SblymnThese settings are the ones that will be restored when the curses 19423b2be97Sblymnapplication exits. 19523b2be97SblymnConversely, 19623b2be97Sblymn.Fn reset_shell_mode 19723b2be97Sblymnwill save the current terminal curses settings for later restoration and 19823b2be97Sblymnrestores the previously saved terminal line settings. 19923b2be97Sblymn.Pp 20023b2be97SblymnThe 20123b2be97Sblymn.Fn echo 20223b2be97Sblymnfunction turns on curses echo mode, characters entered will be echoed 20323b2be97Sblymnto the terminal by curses. 20423b2be97SblymnThe 20523b2be97Sblymn.Fn noecho 20623b2be97Sblymnfunction disables this feature. 20723b2be97Sblymn.Pp 20823b2be97SblymnThe current erase character for the terminal can be determined by 20923b2be97Sblymncalling the 21023b2be97Sblymn.Fn erasechar 21123b2be97Sblymnfunction. 21223b2be97Sblymn.Pp 21323b2be97SblymnThe 21423b2be97Sblymn.Fn flushinp 21523b2be97Sblymnfunction discards any pending input for the current screen. 21623b2be97Sblymn.Pp 21723b2be97SblymnThe modes 21823b2be97Sblymnfor the current terminal can be reset by calling 21923b2be97Sblymn.Fn gettmode , 22023b2be97Sblymnthis will perform the initialisation on the terminal that is normally 22123b2be97Sblymndone by curses at start up. 22223b2be97Sblymn.Pp 22323b2be97SblymnThe 22423b2be97Sblymn.Fn has_ic 22523b2be97Sblymnfunction returns either 22623b2be97Sblymn.Dv TRUE 22723b2be97Sblymnor 22823b2be97Sblymn.Dv FALSE 22923b2be97Sblymndepending on whether or not the terminal has a insert character 23023b2be97Sblymncapability or not. 23123b2be97SblymnSimilarly the 23223b2be97Sblymn.Fn has_il 23323b2be97Sblymnfunction does the same test but for a insert line capability. 23423b2be97Sblymn.Pp 23523b2be97SblymnThe use of the insert character capability in curses operations can be 23623b2be97Sblymnenabled or disabled by calling 23723b2be97Sblymn.Fn idcok 23823b2be97Sblymnon the desired window. 23923b2be97SblymnSimilarly, the use of the insert line capability can be controlled using the 24023b2be97Sblymn.Fn idlok 24123b2be97Sblymnfunction. 24223b2be97Sblymn.Pp 24323b2be97SblymnThe 24423b2be97Sblymn.Fn intrflush 24523b2be97Sblymnfunction controls whether or not a flush of the input buffer is 24623b2be97Sblymnperformed when an interrupt key (kill, suspend or quit) is pressed. 24723b2be97SblymnThe 248*11f267a0Sjdc.Fa win 24923b2be97Sblymnparameter is ignored. 250*11f267a0SjdcThe 251*11f267a0Sjdc.Fn noqiflush 252*11f267a0Sjdcfunction is equivalent to 253*11f267a0Sjdc.Fn intrflush stdscr FALSE . 254*11f267a0SjdcThe 255*11f267a0Sjdc.Fn qiflush 256*11f267a0Sjdcfunction is equivalent to 257*11f267a0Sjdc.Fn intrflush stdscr TRUE . 25823b2be97Sblymn.Pp 25923b2be97SblymnThe character that performs the line kill function can be determined 26023b2be97Sblymnby calling the 26123b2be97Sblymn.Fn killchar 26223b2be97Sblymnfunction. 26323b2be97Sblymn.Pp 26423b2be97SblymnThe 26523b2be97Sblymn.Fn meta 26623b2be97Sblymnfunction turns on and off the generation of 8 bit characters by the 26723b2be97Sblymnterminal, if 26823b2be97Sblymn.Fa flag 26923b2be97Sblymnis 27023b2be97Sblymn.Dv FALSE 27123b2be97Sblymnthen only 7 bit characters will be returned, if 27223b2be97Sblymn.Fa flag 27323b2be97Sblymnis 27423b2be97Sblymn.Dv TRUE 27523b2be97Sblymnthen 8 bit characters will be returned by the terminal. 27623b2be97Sblymn.Pp 27723b2be97SblymnThe 27823b2be97Sblymn.Fn napms 27923b2be97Sblymncauses the application to sleep for the number of milliseconds 28023b2be97Sblymnspecified by 28123b2be97Sblymn.Fa ms . 28223b2be97Sblymn.Pp 28323b2be97SblymnCalling 28423b2be97Sblymn.Fn nl 28523b2be97Sblymnwill cause curses to map all carriage returns to newlines on input, 28623b2be97Sblymnthis functionality is enabled by default. 28723b2be97SblymnThe 28823b2be97Sblymn.Fn nonl 28923b2be97Sblymnfunction disables this behaviour. 29023b2be97Sblymn.Pp 29123b2be97SblymnThe 29223b2be97Sblymn.Fn cbreak 29323b2be97Sblymnfunction will put the terminal into cbreak mode, which means that 29423b2be97Sblymncharacters will be returned one at a time instead of waiting for a 29523b2be97Sblymnnewline character, line discipline processing will be performed. 29623b2be97SblymnThe 29723b2be97Sblymn.Fn nocbreak 29823b2be97Sblymnfunction disables this mode. 29923b2be97Sblymn.Pp 300a3c6a58eSblymnCalling 301a3c6a58eSblymn.Fn halfdelay 302a3c6a58eSblymnputs the terminal into the same mode as 303a3c6a58eSblymn.Fn cbreak 3045cd5ff6dSwizwith the exception that if no character is received within the specified 305a3c6a58eSblymnnumber of tenths of a second then the input routine will return 306a3c6a58eSblymn.Er ERR . 307a3c6a58eSblymnThis mode can be cancelled by calling 308a3c6a58eSblymn.Fn nocbreak . 309a3c6a58eSblymnThe valid range for the timeout is from 1 to 255 tenths of a second. 310a3c6a58eSblymn.Pp 31123b2be97SblymnThe 31223b2be97Sblymn.Fn noraw 31323b2be97Sblymnfunction sets the input mode for the current terminal into Cooked mode, 31423b2be97Sblymnthat is input character translation and signal character processing is 31523b2be97Sblymnperformed. 31623b2be97SblymnThe 31723b2be97Sblymn.Fn raw 31823b2be97Sblymnfunction puts the terminal into Raw mode, no input character 31923b2be97Sblymntranslation is done nor is signal character processing. 32023b2be97Sblymn.Pp 32123b2be97SblymnThe terminal 32223b2be97Sblymntty flags can be saved by calling 32323b2be97Sblymn.Fn savetty 32423b2be97Sblymnand may be restored by calling 32523b2be97Sblymn.Fn resetty , 32623b2be97Sblymnthe use of these functions is discouraged as they may cause the 32723b2be97Sblymnterminal to be put into a state that is incompatiable with curses 32823b2be97Sblymnoperation. 32923b2be97Sblymn.Sh RETURN VALUES 33023b2be97SblymnFunctions returning pointers will return 33123b2be97Sblymn.Dv NULL 33223b2be97Sblymnif an error is detected. 33323b2be97SblymnThe functions that return an int will return one of the following 33423b2be97Sblymnvalues: 33523b2be97Sblymn.Pp 33623b2be97Sblymn.Bl -tag -width ERR -compact 33723b2be97Sblymn.It Er OK 33823b2be97SblymnThe function completed successfully. 33923b2be97Sblymn.It Er ERR 34023b2be97SblymnAn error occurred in the function. 34123b2be97Sblymn.El 34223b2be97Sblymn.Sh SEE ALSO 34323b2be97Sblymn.Xr getch 3 , 34423b2be97Sblymn.Xr termios 4 34523b2be97Sblymn.Sh NOTES 34623b2be97SblymnThe 34723b2be97Sblymn.Fn idcok 34823b2be97Sblymnand 34923b2be97Sblymn.Fn idlok 35023b2be97Sblymncurrently have no effect on the curses code at all, currently curses 35123b2be97Sblymnwill always use the terminal insert character and insert line 35223b2be97Sblymncapabilities if available. 35323b2be97Sblymn.Sh STANDARDS 35423b2be97SblymnThe 35523b2be97Sblymn.Nx 35623b2be97SblymnCurses library complies with the X/Open Curses specification, part of the 35723b2be97SblymnSingle Unix Specification. 35823b2be97Sblymn.Sh HISTORY 35923b2be97SblymnThe Curses package appeared in 36023b2be97Sblymn.Bx 4.0 . 361