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

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1999-2000,2002 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.16 2002/07/20 16:05:19 tom Exp @
  31 -->
  32 <HTML>
  33 <HEAD>
  34 <TITLE>curs_terminfo 3x</TITLE>
  35 <link rev=made href="mailto:bug-ncurses@gnu.org">
  36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  37 </HEAD>
  38 <BODY>
  39 <H1>curs_terminfo 3x</H1>
  40 <HR>
  41 <PRE>
  42 <!-- Manpage converted by man2html 3.0.1 -->
  43
  44 </PRE>
  45 <H2>NAME</H2><PRE>
  46        <STRONG>del_curterm</STRONG>,  <STRONG>mvcur</STRONG>,  <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>set-</STRONG>
  47        <STRONG>term</STRONG>, <STRONG>setupterm</STRONG>,  <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG>,  <STRONG>tigetstr</STRONG>,  <STRONG>tparm</STRONG>,
  48        <STRONG>tputs</STRONG>,  <STRONG>vid_attr</STRONG>,  <STRONG>vid_puts</STRONG>,  <STRONG>vidattr</STRONG>,  <STRONG>vidputs</STRONG>  -  <STRONG>curses</STRONG>
  49        interfaces to terminfo database
  50
  51
  52 </PRE>
  53 <H2>SYNOPSIS</H2><PRE>
  54        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  55        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
  56
  57        <STRONG>int</STRONG> <STRONG>setupterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>setterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
  59        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
  62        <STRONG>char</STRONG> <STRONG>*tparm(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
  63        <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>
  64        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
  66        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  67        <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>)(char));</STRONG>
  68        <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>
  69        <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>
  70        <STRONG>int</STRONG> <STRONG>tigetflag(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>tigetnum(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
  72        <STRONG>char</STRONG> <STRONG>*tigetstr(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
  73
  74
  75 </PRE>
  76 <H2>DESCRIPTION</H2><PRE>
  77        These low-level routines must be called by  programs  that
  78        have to deal directly with the <STRONG>terminfo</STRONG> database to handle
  79        certain terminal capabilities, such as  programming  func-
  80        tion  keys.   For all other functionality, <STRONG>curses</STRONG> routines
  81        are more suitable and their use is recommended.
  82
  83        Initially,  <STRONG>setupterm</STRONG>  should  be   called.    Note   that
  84        <STRONG>setupterm</STRONG>  is automatically called by <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG>.
  85        This  defines  the  set  of  terminal-dependent  variables
  86        [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].  The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and
  87        <STRONG>columns</STRONG>  are  initialized  by  <STRONG>setupterm</STRONG>  as  follows:  If
  88        <STRONG>use_env(FALSE)</STRONG>  has  been  called,  values  for  <STRONG>lines</STRONG> and
  89        <STRONG>columns</STRONG> specified in <STRONG>terminfo</STRONG> are used.  Otherwise, if the
  90        environment  variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist, their val-
  91        ues are used.  If these environment variables do not exist
  92        and the program is running in a window, the current window
  93        size is used.  Otherwise, if the environment variables  do
  94        not  exist,  the values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in
  95        the <STRONG>terminfo</STRONG> database are used.
  96
  97        The header files <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG>  should  be  included
  98        (in  this order) to get the definitions for these strings,
  99        numbers,  and  flags.   Parameterized  strings  should  be
 100        passed  through  <STRONG>tparm</STRONG>  to instantiate them.  All <STRONG>terminfo</STRONG>
 101        strings [including the output of <STRONG>tparm</STRONG>] should be  printed
 102        with  <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call the <STRONG>reset_shell_mode</STRONG> to restore
 103        the tty modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].   Pro-
 104        grams   which   use   cursor   addressing   should  output
 105        <STRONG>enter_ca_mode</STRONG> upon startup and should output  <STRONG>exit_ca_mode</STRONG>
 106        before  exiting.   Programs  desiring shell escapes should
 107        call
 108
 109        <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the  shell
 110        is   called  and  should  output  <STRONG>enter_ca_mode</STRONG>  and  call
 111        <STRONG>reset_prog_mode</STRONG> after returning from the shell.
 112
 113        The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, ini-
 114        tializing the <STRONG>terminfo</STRONG> structures, but does not set up the
 115        output virtualization structures used by <STRONG>curses</STRONG>.  The ter-
 116        minal  type is the character string <EM>term</EM>; if <EM>term</EM> is null,
 117        the environment variable <STRONG>TERM</STRONG> is used.  All output  is  to
 118        file  descriptor  <STRONG>fildes</STRONG>  which is initialized for output.
 119        If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG> returns  <STRONG>OK</STRONG>  or  <STRONG>ERR</STRONG>
 120        and  stores  a  status  value in the integer pointed to by
 121        <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with status of <STRONG>1</STRONG> in
 122        <EM>errret</EM> is normal.  If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
 123
 124               <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot be
 125                    used for curses applications.
 126
 127               <STRONG>0</STRONG>    means that the terminal could not be found, or
 128                    that  it  is a generic type, having too little
 129                    information for curses applications to run.
 130
 131               <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not  be
 132                    found.
 133
 134        If  <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon
 135        finding an error and exits.  Thus, the simplest call is:
 136
 137              <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
 138
 139        which uses all the defaults and sends the output  to  <STRONG>std-</STRONG>
 140        <STRONG>out</STRONG>.
 141
 142        The  <STRONG>setterm</STRONG>  routine is being replaced by <STRONG>setupterm</STRONG>.  The
 143        call:
 144
 145              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
 146
 147        provides the same  functionality  as  <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>.   The
 148        <STRONG>setterm</STRONG>  routine  is  included here for BSD compatibility,
 149        and is not recommended for new programs.
 150
 151        The <STRONG>set_curterm</STRONG> routine  sets  the  variable  <STRONG>cur_term</STRONG>  to
 152        <EM>nterm</EM>, and makes all of the <STRONG>terminfo</STRONG> boolean, numeric, and
 153        string variables use the values from  <EM>nterm</EM>.   It  returns
 154        the old value of <STRONG>cur_term</STRONG>.
 155
 156        The  <STRONG>del_curterm</STRONG>  routine  frees  the  space pointed to by
 157        <EM>oterm</EM> and makes it available for further use.  If <EM>oterm</EM> is
 158        the  same  as  <STRONG>cur_term</STRONG>, references to any of the <STRONG>terminfo</STRONG>
 159        boolean, numeric,  and  string  variables  thereafter  may
 160        refer  to invalid memory locations until another <STRONG>setupterm</STRONG>
 161        has been called.
 162
 163        The  <STRONG>restartterm</STRONG>  routine  is  similar  to  <STRONG>setupterm</STRONG>  and
 164        <STRONG>initscr</STRONG>,  except  that it is called after restoring memory
 165        to a previous state (for example, when  reloading  a  game
 166        saved  as a core image dump).  It assumes that the windows
 167        and the input and output options are the same as when mem-
 168        ory  was saved, but the terminal type and baud rate may be
 169        different.  Accordingly, it saves various tty state  bits,
 170        does a setupterm, and then restores the bits.
 171
 172        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parame-
 173        ters <EM>pi</EM>.  A pointer is returned to the result of <EM>str</EM>  with
 174        the parameters applied.
 175
 176        The  <STRONG>tputs</STRONG>  routine  applies  padding  information  to the
 177        string <EM>str</EM> and outputs it.  The <EM>str</EM>  must  be  a  terminfo
 178        string  variable  or the return value from <STRONG>tparm</STRONG>, <STRONG>tgetstr</STRONG>,
 179        or <STRONG>tgoto</STRONG>.  <EM>affcnt</EM> is the number of lines affected, or 1 if
 180        not  applicable.   <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which
 181        the characters are passed, one at a time.
 182
 183        The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>.  Note  that
 184        the  output  of  <STRONG>putp</STRONG>  always  goes  to <STRONG>stdout</STRONG>, not to the
 185        <EM>fildes</EM> specified in <STRONG>setupterm</STRONG>.
 186
 187        The <STRONG>vidputs</STRONG> routine displays the string on the terminal in
 188        the  video  attribute mode <EM>attrs</EM>, which is any combination
 189        of the attributes listed in  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.   The  characters
 190        are passed to the <STRONG>putchar</STRONG>-like routine <EM>putc</EM>.
 191
 192        The  <STRONG>vidattr</STRONG>  routine  is like the <STRONG>vidputs</STRONG> routine, except
 193        that it outputs through <STRONG>putchar</STRONG>.
 194
 195        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond  to  vidattr
 196        and  vidputs,  respectively.   They use a set of arguments
 197        for representing the video attributes  plus  color,  i.e.,
 198        one of type attr_t for the attributes and one of short for
 199        the color_pair number.  The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines
 200        are  designed  to use the attribute constants with the <EM>WA</EM><STRONG>_</STRONG>
 201        prefix.  The opts argument is  reserved  for  future  use.
 202        Currently,  applications  must  provide a null pointer for
 203        that argument.
 204
 205        The <STRONG>mvcur</STRONG> routine provides low-level  cursor  motion.   It
 206        takes   effect   immediately  (rather  than  at  the  next
 207        refresh).
 208
 209        The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines  return  the
 210        value  of  the  capability  corresponding  to the <STRONG>terminfo</STRONG>
 211        <EM>capname</EM> passed to them, such as <STRONG>xenl</STRONG>.
 212
 213        The <STRONG>tigetflag</STRONG> routine returns the value <STRONG>-1</STRONG> if  <EM>capname</EM>  is
 214        not a boolean capability, or <STRONG>0</STRONG> if it is canceled or absent
 215        from the terminal description.
 216
 217        The <STRONG>tigetnum</STRONG> routine returns the value <STRONG>-2</STRONG>  if  <EM>capname</EM>  is
 218        not  a  numeric  capability,  or  <STRONG>-1</STRONG>  if it is canceled or
 219        absent from the terminal description.
 220
 221        The <STRONG>tigetstr</STRONG> routine returns the value <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> if  <EM>cap-</EM>
 222        <EM>name</EM> is not a string capability, or <STRONG>0</STRONG> if it is canceled or
 223        absent from the terminal description.
 224
 225        The <EM>capname</EM> for each capability is given in the table col-
 226        umn  entitled  <EM>capname</EM> code in the capabilities section of
 227        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 228
 229        <STRONG>char</STRONG> <STRONG>*boolnames</STRONG>, <STRONG>*boolcodes</STRONG>, <STRONG>*boolfnames</STRONG>
 230
 231        <STRONG>char</STRONG> <STRONG>*numnames</STRONG>, <STRONG>*numcodes</STRONG>, <STRONG>*numfnames</STRONG>
 232
 233        <STRONG>char</STRONG> <STRONG>*strnames</STRONG>, <STRONG>*strcodes</STRONG>, <STRONG>*strfnames</STRONG>
 234
 235        These null-terminated arrays  contain  the  <EM>capnames</EM>,  the
 236        <STRONG>termcap</STRONG>  codes, and the full C names, for each of the <STRONG>ter-</STRONG>
 237        <STRONG>minfo</STRONG> variables.
 238
 239
 240 </PRE>
 241 <H2>RETURN VALUE</H2><PRE>
 242        Routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure
 243        and  <STRONG>OK</STRONG>  (SVr4 only specifies "an integer value other than
 244        <STRONG>ERR</STRONG>") upon successful completion, unless  otherwise  noted
 245        in the preceding routine descriptions.
 246
 247        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
 248
 249
 250 </PRE>
 251 <H2>NOTES</H2><PRE>
 252        The <STRONG>setupterm</STRONG> routine should be used in place of  <STRONG>setterm</STRONG>.
 253        It  may be useful when you want to test for terminal capa-
 254        bilities without committing to the allocation  of  storage
 255        involved in <STRONG>initscr</STRONG>.
 256
 257        Note that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
 258
 259
 260 </PRE>
 261 <H2>PORTABILITY</H2><PRE>
 262        The  function  <STRONG>setterm</STRONG>  is not described in the XSI Curses
 263        standard and must be considered non-portable.   All  other
 264        functions are as described in the XSI curses standard.
 265
 266        In  System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type
 267        and returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen  to  implement  the
 268        XSI Curses semantics.
 269
 270        In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
 271        type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
 272
 273        The XSI Curses standard prototypes <STRONG>tparm</STRONG> with a fixed num-
 274        ber  of  parameters, rather than a variable argument list.
 275        This  implementation  uses  a  variable   argument   list.
 276        Portable  applications  should  provide 9 parameters after
 277        the format; zeroes are fine for this purpose.
 278
 279        XSI notes that after calling <STRONG>mvcur</STRONG>, the curses  state  may
 280        not  match the actual terminal state, and that an applica-
 281        tion should touch and refresh the window  before  resuming
 282        normal  curses calls.  Both ncurses and System V Release 4
 283        curses implement <STRONG>mvcur</STRONG> using the SCREEN data allocated  in
 284        either  <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is documented as
 285        a terminfo function, <STRONG>mvcur</STRONG> is  really  a  curses  function
 286        which is not well specified.
 287
 288
 289 </PRE>
 290 <H2>SEE ALSO</H2><PRE>
 291        <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>
 292        <STRONG><A HREF="curs_termcap.3x.html">cap(3x)</A></STRONG>, <STRONG><A HREF="putc.3S.html">putc(3S)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327 </PRE>
 328 <HR>
 329 <ADDRESS>
 330 Man(1) output converted with
 331 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 332 </ADDRESS>
 333 </BODY>
 334 </HTML>