ncurses 6.3 - patch 20220416

[ncurses.git] / man / curs_termcap.3x

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 9244cf0cb2c89f2cdbb2dfce9bee10209caa39dd..e073d940cdd29003d908423090e2339a3653ea22 100644 (file)
--- a/man/curs_termcap.3x
+++ b/man/curs_termcap.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" 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  *
 .\" Copyright 1998-2017,2018 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 `` ``
 .TH curs_termcap 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -66,17 +66,17 @@
 .br
 \fBextern @NCURSES_OSPEED@ ospeed;\fP
 .sp
 .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
 .br

-\fBint tgetflag(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetflag(const char *\fIid\fB);\fR

 .br
 .br

-\fBint tgetnum(const char *\fP\fIid\fP\fB);\fP
+\fBint tgetnum(const char *\fIid\fB);\fR

 .br
 .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
 .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
 .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
 .br
 .SH DESCRIPTION
 These routines are included as a conversion aid for programs that use


@@ -86,7 +86,7 @@ routines are emulated using the \fIterminfo\fP database.
 Thus, they
 can only be used to query the capabilities of entries for which a
 terminfo entry has been compiled.
 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:
 .PP
 The \fBtgetent\fP routine loads the entry for \fIname\fP.
 It returns:


@@ -118,7 +118,7 @@ The \fItermcap\fP library does not check if the terminal
 description is marked with the \fIgeneric\fP capability,
 or if the terminal description has cursor-addressing.
 .RE
 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.
 .PP
 The \fBtgetflag\fP routine gets the boolean entry for \fIid\fP,
 or zero if it is not available.


@@ -152,7 +152,7 @@ Only the first two characters of the \fBid\fP parameter of
 \fBtgetflag\fP,
 \fBtgetnum\fP and
 \fBtgetstr\fP are compared in lookups.
 \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
 .PP
 The \fBtgoto\fP routine expands the given capability using the parameters.
 .bP


@@ -181,7 +181,7 @@ and portable \fItermcap\fP applications should not rely upon its availability.
 The \fBtputs\fP routine is described on the \fBcurs_terminfo\fP(3X) manual
 page.
 It can retrieve capabilities by either termcap or terminfo name.
 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,
 .PP
 The variables
 \fBPC\fP,


@@ -197,6 +197,30 @@ respectively.
 \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.
 \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,
 .
 .SH RETURN VALUE
 Except where explicitly noted,