Annotation of src/lib/libterminfo/termcap.3, Revision 1.5
1.5 ! christos 1: .\" $NetBSD: termcap.3,v 1.4 2010/02/04 09:12:55 wiz Exp $
1.1 roy 2: .\"
3: .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Roy Marples.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
1.5 ! christos 30: .Dd March 6, 2011
1.1 roy 31: .Dt TERMCAP 3
32: .Os
33: .Sh NAME
34: .Nm tgetent ,
35: .Nm tgetnum ,
36: .Nm tgetflag ,
37: .Nm tgetstr ,
38: .Nm tgoto ,
39: .Nm tputs
40: .Nd terminal independent operation routines
41: .Sh LIBRARY
42: .Lb libtermcap
43: .Sh SYNOPSIS
44: .In termcap.h
1.3 snj 45: .Vt char PC ;
46: .Vt char *BC ;
47: .Vt char *UP ;
1.1 roy 48: .Ft int
49: .Fn tgetent "char *bp" "const char *name"
50: .Ft int
51: .Fn tgetnum "const char *id"
52: .Ft int
53: .Fn tgetflag "const char *id"
54: .Ft char *
55: .Fn tgetstr "const char *id" "char **area"
56: .Ft char *
57: .Fn tgoto "const char *cm" "int destcol" "int destline"
58: .Sh DESCRIPTION
1.3 snj 59: These functions extract and use capabilities from a terminal capability
60: database.
1.1 roy 61: They exist as wrappers around equivalent
62: .Xr terminfo 3
63: functions, which new code should use.
64: These are low level routines; see
65: .Xr curses 3
66: for a higher level package.
67: .Pp
68: The
69: .Fn tgetent
70: function calls
71: .Fn setupterm
72: and configures
73: .Va PC ,
74: .Va UP
75: and
76: .Va BC .
77: Only
78: .Va PC
79: is actually used internally.
80: The
81: .Fn tgetent
1.4 wiz 82: function returns \-1 if none of the
1.1 roy 83: .Nm terminfo
84: data base files could be opened,
1.3 snj 85: 0 if the terminal name given does not match an entry,
1.1 roy 86: and 1 if all goes well.
87: The
88: .Fa bp
89: argument is not used.
90: .Pp
91: The
92: .Fn tgetnum
93: function gets the numeric value of the capability
94: .Fa id ,
1.4 wiz 95: returning \-1 if it is not given for the terminal.
1.1 roy 96: The
97: .Fn tgetflag
98: function returns 1 if the specified capability is present in the terminal's
99: entry, 0 if it is not.
100: The
101: .Fn tgetstr
102: function returns the string value of the capability
103: .Fa id .
104: This is a
105: .Xr terminfo 5
106: string and not a
107: .Nm termcap
108: string;
109: as such it should only be processed by
110: .Fn tgoto .
111: The
112: .Fn tgetstr
1.4 wiz 113: function returns
114: .Dv NULL
115: if the capability was not found.
1.1 roy 116: The
117: .Fa area
118: argument is unused.
119: .Pp
120: The
121: .Fn tgoto
1.3 snj 122: function returns a cursor addressing string decoded from
1.1 roy 123: .Fa cm
124: to go to column
125: .Fa destcol
126: in line
1.5 ! christos 127: .Fa destline ,
! 128: or
! 129: .Dq OOPS
! 130: if it could not decode
! 131: a
! 132: .Dv %
! 133: sequence.
1.1 roy 134: .Sh SEE ALSO
135: .Xr terminfo 3 ,
136: .Xr terminfo 5
137: .Sh HISTORY
138: .Nm termcap
139: first appeared in 4.0BSD.
1.2 wiz 140: .Nx 1.5
141: introduced some
1.1 roy 142: .Nm termcap
143: .Fn t_*
1.2 wiz 144: extensions which were removed in
145: .Nx 6.0
146: when
1.1 roy 147: .Xr terminfo 3
148: was introduced.
149: .Sh AUTHORS
150: .An Roy Marples Aq roy@NetBSD.org
CVSweb <webmaster@jp.NetBSD.org>