]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/curs_terminfo.3x.html
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.3 - patch 20220212
[ncurses.git] / doc / html / man / curs_terminfo.3x.html
diff --git a/doc/html/man/curs_terminfo.3x.html b/doc/html/man/curs_terminfo.3x.html
index b54484cb865e83cde20256e17582a39554405fc7..061421aa79436dc75ed9ede27b0deb8c67ea782e 100644 (file)
--- a/doc/html/man/curs_terminfo.3x.html
+++ b/doc/html/man/curs_terminfo.3x.html
@@ -1,6 +1,6 @@
 <!--
   ****************************************************************************
 <!--
   ****************************************************************************
-  * 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,9 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_terminfo.3x,v 1.75 2021/06/17 21:11:08 tom Exp @
+  * @Id: curs_terminfo.3x,v 1.81 2022/02/12 20:05:11 tom Exp @
+  * ***************************************************************************
+  * ***************************************************************************
   * ***************************************************************************
   * ***************************************************************************
   * ***************************************************************************
   * ***************************************************************************
   * ***************************************************************************
   * ***************************************************************************
@@ -43,7 +45,7 @@
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>curs_terminfo 3x</TITLE>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>curs_terminfo 3x</TITLE>
 <link rel="author" href="mailto:bug-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
 </HEAD>
 <BODY>
 <H1 class="no-header">curs_terminfo 3x</H1>
 </HEAD>
 <BODY>
 <H1 class="no-header">curs_terminfo 3x</H1>
@@ -289,7 +291,7 @@
        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
 
        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to  use  the  attribute
        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
 
        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to  use  the  attribute
-       constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
+       constants with the <STRONG>WA_</STRONG> prefix.
 
        X/Open  Curses  reserves  the <EM>opts</EM> argument for future use, saying that
        applications must provide a null pointer for that argument.  As an  ex-
 
        X/Open  Curses  reserves  the <EM>opts</EM> argument for future use, saying that
        applications must provide a null pointer for that argument.  As an  ex-
@@ -301,7 +303,7 @@
 
        While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions which do not use the high-
        level curses state, they are declared in <STRONG>&lt;curses.h&gt;</STRONG> because SystemV did
 
        While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions which do not use the high-
        level curses state, they are declared in <STRONG>&lt;curses.h&gt;</STRONG> because SystemV did
-       this (see <STRONG>HISTORY</STRONG>).
+       this (see <EM>HISTORY</EM>).
 
 
 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
@@ -348,9 +350,34 @@
               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
 
 
               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
 
 
+</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
+       Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal
+       description.  As a side-effect, it sets <STRONG>cur_term</STRONG> to point to this memo-
+       ry.  If an application calls
+
+            <STRONG>del_curterm(cur_term);</STRONG>
+
+       the memory will be freed.
+
+       The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage  allocated
+       by <STRONG>setupterm</STRONG>:
+
+       <STRONG>o</STRONG>   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 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
+
+       <STRONG>o</STRONG>   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 <STRONG>TERMINAL</STRONG> structure.
+
+       The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>.  Normally
+       they do not free this memory, but it is possible to do that  using  the
+       <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function.
+
+
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-       Routines that return an integer return <STRONG>ERR</STRONG> upon failure  and  <STRONG>OK</STRONG>  (SVr4
-       only  specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
+       Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+       only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful  com-
        pletion, unless otherwise noted in the preceding routine descriptions.
 
        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
        pletion, unless otherwise noted in the preceding routine descriptions.
 
        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
@@ -372,25 +399,25 @@
                ditions are documented above.
 
           <STRONG>tputs</STRONG>
                ditions are documented above.
 
           <STRONG>tputs</STRONG>
-               returns  an error if the string parameter is null.  It does not
-               detect I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the  return
+               returns an error if the string parameter is null.  It does  not
+               detect  I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
                value of the output function <EM>putc</EM>.
 
 
 </PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
                value of the output function <EM>putc</EM>.
 
 
 </PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
-       This  implementation  provides a few macros for compatibility with sys-
-       tems  before  SVr4  (see  <STRONG>HISTORY</STRONG>).   Those  include  <STRONG>crmode</STRONG>,  <STRONG>fixterm</STRONG>,
+       This implementation provides a few macros for compatibility  with  sys-
+       tems  before  SVr4  (see  <EM>HISTORY</EM>).   Those  include  <STRONG>crmode</STRONG>,  <STRONG>fixterm</STRONG>,
        <STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
 
        <STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
 
-       In  SVr4,  those  are  found in <STRONG>&lt;curses.h&gt;</STRONG>, but except for <STRONG>setterm</STRONG>, are
+       In SVr4, those are found in <STRONG>&lt;curses.h&gt;</STRONG>, but  except  for  <STRONG>setterm</STRONG>,  are
        likewise macros.  The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
        likewise macros.  The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
-       page.   The  manual page notes that the <STRONG>setterm</STRONG> routine was replaced by
+       page.  The manual page notes that the <STRONG>setterm</STRONG> routine was  replaced  by
        <STRONG>setupterm</STRONG>, stating that the call:
 
              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
 
        provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, and is not recommend-
        <STRONG>setupterm</STRONG>, stating that the call:
 
              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
 
        provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, and is not recommend-
-       ed  for  new programs.  This implementation provides each of those sym-
+       ed for new programs.  This implementation provides each of  those  sym-
        bols as macros for BSD compatibility,
 
 
        bols as macros for BSD compatibility,
 
 
@@ -403,7 +430,7 @@
        fixterm     restore tty to "in curses" state
        gettmode    establish current tty modes
        mvcur       low level cursor motion
        fixterm     restore tty to "in curses" state
        gettmode    establish current tty modes
        mvcur       low level cursor motion
-       putp        utility  function that uses <STRONG>tputs</STRONG> to send char-
+       putp        utility function that uses <STRONG>tputs</STRONG> to send  char-
                    acters via <STRONG>putchar</STRONG>.
        resetterm   set tty modes to "out of curses" state
        resetty     reset tty flags to stored value
                    acters via <STRONG>putchar</STRONG>.
        resetterm   set tty modes to "out of curses" state
        resetty     reset tty flags to stored value
@@ -414,10 +441,10 @@
        tparm       instantiate a string expression with parameters
        tputs       apply padding information to a string
        vidattr     like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
        tparm       instantiate a string expression with parameters
        tputs       apply padding information to a string
        vidattr     like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
-       vidputs     output a string to put terminal in a  specified
+       vidputs     output  a string to put terminal in a specified
                    video attribute mode
 
                    video attribute mode
 
-       The  programming  manual  also mentioned functions provided for termcap
+       The programming manual also mentioned functions  provided  for  termcap
        compatibility (commenting that they "may go away at a later date"):
 
        <STRONG>Function</STRONG>   <STRONG>Description</STRONG>
        compatibility (commenting that they "may go away at a later date"):
 
        <STRONG>Function</STRONG>   <STRONG>Description</STRONG>
@@ -430,19 +457,20 @@
        tputs      apply padding to capability, calling
                   a function to put characters
 
        tputs      apply padding to capability, calling
                   a function to put characters
 
-       Early  terminfo  programs  obtained capability values from the <STRONG>TERMINAL</STRONG>
+       Early terminfo programs obtained capability values  from  the  <STRONG>TERMINAL</STRONG>
        structure initialized by <STRONG>setupterm</STRONG>.
 
        structure initialized by <STRONG>setupterm</STRONG>.
 
-       SVr3 extended terminfo by adding functions to retrieve capability  val-
+       SVr3  extended terminfo by adding functions to retrieve capability val-
        ues (like the termcap interface), and reusing tgoto and tputs:
 
        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
        -------------------------------------------
        tigetflag   get boolean entry for given <EM>id</EM>
        ues (like the termcap interface), and reusing tgoto and tputs:
 
        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
        -------------------------------------------
        tigetflag   get boolean entry for given <EM>id</EM>
+
        tigetnum    get numeric entry for given <EM>id</EM>
        tigetstr    get string entry for given <EM>id</EM>
 
        tigetnum    get numeric entry for given <EM>id</EM>
        tigetstr    get string entry for given <EM>id</EM>
 
-       SVr3  also replaced several of the SVr2 terminfo functions which had no
+       SVr3 also replaced several of the SVr2 terminfo functions which had  no
        counterpart in the termcap interface, documenting them as obsolete:
 
        <STRONG>Function</STRONG>    <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
        counterpart in the termcap interface, documenting them as obsolete:
 
        <STRONG>Function</STRONG>    <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
@@ -455,20 +483,27 @@
        saveterm    def_prog_mode
        setterm     setupterm
 
        saveterm    def_prog_mode
        setterm     setupterm
 
-       SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions,  along  with  <STRONG>putp</STRONG>,
-       <STRONG>tparm</STRONG>  and  <STRONG>tputs</STRONG>.  The latter were needed to support padding, and han-
-       dling functions such as <STRONG>vidattr</STRONG> (which used more than the  two  parame-
+       SVr3  kept  the  <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
+       <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>.  The latter were needed to support padding,  and  han-
+       dling  functions  such as <STRONG>vidattr</STRONG> (which used more than the two parame-
        ters supported by <STRONG>tgoto</STRONG>).
 
        ters supported by <STRONG>tgoto</STRONG>).
 
-       SVr3  introduced  the functions for switching between terminal descrip-
-       tions, e.g., <STRONG>set_curterm</STRONG>.  The various global variables such  as  <STRONG>bool-</STRONG>
-       <STRONG>names</STRONG> were mentioned in the programming manual at this point.
+       SVr3 introduced the functions for switching between  terminal  descrip-
+       tions, e.g., <STRONG>set_curterm</STRONG>.  Some of that was incremental improvements to
+       the SVr2 library:
+
+       <STRONG>o</STRONG>   The <STRONG>TERMINAL</STRONG> type definition was introduced  in  SVr3.01,  for  the
+           <STRONG>term</STRONG> structure provided in SVr2.
+
+       <STRONG>o</STRONG>   The  various  global  variables such as <STRONG>boolnames</STRONG> were mentioned in
+           the programming manual at this point,  though  the  variables  were
+           provided in SVr2.
 
        SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
 
        There are other low-level functions declared in the curses header files
        on Unix systems, but none were documented.  The functions marked "obso-
 
        SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
 
        There are other low-level functions declared in the curses header files
        on Unix systems, but none were documented.  The functions marked "obso-
-       lete" remained in use by the Unix <STRONG>vi</STRONG> editor.
+       lete" remained in use by the Unix <STRONG>vi(1)</STRONG> editor.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
@@ -570,8 +605,9 @@
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,    <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,   <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
-       <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,   <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>,
+       <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG>ter-</STRONG>
+       <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG>
 
 
 
 
 
 
@@ -589,6 +625,7 @@
 <li><a href="#h3-Output-Functions">Output Functions</a></li>
 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
 <li><a href="#h3-Output-Functions">Output Functions</a></li>
 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
+<li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a>
 </ul>
 </li>
 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a>
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/