diff options
Diffstat (limited to 'lib/libterm/termcap.3')
-rw-r--r-- | lib/libterm/termcap.3 | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/lib/libterm/termcap.3 b/lib/libterm/termcap.3 new file mode 100644 index 0000000..08173cd --- /dev/null +++ b/lib/libterm/termcap.3 @@ -0,0 +1,254 @@ +.\" 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; +.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 +.Xr curses 3 +for a higher level package. +.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 . +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/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 . |