man/curs_terminfo.3x

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