curs_terminfo.3x.html

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