vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
1223 lines
28 KiB
Plaintext
1223 lines
28 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright 2018-2024,2025 Thomas E. Dickey *
|
|
.\" Copyright 1998-2016,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: curs_terminfo.3x,v 1.176 2025/11/12 01:06:36 tom Exp $
|
|
.TH curs_terminfo 3X 2025-11-11 "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 '' ""
|
|
.\}
|
|
.
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.
|
|
.SH NAME
|
|
\fB\%del_curterm\fP,
|
|
\fB\%putp\fP,
|
|
\fB\%restartterm\fP,
|
|
\fB\%set_curterm\fP,
|
|
\fB\%setupterm\fP,
|
|
\fB\%tigetflag\fP,
|
|
\fB\%tigetnum\fP,
|
|
\fB\%tigetstr\fP,
|
|
\fB\%tiparm\fP,
|
|
\fB\%tiparm_s\fP,
|
|
\fB\%tiscan_s\fP,
|
|
\fB\%tparm\fP,
|
|
\fB\%tputs\fP,
|
|
\fB\%vid_attr\fP,
|
|
\fB\%vid_puts\fP,
|
|
\fB\%vidattr\fP,
|
|
\fB\%vidputs\fP \-
|
|
\fIcurses\fR interfaces to \fI\%term\%info\fR database
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <curses.h>
|
|
\fB#include <term.h>
|
|
.PP
|
|
\fBTERMINAL * cur_term;
|
|
.PP
|
|
\fBconst char * const boolnames[];
|
|
\fBconst char * const boolcodes[];
|
|
\fBconst char * const boolfnames[];
|
|
\fBconst char * const numnames[];
|
|
\fBconst char * const numcodes[];
|
|
\fBconst char * const numfnames[];
|
|
\fBconst char * const strnames[];
|
|
\fBconst char * const strcodes[];
|
|
\fBconst char * const strfnames[];
|
|
.PP
|
|
\fBint setupterm(const char * \fIterm\fP, int \fIfiledes\fP, int * \fIerrret\fP);
|
|
\fBTERMINAL * set_curterm(TERMINAL * \fInterm\fP);
|
|
\fBint del_curterm(TERMINAL * \fIoterm\fP);
|
|
\fBint restartterm(const char * \fIterm\fP, int \fIfiledes\fP, int * \fIerrret\fP);
|
|
.PP
|
|
\fBchar * tparm(const char * \fIstr\fP, \fR.\|.\|.\fP);
|
|
\fI/* or */
|
|
\fBchar * tparm(const char * \fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
|
|
.PP
|
|
\fBint tputs(const char * \fIstr\fP, int \fIaffcnt\fP, int (* \fIputc\fP)(int));
|
|
\fBint putp(const char * \fIstr\fP);
|
|
.PP
|
|
\fBint vidputs(chtype \fIattrs\fP, int (* \fIputc\fP)(int));
|
|
\fBint vidattr(chtype \fIattrs\fP);
|
|
\fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP, int (* \fIputc\fP)(int));
|
|
\fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP);
|
|
.PP
|
|
\fBint tigetflag(const char * \fIcap-code\fP);
|
|
\fBint tigetnum(const char * \fIcap-code\fP);
|
|
\fBchar * tigetstr(const char * \fIcap-code\fP);
|
|
.PP
|
|
\fBchar * tiparm(const char * \fIstr\fP, \fR.\|.\|.\fP);
|
|
.PP
|
|
\fI/* extensions */
|
|
\fBchar * tiparm_s(int \fIexpected\fP, int \fImask\fP, const char * \fIstr\fP, .\|.\|.);
|
|
\fBint tiscan_s(int * \fIexpected\fP, int * \fImask\fP, const char * \fIstr\fP);
|
|
.PP
|
|
\fI/* deprecated */
|
|
\fBint setterm(const char * \fIterm\fP);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
These lower-level functions of the
|
|
.I curses
|
|
standard must be called by programs that deal directly
|
|
with the
|
|
.I \%term\%info
|
|
database to handle certain terminal capabilities,
|
|
such as programming function keys.
|
|
For all other functionality,
|
|
.I curses
|
|
functions are more suitable and their use is recommended.
|
|
.PP
|
|
None of these functions use
|
|
(or are aware of)
|
|
multibyte character strings such as UTF-8.
|
|
.bP
|
|
Capability names and codes use the POSIX portable character set.
|
|
.bP
|
|
Capability string values have no associated encoding;
|
|
they are strings of 8-bit characters.
|
|
.SS Initialization
|
|
Call
|
|
.B \%setupterm
|
|
from your application to have
|
|
.I \%term\%info
|
|
manage the terminal device;
|
|
this action initializes the terminal-dependent variables listed in
|
|
\fB\%term_variables\fP(3X).
|
|
(A
|
|
.I curses
|
|
application calling \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) achieves
|
|
the same result.)
|
|
Applications can use the terminal capabilities either directly,
|
|
by object definitions corresponding to capability names and codes
|
|
(see \fB\%term_variables\fP(3X))
|
|
or by calling the functions documented here.
|
|
.B \%setupterm
|
|
initializes the
|
|
.I \%term\%info
|
|
variables
|
|
.B \%lines
|
|
and
|
|
.B \%columns
|
|
as described in \fB\%use_env\fP(3X).
|
|
.PP
|
|
Pass parameterized string capability values through
|
|
.B \%tparm
|
|
to instantiate them.
|
|
All
|
|
.I \%term\%info
|
|
strings
|
|
(including the output of
|
|
.BR \%tparm ")"
|
|
should be sent to the terminal device with
|
|
.B \%tputs
|
|
or
|
|
.BR \%putp "."
|
|
Call
|
|
\fB\%reset_shell_mode\fP(3X) to restore the terminal modes before
|
|
exiting.
|
|
(A
|
|
.I curses
|
|
application calling \fB\%endwin\fP(3X) achieves the same result.)
|
|
.\" XXX: What should a "pure" terminfo application that wants to link
|
|
.\" only with libtinfo, and not libcurses, do?
|
|
.PP
|
|
Programs that use cursor addressing should emit certain capabilities
|
|
at specific times.
|
|
Specifically,
|
|
output
|
|
.bP
|
|
.B \%enter_ca_mode
|
|
upon startup,
|
|
and
|
|
.bP
|
|
.B \%exit_ca_mode
|
|
before exiting.
|
|
.PP
|
|
Programs that execute shell subprocesses should
|
|
.bP
|
|
call \fB\%reset_shell_mode\fP(3X) and output
|
|
.B \%exit_ca_mode
|
|
before the shell is called,
|
|
and
|
|
.bP
|
|
output
|
|
.B \%enter_ca_mode
|
|
and call \fB\%reset_prog_mode\fP(3X) after returning from the shell.
|
|
.\" XXX: What should a "pure" terminfo application that wants to link
|
|
.\" only with libtinfo, and not libcurses, do?
|
|
.PP
|
|
\fB\%setupterm\fP reads in the
|
|
.I \%term\%info
|
|
database,
|
|
initializing the
|
|
.I \%term\%info
|
|
structures,
|
|
but does not set up the output virtualization structures used by
|
|
.IR curses "."
|
|
Its parameters follow.
|
|
.RS 3
|
|
.TP 5
|
|
.I term
|
|
is the terminal type,
|
|
a character string.
|
|
If
|
|
.I term
|
|
is null,
|
|
the environment variable
|
|
.I TERM
|
|
is read.
|
|
.TP 5
|
|
.I filedes
|
|
is the file descriptor used for getting and setting terminal I/O modes.
|
|
.IP
|
|
Higher-level applications use \fB\%newterm\fP(3X) to initialize the
|
|
terminal,
|
|
passing an output
|
|
.I stream
|
|
rather than a
|
|
.IR descriptor "."
|
|
In
|
|
.IR curses ","
|
|
the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
|
|
passing the file descriptor derived from its output stream parameter.
|
|
.TP 5
|
|
.I errret
|
|
points to an optional location where an error status can be returned to
|
|
the caller.
|
|
If
|
|
.I errret
|
|
is not null,
|
|
then
|
|
.B \%setupterm
|
|
returns
|
|
.B OK
|
|
or
|
|
.B ERR
|
|
and stores a status value in the integer pointed to by
|
|
.IR errret "."
|
|
A return value of
|
|
.B OK
|
|
combined with status of
|
|
.B 1
|
|
in
|
|
.I errret
|
|
is normal.
|
|
.IP
|
|
If
|
|
.B ERR
|
|
is returned,
|
|
examine
|
|
.IR errret "."
|
|
.RS
|
|
.TP 5
|
|
.B 1
|
|
means that the terminal is a hard-copy type
|
|
(lacks destructive backspace),
|
|
and cannot be used for
|
|
.I curses
|
|
applications.
|
|
The library determines this fact by checking the terminal type's
|
|
.B \%hardcopy
|
|
.RB ( hc )
|
|
capability.
|
|
.TP 5
|
|
.B 0
|
|
means that the terminal could not be found,
|
|
or that it is a generic type,
|
|
having too little information for
|
|
.I curses
|
|
applications to run.
|
|
.IP
|
|
.B \%setupterm
|
|
determines if the entry is a generic type by checking the
|
|
.B \%generic_type
|
|
.RB ( gn )
|
|
capability.
|
|
.TP 5
|
|
.B \-1
|
|
means that the
|
|
.I \%term\%info
|
|
database could not be found.
|
|
.RE
|
|
.IP
|
|
If
|
|
.I errret
|
|
is null,
|
|
.B \%setupterm
|
|
reports an error message upon finding an error and exits.
|
|
Thus,
|
|
the simplest call is:
|
|
.RS
|
|
.IP
|
|
.EX
|
|
setupterm((char *) NULL, 1, (int *) NULL);
|
|
.EE
|
|
.RE
|
|
.IP
|
|
which uses all the defaults and sends the output to
|
|
.IR stdout "."
|
|
.RE
|
|
.\" ********************************************************************
|
|
.SS "The Terminal State"
|
|
.B \%setupterm
|
|
stores its information about the terminal in a
|
|
.I \%TERMINAL
|
|
structure pointed to by the global variable
|
|
.BR \%cur_term "."
|
|
If it detects an error,
|
|
or decides that the terminal is unsuitable
|
|
(hardcopy or generic),
|
|
it discards this information,
|
|
making it unavailable to applications.
|
|
.PP
|
|
If
|
|
.B \%setupterm
|
|
is called repeatedly for the same terminal type,
|
|
it reuses the information.
|
|
It maintains only one copy of a given type's capabilities in memory.
|
|
If called for different types,
|
|
.B \%setupterm
|
|
allocates new storage for each set of terminal capabilities.
|
|
.PP
|
|
.B \%set_curterm
|
|
sets
|
|
.B \%cur_term
|
|
to
|
|
.IR \%nterm ","
|
|
making all of the
|
|
.I \%term\%info
|
|
Boolean,
|
|
numeric,
|
|
and string capabilities use the values from
|
|
.IR \%nterm "."
|
|
It returns the old value of
|
|
.BR \%cur_term "."
|
|
.PP
|
|
.B \%del_curterm
|
|
releases the memory pointed to by
|
|
.IR \%oterm "."
|
|
If
|
|
.I \%oterm
|
|
is
|
|
the same as
|
|
.BR \%cur_term ","
|
|
references to any of the
|
|
.I \%term\%info
|
|
Boolean,
|
|
numeric,
|
|
and string capabilities thereafter may refer to invalid memory locations
|
|
until
|
|
.B \%setupterm
|
|
is called again.
|
|
.PP
|
|
.B \%restartterm
|
|
is similar to
|
|
.BR \%setupterm ","
|
|
but is intended for use after restoring program memory
|
|
to a previous state
|
|
(for example,
|
|
when reloading an application that has been suspended from one terminal
|
|
session and restored in another).
|
|
.B \%restartterm
|
|
assumes that the display dimensions
|
|
and the input and output options are the same as when memory was saved,
|
|
but the terminal type and line speed may differ.
|
|
Accordingly,
|
|
.B \%restartterm
|
|
saves relevant terminal state,
|
|
calls
|
|
.BR \%setupterm ","
|
|
then restores that state.
|
|
.\" ********************************************************************
|
|
.SS "Formatting Output"
|
|
\fB\%tparm\fP instantiates the string
|
|
.I str
|
|
with parameters
|
|
.IR pi "."
|
|
It returns a pointer to a character string representing
|
|
.I str
|
|
with the parameters applied to \*(``%\*('' expressions within.
|
|
.\" XXX: Whose responsibility is it to free that string?
|
|
Application developers should keep in mind some quirks of the interface.
|
|
.bP
|
|
Although \fB\%tparm\fP's actual parameters may be integers or strings,
|
|
the prototype expects
|
|
.I long
|
|
(integer) values.
|
|
.bP
|
|
Aside from the
|
|
.B \%set_attributes\fP
|
|
.RB ( sgr )
|
|
capability,
|
|
most terminal capabilities require no more than one or two parameters.
|
|
.bP
|
|
Padding information is ignored by \fB\%tparm\fP;
|
|
it is interpreted by \fB\%tputs\fP.
|
|
.bP
|
|
The capability string is null-terminated.
|
|
Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
|
|
.PP
|
|
\fB\%tiparm\fP is a newer form of \fB\%tparm\fP that uses
|
|
.I \%stdarg.h
|
|
rather than a fixed-length parameter list.
|
|
Its numeric parameters are
|
|
.IR int s
|
|
rather than
|
|
.IR long "s."
|
|
.PP
|
|
.B \%tparm
|
|
and
|
|
.B \%tiparm
|
|
assume that the application
|
|
passes parameters consistent with the terminal description.
|
|
.I \%ncurses
|
|
provides two extensions as alternatives to deal with untrusted data.
|
|
.bP
|
|
The
|
|
.B \%tiparm_s
|
|
extension is a safer formatting function than
|
|
.B \%tparm
|
|
or
|
|
.BR \%tiparm ","
|
|
because it allows the developer to tell the
|
|
.I curses
|
|
library how many parameters to expect in the parameter list,
|
|
and which may be string parameters.
|
|
.IP
|
|
The
|
|
.I mask
|
|
parameter has one bit set for each of the parameters
|
|
(up to 9)
|
|
passed as
|
|
.I char
|
|
pointers rather than numbers.
|
|
.bP
|
|
The extension
|
|
.B \%tiscan_s
|
|
allows the application
|
|
to inspect a formatting capability to see what the
|
|
.I curses
|
|
library would assume.
|
|
.\" ********************************************************************
|
|
.SS "Output Functions"
|
|
String capabilities can contain
|
|
.IR padding ","
|
|
a time delay
|
|
(accommodating performance limitations of hardware terminals)
|
|
expressed as
|
|
.BI $< n >\c
|
|
,
|
|
where
|
|
.I n
|
|
is a nonnegative integral count of milliseconds.
|
|
If
|
|
.I n
|
|
exceeds 30,000
|
|
(thirty seconds),
|
|
.I \%ncurses
|
|
caps it at that value.
|
|
.PP
|
|
.B \%tputs
|
|
interprets time delays in the string
|
|
.I str
|
|
and acts upon them.
|
|
.bP
|
|
The
|
|
.I str
|
|
parameter must be a
|
|
.I \%term\%info
|
|
string capability or the return value of
|
|
.B \%tparm
|
|
or
|
|
.BR \%tiparm "."
|
|
.bP
|
|
.I affcnt
|
|
is the number of lines affected,
|
|
or
|
|
.B 1
|
|
if not applicable.
|
|
.bP
|
|
.I putc
|
|
is a
|
|
.IR \%putchar -like
|
|
function to which the characters are passed,
|
|
one at a time.
|
|
.PP
|
|
.B \%tputs
|
|
processes each time delay with the \fB\%delay_output\fP(3X) function,
|
|
routing any resulting padding characters through this function.
|
|
.PP
|
|
\fB\%putp\fR calls
|
|
.RB \%\*(`` tputs(\c
|
|
.IB str ", 1, putchar)\c"
|
|
\*(''.
|
|
The output of \fB\%putp\fP always goes to
|
|
.IR stdout ","
|
|
rather than the
|
|
.I \%file\%des
|
|
specified in \fB\%setupterm\fP.
|
|
.PP
|
|
\fB\%vidputs\fP displays the string on the terminal in the video
|
|
attribute mode
|
|
.IR attrs ","
|
|
which is any combination of the attributes listed in \fB\%curses\fP(3X).
|
|
The characters are passed to the
|
|
.IR \%putchar -like
|
|
function
|
|
.IR putc "."
|
|
.PP
|
|
\fB\%vidattr\fP is like \fB\%vidputs\fP,
|
|
except that it outputs through \fI\%putchar\fP(3).
|
|
.PP
|
|
.B \%vid_attr
|
|
and
|
|
.B \%vid_puts
|
|
correspond to
|
|
.B \%vidattr
|
|
and
|
|
.BR \%vidputs ","
|
|
respectively.
|
|
They use multiple parameters to represent the character attributes and
|
|
color;
|
|
namely,
|
|
.bP
|
|
.IR \%attrs ","
|
|
of type
|
|
.IR \%attr_t ","
|
|
for the attributes and
|
|
.bP
|
|
.IR pair ","
|
|
of type
|
|
.IR short ","
|
|
for the color pair number.
|
|
.PP
|
|
Use the attribute constants prefixed with
|
|
.RB \*(`` WA_ \*(''
|
|
with
|
|
.B \%vid_attr
|
|
and
|
|
.BR \%vid_puts "."
|
|
.PP
|
|
X/Open Curses reserves the
|
|
.I opts
|
|
argument for future use,
|
|
saying that applications must provide a null pointer for that argument;
|
|
but see section \*(``EXTENSIONS\*('' below.
|
|
.PP
|
|
While
|
|
.B \%putp
|
|
is a lower-level function
|
|
that does not use higher-level
|
|
.I curses
|
|
state,
|
|
.I \%ncurses
|
|
declares it in
|
|
.I \%curses.h
|
|
because System\ V did so
|
|
(see section \*(``HISTORY\*('' below).
|
|
.\" ********************************************************************
|
|
.SS "Terminal Capability Functions"
|
|
.BR \%tigetflag ","
|
|
.BR \%tigetnum ","
|
|
and
|
|
.B \%tigetstr
|
|
return the value of the capability corresponding to
|
|
the
|
|
.I \%term\%info
|
|
.IR cap-code ","
|
|
such as
|
|
.BR xenl ","
|
|
passed to them.
|
|
The
|
|
.I cap-code
|
|
for each capability is given in the table column of that name
|
|
in the \*(``Capabilities\*('' section of \fB\%terminfo\fP(5).
|
|
.PP
|
|
These functions return special values to denote errors.
|
|
.PP
|
|
.B \%tigetflag
|
|
returns
|
|
.TP
|
|
.B \-1
|
|
if
|
|
.I cap-code
|
|
is not a Boolean capability,
|
|
or
|
|
.TP
|
|
.B 0
|
|
if it is canceled or absent from the terminal description.
|
|
.PP
|
|
.B \%tigetnum
|
|
returns
|
|
.TP
|
|
.B \-2
|
|
if
|
|
.I cap-code
|
|
is not a numeric capability,
|
|
or
|
|
.TP
|
|
.B \-1
|
|
if it is canceled or absent from the terminal description.
|
|
.PP
|
|
.B \%tigetstr
|
|
returns
|
|
.TP
|
|
.B "(char *)\-1"
|
|
if
|
|
.I cap-code
|
|
is not a string capability,
|
|
or
|
|
.TP
|
|
.B NULL
|
|
if it is canceled or absent from the terminal description.
|
|
.\" ********************************************************************
|
|
.SS "Terminal Capability Names"
|
|
These null-terminated arrays contain
|
|
.bP
|
|
the short \fI\%term\%info\fP names (\*(``codes\*(''),
|
|
.bP
|
|
the \fItermcap\fP names (\*(``names\*(''),
|
|
and
|
|
.bP
|
|
the long \fI\%term\%info\fP names (\*(``fnames\*('')
|
|
.PP
|
|
for each standard
|
|
.I \%term\%info
|
|
capability name.
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
|
|
\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
|
|
\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
|
|
.fi
|
|
.RE
|
|
.\" ********************************************************************
|
|
.SS "Releasing Memory"
|
|
Each successful call to \fB\%setupterm\fP allocates memory to hold the
|
|
terminal description.
|
|
As a side effect,
|
|
it sets \fB\%cur_term\fP to point to this memory.
|
|
If an application calls
|
|
.RS
|
|
.EX
|
|
del_curterm(cur_term);
|
|
.EE
|
|
.RE
|
|
the memory will be freed.
|
|
.PP
|
|
The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
|
|
storage allocated by \fB\%setupterm\fP as follows.
|
|
.bP
|
|
They add the \*(``static\*(''
|
|
.I \%term\%info
|
|
variables [a-z].
|
|
Before
|
|
.I \%ncurses
|
|
6.3,
|
|
those were shared by all screens.
|
|
With
|
|
.I \%ncurses
|
|
6.3,
|
|
those are allocated per screen.
|
|
See \fB\%terminfo\fP(5).
|
|
.bP
|
|
To improve performance,
|
|
.I \%ncurses
|
|
6.3 caches the result of analyzing
|
|
.I \%term\%info
|
|
strings for their parameter types.
|
|
That is stored as a binary tree referenced from the
|
|
.I \%TERMINAL
|
|
structure.
|
|
.PP
|
|
The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
|
|
\fB\%setupterm\fP.
|
|
Normally they do not free this memory,
|
|
but it is possible to do that using the \fB\%delscreen\fP(3X) function.
|
|
.\" ********************************************************************
|
|
.SH RETURN VALUE
|
|
Functions that return integers return
|
|
.B ERR
|
|
upon failure and
|
|
.B OK
|
|
upon success.
|
|
.PP
|
|
In
|
|
.IR \%ncurses ","
|
|
.TP 5
|
|
.B del_curterm
|
|
fails if its terminal parameter is null.
|
|
.TP 5
|
|
.B putp
|
|
calls \fB\%tputs\fP,
|
|
returning the same error codes.
|
|
.TP 5
|
|
.B restartterm
|
|
fails if the associated call to \fB\%setupterm\fP returns
|
|
.BR ERR "."
|
|
.TP 5
|
|
.B setupterm
|
|
fails if it cannot allocate enough memory,
|
|
or create the initial windows
|
|
.RB \%( stdscr ,
|
|
.BR \%curscr ","
|
|
and
|
|
.BR \%newscr ")."
|
|
Other error conditions are documented above.
|
|
.TP 5
|
|
.B tparm
|
|
returns a null pointer if the capability would require unexpected
|
|
parameters;
|
|
that is,
|
|
too many,
|
|
too few,
|
|
or incorrect types
|
|
(strings where integers are expected,
|
|
or vice versa).
|
|
.TP 5
|
|
.B tputs
|
|
fails if the string parameter is null.
|
|
It does not detect I/O errors:
|
|
X/Open Curses states that \fB\%tputs\fP ignores the return value
|
|
of the output function \fI\%putc\fP.
|
|
.\" ********************************************************************
|
|
.SH NOTES
|
|
The
|
|
.B \%vid_attr
|
|
function in
|
|
.I \%ncurses
|
|
is a special case.
|
|
It was originally implemented based on a draft of X/Open Curses,
|
|
as a macro,
|
|
before other parts of the
|
|
.I \%ncurses
|
|
wide-character API were developed,
|
|
and unlike the other wide-character functions,
|
|
is also provided in the non-wide-character configuration.
|
|
.\" ********************************************************************
|
|
.SH EXTENSIONS
|
|
The functions marked as extensions originated in
|
|
.IR \%ncurses ","
|
|
and are not found in SVr4
|
|
.IR curses ","
|
|
4.4BSD
|
|
.IR curses ","
|
|
or any other previous
|
|
.I curses
|
|
implementation.
|
|
.PP
|
|
.I \%ncurses
|
|
allows
|
|
.I opts
|
|
to be a pointer to
|
|
.IR int ","
|
|
which overrides the
|
|
.I pair
|
|
.RI ( short )
|
|
argument.
|
|
.\" ********************************************************************
|
|
.SH PORTABILITY
|
|
Except for
|
|
.IR \%setterm ","
|
|
X/Open Curses Issue\ 4 describes these functions.
|
|
It specifies no error conditions for them.
|
|
.PP
|
|
SVr4 describes a successful return value
|
|
except where \*(``otherwise noted\*(''
|
|
as
|
|
\*(``an integer value other than
|
|
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 539
|
|
.SS "Header Files"
|
|
On legacy
|
|
.I curses
|
|
systems,
|
|
include
|
|
.I \%curses.h
|
|
and
|
|
.I \%term.h
|
|
in that order
|
|
to make visible the definitions of the string arrays
|
|
storing the capability names and codes.
|
|
.SS "Compatibility Macros"
|
|
.I \%ncurses
|
|
implements a few macros for early System\ V
|
|
.I curses
|
|
compatibility
|
|
(see section \*(``HISTORY\*('' below).
|
|
They include
|
|
.IR \%crmode ","
|
|
.IR \%fixterm ","
|
|
.IR \%gettmode ","
|
|
.IR \%nocrmode ","
|
|
.IR \%resetterm ","
|
|
.IR \%saveterm ","
|
|
and
|
|
.IR \%setterm "."
|
|
.PP
|
|
In SVr4,
|
|
these are found in
|
|
.IR \%curses.h ","
|
|
but except for
|
|
.IR \%setterm ","
|
|
are likewise macros.
|
|
The one function,
|
|
.IR \%setterm ","
|
|
is mentioned in the manual page.
|
|
It further notes that
|
|
.I \%setterm
|
|
was replaced by
|
|
.IR \%setupterm ","
|
|
stating that the call
|
|
.RS
|
|
.EX
|
|
.RI setupterm( term ", 1, (int *)0)"
|
|
.EE
|
|
.RE
|
|
provides the same functionality as
|
|
.RS
|
|
.EX
|
|
.RI setterm( term )
|
|
.EE
|
|
.RE
|
|
and discouraging the latter for new programs.
|
|
.SS "Legacy Data"
|
|
.I \%setupterm
|
|
copies the terminal name to the array
|
|
.IR \%ttytype "."
|
|
This behavior is not specified by X/Open Curses,
|
|
but is assumed by some applications.
|
|
.PP
|
|
Other implementations may not declare the capability name arrays.
|
|
Some provide them without declaring them.
|
|
X/Open Curses does not specify them.
|
|
.PP
|
|
Extended terminal capability names,
|
|
as defined by
|
|
.RB \%\*(`` "@TIC@ \-x" \*('',
|
|
are not stored in the arrays described here.
|
|
.SS "Output Buffering"
|
|
Older versions of
|
|
.I \%ncurses
|
|
assumed that the file descriptor passed to
|
|
.I \%setupterm
|
|
from
|
|
.I \%initscr
|
|
or
|
|
.I \%newterm
|
|
used buffered I/O,
|
|
and wrote to the corresponding
|
|
.I stdio
|
|
stream.
|
|
In addition to the limitation that the terminal was left in
|
|
block-buffered mode on exit
|
|
(like System\ V
|
|
.IR curses "),"
|
|
it was problematic because
|
|
.I \%ncurses
|
|
did not allow a reliable way to clean up on receiving
|
|
.IR SIGTSTP "."
|
|
.PP
|
|
.I \%ncurses
|
|
.RI 6. x
|
|
uses output buffers managed directly by
|
|
.IR \%ncurses "."
|
|
The lower-level functions described here
|
|
that write to the terminal device
|
|
do so via the standard output stream;
|
|
they thus are not signal-safe.
|
|
The higher-level functions in
|
|
.I \%ncurses
|
|
employ alternate versions of these functions
|
|
using a more reliable buffering scheme.
|
|
.SS "Function Prototypes"
|
|
The X/Open Curses prototypes are based on the SVr4
|
|
.I curses
|
|
header declarations,
|
|
which were defined at the same time the C language was first
|
|
standardized in the late 1980s.
|
|
.bP
|
|
X/Open Curses uses
|
|
.I \%const
|
|
less effectively than a later design might,
|
|
sometimes applying it needlessly to function parameters
|
|
that are passed by value
|
|
(and therefore copied),
|
|
and in most cases overlooking parameters
|
|
that normally would benefit from
|
|
.IR \%const "."
|
|
Passing
|
|
.IR \%const -qualified
|
|
parameters to functions that do not declare them
|
|
.I \%const
|
|
may prevent the program from compiling.
|
|
On the other hand,
|
|
\*(``writable strings\*('' are an obsolescent C language feature.
|
|
.IP
|
|
As an extension,
|
|
.I \%ncurses
|
|
can be configured to change the function prototypes
|
|
to use the
|
|
.I \%const
|
|
keyword.
|
|
The
|
|
.I \%ncurses
|
|
ABI 6 enables this feature by default.
|
|
.bP
|
|
X/Open Curses prototypes
|
|
.I \%tparm
|
|
with a fixed number of parameters,
|
|
rather than a variable argument list.
|
|
.IP
|
|
.I \%ncurses
|
|
uses a variable argument list,
|
|
but can be configured to use the fixed-parameter list.
|
|
Portable applications should provide nine parameters after the format;
|
|
zeroes are fine for this purpose.
|
|
.IP
|
|
In response to review comments by Thomas E. Dickey,
|
|
X/Open Curses Issue\ 7 proposed the
|
|
.I \%tiparm
|
|
function in mid-2009.
|
|
.IP
|
|
While
|
|
.I \%tiparm
|
|
is always provided in
|
|
.IR \%ncurses ","
|
|
the older form is available only as a build-time configuration option.
|
|
If not specially configured,
|
|
.I \%tparm
|
|
is the same as
|
|
.IR \%tiparm "."
|
|
.PP
|
|
Both forms of
|
|
.I \%tparm
|
|
have drawbacks.
|
|
.bP
|
|
Most calls to
|
|
.I \%tparm
|
|
require only one or two parameters.
|
|
Passing nine on each call is awkward.
|
|
.IP
|
|
Using
|
|
.I long
|
|
for the numeric parameter type is a workaround to make the parameter use
|
|
the same amount of stack memory as a pointer.
|
|
That approach dates to the mid-1980s,
|
|
before C was standardized.
|
|
Since ANSI\ C (1989),
|
|
C language standards do not require a pointer to fit in a
|
|
.IR long ")."
|
|
.bP
|
|
Providing the right number of parameters for a variadic function
|
|
such as
|
|
.I \%tiparm
|
|
can be a problem,
|
|
in particular for string parameters.
|
|
However,
|
|
only a few
|
|
.I \%term\%info
|
|
capabilities use string parameters
|
|
(for instance,
|
|
the ones used for programmable function keys).
|
|
.IP
|
|
The
|
|
.I \%ncurses
|
|
library checks usage of these capabilities,
|
|
and returns
|
|
.I ERR
|
|
if the capability mishandles string parameters.
|
|
But it cannot check if a calling program provides strings in the right
|
|
places for the
|
|
.I \%tparm
|
|
calls.
|
|
.IP
|
|
.IR \%ncurses 's
|
|
\fB\%@TPUT@\fR(1) checks its use of these capabilities with a table,
|
|
so that it calls
|
|
.I \%tparm
|
|
correctly.
|
|
.SS "Special \fITERM\fP treatment"
|
|
If
|
|
.I \%ncurses
|
|
is configured to use a terminal driver
|
|
that does not employ the POSIX
|
|
.I \%termios
|
|
API,
|
|
as with the MinGW port,
|
|
.bP
|
|
.I \%setupterm
|
|
interprets a missing or empty
|
|
.I TERM
|
|
variable as the special value \*(``unknown\*(''.
|
|
.IP
|
|
SVr4
|
|
.I curses
|
|
uses the special value \*(``dumb\*(''.
|
|
.IP
|
|
The difference between the two is that the former uses the
|
|
.B \%generic_type
|
|
.RB ( gn )
|
|
.I \%term\%info
|
|
capability,
|
|
while the latter does not.
|
|
A generic terminal is unsuitable for full-screen applications.
|
|
.bP
|
|
.I \%setupterm
|
|
allows explicit use of the Microsoft Windows console driver by checking
|
|
whether the
|
|
.I TERM
|
|
environment variable has the value \*(``#win32con\*(''
|
|
or an abbreviation of that string.
|
|
.SS "Other Portability Issues"
|
|
In SVr4,
|
|
.I \%set_curterm
|
|
returns an
|
|
.IR int ","
|
|
.I OK
|
|
or
|
|
.IR ERR "."
|
|
We have chosen to implement the X/Open Curses semantics.
|
|
.PP
|
|
In SVr4,
|
|
the third argument of
|
|
.I \%tputs
|
|
has the type
|
|
.RB \*(`` "int (*)(char)" \*(''.
|
|
.PP
|
|
At least one implementation of X/Open Curses
|
|
(Solaris
|
|
.IR \%xcurses ")"
|
|
returns a value other than
|
|
.I OK
|
|
or
|
|
.I ERR
|
|
from
|
|
.IR \%tputs "."
|
|
It instead returns the length of the string,
|
|
and does no error checking.
|
|
.PP
|
|
Very old versions of AIX
|
|
.\" Can we be more specific? Like, AIX 4.3.3 and earlier? --GBR
|
|
.I curses
|
|
required inclusion of
|
|
.I \%curses.h
|
|
before
|
|
.IR \%term.h .
|
|
.\" ********************************************************************
|
|
.SH HISTORY
|
|
SVr2 (1984) introduced the
|
|
.I \%term\%info
|
|
feature.
|
|
Its programming manual mentioned the following low-level functions.
|
|
.PP
|
|
.TS
|
|
Lb Lb
|
|
Li Lw(47n)x.
|
|
Function Description
|
|
_
|
|
fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
|
|
gettmode establish current terminal modes
|
|
mvcur low level cursor motion
|
|
putp use \fItputs\fP to send characters via \fIputchar\fP
|
|
resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
|
|
state
|
|
resetty reset terminal flags to stored value
|
|
saveterm save current modes as \*(``in \fIcurses\fP\*('' state
|
|
savetty store current terminal flags
|
|
setterm establish terminal with given type
|
|
setupterm establish terminal with given type
|
|
tparm interpolate parameters into string capability
|
|
tputs apply padding information to a string
|
|
vidattr like \fIvidputs\fP, but output through \fIputchar\fP
|
|
vidputs T{
|
|
write string to terminal, applying specified attributes
|
|
T}
|
|
.TE
|
|
.PP
|
|
The programming manual also mentioned
|
|
functions provided for
|
|
.I termcap
|
|
compatibility
|
|
(commenting that they \*(``may go away at a later date\*('').
|
|
.PP
|
|
.TS
|
|
Lb Lb
|
|
Li Lw(48n)x.
|
|
Function Description
|
|
_
|
|
tgetent look up \fItermcap\fP entry for given \fIname\fP
|
|
tgetflag get Boolean entry for given \fIid\fP
|
|
tgetnum get numeric entry for given \fIid\fP
|
|
tgetstr get string entry for given \fIid\fP
|
|
tgoto apply parameters to given capability
|
|
tputs T{
|
|
write characters via a function parameter, applying padding
|
|
T}
|
|
.TE
|
|
.PP
|
|
Early
|
|
.I \%term\%info
|
|
programs obtained capability values from the
|
|
.I \%TERMINAL
|
|
structure initialized by
|
|
.IR \%setupterm "."
|
|
.PP
|
|
SVr3 (1987) extended
|
|
.I \%term\%info
|
|
by adding functions to retrieve capability values
|
|
(like the
|
|
.I termcap
|
|
interface),
|
|
and reusing
|
|
.I \%tgoto
|
|
and
|
|
.IR \%tputs "."
|
|
.PP
|
|
.ne 4v
|
|
.TS
|
|
Lb Lb
|
|
LI Lx.
|
|
Function Description
|
|
_
|
|
tigetflag get Boolean entry for given \fIid\fP
|
|
tigetnum get numeric entry for given \fIid\fP
|
|
tigetstr get string entry for given \fIid\fP
|
|
.TE
|
|
.PP
|
|
SVr3 also replaced several of the SVr2
|
|
.I \%term\%info
|
|
functions that had no counterpart in the
|
|
.I termcap
|
|
interface,
|
|
documenting them as obsolete.
|
|
.PP
|
|
.TS
|
|
Lb Lb
|
|
Li Lix.
|
|
Function Replaced by
|
|
_
|
|
crmode cbreak
|
|
fixterm reset_prog_mode
|
|
gettmode \fRn/a\fP
|
|
nocrmode nocbreak
|
|
resetterm reset_shell_mode
|
|
saveterm def_prog_mode
|
|
setterm setupterm
|
|
.TE
|
|
.PP
|
|
SVr3 kept the
|
|
.IR \%mvcur ","
|
|
.IR \%vidattr ","
|
|
and
|
|
.I \%vidputs
|
|
functions,
|
|
along with
|
|
.IR \%putp ","
|
|
.IR \%tparm ","
|
|
and
|
|
.IR \%tputs "."
|
|
The latter were needed to support padding,
|
|
and to handle capabilities accessed by functions such as
|
|
.I \%vidattr
|
|
(which used more than the two parameters supported by
|
|
.IR \%tgoto ")."
|
|
.PP
|
|
SVr3 introduced the functions for switching between terminal
|
|
descriptions;
|
|
for example,
|
|
.IR \%set_curterm "."
|
|
Some changes reflected incremental improvements to the SVr2 library.
|
|
.bP
|
|
The
|
|
.I \%TERMINAL
|
|
type definition was introduced in SVr3.01,
|
|
for the
|
|
.I term
|
|
structure provided in SVr2.
|
|
.bP
|
|
Various global variables such as
|
|
.I \%boolnames
|
|
were mentioned in the programming manual at this point,
|
|
though the variables had been provided in SVr2.
|
|
.PP
|
|
SVr4 (1989) added the
|
|
.I \%vid_attr
|
|
and
|
|
.I \%vid_puts
|
|
functions.
|
|
.PP
|
|
Other low-level functions are declared in the
|
|
.I curses
|
|
header files of Unix systems,
|
|
but none are documented.
|
|
Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
|
|
\fIvi\fP(1) editor.
|
|
.SH SEE ALSO
|
|
\fB\%curses\fP(3X),
|
|
\fB\%curs_initscr\fP(3X),
|
|
\fB\%curs_kernel\fP(3X),
|
|
\fB\%curs_memleaks\fP(3X),
|
|
\fB\%curs_termcap\fP(3X),
|
|
\fB\%curs_variables\fP(3X),
|
|
\fB\%putc\fP(3),
|
|
\fB\%term_variables\fP(3X),
|
|
\fB\%terminfo\fP(5)
|