'\" t
.\"***************************************************************************
-.\" Copyright 2018-2021,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.192 2023/12/31 00:46:04 tom Exp $
-.TH ncurses 3X 2023-12-30 "ncurses 6.4" "Library calls"
+.\" $Id: ncurses.3x,v 1.204 2024/03/23 20:42:29 tom Exp $
+.TH ncurses 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB#include <curses.h>
.fi
.SH DESCRIPTION
-The \fI\%ncurses\fP library routines give the user a
-terminal-independent method of updating character screens with
-reasonable optimization.
-This implementation is \*(``new curses\*('' (\fI\%ncurses\fP) and
-is the approved replacement for
-4.4BSD classic curses, which has been discontinued.
+The \*(``new curses\*('' library offers the programmer a
+terminal-independent means of reading keyboard and mouse input and
+updating character-cell terminals with output optimized to minimize
+screen updates.
+.I \%ncurses
+replaces the
+.I curses
+libraries from
+System V Release 4 Unix (\*(``SVr4\*('')
+and
+4.4BSD Unix,
+the development of which ceased in the 1990s.
This describes \fI\%ncurses\fP
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.PP
-The \fI\%ncurses\fP library emulates the curses library of
-System V Release 4 Unix (\*(``SVr4\*(''),
-and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
-XSI stands for X/Open System Interfaces Extension.
-The \fI\%ncurses\fP library is freely redistributable in source form.
+.I \%ncurses
+permits control of the terminal screen's contents;
+abstraction and subdivision thereof with
+.I windows
+and
+.IR pads ;
+the reading of terminal input;
+control of terminal input and output options;
+environment query routines;
+color manipulation;
+the definition and use of
+.I "soft label"
+keys;
+.I \%term\%info
+capabilities;
+a
+.I \%term\%cap
+compatibility interface;
+and access to low-level terminal-manipulation routines.
+.PP
+.I \%ncurses
+implements the standard interface described by
+X/Open Curses Issue\ 7.
+In many behavioral details not standardized by X/Open,
+.I \%ncurses
+emulates the
+.I curses
+library of SVr4 and provides numerous useful extensions.
.PP
\fI\%ncurses\fP man pages employ several sections to clarify matters of
usage and interoperability with other \fIcurses\fP implementations.
(in a file called \*(``trace\*('' in the current directory)
that describe curses actions.
See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
-.PP
-The \fI\%ncurses\fP package supports: overall screen, window and pad
-manipulation; output to windows and pads; reading terminal input; control over
-terminal and \fBcurses\fP input and output options; environment query
-routines; color manipulation; use of soft label keys; terminfo capabilities;
-and access to low-level terminal-manipulation routines.
.SS Initialization
The library uses the locale which the calling program has initialized.
That is normally done with \fBsetlocale\fP(3):
the library assumes that characters are printable as in ISO\-8859\-1,
to work with certain legacy programs.
You should initialize the locale and not rely on specific details of
-the library when the locale has not been setup.
+the library when the locale has not been set up.
.PP
The function \fBinitscr\fP or \fBnewterm\fP
must be called to initialize the library
see below)
with \*(``w\*('';
these allow the user to specify a pointer to a
-.I \%WINDOW.
+.IR \%WINDOW .
Counterparts not thus prefixed
(or infixed)
affect \fB\%stdscr\fP.
.I "key codes."
See \fB\%getch\fP(3X).
.SS "Effects of GUIs and Environment Variables"
-The selection of an approprate value of
+The selection of an appropriate value of
.I TERM
in the process environment is essential to correct
.I curses
.I \%chtype
datum,
which is often an alias of
-.I int.
+.IR int .
.IP
Attributes alone
(with no corresponding character)
Each cell of a
.I \%WINDOW
is stored as a
-.I \%chtype.
+.IR \%chtype .
.TP 10
.I \%ncursesw
is the library in its \*(``wide\*('' configuration,
.TP 9 \" "cchar_t" + 2n
.I \%cchar_t
corresponds to the non-wide configuration's
-.I \%chtype.
+.IR \%chtype .
It always a structure type,
because it stores more data than fits into an integral type.
A character code may not be representable as a
-.I \%char,
+.IR \%char ,
and moreover more than one character may occupy a cell
(as with accent marks and other diacritics).
Each character is of type
-.I \%wchar_t;
+.IR \%wchar_t ;
a complex character contains one spacing character and zero or more
non-spacing characters
(see below).
Attributes and color data are stored in separate fields of the
structure,
not combined as in
-.I \%chtype.
+.IR \%chtype .
.PP
Each cell of a
.I \%WINDOW
is stored as a
-.I \%cchar_t.
+.IR \%cchar_t .
.PP
The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
functions store and retrieve the data from a
.I \%wchar_t
stores a wide character.
Like
-.I \%chtype,
+.IR \%chtype ,
it may be an alias of
-.I int.
+.IR int .
Depending on the character encoding,
a wide character may be
-.I spacing,
+.IR spacing ,
meaning that it occupies a character cell by itself and typically
accompanies cursor advancement,
or
-.I non-spacing,
+.IR non-spacing ,
meaning that it occupies the same cell as a spacing character,
is often regarded as a \*(``modifier\*('' of the base glyph with which
it combines,
The following environment symbols are useful for customizing the
runtime behavior of the \fI\%ncurses\fP library.
The most important ones have been already discussed in detail.
-.SS \fICC\fP command-character
+.SS "\fICC\fP (command character)"
When set,
change the
.B \%command_character
the C compiler's name,
\fI\%ncurses\fP ignores it if it does not happen to be a single
character.
-.SS \fIBAUDRATE\fP
+.SS "\fIBAUDRATE\fP"
The debugging library checks this environment variable when the application
has redirected output to a file.
-The variable's numeric value is used for the baudrate.
+The variable's numeric value is used for the baud rate.
If no value is found, \fI\%ncurses\fP uses 9600.
This allows testers to construct repeatable test-cases
-that take into account costs that depend on baudrate.
-.SS \fICOLUMNS\fP
+that take into account costs that depend on baud rate.
+.SS "\fICOLUMNS\fP"
Specify the width of the screen in characters.
Applications running in a windowing environment usually are able to
obtain the width of the window in which they are executing.
-If neither the \fI\%COLUMNS\fP value nor the terminal's screen size is available,
+If neither the \fI\%COLUMNS\fP value
+nor the terminal's screen size is available,
\fI\%ncurses\fP uses the size which may be specified in the terminfo
database
(i.e., the \fBcols\fP capability).
Use the \fBuse_tioctl\fP function to update \fI\%COLUMNS\fP or
\fILINES\fP to match the screen size obtained from system calls or the
terminal database.
-.SS \fIESCDELAY\fP
+.SS "\fIESCDELAY\fP"
Specifies the total time,
in milliseconds,
for which \fI\%ncurses\fP will await a character sequence,
in either form,
but setting the environment variable rather than the global variable
does not create problems when compiling an application.
-.SS \fIHOME\fP
+.SS "\fIHOME\fP"
Tells \fI\%ncurses\fP where your home directory is.
That is where it may read and write auxiliary terminal descriptions:
.PP
$HOME/.terminfo
.EE
.RE
-.SS \fILINES\fP
+.SS "\fILINES\fP"
Like \fI\%COLUMNS\fP, specify the height of the screen in characters.
See \fI\%COLUMNS\fP for a detailed description.
-.SS \fIMOUSE_BUTTONS_123\fP
+.SS "\fIMOUSE_BUTTONS_123\fP"
This applies only to the OS/2 EMX port.
It specifies the order of buttons on the mouse.
OS/2 numbers a 3-button mouse inconsistently from other
This variable lets you customize the mouse.
The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
If it is not specified, \fI\%ncurses\fP uses 132.
-.SS \fINCURSES_ASSUMED_COLORS\fP
+.SS "\fINCURSES_ASSUMED_COLORS\fP"
Override the compiled-in assumption that the
terminal's default colors are white-on-black
(see \fBdefault_colors\fP(3X)).
about the colors, set this to "\-1,\-1".
To make it green-on-black, set it to "2,0".
Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed.
-.SS \fINCURSES_CONSOLE2\fP
+.SS "\fINCURSES_CONSOLE2\fP"
This applies only to the MinGW port of \fI\%ncurses\fP.
.PP
The \fBConsole2\fP program's handling of the Microsoft Console API call
mapping coordinates,
explicitly saving and restoring the original screen contents.
Setting the environment variable \fBNCGDB\fP has the same effect.
-.SS \fINCURSES_GPM_TERMS\fP
+.SS "\fINCURSES_GPM_TERMS\fP"
This applies only to \fI\%ncurses\fP configured to use the GPM
interface.
.PP
If the environment variable is absent,
\fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains
\*(``linux\*(''.
-.SS \fINCURSES_NO_HARD_TABS\fP
+.SS "\fINCURSES_NO_HARD_TABS\fP"
\fI\%ncurses\fP may use tabs as part of cursor movement optimization.
In some cases,
your terminal driver may not handle these properly.
Set this environment variable to any value to disable the feature.
You can also adjust your \fBstty\fP(1) settings to avoid the problem.
-.SS \fINCURSES_NO_MAGIC_COOKIE\fP
+.SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
Some terminals use a magic-cookie feature which requires special handling
to make highlighting and other video attributes display properly.
You can suppress the highlighting entirely for these terminals by
setting this environment variable to any value.
-.SS \fINCURSES_NO_PADDING\fP
+.SS "\fINCURSES_NO_PADDING\fP"
Most of the terminal descriptions in the terminfo database are written
for real \*(``hardware\*('' terminals.
Many people use terminal emulators
to disable all but mandatory padding.
Mandatory padding is used as a part of special control
sequences such as \fBflash\fP.
-.SS \fINCURSES_NO_SETBUF\fP
+.SS "\fINCURSES_NO_SETBUF\fP"
This setting is obsolete.
Before changes
.RS 3
As a special case, the low-level calls such as \fBputp\fP still use the
standard output.
But high-level curses calls do not.
-.SS \fINCURSES_NO_UTF8_ACS\fP
+.SS "\fINCURSES_NO_UTF8_ACS\fP"
During initialization, the \fI\%ncurses\fP library
checks for special cases where VT100 line-drawing (and the corresponding
alternate character set capabilities) described in the terminfo are known
# VT100 shift\-in/shift\-out, with corresponding font.
linux\-vt100|linux console with VT100 line\-graphics,
U8#0, use=linux,
-
+\&
# uxterm with vt100Graphics resource set to false
xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
U8#1, use=xterm,
The name \*(``U8\*('' is chosen to be two characters,
to permit it to be used by applications that use \fI\%ncurses\fP'
termcap interface.
-.SS \fINCURSES_TRACE\fP
+.SS "\fINCURSES_TRACE\fP"
During initialization, the \fI\%ncurses\fP debugging library
checks the \fI\%NCURSES_TRACE\fP environment variable.
If it is defined,
file \fBtrace\fP to the current directory.
.PP
See \fBcurs_trace\fP(3X) for more information.
-.SS \fITERM\fP
+.SS "\fITERM\fP"
Denotes your terminal type.
Each terminal type is distinct, though many are similar.
.PP
terminal emulators which allow you to
specify \fITERM\fP as a parameter or configuration value do
not change their behavior to match that setting.
-.SS \fITERMCAP\fP
+.SS "\fITERMCAP\fP"
If the \fI\%ncurses\fP library has been configured with \fItermcap\fP
support, \fI\%ncurses\fP will check for a terminal's description in
termcap form if it is not available in the terminfo database.
the \fITERM\fP environment variable exists.
In either case, setting it directs \fI\%ncurses\fP to ignore
the usual place for this information, e.g., /etc/termcap.
-.SS \fITERMINFO\fP
+.SS "\fITERMINFO\fP"
\fI\%ncurses\fP can be configured to read from multiple terminal
databases.
The \fI\%TERMINFO\fP variable overrides the location for
@TERMINFO@ (corresponding to the \fITERMINFO\fP variable)
.RE
.RE
-.SS \fITERMINFO_DIRS\fP
+.SS "\fITERMINFO_DIRS\fP"
Specifies a list of locations to search for terminal descriptions.
Each location in the list is a terminal database as described in
the section on the \fI\%TERMINFO\fP variable.
.PP
There is no corresponding feature in System V terminfo;
it is an extension developed for \fI\%ncurses\fP.
-.SS \fITERMPATH\fP
+.SS "\fITERMPATH\fP"
If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks
the \fI\%TERMPATH\fP environment variable.
This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
option to peruse them all.
A few are of particular significance to the application developer
employing
-.I \%ncurses.
+.IR \%ncurses .
.TP 5
\-\-disable\-overwrite
The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
.I \%ncurses
enables an application to capture mouse events on certain terminals,
including
-.I \%xterm;
+.IR \%xterm ;
see \fB\%curs_mouse\fP(3X).
.PP
.I \%ncurses
provides a means of responding to window resizing events,
as when running in a GUI terminal emulator application such as
-.I \%xterm;
+.IR \%xterm ;
see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
.PP
.I \%ncurses
if the terminal setup code cannot find a
.I \%term\%info
entry corresponding to
-.I TERM.
+.IR TERM .
Use of this feature is not recommended,
as it essentially includes an entire
.I termcap
projects / ncurses.git / blobdiff