int
tgetent(
char *bp
, const char *name
)
int
tgetnum(
const char *id
)
int
tgetflag(
const char *id
)
char
*
tgetstr(
const char *id
, char **area
)
char
*
tgoto(
const char *cm
, int destcol
, int destline
)
void
tputs(
const char *cp
, int affcnt
, int (*outc)(int)
)
int
t_getent(
struct tinfo **info
, const char *name
)
int
t_getnum(
struct tinfo *info
, const char *id
)
int
t_getflag(
struct tinfo *info
, const char *id
)
char
*
t_getstr(
struct tinfo *info
, const char *id
, char **area
, size_t *limit
)
char
*
t_agetstr(
struct tinfo *info
, const char *id
)
int
t_getterm(
struct tinfo *info
, char **area
, size_t *limit
)
int
t_goto(
struct tinfo *info
, const char *id
, int destcol
, int destline
, char *buffer
, size_t limit
)
int
t_puts(
struct tinfo *info
, const char *cp
, int affcnt
void (*outc)(char, void *), void *args
)
void
t_freent(
struct tinfo *info
)
int
t_setinfo(
struct tinfo **info
, const char *entry
)
int
t_putws(
struct tinfo *info
, const wchar_t *cp
, int affcnt
void (*outc)(wchar_t, void *), void *args
)
/usr/share/misc/termcap
,
the format of which is described in
termcap(5).
These are low level routines;
see
curses(3)
for a higher level package.
The
tgetent()
function
extracts the entry for terminal
name
into the buffer at
bp
.
The
bp
argument
should be a character buffer of size
1024 and must be retained through all subsequent calls to
tgetnum(),
tgetflag(
),
and
tgetstr(
).
The
tgetent(
)
function
returns -1 if none of the
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
TERMCAP
variable.
If found, and the value does not begin with a slash, the value does
not contain the ZZ capability (see
NOTES
for a description of this capability),
and the terminal type
name
is the same as the environment string
TERM
,
the
TERMCAP
string is used instead of reading a
termcap
file.
If the value does contain the ZZ capability then the
TERM
environment string is used to read
termcap,
if the read fails for any reason the value of
TERMCAP
will be used despite it containing ZZ.
If
TERMCAP
does begin with a slash, the string is used as a path name
of the
termcap
file to search.
If
TERMCAP
does not begin with a slash and
name
is different from
TERM
,
tgetent()
searches the files
$HOME/.termcap
and
/usr/share/misc/termcap
,
in that order, unless the environment variable
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
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
tgetent(),
as well as help debug new terminal descriptions
or make one for your terminal if you can't write the file
/usr/share/misc/termcap
.
The
tgetnum()
function
gets the numeric value of capability
id
,
returning -1 if it is not given for the terminal.
The
tgetflag()
function
returns 1 if the specified capability is present in
the terminal's entry, 0 if it is not.
The
tgetstr(
)
function
returns the string value of the capability
id
;
if
area
does not point to
NULL
and does not point to a pointer to
NULL
,
it copies the string value into the buffer pointed to by
*area
,
and advances the
*area
pointer past the copy of the string.
It decodes the abbreviations for this field described in
termcap(5),
except for cursor addressing and padding information.
The
tgetstr()
function
returns
NULL
if the capability was not found.
The
tgoto()
function
returns a cursor addressing string decoded from
cm
to go to column
destcol
in line
destline
.
It uses the external variables
UP
(from the
up
capability)
and
BC
(if
bc
is given rather than
bs)
if necessary to avoid placing
\n,
^D
or
^@
in
the returned string.
(Programs which call
tgoto()
should be sure to turn off the
XTABS
bit(s),
since
tgoto()
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,
such as nondestructive space.)
If a
%
sequence is given which is not understood, then
tgoto()
returns
(
OOPS
).
The
tputs()
function
decodes the leading padding information of the string
cp
;
affcnt
gives the number of lines affected by the operation, or 1 if this is
not applicable,
outc
is a routine which is called with each character in turn.
The external variable
ospeed
should contain the output speed of the terminal as encoded by
stty(3).
The external variable
PC
should contain a pad character to be used (from the
pc
capability)
if a null
(^@)
is inappropriate.
The
t_getent()
function operates in a similar manner to the
tgetent(
)
function excepting that the
info
argument is a pointer to a pointer of the opaque type
tinfo.
If the call to
t_getent()
succeeds then the argument
info
will be updated with the address of an object that contains the termcap
entry.
This pointer can then be passed to calls of
t_getnum(),
t_getflag(
)
and
t_getstr(
).
When the information pointed to by
info
is no longer required any storage associated with the object can be
released by calling
t_freent().
The functions
t_getnum()
and
t_getflag(
)
operate in the same manner as
tgetnum(
)
and
tgetflag(
)
with the exception that the pointer to the termcap object is passed along
with the id of the capability required.
The function
t_getstr()
performs the same function as
tgetstr(
)
but has a
limit
parameter that gives the number of characters that can be inserted in to
the array pointed to by
area
.
The
limit
argument is updated by the
t_getstr()
call to give the number of characters that remain available in
area
.
If the t_getstr call fails then
NULL
will be returned and errno set to indicate the failure,
ENOENT
indicates there was no termcap entry for the given
id
,
E2BIG
indicates the retrieved entry would have overflowed
area
.
If t_getstr is called with
area
being
NULL
then the size required to hold the capability string will be returned in
limit
so the caller can allocate enough storage to hold the capability.
The function
t_agetstr()
performs the same function as
t_getstr(
)
except it handles memory allocation automatically.
The memory that
t_agetstr(
)
allocates will be freed when
t_freent(
)
is called.
The function
t_getterm()
returns a copy of the termcap name string of the termcap entry
associated with
info
in the buffer pointed to by
area
.
t_getterm()
returns 0 on success and -1 on error.
On error errno will be set to
EINVAL
if the termcap entry in
info
is malformed or
E2BIG
if the size of the name exceeds the size specified by
limit
.
If
area
is
NULL
then the size required to hold the terminal name will be returned in
limit
allowing sufficient storage to be allocated.
If
limit
is
NULL
then no bounds checking will be performed.
The
t_goto()
function is the same as the
tgoto(
)
function excepting that the capabilities for
up
and
bc
are extracted from the
info
object and that the string formed by
t_goto()
is placed in the
buffer
argument, the number of characters allowed to be placed in
buffer
is controlled by
limit
.
If the expansion performed by
t_goto()
would exceed the space in
buffer
then
t_goto()
will return -1 and set errno to
E2BIG
.
The function
t_puts()
is similar to the
tputs(
)
function excepting that
info
holds a pointer to the termcap object that was returned by a previous
t_getent()
call, this object will be used to retrieve the
pc
attribute for the terminal.
The function
t_putws(
)
is similar to
t_puts(
)
but it operates on a string of wide characters.
The
outc
function is a pointer to a function that will be called by
t_puts()
to output each character in the
cp
string.
The
outc
function will be called with two parameters.
The first is the character
to be printed and the second is an optional argument that was passed to
t_puts()
in the
args
argument.
The interpretation of the contents of
args
is dependent solely on the implementation of
outc
.
The
t_setinfo()
function allows the termcap entry contained in the
entry
string to be inserted into the
info
structure.
Memory sufficient to hold the contents of
entry
is automatically allocated.
This allows the programmer to provide a fail over terminal capability
string if fetching the termcap entry from the termcap database fails.
The format of the string
entry
is assumed to be a valid termcap entry.
NOTE: For termcap entries that are larger than 1023 bytes a special
capability of
ZZ
is added to the end of the termcap entry retrieved.
The number that follows this entry is the address of the buffer allocated
to hold the full termcap entry.
The caller may retrieve the pointer to the extended buffer by performing a
tgetstr()
to retrieve the
ZZ
capability, the string is the output of a
printf()
%p and may be converted back to a pointer using
sscanf(
)
or similar.
The ZZ capability is only necessary if the caller wishes to
directly manipulate the termcap entry, all the termcap function calls
automatically use the extended buffer to retrieve terminal capabilities.
/usr/lib/libtermcap.a
/usr/share/misc/termcap
$HOME/.termcap