document libotermcap and say why it is deprecated

1 files changed, 274 insertions, 0 deletions

diff --git a/lib/libocurses/otermcap.3 b/lib/libocurses/otermcap.3
new file mode 100644
index 00000000000..7d5d066b21c
--- /dev/null
+++ b/lib/libocurses/otermcap.3
@@ -0,0 +1,274 @@
+.\"	$OpenBSD: otermcap.3,v 1.1 1998/11/30 16:12:24 millert Exp $
+.\"	$NetBSD: termcap.3,v 1.5 1995/06/05 19:45:48 pk Exp $
+.\"
+.\" Copyright (c) 1980, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" 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	8.2 (Berkeley) 12/11/93
+.\"
+.Dd December 11, 1993
+.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;
+.Ft int
+.Fn tgetent "char *bp" "char *name"
+.Ft int
+.Fn tgetnum "char *id"
+.Ft int
+.Fn tgetflag "char *id"
+.Ft char *
+.Fn tgetstr "char *id" "char **area"
+.Ft char *
+.Fn tgoto "char *cm" destcol destline
+.Ft void
+.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 .
+This version of these routines has been deprecated in favor of
+the emulation provided by
+.Xr termcap 3 .
+This library is provided solely for old applications that
+require behavior that is not emulated.
+.Pp
+The
+.Fn tgetent
+function
+extracts the entry for terminal
+.Fa name
+into the buffer at
+.Fa bp .
+The
+.Fa bp
+argument
+should be a character buffer of size
+1024 and must be retained through all subsequent calls to
+.Fn tgetnum ,
+.Fn tgetflag ,
+and
+.Fn tgetstr .
+As an extension
+.Fn tgetent
+can be passed NULL
+for the
+.Fa bp
+argument, in which case an internal buffer will be used.
+If repeated calls to
+.Fn tgetent
+is made with a NULL
+.Fa bp
+argument, some memory will be leaked on each call subsequent
+to the first.
+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.
+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
+.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
+.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
+.Fa id ,
+returning \-1 if it is not given for the terminal.
+The
+.Fn tgetflag
+function
+returns 1 if the specified capability is present in
+the terminal's entry, 0 if it is not.
+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
+.Xr termcap 5 ,
+except for cursor addressing and padding information.
+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
+.Fa cm
+to go to column
+.Fa destcol
+in line
+.Fa destline .
+It uses the external variables
+.Va UP
+(from the
+.Sy up
+capability)
+and
+.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.
+(Programs which call
+.Fn tgoto
+should be sure to turn off the
+.Dv XTABS
+bit(s),
+since
+.Fn tgoto
+may now output a tab.
+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.)
+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
+.Fa cp ;
+.Fa affcnt
+gives the number of lines affected by the operation, or 1 if this is
+not applicable,
+.Fa outc
+is a routine which is called with each character in turn.
+The external variable
+.Va ospeed
+should contain the output speed of the terminal as encoded by
+.Xr stty 3 .
+The external variable
+.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/libotermcap.a
+.Fl l Ar lotermcap
+library
+.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 3 ,
+.Xr termcap 5
+.Sh HISTORY
+The
+.Nm
+functions appeared in 
+.Bx 4.0 .