del_curterm(3curses)

del_curterm -- interfaces to the terminfo database

Synopsis

cc [options] file -lcurses

#include <term.h>

int del_curterm(TERMINAL *oterm);

int restartterm(char *term, int fildes, int *errret);

TERMINAL *set_curterm(TERMINAL *nterm);

int setupterm(char *term, int fildes, int *errret);

Description

These functions retrieve information from the terminfo database.

To gain access to the terminfo database, setupterm(3curses) must be called first. It is automatically called by initscr(3curses) and newterm(3curses). The setupterm(3curses) function initialises the other functions to use the terminfo record for a specified terminal (which depends on whether use_env(3curses) was called). It sets the cur_term external variable to a TERMINAL structure that contains the record from the terminfo database for the specified terminal.

The terminal type is the character string term; if term is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then "unknown" is used as the terminal type. The application must set fildes to a file descriptor, open for output, to the terminal device, before calling setupterm(3curses). If errret is not null, the integer it points to is set to one of the following values to report the function outcome:

-1: The terminfo database was not found (function fails).
0: The entry for the terminal was not found in terminfo (function fails).
1: Success.

If setupterm(3curses) detects an error and errret is a null pointer, setupterm(3curses) writes a diagnostic message and exits.

A simple call to setupterm(3curses) that uses all the defaults and sends the output to stdout is:

   setupterm((char *)0, fileno(stdout), (int *)0);

The set_curterm(3curses) function sets the variable cur_term to nterm, and makes all of the terminfo boolean, numeric, and string variables use the values from nterm.

The del_curterm(3curses) function frees the space pointed to by oterm and makes it available for further use. If oterm is the same as cur_term, references to any of the terminfo boolean, numeric, and string variables thereafter may refer to invalid memory locations until setupterm(3curses) is called again.

The restartterm(3curses) function assumes a previous call to setupterm(3curses) (perhaps from initscr(3curses) or newterm(3curses)). It lets the application specify a different terminal type in term and updates the information returned by baudrate(3curses) based on fildes, but does not destroy other information created by initscr(3curses), newterm(3curses) or setupterm(3curses).

Return value

Upon successful completion, set_curterm(3curses) returns the previous value of cur_term. Otherwise, it returns a null pointer.

Upon successful completion, the other functions return OK. Otherwise, they return ERR.

Errors

No errors are defined.

Usage

An application would call setupterm(3curses) if it required access to the terminfo database but did not otherwise need to use Curses.

Standards Conformance

The Single UNIX Specification, Version 2; The Open Group.

References

baudrate(3curses), erasechar(3curses), has_ic(3curses), longname(3curses), putc(3S), termattrs(3curses), termname(3curses), tgetent(3curses), tigetflag(3curses), use_env(3curses), term(4)