1curs_terminfo(3CURSES)     Curses Library Functions     curs_terminfo(3CURSES)
2
3
4

NAME

6       curs_terminfo,  setupterm,  setterm, set_curterm, del_curterm, restart‐
7       term, tparm, tputs, putp, vidputs, vidattr, mvcur, tigetflag, tigetnum,
8       tigetstr - curses interfaces to terminfo database
9

SYNOPSIS

11       cc [ flag ... ] file ... -lcurses [ library ... ]
12       #include <curses.h>
13       #include <term.h>
14
15       int setupterm(char *term, int fildes, int *errret);
16
17
18       int setterm(char *term);
19
20
21       int set_curterm(TERMINAL *nterm);
22
23
24       int del_curterm(TERMINAL *oterm);
25
26
27       int restartterm(char *term, int fildes, int *errret);
28
29
30       char *tparm(char *str, long int p1, long int p2, long int p3, long int p4,
31            long int p5, long int p6, long int p7, long int p8, long int p9);
32
33
34       int tputs(char *str, int affcnt, int (*putc)(char));
35
36
37       int putp(char *str);
38
39
40       int vidputs(chtype attrs, int (*putc)(char));
41
42
43       int vidattr(chtype attrs);
44
45
46       int mvcur(int oldrow, int oldcol, int newrow, int newcol);
47
48
49       int tigetflag(char *capname);
50
51
52       int tigetnum(char *capname);
53
54
55       char *tigetstr(char *capname);
56
57

DESCRIPTION

59       These  low-level  routines must be called by programs that have to deal
60       directly with the terminfo database to handle certain terminal capabil‐
61       ities,  such as programming function keys. For all other functionality,
62       curses routines are more suitable and their use is recommended.
63
64
65       Initially, setupterm() should be called. Note that setupterm() is auto‐
66       matically  called  by  initscr() and newterm(). This defines the set of
67       terminal-dependent variables  (listed  in  terminfo(4)).  The  terminfo
68       variables  lines and columns are initialized by setupterm() as follows:
69       If use_env(FALSE) has been called, values for lines and columns  speci‐
70       fied  in  terminfo  are  used.  Otherwise, if the environment variables
71       LINES and COLUMNS exist, their values are used.  If  these  environment
72       variables do not exist and the program is running in a window, the cur‐
73       rent window size is used. Otherwise, if the  environment  variables  do
74       not  exist,  the values for lines and columns specified in the terminfo
75       database are used.
76
77
78       The headers <curses.h> and <term.h> should be included (in this  order)
79       to  get  the definitions for these strings, numbers, and flags. Parame‐
80       terized strings should be passed through tparm() to  instantiate  them.
81       All  terminfo  strings  (including  the  output  of  tparm()) should be
82       printed with tputs() or putp(). Call the reset_shell_mode() routine  to
83       restore  the  tty modes before exiting (see curs_kernel(3CURSES)). Pro‐
84       grams which use cursor  addressing  should  output  enter_ca_mode  upon
85       startup  and should output exit_ca_mode before exiting. Programs desir‐
86       ing shell escapes should call reset_shell_mode and output  exit_ca_mode
87       before  the  shell  is  called and should output enter_ca_mode and call
88       reset_prog_mode after returning from the shell.
89
90
91       The setupterm() routine reads in the  terminfo  database,  initializing
92       the  terminfo structures, but does not set up the output virtualization
93       structures used by curses. The terminal type is  the  character  string
94       term;  if term is null, the environment variable TERM is used. All out‐
95       put is to file descriptor fildes which is initialized  for  output.  If
96       errret  is  not  null,  then setupterm() returns OK or ERR and stores a
97       status value in the integer pointed to by errret.  A  status  of  1  in
98       errret  is normal, 0 means that the terminal could not be found, and −1
99       means that the terminfo database could not be found. If errret is null,
100       setupterm()  prints  an  error message upon finding an error and exits.
101       Thus, the simplest call is:
102
103
104       setupterm((char *)0, 1, (int *)0);,
105
106
107       which uses all the defaults and sends the output to stdout.
108
109
110       The setterm() routine is being replaced by setupterm(). The call:
111
112
113       setupterm(term, 1, (int *)0)
114
115
116       provides the same functionality as setterm(term). The setterm() routine
117       is included here for compatibility and is supported at Level 2.
118
119
120       The  set_curterm()  routine  sets  the  variable cur_term to nterm, and
121       makes all of the terminfo boolean, numeric, and  string  variables  use
122       the values from nterm.
123
124
125       The del_curterm() routine frees the space pointed to by oterm and makes
126       it available for further use. If oterm is the same as cur_term,  refer‐
127       ences  to  any  of  the terminfo boolean, numeric, and string variables
128       thereafter  may  refer  to  invalid  memory  locations  until   another
129       setupterm() has been called.
130
131
132       The  restartterm()  routine  is  similar  to setupterm() and initscr(),
133       except that it is called after restoring memory to a previous state. It
134       assumes  that the windows and the input and output options are the same
135       as when memory was saved, but the terminal type and baud  rate  may  be
136       different.
137
138
139       The  tparm()  routine instantiates the string str with parameters pi. A
140       pointer is returned to the result of str with the parameters applied.
141
142
143       The tputs() routine applies padding information to the string  str  and
144       outputs  it.  The  str must be a terminfo string variable or the return
145       value from tparm(), tgetstr(), or tgoto().  affcnt  is  the  number  of
146       lines  affected,  or 1 if not applicable. putc is a putchar()-like rou‐
147       tine to which the characters are passed, one at a time.
148
149
150       The putp() routine calls tputs(str, 1, putchar). Note that  the  output
151       of  putpA()  always  goes  to  stdout,  not  to the fildes specified in
152       setupterm().
153
154
155       The vidputs() routine displays the string on the terminal in the  video
156       attribute mode attrs, which is any combination of the attributes listed
157       in curses(3CURSES). The characters are  passed  to  the  putchar()-like
158       routine putc() .
159
160
161       The  vidattr()  routine  is  like the vidputs() routine, except that it
162       outputs through putchar().
163
164
165       The mvcur() routine provides low-level cursor motion.
166
167
168       The tigetflag(), tigetnum() and tigetstr() routines return the value of
169       the  capability  corresponding  to the terminfo capname passed to them,
170       such as xenl.
171
172
173       With the tigetflag() routine, the value −1 is returned  if  capname  is
174       not a boolean capability.
175
176
177       With the tigetnum() routine, the value −2 is returned if capname is not
178       a numeric capability.
179
180
181       With the tigetstr() routine, the value (char *)−1 is returned  if  cap‐
182       name is not a string capability.
183
184
185       The  capname  for each capability is given in the table column entitled
186       capname code in the capabilities section of terminfo(4).
187
188         char *boolnames, *boolcodes, *boolfnames
189         char *numnames, *numcodes, *numfnames
190         char *strnames, *strcodes, *strfnames
191
192
193
194       These null-terminated arrays contain the capnames, the  termcap  codes,
195       and the full C names, for each of the terminfo variables.
196

RETURN VALUES

198       All  routines  return the integer ERR upon failure and an integer value
199       other than ERR upon successful completion, unless  otherwise  noted  in
200       the preceding routine descriptions.
201
202
203       Routines that return pointers always return NULL on error.
204

ATTRIBUTES

206       See attributes(5) for descriptions of the following attributes:
207
208
209
210
211       ┌─────────────────────────────┬─────────────────────────────┐
212       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
213       ├─────────────────────────────┼─────────────────────────────┤
214       │MT-Level                     │Unsafe                       │
215       └─────────────────────────────┴─────────────────────────────┘
216

SEE ALSO

218       curs_initscr(3CURSES),   curs_kernel(3CURSES),   curs_termcap(3CURSES),
219       curses(3CURSES), putc(3C), terminfo(4), attributes(5)
220

NOTES

222       The header <curses.h> automatically includes the headers  <stdio.h> and
223       <unctrl.h>.
224
225
226       The setupterm() routine should be used in place of setterm().
227
228
229       Note that vidattr() and vidputs() may be macros.
230
231
232
233SunOS 5.11                        31 Dec 1996           curs_terminfo(3CURSES)
Impressum