


curs_terminfo(3X)                               curs_terminfo(3X)


NNAAMMEE
       ccuurrss__tteerrmmiinnffoo:     sseettuupptteerrmm,     sseetttteerrmm,    sseett__ccuurrtteerrmm,
       ddeell__ccuurrtteerrmm, rreessttaarrtttteerrmm,  ttppaarrmm,  ttppuuttss,  ppuuttpp,  vviiddppuuttss,
       vviiddaattttrr,  mmvvccuurr,  ttiiggeettffllaagg,  ttiiggeettnnuumm,  ttiiggeettssttrr - ccuurrsseess
       interfaces to terminfo database

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ccuurrsseess..hh>>
       ##iinncclluuddee <<tteerrmm..hh>>

       iinntt sseettuupptteerrmm((cchhaarr **tteerrmm,, iinntt ffiillddeess,, iinntt **eerrrrrreett));;
       iinntt sseetttteerrmm((cchhaarr **tteerrmm));;
       TTEERRMMIINNAALL **sseett__ccuurrtteerrmm((TTEERRMMIINNAALL **nntteerrmm));;
       iinntt ddeell__ccuurrtteerrmm((TTEERRMMIINNAALL **ootteerrmm));;
       iinntt rreessttaarrtttteerrmm((cchhaarr **tteerrmm,, iinntt ffiillddeess,, iinntt **eerrrrrreett));;
       cchhaarr **ttppaarrmm((cchhaarr **ssttrr,, lloonngg iinntt pp11,, lloonngg iinntt pp22,, lloonngg  iinntt
       pp33,,
             lloonngg iinntt pp44,, lloonngg iinntt pp55,, lloonngg iinntt pp66,, lloonngg iinntt pp77,,
             long int p8, long int p9);
       iinntt ttppuuttss((cchhaarr **ssttrr,, iinntt aaffffccnntt,, iinntt ((**ppuuttcc))((iinntt))));;
       iinntt ppuuttpp((cchhaarr **ssttrr));;
       iinntt vviiddppuuttss((cchhttyyppee aattttrrss,, iinntt ((**ppuuttcc))((cchhaarr))));;
       iinntt vviiddaattttrr((cchhttyyppee aattttrrss));;
       iinntt mmvvccuurr((iinntt oollddrrooww,, iinntt oollddccooll,, iinntt nneewwrrooww,, iinntt nneewwccooll));;
       iinntt ttiiggeettffllaagg((cchhaarr **ccaappnnaammee));;
       iinntt ttiiggeettnnuumm((cchhaarr **ccaappnnaammee));;
       iinntt ttiiggeettssttrr((cchhaarr **ccaappnnaammee));;

DDEESSCCRRIIPPTTIIOONN
       These low-level routines must be called by  programs  that
       have to deal directly with the tteerrmmiinnffoo database to handle
       certain terminal capabilities, such as  programming  func-
       tion  keys.   For all other functionality, ccuurrsseess routines
       are more suitable and their use is recommended.

       Initially,  sseettuupptteerrmm  should  be   called.    Note   that
       sseettuupptteerrmm  is automatically called by iinniittssccrr and nneewwtteerrmm.
       This  defines  the  set  of  terminal-dependent  variables
       [listed in tteerrmmiinnffoo(5)].  The tteerrmmiinnffoo variables lliinneess and
       ccoolluummnnss  are  initialized  by  sseettuupptteerrmm  as  follows:  If
       uussee__eennvv((FFAALLSSEE))  has  been  called,  values  for  lliinneess and
       ccoolluummnnss specified in tteerrmmiinnffoo are used.  Otherwise, if the
       environment  variables LLIINNEESS and CCOOLLUUMMNNSS exist, their val-
       ues are used.  If these environment variables do not exist
       and the program is running in a window, the current window
       size is used.  Otherwise, if the environment variables  do
       not  exist,  the values for lliinneess and ccoolluummnnss specified in
       the tteerrmmiinnffoo database are used.

       The header files ccuurrsseess..hh and tteerrmm..hh  should  be  included
       (in  this order) to get the definitions for these strings,
       numbers,  and  flags.   Parameterized  strings  should  be
       passed  through  ttppaarrmm  to instantiate them.  All tteerrmmiinnffoo
       strings [including the output of ttppaarrmm] should be  printed



                                                                1





curs_terminfo(3X)                               curs_terminfo(3X)


       with  ttppuuttss or ppuuttpp.  Call the rreesseett__sshheellll__mmooddee to restore
       the tty modes before exiting [see ccuurrss__kkeerrnneell(3X)].   Pro-
       grams   which   use   cursor   addressing   should  output
       eenntteerr__ccaa__mmooddee upon startup and should output  eexxiitt__ccaa__mmooddee
       before  exiting.   Programs  desiring shell escapes should
       call

       rreesseett__sshheellll__mmooddee and output eexxiitt__ccaa__mmooddee before the  shell
       is   called  and  should  output  eenntteerr__ccaa__mmooddee  and  call
       rreesseett__pprroogg__mmooddee after returning from the shell.

       The sseettuupptteerrmm routine reads in the tteerrmmiinnffoo database, ini-
       tializing the tteerrmmiinnffoo structures, but does not set up the
       output virtualization structures used by ccuurrsseess.  The ter-
       minal  type is the character string _t_e_r_m; if _t_e_r_m is null,
       the environment variable TTEERRMM is used.  All output  is  to
       file  descriptor  ffiillddeess  which is initialized for output.
       If _e_r_r_r_e_t is not null, then sseettuupptteerrmm returns  OOKK  or  EERRRR
       and  stores  a  status  value in the integer pointed to by
       _e_r_r_r_e_t.  A status of 11 in _e_r_r_r_e_t is normal, 00  means  that
       the  terminal  could  not  be found, and --11 means that the
       tteerrmmiinnffoo database could not be found.  If _e_r_r_r_e_t is  null,
       sseettuupptteerrmm  prints  an  error message upon finding an error
       and exits.  Thus, the simplest call is:

             sseettuupptteerrmm((((cchhaarr **))00,, 11,, ((iinntt **))00));;,

       which uses all the defaults and sends the output  to  ssttdd--
       oouutt.

       The  sseetttteerrmm  routine is being replaced by sseettuupptteerrmm.  The
       call:

             sseettuupptteerrmm((_t_e_r_m,, 11,, ((iinntt **))00))

       provides the same  functionality  as  sseetttteerrmm((_t_e_r_m)).   The
       sseetttteerrmm  routine  is  included here for BSD compatibility,
       and is not recommended for new programs.

       The sseett__ccuurrtteerrmm routine  sets  the  variable  ccuurr__tteerrmm  to
       _n_t_e_r_m, and makes all of the tteerrmmiinnffoo boolean, numeric, and
       string variables use the values from  _n_t_e_r_m.   It  returns
       the old value of ccuurr__tteerrmm.

       The  ddeell__ccuurrtteerrmm  routine  frees  the  space pointed to by
       _o_t_e_r_m and makes it available for further use.  If _o_t_e_r_m is
       the  same  as  ccuurr__tteerrmm, references to any of the tteerrmmiinnffoo
       boolean, numeric,  and  string  variables  thereafter  may
       refer  to invalid memory locations until another sseettuupptteerrmm
       has been called.

       The  rreessttaarrtttteerrmm  routine  is  similar  to  sseettuupptteerrmm  and
       iinniittssccrr,  except  that it is called after restoring memory
       to a previous state (for example, when  reloading  a  game



                                                                2





curs_terminfo(3X)                               curs_terminfo(3X)


       saved  as a core image dump).  It assumes that the windows
       and the input and output options are the same as when mem-
       ory  was saved, but the terminal type and baud rate may be
       different.  Accordingly, it saves various tty state  bits,
       does a setupterm, and then restores the bits.

       The ttppaarrmm routine instantiates the string _s_t_r with parame-
       ters _p_i.  A pointer is returned to the result of _s_t_r  with
       the parameters applied.

       The  ttppuuttss  routine  applies  padding  information  to the
       string _s_t_r and outputs it.  The _s_t_r  must  be  a  terminfo
       string  variable  or the return value from ttppaarrmm, ttggeettssttrr,
       or ttggoottoo.  _a_f_f_c_n_t is the number of lines affected, or 1 if
       not  applicable.   _p_u_t_c is a ppuuttcchhaarr-like routine to which
       the characters are passed, one at a time.

       The ppuuttpp routine calls ttppuuttss((_s_t_r,, 11,, ppuuttcchhaarr)).  Note  that
       the  output  of  ppuuttpp  always  goes  to ssttddoouutt, not to the
       _f_i_l_d_e_s specified in sseettuupptteerrmm.

       The vviiddppuuttss routine displays the string on the terminal in
       the  video  attribute mode _a_t_t_r_s, which is any combination
       of the attributes listed in  ccuurrsseess(3X).   The  characters
       are passed to the ppuuttcchhaarr-like routine _p_u_t_c.

       The  vviiddaattttrr  routine  is like the vviiddppuuttss routine, except
       that it outputs through ppuuttcchhaarr.

       The mmvvccuurr routine provides low-level  cursor  motion.   It
       takes   effect   immediately  (rather  than  at  the  next
       refresh).

       The ttiiggeettffllaagg, ttiiggeettnnuumm and ttiiggeettssttrr routines  return  the
       value of the capability corresponding to the tteerrmmiinnffoo _c_a_p_-
       _n_a_m_e passed to them, such as xxeennll.

       The ttiiggeettffllaagg routine returns the value --11 if  _c_a_p_n_a_m_e  is
       not a boolean capability.

       The  ttiiggeettnnuumm  routine  returns the value --22 if _c_a_p_n_a_m_e is
       not a numeric capability.

       The ttiiggeettssttrr routine returns the value ((cchhaarr **))--11 if  _c_a_p_-
       _n_a_m_e is not a string capability.

       The _c_a_p_n_a_m_e for each capability is given in the table col-
       umn entitled _c_a_p_n_a_m_e code in the capabilities  section  of
       tteerrmmiinnffoo(5).

       cchhaarr **bboooollnnaammeess, **bboooollccooddeess, **bboooollffnnaammeess

       cchhaarr **nnuummnnaammeess, **nnuummccooddeess, **nnuummffnnaammeess




                                                                3





curs_terminfo(3X)                               curs_terminfo(3X)


       cchhaarr **ssttrrnnaammeess, **ssttrrccooddeess, **ssttrrffnnaammeess

       These  null-terminated  arrays  contain  the _c_a_p_n_a_m_e_s, the
       tteerrmmccaapp codes, and the full C names, for each of the  tteerr--
       mmiinnffoo variables.

RREETTUURRNN VVAALLUUEE
       Routines  that  return  an integer return EERRRR upon failure
       and OOKK (SVr4 only specifies "an integer value  other  than
       EERRRR")  upon  successful completion, unless otherwise noted
       in the preceding routine descriptions.

       Routines that return pointers always return NNUULLLL on error.

NNOOTTEESS
       The  sseettuupptteerrmm routine should be used in place of sseetttteerrmm.
       It may be useful when you want to test for terminal  capa-
       bilities  without  committing to the allocation of storage
       involved in iinniittssccrr.

       Note that vviiddaattttrr and vviiddppuuttss may be macros.

PPOORRTTAABBIILLIITTYY
       The function sseetttteerrmm is not describe  in  the  XSI  Curses
       standard  and  must be considered non-portable.  All other
       functions are as described in the XSI curses standard.

       In System V Release 4, sseett__ccuurrtteerrmm has an iinntt return  type
       and  returns  OOKK  or EERRRR.  We have chosen to implement the
       XSI Curses semantics.

       In System V Release 4, the third argument of ttppuuttss has the
       type iinntt ((**ppuuttcc))((cchhaarr)).

SSEEEE AALLSSOO
       ccuurrsseess(3X),       ccuurrss__iinniittssccrr(3X),       ccuurrss__kkeerrnneell(3X),
       ccuurrss__tteerrmmccaapp(3X), ppuuttcc(3S), tteerrmmiinnffoo(5)




















                                                                4


