1curs_terminfo(3X) curs_terminfo(3X)
2
6 del_curterm, mvcur, putp, restartterm, set_curterm, setterm, setupterm,
7 tigetflag, tigetnum, tigetstr, tparm, tputs, vid_attr, vid_puts,
8 vidattr, vidputs - curses interfaces to terminfo database
9
11 #include <curses.h>
12 #include <term.h>
13 int setupterm(char *term, int fildes, int *errret);
15 int setterm(char *term);
16 TERMINAL *set_curterm(TERMINAL *nterm);
17 int del_curterm(TERMINAL *oterm);
18 int restartterm(char *term, int fildes, int *errret);
19 char *tparm(char *str, ...);
20 int tputs(const char *str, int affcnt, int (*putc)(int));
21 int putp(const char *str);
22 int vidputs(chtype attrs, int (*putc)(int));
23 int vidattr(chtype attrs);
24 int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(char));
25 int vid_attr(attr_t attrs, short pair, void *opts);
26 int mvcur(int oldrow, int oldcol, int newrow, int newcol);
27 int tigetflag(char *capname);
28 int tigetnum(char *capname);
29 char *tigetstr(char *capname);
30
32 These low-level routines must be called by programs that have to deal
33 directly with the terminfo database to handle certain terminal capabil‐
34 ities, such as programming function keys. For all other functionality,
35 curses routines are more suitable and their use is recommended.
36 Initially, setupterm should be called. Note that setupterm is automat‐
38 ically called by initscr and newterm. This defines the set of termi‐
39 nal-dependent variables [listed in terminfo(5)]. The terminfo vari‐
40 ables lines and columns are initialized by setupterm as follows:
41 If use_env(FALSE) has been called, values for lines and columns
43 specified in terminfo are used.
44 Otherwise, if the environment variables LINES and COLUMNS exist,
46 their values are used. If these environment variables do not
47 exist and the program is running in a window, the current window
48 size is used. Otherwise, if the environment variables do not
49 exist, the values for lines and columns specified in the termin‐
50 fo database are used.
51 The header files curses.h and term.h should be included (in this order)
53 to get the definitions for these strings, numbers, and flags. Parame‐
54 terized strings should be passed through tparm to instantiate them.
55 All terminfo strings [including the output of tparm] should be printed
56 with tputs or putp. Call the reset_shell_mode to restore the tty modes
57 before exiting [see curs_kernel(3X)]. Programs which use cursor ad‐
58 dressing should output enter_ca_mode upon startup and should output ex‐
59 it_ca_mode before exiting. Programs desiring shell escapes should call
60 reset_shell_mode and output exit_ca_mode before the shell is called and
62 should output enter_ca_mode and call reset_prog_mode after returning
63 from the shell.
64 The setupterm routine reads in the terminfo database, initializing the
66 terminfo structures, but does not set up the output virtualization
67 structures used by curses. The terminal type is the character string
68 term; if term is null, the environment variable TERM is used. All out‐
69 put is to file descriptor fildes which is initialized for output. If
70 errret is not null, then setupterm returns OK or ERR and stores a sta‐
71 tus value in the integer pointed to by errret. A return value of OK
72 combined with status of 1 in errret is normal. If ERR is returned, ex‐
73 amine errret:
74 1 means that the terminal is hardcopy, cannot be used for
76 curses applications.
77 0 means that the terminal could not be found, or that it is a
79 generic type, having too little information for curses ap‐
80 plications to run.
81 -1 means that the terminfo database could not be found.
83 If errret is null, setupterm prints an error message upon finding an
85 error and exits. Thus, the simplest call is:
86 setupterm((char *)0, 1, (int *)0);,
88 which uses all the defaults and sends the output to stdout.
90 The setterm routine is being replaced by setupterm. The call:
92 setupterm(term, 1, (int *)0)
94 provides the same functionality as setterm(term). The setterm routine
96 is included here for BSD compatibility, and is not recommended for new
97 programs.
98 The set_curterm routine sets the variable cur_term to nterm, and makes
100 all of the terminfo boolean, numeric, and string variables use the val‐
101 ues from nterm. It returns the old value of cur_term.
102 The del_curterm routine frees the space pointed to by oterm and makes
104 it available for further use. If oterm is the same as cur_term, refer‐
105 ences to any of the terminfo boolean, numeric, and string variables
106 thereafter may refer to invalid memory locations until another se‐
107 tupterm has been called.
108 The restartterm routine is similar to setupterm and initscr, except
110 that it is called after restoring memory to a previous state (for exam‐
111 ple, when reloading a game saved as a core image dump). It assumes
112 that the windows and the input and output options are the same as when
113 memory was saved, but the terminal type and baud rate may be different.
114 Accordingly, it saves various tty state bits, calls setupterm, and then
115 restores the bits.
116 The tparm routine instantiates the string str with parameters pi. A
118 pointer is returned to the result of str with the parameters applied.
119 The tputs routine applies padding information to the string str and
121 outputs it. The str must be a terminfo string variable or the return
122 value from tparm, tgetstr, or tgoto. affcnt is the number of lines af‐
123 fected, or 1 if not applicable. putc is a putchar-like routine to
124 which the characters are passed, one at a time.
125 The putp routine calls tputs(str, 1, putchar). Note that the output of
127 putp always goes to stdout, not to the fildes specified in setupterm.
128 The vidputs routine displays the string on the terminal in the video
130 attribute mode attrs, which is any combination of the attributes listed
131 in curses(3X). The characters are passed to the putchar-like routine
132 putc.
133 The vidattr routine is like the vidputs routine, except that it outputs
135 through putchar.
136 The vid_attr and vid_puts routines correspond to vidattr and vidputs,
138 respectively. They use a set of arguments for representing the video
139 attributes plus color, i.e., one of type attr_t for the attributes and
140 one of short for the color_pair number. The vid_attr and vid_puts rou‐
141 tines are designed to use the attribute constants with the WA_ prefix.
142 The opts argument is reserved for future use. Currently, applications
143 must provide a null pointer for that argument.
144 The mvcur routine provides low-level cursor motion. It takes effect
146 immediately (rather than at the next refresh).
147 The tigetflag, tigetnum and tigetstr routines return the value of the
149 capability corresponding to the terminfo capname passed to them, such
150 as xenl.
151 The tigetflag routine returns the value -1 if capname is not a boolean
153 capability, or 0 if it is canceled or absent from the terminal descrip‐
154 tion.
155 The tigetnum routine returns the value -2 if capname is not a numeric
157 capability, or -1 if it is canceled or absent from the terminal de‐
158 scription.
159 The tigetstr routine returns the value (char *)-1 if capname is not a
161 string capability, or 0 if it is canceled or absent from the terminal
162 description.
163 The capname for each capability is given in the table column entitled
165 capname code in the capabilities section of terminfo(5).
166 char *boolnames[], *boolcodes[], *boolfnames[]
168 char *numnames[], *numcodes[], *numfnames[]
170 char *strnames[], *strcodes[], *strfnames[]
172 These null-terminated arrays contain the capnames, the termcap codes,
174 and the full C names, for each of the terminfo variables.
175
177 Routines that return an integer return ERR upon failure and OK (SVr4
178 only specifies "an integer value other than ERR") upon successful com‐
179 pletion, unless otherwise noted in the preceding routine descriptions.
180 Routines that return pointers always return NULL on error.
182 X/Open defines no error conditions. In this implementation
184 del_curterm
186 returns an error if its terminal parameter is null.
187 restartterm
189 returns an error if the associated call to setupterm re‐
190 turns an error.
191 setupterm
193 returns an error if it cannot allocate enough memory, or
194 create the initial windows (stdscr, curscr, newscr). Other
195 error conditions are documented above.
196
198 The setupterm routine should be used in place of setterm. It may be
199 useful when you want to test for terminal capabilities without commit‐
200 ting to the allocation of storage involved in initscr.
201 Note that vidattr and vidputs may be macros.
203
205 The function setterm is not described in the XSI Curses standard and
206 must be considered non-portable. All other functions are as described
207 in the XSI curses standard.
208 setupterm copies the terminal name to the array ttytype. This is not
210 part of X/Open Curses, but is assumed by some applications.
211 In System V Release 4, set_curterm has an int return type and returns
213 OK or ERR. We have chosen to implement the XSI Curses semantics.
214 In System V Release 4, the third argument of tputs has the type int
216 (*putc)(char).
217 The XSI Curses standard prototypes tparm with a fixed number of parame‐
219 ters, rather than a variable argument list. This implementation uses a
220 variable argument list. Portable applications should provide 9 parame‐
221 ters after the format; zeroes are fine for this purpose.
222 XSI notes that after calling mvcur, the curses state may not match the
224 actual terminal state, and that an application should touch and refresh
225 the window before resuming normal curses calls. Both ncurses and Sys‐
226 tem V Release 4 curses implement mvcur using the SCREEN data allocated
227 in either initscr or newterm. So though it is documented as a terminfo
228 function, mvcur is really a curses function which is not well speci‐
229 fied.
230 XSI states that the old location must be given for mvcur. This imple‐
232 mentation allows the caller to use -1's for the old ordinates. In that
233 case, the old location is unknown.
234 Extended terminal capability names, e.g., as defined by tic -x, are not
236 stored in the arrays described in this section.
237
239 curses(3X), curs_initscr(3X), curs_kernel(3X), curs_termcap(3X),
240 putc(3), terminfo(5)
241 curs_terminfo(3X)