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

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