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

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