man/curs_terminfo.3x

   1 .\"***************************************************************************
   2 .\" Copyright (c) 1999-2000,2002 Free Software Foundation, Inc.              *
   3 .\"                                                                          *
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   5 .\" copy of this software and associated documentation files (the            *
   6 .\" "Software"), to deal in the Software without restriction, including      *
   7 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   8 .\" distribute, distribute with modifications, sublicense, and/or sell       *
   9 .\" copies of the Software, and to permit persons to whom the Software is    *
  10 .\" furnished to do so, subject to the following conditions:                 *
  11 .\"                                                                          *
  12 .\" The above copyright notice and this permission notice shall be included  *
  13 .\" in all copies or substantial portions of the Software.                   *
  14 .\"                                                                          *
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  22 .\"                                                                          *
  23 .\" Except as contained in this notice, the name(s) of the above copyright   *
  24 .\" holders shall not be used in advertising or otherwise to promote the     *
  25 .\" sale, use or other dealings in this Software without prior written       *
  26 .\" authorization.                                                           *
  27 .\"***************************************************************************
  28 .\"
  29 .\" $Id: curs_terminfo.3x,v 1.16 2002/07/20 16:05:19 tom Exp $
  30 .TH curs_terminfo 3X ""
  31 .ds n 5
  32 .SH NAME
  33 \fBdel_curterm\fR,
  34 \fBmvcur\fR,
  35 \fBputp\fR,
  36 \fBrestartterm\fR,
  37 \fBset_curterm\fR,
  38 \fBsetterm\fR,
  39 \fBsetupterm\fR,
  40 \fBtigetflag\fR,
  41 \fBtigetnum\fR,
  42 \fBtigetstr\fR,
  43 \fBtparm\fR,
  44 \fBtputs\fR,
  45 \fBvid_attr\fR,
  46 \fBvid_puts\fR,
  47 \fBvidattr\fR,
  48 \fBvidputs\fR - \fBcurses\fR interfaces to terminfo database
  49 .SH SYNOPSIS
  50 .nf
  51 \fB#include <curses.h>\fR
  52 .br
  53 \fB#include <term.h>\fR
  54
  55 \fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
  56 .br
  57 \fBint setterm(char *\fR\fIterm\fR\fB);\fR
  58 .br
  59 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
  60 .br
  61 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
  62 .br
  63 \fBint restartterm(const char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
  64 .br
  65 \fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
  66 .br
  67 \fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
  68 .br
  69 \fBint putp(const char *\fR\fIstr\fR\fB);\fR
  70 .br
  71 \fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
  72 .br
  73 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
  74 .br
  75 \fBint vid_puts(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB, int (*\fR\fIputc\fR\fB)(char));\fR
  76 .br
  77 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
  78 .br
  79 \fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
  80 .br
  81 \fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
  82 .br
  83 \fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
  84 .br
  85 \fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
  86 .br
  87 .fi
  88 .SH DESCRIPTION
  89 These low-level routines must be called by programs that have to deal
  90 directly with the \fBterminfo\fR database to handle certain terminal
  91 capabilities, such as programming function keys.  For all other
  92 functionality, \fBcurses\fR routines are more suitable and their use is
  93 recommended.
  94
  95 Initially, \fBsetupterm\fR should be called.  Note that
  96 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
  97 \fBnewterm\fR.  This defines the set of terminal-dependent variables
  98 [listed in \fBterminfo\fR(\*n)].  The \fBterminfo\fR variables
  99 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
 100 follows: If \fBuse_env(FALSE)\fR has been called, values for
 101 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
 102 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
 103 exist, their values are used.  If these environment variables do not
 104 exist and the program is running in a window, the current window size
 105 is used.  Otherwise, if the environment variables do not exist, the
 106 values for \fBlines\fR and \fBcolumns\fR specified in the
 107 \fBterminfo\fR database are used.
 108
 109 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
 110 order) to get the definitions for these strings, numbers, and flags.
 111 Parameterized strings should be passed through \fBtparm\fR to instantiate them.
 112 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
 113 with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
 114 tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
 115 cursor addressing should output \fBenter_ca_mode\fR upon startup and should
 116 output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
 117 should call
 118
 119 \fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
 120 is called and should output \fBenter_ca_mode\fR and call
 121 \fBreset_prog_mode\fR after returning from the shell.
 122
 123 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
 124 initializing the \fBterminfo\fR structures, but does not set up the
 125 output virtualization structures used by \fBcurses\fR.  The terminal
 126 type is the character string \fIterm\fR; if \fIterm\fR is null, the
 127 environment variable \fBTERM\fR is used.
 128 All output is to file descriptor \fBfildes\fR which is initialized for output.
 129 If \fIerrret\fR is not null,
 130 then \fBsetupterm\fR returns \fBOK\fR or
 131 \fBERR\fR and stores a status value in the integer pointed to by
 132 \fIerrret\fR.
 133 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
 134 is normal.
 135 If \fBERR\fR is returned, examine \fIerrret\fR:
 136 .RS
 137 .TP 5
 138 .B 1
 139 means that the terminal is hardcopy, cannot be used for curses applications.
 140 .TP 5
 141 .B 0
 142 means that the terminal could not be found,
 143 or that it is a generic type,
 144 having too little information for curses applications to run.
 145 .TP 5
 146 .B -1
 147 means that the \fBterminfo\fR database could not be found.
 148 .RE
 149 .PP
 150 If \fIerrret\fR is
 151 null, \fBsetupterm\fR prints an error message upon finding an error
 152 and exits.  Thus, the simplest call is:
 153
 154       \fBsetupterm((char *)0, 1, (int *)0);\fR,
 155
 156 which uses all the defaults and sends the output to \fBstdout\fR.
 157
 158 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
 159
 160       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
 161
 162 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
 163 The \fBsetterm\fR routine is included here for BSD compatibility, and
 164 is not recommended for new programs.
 165
 166 The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
 167 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
 168 string variables use the values from \fInterm\fR.  It returns the old value
 169 of \fBcur_term\fR.
 170
 171 The \fBdel_curterm\fR routine frees the space pointed to by
 172 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
 173 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
 174 boolean, numeric, and string variables thereafter may refer to invalid
 175 memory locations until another \fBsetupterm\fR has been called.
 176
 177 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
 178 except that it is called after restoring memory to a previous state (for
 179 example, when reloading a game saved as a core image dump).  It assumes that
 180 the windows and the input and output options are the same as when memory was
 181 saved, but the terminal type and baud rate may be different.  Accordingly,
 182 it saves various tty state bits, does a setupterm, and then restores the bits.
 183
 184 The \fBtparm\fR routine instantiates the string \fIstr\fR with
 185 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
 186 with the parameters applied.
 187
 188 The \fBtputs\fR routine applies padding information to the string
 189 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
 190 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
 191 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
 192 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
 193 the characters are passed, one at a time.
 194
 195 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
 196 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
 197 the \fIfildes\fR specified in \fBsetupterm\fR.
 198
 199 The \fBvidputs\fR routine displays the string on the terminal in the
 200 video attribute mode \fIattrs\fR, which is any combination of the
 201 attributes listed in \fBcurses\fR(3X).  The characters are passed to
 202 the \fBputchar\fR-like routine \fIputc\fR.
 203
 204 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
 205 that it outputs through \fBputchar\fR.
 206
 207 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
 208 respectively.
 209 They use a set of arguments for representing the video attributes plus color,
 210 i.e.,
 211 one of type attr_t for the attributes and one of short for
 212 the color_pair number.
 213 The \fBvid_attr\fR and \fBvid_puts\fR routines
 214 are designed to use the attribute constants with the \fIWA_\fR prefix.
 215 The opts argument is reserved for future use.
 216 Currently, applications must provide a null pointer for that argument.
 217
 218 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
 219 effect immediately (rather than at the next refresh).
 220
 221 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
 222 the value of the capability corresponding to the \fBterminfo\fR
 223 \fIcapname\fR passed to them, such as \fBxenl\fR.
 224
 225 The \fBtigetflag\fR routine returns the value \fB-1\fR if
 226 \fIcapname\fR is not a boolean capability,
 227 or \fB0\fR if it is canceled or absent from the terminal description.
 228
 229 The \fBtigetnum\fR routine returns the value \fB-2\fR if
 230 \fIcapname\fR is not a numeric capability,
 231 or \fB-1\fR if it is canceled or absent from the terminal description.
 232
 233 The \fBtigetstr\fR routine returns the value \fB(char *)-1\fR
 234 if \fIcapname\fR is not a string capability,
 235 or \fB0\fR if it is canceled or absent from the terminal description.
 236
 237 The \fIcapname\fR for each capability is given in the table column entitled
 238 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
 239
 240 \fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR
 241
 242 \fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR
 243
 244 \fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR
 245
 246 These null-terminated arrays contain the \fIcapnames\fR, the
 247 \fBtermcap\fR codes, and the full C names, for each of the
 248 \fBterminfo\fR variables.
 249 .SH RETURN VALUE
 250 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 251 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
 252 completion, unless otherwise noted in the preceding routine descriptions.
 253
 254 Routines that return pointers always return \fBNULL\fR on error.
 255 .SH NOTES
 256 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
 257 It may be useful when you want to test for terminal capabilities without
 258 committing to the allocation of storage involved in \fBinitscr\fR.
 259
 260 Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
 261 .SH PORTABILITY
 262 The function \fBsetterm\fR is not described in the XSI Curses standard and must
 263 be considered non-portable.  All other functions are as described in the XSI
 264 curses standard.
 265
 266 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
 267 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the XSI Curses
 268 semantics.
 269
 270 In System V Release 4, the third argument of \fBtputs\fR has the type
 271 \fBint (*putc)(char)\fR.
 272
 273 The XSI Curses standard prototypes \fBtparm\fR with a fixed number of parameters,
 274 rather than a variable argument list.
 275 This implementation uses a variable argument list.
 276 Portable applications should provide 9 parameters after the format;
 277 zeroes are fine for this purpose.
 278
 279 XSI notes that after calling \fBmvcur\fR, the curses state may not match the
 280 actual terminal state, and that an application should touch and refresh
 281 the window before resuming normal curses calls.
 282 Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
 283 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
 284 So though it is documented as a terminfo function,
 285 \fBmvcur\fR is really a curses function which is not well specified.
 286 .SH SEE ALSO
 287 \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X),
 288 \fBputc\fR(3S), \fBterminfo\fR(\*n)
 289 .\"#
 290 .\"# The following sets edit modes for GNU EMACS
 291 .\"# Local Variables:
 292 .\"# mode:nroff
 293 .\"# fill-column:79
 294 .\"# End: