setupterm(3xcurses)

1del_curterm(3XCURSES)   X/Open Curses Library Functions  del_curterm(3XCURSES)
2
3
4

NAME

6       del_curterm,  restartterm,  set_curterm,  setupterm - interfaces to the
7       terminfo database
8

SYNOPSIS

10       cc [ flag... ] file... -I /usr/xpg4/include  -L  /usr/xpg4/lib \
11        -R  /usr/xpg4/lib  -lcurses  [ library... ]
12
13       c89 [ flag... ] file... -lcurses [ library... ]
14
15       #include <term.h>
16
17       int del_curterm(TERMINAL *oterm);
18
19
20       int restartterm(char *term, int fildes, int *errret);
21
22
23       TERMINAL *set_curterm(TERMINAL *nterm);
24
25
26       int setupterm(char *term, int fildes, int *errret);
27
28

DESCRIPTION

30       Within X/Open Curses, the setupterm() function is automatically  called
31       by the  initscr (3XC) and newterm (3XC) functions. This function can be
32       also be used outside of X/Open Curses  when  a  program  has  to   deal
33       directly  with  the terminfo database to handle certain terminal  capa‐
34       bilities.  The use of appropriate X/Open  Curses  functions  is  recom‐
35       mended in all other  situations.
36
37
38       The  setupterm()  function  loads  terminal-dependent variables for the
39       terminfo layer of X/Open Curses. The setupterm()  function  initializes
40       the  terminfo  variables  lines and columns such that if use_env(FALSE)
41       has been called, the terminfo values assigned in the database are  used
42       regardless of the environmental variables LINES and COLUMNS or the pro‐
43       gram's window dimensions; when use_env(TRUE) has been called, which  is
44       the  default,  the environment variables LINES and COLUMNS are used, if
45       they exist.  If the environment variables do not exist and the  program
46       is running in a  window, the current window size is used.
47
48
49       The term parameter of setupterm() specifies the terminal; if null, ter‐
50       minal type is taken from the TERM environment variable. All  output  is
51       sent  to fildes which is initialized for output. If errret is not null,
52       OK or ERR is returned and a status  value  is  stored  in  the  integer
53       pointed to by errret.  The following status values may be returned:
54
55
56
57
58       ┌───────────────────────────────────────────────────────────────────┐
59       │Value                         Description                          │
60       │1                             Normal                               │
61       │0                             Terminal could not be found          │
62       │-1                            terminfo database could not be found │
63       └───────────────────────────────────────────────────────────────────┘
64
65
66       If  errret  is  null,  an error message is printed, and the setupterm()
67       function calls the exit() function with a non-zero parameter.
68
69
70       The set_curterm() function sets the cur_term variable  to   nterm.  The
71       values  from  nterm as well as other state information for the terminal
72       are  used  by  X/Open  Curses   functions   such   as   beep(3XCURSES),
73       flash(3XCURSES),     mvcur(3XCURSES),    tigetflag(3XCURSES),    tiget‐
74       str(3XCURSES), and tigetnum(3XCURSES).
75
76
77       The del_curterm() function frees the space pointed  to  by  oterm.   If
78       oterm  and the cur_term variable are the same, all Boolean, numeric, or
79       string terminfo variables will refer to invalid memory locations  until
80       you call setupterm() and specify a new terminal  type.
81
82
83       The  restartterm()  function  assumes  that  a  call to setupterm() has
84       already been made (probably from initscr() or newterm()). It allows you
85       to specify a new terminal type in term and updates the data returned by
86       baudrate(3XCURSES) based on fildes. Other information  created  by  the
87       initscr(), newterm(), and  setupterm() functions is preserved.
88

PARAMETERS

90       oterm     Is the terminal type for which to free space.
91
92
93       term      Is the terminal type for which variables are set.
94
95
96       fildes    Is a file descriptor initialized for output.
97
98
99       errret    Is  a  pointer  to  an  integer  in which the status value is
100                 stored.
101
102
103       nterm     Is the new terminal to become the current terminal.
104
105

RETURN VALUES

107       On success, the set_curterm() function returns the  previous  value  of
108       cur_term. Otherwise, it returns a null pointer.
109
110
111       On success, the other functions return OK. Otherwise, they return ERR.
112

ERRORS

114       None.
115

ATTRIBUTES

117       See attributes(5) for descriptions of the following attributes:
118
119
120
121
122       ┌─────────────────────────────┬─────────────────────────────┐
123       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
124       ├─────────────────────────────┼─────────────────────────────┤
125       │Interface Stability          │Standard                     │
126       ├─────────────────────────────┼─────────────────────────────┤
127       │MT-Level                     │Unsafe                       │
128       └─────────────────────────────┴─────────────────────────────┘
129