December 17, 2006 TERMCAP 3

### NAME

tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs - terminal independent operation routines

### LIBRARY

Termcap Access Library (libtermcap, -ltermcap)

### SYNOPSIS

```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`)

### DESCRIPTION

These functions extract and use capabilities from a terminal capability data base, usually ```/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.

### FILES

```/usr/lib/libtermcap.a`
  -l termcap library (also known as -l termlib)
```/usr/share/misc/termcap`
  standard terminal capability data base
```$HOME/.termcap`
  user's terminal capability data base

### SEE ALSO

ex(1), curses(3), termcap(5)

### HISTORY

The termcap t_*() functions appeared in NetBSD1.5. The rest of the termcap functions appeared in 4.0BSD.