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

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1999-2016,2017 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.55 2017/03/31 15:16:15 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 http://invisible-island.net/scripts/readme.html#others_scripts">
  41 <TITLE>curs_terminfo 3x</TITLE>
  42 <link rev=made 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>,
  55        <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>, <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>,
  56        <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> -
  57        <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
 102        have to deal directly with the <STRONG>terminfo</STRONG> database to handle
 103        certain terminal capabilities, such as  programming  func-
 104        tion  keys.   For all other functionality, <STRONG>curses</STRONG> routines
 105        are more suitable and their use is recommended.
 106
 107
 108 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
 109        Initially, <STRONG>setupterm</STRONG> should  be  called.   The  high-level
 110        curses  functions  <STRONG>initscr</STRONG>  and  <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to
 111        initialize the low-level set of  terminal-dependent  vari-
 112        ables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
 113
 114        Applications  can use the terminal capabilities either di-
 115        rectly (via header definitions), or by special  functions.
 116        The  header  files  <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG> should be included
 117        (in this order) to get the definitions for these  strings,
 118        numbers, and flags.
 119
 120        The  <STRONG>terminfo</STRONG>  variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized
 121        by <STRONG>setupterm</STRONG> as follows:
 122
 123        <STRONG>o</STRONG>   If <STRONG>use_env(FALSE)</STRONG> has been called,  values  for  <STRONG>lines</STRONG>
 124            and <STRONG>columns</STRONG> specified in <STRONG>terminfo</STRONG> are used.
 125
 126        <STRONG>o</STRONG>   Otherwise, if the environment variables <STRONG>LINES</STRONG> and <STRONG>COL-</STRONG>
 127            <STRONG>UMNS</STRONG> exist, their values are used.  If these  environ-
 128            ment variables do not exist and the program is running
 129            in a window, the current window size is used.   Other-
 130            wise,  if  the environment variables do not exist, the
 131            values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG>
 132            database are used.
 133
 134        Parameterized  strings  should  be passed through <STRONG>tparm</STRONG> to
 135        instantiate them.  All  <STRONG>terminfo</STRONG>  strings  [including  the
 136        output  of  <STRONG>tparm</STRONG>]  should  be printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.
 137        Call <STRONG>reset_shell_mode</STRONG> to restore the tty modes before  ex-
 138        iting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
 139
 140        Programs which use cursor addressing should
 141
 142        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and
 143
 144        <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.
 145
 146        Programs which execute shell subprocesses should
 147
 148        <STRONG>o</STRONG>   call  <STRONG>reset_shell_mode</STRONG>  and output <STRONG>exit_ca_mode</STRONG> before
 149            the shell is called and
 150
 151        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> and  call  <STRONG>reset_prog_mode</STRONG>  after
 152            returning from the shell.
 153
 154        The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, ini-
 155        tializing the <STRONG>terminfo</STRONG> structures, but does not set up the
 156        output  virtualization  structures  used by <STRONG>curses</STRONG>.  These
 157        are its parameters:
 158
 159           <EM>term</EM> is the terminal type, a character string.  If <EM>term</EM>
 160                is null, the environment variable <STRONG>TERM</STRONG> is used.
 161
 162           <EM>filedes</EM>
 163                is the file descriptor used for all output.
 164
 165           <EM>errret</EM>
 166                points to an optional location where an error sta-
 167                tus can be returned to the caller.  If  <EM>errret</EM>  is
 168                not  null,  then  <STRONG>setupterm</STRONG>  returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and
 169                stores a status value in the integer pointed to by
 170                <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with status
 171                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
 176                     be used for curses applications.
 177
 178                     <STRONG>setupterm</STRONG>  determines if the entry is a hard-
 179                     copy type by checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capa-
 180                     bility.
 181
 182                <STRONG>0</STRONG>    means  that  the terminal could not be found,
 183                     or that it is a generic type, having too lit-
 184                     tle  information  for  curses applications to
 185                     run.
 186
 187                     <STRONG>setupterm</STRONG> determines if the entry is a gener-
 188                     ic type by checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capabil-
 189                     ity.
 190
 191                <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not be
 192                     found.
 193
 194                If  <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error mes-
 195                sage upon finding an error and exits.   Thus,  the
 196                simplest call is:
 197
 198                      <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
 199
 200                which  uses  all the defaults and sends the output
 201                to <STRONG>stdout</STRONG>.
 202
 203        The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>.  The call:
 204
 205              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
 206
 207        provides the same  functionality  as  <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>.   The
 208        <STRONG>setterm</STRONG>  routine is provided for BSD compatibility, and is
 209        not recommended for new programs.
 210
 211
 212 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
 213        The <STRONG>setupterm</STRONG> routine stores  its  information  about  the
 214        terminal  in a <STRONG>TERMINAL</STRONG> structure pointed to by the global
 215        variable <STRONG>cur_term</STRONG>.  If it detects  an  error,  or  decides
 216        that  the terminal is unsuitable (hardcopy or generic), it
 217        discards this information, making it not available to  ap-
 218        plications.
 219
 220        If  <STRONG>setupterm</STRONG>  is  called repeatedly for the same terminal
 221        type, it will reuse the information.   It  maintains  only
 222        one copy of a given terminal's capabilities in memory.  If
 223        it is called for different terminal types, <STRONG>setupterm</STRONG> allo-
 224        cates new storage for each set of terminal capabilities.
 225
 226        The  <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes
 227        all of the <STRONG>terminfo</STRONG> boolean, numeric, and string variables
 228        use  the  values  from <EM>nterm</EM>.  It returns the old value of
 229        <STRONG>cur_term</STRONG>.
 230
 231        The <STRONG>del_curterm</STRONG> routine frees  the  space  pointed  to  by
 232        <EM>oterm</EM> and makes it available for further use.  If <EM>oterm</EM> is
 233        the same as <STRONG>cur_term</STRONG>, references to any  of  the  <STRONG>terminfo</STRONG>
 234        boolean,  numeric, and string variables thereafter may re-
 235        fer to invalid memory locations  until  another  <STRONG>setupterm</STRONG>
 236        has been called.
 237
 238        The  <STRONG>restartterm</STRONG>  routine  is  similar  to  <STRONG>setupterm</STRONG>  and
 239        <STRONG>initscr</STRONG>, except that it is called after  restoring  memory
 240        to  a  previous  state (for example, when reloading a game
 241        saved as a core image dump).  <STRONG>restartterm</STRONG> assumes that the
 242        windows  and  the input and output options are the same as
 243        when memory was saved, but the terminal type and baud rate
 244        may  be different.  Accordingly, <STRONG>restartterm</STRONG> saves various
 245        tty state bits, calls <STRONG>setupterm</STRONG>,  and  then  restores  the
 246        bits.
 247
 248
 249 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
 250        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parame-
 251        ters <EM>pi</EM>.  A pointer is returned to the result of <EM>str</EM>  with
 252        the  parameters  applied.   Application  developers should
 253        keep in mind these quirks of the interface:
 254
 255        <STRONG>o</STRONG>   Although <STRONG>tparm</STRONG>'s actual parameters may be integers  or
 256            strings, the prototype expects <STRONG>long</STRONG> (integer) values.
 257
 258        <STRONG>o</STRONG>   Aside  from  the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most
 259            terminal capabilities require no more than one or  two
 260            parameters.
 261
 262        <STRONG>tiparm</STRONG>  is  a  newer  form  of <STRONG>tparm</STRONG> which uses <EM>&lt;stdarg.h&gt;</EM>
 263        rather than a fixed-parameter list.  Its  numeric  parame-
 264        ters are integers (int) rather than longs.
 265
 266
 267 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
 268        The  <STRONG>tputs</STRONG>  routine  applies  padding  information  to the
 269        string <EM>str</EM> and outputs it:
 270
 271        <STRONG>o</STRONG>   The <EM>str</EM> must be a terminfo string variable or the  re-
 272            turn value from <STRONG>tparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
 273
 274        <STRONG>o</STRONG>   <EM>affcnt</EM>  is  the  number of lines affected, or 1 if not
 275            applicable.
 276
 277        <STRONG>o</STRONG>   <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters
 278            are passed, one at a time.
 279
 280        The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>.  The output
 281        of <STRONG>putp</STRONG> always goes to <STRONG>stdout</STRONG>,  rather  than  the  <EM>filedes</EM>
 282        specified in <STRONG>setupterm</STRONG>.
 283
 284        The <STRONG>vidputs</STRONG> routine displays the string on the terminal in
 285        the video attribute mode <EM>attrs</EM>, which is  any  combination
 286        of  the  attributes  listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.  The characters
 287        are passed to the <STRONG>putchar</STRONG>-like routine <EM>putc</EM>.
 288
 289        The <STRONG>vidattr</STRONG> routine is like the  <STRONG>vidputs</STRONG>  routine,  except
 290        that it outputs through <STRONG>putchar</STRONG>.
 291
 292        The  <STRONG>vid_attr</STRONG>  and <STRONG>vid_puts</STRONG> routines correspond to vidattr
 293        and vidputs, respectively.  They use a  set  of  arguments
 294        for representing the video attributes plus color, i.e.,
 295
 296        <STRONG>o</STRONG>   <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
 297
 298        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
 299
 300        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the
 301        attribute constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
 302
 303        X/Open Curses reserves the <EM>opts</EM> argument for  future  use,
 304        saying  that  applications must provide a null pointer for
 305        that argument.  As an extension, this  implementation  al-
 306        lows  <EM>opts</EM> to be used as a pointer to <STRONG>int</STRONG>, which overrides
 307        the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
 308
 309        The <STRONG>mvcur</STRONG> routine provides low-level  cursor  motion.   It
 310        takes  effect  immediately  (rather  than  at the next re-
 311        fresh).
 312
 313
 314 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
 315        The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines  return  the
 316        value of the capability corresponding to the <STRONG>terminfo</STRONG> <EM>cap-</EM>
 317        <EM>name</EM> passed to them, such as <STRONG>xenl</STRONG>.  The <EM>capname</EM>  for  each
 318        capability  is  given in the table column entitled <EM>capname</EM>
 319        code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 320
 321        These routines return special values to denote errors.
 322
 323        The <STRONG>tigetflag</STRONG> routine returns
 324
 325        <STRONG>-1</STRONG>     if <EM>capname</EM> is not a boolean capability, or
 326
 327        <STRONG>0</STRONG>      if it is canceled or absent from the  terminal  de-
 328               scription.
 329
 330        The <STRONG>tigetnum</STRONG> routine returns
 331
 332        <STRONG>-2</STRONG>     if <EM>capname</EM> is not a numeric capability, or
 333
 334        <STRONG>-1</STRONG>     if  it  is canceled or absent from the terminal de-
 335               scription.
 336
 337        The <STRONG>tigetstr</STRONG> routine returns
 338
 339        <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
 340               if <EM>capname</EM> is not a string capability, or
 341
 342        <STRONG>0</STRONG>      if it is canceled or absent from the  terminal  de-
 343               scription.
 344
 345
 346 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
 347        These null-terminated arrays contain
 348
 349        <STRONG>o</STRONG>   the short terminfo names ("codes"),
 350
 351        <STRONG>o</STRONG>   the <STRONG>termcap</STRONG> names ("names", and
 352
 353        <STRONG>o</STRONG>   the long terminfo names ("fnames")
 354
 355        for each of the predefined <STRONG>terminfo</STRONG> variables:
 356
 357               <STRONG>const</STRONG>   <STRONG>char</STRONG>  <STRONG>*boolnames[]</STRONG>,  <STRONG>*boolcodes[]</STRONG>,  <STRONG>*boolf-</STRONG>
 358               <STRONG>names[]</STRONG>
 359               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
 360               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
 361
 362
 363 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 364        Routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure
 365        and  <STRONG>OK</STRONG>  (SVr4 only specifies "an integer value other than
 366        <STRONG>ERR</STRONG>") upon successful completion, unless  otherwise  noted
 367        in the preceding routine descriptions.
 368
 369        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
 370
 371        X/Open  defines  no error conditions.  In this implementa-
 372        tion
 373
 374           <STRONG>del_curterm</STRONG>
 375                returns an error  if  its  terminal  parameter  is
 376                null.
 377
 378           <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
 379
 380           <STRONG>restartterm</STRONG>
 381                returns  an  error  if  the associated call to <STRONG>se-</STRONG>
 382                <STRONG>tupterm</STRONG> returns an error.
 383
 384           <STRONG>setupterm</STRONG>
 385                returns an error if it cannot allocate enough mem-
 386                ory,   or  create  the  initial  windows  (stdscr,
 387                curscr, newscr).  Other error conditions are docu-
 388                mented above.
 389
 390           <STRONG>tputs</STRONG>
 391                returns  an error if the string parameter is null.
 392                It does not detect I/O errors: X/Open states  that
 393                <STRONG>tputs</STRONG> ignores the return value of the output func-
 394                tion <EM>putc</EM>.
 395
 396
 397 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 398
 399 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
 400        X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
 401
 402        The function <STRONG>setterm</STRONG> is not described by X/Open  and  must
 403        be  considered  non-portable.   All other functions are as
 404        described by X/Open.
 405
 406
 407 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
 408        <STRONG>setupterm</STRONG> copies the terminal name to the  array  <STRONG>ttytype</STRONG>.
 409        This  is not part of X/Open Curses, but is assumed by some
 410        applications.
 411
 412        Other implementions may not declare  the  capability  name
 413        arrays.  Some provide them without declaring them.  X/Open
 414        does not specify them.
 415
 416        Extended terminal capability names, e.g.,  as  defined  by
 417        <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not stored in the arrays described here.
 418
 419
 420 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
 421        Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor
 422        passed to <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses  buffered
 423        I/O,  and would write to the corresponding stream.  In ad-
 424        dition to the limitation that the  terminal  was  left  in
 425        block-buffered mode on exit (like System V curses), it was
 426        problematic because <STRONG>ncurses</STRONG> did not allow a  reliable  way
 427        to cleanup on receiving SIGTSTP.
 428
 429        The current version (ncurses6) uses output buffers managed
 430        directly by <STRONG>ncurses</STRONG>.  Some of the low-level functions  de-
 431        scribed  in this manual page write to the standard output.
 432        They are not signal-safe.   The  high-level  functions  in
 433        <STRONG>ncurses</STRONG>  use  alternate  versions of these functions using
 434        the more reliable buffering scheme.
 435
 436
 437 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
 438        The X/Open Curses prototypes are based on the SVr4  curses
 439        header  declarations,  which were defined at the same time
 440        the C language was first standardized in the late 1980s.
 441
 442        <STRONG>o</STRONG>   X/Open Curses uses <STRONG>const</STRONG> less effectively than a later
 443            design  might, in some cases applying it needlessly to
 444            values are already constant, and in most  cases  over-
 445            looking  parameters  which  normally  would use <STRONG>const</STRONG>.
 446            Using constant parameters for functions which  do  not
 447            use  <STRONG>const</STRONG> may prevent the program from compiling.  On
 448            the other hand, <EM>writable</EM> <EM>strings</EM>  are  an  obsolescent
 449            feature.
 450
 451            As an extension, this implementation can be configured
 452            to change the function prototypes  to  use  the  <STRONG>const</STRONG>
 453            keyword.   The  ncurses  ABI 6 enables this feature by
 454            default.
 455
 456        <STRONG>o</STRONG>   X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number  of
 457            parameters, rather than a variable argument list.
 458
 459            This implementation uses a variable argument list, but
 460            can be configured to  use  the  fixed-parameter  list.
 461            Portable  applications should provide 9 parameters af-
 462            ter the format; zeroes are fine for this purpose.
 463
 464            In response to review comments by  Thomas  E.  Dickey,
 465            X/Open  Curses Issue 7 proposed the <STRONG>tiparm</STRONG> function in
 466            mid-2009.
 467
 468
 469 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
 470        If configured to use the terminal-driver,  e.g.,  for  the
 471        MinGW port,
 472
 473        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  interprets a missing/empty TERM variable as
 474            the special value "unknown".
 475
 476        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG> allows explicit use of the the windows  con-
 477            sole driver by checking if $TERM is set to "#win32con"
 478            or an abbreviation of that string.
 479
 480
 481 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
 482        In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return  type
 483        and  returns  <STRONG>OK</STRONG>  or <STRONG>ERR</STRONG>.  We have chosen to implement the
 484        X/Open Curses semantics.
 485
 486        In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
 487        type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
 488
 489        At least one implementation of X/Open Curses (Solaris) re-
 490        turns a value other than OK/ERR from <STRONG>tputs</STRONG>.  That  returns
 491        the length of the string, and does no error-checking.
 492
 493        X/Open  notes  that  after calling <STRONG>mvcur</STRONG>, the curses state
 494        may not match the actual terminal state, and that  an  ap-
 495        plication  should  touch and refresh the window before re-
 496        suming normal curses calls.  Both <STRONG>ncurses</STRONG> and System V Re-
 497        lease 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
 498        cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is docu-
 499        mented  as  a  terminfo function, <STRONG>mvcur</STRONG> is really a curses
 500        function which is not well specified.
 501
 502        X/Open states that the old  location  must  be  given  for
 503        <STRONG>mvcur</STRONG>.   This implementation allows the caller to use -1's
 504        for the old ordinates.  In that case, the old location  is
 505        unknown.
 506
 507
 508 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 509        <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>curs_term-</STRONG>
 510        <STRONG><A HREF="curs_termcap.3x.html">cap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>,  <STRONG>putc(3)</STRONG>,
 511        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 512
 513
 514
 515                                                       <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
 516 </PRE>
 517 <div class="nav">
 518 <ul>
 519 <li><a href="#h2-NAME">NAME</a></li>
 520 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 521 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 522 <ul>
 523 <li><a href="#h3-Initialization">Initialization</a></li>
 524 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
 525 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
 526 <li><a href="#h3-Output-Functions">Output Functions</a></li>
 527 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
 528 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
 529 </ul>
 530 </li>
 531 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 532 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 533 <ul>
 534 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
 535 <li><a href="#h3-Legacy-data">Legacy data</a></li>
 536 <li><a href="#h3-Output-buffering">Output buffering</a></li>
 537 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
 538 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
 539 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
 540 </ul>
 541 </li>
 542 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 543 </ul>
 544 </div>
 545 </BODY>
 546 </HTML>