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

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