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