1*104b35feSgrant.\" $NetBSD: curses_tty.3,v 1.4 2003/02/14 16:29:12 grant Exp $ 223b2be97Sblymn.\" 323b2be97Sblymn.\" Copyright (c) 2002 4*104b35feSgrant.\" 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.\" 335cd5ff6dSwiz.Dd January 9, 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 , 5723b2be97Sblymn.Nm killchar , 5823b2be97Sblymn.Nm meta , 5923b2be97Sblymn.Nm napms , 6023b2be97Sblymn.Nm nl , 6123b2be97Sblymn.Nm nonl , 6223b2be97Sblymn.Nm cbreak , 6323b2be97Sblymn.Nm nocbreak , 6423b2be97Sblymn.Nm raw , 6523b2be97Sblymn.Nm noraw , 6623b2be97Sblymn.Nm savetty , 6723b2be97Sblymn.Nm resetty , 6823b2be97Sblymn.Nd curses terminal manipulation routines 6923b2be97Sblymn.Sh LIBRARY 7023b2be97Sblymn.Lb libcurses 7123b2be97Sblymn.Sh SYNOPSIS 7223b2be97Sblymn.Fd #include \*[Lt]curses.h\*[Gt] 7323b2be97Sblymn.Ft int 7423b2be97Sblymn.Fn beep "void" 7523b2be97Sblymn.Ft int 7623b2be97Sblymn.Fn flash "void" 7723b2be97Sblymn.Ft int 7823b2be97Sblymn.Fn curs_set "int visibility" 7923b2be97Sblymn.Ft int 8023b2be97Sblymn.Fn def_prog_mode "void" 8123b2be97Sblymn.Ft int 8223b2be97Sblymn.Fn reset_prog_mode "void" 8323b2be97Sblymn.Ft int 8423b2be97Sblymn.Fn def_shell_mode "void" 8523b2be97Sblymn.Ft int 8623b2be97Sblymn.Fn reset_shell_mode "void" 8723b2be97Sblymn.Ft int 8823b2be97Sblymn.Fn echo "void" 8923b2be97Sblymn.Ft int 9023b2be97Sblymn.Fn noecho "void" 9123b2be97Sblymn.Ft int 9223b2be97Sblymn.Fn delay_output "int ms" 9323b2be97Sblymn.Ft char 9423b2be97Sblymn.Fn erasechar "void" 9523b2be97Sblymn.Ft int 9623b2be97Sblymn.Fn flushinp "void" 9723b2be97Sblymn.Ft int 9823b2be97Sblymn.Fn gettmode "void" 9923b2be97Sblymn.Ft int 10023b2be97Sblymn.Fn has_ic "void" 10123b2be97Sblymn.Ft int 10223b2be97Sblymn.Fn has_il "void" 10323b2be97Sblymn.Ft int 10423b2be97Sblymn.Fn idcok "WINDOW *win" "boolf flag" 10523b2be97Sblymn.Ft int 10623b2be97Sblymn.Fn idlok "WINDOW *win" "boolf flag" 10723b2be97Sblymn.Ft int 10823b2be97Sblymn.Fn intrflush "WINDOW *win" "boolf flag" 10923b2be97Sblymn.Ft char 11023b2be97Sblymn.Fn killchar "void" 11123b2be97Sblymn.Ft int 11223b2be97Sblymn.Fn meta "WINDOW *win" "boolf flag" 11323b2be97Sblymn.Ft int 11423b2be97Sblymn.Fn napms "int ms" 11523b2be97Sblymn.Ft int 11623b2be97Sblymn.Fn nl "void" 11723b2be97Sblymn.Ft int 11823b2be97Sblymn.Fn nonl "void" 11923b2be97Sblymn.Ft int 12023b2be97Sblymn.Fn cbreak "void" 12123b2be97Sblymn.Ft int 12223b2be97Sblymn.Fn nocbreak "void" 12323b2be97Sblymn.Ft int 124a3c6a58eSblymn.Fn halfdelay "int" 125a3c6a58eSblymn.Ft int 12623b2be97Sblymn.Fn raw "void" 12723b2be97Sblymn.Ft int 12823b2be97Sblymn.Fn noraw "void" 12923b2be97Sblymn.Ft int 13023b2be97Sblymn.Fn savetty "void" 13123b2be97Sblymn.Ft int 13223b2be97Sblymn.Fn resetty "void" 13323b2be97Sblymn.Sh DESCRIPTION 13423b2be97SblymnThese functions manipulate curses terminal settings. 13523b2be97Sblymn.Pp 13623b2be97SblymnThe 13723b2be97Sblymn.Fn beep 13823b2be97Sblymnfunction rings the terminal bell, if this is possible. 13923b2be97SblymnFailing that, the terminal screen will be flashed. 14023b2be97SblymnIf neither of these are possible, then no action will be taken. 14123b2be97Sblymn.Fn flash 14223b2be97Sblymnwill flash the terminal screen if possible. 14323b2be97SblymnFailing that, the terminal bell will be rung. 14423b2be97SblymnIf neither of these are possible then no action will be taken. 14523b2be97Sblymn.Pp 14623b2be97SblymnThe cursor 14723b2be97Sblymnvisibility can be set by calling 14823b2be97Sblymn.Fn curs_set . 14923b2be97SblymnThe following visibility settings are valid for 15023b2be97Sblymn.Fn curs_set : 15123b2be97Sblymn.Pp 15223b2be97Sblymn.Bl -tag -width visibility -compact -offset indent 15323b2be97Sblymn.It Visibility 15423b2be97SblymnEffect 15523b2be97Sblymn.It 0 15623b2be97Sblymncursor is invisible. 15723b2be97Sblymn.It 1 15823b2be97Sblymncursor is normal visibility 15923b2be97Sblymn.It 2 16023b2be97Sblymncursor is high visibility 16123b2be97Sblymn.El 16223b2be97Sblymn.Pp 16323b2be97SblymnA successful call to 16423b2be97Sblymn.Fn curs_set 16523b2be97Sblymnwill return the previous visibility setting for the cursor. 16623b2be97Sblymn.Pp 16723b2be97SblymnThe 16823b2be97Sblymn.Fn delay_output 16923b2be97Sblymnfunction pauses the output to the terminal by sending the appropriate 17023b2be97Sblymnnumber of terminal pad characters such that the transmission time of 17123b2be97Sblymnthe pad characters will take 17223b2be97Sblymn.Fa ms 17323b2be97Sblymnmilliseconds. 17423b2be97Sblymn.Pp 17523b2be97SblymnCalling 17623b2be97Sblymn.Fn def_prog_mode 17723b2be97Sblymnwill cause the current terminal curses setting to be saved. 17823b2be97SblymnA subequent call to 17923b2be97Sblymn.Fn reset_prog_mode , 18023b2be97Sblymnwill restore the saved settings. 18123b2be97SblymnThis is useful when calls to external programs are made that may 18223b2be97Sblymnreset the terminal characteristics. 18323b2be97Sblymn.Pp 18423b2be97SblymnThe 18523b2be97Sblymn.Fn def_shell_mode 18623b2be97Sblymnfunction saves the current terminal line settings. 18723b2be97SblymnThese settings are the ones that will be restored when the curses 18823b2be97Sblymnapplication exits. 18923b2be97SblymnConversely, 19023b2be97Sblymn.Fn reset_shell_mode 19123b2be97Sblymnwill save the current terminal curses settings for later restoration and 19223b2be97Sblymnrestores the previously saved terminal line settings. 19323b2be97Sblymn.Pp 19423b2be97SblymnThe 19523b2be97Sblymn.Fn echo 19623b2be97Sblymnfunction turns on curses echo mode, characters entered will be echoed 19723b2be97Sblymnto the terminal by curses. 19823b2be97SblymnThe 19923b2be97Sblymn.Fn noecho 20023b2be97Sblymnfunction disables this feature. 20123b2be97Sblymn.Pp 20223b2be97SblymnThe current erase character for the terminal can be determined by 20323b2be97Sblymncalling the 20423b2be97Sblymn.Fn erasechar 20523b2be97Sblymnfunction. 20623b2be97Sblymn.Pp 20723b2be97SblymnThe 20823b2be97Sblymn.Fn flushinp 20923b2be97Sblymnfunction discards any pending input for the current screen. 21023b2be97Sblymn.Pp 21123b2be97SblymnThe modes 21223b2be97Sblymnfor the current terminal can be reset by calling 21323b2be97Sblymn.Fn gettmode , 21423b2be97Sblymnthis will perform the initialisation on the terminal that is normally 21523b2be97Sblymndone by curses at start up. 21623b2be97Sblymn.Pp 21723b2be97SblymnThe 21823b2be97Sblymn.Fn has_ic 21923b2be97Sblymnfunction returns either 22023b2be97Sblymn.Dv TRUE 22123b2be97Sblymnor 22223b2be97Sblymn.Dv FALSE 22323b2be97Sblymndepending on whether or not the terminal has a insert character 22423b2be97Sblymncapability or not. 22523b2be97SblymnSimilarly the 22623b2be97Sblymn.Fn has_il 22723b2be97Sblymnfunction does the same test but for a insert line capability. 22823b2be97Sblymn.Pp 22923b2be97SblymnThe use of the insert character capability in curses operations can be 23023b2be97Sblymnenabled or disabled by calling 23123b2be97Sblymn.Fn idcok 23223b2be97Sblymnon the desired window. 23323b2be97SblymnSimilarly, the use of the insert line capability can be controlled using the 23423b2be97Sblymn.Fn idlok 23523b2be97Sblymnfunction. 23623b2be97Sblymn.Pp 23723b2be97SblymnThe 23823b2be97Sblymn.Fn intrflush 23923b2be97Sblymnfunction controls whether or not a flush of the input buffer is 24023b2be97Sblymnperformed when an interrupt key (kill, suspend or quit) is pressed. 24123b2be97SblymnThe 24223b2be97Sblymn.Fn win 24323b2be97Sblymnparameter is ignored. 24423b2be97Sblymn.Pp 24523b2be97SblymnThe character that performs the line kill function can be determined 24623b2be97Sblymnby calling the 24723b2be97Sblymn.Fn killchar 24823b2be97Sblymnfunction. 24923b2be97Sblymn.Pp 25023b2be97SblymnThe 25123b2be97Sblymn.Fn meta 25223b2be97Sblymnfunction turns on and off the generation of 8 bit characters by the 25323b2be97Sblymnterminal, if 25423b2be97Sblymn.Fa flag 25523b2be97Sblymnis 25623b2be97Sblymn.Dv FALSE 25723b2be97Sblymnthen only 7 bit characters will be returned, if 25823b2be97Sblymn.Fa flag 25923b2be97Sblymnis 26023b2be97Sblymn.Dv TRUE 26123b2be97Sblymnthen 8 bit characters will be returned by the terminal. 26223b2be97Sblymn.Pp 26323b2be97SblymnThe 26423b2be97Sblymn.Fn napms 26523b2be97Sblymncauses the application to sleep for the number of milliseconds 26623b2be97Sblymnspecified by 26723b2be97Sblymn.Fa ms . 26823b2be97Sblymn.Pp 26923b2be97SblymnCalling 27023b2be97Sblymn.Fn nl 27123b2be97Sblymnwill cause curses to map all carriage returns to newlines on input, 27223b2be97Sblymnthis functionality is enabled by default. 27323b2be97SblymnThe 27423b2be97Sblymn.Fn nonl 27523b2be97Sblymnfunction disables this behaviour. 27623b2be97Sblymn.Pp 27723b2be97SblymnThe 27823b2be97Sblymn.Fn cbreak 27923b2be97Sblymnfunction will put the terminal into cbreak mode, which means that 28023b2be97Sblymncharacters will be returned one at a time instead of waiting for a 28123b2be97Sblymnnewline character, line discipline processing will be performed. 28223b2be97SblymnThe 28323b2be97Sblymn.Fn nocbreak 28423b2be97Sblymnfunction disables this mode. 28523b2be97Sblymn.Pp 286a3c6a58eSblymnCalling 287a3c6a58eSblymn.Fn halfdelay 288a3c6a58eSblymnputs the terminal into the same mode as 289a3c6a58eSblymn.Fn cbreak 2905cd5ff6dSwizwith the exception that if no character is received within the specified 291a3c6a58eSblymnnumber of tenths of a second then the input routine will return 292a3c6a58eSblymn.Er ERR . 293a3c6a58eSblymnThis mode can be cancelled by calling 294a3c6a58eSblymn.Fn nocbreak . 295a3c6a58eSblymnThe valid range for the timeout is from 1 to 255 tenths of a second. 296a3c6a58eSblymn.Pp 29723b2be97SblymnThe 29823b2be97Sblymn.Fn noraw 29923b2be97Sblymnfunction sets the input mode for the current terminal into Cooked mode, 30023b2be97Sblymnthat is input character translation and signal character processing is 30123b2be97Sblymnperformed. 30223b2be97SblymnThe 30323b2be97Sblymn.Fn raw 30423b2be97Sblymnfunction puts the terminal into Raw mode, no input character 30523b2be97Sblymntranslation is done nor is signal character processing. 30623b2be97Sblymn.Pp 30723b2be97SblymnThe terminal 30823b2be97Sblymntty flags can be saved by calling 30923b2be97Sblymn.Fn savetty 31023b2be97Sblymnand may be restored by calling 31123b2be97Sblymn.Fn resetty , 31223b2be97Sblymnthe use of these functions is discouraged as they may cause the 31323b2be97Sblymnterminal to be put into a state that is incompatiable with curses 31423b2be97Sblymnoperation. 31523b2be97Sblymn.Sh RETURN VALUES 31623b2be97SblymnFunctions returning pointers will return 31723b2be97Sblymn.Dv NULL 31823b2be97Sblymnif an error is detected. 31923b2be97SblymnThe functions that return an int will return one of the following 32023b2be97Sblymnvalues: 32123b2be97Sblymn.Pp 32223b2be97Sblymn.Bl -tag -width ERR -compact 32323b2be97Sblymn.It Er OK 32423b2be97SblymnThe function completed successfully. 32523b2be97Sblymn.It Er ERR 32623b2be97SblymnAn error occurred in the function. 32723b2be97Sblymn.El 32823b2be97Sblymn.Sh SEE ALSO 32923b2be97Sblymn.Xr getch 3 , 33023b2be97Sblymn.Xr termios 4 33123b2be97Sblymn.Sh NOTES 33223b2be97SblymnThe 33323b2be97Sblymn.Fn idcok 33423b2be97Sblymnand 33523b2be97Sblymn.Fn idlok 33623b2be97Sblymncurrently have no effect on the curses code at all, currently curses 33723b2be97Sblymnwill always use the terminal insert character and insert line 33823b2be97Sblymncapabilities if available. 33923b2be97Sblymn.Sh STANDARDS 34023b2be97SblymnThe 34123b2be97Sblymn.Nx 34223b2be97SblymnCurses library complies with the X/Open Curses specification, part of the 34323b2be97SblymnSingle Unix Specification. 34423b2be97Sblymn.Sh HISTORY 34523b2be97SblymnThe Curses package appeared in 34623b2be97Sblymn.Bx 4.0 . 347