[unix-history] / usr / man / man3 / termlib.3

.TH TERMLIB 3 10/22/79 3
.UC
.SH NAME
tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs \- terminal independent operation routines
.SH SYNOPSIS
.nf
.DT
\fBchar PC;
char *BC;
char *UP;
short ospeed;

tgetent(bp, name)
char *bp, *name;

tgetnum(id)
char *id;

tgetflag(id)
char *id;

char *
tgetstr(id, area)
char *id, **area;

char *
tgoto(cm, destcol, destline)
char *cm;

tputs(cp, affcnt, outc)
register char *cp;
int affcnt;
int (*outc)();\fP
.fi
.SH DESCRIPTION
These functions extract and use capabilities from the terminal capability data
base
.IR termcap (5).
.PP
.I Tgetent
extracts the entry for terminal
.I name
into the buffer at
.I bp.
.I Bp
should be a character buffer of size
1024 and must be retained through all subsequent calls
to
.I tgetnum,
.I tgetflag,
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,
and 1 if all goes well.
It will look in the environment for a TERMCAP variable.
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.
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
gets the numeric value of capability
.I id,
returning \-1 if is not given for the terminal.
.I Tgetflag
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
pointer.
It decodes the abbreviations for this field described in
.IR termcap (5),
except for cursor addressing and padding information.
.PP
.I Tgoto
returns a cursor addressing string decoded from
.I cm
to go to column
.I destcol
in line
.I destline.
It uses the external variables
.B UP
(from the \fBup\fR capability)
and
.B BC
(if \fBbc\fR is given rather than \fBbs\fR)
if necessary to avoid placing \fB\et\fR, \fB\en\fR, \fB^D\fR or \fB^@\fR in
the returned string.
If a \fB%\fR sequence is given which is not understood, then
.I tgoto
returns ``OOPS''.
.PP
.I Tputs
decodes the leading padding information of the string
.I cp;
.I affcnt
gives the number of lines affected by the operation, or 1 if this is
not applicable,
.I outc
is a routine which is called with each character in turn.
The external variable
.I ospeed
should contain the output speed of the terminal as encoded by
.I stty (2).
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
.DT
/usr/lib/libtermlib.a	\-ltermlib library
.br
/etc/termcap	data base
.SH SEE ALSO
ex (1), termcap (5)
.SH AUTHOR
William Joy
.br
Mark Horton
.SH BUGS
The terminal independent cursor motion optimization routines of
.I ex
should be placed in the library also,
as well as a more straightforward user interface.
Commit	Line	Data
053b7e7b BJ	1	.TH TERMLIB 3 10/22/79 3
	2	.UC
	3	.SH NAME
	4	tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs \- terminal independent operation routines
	5	.SH SYNOPSIS
	6	.nf
	7	.DT
	8	\fBchar PC;
	9	char *BC;
	10	char *UP;
	11	short ospeed;
	12
	13	tgetent(bp, name)
	14	char bp, name;
	15
	16	tgetnum(id)
	17	char *id;
	18
	19	tgetflag(id)
	20	char *id;
	21
	22	char *
	23	tgetstr(id, area)
	24	char id, *area;
	25
	26	char *
	27	tgoto(cm, destcol, destline)
	28	char *cm;
	29
	30	tputs(cp, affcnt, outc)
	31	register char *cp;
	32	int affcnt;
	33	int (*outc)();\fP
	34	.fi
	35	.SH DESCRIPTION
	36	These functions extract and use capabilities from the terminal capability data
	37	base
	38	.IR termcap (5).
	39	.PP
	40	.I Tgetent
	41	extracts the entry for terminal
	42	.I name
	43	into the buffer at
	44	.I bp.
	45	.I Bp
	46	should be a character buffer of size
	47	1024 and must be retained through all subsequent calls
	48	to
	49	.I tgetnum,
	50	.I tgetflag,
	51	and
	52	.I tgetstr.
	53	.I Tgetent
	54	returns \-1 if it cannot open the
	55	.I termcap
	56	file, 0 if the terminal name given does not have an entry,
	57	and 1 if all goes well.
	58	It will look in the environment for a TERMCAP variable.
	59	If found, and the value does not begin with a slash,
	60	and the terminal type
	61	.B name
	62	is the same as the environment string TERM,
	63	the TERMCAP string is used instead of reading the termcap file.
	64	If it does begin with a slash, the string is used as a path name rather than
65	.I /etc/termcap.
66	This can speed up entry into programs that call
67	.IR tgetent ,
68	as well as to help debug new terminal descriptions
69	or to make one for your terminal if you can't write the file
70	.I /etc/termcap.
71	.PP
72	.I Tgetnum
73	gets the numeric value of capability
74	.I id,
75	returning \-1 if is not given for the terminal.
76	.I Tgetflag
77	returns 1 if the specified capability is present in
78	the terminal's entry, 0 if it is not.
79	.I Tgetstr
80	gets the string value of capability
81	.I id,
82	placing it in the buffer at
83	.I area,
84	advancing the
85	.I area
86	pointer.
87	It decodes the abbreviations for this field described in
88	.IR termcap (5),
89	except for cursor addressing and padding information.
90	.PP
91	.I Tgoto
92	returns a cursor addressing string decoded from
93	.I cm
94	to go to column
95	.I destcol
96	in line
97	.I destline.
98	It uses the external variables
99	.B UP
100	(from the \fBup\fR capability)
101	and
102	.B BC
103	(if \fBbc\fR is given rather than \fBbs\fR)
104	if necessary to avoid placing \fB\et\fR, \fB\en\fR, \fB^D\fR or \fB^@\fR in
105	the returned string.
106	If a \fB%\fR sequence is given which is not understood, then
107	.I tgoto
108	returns ``OOPS''.
109	.PP
110	.I Tputs
111	decodes the leading padding information of the string
112	.I cp;
113	.I affcnt
114	gives the number of lines affected by the operation, or 1 if this is
115	not applicable,
116	.I outc
117	is a routine which is called with each character in turn.
118	The external variable
119	.I ospeed
120	should contain the output speed of the terminal as encoded by
121	.I stty (2).
122	The external variable
123	.B PC
124	should contain a pad character to be used (from the \fBpc\fR capability)
125	if a null (\fB^@\fR) is inappropriate.
126	.SH FILES
127	.DT
128	/usr/lib/libtermlib.a \-ltermlib library
129	.br
130	/etc/termcap data base
131	.SH SEE ALSO
132	ex (1), termcap (5)
133	.SH AUTHOR
134	William Joy
135	.br
136	Mark Horton
137	.SH BUGS
138	The terminal independent cursor motion optimization routines of
139	.I ex
140	should be placed in the library also,
141	as well as a more straightforward user interface.