del_curterm, restartterm, set_curterm, or setupterm Subroutine

Purpose

Interfaces to the terminfo database.

Library

Curses Library (libcurses.a)

Syntax

#include <term.h>

int del_curterm(TERMINAL *oterm); 

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

TERMINAL *set_curterm(TERMINAL *nterm);

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

Description

The del_curterm, restartterm, set_curterm, setupterm subroutines retrieve information from the terminfo database.

To gain access to the terminfo database, the setupterm subroutine must be called first. It is automatically called by the initscr and newterm subroutines. The setupterm subroutine initialises the other subroutines to use the terminfo record for a specified terminal (which depends on whether the use_env subroutine was called). It sets the dur_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, the "unknown" is used as the terminal type. The application must set the fildes parameter to a file descriptor, open for output, to the terminal device, before calling the setupterm subroutine. If the erret parameter is not null, the integer it points to is set to one of the following values to report the function outcome:

A simple call to the setupterm subroutine that uses all the defaults and sends the output to stdout is:

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

The set_curterm subroutine 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 subroutine 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 the setupterm subroutine is called again.

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

Parameters

Return Values

Upon successful completion, the set_curterm subroutine returns the previous value of cur_term. Otherwise, it returns a null pointer.

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

Examples

To free the space occupied by a TERMINAL structure called my_term, use:

For the restartterm subroutine:

To restart an aixterm after a previous memory save and exit on error with a message, enter:

restartterm("aixterm", 1, (int*)0);

For the set_curterm subroutine:

To set the cur_term variable to point to the my_term terminal, use:

For the setupterm subroutine:

To determine the current terminal's capabilities using $TERM as the terminal name, standard output as output, and returning no error codes, enter:

setupterm((char*) 0, 1, (int*) 0);

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The baudrate, longname, putc, termattrs, termnamed, tgetent, tigetflag, and use_env subroutines.

Curses Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

List of Curses Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Understanding Terminals with Curses in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.