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

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