man/curs_terminfo.3x

   1 .\"***************************************************************************
   2 .\" Copyright (c) 1999-2010,2011 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.36 2011/12/17 23:31:40 tom Exp $
  30 .TH curs_terminfo 3X ""
  31 .ds n 5
  32 .na
  33 .hy 0
  34 .SH NAME
  35 \fBdel_curterm\fR,
  36 \fBmvcur\fR,
  37 \fBputp\fR,
  38 \fBrestartterm\fR,
  39 \fBset_curterm\fR,
  40 \fBsetterm\fR,
  41 \fBsetupterm\fR,
  42 \fBtigetflag\fR,
  43 \fBtigetnum\fR,
  44 \fBtigetstr\fR,
  45 \fBtiparm\fR,
  46 \fBtparm\fR,
  47 \fBtputs\fR,
  48 \fBvid_attr\fR,
  49 \fBvid_puts\fR,
  50 \fBvidattr\fR,
  51 \fBvidputs\fR \- \fBcurses\fR interfaces to terminfo database
  52 .ad
  53 .hy
  54 .SH SYNOPSIS
  55 .nf
  56 \fB#include <curses.h>\fR
  57 .br
  58 \fB#include <term.h>\fR
  59 .PP
  60 \fBint setupterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
  61 .br
  62 \fBint setterm(char *\fR\fIterm\fR\fB);\fR
  63 .br
  64 \fBTERMINAL *set_curterm(TERMINAL *\fR\fInterm\fR\fB);\fR
  65 .br
  66 \fBint del_curterm(TERMINAL *\fR\fIoterm\fR\fB);\fR
  67 .br
  68 \fBint restartterm(char *\fR\fIterm\fR\fB, int \fR\fIfildes\fR\fB, int *\fR\fIerrret\fR\fB);\fR
  69 .br
  70 \fBchar *tparm(char *\fR\fIstr\fR\fB, ...);\fR
  71 .br
  72 \fBint tputs(const char *\fR\fIstr\fR\fB, int \fR\fIaffcnt\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
  73 .br
  74 \fBint putp(const char *\fR\fIstr\fR\fB);\fR
  75 .br
  76 \fBint vidputs(chtype \fR\fIattrs\fR\fB, int (*\fR\fIputc\fR\fB)(int));\fR
  77 .br
  78 \fBint vidattr(chtype \fR\fIattrs\fR\fB);\fR
  79 .br
  80 \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
  81 .br
  82 \fBint vid_attr(attr_t \fR\fIattrs\fR\fB, short \fR\fIpair\fR\fB, void *\fR\fIopts\fR\fB);\fR
  83 .br
  84 \fBint mvcur(int \fR\fIoldrow\fR\fB, int \fR\fIoldcol\fR\fB, int \fR\fInewrow\fR, int \fR\fInewcol\fR\fB);\fR
  85 .br
  86 \fBint tigetflag(char *\fR\fIcapname\fR\fB);\fR
  87 .br
  88 \fBint tigetnum(char *\fR\fIcapname\fR\fB);\fR
  89 .br
  90 \fBchar *tigetstr(char *\fR\fIcapname\fR\fB);\fR
  91 .br
  92 \fBchar *tiparm(const char *\fR\fIstr\fR\fB, ...);\fR
  93 .br
  94 .fi
  95 .SH DESCRIPTION
  96 These low-level routines must be called by programs that have to deal
  97 directly with the \fBterminfo\fR database to handle certain terminal
  98 capabilities, such as programming function keys.  For all other
  99 functionality, \fBcurses\fR routines are more suitable and their use is
 100 recommended.
 101 .PP
 102 Initially, \fBsetupterm\fR should be called.  Note that
 103 \fBsetupterm\fR is automatically called by \fBinitscr\fR and
 104 \fBnewterm\fR.  This defines the set of terminal-dependent variables
 105 [listed in \fBterminfo\fR(\*n)].
 106 The \fBterminfo\fR variables
 107 \fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as
 108 follows:
 109 .RS
 110 .PP
 111 If \fBuse_env(FALSE)\fR has been called, values for
 112 \fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used.
 113 .PP
 114 Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR
 115 exist, their values are used.  If these environment variables do not
 116 exist and the program is running in a window, the current window size
 117 is used.  Otherwise, if the environment variables do not exist, the
 118 values for \fBlines\fR and \fBcolumns\fR specified in the
 119 \fBterminfo\fR database are used.
 120 .RE
 121 .PP
 122 The header files \fBcurses.h\fR and \fBterm.h\fR should be included (in this
 123 order) to get the definitions for these strings, numbers, and flags.
 124 Parameterized strings should be passed through \fBtparm\fR to instantiate them.
 125 All \fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed
 126 with \fBtputs\fR or \fBputp\fR.  Call the \fBreset_shell_mode\fR to restore the
 127 tty modes before exiting [see \fBcurs_kernel\fR(3X)].  Programs which use
 128 cursor addressing should output \fBenter_ca_mode\fR upon startup and should
 129 output \fBexit_ca_mode\fR before exiting.  Programs desiring shell escapes
 130 should call
 131 .PP
 132 \fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell
 133 is called and should output \fBenter_ca_mode\fR and call
 134 \fBreset_prog_mode\fR after returning from the shell.
 135 .PP
 136 The \fBsetupterm\fR routine reads in the \fBterminfo\fR database,
 137 initializing the \fBterminfo\fR structures, but does not set up the
 138 output virtualization structures used by \fBcurses\fR.  The terminal
 139 type is the character string \fIterm\fR; if \fIterm\fR is null, the
 140 environment variable \fBTERM\fR is used.
 141 All output is to file descriptor \fBfildes\fR which is initialized for output.
 142 If \fIerrret\fR is not null,
 143 then \fBsetupterm\fR returns \fBOK\fR or
 144 \fBERR\fR and stores a status value in the integer pointed to by
 145 \fIerrret\fR.
 146 A return value of \fBOK\fR combined with status of \fB1\fR in \fIerrret\fR
 147 is normal.
 148 If \fBERR\fR is returned, examine \fIerrret\fR:
 149 .RS
 150 .TP 5
 151 .B 1
 152 means that the terminal is hardcopy, cannot be used for curses applications.
 153 .TP 5
 154 .B 0
 155 means that the terminal could not be found,
 156 or that it is a generic type,
 157 having too little information for curses applications to run.
 158 .TP 5
 159 .B \-1
 160 means that the \fBterminfo\fR database could not be found.
 161 .RE
 162 .PP
 163 If \fIerrret\fR is
 164 null, \fBsetupterm\fR prints an error message upon finding an error
 165 and exits.  Thus, the simplest call is:
 166 .sp
 167       \fBsetupterm((char *)0, 1, (int *)0);\fR,
 168 .sp
 169 which uses all the defaults and sends the output to \fBstdout\fR.
 170 .PP
 171 The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR.  The call:
 172 .sp
 173       \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR
 174 .sp
 175 provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR.
 176 The \fBsetterm\fR routine is included here for BSD compatibility, and
 177 is not recommended for new programs.
 178 .PP
 179 The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to
 180 \fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and
 181 string variables use the values from \fInterm\fR.  It returns the old value
 182 of \fBcur_term\fR.
 183 .PP
 184 The \fBdel_curterm\fR routine frees the space pointed to by
 185 \fIoterm\fR and makes it available for further use.  If \fIoterm\fR is
 186 the same as \fBcur_term\fR, references to any of the \fBterminfo\fR
 187 boolean, numeric, and string variables thereafter may refer to invalid
 188 memory locations until another \fBsetupterm\fR has been called.
 189 .PP
 190 The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and \fBinitscr\fR,
 191 except that it is called after restoring memory to a previous state (for
 192 example, when reloading a game saved as a core image dump).  It assumes that
 193 the windows and the input and output options are the same as when memory was
 194 saved, but the terminal type and baud rate may be different.  Accordingly,
 195 it saves various tty state bits, calls \fBsetupterm\fP,
 196 and then restores the bits.
 197 .PP
 198 The \fBtparm\fR routine instantiates the string \fIstr\fR with
 199 parameters \fIpi\fR.  A pointer is returned to the result of \fIstr\fR
 200 with the parameters applied.
 201 .PP
 202 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
 203 rather than a fixed-parameter list.
 204 Its numeric parameters are integers (int) rather than longs.
 205 .PP
 206 The \fBtputs\fR routine applies padding information to the string
 207 \fIstr\fR and outputs it.  The \fIstr\fR must be a terminfo string
 208 variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or
 209 \fBtgoto\fR.  \fIaffcnt\fR is the number of lines affected, or 1 if
 210 not applicable.  \fIputc\fR is a \fBputchar\fR-like routine to which
 211 the characters are passed, one at a time.
 212 .PP
 213 The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR.
 214 Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to
 215 the \fIfildes\fR specified in \fBsetupterm\fR.
 216 .PP
 217 The \fBvidputs\fR routine displays the string on the terminal in the
 218 video attribute mode \fIattrs\fR, which is any combination of the
 219 attributes listed in \fBcurses\fR(3X).  The characters are passed to
 220 the \fBputchar\fR-like routine \fIputc\fR.
 221 .PP
 222 The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except
 223 that it outputs through \fBputchar\fR.
 224 .PP
 225 The \fBvid_attr\fR and \fBvid_puts\fR routines correspond to vidattr and vidputs,
 226 respectively.
 227 They use a set of arguments for representing the video attributes plus color,
 228 i.e.,
 229 one of type attr_t for the attributes and one of short for
 230 the color_pair number.
 231 The \fBvid_attr\fR and \fBvid_puts\fR routines
 232 are designed to use the attribute constants with the \fIWA_\fR prefix.
 233 The opts argument is reserved for future use.
 234 Currently, applications must provide a null pointer for that argument.
 235 .PP
 236 The \fBmvcur\fR routine provides low-level cursor motion.  It takes
 237 effect immediately (rather than at the next refresh).
 238 .PP
 239 The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return
 240 the value of the capability corresponding to the \fBterminfo\fR
 241 \fIcapname\fR passed to them, such as \fBxenl\fR.
 242 .PP
 243 The \fBtigetflag\fR routine returns the value \fB\-1\fR if
 244 \fIcapname\fR is not a boolean capability,
 245 or \fB0\fR if it is canceled or absent from the terminal description.
 246 .PP
 247 The \fBtigetnum\fR routine returns the value \fB\-2\fR if
 248 \fIcapname\fR is not a numeric capability,
 249 or \fB\-1\fR if it is canceled or absent from the terminal description.
 250 .PP
 251 The \fBtigetstr\fR routine returns the value \fB(char *)\-1\fR
 252 if \fIcapname\fR is not a string capability,
 253 or \fB0\fR if it is canceled or absent from the terminal description.
 254 .PP
 255 The \fIcapname\fR for each capability is given in the table column entitled
 256 \fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n).
 257 .sp
 258 .RS
 259 \fBchar *boolnames[]\fR, \fB*boolcodes[]\fR, \fB*boolfnames[]\fR
 260 .sp
 261 \fBchar *numnames[]\fR, \fB*numcodes[]\fR, \fB*numfnames[]\fR
 262 .sp
 263 \fBchar *strnames[]\fR, \fB*strcodes[]\fR, \fB*strfnames[]\fR
 264 .RE
 265 .PP
 266 These null-terminated arrays contain the \fIcapnames\fR, the
 267 \fBtermcap\fR codes, and the full C names, for each of the
 268 \fBterminfo\fR variables.
 269 .SH RETURN VALUE
 270 Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
 271 (SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
 272 completion, unless otherwise noted in the preceding routine descriptions.
 273 .PP
 274 Routines that return pointers always return \fBNULL\fR on error.
 275 .PP
 276 X/Open defines no error conditions.
 277 In this implementation
 278 .RS
 279 .TP 5
 280 \fBdel_curterm\fP
 281 returns an error
 282 if its terminal parameter is null.
 283 .TP 5
 284 \fBputp\fP
 285 calls \fBtputs\fP, returning the same error-codes.
 286 .TP 5
 287 \fBrestartterm\fP
 288 returns an error
 289 if the associated call to \fBsetupterm\fP returns an error.
 290 .TP 5
 291 \fBsetupterm\fP
 292 returns an error
 293 if it cannot allocate enough memory, or
 294 create the initial windows (stdscr, curscr, newscr).
 295 Other error conditions are documented above.
 296 .TP 5
 297 \fBtputs\fP
 298 returns an error if the string parameter is null.
 299 It does not detect I/O errors:
 300 X/Open states that \fBtputs\fP ignores the return value
 301 of the output function \fIputc\fP.
 302 .RE
 303 .SH NOTES
 304 The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR.
 305 It may be useful when you want to test for terminal capabilities without
 306 committing to the allocation of storage involved in \fBinitscr\fR.
 307 .PP
 308 Note that \fBvidattr\fR and \fBvidputs\fR may be macros.
 309 .SH PORTABILITY
 310 The function \fBsetterm\fR is not described by X/Open and must
 311 be considered non-portable.  All other functions are as described by X/Open.
 312 .PP
 313 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
 314 This is not part of X/Open Curses, but is assumed by some applications.
 315 .PP
 316 In System V Release 4, \fBset_curterm\fR has an \fBint\fR return type and
 317 returns \fBOK\fR or \fBERR\fR.  We have chosen to implement the X/Open Curses
 318 semantics.
 319 .PP
 320 In System V Release 4, the third argument of \fBtputs\fR has the type
 321 \fBint (*putc)(char)\fR.
 322 .PP
 323 At least one implementation of X/Open Curses (Solaris) returns a value
 324 other than OK/ERR from \fBtputs\fP.
 325 That returns the length of the string, and does no error-checking.
 326 .PP
 327 X/Open Curses prototypes \fBtparm\fR with a fixed number of parameters,
 328 rather than a variable argument list.
 329 This implementation uses a variable argument list, but can be
 330 configured to use the fixed-parameter list.
 331 Portable applications should provide 9 parameters after the format;
 332 zeroes are fine for this purpose.
 333 .PP
 334 In response to comments by Thomas E. Dickey,
 335 X/Open Curses Issue 7 proposed the \fBtiparam\fP function in mid-2009.
 336 .PP
 337 X/Open notes that after calling \fBmvcur\fR, the curses state may not match the
 338 actual terminal state, and that an application should touch and refresh
 339 the window before resuming normal curses calls.
 340 Both ncurses and System V Release 4 curses implement \fBmvcur\fR using
 341 the SCREEN data allocated in either \fBinitscr\fR or \fBnewterm\fR.
 342 So though it is documented as a terminfo function,
 343 \fBmvcur\fR is really a curses function which is not well specified.
 344 .PP
 345 X/Open states that the old location must be given for \fBmvcur\fP.
 346 This implementation allows the caller to use \-1's for the old ordinates.
 347 In that case, the old location is unknown.
 348 .PP
 349 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
 350 are not stored in the arrays described in this section.
 351 .SH SEE ALSO
 352 \fBcurses\fR(3X),
 353 \fBcurs_initscr\fR(3X),
 354 \fBcurs_kernel\fR(3X),
 355 \fBcurs_termcap\fR(3X),
 356 \fBcurs_variables\fR(3X),
 357 \fBterm_variables\fR(3X),
 358 \fBputc\fR(3),
 359 \fBterminfo\fR(\*n)