ncurses 6.4 - patch 20230429

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

diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x
index 9244cf0cb2c89f2cdbb2dfce9bee10209caa39dd..080b31850395c981d018829ec46a647fa77ad8d8 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,2023 Thomas E. Dickey                                *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_termcap.3x,v 1.52 2021/12/25 21:31:00 tom Exp $
+.\" $Id: curs_termcap.3x,v 1.58 2023/04/16 18:16:40 tom Exp $
 .TH curs_termcap 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -66,17 +66,17 @@
 .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
@@ -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.
-.SS INITIALIZATION
+.SS Initialization
 .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
-.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.
@@ -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.
-.SS FORMATTING CAPABILITIES
+.SS Formatting Capabilities
 .PP
 The \fBtgoto\fP routine expands the given capability using the parameters.
 .bP
@@ -173,7 +173,13 @@ It does this also for calls requiring only a single parameter.
 In that case, the first parameter is merely a placeholder.
 .bP
 Normally the ncurses library is compiled with terminfo support.
-In that case, \fBtgoto\fP uses \fBtparm\fP(3X) (a more capable formatter).
+In that case, \fBtgoto\fP uses an internal version of
+\fBtparm\fP(3X) (a more capable formatter).
+.IP
+With terminfo support, \fBtgoto\fP is able to use some of the terminfo
+features, but not all.
+In particular, it allows only numeric parameters;
+\fBtparm\fP supports string parameters.
 .IP
 However, \fBtparm\fP is not a \fItermcap\fP feature,
 and portable \fItermcap\fP applications should not rely upon its availability.
@@ -181,7 +187,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.
-.SS GLOBAL VARIABLES
+.SS Global Variables
 .PP
 The variables
 \fBPC\fP,
@@ -197,6 +203,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.
+.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,
@@ -205,6 +235,20 @@ routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
 completion.
 .PP
 Routines that return pointers return \fBNULL\fP on error.
+.PP
+A few special cases apply:
+.bP
+If the terminal database has not been initialized,
+these return an error.
+.bP
+The calls with a string parameter (\fBtgoto\fP, \fBtputs\fP)
+check if the string is null, or cancelled.
+Those return an error.
+.bP
+A call to \fBtgoto\fP using a capability with string parameters is an error.
+.bP
+A call to \fBtgoto\fP using a capability with more than two parameters
+is an error.
 .SH BUGS
 If you call \fBtgetstr\fP to fetch \fBca\fP or any other parameterized string,
 be aware that it will be returned in terminfo notation, not the older and