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