.\"*************************************************************************** .\" Copyright 2019-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 * .\" "Software"), to deal in the Software without restriction, including * .\" without limitation the rights to use, copy, modify, merge, publish, * .\" distribute, distribute with modifications, sublicense, and/or sell * .\" copies of the Software, and to permit persons to whom the Software is * .\" furnished to do so, subject to the following conditions: * .\" * .\" The above copyright notice and this permission notice shall be included * .\" in all copies or substantial portions of the Software. * .\" * .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * .\" * .\" Except as contained in this notice, the name(s) of the above copyright * .\" holders shall not be used in advertising or otherwise to promote the * .\" sale, use or other dealings in this Software without prior written * .\" authorization. * .\"*************************************************************************** .\" .\" $Id: term_variables.3x,v 1.40 2024/12/28 21:35:10 tom Exp $ .TH term_variables 3X 2024-12-28 "ncurses 6.5" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq .\} .el \{\ .ie t .ds `` `` .el .ds `` "" .ie t .ds '' '' .el .ds '' "" .\} . .SH NAME \fB\%SP\fP, \fB\%acs_map\fP, \fB\%boolcodes\fP, \fB\%boolfnames\fP, \fB\%boolnames\fP, \fB\%cur_term\fP, \fB\%numcodes\fP, \fB\%numfnames\fP, \fB\%numnames\fP, \fB\%strcodes\fP, \fB\%strfnames\fP, \fB\%strnames\fP, \fB\%ttytype\fP \- \fIterminfo\fR global variables .SH SYNOPSIS .nf \fB#include \fB#include .PP \fBchtype acs_map[]; .PP \fBSCREEN * SP; .PP \fBTERMINAL * cur_term; .PP \fBchar ttytype[]; .PP \fBNCURSES_CONST char * const boolcodes[]; \fBNCURSES_CONST char * const boolfnames[]; \fBNCURSES_CONST char * const boolnames[]; .PP \fBNCURSES_CONST char * const numcodes[]; \fBNCURSES_CONST char * const numfnames[]; \fBNCURSES_CONST char * const numnames[]; .PP \fBNCURSES_CONST char * const strcodes[]; \fBNCURSES_CONST char * const strfnames[]; \fBNCURSES_CONST char * const strnames[]; .fi .SH DESCRIPTION This page summarizes variables provided by the .I curses library's lower-level .I \%term\%info interface. Locate a more complete description in the \fBcurs_terminfo\fP(3X) manual page. .PP Depending on .IR \%ncurses 's build-time configuration, these may be actual variables, or macros (see \fBcurs_threads\fP(3X)) that provide read-only access to .IR curses 's state. In either case, applications should treat them as read-only to avoid confusing the library. .SS "Alternate Character Set Mapping" After initializing the .I curses or .I \%term\%info interfaces, the .B acs_map array holds information used to translate cells with the .B \%A_ALTCHARSET video attribute into line-drawing characters. .PP The encoding of the information in this array has changed periodically. Application developers need only know that it is used for the \*(``ACS_\*('' constants in .IR \%curses.h "." .PP The comparable data for the wide-character library are not exposed as symbols in the API. .SS "Current Terminal Data" After initializing the .I curses or .I \%term\%info interfaces, .B cur_term contains data describing the current terminal. It is also updated as a side-effect of \fBset_term\fP(3X) and \fBdelscreen\fP(3X). .PP It is possible to save a value of .B cur_term for subsequent use as a parameter to \fBset_term\fP(3X) for switching between screens. Alternatively, one can save the return value from \fBnewterm\fP(3X) or \fBsetupterm\fP(3X) to reuse in \fBset_term\fP(3X). .SS "\fIterminfo\fP Lookup Tables" The \fBtic\fP(1) and \fBinfocmp\fP(1) programs use lookup tables for the long and short names of .I \%term\%info capabilities, as well as the corresponding names for .I termcap capabilities. These are available to other applications, though the hash tables used by the .I \%term\%info and .I termcap functions are not. .PP .I \%term\%info stores capability names in arrays with an \*(``f\*('' (eff) in their names: .BR \%boolfnames "," .BR \%numfnames "," and .BR \%strfnames "." It stores the briefer capability codes in arrays without the \*(``f\*('': .BR \%boolnames "," .BR \%numnames "," and .BR \%strnames "." The corresponding .I termcap capability codes are stored in .BR \%boolcodes "," .BR \%numcodes "," and .BR \%strcodes "." \fB\%terminfo\fP(5) catalogs these. .\" .SS "Terminal Type" A terminal description begins with one or more terminal names separated by \*(``|\*('' (vertical bars). On initialization of the .I curses or .I \%term\%info interfaces, \fBsetupterm\fP(3X) copies the terminal name to the array .BR ttytype "." .\" .SS "\fIterminfo\fP Names" In addition to the variables, .I term.h also defines a symbol for each .I \%term\%info capability name. These are in terms of the symbol .BR CUR "," which is defined .PP .RS .EX #define CUR ((TERMTYPE *)(cur_term))\-> .EE .RE .PP These symbols provide a faster method of accessing .I \%term\%info capabilities than using, for example, \fBtigetstr\fP(3X). .PP The definition of .B CUR is implementation-dependent, but each .I \%term\%info library defines these names to point into the in-memory description of the current terminal. For example, in .IR \%ncurses "," the expressions .B tigetstr("key_dc") and \*(``\c \" `` string not reliable in a macro call on DWB/Heirloom nroffs .B "CUR Strings[59]\c" \*('' \" '' string not reliable in a macro call on DWB/Heirloom nroffs are equivalent. .\" .SS "\fIterminfo\fP and \fIcurses" \fB\%setupterm\fP(3X) initializes the lower-level .I \%term\%info interface. The higher-level .I curses interface uses the .I \%term\%info interface internally; the symbol .B SP bridges the .I curses .I SCREEN type with the .I \%term\%info .I TERMINAL type. .\" .SH PORTABILITY X/Open Curses does not describe any of these symbols except for .IR \%cur_term "." (The inclusion of .I \%cur_term appears to be an oversight, since other comparable low-level information is omitted by X/Open.) .PP Other implementations may have comparable variables. Some implementations provide the variables in their libraries, but omit them from the header files. .PP All implementations that provide .I \%term\%info interfaces add definitions as described in the .RI \*(`` terminfo Names\*('' section above. Most, but not all, base the definition upon the .I \%cur_term variable. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_terminfo\fP(3X), \fB\%curs_threads\fP(3X), \fB\%terminfo\fP(5)