.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2022 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.52 2021/12/25 21:31:00 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.56 2022/02/12 20:05:11 tom Exp $
.TH curs_termcap 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.br
\fBextern @NCURSES_OSPEED@ ospeed;\fP
.sp
-\fBint tgetent(char *\fP\fIbp\fP\fB, const char *\fP\fIname\fP\fB);\fP
+\fBint tgetent(char *\fIbp\fB, const char *\fIname\fB);\fR
.br
-\fBint tgetflag(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetflag(const char *\fIid\fB);\fR
.br
-\fBint tgetnum(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetnum(const char *\fIid\fB);\fR
.br
-\fBchar *tgetstr(const char *\fP\fIid\fP\fB, char **\fP\fIarea\fP\fB);\fP
+\fBchar *tgetstr(const char *\fIid\fB, char **\fIarea\fB);\fR
.br
-\fBchar *tgoto(const char *\fP\fIcap\fP\fB, int \fP\fIcol\fP\fB, int \fP\fIrow\fP\fB);\fP
+\fBchar *tgoto(const char *\fIcap\fB, int \fIcol\fB, int \fIrow\fB);\fR
.br
-\fBint tputs(const char *\fP\fIstr\fP\fB, int \fP\fIaffcnt\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR
.br
.SH DESCRIPTION
These routines are included as a conversion aid for programs that use
Thus, they
can only be used to query the capabilities of entries for which a
terminfo entry has been compiled.
-.SS INITIALIZATION
+.SS Initialization
.PP
The \fBtgetent\fP routine loads the entry for \fIname\fP.
It returns:
description is marked with the \fIgeneric\fP capability,
or if the terminal description has cursor-addressing.
.RE
-.SS CAPABILITY VALUES
+.SS Capability Values
.PP
The \fBtgetflag\fP routine gets the boolean entry for \fIid\fP,
or zero if it is not available.
\fBtgetflag\fP,
\fBtgetnum\fP and
\fBtgetstr\fP are compared in lookups.
-.SS FORMATTING CAPABILITIES
+.SS Formatting Capabilities
.PP
The \fBtgoto\fP routine expands the given capability using the parameters.
.bP
The \fBtputs\fP routine is described on the \fBcurs_terminfo\fP(3X) manual
page.
It can retrieve capabilities by either termcap or terminfo name.
-.SS GLOBAL VARIABLES
+.SS Global Variables
.PP
The variables
\fBPC\fP,
\fBBC\fP is used in the \fBtgoto\fP emulation.
The variable \fBospeed\fP is set by ncurses in a system-specific coding
to reflect the terminal speed.
+.SS Releasing Memory
+The termcap functions provide no means for freeing memory,
+because legacy termcap implementations used only the buffer
+areas provided by the caller via \fBtgetent\fP and \fBtgetstr\fP.
+Those buffers are unused in terminfo.
+.PP
+On the other hand, terminfo allocates memory.
+It uses \fBsetupterm\fP to retrieve the data used by \fBtgetent\fP
+and the functions which return capability values such as \fBtgetstr\fP.
+One could use
+.sp
+ \fBdel_curterm(cur_term);\fP
+.sp
+.PP
+to free this memory, but there is an additional complication with ncurses.
+It uses a fixed-size \fIpool\fP of storage locations,
+one per setting of the \fBTERM\fP variable when \fBtgetent\fP is called.
+The \fBscreen\fP(1) program relies upon this arrangement,
+to improve its performance.
+.PP
+An application which uses only the low-level termcap functions could
+free the memory using \fBdel_curterm\fP,
+because the pool is freed using other functions
+(see \fBcurs_memleaks\fP(3X)).
.
.SH RETURN VALUE
Except where explicitly noted,