Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2016,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_color.3x,v 1.126 2025/08/23 22:39:20 tom Exp $
31 .TH color 3NCURSES 2025-08-23 "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 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .
48 .SH NAME
49 \fB\%start_color\fP,
50 \fB\%has_colors\fP,
51 \fB\%can_change_color\fP,
52 \fB\%init_pair\fP,
53 \fB\%init_color\fP,
54 \fB\%init_extended_pair\fP,
55 \fB\%init_extended_color\fP,
56 \fB\%color_content\fP,
57 \fB\%pair_content\fP,
58 \fB\%extended_color_content\fP,
59 \fB\%extended_pair_content\fP,
60 \fB\%reset_color_pairs\fP,
61 \fB\%COLOR_PAIR\fP,
62 \fB\%PAIR_NUMBER\fP,
63 \fB\%COLORS\fP,
64 \fB\%COLOR_PAIRS\fP,
65 \fB\%COLOR_BLACK\fP,
66 \fB\%COLOR_RED\fP,
67 \fB\%COLOR_GREEN\fP,
68 \fB\%COLOR_YELLOW\fP,
69 \fB\%COLOR_BLUE\fP,
70 \fB\%COLOR_MAGENTA\fP,
71 \fB\%COLOR_CYAN\fP,
72 \fB\%COLOR_WHITE\fP,
73 \fB\%A_COLOR\fP \-
74 manipulate terminal colors with \fIcurses\fR
75 .SH SYNOPSIS
76 .nf
77 \fB#include <curses.h>
78 .PP
79 \fI/* variables */
80 \fBint COLOR_PAIRS;
81 \fBint COLORS;
82 .PP
83 \fBint start_color(void);
84 .PP
85 \fBbool has_colors(void);
86 \fBbool can_change_color(void);
87 .PP
88 \fBint init_pair(short \fIpair\fP, short \fIf\fP, short \fIb\fP);
89 \fBint init_color(short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
90 \fI/* extensions */
91 \fBint init_extended_pair(int \fIpair\fP, int \fIf\fP, int \fIb\fP);
92 \fBint init_extended_color(int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
93 .PP
94 \fBint color_content(short \fIcolor\fP, short *\fIr\fP, short *\fIg\fP, short *\fIb\fP);
95 \fBint pair_content(short \fIpair\fP, short *\fIf\fP, short *\fIb\fP);
96 \fI/* extensions */
97 \fBint extended_color_content(int \fIcolor\fP, int *\fIr\fP, int *\fIg\fP, int *\fIb\fP);
98 \fBint extended_pair_content(int \fIpair\fP, int *\fIf\fP, int *\fIb\fP);
99 .PP
100 \fI/* extension */
101 \fBvoid reset_color_pairs(void);
102 .PP
103 \fI/* macros */
104 \fBint COLOR_PAIR(int \fIn\fP);
105 \fBPAIR_NUMBER(int \fIattr\fP);
106 \fBCOLOR_BLACK
107 \fBCOLOR_RED
108 \fBCOLOR_GREEN
109 \fBCOLOR_YELLOW
110 \fBCOLOR_BLUE
111 \fBCOLOR_MAGENTA
112 \fBCOLOR_CYAN
113 \fBCOLOR_WHITE
114 \fBA_COLOR
115 .fi
116 .SH DESCRIPTION
117 .SS Overview
118 \fIcurses\fP supports color attributes on terminals with that
119 capability.
120 Call \fB\%start_color\fP
121 (typically right after \fB\%initscr\fP(3NCURSES))
122 to enable this feature.
123 Colors are always used in pairs.
124 A
125 .I "color pair"
126 couples a foreground color for characters with a background color for
127 the blank field on which characters are rendered.
128 \fB\%init_pair\fP initializes a color pair.
129 The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a
130 video attribute.
131 .PP
132 If a terminal has the relevant capability,
133 \fB\%init_color\fP permits (re)definition of a color.
134 \fB\%has_colors\fP and \fB\%can_change_color\fP
135 return \fBTRUE\fP or \fBFALSE\fP,
136 depending on whether the terminal has color capability and whether the
137 programmer can change the colors.
138 \fB\%color_content\fP permits extraction of the
139 red,
140 green,
141 and blue components of an initialized color.
142 \fB\%pair_content\fP permits discovery of a color pair's current
143 definition.
144 .SS Rendering
145 .I curses
146 combines the following data to render a character cell.
147 Any of them can include color information.
148 .bP
149 .I curses
150 character attributes,
151 as from \fB\%waddch\fP(3NCURSES) or \fB\%wadd_wch\fP(3NCURSES)
152 .bP
153 window attributes,
154 as from \fB\%wattrset\fP(3NCURSES) or \fB\%wattr_set\fP(3NCURSES)
155 .bP
156 window background character attributes,
157 as from \fB\%wbkgdset\fP(3NCURSES) or \fB\%wbkgrndset\fP(3NCURSES)
158 .PP
159 Per-character and window attributes are usually set through a function
160 parameter containing attributes including a color pair value.
161 Some functions,
162 such as \fB\%wattr_set\fP,
163 use a separate color pair number parameter.
164 .PP
165 The background character is a special case:
166 it includes a character code,
167 just as if it were passed to \fB\%waddch\fP.
168 .PP
169 The \fIcurses\fP library does the actual work of combining these color
170 pairs in an internal function called from \fB\%waddch\fP:
171 .bP
172 If the parameter passed to \fB\%waddch\fP is \fIblank\fP,
173 and it uses the special color pair 0,
174 \fIcurses\fP next checks the window attribute.
175 .RS
176 .bP
177 If the window attribute does not use color pair 0,
178 \fIcurses\fP uses the color pair from the window attribute.
179 .bP
180 Otherwise, \fIcurses\fP uses the background character.
181 .RE
182 .bP
183 If the parameter passed to \fB\%waddch\fP is \fInot blank\fP,
184 or it does not use the special color pair 0,
185 \fIcurses\fP prefers the color pair from the parameter,
186 if it is nonzero.
187 Otherwise, it tries the window attribute next, and finally the
188 background character.
189 .PP
190 Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP.
191 Those do not combine its parameter with a color pair.
192 Consequently those calls use only the window attribute or
193 the background character.
194 .SH CONSTANTS
195 ISO\ 6429 and ECMA-48
196 define eight standard colors
197 (also known as \*(``ANSI\*('' colors).
198 .I curses\.h
199 defines object-like macros
200 .BR \%COLOR_BLACK ","
201 .BR \%COLOR_RED ","
202 .BR \%COLOR_GREEN ","
203 .BR \%COLOR_YELLOW ","
204 .BR \%COLOR_BLUE ","
205 .BR \%COLOR_MAGENTA ","
206 .BR \%COLOR_CYAN ","
207 and
208 .B \%COLOR_WHITE
209 accordingly.
210 .I curses
211 assumes that
212 .B \%COLOR_BLACK
213 is the default background color for all terminals.
214 .I \%ncurses
215 offers an extension to override that assumption;
216 see \fB\%assume_default_colors\fP(3NCURSES).
217 Some terminals support additional colors that lack standard names.
218 .PP
219 .B \%A_COLOR
220 is a bit mask that,
221 when bitwise \*(``and\*(''-ed with a
222 .IR \%chtype ","
223 .\" XXX: and right-shifted by...?
224 extracts its color pair identifier.
225 .SH VARIABLES
226 .SS COLORS
227 is initialized by \fB\%start_color\fP to the maximum number of colors
228 the terminal can support.
229 .SS COLOR_PAIRS
230 is initialized by \fB\%start_color\fP to the maximum number of color
231 pairs the terminal can support.
232 Often,
233 its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
234 but this is not always true.
235 .bP
236 A few terminals use the HLS color space
237 (see \fB\%start_color\fP below),
238 ignoring this rule;
239 and
240 .bP
241 terminals supporting a large number of colors are limited to the number
242 of color pairs that a
243 .I "signed short"
244 value can represent.
245 .SH FUNCTIONS
246 .SS start_color
247 The \fB\%start_color\fP routine requires no arguments.
248 It must be called if the programmer wants to use colors, and before any other
249 color manipulation routine is called.
250 It is good practice to call this routine right after \fB\%initscr\fP.
251 \fB\%start_color\fP does this:
252 .bP
253 It initializes two global variables, \fB\%COLORS\fP and
254 \fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
255 and color pairs the terminal can support).
256 .bP
257 It initializes the special color pair \fB\%0\fP to the default foreground
258 and background colors.
259 No other color pairs are initialized.
260 .bP
261 It restores the colors on the terminal to the values
262 they had when the terminal was just turned on.
263 .bP
264 If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability,
265 \fB\%start_color\fP
266 initializes its internal table representing the
267 red, green, and blue components of the color palette.
268 .IP
269 The components depend on whether the terminal uses
270 CGA (aka \*(``ANSI\*('') or
271 HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set).
272 The table is initialized first for eight basic colors
273 (black, red, green, yellow, blue, magenta, cyan, and white),
274 using weights that depend upon the CGA/HLS choice.
275 For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
276 depending on whether the corresponding
277 red, green, or blue component is used or not.
278 That permits using \fB1000\fP to represent bold/bright colors.
279 After the initial eight colors
280 (if the terminal supports more than eight colors)
281 the components are initialized using the same pattern,
282 but with weights of \fB1000\fP.
283 SVr4 uses a similar scheme, but uses \fB1000\fP
284 for the components of the initial eight colors.
285 .IP
286 \fB\%start_color\fP does not attempt to set the terminal's color palette
287 to match its built-in table.
288 An application may use \fB\%init_color\fP to alter the internal table
289 along with the terminal's color.
290 .PP
291 These limits apply to color values and color pairs.
292 Values outside these limits are not valid, and may result in a runtime error:
293 .bP
294 \fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability,
295 (see \fB\%terminfo\fP(5)).
296 .bP
297 color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP,
298 inclusive (including \fB0\fP and \fB\%COLORS\-1\fP).
299 .bP
300 a special color value \fB\-1\fP is used in certain extended functions
301 to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3NCURSES)).
302 .bP
303 \fB\%COLOR_PAIRS\fP corresponds to
304 the terminal database's \fB\%max_pairs\fP capability,
305 (see \fB\%terminfo\fP(5)).
306 .bP
307 valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
308 inclusive.
309 .bP
310 color pair \fB0\fP is special; it denotes \*(``no color\*(''.
311 .IP
312 Color pair \fB0\fP is assumed to be white on black,
313 but is actually whatever the terminal implements before color is initialized.
314 It cannot be modified by the application.
315 .SS has_colors
316 .B \%has_colors
317 returns
318 .B TRUE
319 if the terminal supports colors and
320 .B FALSE
321 if it does not.
322 \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES) must be called first,
323 but
324 .B \%start_color
325 need not be.
326 An application might call
327 .B \%has_colors
328 to decide whether to use color
329 or a video attribute like
330 .B \%A_BOLD
331 to render text.
332 .PP
333 Color support in
334 .I curses
335 requires that the terminal type description
336 support the capabilities
337 .B \%max_colors
338 .RB \%( colors ),
339 .B \%max_pairs
340 .RB \%( pairs ),
341 and any of
342 .bP
343 .B \%set_foreground
344 .RB ( setf )
345 and
346 .B \%set_background
347 .RB ( setb );
348 .bP
349 .B \%set_a_foreground
350 .RB ( setaf )
351 and
352 .B \%set_a_background
353 .RB ( setab );
354 or
355 .bP
356 .B \%set_color_pair
357 .RB ( scp ).
358 .SS can_change_color
359 The \fB\%can_change_color\fP routine requires no arguments.
360 It returns \fBTRUE\fP if the terminal supports colors
361 and can change their definitions;
362 other, it returns \fBFALSE\fP.
363 This routine facilitates writing terminal-independent programs.
364 .SS init_pair
365 The \fB\%init_pair\fP routine changes the definition of a color pair.
366 It takes three arguments:
367 the number of the color pair to be changed, the foreground
368 color number, and the background color number.
369 For portable applications:
370 .bP
371 The first argument must be a valid color pair value.
372 If default colors are used (see \fB\%use_default_colors\fP(3NCURSES))
373 the upper limit is adjusted to allow for extra pairs which use
374 a default color in foreground and/or background.
375 .bP
376 The second and third arguments must be valid color values.
377 .PP
378 If the color pair was previously initialized,
379 the screen is refreshed and all occurrences of that color pair
380 are changed to the new definition.
381 .PP
382 As an extension,
383 \fI\%ncurses\fP allows you to set color pair \fB0\fP via the
384 \fB\%assume_default_colors\fP(3NCURSES) routine, or to specify the use of
385 default colors (color number \fB\-1\fP) if you first invoke the
386 \fB\%use_default_colors\fP(3NCURSES) routine.
387 .SS init_extended_pair
388 Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
389 that limits color pairs and color-values
390 to 32767 on modern hardware.
391 The extension \fB\%init_extended_pair\fP uses \fBint\fPs
392 for the color pair and color-value,
393 allowing a larger number of colors to be supported.
394 .SS init_color
395 The \fB\%init_color\fP routine changes the definition of a color.
396 It takes four arguments:
397 the number of the color to be changed followed by three RGB values
398 (for the amounts of red, green, and blue components).
399 .bP
400 The first argument must be a valid color value;
401 default colors are not allowed here.
402 (See the section \fB\%Colors\fP for the default color index.)
403 .bP
404 Each of the last three arguments
405 must be a value in the range \fB0\fP through \fB1000\fP.
406 .PP
407 When \fB\%init_color\fP is used, all
408 occurrences of that color on the screen immediately change to the new
409 definition.
410 .SS init_extended_color
411 Because \fB\%init_color\fP uses signed \fBshort\fPs for its parameters,
412 that limits color-values and their red, green, and blue components
413 to 32767 on modern hardware.
414 The extension \fB\%init_extended_color\fP uses \fBint\fPs
415 for the color value and
416 for setting the red, green, and blue components,
417 allowing a larger number of colors to be supported.
418 .SS color_content
419 The \fB\%color_content\fP routine gives programmers a way to find the intensity
420 of the red, green, and blue (RGB) components in a color.
421 It requires four arguments: the color number, and three addresses
422 of \fBshort\fRs for storing
423 the information about the amounts of red, green, and blue components in the
424 given color.
425 .bP
426 The first argument must be a valid color value, i.e.,
427 \fB0\fP through \fB\%COLORS\-1\fP, inclusive.
428 .bP
429 The values that are stored at the addresses pointed to by the
430 last three arguments are in the range
431 \fB0\fP (no component) through \fB1000\fP
432 (maximum amount of component), inclusive.
433 .SS extended_color_content
434 Because \fB\%color_content\fP uses signed \fBshort\fPs for its parameters,
435 that limits color-values and their red, green, and blue components
436 to 32767 on modern hardware.
437 The extension \fB\%extended_color_content\fP uses \fBint\fPs
438 for the color value and
439 for returning the red, green, and blue components,
440 allowing a larger number of colors to be supported.
441 .SS pair_content
442 The \fB\%pair_content\fP routine allows programmers to find out what colors a
443 given color pair consists of.
444 It requires three arguments: the color pair
445 number, and two addresses of \fBshort\fRs for storing the foreground and the
446 background color numbers.
447 .bP
448 The first argument must be a valid color value,
449 i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive.
450 .bP
451 The values that are stored at the addresses pointed
452 to by the second and third arguments are in the
453 range \fB0\fP through \fB\%COLORS\fP, inclusive.
454 .SS extended_pair_content
455 Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
456 that limits color pair and color-values to 32767 on modern hardware.
457 The extension \fB\%extended_pair_content\fP uses \fBint\fPs
458 for the color pair and
459 for returning the foreground and background colors,
460 allowing a larger number of colors to be supported.
461 .SS reset_color_pairs
462 The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
463 all of the color pair information which was set with \fB\%init_pair\fP.
464 It also touches the current- and standard-screens, allowing an application to
465 switch color palettes rapidly.
466 .SS COLOR_PAIR
467 \fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an
468 attribute.
469 Attributes can hold color pairs in the range 0 to 255.
470 If you need a color pair larger than that,
471 you must use functions such as \fB\%attr_set\fP
472 (which pass the color pair as a separate parameter)
473 rather than the legacy functions such as \fB\%attrset\fP.
474 .SS PAIR_NUMBER
475 \fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
476 \fIattr\fP parameter and returns it as a color pair number;
477 it is the inverse operation of \fB\%COLOR_PAIR\fP.
478 .SH RETURN VALUE
479 .B \%can_change_color
480 and
481 .B \%has_colors
482 return
483 .B TRUE
484 or
485 .BR FALSE "."
486 The other functions return
487 .B OK
488 on success and
489 .B ERR
490 on failure.
491 .PP
492 In
493 .IR \%ncurses ","
494 functions returning an
495 .I int
496 recognize several error conditions.
497 .bP
498 All return
499 .B ERR
500 if the screen has not been initialized;
501 see \fBinitscr\fP(3NCURSES) or \fBnewterm\fP(3NCURSES).
502 .bP
503 All except
504 .B \%start_color
505 return
506 .B ERR
507 if
508 .B \%start_color
509 has not been called,
510 or itself returned
511 .BR ERR "."
512 .bP
513 .B \%start_color
514 returns
515 .B ERR
516 if it cannot allocate memory for its color pair table.
517 .bP
518 .B \%init_color
519 returns
520 .B ERR
521 if the terminal type does not support assignable color values;
522 that is,
523 if the
524 .B \%initialize_color
525 .RB ( initc )
526 capability is absent from its description.
527 .bP
528 .B \%init_color
529 returns
530 .B ERR
531 if any of its
532 .IR r ","
533 .IR g ","
534 .I b
535 arguments is outside the range 0-1000 inclusive.
536 .bP
537 .BR \%init_pair ","
538 .BR \%init_color ","
539 .BR \%init_extended_pair ","
540 .BR \%init_extended_color ","
541 .BR \%color_content ","
542 .BR \%pair_content ","
543 .BR \%extended_color_content ","
544 and
545 .B \%extended_pair_content
546 return
547 .B ERR
548 on attempts to use
549 .RS
550 .bP
551 color identifiers outside the range
552 .RB \%0- COLORS \-1
553 inclusive,
554 the default colors extension notwithstanding,
555 or
556 .bP
557 color pair identifiers outside the range
558 .RB \%0- COLOR_PAIRS \-1
559 inclusive.
560 .RE
561 .SH NOTES
562 In
563 .IR \%ncurses ","
564 .B \%init_pair
565 accepts negative foreground and background color arguments
566 to support its \fB\%use_default_colors\fP(3NCURSES) extension,
567 but only after the latter function has been called.
568 .PP
569 The assumption that
570 .B \%COLOR_BLACK
571 is the terminal's default background color can be overridden using
572 .IR \%ncurses 's
573 \fB\%assume_default_colors\fP(3NCURSES) extension.
574 .PP
575 In
576 .IR \%ncurses ","
577 each pointer passed to
578 .B \%color_content
579 and
580 .B \%pair_content
581 can be null,
582 in which case the library ignores it,
583 permitting the application to disregard unnecessary information.
584 .PP
585 In
586 .IR \%ncurses ","
587 each screen has a
588 color activation flag,
589 color palette,
590 color pair table,
591 and associated
592 .B \%COLORS
593 and
594 .B \%COLOR_PAIRS
595 values;
596 .B \%start_color
597 affects only the current screen.
598 The SVr4 and X/Open Curses interface was not really designed
599 with this in mind;
600 historical implementations may use a single shared color palette.
601 .PP
602 Setting an implicit background color via a color pair affects only
603 character cells that a character write operation explicitly touches.
604 To change the background color used
605 when parts of a window are blanked by erasing or scrolling operations,
606 see \fB\%bkgd\fP(3NCURSES).
607 .PP
608 Several caveats apply to IBM PC-compatible machines
609 of the 80486 era and earlier
610 with CGA/EGA/VGA video.
611 .bP
612 .B \%COLOR_YELLOW
613 was frequently converted,
614 in the analog domain,
615 to a shade of brown if the intensity bit was not set.
616 .\" https://nerdlypleasures.blogspot.com/2023/03/the-saga-of-color-brown-in-early-years.html
617 To get yellow on such devices,
618 one would combine
619 .B \%COLOR_YELLOW
620 with the
621 .B \%A_BOLD
622 attribute.
623 .bP
624 The
625 .B \%A_BLINK
626 attribute should in theory make the background bright.
627 This often fails to work,
628 and even VGA controllers for which it mostly works,
629 such as those from Paradise and compatibles,
630 do the wrong thing
631 when you try to set a bright \*(``yellow\*('' background \(em
632 you get a blinking yellow foreground instead.
633 .bP
634 Color RGB values are not configurable on these devices
635 (in text mode).
636 .SH EXTENSIONS
637 The functions marked as extensions originated in
638 .IR \%ncurses ","
639 and are not found in SVr4
640 .IR curses ,
641 4.4BSD
642 .IR curses ,
643 or any other previous
644 .I curses
645 implementation.
646 .SH PORTABILITY
647 Applications employing
648 .I \%ncurses
649 extensions should condition their use on the visibility of the
650 .B \%NCURSES_VERSION
651 preprocessor macro.
652 .PP
653 X/Open Curses Issue\ 4 describes these functions.
654 It specifies no error conditions for them.
655 .PP
656 .I \%ncurses
657 satisfies X/Open Curses's minimum maximums for
658 .I \%COLORS
659 and
660 .IR \%COLOR_PAIRS "."
661 .PP
662 X/Open Curses does not specify a limit for the number of colors and
663 color pairs which a terminal can support.
664 However,
665 in its use of
666 .I short
667 for the parameters,
668 it carries over SVr4's implementation detail for the compiled
669 .I \%term\%info
670 database,
671 which uses signed 16-bit numbers.
672 .I \%ncurses
673 provides extended versions of the functions using
674 .I short
675 parameters,
676 allowing applications to use larger color and pair identifiers.
677 .PP
678 SVr4
679 .I curses
680 returns
681 .I ERR
682 from
683 .I \%pair_content
684 if its
685 .I pair
686 argument
687 was not initialized using
688 .IR \%init_pairs ,
689 and from
690 .I \%color_content
691 if the terminal does not support changing colors.
692 .I \%ncurses
693 does neither.
694 .SH HISTORY
695 SVr3.2 (1987) introduced color support to
696 .I curses
697 with all of the symbols
698 in the synopsis above except those marked as extensions.
699 It reserved color pair 0 as the terminal's initial,
700 \*(``uncolored\*('' state,
701 .\" "we assume that color 0 is always a default background.", SVr3.2
702 .\" usr/src/lib/libcurses/screen/start_col.c
703 and limited the number of possible color pairs to 64,
704 because the color pair datum was encoded in six bits of a
705 .IR \%chtype "."
706 .PP
707 SVr4 made only internal changes,
708 such as moving the storage of color state
709 from the
710 .I SCREEN
711 structure
712 (pointed to by
713 .IR SP )
714 to the
715 .I \%TERMINAL
716 structure
717 (pointed to by
718 .IR \%cur_term ")."
719 .PP
720 Other
721 .I curses
722 implementations impose different limits on the number of colors and
723 color pairs.
724 .bP
725 .I \%PCCurses
726 (1987-1990) provided for only 8 colors
727 (and therefore required at most 8\(mu8 = 64 color pairs).
728 .bP
729 .I \%PDCurses
730 (1992-present) inherited the 8-color limitation from
731 .IR \%PCCurses ,
732 but changed this to 256 in version 2.5 (2001),
733 and widened its
734 .I \%chtype
735 from 16 to 32 bits.
736 .bP
737 X/Open Curses (1992-present)
738 specified a new structure type,
739 .IR \%cchar_t ","
740 to store the character code,
741 attribute flags,
742 and color pair identifier,
743 allowing an increased range of color pairs.
744 It specifies a
745 .I short
746 as storing identifiers for colors and color pairs,
747 limiting portable values to 15 bits;
748 negative values are invalid in System\ V.
749 .bP
750 .I \%ncurses
751 (1992-present),
752 in its non-wide-character configuration,
753 uses 8 bits of
754 .I \%chtype
755 for the color pair identifier.
756 .IP
757 Version 5.3 (2002) offered a wide-character interface,
758 but encoded the color pair identifier with attributes
759 in the character type.
760 .IP
761 Since version 6 (2015),
762 .I \%ncurses
763 uses a separate
764 .I int
765 for the color pair identifier in a
766 .IR \%cchar_t ","
767 introducing extension functions to manage the wider type.
768 When a color pair value fits in 8 bits,
769 .I \%ncurses
770 permits color pair data to be manipulated
771 via the functions taking
772 .I \%chtype
773 arguments,
774 even when a
775 .I curses
776 window uses wide-character cells.
777 .bP
778 NetBSD
779 .I curses
780 used 6 bits for the color pair identifier from 2000
781 (when it first added color support)
782 until 2004.
783 At that point,
784 NetBSD widened the color pair identifier to use 9 bits.
785 As of 2025,
786 that size is unchanged.
787 .\" http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libcurses/curses.h?rev=1.133
788 .\" indicates a mask of 0x03fe0000.
789 Like
790 .I \%ncurses
791 before version 6,
792 the NetBSD color pair datum is stored in
793 the attributes field of
794 .IR \%cchar_t ","
795 limiting the number of color pairs.
796 .SH SEE ALSO
797 \fB\%ncurses\fP(3NCURSES),
798 \fB\%attr\fP(3NCURSES),
799 \fB\%initscr\fP(3NCURSES),
800 \fB\%curses_variables\fP(3NCURSES),
801 \fB\%default_colors\fP(3NCURSES)