ncurses 6.3 - patch 20220416

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

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 8ad906e0b1b8b71560cbf3a62108517f340e10e8..9abad1b04c3498b289aac7fbf9479eff5204e3d3 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2022 Thomas E. Dickey                                *

 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_terminfo.3x,v 1.79 2021/12/25 21:34:58 tom Exp $
+.\" $Id: curs_terminfo.3x,v 1.81 2022/02/12 20:05:11 tom Exp $

 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .TH curs_terminfo 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -76,37 +76,37 @@
 \fBconst char * const strcodes[];\fP
 \fBconst char * const strfnames[];\fP
 .sp
 \fBconst char * const strcodes[];\fP
 \fBconst char * const strfnames[];\fP
 .sp

-\fBint setupterm(const char *\fP\fIterm\fP\fB, int \fP\fIfiledes\fP\fB, int *\fP\fIerrret\fP\fB);\fP
+\fBint setupterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR

 .br
 .br

-\fBTERMINAL *set_curterm(TERMINAL *\fP\fInterm\fP\fB);\fP
+\fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR

 .br
 .br

-\fBint del_curterm(TERMINAL *\fP\fIoterm\fP\fB);\fP
+\fBint del_curterm(TERMINAL *\fIoterm\fB);\fR

 .br
 .br

-\fBint restartterm(const char *\fP\fIterm\fP\fB, int \fP\fIfiledes\fP\fB, int *\fP\fIerrret\fP\fB);\fP
+\fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR

 .sp
 .sp

-\fBchar *tparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tparm(const char *\fIstr\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
 .br

-\fBint putp(const char *\fP\fIstr\fP\fB);\fP
+\fBint putp(const char *\fIstr\fB);\fR

 .sp
 .sp

-\fBint vidputs(chtype \fP\fIattrs\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR

 .br
 .br

-\fBint vidattr(chtype \fP\fIattrs\fP\fB);\fP
+\fBint vidattr(chtype \fIattrs\fB);\fR

 .br
 .br

-\fBint vid_puts(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB, int (*\fP\fIputc\fP\fB)(int));\fP
+\fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR

 .br
 .br

-\fBint vid_attr(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fP
+\fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR

 .sp
 .sp

-\fBint mvcur(int \fP\fIoldrow\fP\fB, int \fP\fIoldcol\fP\fB, int \fP\fInewrow\fP, int \fP\fInewcol\fP\fB);\fP
+\fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR

 .sp
 .sp

-\fBint tigetflag(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetflag(const char *\fIcapname\fB);\fR

 .br
 .br

-\fBint tigetnum(const char *\fP\fIcapname\fP\fB);\fP
+\fBint tigetnum(const char *\fIcapname\fB);\fR

 .br
 .br

-\fBchar *tigetstr(const char *\fP\fIcapname\fP\fB);\fP
+\fBchar *tigetstr(const char *\fIcapname\fB);\fR

 .sp
 .sp

-\fBchar *tiparm(const char *\fP\fIstr\fP\fB, ...);\fP
+\fBchar *tiparm(const char *\fIstr\fB, ...);\fR

 .br
 .fi
 .SH DESCRIPTION
 .br
 .fi
 .SH DESCRIPTION


@@ -313,7 +313,7 @@ not applicable.
 \fIputc\fP is a \fBputchar\fP-like routine to which
 the characters are passed, one at a time.
 .PP
 \fIputc\fP is a \fBputchar\fP-like routine to which
 the characters are passed, one at a time.
 .PP

-The \fBputp\fP routine calls \fBtputs(\fP\fIstr\fP\fB, 1, putchar)\fP.
+The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR.

 The output of \fBputp\fP always goes to \fBstdout\fP, rather than
 the \fIfiledes\fP specified in \fBsetupterm\fP.
 .PP
 The output of \fBputp\fP always goes to \fBstdout\fP, rather than
 the \fIfiledes\fP specified in \fBsetupterm\fP.
 .PP


@@ -407,6 +407,32 @@ for each of the predefined \fBterminfo\fP variables:
 .br
 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
 .RE
 .br
 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
 .RE

+.\" ***************************************************************************
+.SS Releasing Memory
+Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
+description.  As a side-effect, it sets \fBcur_term\fP to point to this memory.
+If an application calls
+.sp
+       \fBdel_curterm(cur_term);\fP
+.sp
+the memory will be freed.
+.PP
+The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage
+allocated by \fBsetupterm\fP: 
+.bP
+the \*(``static\*('' terminfo variables [a-z].
+Before ncurses 6.3, those were shared by all screens.
+With ncurses 6.3, those are allocated per screen.
+See \fBterminfo\fP(\*n) for details.
+.bP
+to improve performance, ncurses 6.3 caches the result of analyzing terminfo
+strings for their parameter types.
+That is stored as a binary tree referenced from the \fBTERMINAL\fP structure.
+.PP
+The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP.
+Normally they do not free this memory, but it is possible to do that using
+the \fBdelscreen\fP(3X) function.
+.\" ***************************************************************************

 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
 (SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('')
 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
 (SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('')


@@ -461,9 +487,9 @@ The one function, \fBsetterm\fP, is mentioned in the manual page.
 The manual page notes that the \fBsetterm\fP routine
 was replaced by \fBsetupterm\fP, stating that the call:
 .sp
 The manual page notes that the \fBsetterm\fP routine
 was replaced by \fBsetupterm\fP, stating that the call:
 .sp

-      \fBsetupterm(\fP\fIterm\fP\fB, 1, (int *)0)\fP
+      \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR

 .sp
 .sp

-provides the same functionality as \fBsetterm(\fP\fIterm\fP\fB)\fP,
+provides the same functionality as \fBsetterm(\fIterm\fB)\fR,

 and is not recommended for new programs.
 This implementation provides each of those symbols
 as macros for BSD compatibility,
 and is not recommended for new programs.
 This implementation provides each of those symbols
 as macros for BSD compatibility,


@@ -675,6 +701,7 @@ In that case, the old location is unknown.
 \fBcurses\fP(3X),
 \fBcurs_initscr\fP(3X),
 \fBcurs_kernel\fP(3X),
 \fBcurses\fP(3X),
 \fBcurs_initscr\fP(3X),
 \fBcurs_kernel\fP(3X),

+\fBcurs_memleaks\fP(3X),

 \fBcurs_termcap\fP(3X),
 \fBcurs_variables\fP(3X),
 \fBterm_variables\fP(3X),
 \fBcurs_termcap\fP(3X),
 \fBcurs_variables\fP(3X),
 \fBterm_variables\fP(3X),