man/curs_terminfo.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_terminfo.3x,v 1.83 2023/04/08 22:54:21 tom Exp $
  31 .TH curs_terminfo 3X ""
  32 .ie \n(.g .ds `` \(lq
  33 .el       .ds `` ``
  34 .ie \n(.g .ds '' \(rq
  35 .el       .ds '' ''
  36 .de bP
  37 .ie n  .IP \(bu 4
  38 .el    .IP \(bu 2
  39 ..
  40 .ds n 5
  41 .na
  42 .hy 0
  43 .SH NAME
  44 \fBdel_curterm\fP,
  45 \fBmvcur\fP,
  46 \fBputp\fP,
  47 \fBrestartterm\fP,
  48 \fBset_curterm\fP,
  49 \fBsetupterm\fP,
  50 \fBtigetflag\fP,
  51 \fBtigetnum\fP,
  52 \fBtigetstr\fP,
  53 \fBtiparm\fP,
  54 \fBtparm\fP,
  55 \fBtputs\fP,
  56 \fBvid_attr\fP,
  57 \fBvid_puts\fP,
  58 \fBvidattr\fP,
  59 \fBvidputs\fP \- \fBcurses\fP interfaces to terminfo database
  60 .ad
  61 .hy
  62 .SH SYNOPSIS
  63 .nf
  64 \fB#include <curses.h>\fP
  65 \fB#include <term.h>\fP
  66 .sp
  67 \fBTERMINAL *cur_term;\fP
  68 .sp
  69 \fBconst char * const boolnames[];\fP
  70 \fBconst char * const boolcodes[];\fP
  71 \fBconst char * const boolfnames[];\fP
  72 \fBconst char * const numnames[];\fP
  73 \fBconst char * const numcodes[];\fP
  74 \fBconst char * const numfnames[];\fP
  75 \fBconst char * const strnames[];\fP
  76 \fBconst char * const strcodes[];\fP
  77 \fBconst char * const strfnames[];\fP
  78 .sp
  79 \fBint setupterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR
  80 .br
  81 \fBTERMINAL *set_curterm(TERMINAL *\fInterm\fB);\fR
  82 .br
  83 \fBint del_curterm(TERMINAL *\fIoterm\fB);\fR
  84 .br
  85 \fBint restartterm(const char *\fIterm\fB, int \fIfiledes\fB, int *\fIerrret\fB);\fR
  86 .sp
  87 \fBchar *tparm(const char *\fIstr\fB, ...);\fR
  88 .br
  89         \fIor\fP
  90 .br
  91 \fBchar *tparm(const char *\fIstr\fB, long \fIp1 ... \fBlong \fIp9\fB);\fR
  92 .sp
  93 \fBint tputs(const char *\fIstr\fB, int \fIaffcnt\fB, int (*\fIputc\fB)(int));\fR
  94 .br
  95 \fBint putp(const char *\fIstr\fB);\fR
  96 .sp
  97 \fBint vidputs(chtype \fIattrs\fB, int (*\fIputc\fB)(int));\fR
  98 .br
  99 \fBint vidattr(chtype \fIattrs\fB);\fR
 100 .br
 101 \fBint vid_puts(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB, int (*\fIputc\fB)(int));\fR
 102 .br
 103 \fBint vid_attr(attr_t \fIattrs\fB, short \fIpair\fB, void *\fIopts\fB);\fR
 104 .sp
 105 \fBint mvcur(int \fIoldrow\fB, int \fIoldcol\fB, int \fInewrow\fR, int \fInewcol\fB);\fR
 106 .sp
 107 \fBint tigetflag(const char *\fIcapname\fB);\fR
 108 .br
 109 \fBint tigetnum(const char *\fIcapname\fB);\fR
 110 .br
 111 \fBchar *tigetstr(const char *\fIcapname\fB);\fR
 112 .sp
 113 \fBchar *tiparm(const char *\fIstr\fB, ...);\fR
 114 .br
 115 .fi
 116 .SH DESCRIPTION
 117 These low-level routines must be called by programs that have to deal
 118 directly with the \fBterminfo\fP database to handle certain terminal
 119 capabilities, such as programming function keys.
 120 For all other
 121 functionality, \fBcurses\fP routines are more suitable and their use is
 122 recommended.
 123 .PP
 124 None of these functions use (or are aware of) multibyte character strings
 125 such as UTF-8:
 126 .bP
 127 capability names use the POSIX portable character set
 128 .bP
 129 capability string values have no associated encoding;
 130 they are strings of 8-bit characters.
 131 .SS Initialization
 132 .PP
 133 Initially, \fBsetupterm\fP should be called.
 134 The high-level curses functions \fBinitscr\fP and
 135 \fBnewterm\fP call \fBsetupterm\fP to initialize the
 136 low-level set of terminal-dependent variables
 137 [listed in \fBterminfo\fP(\*n)].
 138 .PP
 139 Applications can use the
 140 terminal capabilities either directly (via header definitions),
 141 or by special functions.
 142 The header files \fBcurses.h\fP and \fBterm.h\fP should be included (in this
 143 order) to get the definitions for these strings, numbers, and flags.
 144 .PP
 145 The \fBterminfo\fP variables
 146 \fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as
 147 follows:
 148 .bP
 149 If \fBuse_env(FALSE)\fP has been called, values for
 150 \fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used.
 151 .bP
 152 Otherwise, if the environment variables \fBLINES\fP and \fBCOLUMNS\fP
 153 exist, their values are used.
 154 If these environment variables do not
 155 exist and the program is running in a window, the current window size
 156 is used.
 157 Otherwise, if the environment variables do not exist, the
 158 values for \fBlines\fP and \fBcolumns\fP specified in the
 159 \fBterminfo\fP database are used.
 160 .PP
 161 Parameterized strings should be passed through \fBtparm\fP to instantiate them.
 162 All \fBterminfo\fP strings
 163 (including the output of \fBtparm\fP)
 164 should be printed
 165 with \fBtputs\fP or \fBputp\fP.
 166 Call \fBreset_shell_mode\fP to restore the
 167 tty modes before exiting [see \fBcurs_kernel\fP(3X)].
 168 .PP
 169 Programs which use
 170 cursor addressing should
 171 .bP
 172 output \fBenter_ca_mode\fP upon startup and
 173 .bP
 174 output \fBexit_ca_mode\fP before exiting.
 175 .PP
 176 Programs which execute shell subprocesses should
 177 .bP
 178 call \fBreset_shell_mode\fP and
 179 output \fBexit_ca_mode\fP before the shell
 180 is called and
 181 .bP
 182 output \fBenter_ca_mode\fP and
 183 call \fBreset_prog_mode\fP after returning from the shell.
 184 .PP
 185 The \fBsetupterm\fP routine reads in the \fBterminfo\fP database,
 186 initializing the \fBterminfo\fP structures, but does not set up the
 187 output virtualization structures used by \fBcurses\fP.
 188 These are its parameters:
 189 .RS 3
 190 .TP 5
 191 \fIterm\fP
 192 is the terminal type, a character string.
 193 If \fIterm\fP is null, the environment variable \fBTERM\fP is used.
 194 .TP 5
 195 \fIfiledes\fP
 196 is the file descriptor used for all output.
 197 .TP 5
 198 \fIerrret\fP
 199 points to an optional location where an error status can be returned to
 200 the caller.
 201 If \fIerrret\fP is not null,
 202 then \fBsetupterm\fP returns \fBOK\fP or
 203 \fBERR\fP and stores a status value in the integer pointed to by
 204 \fIerrret\fP.
 205 A return value of \fBOK\fP combined with status of \fB1\fP in \fIerrret\fP
 206 is normal.
 207 .IP
 208 If \fBERR\fP is returned, examine \fIerrret\fP:
 209 .RS
 210 .TP 5
 211 .B 1
 212 means that the terminal is hardcopy, cannot be used for curses applications.
 213 .IP
 214 \fBsetupterm\fP determines if the entry is a hardcopy type by
 215 checking the \fBhc\fP (\fBhardcopy\fP) capability.
 216 .TP 5
 217 .B 0
 218 means that the terminal could not be found,
 219 or that it is a generic type,
 220 having too little information for curses applications to run.
 221 .IP
 222 \fBsetupterm\fP determines if the entry is a generic type by
 223 checking the \fBgn\fP (\fBgeneric\fP) capability.
 224 .TP 5
 225 .B \-1
 226 means that the \fBterminfo\fP database could not be found.
 227 .RE
 228 .IP
 229 If \fIerrret\fP is
 230 null, \fBsetupterm\fP prints an error message upon finding an error
 231 and exits.
 232 Thus, the simplest call is:
 233 .sp
 234       \fBsetupterm((char *)0, 1, (int *)0);\fP,
 235 .sp
 236 which uses all the defaults and sends the output to \fBstdout\fP.
 237 .RE
 238 .\" ***************************************************************************
 239 .SS The Terminal State
 240 .PP
 241 The \fBsetupterm\fP routine stores its information about the terminal
 242 in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
 243 If it detects an error,
 244 or decides that the terminal is unsuitable (hardcopy or generic),
 245 it discards this information,
 246 making it not available to applications.
 247 .PP
 248 If \fBsetupterm\fP is called repeatedly for the same terminal type,
 249 it will reuse the information.
 250 It maintains only one copy of a given terminal's capabilities in memory.
 251 If it is called for different terminal types,
 252 \fBsetupterm\fP allocates new storage for each set of terminal capabilities.
 253 .PP
 254 The \fBset_curterm\fP routine sets \fBcur_term\fP to
 255 \fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and
 256 string variables use the values from \fInterm\fP.
 257 It returns the old value of \fBcur_term\fP.
 258 .PP
 259 The \fBdel_curterm\fP routine frees the space pointed to by
 260 \fIoterm\fP and makes it available for further use.
 261 If \fIoterm\fP is
 262 the same as \fBcur_term\fP, references to any of the \fBterminfo\fP
 263 boolean, numeric, and string variables thereafter may refer to invalid
 264 memory locations until another \fBsetupterm\fP has been called.
 265 .PP
 266 The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP,
 267 except that it is called after restoring memory to a previous state (for
 268 example, when reloading a game saved as a core image dump).
 269 \fBrestartterm\fP assumes that the windows and the input and output options
 270 are the same as when memory was saved,
 271 but the terminal type and baud rate may be different.
 272 Accordingly, \fBrestartterm\fP saves various tty state bits,
 273 calls \fBsetupterm\fP, and then restores the bits.
 274 .\" ***************************************************************************
 275 .SS Formatting Output
 276 .PP
 277 The \fBtparm\fP routine instantiates the string \fIstr\fP with
 278 parameters \fIpi\fP.  A pointer is returned to the result of \fIstr\fP
 279 with the parameters applied.
 280 Application developers should keep in mind these quirks of the interface:
 281 .bP
 282 Although \fBtparm\fP's actual parameters may be integers or strings,
 283 the prototype expects \fBlong\fP (integer) values.
 284 .bP
 285 Aside from the \fBset_attributes\fP (\fBsgr\fP) capability,
 286 most terminal capabilities require no more than one or two parameters.
 287 .bP
 288 Padding information is ignored by \fBtparm\fP;
 289 it is interpreted by \fBtputs\fP.
 290 .bP
 291 The capability string is null-terminated.
 292 Use \*(``\\200\*('' where an ASCII NUL is needed in the output.
 293 .PP
 294 \fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
 295 rather than a fixed-parameter list.
 296 Its numeric parameters are integers (int) rather than longs.
 297 .\" ***************************************************************************
 298 .SS Output Functions
 299 .PP
 300 The \fBtputs\fP routine applies padding information
 301 (i.e., by interpreting marker embedded in the terminfo capability
 302 such as \*(``$<5>\*('' as 5 milliseconds)
 303 to the string
 304 \fIstr\fP and outputs it:
 305 .bP
 306 The \fIstr\fP parameter must be a terminfo string
 307 variable or the return value from
 308 \fBtparm\fP, \fBtiparm\fP, \fBtgetstr\fP, or \fBtgoto\fP.
 309 .IP
 310 The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
 311 interface,
 312 which happens to share this function name with the \fIterminfo\fP interface.
 313 .bP
 314 \fIaffcnt\fP is the number of lines affected, or 1 if
 315 not applicable.
 316 .bP
 317 \fIputc\fP is a \fBputchar\fP-like routine to which
 318 the characters are passed, one at a time.
 319 .PP
 320 The \fBputp\fR routine calls \fBtputs(\fIstr\fB, 1, putchar)\fR.
 321 The output of \fBputp\fP always goes to \fBstdout\fP, rather than
 322 the \fIfiledes\fP specified in \fBsetupterm\fP.
 323 .PP
 324 The \fBvidputs\fP routine displays the string on the terminal in the
 325 video attribute mode \fIattrs\fP, which is any combination of the
 326 attributes listed in \fBcurses\fP(3X).
 327 The characters are passed to
 328 the \fBputchar\fP-like routine \fIputc\fP.
 329 .PP
 330 The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except
 331 that it outputs through \fBputchar\fP.
 332 .PP
 333 The \fBvid_attr\fP and \fBvid_puts\fP routines correspond
 334 to vidattr and vidputs, respectively.
 335 They use a set of arguments for representing the video attributes plus color,
 336 i.e.,
 337 .bP
 338 \fIattrs\fP of type \fBattr_t\fP for the attributes and
 339 .bP
 340 \fIpair\fP of type \fBshort\fP for the color-pair number.
 341 .PP
 342 The \fBvid_attr\fP and \fBvid_puts\fP routines
 343 are designed to use the attribute constants with the \fBWA_\fP prefix.
 344 .PP
 345 X/Open Curses reserves the \fIopts\fP argument for future use,
 346 saying that applications must provide a null pointer for that argument.
 347 As an extension,
 348 this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
 349 which overrides the \fIpair\fP (\fBshort\fP) argument.
 350 .PP
 351 The \fBmvcur\fP routine provides low-level cursor motion.
 352 It takes effect immediately (rather than at the next refresh).
 353 .PP
 354 While \fBputp\fP and \fBmvcur\fP are low-level functions which
 355 do not use the high-level curses state,
 356 they are declared in \fB<curses.h>\fP because SystemV did this
 357 (see \fIHISTORY\fP).
 358 .\" ***************************************************************************
 359 .SS Terminal Capability Functions
 360 .PP
 361 The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return
 362 the value of the capability corresponding to the \fBterminfo\fP
 363 \fIcapname\fP passed to them, such as \fBxenl\fP.
 364 The \fIcapname\fP for each capability is given in the table column entitled
 365 \fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n).
 366 .PP
 367 These routines return special values to denote errors.
 368 .PP
 369 The \fBtigetflag\fP routine returns
 370 .TP
 371 \fB\-1\fP
 372 if \fIcapname\fP is not a boolean capability,
 373 or
 374 .TP
 375 \fB0\fP
 376 if it is canceled or absent from the terminal description.
 377 .PP
 378 The \fBtigetnum\fP routine returns
 379 .TP
 380 \fB\-2\fP
 381 if \fIcapname\fP is not a numeric capability, or
 382 .TP
 383 \fB\-1\fP
 384 if it is canceled or absent from the terminal description.
 385 .PP
 386 The \fBtigetstr\fP routine returns
 387 .TP
 388 \fB(char *)\-1\fP
 389 if \fIcapname\fP is not a string capability,
 390 or
 391 .TP
 392 \fB0\fP
 393 if it is canceled or absent from the terminal description.
 394 .\" ***************************************************************************
 395 .SS Terminal Capability Names
 396 .PP
 397 These null-terminated arrays contain
 398 .bP
 399 the short terminfo names (\*(``codes\*(''),
 400 .bP
 401 the \fBtermcap\fP names (\*(``names\*(''), and
 402 .bP
 403 the long terminfo names (\*(``fnames\*('')
 404 .PP
 405 for each of the predefined \fBterminfo\fP variables:
 406 .sp
 407 .RS
 408 \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
 409 .br
 410 \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
 411 .br
 412 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
 413 .RE
 414 .\" ***************************************************************************
 415 .SS Releasing Memory
 416 Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
 417 description.
 418 As a side-effect, it sets \fBcur_term\fP to point to this memory.
 419 If an application calls
 420 .sp
 421         \fBdel_curterm(cur_term);\fP
 422 .sp
 423 the memory will be freed.
 424 .PP
 425 The formatting functions \fBtparm\fP and \fBtiparm\fP extend the storage
 426 allocated by \fBsetupterm\fP:
 427 .bP
 428 the \*(``static\*('' terminfo variables [a-z].
 429 Before ncurses 6.3, those were shared by all screens.
 430 With ncurses 6.3, those are allocated per screen.
 431 See \fBterminfo\fP(\*n) for details.
 432 .bP
 433 to improve performance, ncurses 6.3 caches the result of analyzing terminfo
 434 strings for their parameter types.
 435 That is stored as a binary tree referenced from the \fBTERMINAL\fP structure.
 436 .PP
 437 The higher-level \fBinitscr\fP and \fBnewterm\fP functions use \fBsetupterm\fP.
 438 Normally they do not free this memory, but it is possible to do that using
 439 the \fBdelscreen\fP(3X) function.
 440 .\" ***************************************************************************
 441 .SH RETURN VALUE
 442 Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
 443 (SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('')
 444 upon successful completion,
 445 unless otherwise noted in the preceding routine descriptions.
 446 .PP
 447 Routines that return pointers always return \fBNULL\fP on error.
 448 .PP
 449 X/Open defines no error conditions.
 450 In this implementation
 451 .RS 3
 452 .TP 5
 453 \fBdel_curterm\fP
 454 returns an error
 455 if its terminal parameter is null.
 456 .TP 5
 457 \fBputp\fP
 458 calls \fBtputs\fP, returning the same error-codes.
 459 .TP 5
 460 \fBrestartterm\fP
 461 returns an error
 462 if the associated call to \fBsetupterm\fP returns an error.
 463 .TP 5
 464 \fBsetupterm\fP
 465 returns an error
 466 if it cannot allocate enough memory, or
 467 create the initial windows (stdscr, curscr, newscr).
 468 Other error conditions are documented above.
 469 .TP 5
 470 \fBtparm\fP
 471 returns a null if the capability would require unexpected parameters,
 472 e.g., too many, too few, or incorrect types
 473 (strings where integers are expected, or vice versa).
 474 .TP 5
 475 \fBtputs\fP
 476 returns an error if the string parameter is null.
 477 It does not detect I/O errors:
 478 X/Open states that \fBtputs\fP ignores the return value
 479 of the output function \fIputc\fP.
 480 .RE
 481 .\" ***************************************************************************
 482 .SS Compatibility macros
 483 This implementation provides a few macros for compatibility with systems
 484 before SVr4 (see \fIHISTORY\fP).
 485 Those include
 486 \fBcrmode\fP,
 487 \fBfixterm\fP,
 488 \fBgettmode\fP,
 489 \fBnocrmode\fP,
 490 \fBresetterm\fP,
 491 \fBsaveterm\fP, and
 492 \fBsetterm\fP.
 493 .PP
 494 In SVr4, those are found in \fB<curses.h>\fP,
 495 but except for \fBsetterm\fP, are likewise macros.
 496 The one function, \fBsetterm\fP, is mentioned in the manual page.
 497 The manual page notes that the \fBsetterm\fP routine
 498 was replaced by \fBsetupterm\fP, stating that the call:
 499 .sp
 500       \fBsetupterm(\fIterm\fB, 1, (int *)0)\fR
 501 .sp
 502 provides the same functionality as \fBsetterm(\fIterm\fB)\fR,
 503 and is not recommended for new programs.
 504 This implementation provides each of those symbols
 505 as macros for BSD compatibility,
 506 .\" ***************************************************************************
 507 .SH HISTORY
 508 .PP
 509 SVr2 introduced the terminfo feature.
 510 Its programming manual mentioned these low-level functions:
 511 .TS
 512 l l
 513 _ _
 514 l l.
 515 \fBFunction\fP  \fBDescription\fP
 516 fixterm restore tty to \*(``in curses\*('' state
 517 gettmode        establish current tty modes
 518 mvcur   low level cursor motion
 519 putp    T{
 520 utility function that uses \fBtputs\fP to send characters via \fBputchar\fP.
 521 T}
 522 resetterm       set tty modes to \*(``out of curses\*('' state
 523 resetty reset tty flags to stored value
 524 saveterm        save current modes as \*(``in curses\*('' state
 525 savetty store current tty flags
 526 setterm establish terminal with given type
 527 setupterm       establish terminal with given type
 528 tparm   instantiate a string expression with parameters
 529 tputs   apply padding information to a string
 530 vidattr like \fBvidputs\fP, but outputs through \fBputchar\fP
 531 vidputs T{
 532 output a string to put terminal in a specified video attribute mode
 533 T}
 534 .TE
 535 .PP
 536 The programming manual also mentioned
 537 functions provided for termcap compatibility
 538 (commenting that they \*(``may go away at a later date\*(''):
 539 .TS
 540 l l
 541 _ _
 542 l l.
 543 \fBFunction\fP  \fBDescription\fP
 544 tgetent look up termcap entry for given \fIname\fP
 545 tgetflag        get boolean entry for given \fIid\fP
 546 tgetnum get numeric entry for given \fIid\fP
 547 tgetstr get string entry for given \fIid\fP
 548 tgoto   apply parameters to given capability
 549 tputs   T{
 550 apply padding to capability, calling a function to put characters
 551 T}
 552 .TE
 553 .PP
 554 Early terminfo programs obtained capability values from the
 555 \fBTERMINAL\fP structure initialized by \fBsetupterm\fP.
 556 .PP
 557 SVr3 extended terminfo by adding functions to retrieve capability values
 558 (like the termcap interface),
 559 and reusing tgoto and tputs:
 560 .TS
 561 l l
 562 _ _
 563 l l.
 564 \fBFunction\fP  \fBDescription\fP
 565 tigetflag       get boolean entry for given \fIid\fP
 566 tigetnum        get numeric entry for given \fIid\fP
 567 tigetstr        get string entry for given \fIid\fP
 568 .TE
 569 .PP
 570 SVr3 also replaced several of the SVr2 terminfo functions
 571 which had no counterpart in the termcap interface,
 572 documenting them as obsolete:
 573 .TS
 574 l l
 575 _ _
 576 l l.
 577 \fBFunction\fP  \fBReplaced by\fP
 578 crmode  cbreak
 579 fixterm reset_prog_mode
 580 gettmode        N/A
 581 nocrmode        nocbreak
 582 resetterm       reset_shell_mode
 583 saveterm        def_prog_mode
 584 setterm setupterm
 585 .TE
 586 .PP
 587 SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,
 588 along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP.
 589 The latter were needed to support padding,
 590 and handling functions such as \fBvidattr\fP
 591 (which used more than the two parameters supported by \fBtgoto\fP).
 592 .PP
 593 SVr3 introduced the functions for switching between terminal
 594 descriptions, e.g., \fBset_curterm\fP.
 595 Some of that was incremental improvements to the SVr2 library:
 596 .bP
 597 The \fBTERMINAL\fP type definition was introduced in SVr3.01,
 598 for the \fBterm\fP structure provided in SVr2.
 599 .bP
 600 The various global variables such as \fBboolnames\fP were mentioned
 601 in the programming manual at this point,
 602 though the variables were provided in SVr2.
 603 .PP
 604 SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
 605 .PP
 606 There are other low-level functions declared in the curses header files
 607 on Unix systems,
 608 but none were documented.
 609 The functions marked \*(``obsolete\*('' remained in use
 610 by the Unix \fBvi\fP(1) editor.
 611 .SH PORTABILITY
 612 .SS Legacy functions
 613 .PP
 614 X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros.
 615 .PP
 616 The function \fBsetterm\fP is not described by X/Open and must
 617 be considered non-portable.
 618 All other functions are as described by X/Open.
 619 .SS Legacy data
 620 .PP
 621 \fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
 622 This is not part of X/Open Curses, but is assumed by some applications.
 623 .PP
 624 Other implementions may not declare the capability name arrays.
 625 Some provide them without declaring them.
 626 X/Open does not specify them.
 627 .PP
 628 Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
 629 are not stored in the arrays described here.
 630 .SS Output buffering
 631 .PP
 632 Older versions of \fBncurses\fP assumed that the file descriptor passed to
 633 \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
 634 and would write to the corresponding stream.
 635 In addition to the limitation that the terminal was left in block-buffered
 636 mode on exit (like System V curses),
 637 it was problematic because \fBncurses\fP
 638 did not allow a reliable way to cleanup on receiving SIGTSTP.
 639 .PP
 640 The current version (ncurses6)
 641 uses output buffers managed directly by \fBncurses\fP.
 642 Some of the low-level functions described in this manual page write
 643 to the standard output.
 644 They are not signal-safe.
 645 The high-level functions in \fBncurses\fP use
 646 alternate versions of these functions
 647 using the more reliable buffering scheme.
 648 .SS Function prototypes
 649 .PP
 650 The X/Open Curses prototypes are based on the SVr4 curses header declarations,
 651 which were defined at the same time the C language was first standardized in
 652 the late 1980s.
 653 .bP
 654 X/Open Curses uses \fBconst\fP less effectively than a later design might,
 655 in some cases applying it needlessly to values are already constant,
 656 and in most cases overlooking parameters which normally would use \fBconst\fP.
 657 Using constant parameters for functions which do not use \fBconst\fP
 658 may prevent the program from compiling.
 659 On the other hand, \fIwritable strings\fP are an obsolescent feature.
 660 .IP
 661 As an extension, this implementation can be configured to change the
 662 function prototypes to use the \fBconst\fP keyword.
 663 The ncurses ABI 6 enables this feature by default.
 664 .bP
 665 X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters,
 666 rather than a variable argument list.
 667 .IP
 668 This implementation uses a variable argument list, but can be
 669 configured to use the fixed-parameter list.
 670 Portable applications should provide 9 parameters after the format;
 671 zeroes are fine for this purpose.
 672 .IP
 673 In response to review comments by Thomas E. Dickey,
 674 X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
 675 .IP
 676 While \fBtiparm\fP is always provided in ncurses,
 677 the older form is only available as a build-time configuration option.
 678 If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP.
 679 .PP
 680 Both forms of \fBtparm\fP have drawbacks:
 681 .bP
 682 Most of the calls to \fBtparm\fP use only one or two parameters.
 683 Passing nine on each call is awkward.
 684 .IP
 685 Using \fBlong\fP for the numeric parameter type is a workaround
 686 to make the parameter use the same amount of stack as a pointer.
 687 That approach dates back to the mid-1980s, before C was standarized.
 688 Since then, there is a standard
 689 (and pointers are not required to fit in a long).
 690 .bP
 691 Providing the right number of parameters for a variadic function
 692 such as \fBtiparm\fP can be a problem, in particular for string parameters.
 693 However, only a few terminfo capabilities use string parameters
 694 (e.g., the ones used for programmable function keys).
 695 .IP
 696 The ncurses library checks usage of these capabilities,
 697 and returns an error if the capability mishandles string parameters.
 698 But it cannot check if a calling program provides strings in the right
 699 places for the \fBtparm\fP calls.
 700 .IP
 701 The \fBtput\fR(3X) program checks its use of these capabilities with a table,
 702 so that it calls \fBtparm\fP correctly.
 703 .SS Special TERM treatment
 704 .PP
 705 If configured to use the terminal-driver,
 706 e.g., for the MinGW port,
 707 .bP
 708 \fBsetupterm\fP interprets a missing/empty TERM variable as the
 709 special value \*(``unknown\*(''.
 710 .bP
 711 \fBsetupterm\fP allows explicit use of the
 712 the windows console driver by checking if $TERM is set to
 713 \*(``#win32con\*('' or an abbreviation of that string.
 714 .SS Other portability issues
 715 .PP
 716 In System V Release 4, \fBset_curterm\fP has an \fBint\fP return type and
 717 returns \fBOK\fP or \fBERR\fP.  We have chosen to implement the X/Open Curses
 718 semantics.
 719 .PP
 720 In System V Release 4, the third argument of \fBtputs\fP has the type
 721 \fBint (*putc)(char)\fP.
 722 .PP
 723 At least one implementation of X/Open Curses (Solaris) returns a value
 724 other than \fBOK\fP/\fBERR\fP from \fBtputs\fP.
 725 That returns the length of the string, and does no error-checking.
 726 .PP
 727 X/Open notes that after calling \fBmvcur\fP, the curses state may not match the
 728 actual terminal state, and that an application should touch and refresh
 729 the window before resuming normal curses calls.
 730 Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fP using
 731 the SCREEN data allocated in either \fBinitscr\fP or \fBnewterm\fP.
 732 So though it is documented as a terminfo function,
 733 \fBmvcur\fP is really a curses function which is not well specified.
 734 .PP
 735 X/Open states that the old location must be given for \fBmvcur\fP.
 736 This implementation allows the caller to use \-1's for the old ordinates.
 737 In that case, the old location is unknown.
 738 .SH SEE ALSO
 739 \fBcurses\fP(3X),
 740 \fBcurs_initscr\fP(3X),
 741 \fBcurs_kernel\fP(3X),
 742 \fBcurs_memleaks\fP(3X),
 743 \fBcurs_termcap\fP(3X),
 744 \fBcurs_variables\fP(3X),
 745 \fBterm_variables\fP(3X),
 746 \fBputc\fP(3),
 747 \fBterminfo\fP(\*n)