.\"***************************************************************************
-.\" Copyright (c) 2010 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 2010-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_variables.3x,v 1.4 2010/12/04 18:38:55 tom Exp $
-.TH curs_variables 3X ""
+.\" $Id: curs_variables.3x,v 1.47 2024/04/13 22:37:35 tom Exp $
+.TH curs_variables 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
+.ie \n(.g .ds : \:
+.el .ds : \" empty
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
-.na
-.hy 0
+.
.SH NAME
-\fBCOLORS\fR,
-\fBCOLOR_PAIRS\fR,
-\fBCOLS\fR,
-\fBESCDELAY\fR,
-\fBLINES\fR,
-\fBTABSIZE\fR,
-\fBcurscr\fR,
-\fBnewscr\fR,
-\fBstdscr\fR
-\- \fBcurses\fR global variables
-.ad
-.hy
+\fI\%bool\fP,
+\fI\%chtype\fP,
+\fI\%cchar_t\fP,
+\fI\%attr_t\fP,
+\fI\%SCREEN\fP,
+\fI\%WINDOW\fP,
+\fB\%TRUE\fP,
+\fB\%FALSE\fP,
+\fB\%ERR\fP,
+\fB\%OK\fP,
+\fB\%curscr\fP,
+\fB\%newscr\fP,
+\fB\%stdscr\fP,
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLS\fP,
+\fB\%LINES\fP,
+\fB\%ESCDELAY\fP,
+\fB\%TABSIZE\fP \-
+\fIcurses\fR data types, constants, and global variables
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fR
-.PP
-\fBint COLOR_PAIRS;\fR
-.br
-\fBint COLORS;\fR
-.br
-\fBint COLS;\fR
-.br
-\fBint ESCDELAY;\fR
-.br
-\fBint LINES;\fR
-.br
-\fBint TABSIZE;\fR
-.br
-\fBWINDOW * curscr;\fR
-.br
-\fBWINDOW * newscr;\fR
-.br
-\fBWINDOW * stdscr;\fR
+\fB#include <curses.h>
+.PP
+\fI/* data types */
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN;
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;
+.PP
+\fI/* constants */
+\fBconst bool TRUE;
+\fBconst bool FALSE;
+.PP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;
+.PP
+\fI/* variables */
+\fBint COLORS;
+\fBint COLOR_PAIRS;
+\fBint COLS;
+\fBint LINES;
+\fBWINDOW * curscr;
+\fBWINDOW * stdscr;
+.PP
+\fI/* extensions */
+\fBint ESCDELAY;
+\fBint TABSIZE;
+\fBWINDOW * newscr;
.fi
.SH DESCRIPTION
-This page summarizes variables provided by the \fBcurses\fP library.
-A more complete description is given in the \fBcurses\fP(3X) manual page.
+This page summarizes data types,
+constants,
+and variables provided by the \fIcurses\fP library.
+Locate further discussion in \fB\%curses\fP(3X).
.PP
-Depending on the configuration, these may be actual variables,
-or macros (see \fBcurs_threads\fR(3X))
-which provide read-only access to \fIcurses\fP's state.
-In either case, applications should treat them as read-only to avoid
+Depending on \fI\%ncurses\fP's build-time configuration,
+the variables may instead be
+macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(3X))
+that provide read-only access to the library's state.
+In either case,
+applications should treat them as read-only to avoid
confusing the library.
-.SS COLOR_PAIRS
-After initializing curses, this variable contains the number of color pairs
-which the terminal can support.
-Usually the number of color pairs will be the product \fBCOLORS\fP*\fBCOLORS\fP,
-however this is not always true:
-.bP
-a few terminals use HLS colors, which do not follow this rule
-.bP
-terminals supporting a large number of colors are limited by the number
-of color pairs that can be represented in a \fIsigned short\fP value.
+.SH "CONSTANTS"
+.SS "TRUE, FALSE"
+The \fIcurses\fP library defines \fBTRUE\fP and \fBFALSE\fP
+to represent the values of the Boolean data type.
+.SS "ERR, OK"
+\fIcurses\fP and \fIterminfo\fP routines frequently return these
+constant integral values indicating failure and success,
+respectively.
+.SH "PREDEFINED TYPES"
+.SS "\fIbool\fP"
+X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
+standards,
+each of which also defined a Boolean data type.
+The \fIcurses\fP library requires an integral type \fIbool\fP.
+.PP
+\fB\%ncurses\fP' configure script attempts to discover the
+data type used by the system's C and C++ compilers,
+to reuse for the \fIcurses\fP \fIbool\fP.
+.SS "\fIchtype\fP"
+The \fI\%chtype\fP integral type combines a
+(\*(``narrow\*('',
+8-bit)
+character with attributes encoding the character's \fIrendition\fP,
+such as the styling of its typeface and/or foreground and background
+colors.
+See,
+for example,
+\fB\%addch\fP(3X),
+\fB\%attron\fP(3X),
+and
+\fB\%inch\fP(3X).
+.SS "\fIcchar_t\fP, \fIattr_t\fP"
+\fI\%chtype\fP is too small for the standard C library's wide-character
+type,
+\fIwchar_t\fP.
+\fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
+enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
+(a \*(``user-perceived character\*('' [UAX #29],
+which may nevertheless require several character encoding units to
+represent).
+\fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
+apply to \fI\%cchar_t\fPs.
+See,
+for example,
+\fB\%add_wch\fP(3X),
+\fB\%attr_on\fP(3X),
+and
+\fB\%in_wch\fP(3X).
+.SS "\fISCREEN\fP"
+.I curses
+manages a terminal device with this structure type;
+see \fB\%initscr\fP(3X).
+.SS "\fIWINDOW\fP"
+.I curses
+represents rectangular portions of the terminal screen with the
+.I \%WINDOW
+structure type;
+see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3X).
+.SH "VARIABLES"
+.SS "curscr, stdscr, newscr"
+The library records updates to the terminal screen in a window named
+\fB\%curscr\fP.
+This object is referred to as the \*(``physical screen\*('' in
+\fB\%curs_refresh\fP(3X) and
+\fB\%curs_outopts\fP(3X).
+.PP
+\fI\%ncurses\fP collects pending updates to the terminal screen in a
+window named \fB\%newscr\fP.
+This object is referred to as the \*(``virtual screen\*('' in the
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+and
+\fB\%curs_outopts\fP(3X).
+When the screen is refreshed,
+\fIcurses\fP determines a minimal set of updates using the terminal's
+capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
+.PP
+Once \fIcurses\fP is initialized,
+it creates a window named \fB\%stdscr\fP.
+It is the same size as the terminal screen and is the default window
+used by routines that do not take a parameter identifying one.
+Many \fIcurses\fP functions use this window.
.SS COLORS
-After initializing curses, this variable contains the number of colors
-which the terminal can support.
-.SS COLS
-After initializing curses, this variable contains the width of the screen,
-i.e., the number of columns.
+Once \fIcurses\fP is initialized,
+\fB\%COLORS\fP
+contains the number of colors supported by the terminal;
+see \fB\%curs_color\fP(3X).
+.SS COLOR_PAIRS
+Once \fIcurses\fP is initialized,
+\fB\%COLOR_PAIRS\fP
+contains the number of color pairs supported by the terminal;
+see \fB\%curs_color\fP(3X).
+.SS "COLS, LINES"
+Once \fIcurses\fP is initialized,
+.B \%COLS
+and
+.B LINES
+contain the screen's width and height in character cells,
+respectively;
+that is,
+the number of columns and lines.
.SS ESCDELAY
-This variable holds the number of milliseconds to wait after reading an
-escape character,
-to distinguish between an individual escape character entered on the
-keyboard from escape sequences sent by cursor- and function-keys
-(see curses(3X).
-.SS LINES
-After initializing curses, this variable contains the height of the screen,
-i.e., the number of lines.
+For
+.I curses
+to distinguish the ESC character resulting from a user's press of the
+\*(``Escape\*('' key on the input device from one beginning an
+.I "escape sequence"
+(as commonly produced by function keys),
+it waits after the escape character to see if further characters are
+available on the input stream within a short interval.
+.B \%ESCDELAY
+stores this interval in milliseconds.
+.PP
+If \fB\%keypad\fP(3X) is disabled for the
+.I curses
+window receiving input,
+a program must disambiguate escape sequences itself.
.SS TABSIZE
-This variable holds the number of columns used by the \fIcurses\fP library
-when converting a tab character to spaces as it adds the tab to a window
-(see curs_addch(3X).
-.SS The Current Screen
-This implementation of curses uses a special window \fBcurscr\fP to
-record its updates to the terminal screen.
-.SS The New Screen
-This implementation of curses uses a special window \fBnewscr\fP to
-hold updates to the terminal screen before applying them to \fBcurscr\fP.
-.SS The Standard Screen
-Upon initializing curses,
-a default window called \fBstdscr\fP,
-which is the size of the terminal screen, is created.
-Many curses functions use this window.
+The \fIcurses\fP library converts a tab character to this number of
+spaces as it adds a tab to a window;
+see \fB\%curs_addch\fP(3X).
.SH NOTES
-The curses library is initialized using either \fBinitscr\fR(3X),
-or \fBnewterm\fR(3X).
+Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
+\fIcurses\fP.
.PP
-If \fBcurses\fP is configured to use separate curses/terminfo libraries,
-most of these variables reside in the curses library.
+If
+.I \%ncurses
+is configured to provide separate
+.I curses
+and
+.I \%tinfo
+libraries,
+most of these variables reside in the former.
.SH PORTABILITY
-ESCDELAY and TABSIZE are extensions,
-not provided in most other implementations of curses.
+The X/Open Curses standard documents all of the foregoing types and
+symbols except for \fB\%newscr\fP,
+\fB\%TABSIZE\fP,
+and \fB\%ESCDELAY\fP.
+.PP
+X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data
+structure\*('';
+SVr4 gave more details,
+noting its use \*(``for certain low-level operations like clearing and
+redrawing a screen containing garbage\*(''.
+.\" SVID 4, Volume 3, p. 408
+Neither specified its interaction with the rest of the interface beyond
+use as an argument to \fB\%clearok\fP(3X) and \fB\%wrefresh\fP(3X).
+.PP
+\fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
+When refreshing the screen,
+it is used as a working area for combining the standard window
+\fB\%stdscr\fP with any others the application may have created with
+\fB\%newwin\fP(3X).
+When the update of \fB\%newscr\fP is complete,
+\fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP.
+.PP
+\fB\%TABSIZE\fP is a feature of SVr4 \fIcurses\fP.
+.bP
+SVr4 initially sets \fB\%TABSIZE\fP from the terminal description's
+\fB\%init_tabs\fP capability.
+After that,
+it can be altered by applications using SVr4 \fIcurses\fP.
+.bP
+SVr4 \fIcurses\fP uses the value of \fB\%TABSIZE\fP to compute the
+position of tab stops when updating both
+the virtual screen with \fB\%addch\fP(3X) and
+the physical screen with \fB\%mvcur\fP(3X).
+.bP
+\fI\%ncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
+virtual screen.
+It uses the terminal description's \*(``\fBit\fP\*(''
+(\fB\%init_tabs\fP) capability for computing hardware tabs
+(that is,
+tab stops on the physical screen).
+.bP
+Other implementations differ.
+For instance,
+NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
+environment variable.
+\fI\%ncurses\fP does not.
+.IP
+NetBSD \fIcurses\fP does not support hardware tabs;
+it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
+variable only for updating the virtual screen.
+.PP
+\fB\%ESCDELAY\fP is a feature of AIX \fIcurses\fP.
+.bP
+In AIX,
+the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds.
+.bP
+The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
+.bP
+AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
+\fI\%ncurses\fP does not enforce any upper limit.
+.PP
+\fI\%ncurses\fP has long used \fB\%ESCDELAY\fP with units of
+milliseconds,
+making it impossible to be completely compatible with AIX.
+Consequently,
+most users have decided either to override the value,
+or to rely upon its default.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_threads\fR(3X),
-\fBterm_variables\fR(3X),
-\fBterminfo\fR(3X),
-\fBterminfo\fR(\*n).
+\fB\%curses\fP(3X),
+\fB\%curs_color\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_threads\fP(3X),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(5)
+.PP
+[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
+Segmentation\*('';
+\%<https://\*:unicode\*:.org/\*:reports/\*:tr29/>
projects / ncurses.git / blobdiff