setupterm Subroutine

Purpose

Initializes the terminal structure with the values in the terminfo database.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>
#include <term.h>

setupterm( Term,  FileNumber,  ErrorCode)
char *Term;
int FileNumber;
int *ErrorCode;

Description

The setupterm subroutine determines the number of lines and columns available on the output terminal. The setupterm subroutine calls the termdef subroutine to define the number of lines and columns on the display. If the termdef subroutine cannot supply this information, the setupterm subroutine uses the values in the terminfo database.

The setupterm subroutine initializes the terminal structure with the terminal-dependent capabilities from terminfo. This routine is automatically called by the initscr and newterm subroutines. The setupterm subroutine deals directly with the terminfo database.

Two of the terminal-dependent capabilities are the lines and columns. The setupterm subroutine populates the lines and column fields in the terminal structure in the following manner:

  1. If the environment variables LINES and COLUMNS are set, the setupterm subroutine uses these values.
  2. If the environment variables are not set, the setupterm subroutine obtains the lines and columns information from the tty subsystem.
  3. As a last resort, the setupterm subroutine uses the values defined in the terminfo database.
    Note: These may or may not be the same as the values in the terminfo database.

The simplest call is setupterm((char*) 0, 1, (int*) 0), which uses all defaults.

After the call to the setupterm subroutine, the cur_term global variable is set to point to the current structure of terminal capabilities. A program can use more than one terminal at a time by calling the setupterm subroutine for each terminal and then saving and restoring the cur_term variable.

Parameters

Item Description
ErrorCode Specifies a pointer to an integer to return the error code to. If a null pointer (0) is passed for this parameter, no status is returned. An error causes the setupterm subroutine to print an error message and exit instead of returning.
FileNumber Specifies the output files file descriptor (1 equals standard output).
Term Specifies the terminal name. If 0 is passed for this parameter, the value of the $TERM environment variable is used.

Return Values

One of the following status values is stored into the integer pointed to by the ErrorCode parameter:

Item Description
1 Successful completion.
0 No such terminal.
-1  An error occurred while locating the terminfo database.

Example

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