.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2017,2018 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 tom Exp $
-.TH curs_termcap 3X 2023-12-17 "ncurses 6.4" "Library calls"
+.\" $Id: curs_termcap.3x,v 1.85 2024/04/20 19:13:12 tom Exp $
+.TH curs_termcap 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%tgetent\fP loads the terminal database entry for \fIname\fP;
see \fBterm\fP(7).
This must be done before calling any of the other functions.
-It returns:
+It returns
.RS 3
-.TP 4
+.TP 5 \" "-1" + 2n + adjust for PDF
1
on success,
-.TP 4
+.TP
0
if there is no such entry
(or if the matching entry describes a generic terminal,
.I curses
applications to run),
and
-.TP 4
+.TP
\-1
if the \fI\%term\%info\fP database could not be found.
.RE
X/Open Curses now withdrawn.
The BSD \fItermcap\fP library would store a copy of the terminal type
description in the area referenced by this pointer.
-\fI\%ncurses\fP stores terminal type descriptions in compiled form,
+\fI\%term\%info\fP stores terminal type descriptions in compiled form,
which is not the same thing.
.bP
The meanings of the return values differ.
The BSD \fItermcap\fP library does not check whether the terminal type
-description is marked with the
-.B gn
-.RB ( \%generic )
+description includes the
+.B \%generic
+.RB ( gn )
capability,
nor whether the terminal type description supports an addressable
cursor,
most hardware terminals use cursor addressing with \fIrow\fP first,
but the original developers of the \fItermcap\fP interface chose to
put the \fIcol\fP (column) parameter first.
-The \fB\%tgoto\fP function swaps the order of parameters.
+The \fB\%tgoto\fP function swaps the order of its parameters.
It does this even for calls requiring only a single parameter.
In that case,
the first parameter is merely a placeholder.
.bP
Normally the \fI\%ncurses\fP library is compiled without
-full \fI\%term\%cap\fP support.
+full \fI\%termcap\fP support.
In that case,
\fB\%tgoto\fP uses an internal version of \fB\%tparm\fP(3X)
(a more capable function).
.PP
\fB\%tputs\fP is described in \fB\%curs_terminfo\fP(3X).
It can retrieve capabilities by either \fItermcap\fP or
-\fI\%term\%info\fP name.
+\fI\%term\%info\fP code.
.SS "Global Variables"
The variables
\fBPC\fP,
to free this memory,
but there is an additional complication with \fI\%ncurses\fP.
It uses a fixed-size pool of storage locations,
-one per value of the \fITERM\fP environment variable when
-\fB\%tgetent\fP is called.
-The \fBscreen\fP(1) program relies upon this arrangement to improve its
+one per value of the terminal name parameter given to \fB\%tgetent\fP.
+The \fIscreen\fP(1) program relies upon this arrangement to improve its
performance.
.PP
An application that uses only the \fItermcap\fP functions,
.SS Standards
.bP
X/Open Curses, Issue 4, Version 2 (1996),
-describes these functions.
-However,
-they are marked
+describes these functions,
+marking them as
\*(``TO BE WITHDRAWN\*(''.
.bP
-X/Open Curses, Issue 7 (2009) marked the \fItermcap\fP interface
+X/Open Curses, Issue 7 (2009) marks the \fItermcap\fP interface
(along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn.
.PP
Neither X/Open Curses nor the SVr4 man pages documented the return
values of \fB\%tgetent\fP correctly,
-though all three were in fact returned ever since SVr1.
+though all three shown here were in fact returned ever since SVr1.
In particular,
an omission in the X/Open Curses specification has been misinterpreted
to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP.
(June 1986).
4.4BSD-Lite
(June 1994)
-refactored it
+refactored it,
.\" Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
.\" entry points disappearing from termcap.c.
-but left the API unchanged.
+leaving the API unchanged.
.PP
-Function prototypes were a feature of the forthcoming ANSI C (1989).
-Thus the library provided no header file declaring them.
+Function prototypes were a feature of ANSI C (1989).
+The library long antedated the standard and thus provided no header file
+declaring them.
Nevertheless,
the BSD sources included two different \fI\%termcap.h\fP header files
over time.
.bP
One was used internally by \fBjove\fP(1) from 4.3BSD onward.
.\" 2BSD became a branch retaining support for non-virtual memory
-.\" systems (like the PDP-11) whereas most BSD development focused on
+.\" systems (such as the PDP-11) whereas most BSD development focused on
.\" the VAX and other VM-enabled systems starting with 3BSD.
.\"
.\" This man page previously located a termcap.h in 2BSD, but that may
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
.\" jove/Makefile
.\" --much too late for 2BSD (1979).
-It delcared global symbols for the \fItermcap\fP variables that it used.
+It declared global symbols for the \fItermcap\fP variables that it used.
.bP
The other appeared in 4.4BSD-Lite Release 2
(June 1995)
but in that instance,
it was \fIlibedit\fP that differed from BSD \fItermcap\fP.
.PP
-GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP in mid-1993 to support
-the \fBreadline\fP(3) library.
+GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP(1) in mid-1993 to
+support the \fI\%readline\fP(3) library.
.PP
\fI\%ncurses\fP 1.8.1
(November 1993)
and programs that intend to work with all \fItermcap\fP library
interfaces must account for that fact.
.SH BUGS
-If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other
-parameterized string capability,
+If you call \fB\%tgetstr\fP to fetch
+.B \%column_address
+.RB ( ch )
+or any other parameterized string capability,
be aware that it is returned in \fI\%term\%info\fP notation,
not the older and not-quite-compatible \fItermcap\fP notation.
This does not cause problems if all you do with it is call \fB\%tgoto\fP
or \fB\%tparm\fP,
-which both expand \fI\%term\%info\fP-style strings as \fI\%term\%info\fP
-does.
+which both parametrically expand \fI\%term\%info\fP-style string
+capabilities as \fI\%term\%info\fP does.
(If
.I \%ncurses
is configured to support \fItermcap,\fP
\fB\%tputs("50")\fP in a \fItermcap\fP system may busy-wait for 50
milliseconds rather than transmitting \*(``50\*(''.
.PP
-\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's \fBsgr\fP
-string.
+\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's
+.B \%set_attributes
+.RB ( sgr )
+capability.
One consequence is that \fItermcap\fP applications assume that
.RB \*(`` me \*(''
-(equivalent to \fI\%term\%info\fP's \fBsgr0\fP capability)
+(equivalent to \fI\%term\%info\fP's
+.B \%exit_attribute_mode
+.RB ( sgr0 )
+capability)
does not reset the alternate character set.
\fI\%ncurses\fP checks for,
and modifies the data shared with,
projects / ncurses.git / blobdiff