Debian Codegraph @

upstream/mageia-cauldron/man3/curs_variables.3x

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.65 2025/07/05 13:04:08 tom Exp $
31 .TH curs_variables 3X 2025-07-05 "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\%curses\fP(3X).
158 .PP
159 Depending on \fI\%ncurses\fP's build-time configuration,
160 the variables may instead be
161 macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(3X))
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 .IR \%ncurses 's
193 configure script attempts to discover the
194 data type used by the system's C and C++ compilers,
195 to reuse for the \fIcurses\fP \fIbool\fP.
196 .SS "\fIchtype\fP"
197 The \fI\%chtype\fP integral type combines a
198 (\*(``narrow\*('',
199 8-bit)
200 character with attributes encoding the character's \fIrendition\fP,
201 such as the styling of its typeface and/or foreground and background
202 colors.
203 See,
204 for example,
205 \fB\%addch\fP(3X),
206 \fB\%attron\fP(3X),
207 and
208 \fB\%inch\fP(3X).
209 .SS "\fIcchar_t\fP, \fIattr_t\fP"
210 \fI\%chtype\fP is too small for the standard C library's wide-character
211 type,
212 \fIwchar_t\fP.
213 \fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
214 enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
215 (a \*(``user-perceived character\*('' [UAX #29],
216 which may nevertheless require several character encoding units to
217 represent).
218 \fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
219 apply to \fI\%cchar_t\fPs.
220 See,
221 for example,
222 \fB\%add_wch\fP(3X),
223 \fB\%attr_on\fP(3X),
224 and
225 \fB\%in_wch\fP(3X).
226 .SS "\fISCREEN\fP"
227 .I curses
228 manages a terminal device with this structure type;
229 see \fB\%initscr\fP(3X).
230 .SS "\fIWINDOW\fP"
231 .I curses
232 represents rectangular portions of the terminal screen with the
233 .I \%WINDOW
234 structure type;
235 see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3X).
236 .SH "VARIABLES"
237 .SS "curscr, newscr, stdscr"
238 When a
239 .I curses
240 application calls
241 \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X),
242 the library creates a window named
243 .B \%stdscr
244 that is the same size as the terminal screen,
245 (minus any lines reserved by
246 \fB\%ripoffline\fP(3X) or \fB\%slk_init\fP(3X))
247 and is the implicit window used by functions
248 that interact with a window
249 but do not take a parameter identifying one;
250 many
251 .I curses
252 functions use it.
253 An application need not use
254 .BR \%stdscr ";"
255 it might prefer to tile the display into multiple windows instead.
256 .PP
257 The library records updates to the terminal screen in a window named
258 \fB\%curscr\fP.
259 This object is referred to as the \*(``physical screen\*('' in
260 \fB\%curs_refresh\fP(3X) and
261 \fB\%curs_outopts\fP(3X).
262 .PP
263 \fI\%ncurses\fP collects pending updates to the terminal screen in a
264 window named \fB\%newscr\fP.
265 This object is referred to as the \*(``virtual screen\*('' in the
266 \fB\%curs_kernel\fP(3X),
267 \fB\%curs_refresh\fP(3X),
268 and
269 \fB\%curs_outopts\fP(3X).
270 When the screen is refreshed,
271 \fIcurses\fP determines a minimal set of updates using the terminal's
272 capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
273 .SS COLORS
274 Once \fIcurses\fP is initialized,
275 \fB\%COLORS\fP
276 contains the number of colors supported by the terminal;
277 see \fB\%curs_color\fP(3X).
278 .SS COLOR_PAIRS
279 Once \fIcurses\fP is initialized,
280 \fB\%COLOR_PAIRS\fP
281 contains the number of color pairs supported by the terminal;
282 see \fB\%curs_color\fP(3X).
283 .SS "COLS, LINES"
284 Once \fIcurses\fP is initialized,
285 .B \%COLS
286 and
287 .B LINES
288 contain the screen's width and height in character cells,
289 respectively;
290 that is,
291 the number of columns and lines.
292 .SS ESCDELAY
293 When reading key strokes from a window in keypad mode,
294 .I curses
295 distinguishes the ESC character resulting from a user's press of the
296 \*(``Escape\*('' key on the input device
297 from one beginning an escape sequence
298 (commonly produced by function keys),
299 by waiting after receiving the escape character
300 to see if further characters are available
301 on the input stream within a short interval.
302 .B \%ESCDELAY
303 stores this interval in milliseconds.
304 .PP
305 If \fB\%keypad\fP(3X) is disabled for the
306 .I curses
307 window receiving input,
308 a program must disambiguate escape sequences itself.
309 .SS TABSIZE
310 The \fIcurses\fP library converts a tab character to this number of
311 spaces as it adds a tab to a window;
312 see \fB\%curs_addch\fP(3X).
313 .SH NOTES
314 Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
315 \fIcurses\fP.
316 .PP
317 If
318 .I \%ncurses
319 is configured to provide separate
320 .I curses
321 and
322 .I \%tinfo
323 libraries,
324 most of these symbols reside in the former.
325 The
326 .B bool
327 data type
328 is used by both.
329 .SH EXTENSIONS
330 The
331 .B \%CCHARW_MAX
332 constant,
333 and
334 .BR \%ESCDELAY ","
335 .BR \%TABSIZE ","
336 and
337 .B \%newscr
338 variables,
339 are
340 extensions,
341 the first of these originating in
342 .\" Solaris xcurses calls it M_CCHAR_MAX.
343 .IR \%ncurses "."
344 .SH PORTABILITY
345 Applications employing
346 .I \%ncurses
347 extensions should condition their use on the visibility of the
348 .B \%NCURSES_VERSION
349 preprocessor macro.
350 .PP
351 The X/Open Curses standard documents all of the foregoing types and
352 symbols except for
353 .BR \%CCHARW_MAX ","
354 .BR \%newscr ","
355 .BR \%TABSIZE ","
356 and
357 .BR \%ESCDELAY "."
358 .PP
359 X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data
360 structure\*('';
361 SVr4 gave more details,
362 noting its use \*(``for certain low-level operations like clearing and
363 redrawing a screen containing garbage\*(''.
364 .\" SVID 4, Volume 3, p. 408
365 Neither specified its interaction with the rest of the interface beyond
366 use as an argument to \fB\%clearok\fP(3X) and \fB\%wrefresh\fP(3X).
367 .PP
368 \fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
369 When refreshing the screen,
370 it is used as a working area for combining the standard window
371 \fB\%stdscr\fP with any others the application may have created with
372 \fB\%newwin\fP(3X).
373 When the update of \fB\%newscr\fP is complete,
374 \fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP.
375 .PP
376 .B \%TABSIZE
377 is a feature of SVr4
378 .IR curses "."
379 .bP
380 SVr4 initially sets
381 .B \%TABSIZE
382 from the terminal description's
383 .B \%init_tabs
384 .RB ( it )
385 capability.
386 After that,
387 it can be altered by applications using SVr4
388 .IR curses "."
389 .bP
390 SVr4
391 .I curses
392 uses
393 .BR \%TABSIZE 's
394 value to compute the position of tab stops when updating both
395 the virtual screen with \fB\%addch\fP(3X) and
396 the physical screen with \fB\%mvcur\fP(3X).
397 .bP
398 In
399 .IR \%ncurses ","
400 .BR \%TABSIZE 's
401 value affects only the virtual screen.
402 The library uses the terminal type description's
403 .B \%init_tabs
404 .RB ( it )
405 capability to compute hardware tabs
406 (that is,
407 tab stops on the physical screen).
408 .bP
409 Other implementations differ.
410 For instance,
411 NetBSD
412 .I curses
413 allows
414 .B \%TABSIZE
415 to be set through an environment variable.
416 .I \%ncurses
417 does not.
418 .IP
419 NetBSD
420 .I curses
421 does not support hardware tabs;
422 it uses the
423 .B \%init_tabs
424 .RB ( it )
425 capability and the
426 .B \%TABSIZE
427 variable only to update the virtual screen.
428 .PP
429 .B \%ESCDELAY
430 is a feature of AIX
431 .IR curses "."
432 .bP
433 AIX treats
434 .BR \%ESCDELAY 's
435 value as counting
436 .I fifths
437 of milliseconds.
438 .bP
439 AIX's default
440 .B \%ESCDELAY
441 equals 0.1 seconds.
442 .bP
443 AIX also enforces a limit of 10,000 seconds for
444 .BR \%ESCDELAY ";"
445 .I \%ncurses
446 does not enforce an upper limit.
447 .PP
448 .I \%ncurses
449 has long interpreted
450 .B \%ESCDELAY
451 as a count of milliseconds,
452 making it impossible to be completely compatible with AIX.
453 Consequently,
454 most users have decided either to override the value,
455 or to rely upon its default.
456 .SH SEE ALSO
457 .UR https://\*:unicode\*:.org/\*:reports/\*:tr29/
458 [UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
459 Segmentation\*(''
460 .UE
461 .PP
462 \fB\%getcchar\fP(3X)
463 further discusses the
464 .I \%ncurses
465 extension
466 .BR \%CCHARW_MAX "."
467 .PP
468 \fB\%curses\fP(3X),
469 \fB\%curs_color\fP(3X),
470 \fB\%curs_opaque\fP(3X),
471 \fB\%curs_terminfo\fP(3X),
472 \fB\%curs_threads\fP(3X),
473 \fB\%term_variables\fP(3X),
474 \fB\%terminfo\fP(5)