man/curs_terminfo.3x

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