Debian Codegraph @

upstream/debian-trixie/man3/curses_variables.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-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: curs_variables.3x,v 1.58 2025/01/19 00:51:10 tom Exp $
31 .TH curses_variables 3NCURSES 2025-01-18 "ncurses 6.5" "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 .ie \n(.g .ds : \:
44 .el .ds : \" empty
45 .
46 .de bP
47 .ie n .IP \(bu 4
48 .el .IP \(bu 2
49 ..
50 .
51 .\" URL hyperlink support macros from groff's "an-ext.tmac"
52 .
53 .\" Save the automatic hyphenation mode.
54 .\"
55 .\" In AT&T troff, there was no register exposing the hyphenation mode,
56 .\" and no way to save and restore it. Set `mH` to a reasonable value
57 .\" for your implementation and preference.
58 .de mY
59 . ie !\\n(.g \
60 . nr mH 14
61 . el \
62 . do nr mH \\n[.hy] \" groff extension register
63 ..
64 .
65 .\" Prepare link text for mail/web hyperlinks. `MT` and `UR` call this.
66 .de mV
67 . ds mU \\$1\"
68 ..
69 .
70 .\" Emit hyperlink. The optional argument supplies trailing punctuation
71 .\" after link text. `ME` and `UE` call this.
72 .de mQ
73 . mY
74 . nh
75 <\\*(mU>\\$1
76 . hy \\n(mH
77 . rm mU
78 ..
79 .
80 .\" Start URL.
81 .\" .UR url
82 .if !\n(.g \{\
83 .de UR
84 . mV \\$1
85 ..
86 .\}
87 .
88 .\" End URL.
89 .\" .UE [punctuation]
90 .if !\n(.g \{\
91 .de UE
92 . mQ \\$1
93 ..
94 .\}
95 .
96 .SH NAME
97 \fI\%bool\fP,
98 \fI\%chtype\fP,
99 \fI\%cchar_t\fP,
100 \fI\%attr_t\fP,
101 \fI\%SCREEN\fP,
102 \fI\%WINDOW\fP,
103 \fB\%TRUE\fP,
104 \fB\%FALSE\fP,
105 \fB\%ERR\fP,
106 \fB\%OK\fP,
107 \fB\%CCHARW_MAX\fP,
108 \fB\%curscr\fP,
109 \fB\%newscr\fP,
110 \fB\%stdscr\fP,
111 \fB\%COLORS\fP,
112 \fB\%COLOR_PAIRS\fP,
113 \fB\%COLS\fP,
114 \fB\%LINES\fP,
115 \fB\%ESCDELAY\fP,
116 \fB\%TABSIZE\fP \-
117 \fIcurses\fR data types, constants, and global variables
118 .SH SYNOPSIS
119 .nf
120 \fB#include <curses.h>
121 .PP
122 \fI/* data types */
123 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;
124 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;
125 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;
126 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;
127 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN;
128 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;
129 .PP
130 \fI/* constants */
131 \fBconst bool TRUE;
132 \fBconst bool FALSE;
133 .PP
134 \fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;
135 \fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;
136 .PP
137 \fI/* extension */
138 \fBconst \fI/*\fP .\|.\|. \fI*/\fP CCHARW_MAX;
139 .PP
140 \fI/* variables */
141 \fBint COLORS;
142 \fBint COLOR_PAIRS;
143 \fBint COLS;
144 \fBint LINES;
145 \fBWINDOW * curscr;
146 \fBWINDOW * stdscr;
147 .PP
148 \fI/* extensions */
149 \fBint ESCDELAY;
150 \fBint TABSIZE;
151 \fBWINDOW * newscr;
152 .fi
153 .SH DESCRIPTION
154 This page summarizes data types,
155 constants,
156 and variables provided by the \fIcurses\fP library.
157 Locate further discussion in \fB\%ncurses\fP(3NCURSES).
158 .PP
159 Depending on \fI\%ncurses\fP's build-time configuration,
160 the variables may instead be
161 macros (see \fB\%threads\fP(3NCURSES) and \fB\%opaque\fP(3NCURSES))
162 that provide read-only access to the library's state.
163 In either case,
164 applications should treat them as read-only to avoid
165 confusing the library.
166 .SH CONSTANTS
167 .SS "TRUE, FALSE"
168 The \fIcurses\fP library defines \fBTRUE\fP and \fBFALSE\fP
169 to represent the values of the Boolean data type.
170 .SS "ERR, OK"
171 \fIcurses\fP and \fIterminfo\fP routines frequently return these
172 constant integral values indicating failure and success,
173 respectively.
174 .SS CCHARW_MAX
175 This integral value,
176 an
177 .I \%ncurses
178 extension,
179 contains the maximum number of
180 .I \%wchar_t
181 wide characters that can be stored in a
182 .I curses
183 complex character
184 .IR \%cchar_t "."
185 .SH "PREDEFINED TYPES"
186 .SS "\fIbool\fP"
187 X/Open Issue\ 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
188 standards,
189 each of which also defined a Boolean data type.
190 The \fIcurses\fP library requires an integral type \fIbool\fP.
191 .PP
192 \fB\%ncurses\fP' configure script attempts to discover the
193 data type used by the system's C and C++ compilers,
194 to reuse for the \fIcurses\fP \fIbool\fP.
195 .SS "\fIchtype\fP"
196 The \fI\%chtype\fP integral type combines a
197 (\*(``narrow\*('',
198 8-bit)
199 character with attributes encoding the character's \fIrendition\fP,
200 such as the styling of its typeface and/or foreground and background
201 colors.
202 See,
203 for example,
204 \fB\%addch\fP(3NCURSES),
205 \fB\%attron\fP(3NCURSES),
206 and
207 \fB\%inch\fP(3NCURSES).
208 .SS "\fIcchar_t\fP, \fIattr_t\fP"
209 \fI\%chtype\fP is too small for the standard C library's wide-character
210 type,
211 \fIwchar_t\fP.
212 \fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
213 enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
214 (a \*(``user-perceived character\*('' [UAX #29],
215 which may nevertheless require several character encoding units to
216 represent).
217 \fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
218 apply to \fI\%cchar_t\fPs.
219 See,
220 for example,
221 \fB\%add_wch\fP(3NCURSES),
222 \fB\%attr_on\fP(3NCURSES),
223 and
224 \fB\%in_wch\fP(3NCURSES).
225 .SS "\fISCREEN\fP"
226 .I curses
227 manages a terminal device with this structure type;
228 see \fB\%initscr\fP(3NCURSES).
229 .SS "\fIWINDOW\fP"
230 .I curses
231 represents rectangular portions of the terminal screen with the
232 .I \%WINDOW
233 structure type;
234 see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3NCURSES).
235 .SH "VARIABLES"
236 .SS "curscr, newscr, stdscr"
237 When a
238 .I curses
239 application calls
240 \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES),
241 the library creates a window named
242 .B \%stdscr
243 that is the same size as the terminal screen
244 and is the implicit window used by functions
245 that interact with a window
246 but do not take a parameter identifying one;
247 many
248 .I curses
249 functions use it.
250 An application need not use
251 .BR \%stdscr ";"
252 it might prefer to tile the display into multiple windows instead.
253 .PP
254 The library records updates to the terminal screen in a window named
255 \fB\%curscr\fP.
256 This object is referred to as the \*(``physical screen\*('' in
257 \fB\%refresh\fP(3NCURSES) and
258 \fB\%outopts\fP(3NCURSES).
259 .PP
260 \fI\%ncurses\fP collects pending updates to the terminal screen in a
261 window named \fB\%newscr\fP.
262 This object is referred to as the \*(``virtual screen\*('' in the
263 \fB\%kernel\fP(3NCURSES),
264 \fB\%refresh\fP(3NCURSES),
265 and
266 \fB\%outopts\fP(3NCURSES).
267 When the screen is refreshed,
268 \fIcurses\fP determines a minimal set of updates using the terminal's
269 capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
270 .SS COLORS
271 Once \fIcurses\fP is initialized,
272 \fB\%COLORS\fP
273 contains the number of colors supported by the terminal;
274 see \fB\%color\fP(3NCURSES).
275 .SS COLOR_PAIRS
276 Once \fIcurses\fP is initialized,
277 \fB\%COLOR_PAIRS\fP
278 contains the number of color pairs supported by the terminal;
279 see \fB\%color\fP(3NCURSES).
280 .SS "COLS, LINES"
281 Once \fIcurses\fP is initialized,
282 .B \%COLS
283 and
284 .B LINES
285 contain the screen's width and height in character cells,
286 respectively;
287 that is,
288 the number of columns and lines.
289 .SS ESCDELAY
290 For
291 .I curses
292 to distinguish the ESC character resulting from a user's press of the
293 \*(``Escape\*('' key on the input device from one beginning an
294 .I "escape sequence"
295 (as commonly produced by function keys),
296 it waits after the escape character to see if further characters are
297 available on the input stream within a short interval.
298 .B \%ESCDELAY
299 stores this interval in milliseconds.
300 .PP
301 If \fB\%keypad\fP(3NCURSES) is disabled for the
302 .I curses
303 window receiving input,
304 a program must disambiguate escape sequences itself.
305 .SS TABSIZE
306 The \fIcurses\fP library converts a tab character to this number of
307 spaces as it adds a tab to a window;
308 see \fB\%addch\fP(3NCURSES).
309 .SH NOTES
310 Either \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES) initializes
311 \fIcurses\fP.
312 .PP
313 If
314 .I \%ncurses
315 is configured to provide separate
316 .I curses
317 and
318 .I \%tinfo
319 libraries,
320 most of these symbols reside in the former.
321 The
322 .B bool
323 data type
324 is used by both.
325 .SH EXTENSIONS
326 The
327 .B \%CCHARW_MAX
328 constant,
329 and
330 .BR \%ESCDELAY ","
331 .BR \%TABSIZE ","
332 and
333 .B \%newscr
334 variables,
335 are
336 extensions,
337 the first of these originating in
338 .\" Solaris xcurses calls it M_CCHAR_MAX.
339 .IR \%ncurses "."
340 .SH PORTABILITY
341 Applications employing
342 .I \%ncurses
343 extensions should condition their use on the visibility of the
344 .B \%NCURSES_VERSION
345 preprocessor macro.
346 .PP
347 The X/Open Curses standard documents all of the foregoing types and
348 symbols except for
349 .BR \%CCHARW_MAX ","
350 .BR \%newscr ","
351 .BR \%TABSIZE ","
352 and
353 .BR \%ESCDELAY "."
354 .PP
355 X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data
356 structure\*('';
357 SVr4 gave more details,
358 noting its use \*(``for certain low-level operations like clearing and
359 redrawing a screen containing garbage\*(''.
360 .\" SVID 4, Volume 3, p. 408
361 Neither specified its interaction with the rest of the interface beyond
362 use as an argument to \fB\%clearok\fP(3NCURSES) and \fB\%wrefresh\fP(3NCURSES).
363 .PP
364 \fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
365 When refreshing the screen,
366 it is used as a working area for combining the standard window
367 \fB\%stdscr\fP with any others the application may have created with
368 \fB\%newwin\fP(3NCURSES).
369 When the update of \fB\%newscr\fP is complete,
370 \fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP.
371 .PP
372 \fB\%TABSIZE\fP is a feature of SVr4 \fIcurses\fP.
373 .bP
374 SVr4 initially sets \fB\%TABSIZE\fP from the terminal description's
375 \fB\%init_tabs\fP capability.
376 After that,
377 it can be altered by applications using SVr4 \fIcurses\fP.
378 .bP
379 SVr4 \fIcurses\fP uses the value of \fB\%TABSIZE\fP to compute the
380 position of tab stops when updating both
381 the virtual screen with \fB\%addch\fP(3NCURSES) and
382 the physical screen with \fB\%mvcur\fP(3NCURSES).
383 .bP
384 \fI\%ncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
385 virtual screen.
386 It uses the terminal description's \*(``\fBit\fP\*(''
387 \%(\fBinit_tabs\fP) capability for computing hardware tabs
388 (that is,
389 tab stops on the physical screen).
390 .bP
391 Other implementations differ.
392 For instance,
393 NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
394 environment variable.
395 \fI\%ncurses\fP does not.
396 .IP
397 NetBSD \fIcurses\fP does not support hardware tabs;
398 it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
399 variable only for updating the virtual screen.
400 .PP
401 \fB\%ESCDELAY\fP is a feature of AIX \fIcurses\fP.
402 .bP
403 In AIX,
404 the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds.
405 .bP
406 The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
407 .bP
408 AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
409 \fI\%ncurses\fP does not enforce any upper limit.
410 .PP
411 \fI\%ncurses\fP has long used \fB\%ESCDELAY\fP with units of
412 milliseconds,
413 making it impossible to be completely compatible with AIX.
414 Consequently,
415 most users have decided either to override the value,
416 or to rely upon its default.
417 .SH SEE ALSO
418 .UR https://\*:unicode\*:.org/\*:reports/\*:tr29/
419 [UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
420 Segmentation\*(''
421 .UE
422 .PP
423 \fB\%getcchar\fP(3NCURSES)
424 further discusses
425 .BR \%CCHARW_MAX "."
426 .PP
427 \fB\%ncurses\fP(3NCURSES),
428 \fB\%color\fP(3NCURSES),
429 \fB\%opaque\fP(3NCURSES),
430 \fB\%terminfo\fP(3NCURSES),
431 \fB\%threads\fP(3NCURSES),
432 \fB\%terminfo_variables\fP(3NCURSES),
433 \fB\%terminfo\fP(5)