man/curs_terminfo.3x

   1 .\" $Id: curs_terminfo.3x,v 1.6 1996/06/15 22:45:50 tom Exp $
   2 .TH curs_terminfo 3X ""
   3 .ds n 5
   4 .SH NAME
   5 \fBsetupterm\fR, \fBsetterm\fR,
   6 \fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR,
   7 \fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR,
   8 \fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBcurses\fR
   9 interfaces to terminfo database
  10 .SH SYNOPSIS
  11 \fB#include <curses.h>\fR
  12 .br
  13 \fB#include <term.h>\fR
  14
  15 \fBint setupterm(const char *term, int fildes, int *errret);\fR
  16 .br
  17 \fBint setterm(const char *term);\fR
  18 .br
  19 \fBTERMINAL *set_curterm(TERMINAL *nterm);\fR
  20 .br
  21 \fBint del_curterm(TERMINAL *oterm);\fR
  22 .br
  23 \fBint restartterm(const char *term, int fildes, int *errret);\fR
  24 .br
  25 \fBchar *tparm(const char *str, ...);\fR
  26 .br
  27 \fBchar *tparam(const char *str, char *buffer, int size, ...);\fR
  28 .br
  29 \fBint tputs(const char *str, int affcnt, int (*putc)(int));\fR
  30 .br
  31 \fBint putp(const char *str);\fR
  32 .br
  33 \fBint vidputs(chtype attrs, int (*putc)(char));\fR
  34 .br
  35 \fBint vidattr(chtype attrs);\fR
  36 .br
  37 \fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR
  38 .br
  39 \fBint tigetflag(const char *capname);\fR
  40 .br
  41 \fBint tigetnum(const char *capname);\fR
  42 .br
  43 \fBchar *tigetstr(const char *capname);\fR
  44 .br
  45 .SH DESCRIPTION
  46 These low-level routines must be called by programs that have to deal
  47 directly with the \fBterminfo\fR database to handle certain terminal
  48 capabilities, such as programming function keys.  For all other
  49 functionality, \fBcurses\fR routines are more suitable and their use is
  50 recommended.
  51
  52 Initially, \fBsetupterm\fR should be called.  Note that
  53 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
  54 \fBnewterm\fR.  This defines the set of terminal-dependent variables
  55 [listed in \fBterminfo\fR(\*n)].  The \fBterminfo\fR variables
  56 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
  57 follows: If \fBuse_env(FALSE)\fR has been called, values for
  58 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
  59 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
  60 exist, their values are used.  If these environment variables do not
  61 exist and the program is running in a window, the current window size
  62 is used.  Otherwise, if the environment variables do not exist, the
  63 values for \fBlines\fR and \fBcolumns\fR specified in the
  64 \fBterminfo\fR database are used.
  65
  66 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
  67 order) to get the definitions for these strings, numbers, and flags.
  68 Parameterized strings should be passed through \fBtparm\fR to instantiate them.
  69 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
  70 with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
  71 tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
  72 cursor addressing should output \fBenter_ca_mode\fR upon startup and should
  73 output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
  74 should call
  75
  76 \fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
  77 is called and should output \fBenter_ca_mode\fR and call
  78 \fBreset_prog_mode\fR after returning from the shell.
  79
  80 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
  81 initializing the \fBterminfo\fR structures, but does not set up the
  82 output virtualization structures used by \fBcurses\fR.  The terminal
  83 type is the character string \fIterm\fR; if \fIterm\fR is null, the
  84 environment variable \fBTERM\fR is used.  All output is to file
  85 descriptor \fBfildes\fR which is initialized for output.  If
  86 \fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or
  87 \fBERR\fR and stores a status value in the integer pointed to by
  88 \fIerrret\fR.  A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR
  89 means that the terminal could not be found, and \fB-1\fR means that
  90 the \fBterminfo\fR database could not be found.  If \fIerrret\fR is
  91 null, \fBsetupterm\fR prints an error message upon finding an error
  92 and exits.  Thus, the simplest call is:
  93
  94       \fBsetupterm((char *)0, 1, (int *)0);\fR,
  95
  96 which uses all the defaults and sends the output to \fBstdout\fR.
  97
  98 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
  99
 100       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
 101
 102 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
 103 The \fBsetterm\fR routine is included here for BSD compatibility, and
 104 is not recommended for new programs.
 105
 106 The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
 107 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
 108 string variables use the values from \fInterm\fR.  It returns the old value
 109 of \fBcur_term\fR.
 110
 111 The \fBdel_curterm\fR routine frees the space pointed to by
 112 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
 113 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
 114 boolean, numeric, and string variables thereafter may refer to invalid
 115 memory locations until another \fBsetupterm\fR has been called.
 116
 117 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
 118 except that it is called after restoring memory to a previous state (for
 119 example, when reloading a game saved as a core image dump).  It assumes that
 120 the windows and the input and output options are the same as when memory was
 121 saved, but the terminal type and baud rate may be different.  Accordingly,
 122 it saves various tty state bits, does a setupterm, and then restores the bits.
 123
 124 The \fBtparm\fR routine instantiates the string \fIstr\fR with
 125 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
 126 with the parameters applied.
 127
 128 The \fBtparam\fR routine is included for compatibility with the GNU termcap
 129 implementation.  It works like \fBtparm\fR but you specify a buffer and buffer
 130 size to be filled with the expanded string.
 131
 132 The \fBtputs\fR routine applies padding information to the string
 133 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
 134 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
 135 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
 136 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
 137 the characters are passed, one at a time.
 138
 139 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
 140 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
 141 the \fIfildes\fR specified in \fBsetupterm\fR.
 142
 143 The \fBvidputs\fR routine displays the string on the terminal in the
 144 video attribute mode \fIattrs\fR, which is any combination of the
 145 attributes listed in \fBcurses\fR(3X).  The characters are passed to
 146 the \fBputchar\fR-like routine \fIputc\fR.
 147
 148 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
 149 that it outputs through \fBputchar\fR.
 150
 151 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
 152 effect immediately (rather than at the next refresh).
 153
 154 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
 155 the value of the capability corresponding to the \fBterminfo\fR
 156 \fIcapname\fR passed to them, such as \fBxenl\fR.
 157
 158 The \fBtigetflag\fR routine returns the value \fB-1\fR if
 159 \fIcapname\fR is not a boolean capability.
 160
 161 The \fBtigetnum\fR routine returns the value \fB-2\fR if
 162 \fIcapname\fR is not a numeric capability.
 163
 164 The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
 165 if \fIcapname\fR is not a string capability.
 166
 167 The \fIcapname\fR for each capability is given in the table column entitled
 168 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
 169
 170 \fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
 171
 172 \fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
 173
 174 \fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
 175
 176 These null-terminated arrays contain the \fIcapnames\fR, the
 177 \fBtermcap\fR codes, and the full C names, for each of the
 178 \fBterminfo\fR variables.
 179 .SH RETURN VALUE
 180 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 181 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
 182 completion, unless otherwise noted in the preceding routine descriptions.
 183
 184 Routines that return pointers always return \fBNULL\fR on error.
 185 .SH NOTES
 186 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
 187 It may be useful when you want to test for terminal capabilities without
 188 committing to the allocation of storage involved in \fBinitscr\fR.
 189
 190 Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
 191 .SH PORTABILITY
 192 The function \fBsetterm\fR is not described in the XSI Curses standard and must
 193 be considered non-portable.  All other functions are as described in the XSI
 194 curses standard.
 195
 196 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
 197 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the XSI Curses
 198 semantics.
 199
 200 In System V Release 4, the third argument of \fBtputs\fR has the type
 201 \fBint (*putc)(char)\fR.
 202
 203 The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
 204 rather than a variable argument list.
 205 .SH SEE ALSO
 206 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
 207 \fBputc\fR(3S), \fBterminfo\fR(\*n)
 208 .\"#
 209 .\"# The following sets edit modes for GNU EMACS
 210 .\"# Local Variables:
 211 .\"# mode:nroff
 212 .\"# fill-column:79
 213 .\"# End: