doc/html/man/curs_terminfo.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2022,2023 Thomas E. Dickey                                *
   5   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: curs_terminfo.3x,v 1.94 2023/08/06 00:03:04 tom Exp @
  32   * ***************************************************************************
  33   * ***************************************************************************
  34   * ***************************************************************************
  35   * ***************************************************************************
  36   * ***************************************************************************
  37   * ***************************************************************************
  38   * ***************************************************************************
  39   * ***************************************************************************
  40   * ***************************************************************************
  41 -->
  42 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  43 <HTML>
  44 <HEAD>
  45 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  46 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  47 <TITLE>curs_terminfo 3x 2023-08-05 ncurses 6.4 Library calls</TITLE>
  48 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  49
  50 </HEAD>
  51 <BODY>
  52 <H1 class="no-header">curs_terminfo 3x 2023-08-05 ncurses 6.4 Library calls</H1>
  53 <PRE>
  54 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>                Library calls               <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
  55
  56
  57
  58
  59 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  60        <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>,
  61        <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tiparm_s</STRONG>, <STRONG>tiscan_s</STRONG>, <STRONG>tparm</STRONG>,
  62        <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG> interfaces to
  63        terminfo database
  64
  65
  66 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  67        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  68        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
  69
  70        <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
  71
  72        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG>
  73        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG>
  74        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG>
  75        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG>
  76        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG>
  77        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG>
  78        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG>
  79        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG>
  80        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>
  81
  82        <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
  83        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
  84        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
  85        <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
  86
  87        <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
  88             <EM>or</EM>
  89        <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> <EM>...</EM> <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>
  90
  91        <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
  92        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
  93
  94        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
  95        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  96        <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
  97        <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
  98
  99        <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM>, int <EM>newcol</EM><STRONG>);</STRONG>
 100
 101        <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
 102        <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
 103        <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
 104
 105        <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
 106
 107        /* extensions */
 108        <STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
 109        <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
 110
 111
 112 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 113        These low-level routines must be called by programs that have  to  deal
 114        directly with the <STRONG>terminfo</STRONG> database to handle certain terminal capabil-
 115        ities, such as programming function keys.  For all other functionality,
 116        <STRONG>curses</STRONG> routines are more suitable and their use is recommended.
 117
 118        None  of  these  functions  use  (or  are aware of) multibyte character
 119        strings such as UTF-8:
 120
 121        <STRONG>o</STRONG>   capability names use the POSIX portable character set
 122
 123        <STRONG>o</STRONG>   capability string values have  no  associated  encoding;  they  are
 124            strings of 8-bit characters.
 125
 126
 127 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
 128        Initially, <STRONG>setupterm</STRONG> should be called.  The high-level curses functions
 129        <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level  set  of
 130        terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
 131
 132        Applications  can  use  the  terminal capabilities either directly (via
 133        header definitions), or by special functions.  The header  files  <STRONG>curs-</STRONG>
 134        <STRONG>es.h</STRONG>  and  <STRONG>term.h</STRONG> should be included (in this order) to get the defini-
 135        tions for these strings, numbers, and flags.
 136
 137        The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized  by  <STRONG>setupterm</STRONG>
 138        as follows:
 139
 140        <STRONG>o</STRONG>   If  <STRONG>use_env(FALSE)</STRONG>  has  been  called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>
 141            specified in <STRONG>terminfo</STRONG> are used.
 142
 143        <STRONG>o</STRONG>   Otherwise, if the environment variables <STRONG>LINES</STRONG>  and  <STRONG>COLUMNS</STRONG>  exist,
 144            their values are used.  If these environment variables do not exist
 145            and the program is running in a window, the current window size  is
 146            used.   Otherwise,  if  the environment variables do not exist, the
 147            values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
 148            used.
 149
 150        Parameterized  strings  should  be  passed through <STRONG>tparm</STRONG> to instantiate
 151        them.  All <STRONG>terminfo</STRONG> strings (including the output of <STRONG>tparm</STRONG>)  should  be
 152        printed  with  <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call <STRONG>reset_shell_mode</STRONG> to restore the tty
 153        modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
 154
 155        Programs which use cursor addressing should
 156
 157        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and
 158
 159        <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.
 160
 161        Programs which execute shell subprocesses should
 162
 163        <STRONG>o</STRONG>   call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the  shell  is
 164            called and
 165
 166        <STRONG>o</STRONG>   output  <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from
 167            the shell.
 168
 169        The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing  the
 170        <STRONG>terminfo</STRONG>  structures,  but  does  not  set up the output virtualization
 171        structures used by <STRONG>curses</STRONG>.  These are its parameters:
 172
 173           <EM>term</EM> is the terminal type, a character string.  If <EM>term</EM> is null, the
 174                environment variable <STRONG>TERM</STRONG> is used.
 175
 176           <EM>filedes</EM>
 177                is  the  file  descriptor used for getting and setting terminal
 178                I/O modes.
 179
 180                Higher-level applications use <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> for initializing  the
 181                terminal,  passing  an  output <EM>stream</EM> rather than a <EM>descriptor</EM>.
 182                In curses, the two are  the  same  because  <STRONG>newterm</STRONG>  calls  <STRONG>se-</STRONG>
 183                <STRONG>tupterm</STRONG>,  passing  the  file descriptor derived from its output
 184                stream parameter.
 185
 186           <EM>errret</EM>
 187                points to an optional location where an error status can be re-
 188                turned  to  the  caller.  If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
 189                returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a  status  value  in  the  integer
 190                pointed  to by <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with sta-
 191                tus of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
 192
 193                If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
 194
 195                <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot  be  used  for
 196                     curses applications.
 197
 198                     <STRONG>setupterm</STRONG>  determines  if  the entry is a hardcopy type by
 199                     checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capability.
 200
 201                <STRONG>0</STRONG>    means that the terminal could not be found, or that it  is
 202                     a  generic  type, having too little information for curses
 203                     applications to run.
 204
 205                     <STRONG>setupterm</STRONG> determines if the entry is  a  generic  type  by
 206                     checking the <STRONG>gn</STRONG> (<STRONG>generic_type</STRONG>) capability.
 207
 208                <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not be found.
 209
 210                If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon find-
 211                ing an error and exits.  Thus, the simplest call is:
 212
 213                      <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
 214
 215                which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
 216
 217
 218 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
 219        The <STRONG>setupterm</STRONG> routine stores its information about the  terminal  in  a
 220        <STRONG>TERMINAL</STRONG>  structure  pointed to by the global variable <STRONG>cur_term</STRONG>.  If it
 221        detects an error, or decides that the terminal is unsuitable  (hardcopy
 222        or  generic),  it discards this information, making it not available to
 223        applications.
 224
 225        If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type,  it  will
 226        reuse  the  information.   It maintains only one copy of a given termi-
 227        nal's capabilities in memory.  If it is called for  different  terminal
 228        types,  <STRONG>setupterm</STRONG>  allocates new storage for each set of terminal capa-
 229        bilities.
 230
 231        The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes  all  of  the
 232        <STRONG>terminfo</STRONG>  boolean,  numeric,  and  string variables use the values from
 233        <EM>nterm</EM>.  It returns the old value of <STRONG>cur_term</STRONG>.
 234
 235        The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM>  and  makes
 236        it available for further use.  If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, refer-
 237        ences to any of the <STRONG>terminfo</STRONG> boolean,  numeric,  and  string  variables
 238        thereafter  may  refer  to  invalid  memory locations until another <STRONG>se-</STRONG>
 239        <STRONG>tupterm</STRONG> has been called.
 240
 241        The <STRONG>restartterm</STRONG> routine is similar to  <STRONG>setupterm</STRONG>  and  <STRONG>initscr</STRONG>,  except
 242        that it is called after restoring memory to a previous state (for exam-
 243        ple, when reloading a game saved as a core  image  dump).   <STRONG>restartterm</STRONG>
 244        assumes  that the windows and the input and output options are the same
 245        as when memory was saved, but the terminal type and baud  rate  may  be
 246        different.   Accordingly,  <STRONG>restartterm</STRONG>  saves  various  tty state bits,
 247        calls <STRONG>setupterm</STRONG>, and then restores the bits.
 248
 249
 250 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
 251        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with  parameters  <EM>pi</EM>.   A
 252        pointer  is  returned to the result of <EM>str</EM> with the parameters applied.
 253        Application developers should keep in mind these quirks of  the  inter-
 254        face:
 255
 256        <STRONG>o</STRONG>   Although  <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the
 257            prototype expects <STRONG>long</STRONG> (integer) values.
 258
 259        <STRONG>o</STRONG>   Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal capa-
 260            bilities require no more than one or two parameters.
 261
 262        <STRONG>o</STRONG>   Padding  information  is  ignored  by  <STRONG>tparm</STRONG>;  it is interpreted by
 263            <STRONG>tputs</STRONG>.
 264
 265        <STRONG>o</STRONG>   The capability string is  null-terminated.   Use  "\200"  where  an
 266            ASCII NUL is needed in the output.
 267
 268        <STRONG>tiparm</STRONG>  is  a  newer  form of <STRONG>tparm</STRONG> which uses <EM>&lt;stdarg.h&gt;</EM> rather than a
 269        fixed-parameter list.  Its numeric parameters are integers (int) rather
 270        than longs.
 271
 272        Both  <STRONG>tparm</STRONG>  and  <STRONG>tiparm</STRONG>  assume that the application passes parameters
 273        consistent with the terminal description.  Two extensions are  provided
 274        as alternatives to deal with untrusted data:
 275
 276        <STRONG>o</STRONG>   <STRONG>tiparm_s</STRONG>  is an extension which is a safer formatting function than
 277            <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>, because it allows the developer to tell the curses
 278            library  how  many  parameters to expect in the parameter list, and
 279            which may be string parameters.
 280
 281            The <EM>mask</EM> parameter has one bit set for each of the  parameters  (up
 282            to 9) which will be passed as char* rather than numbers.
 283
 284        <STRONG>o</STRONG>   The  extension <STRONG>tiscan_s</STRONG> allows the application to inspect a format-
 285            ting capability to see what the curses library would assume.
 286
 287
 288 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
 289        The <STRONG>tputs</STRONG> routine applies padding information  (i.e.,  by  interpreting
 290        marker  embedded  in  the  terminfo capability such as "$&lt;5&gt;" as 5 mil-
 291        liseconds) to the string <EM>str</EM> and outputs it:
 292
 293        <STRONG>o</STRONG>   The <EM>str</EM> parameter must be a terminfo string variable or the  return
 294            value from <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
 295
 296            The  <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface,
 297            which happens to share this function name with the <EM>terminfo</EM>  inter-
 298            face.
 299
 300        <STRONG>o</STRONG>   <EM>affcnt</EM> is the number of lines affected, or 1 if not applicable.
 301
 302        <STRONG>o</STRONG>   <EM>putc</EM>  is a <STRONG>putchar</STRONG>-like routine to which the characters are passed,
 303            one at a time.
 304
 305        The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>.  The output of <STRONG>putp</STRONG>  al-
 306        ways goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.
 307
 308        The  <STRONG>vidputs</STRONG>  routine  displays the string on the terminal in the video
 309        attribute mode <EM>attrs</EM>, which is any combination of the attributes listed
 310        in  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.   The characters are passed to the <STRONG>putchar</STRONG>-like routine
 311        <EM>putc</EM>.
 312
 313        The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
 314        through <STRONG>putchar</STRONG>.
 315
 316        The  <STRONG>vid_attr</STRONG>  and <STRONG>vid_puts</STRONG> routines correspond to vidattr and vidputs,
 317        respectively.  They use a set of arguments for representing  the  video
 318        attributes plus color, i.e.,
 319
 320        <STRONG>o</STRONG>   <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
 321
 322        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
 323
 324        The  <STRONG>vid_attr</STRONG>  and  <STRONG>vid_puts</STRONG> routines are designed to use the attribute
 325        constants with the <STRONG>WA_</STRONG> prefix.
 326
 327        X/Open Curses reserves the <EM>opts</EM> argument for future  use,  saying  that
 328        applications  must provide a null pointer for that argument.  As an ex-
 329        tension, this implementation allows <EM>opts</EM> to be used  as  a  pointer  to
 330        <STRONG>int</STRONG>, which overrides the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
 331
 332        The  <STRONG>mvcur</STRONG>  routine  provides low-level cursor motion.  It takes effect
 333        immediately (rather than at the next refresh).  Unlike the  other  low-
 334        level  output  functions,  which either write to the standard output or
 335        pass an output function parameter, <STRONG>mvcur</STRONG> uses an output file descriptor
 336        derived from the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.
 337
 338        While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions which do not use the high-
 339        level curses state, they are declared in <STRONG>&lt;curses.h&gt;</STRONG> because SystemV did
 340        this (see <EM>HISTORY</EM>).
 341
 342
 343 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
 344        The  <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value of the
 345        capability corresponding to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to  them,  such
 346        as  <STRONG>xenl</STRONG>.  The <EM>capname</EM> for each capability is given in the table column
 347        entitled <EM>capname</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 348
 349        These routines return special values to denote errors.
 350
 351        The <STRONG>tigetflag</STRONG> routine returns
 352
 353        <STRONG>-1</STRONG>     if <EM>capname</EM> is not a boolean capability, or
 354
 355        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
 356
 357        The <STRONG>tigetnum</STRONG> routine returns
 358
 359        <STRONG>-2</STRONG>     if <EM>capname</EM> is not a numeric capability, or
 360
 361        <STRONG>-1</STRONG>     if it is canceled or absent from the terminal description.
 362
 363        The <STRONG>tigetstr</STRONG> routine returns
 364
 365        <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
 366               if <EM>capname</EM> is not a string capability, or
 367
 368        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
 369
 370
 371 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
 372        These null-terminated arrays contain
 373
 374        <STRONG>o</STRONG>   the short terminfo names ("codes"),
 375
 376        <STRONG>o</STRONG>   the <STRONG>termcap</STRONG> names ("names"), and
 377
 378        <STRONG>o</STRONG>   the long terminfo names ("fnames")
 379
 380        for each of the predefined <STRONG>terminfo</STRONG> variables:
 381
 382               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
 383               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
 384               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
 385
 386
 387 </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
 388        Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal
 389        description.  As a side-effect, it sets <STRONG>cur_term</STRONG> to point to this memo-
 390        ry.  If an application calls
 391
 392                <STRONG>del_curterm(cur_term);</STRONG>
 393
 394        the memory will be freed.
 395
 396        The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage  allocated
 397        by <STRONG>setupterm</STRONG>:
 398
 399        <STRONG>o</STRONG>   the  "static"  terminfo variables [a-z].  Before ncurses 6.3, those
 400            were shared by all screens.  With ncurses 6.3, those are  allocated
 401            per screen.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
 402
 403        <STRONG>o</STRONG>   to  improve performance, ncurses 6.3 caches the result of analyzing
 404            terminfo strings for their parameter types.  That is  stored  as  a
 405            binary tree referenced from the <STRONG>TERMINAL</STRONG> structure.
 406
 407        The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>.  Normally
 408        they do not free this memory, but it is possible to do that  using  the
 409        <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function.
 410
 411
 412 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 413        Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
 414        only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful  com-
 415        pletion, unless otherwise noted in the preceding routine descriptions.
 416
 417        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
 418
 419        X/Open defines no error conditions.  In this implementation
 420
 421           <STRONG>del_curterm</STRONG>
 422                returns an error if its terminal parameter is null.
 423
 424           <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
 425
 426           <STRONG>restartterm</STRONG>
 427                returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
 428                error.
 429
 430           <STRONG>setupterm</STRONG>
 431                returns an error if it cannot allocate enough memory, or create
 432                the initial windows (stdscr, curscr, newscr).  Other error con-
 433                ditions are documented above.
 434
 435           <STRONG>tparm</STRONG>
 436                returns a null if the capability would require  unexpected  pa-
 437                rameters,  e.g., too many, too few, or incorrect types (strings
 438                where integers are expected, or vice versa).
 439
 440           <STRONG>tputs</STRONG>
 441                returns an error if the string parameter is null.  It does  not
 442                detect  I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
 443                value of the output function <EM>putc</EM>.
 444
 445
 446 </PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
 447        This implementation provides a few macros for compatibility  with  sys-
 448        tems  before  SVr4  (see  <EM>HISTORY</EM>).   Those  include  <STRONG>crmode</STRONG>,  <STRONG>fixterm</STRONG>,
 449        <STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
 450
 451        In SVr4, those are found in <STRONG>&lt;curses.h&gt;</STRONG>, but  except  for  <STRONG>setterm</STRONG>,  are
 452        likewise macros.  The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
 453        page.  The manual page notes that the <STRONG>setterm</STRONG> routine was  replaced  by
 454        <STRONG>setupterm</STRONG>, stating that the call:
 455
 456              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
 457
 458        provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, and is not recommend-
 459        ed for new programs.  This implementation provides each of  those  sym-
 460        bols as macros for BSD compatibility,
 461
 462
 463 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 464        SVr2 introduced the terminfo feature.  Its programming manual mentioned
 465        these low-level functions:
 466
 467        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
 468        ------------------------------------------------------------
 469        fixterm     restore tty to "in curses" state
 470        gettmode    establish current tty modes
 471        mvcur       low level cursor motion
 472        putp        utility function that uses <STRONG>tputs</STRONG> to send  char-
 473                    acters via <STRONG>putchar</STRONG>.
 474        resetterm   set tty modes to "out of curses" state
 475        resetty     reset tty flags to stored value
 476        saveterm    save current modes as "in curses" state
 477        savetty     store current tty flags
 478        setterm     establish terminal with given type
 479        setupterm   establish terminal with given type
 480        tparm       instantiate a string expression with parameters
 481        tputs       apply padding information to a string
 482        vidattr     like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
 483        vidputs     output  a string to put terminal in a specified
 484                    video attribute mode
 485
 486        The programming manual also mentioned functions  provided  for  termcap
 487        compatibility (commenting that they "may go away at a later date"):
 488
 489        <STRONG>Function</STRONG>   <STRONG>Description</STRONG>
 490        ------------------------------------------------
 491        tgetent    look up termcap entry for given <EM>name</EM>
 492        tgetflag   get boolean entry for given <EM>id</EM>
 493        tgetnum    get numeric entry for given <EM>id</EM>
 494        tgetstr    get string entry for given <EM>id</EM>
 495        tgoto      apply parameters to given capability
 496        tputs      apply padding to capability, calling
 497                   a function to put characters
 498
 499        Early terminfo programs obtained capability values  from  the  <STRONG>TERMINAL</STRONG>
 500        structure initialized by <STRONG>setupterm</STRONG>.
 501
 502        SVr3  extended terminfo by adding functions to retrieve capability val-
 503        ues (like the termcap interface), and reusing tgoto and tputs:
 504
 505        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
 506        -------------------------------------------
 507        tigetflag   get boolean entry for given <EM>id</EM>
 508        tigetnum    get numeric entry for given <EM>id</EM>
 509        tigetstr    get string entry for given <EM>id</EM>
 510
 511        SVr3 also replaced several of the SVr2 terminfo functions which had  no
 512        counterpart in the termcap interface, documenting them as obsolete:
 513
 514        <STRONG>Function</STRONG>    <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
 515        -----------------------------
 516        crmode      cbreak
 517        fixterm     reset_prog_mode
 518        gettmode    N/A
 519        nocrmode    nocbreak
 520        resetterm   reset_shell_mode
 521        saveterm    def_prog_mode
 522        setterm     setupterm
 523
 524        SVr3  kept  the  <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
 525        <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>.  The latter were needed to support padding,  and  han-
 526        dling  functions  such as <STRONG>vidattr</STRONG> (which used more than the two parame-
 527        ters supported by <STRONG>tgoto</STRONG>).
 528
 529        SVr3 introduced the functions for switching between  terminal  descrip-
 530        tions, e.g., <STRONG>set_curterm</STRONG>.  Some of that was incremental improvements to
 531        the SVr2 library:
 532
 533        <STRONG>o</STRONG>   The <STRONG>TERMINAL</STRONG> type definition was introduced  in  SVr3.01,  for  the
 534            <STRONG>term</STRONG> structure provided in SVr2.
 535
 536        <STRONG>o</STRONG>   The  various  global  variables such as <STRONG>boolnames</STRONG> were mentioned in
 537            the programming manual at this point,  though  the  variables  were
 538            provided in SVr2.
 539
 540        SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
 541
 542        There are other low-level functions declared in the curses header files
 543        on Unix systems, but none were documented.  The functions marked "obso-
 544        lete" remained in use by the Unix <STRONG>vi(1)</STRONG> editor.
 545
 546
 547 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 548
 549 </PRE><H3><a name="h3-Extensions">Extensions</a></H3><PRE>
 550        The  functions  marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
 551        are not found in SVr4 curses, 4.4BSD curses, or any other previous ver-
 552        sion of curses.
 553
 554
 555 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
 556        X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
 557
 558        The  function <STRONG>setterm</STRONG> is not described by X/Open and must be considered
 559        non-portable.  All other functions are as described by X/Open.
 560
 561
 562 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
 563        <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>.  This  is  not
 564        part of X/Open Curses, but is assumed by some applications.
 565
 566        Other  implementions  may not declare the capability name arrays.  Some
 567        provide them without declaring them.  X/Open does not specify them.
 568
 569        Extended terminal capability names, e.g., as defined by <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not
 570        stored in the arrays described here.
 571
 572
 573 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
 574        Older  versions  of  <STRONG>ncurses</STRONG> assumed that the file descriptor passed to
 575        <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
 576        the  corresponding stream.  In addition to the limitation that the ter-
 577        minal was left in block-buffered mode on exit (like System  V  curses),
 578        it  was  problematic  because  <STRONG>ncurses</STRONG>  did not allow a reliable way to
 579        cleanup on receiving SIGTSTP.
 580
 581        The current version (ncurses6) uses output buffers managed directly  by
 582        <STRONG>ncurses</STRONG>.  Some of the low-level functions described in this manual page
 583        write to the standard output.  They are not signal-safe.  The high-lev-
 584        el functions in <STRONG>ncurses</STRONG> use alternate versions of these functions using
 585        the more reliable buffering scheme.
 586
 587
 588 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
 589        The X/Open Curses prototypes are based on the SVr4 curses header decla-
 590        rations,  which  were defined at the same time the C language was first
 591        standardized in the late 1980s.
 592
 593        <STRONG>o</STRONG>   X/Open Curses uses <STRONG>const</STRONG>  less  effectively  than  a  later  design
 594            might,  in  some cases applying it needlessly to values are already
 595            constant, and in most cases overlooking parameters  which  normally
 596            would  use <STRONG>const</STRONG>.  Using constant parameters for functions which do
 597            not use <STRONG>const</STRONG> may prevent the program from compiling.  On the other
 598            hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent feature.
 599
 600            As  an  extension,  this implementation can be configured to change
 601            the function prototypes to use the <STRONG>const</STRONG> keyword.  The ncurses  ABI
 602            6 enables this feature by default.
 603
 604        <STRONG>o</STRONG>   X/Open  Curses  prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
 605            rather than a variable argument list.
 606
 607            This implementation uses a variable argument list, but can be  con-
 608            figured  to  use  the  fixed-parameter list.  Portable applications
 609            should provide 9 parameters after the format; zeroes are  fine  for
 610            this purpose.
 611
 612            In  response  to review comments by Thomas E. Dickey, X/Open Curses
 613            Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
 614
 615            While <STRONG>tiparm</STRONG> is always provided in ncurses, the older form is  only
 616            available  as  a build-time configuration option.  If not specially
 617            configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>.
 618
 619        Both forms of <STRONG>tparm</STRONG> have drawbacks:
 620
 621        <STRONG>o</STRONG>   Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters.  Passing
 622            nine on each call is awkward.
 623
 624            Using  <STRONG>long</STRONG>  for the numeric parameter type is a workaround to make
 625            the parameter use the same amount of stack as a pointer.  That  ap-
 626            proach  dates  back  to  the  mid-1980s, before C was standardized.
 627            Since then, there is a standard (and pointers are not  required  to
 628            fit in a long).
 629
 630        <STRONG>o</STRONG>   Providing  the  right  number of parameters for a variadic function
 631            such as <STRONG>tiparm</STRONG> can be a problem, in particular for  string  parame-
 632            ters.  However, only a few terminfo capabilities use string parame-
 633            ters (e.g., the ones used for programmable function keys).
 634
 635            The ncurses library checks usage of these capabilities, and returns
 636            an  error  if  the capability mishandles string parameters.  But it
 637            cannot check if a calling program provides  strings  in  the  right
 638            places for the <STRONG>tparm</STRONG> calls.
 639
 640            The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a ta-
 641            ble, so that it calls <STRONG>tparm</STRONG> correctly.
 642
 643
 644 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
 645        If configured to use the terminal-driver, e.g., for the MinGW port,
 646
 647        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG> interprets a missing/empty TERM variable as  the  special
 648            value "unknown".
 649
 650            SVr4 curses uses the special value "dumb".
 651
 652            The  difference  between  the  two  is  that the former uses the <STRONG>gn</STRONG>
 653            (<STRONG>generic_type</STRONG>) terminfo capability, while the latter does  not.   A
 654            generic terminal is unsuitable for full-screen applications.
 655
 656        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  allows explicit use of the the windows console driver by
 657            checking if $TERM is set to "#win32con" or an abbreviation of  that
 658            string.
 659
 660
 661 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
 662        In  System  V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type and returns
 663        <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen to implement the X/Open Curses semantics.
 664
 665        In System V Release 4, the third argument of <STRONG>tputs</STRONG>  has  the  type  <STRONG>int</STRONG>
 666        <STRONG>(*putc)(char)</STRONG>.
 667
 668        At  least one implementation of X/Open Curses (Solaris) returns a value
 669        other than <STRONG>OK</STRONG>/<STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>.  That returns the length of  the  string,
 670        and does no error-checking.
 671
 672        X/Open  notes  that after calling <STRONG>mvcur</STRONG>, the curses state may not match
 673        the actual terminal state, and that an application should touch and re-
 674        fresh the window before resuming normal curses calls.  Both <STRONG>ncurses</STRONG> and
 675        System V Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN  data  allo-
 676        cated  in  either  <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is documented as a
 677        terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not  well
 678        specified.
 679
 680        X/Open  states that the old location must be given for <STRONG>mvcur</STRONG>.  This im-
 681        plementation allows the caller to use -1's for the old  ordinates.   In
 682        that case, the old location is unknown.
 683
 684
 685 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 686        <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>,
 687        <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>
 688        <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG>
 689
 690
 691
 692 ncurses 6.4                       2023-08-05                 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
 693 </PRE>
 694 <div class="nav">
 695 <ul>
 696 <li><a href="#h2-NAME">NAME</a></li>
 697 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 698 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 699 <ul>
 700 <li><a href="#h3-Initialization">Initialization</a></li>
 701 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
 702 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
 703 <li><a href="#h3-Output-Functions">Output Functions</a></li>
 704 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
 705 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
 706 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
 707 </ul>
 708 </li>
 709 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a>
 710 <ul>
 711 <li><a href="#h3-Compatibility-macros">Compatibility macros</a></li>
 712 </ul>
 713 </li>
 714 <li><a href="#h2-HISTORY">HISTORY</a></li>
 715 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 716 <ul>
 717 <li><a href="#h3-Extensions">Extensions</a></li>
 718 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
 719 <li><a href="#h3-Legacy-data">Legacy data</a></li>
 720 <li><a href="#h3-Output-buffering">Output buffering</a></li>
 721 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
 722 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
 723 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
 724 </ul>
 725 </li>
 726 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 727 </ul>
 728 </div>
 729 </BODY>
 730 </HTML>