386BSD 0.1 development

[unix-history] / usr / src / lib / libterm / termcap.3

diff --git a/usr/src/lib/libterm/termcap.3 b/usr/src/lib/libterm/termcap.3
index e51daac..e708fce 100644 (file)
--- a/usr/src/lib/libterm/termcap.3
+++ b/usr/src/lib/libterm/termcap.3
@@ -1,151 +1,254 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)termcap.3   5.1 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.TH TERMCAP 3X "9 February 1983"
-.UC 4
-.SH NAME
-tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs \- terminal independent operation routines
-.SH SYNOPSIS
-.nf
-.B char PC;
-.B char *BC;
-.B char *UP;
-.B short ospeed;
-.PP
-.B tgetent(bp, name)
-.B char *bp, *name;
-.PP
-.B tgetnum(id)
-.B char *id;
-.PP
-.B tgetflag(id)
-.B char *id;
-.PP
-.B char *
-.B tgetstr(id, area)
-.B char *id, **area;
-.PP
-.B char *
-.B tgoto(cm, destcol, destline)
-.B char *cm;
-.PP
-.B tputs(cp, affcnt, outc)
-.B register char *cp;
-.B int affcnt;
-.B int (*outc)();
-.fi
-.SH DESCRIPTION
-These functions extract and use capabilities from the terminal capability data
-base
-.IR termcap (5).
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)termcap.3  6.6 (Berkeley) 4/19/91
+.\"
+.Dd April 19, 1991
+.Dt TERMCAP 3
+.Os BSD 4
+.Sh NAME
+.Nm tgetent ,
+.Nm tgetnum ,
+.Nm tgetflag ,
+.Nm tgetstr ,
+.Nm tgoto ,
+.Nm tputs
+.Nd terminal independent operation routines
+.Sh SYNOPSIS
+.Vt char PC;
+.Vt char *BC;
+.Vt char *UP;
+.Vt short ospeed;
+.Fn tgetent "char *bp" "char *name"
+.Fn tgetnum "char *id"
+.Fn tgetflag "char *id"
+.Ft char *
+.Fn tgetstr "char *id" "char *area"
+.Ft char *
+.Fn tgoto "char *cm" destcol destline
+.Fn tputs "register char *cp" "int affcnt" "int (*outc)()"
+.Sh DESCRIPTION
+These functions extract and use capabilities from a terminal capability data
+base, usually
+.Pa /usr/share/misc/termcap ,
+the format of which is described in
+.Xr termcap 5 .

 These are low level routines;
 see
 These are low level routines;
 see

-.IR curses (3X)
+.Xr curses 3

 for a higher level package.
 for a higher level package.

-.PP
-.I Tgetent
+.Pp
+The
+.Fn tgetent
+function

 extracts the entry for terminal
 extracts the entry for terminal

-.I name
+.Fa name

 into the buffer at
 into the buffer at

-.I bp.
-.I Bp
+.Fa bp .
+The
+.Fa bp
+argument

 should be a character buffer of size
 should be a character buffer of size

-1024 and must be retained through all subsequent calls
-to
-.I tgetnum,
-.I tgetflag,
+1024 and must be retained through all subsequent calls to
+.Fn tgetnum ,
+.Fn tgetflag ,

 and
 and

-.I tgetstr.
-.I Tgetent
-returns \-1 if it cannot open the
-.I termcap
-file, 0 if the terminal name given does not have an entry,
+.Fn tgetstr .
+The
+.Fn tgetent
+function
+returns \-1 if none of the
+.Nm termcap
+data base files could be opened,
+0 if the terminal name given does not have an entry,

 and 1 if all goes well.
 and 1 if all goes well.

-It will look in the environment for a TERMCAP variable.
+It will look in the environment for a
+.Ev TERMCAP
+variable.

 If found, and the value does not begin with a slash,
 and the terminal type
 If found, and the value does not begin with a slash,
 and the terminal type

-.B name
-is the same as the environment string TERM,
-the TERMCAP string is used instead of reading the termcap file.
-If it does begin with a slash, the string is used as a path name rather than
-.I /etc/termcap.
+.Fa name
+is the same as the environment string
+.Ev TERM ,
+the
+.Ev TERMCAP
+string is used instead of reading a
+.Nm termcap
+file.
+If it does begin with a slash, the string is used as a path name
+of the
+.Nm termcap
+file to search.
+If
+.Ev TERMCAP
+does not begin with a slash and
+.Fa name
+is different from
+.Ev TERM ,
+.Fn tgetent
+searches the files
+.Pa $HOME/.termcap
+and
+.Pa /usr/share/misc/termcap ,
+in that order, unless the environment variable
+.Ev TERMPATH
+exists,
+in which case it specifies a list of file pathnames
+(separated by spaces or colons) to be searched instead.
+Whenever multiple files are searched and a
+.Sy tc
+field occurs in the requested entry, the entry it names must be found
+in the same file or one of the succeeding files.

 This can speed up entry into programs that call
 This can speed up entry into programs that call

-.IR tgetent ,
-as well as to help debug new terminal descriptions
-or to make one for your terminal if you can't write the file
-.I /etc/termcap.
-.PP
-.I Tgetnum
+.Fn tgetent ,
+as well as help debug new terminal descriptions
+or make one for your terminal if you can't write the file
+.Pa /usr/share/misc/termcap .
+.Pp
+The
+.Fn tgetnum
+function

 gets the numeric value of capability
 gets the numeric value of capability

-.I id,
+.Fa id ,

 returning \-1 if is not given for the terminal.
 returning \-1 if is not given for the terminal.

-.I Tgetflag
+The
+.Fn tgetflag
+function

 returns 1 if the specified capability is present in
 the terminal's entry, 0 if it is not.
 returns 1 if the specified capability is present in
 the terminal's entry, 0 if it is not.

-.I Tgetstr
-gets the string value of capability
-.I id,
-placing it in the buffer at
-.I area,
-advancing the
-.I area
+The
+.Fn tgetstr
+function
+returns the string value of the capability
+.Fa id ,
+places it in the buffer at
+.Fa area ,
+and advances the
+.Fa area

 pointer.
 It decodes the abbreviations for this field described in
 pointer.
 It decodes the abbreviations for this field described in

-.IR termcap (5),
+.Xr termcap 5 ,

 except for cursor addressing and padding information.
 except for cursor addressing and padding information.

-.PP
-.I Tgoto
+The
+.Fn tgetstr
+function
+returns
+.Dv NULL
+if the capability was not found.
+.Pp
+The
+.Fn tgoto
+function

 returns a cursor addressing string decoded from
 returns a cursor addressing string decoded from

-.I cm
+.Fa cm

 to go to column
 to go to column

-.I destcol
+.Fa destcol

 in line
 in line

-.I destline.
+.Fa destline .

 It uses the external variables
 It uses the external variables

-.B UP
-(from the \fBup\fR capability)
+.Va UP
+(from the
+.Sy up
+capability)

 and
 and

-.B BC
-(if \fBbc\fR is given rather than \fBbs\fR)
-if necessary to avoid placing \fB\en\fR, \fB^D\fR or \fB^@\fR in
+.Va BC
+(if
+.Sy bc
+is given rather than
+.Sy bs )
+if necessary to avoid placing
+.Sy \en ,
+.Sy ^D
+or
+.Sy ^@
+in

 the returned string.
 the returned string.

-(Programs which call tgoto should be sure to turn off the XTABS bit(s),
+(Programs which call
+.Fn tgoto
+should be sure to turn off the
+.Dv XTABS
+bit(s),

 since
 since

-.I tgoto
+.Fn tgoto

 may now output a tab.
 may now output a tab.

-Note that programs using termcap should in general turn off XTABS
-anyway since some terminals use control I for other functions,
+Note that programs using termcap should in general turn off
+.Dv XTABS
+anyway since some terminals use control-I for other functions,

 such as nondestructive space.)
 such as nondestructive space.)

-If a \fB%\fR sequence is given which is not understood, then
-.I tgoto
-returns \*(lqOOPS\*(rq.
-.PP
-.I Tputs
+If a
+.Sy %
+sequence is given which is not understood, then
+.Fn tgoto
+returns
+.Pq Dv OOPS .
+.Pp
+The
+.Fn tputs
+function

 decodes the leading padding information of the string
 decodes the leading padding information of the string

-.IR cp ;
-.I affcnt
+.Fa cp ;
+.Fa affcnt

 gives the number of lines affected by the operation, or 1 if this is
 not applicable,
 gives the number of lines affected by the operation, or 1 if this is
 not applicable,

-.I outc
+.Fa outc

 is a routine which is called with each character in turn.
 The external variable
 is a routine which is called with each character in turn.
 The external variable

-.I ospeed
+.Va ospeed

 should contain the output speed of the terminal as encoded by
 should contain the output speed of the terminal as encoded by

-.IR stty (3).
+.Xr stty 3 .

 The external variable
 The external variable

-.B PC
-should contain a pad character to be used (from the \fBpc\fR capability)
-if a null (\fB^@\fR) is inappropriate.
-.SH FILES
-.ta \w'/usr/lib/libtermcap.a  'u
-/usr/lib/libtermcap.a  \-ltermcap library
-.br
-/etc/termcap   data base
-.DT
-.SH SEE ALSO
-ex(1), curses(3X), termcap(5)
-.SH AUTHOR
-William Joy
+.Va PC
+should contain a pad character to be used (from the
+.SY pc
+capability)
+if a null
+.Pq Sy ^@
+is inappropriate.
+.Sh FILES
+.Bl -tag -width /usr/share/misc/termcap -compact
+.It Pa /usr/lib/libtermcap.a
+.Fl l Ar ltermcap
+library (also known as
+.Fl l Ar ltermlib )
+.It Pa /usr/share/misc/termcap
+standard terminal capability data base
+.It Pa $HOME/.termcap
+user's terminal capability data base
+.El
+.Sh SEE ALSO
+.Xr ex 1 ,
+.Xr curses 3 ,
+.Xr termcap 5
+.Sh HISTORY
+The
+.Nm
+functions appeared in 
+.Bx 4.0 .