xref: /netbsd/lib/libcurses/curses_tty.3 (revision 104b35fe)
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