Debian Codegraph @

upstream/debian-unstable/man3/terminfo_variables.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2019-2024,2025 Thomas E. Dickey *
3 .\" Copyright 2010-2015,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: term_variables.3x,v 1.44 2025/11/12 01:27:41 tom Exp $
31 .TH terminfo_variables 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .SH NAME
44 \fB\%SP\fP,
45 \fB\%acs_map\fP,
46 \fB\%boolcodes\fP,
47 \fB\%boolfnames\fP,
48 \fB\%boolnames\fP,
49 \fB\%cur_term\fP,
50 \fB\%numcodes\fP,
51 \fB\%numfnames\fP,
52 \fB\%numnames\fP,
53 \fB\%strcodes\fP,
54 \fB\%strfnames\fP,
55 \fB\%strnames\fP,
56 \fB\%ttytype\fP \-
57 \fIterminfo\fR global variables
58 .SH SYNOPSIS
59 .nf
60 \fB#include <curses.h>
61 \fB#include <term.h>
62 .PP
63 \fBchtype acs_map[];
64 .PP
65 \fBSCREEN * SP;
66 .PP
67 \fBTERMINAL * cur_term;
68 .PP
69 \fBchar ttytype[];
70 .PP
71 \fBNCURSES_CONST char * const boolcodes[];
72 \fBNCURSES_CONST char * const boolfnames[];
73 \fBNCURSES_CONST char * const boolnames[];
74 .PP
75 \fBNCURSES_CONST char * const numcodes[];
76 \fBNCURSES_CONST char * const numfnames[];
77 \fBNCURSES_CONST char * const numnames[];
78 .PP
79 \fBNCURSES_CONST char * const strcodes[];
80 \fBNCURSES_CONST char * const strfnames[];
81 \fBNCURSES_CONST char * const strnames[];
82 .fi
83 .SH DESCRIPTION
84 This page summarizes variables provided by the
85 .I curses
86 library's lower-level
87 .I \%term\%info
88 interface.
89 Locate a more complete description in the \fBterminfo\fP(3NCURSES) manual
90 page.
91 .PP
92 Depending on
93 .IR \%ncurses 's
94 build-time configuration,
95 these may be actual variables,
96 or macros
97 (see \fBthreads\fP(3NCURSES))
98 that provide read-only access to
99 .IR curses 's
100 state.
101 In either case,
102 applications should treat them as read-only to avoid confusing the
103 library.
104 .SS "Alternate Character Set Mapping"
105 After initializing the
106 .I curses
107 or
108 .I \%term\%info
109 interfaces,
110 the
111 .B acs_map
112 array holds information used to translate cells with the
113 .B \%A_ALTCHARSET
114 video attribute into line-drawing characters.
115 .PP
116 The encoding of the information in this array has changed periodically.
117 Application developers need only know that it is used for the
118 \*(``ACS_\*('' constants in
119 .IR \%curses.h "."
120 .PP
121 The comparable data for the wide-character library are not exposed as
122 symbols in the API.
123 .SS "Current Terminal Data"
124 After initializing the
125 .I curses
126 or
127 .I \%term\%info
128 interfaces,
129 .B cur_term
130 contains data describing the current terminal.
131 It is also updated as a side effect of \fBset_term\fP(3NSES) and
132 \fBdelscreen\fP(3NCURSES).
133 .PP
134 It is possible to save a value of
135 .B cur_term
136 for subsequent use as a parameter to \fBset_term\fP(3NSES)
137 for switching between screens.
138 Alternatively,
139 one can save the return value from \fBnewterm\fP(3NCURSES) or
140 \fBsetupterm\fP(3NCURSES) to reuse in \fBset_term\fP(3NSES).
141 .SS "\fIterminfo\fP Lookup Tables"
142 The \fBtic\fP(1) and \fBinfocmp\fP(1) programs use lookup tables for
143 the long and short names of
144 .I \%term\%info
145 capabilities,
146 as well as the corresponding names for
147 .I termcap
148 capabilities.
149 These are available to other applications,
150 though the hash tables used by the
151 .I \%term\%info
152 and
153 .I termcap
154 functions are not.
155 .PP
156 .I \%term\%info
157 stores capability names in arrays with an \*(``f\*('' (eff) in their
158 names:
159 .BR \%boolfnames ","
160 .BR \%numfnames ","
161 and
162 .BR \%strfnames "."
163 It stores the briefer capability codes in arrays without the
164 \*(``f\*('':
165 .BR \%boolnames ","
166 .BR \%numnames ","
167 and
168 .BR \%strnames "."
169 The corresponding
170 .I termcap
171 capability codes are stored in
172 .BR \%boolcodes ","
173 .BR \%numcodes ","
174 and
175 .BR \%strcodes "."
176 \fB\%terminfo\fP(5) catalogs these.
177 .\"
178 .SS "Terminal Type"
179 A terminal description begins with one or more terminal names
180 separated by \*(``|\*('' (vertical bars).
181 On initialization of the
182 .I curses
183 or
184 .I \%term\%info
185 interfaces,
186 \fBsetupterm\fP(3NCURSES) copies the terminal name to the array
187 .BR ttytype "."
188 .\"
189 .SS "\fIterminfo\fP Names"
190 In addition to the variables,
191 .I term.h
192 also defines a symbol for each
193 .I \%term\%info
194 capability name.
195 These are in terms of the symbol
196 .BR CUR ","
197 which is defined
198 .PP
199 .RS
200 .EX
201 #define CUR ((TERMTYPE *)(cur_term))\->
202 .EE
203 .RE
204 .PP
205 These symbols provide a faster method of accessing
206 .I \%term\%info
207 capabilities than using,
208 for example,
209 \fBtigetstr\fP(3NCURSES).
210 .PP
211 The definition of
212 .B CUR
213 is implementation-dependent,
214 but each
215 .I \%term\%info
216 library defines these names to point
217 into the in-memory description of the current terminal.
218 For example,
219 in
220 .IR \%ncurses ","
221 the expressions
222 .B tigetstr("key_dc")
223 and
224 \*(``\c\" `` string not reliable in a macro call on DWB/Heirloom nroffs
225 .B "CUR Strings[59]\c"
226 \*('' \" '' string not reliable in a macro call on DWB/Heirloom nroffs
227 are equivalent.
228 .\"
229 .SS "\fIterminfo\fP and \fIcurses"
230 \fB\%setupterm\fP(3NCURSES) initializes the lower-level
231 .I \%term\%info
232 interface.
233 The higher-level
234 .I curses
235 interface uses the
236 .I \%term\%info
237 interface internally;
238 the symbol
239 .B SP
240 bridges the
241 .I curses
242 .I SCREEN
243 type with the
244 .I \%term\%info
245 .I TERMINAL
246 type.
247 .\"
248 .SH PORTABILITY
249 X/Open Curses does not describe any of these symbols except for
250 .IR \%cur_term "."
251 (The inclusion of
252 .I \%cur_term
253 appears to be an oversight,
254 since other comparable low-level information is omitted by X/Open.)
255 .PP
256 Other implementations may have comparable variables.
257 Some implementations provide the variables in their libraries,
258 but omit them from the header files.
259 .PP
260 All implementations that provide
261 .I \%term\%info
262 interfaces add definitions
263 as described in the
264 .RI \*(`` terminfo
265 Names\*('' section above.
266 Most,
267 but not all,
268 base the definition upon the
269 .I \%cur_term
270 variable.
271 .SH SEE ALSO
272 \fB\%ncurses\fP(3NCURSES),
273 \fB\%terminfo\fP(3NCURSES),
274 \fB\%threads\fP(3NCURSES),
275 \fB\%terminfo\fP(5)