| 1 |
'\" t |
| 2 |
.\"*************************************************************************** |
| 3 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 4 |
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| 5 |
.\" * |
| 6 |
.\" Permission is hereby granted, free of charge, to any person obtaining a * |
| 7 |
.\" copy of this software and associated documentation files (the * |
| 8 |
.\" "Software"), to deal in the Software without restriction, including * |
| 9 |
.\" without limitation the rights to use, copy, modify, merge, publish, * |
| 10 |
.\" distribute, distribute with modifications, sublicense, and/or sell * |
| 11 |
.\" copies of the Software, and to permit persons to whom the Software is * |
| 12 |
.\" furnished to do so, subject to the following conditions: * |
| 13 |
.\" * |
| 14 |
.\" The above copyright notice and this permission notice shall be included * |
| 15 |
.\" in all copies or substantial portions of the Software. * |
| 16 |
.\" * |
| 17 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 18 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 19 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 20 |
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 21 |
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 22 |
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 23 |
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 24 |
.\" * |
| 25 |
.\" Except as contained in this notice, the name(s) of the above copyright * |
| 26 |
.\" holders shall not be used in advertising or otherwise to promote the * |
| 27 |
.\" sale, use or other dealings in this Software without prior written * |
| 28 |
.\" authorization. * |
| 29 |
.\"*************************************************************************** |
| 30 |
.\" |
| 31 |
.\" $Id: curs_terminfo.3x,v 1.176 2025/11/12 01:06:36 tom Exp $ |
| 32 |
.TH terminfo 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls" |
| 33 |
.ie \n(.g \{\ |
| 34 |
.ds `` \(lq |
| 35 |
.ds '' \(rq |
| 36 |
.\} |
| 37 |
.el \{\ |
| 38 |
.ie t .ds `` `` |
| 39 |
.el .ds `` "" |
| 40 |
.ie t .ds '' '' |
| 41 |
.el .ds '' "" |
| 42 |
.\} |
| 43 |
. |
| 44 |
.de bP |
| 45 |
.ie n .IP \(bu 4 |
| 46 |
.el .IP \(bu 2 |
| 47 |
.. |
| 48 |
. |
| 49 |
.SH NAME |
| 50 |
\fB\%del_curterm\fP, |
| 51 |
\fB\%putp\fP, |
| 52 |
\fB\%restartterm\fP, |
| 53 |
\fB\%set_curterm\fP, |
| 54 |
\fB\%setupterm\fP, |
| 55 |
\fB\%tigetflag\fP, |
| 56 |
\fB\%tigetnum\fP, |
| 57 |
\fB\%tigetstr\fP, |
| 58 |
\fB\%tiparm\fP, |
| 59 |
\fB\%tiparm_s\fP, |
| 60 |
\fB\%tiscan_s\fP, |
| 61 |
\fB\%tparm\fP, |
| 62 |
\fB\%tputs\fP, |
| 63 |
\fB\%vid_attr\fP, |
| 64 |
\fB\%vid_puts\fP, |
| 65 |
\fB\%vidattr\fP, |
| 66 |
\fB\%vidputs\fP \- |
| 67 |
\fIcurses\fR interfaces to \fI\%term\%info\fR database |
| 68 |
.SH SYNOPSIS |
| 69 |
.nf |
| 70 |
\fB#include <curses.h> |
| 71 |
\fB#include <term.h> |
| 72 |
.PP |
| 73 |
\fBTERMINAL * cur_term; |
| 74 |
.PP |
| 75 |
\fBconst char * const boolnames[]; |
| 76 |
\fBconst char * const boolcodes[]; |
| 77 |
\fBconst char * const boolfnames[]; |
| 78 |
\fBconst char * const numnames[]; |
| 79 |
\fBconst char * const numcodes[]; |
| 80 |
\fBconst char * const numfnames[]; |
| 81 |
\fBconst char * const strnames[]; |
| 82 |
\fBconst char * const strcodes[]; |
| 83 |
\fBconst char * const strfnames[]; |
| 84 |
.PP |
| 85 |
\fBint setupterm(const char * \fIterm\fP, int \fIfiledes\fP, int * \fIerrret\fP); |
| 86 |
\fBTERMINAL * set_curterm(TERMINAL * \fInterm\fP); |
| 87 |
\fBint del_curterm(TERMINAL * \fIoterm\fP); |
| 88 |
\fBint restartterm(const char * \fIterm\fP, int \fIfiledes\fP, int * \fIerrret\fP); |
| 89 |
.PP |
| 90 |
\fBchar * tparm(const char * \fIstr\fP, \fR.\|.\|.\fP); |
| 91 |
\fI/* or */ |
| 92 |
\fBchar * tparm(const char * \fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP); |
| 93 |
.PP |
| 94 |
\fBint tputs(const char * \fIstr\fP, int \fIaffcnt\fP, int (* \fIputc\fP)(int)); |
| 95 |
\fBint putp(const char * \fIstr\fP); |
| 96 |
.PP |
| 97 |
\fBint vidputs(chtype \fIattrs\fP, int (* \fIputc\fP)(int)); |
| 98 |
\fBint vidattr(chtype \fIattrs\fP); |
| 99 |
\fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP, int (* \fIputc\fP)(int)); |
| 100 |
\fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void * \fIopts\fP); |
| 101 |
.PP |
| 102 |
\fBint tigetflag(const char * \fIcap-code\fP); |
| 103 |
\fBint tigetnum(const char * \fIcap-code\fP); |
| 104 |
\fBchar * tigetstr(const char * \fIcap-code\fP); |
| 105 |
.PP |
| 106 |
\fBchar * tiparm(const char * \fIstr\fP, \fR.\|.\|.\fP); |
| 107 |
.PP |
| 108 |
\fI/* extensions */ |
| 109 |
\fBchar * tiparm_s(int \fIexpected\fP, int \fImask\fP, const char * \fIstr\fP, .\|.\|.); |
| 110 |
\fBint tiscan_s(int * \fIexpected\fP, int * \fImask\fP, const char * \fIstr\fP); |
| 111 |
.PP |
| 112 |
\fI/* deprecated */ |
| 113 |
\fBint setterm(const char * \fIterm\fP); |
| 114 |
.fi |
| 115 |
.SH DESCRIPTION |
| 116 |
These lower-level functions of the |
| 117 |
.I curses |
| 118 |
standard must be called by programs that deal directly |
| 119 |
with the |
| 120 |
.I \%term\%info |
| 121 |
database to handle certain terminal capabilities, |
| 122 |
such as programming function keys. |
| 123 |
For all other functionality, |
| 124 |
.I curses |
| 125 |
functions are more suitable and their use is recommended. |
| 126 |
.PP |
| 127 |
None of these functions use |
| 128 |
(or are aware of) |
| 129 |
multibyte character strings such as UTF-8. |
| 130 |
.bP |
| 131 |
Capability names and codes use the POSIX portable character set. |
| 132 |
.bP |
| 133 |
Capability string values have no associated encoding; |
| 134 |
they are strings of 8-bit characters. |
| 135 |
.SS Initialization |
| 136 |
Call |
| 137 |
.B \%setupterm |
| 138 |
from your application to have |
| 139 |
.I \%term\%info |
| 140 |
manage the terminal device; |
| 141 |
this action initializes the terminal-dependent variables listed in |
| 142 |
\fB\%terminfo_variables\fP(3NCURSES). |
| 143 |
(A |
| 144 |
.I curses |
| 145 |
application calling \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES) achieves |
| 146 |
the same result.) |
| 147 |
Applications can use the terminal capabilities either directly, |
| 148 |
by object definitions corresponding to capability names and codes |
| 149 |
(see \fB\%terminfo_variables\fP(3NCURSES)) |
| 150 |
or by calling the functions documented here. |
| 151 |
.B \%setupterm |
| 152 |
initializes the |
| 153 |
.I \%term\%info |
| 154 |
variables |
| 155 |
.B \%lines |
| 156 |
and |
| 157 |
.B \%columns |
| 158 |
as described in \fB\%use_env\fP(3NCURSES). |
| 159 |
.PP |
| 160 |
Pass parameterized string capability values through |
| 161 |
.B \%tparm |
| 162 |
to instantiate them. |
| 163 |
All |
| 164 |
.I \%term\%info |
| 165 |
strings |
| 166 |
(including the output of |
| 167 |
.BR \%tparm ")" |
| 168 |
should be sent to the terminal device with |
| 169 |
.B \%tputs |
| 170 |
or |
| 171 |
.BR \%putp "." |
| 172 |
Call |
| 173 |
\fB\%reset_shell_mode\fP(3NCURSES) to restore the terminal modes before |
| 174 |
exiting. |
| 175 |
(A |
| 176 |
.I curses |
| 177 |
application calling \fB\%endwin\fP(3NCURSES) achieves the same result.) |
| 178 |
.\" XXX: What should a "pure" terminfo application that wants to link |
| 179 |
.\" only with libtinfo, and not libcurses, do? |
| 180 |
.PP |
| 181 |
Programs that use cursor addressing should emit certain capabilities |
| 182 |
at specific times. |
| 183 |
Specifically, |
| 184 |
output |
| 185 |
.bP |
| 186 |
.B \%enter_ca_mode |
| 187 |
upon startup, |
| 188 |
and |
| 189 |
.bP |
| 190 |
.B \%exit_ca_mode |
| 191 |
before exiting. |
| 192 |
.PP |
| 193 |
Programs that execute shell subprocesses should |
| 194 |
.bP |
| 195 |
call \fB\%reset_shell_mode\fP(3NCURSES) and output |
| 196 |
.B \%exit_ca_mode |
| 197 |
before the shell is called, |
| 198 |
and |
| 199 |
.bP |
| 200 |
output |
| 201 |
.B \%enter_ca_mode |
| 202 |
and call \fB\%reset_prog_mode\fP(3NCURSES) after returning from the shell. |
| 203 |
.\" XXX: What should a "pure" terminfo application that wants to link |
| 204 |
.\" only with libtinfo, and not libcurses, do? |
| 205 |
.PP |
| 206 |
\fB\%setupterm\fP reads in the |
| 207 |
.I \%term\%info |
| 208 |
database, |
| 209 |
initializing the |
| 210 |
.I \%term\%info |
| 211 |
structures, |
| 212 |
but does not set up the output virtualization structures used by |
| 213 |
.IR curses "." |
| 214 |
Its parameters follow. |
| 215 |
.RS 3 |
| 216 |
.TP 5 |
| 217 |
.I term |
| 218 |
is the terminal type, |
| 219 |
a character string. |
| 220 |
If |
| 221 |
.I term |
| 222 |
is null, |
| 223 |
the environment variable |
| 224 |
.I TERM |
| 225 |
is read. |
| 226 |
.TP 5 |
| 227 |
.I filedes |
| 228 |
is the file descriptor used for getting and setting terminal I/O modes. |
| 229 |
.IP |
| 230 |
Higher-level applications use \fB\%newterm\fP(3NCURSES) to initialize the |
| 231 |
terminal, |
| 232 |
passing an output |
| 233 |
.I stream |
| 234 |
rather than a |
| 235 |
.IR descriptor "." |
| 236 |
In |
| 237 |
.IR curses "," |
| 238 |
the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP, |
| 239 |
passing the file descriptor derived from its output stream parameter. |
| 240 |
.TP 5 |
| 241 |
.I errret |
| 242 |
points to an optional location where an error status can be returned to |
| 243 |
the caller. |
| 244 |
If |
| 245 |
.I errret |
| 246 |
is not null, |
| 247 |
then |
| 248 |
.B \%setupterm |
| 249 |
returns |
| 250 |
.B OK |
| 251 |
or |
| 252 |
.B ERR |
| 253 |
and stores a status value in the integer pointed to by |
| 254 |
.IR errret "." |
| 255 |
A return value of |
| 256 |
.B OK |
| 257 |
combined with status of |
| 258 |
.B 1 |
| 259 |
in |
| 260 |
.I errret |
| 261 |
is normal. |
| 262 |
.IP |
| 263 |
If |
| 264 |
.B ERR |
| 265 |
is returned, |
| 266 |
examine |
| 267 |
.IR errret "." |
| 268 |
.RS |
| 269 |
.TP 5 |
| 270 |
.B 1 |
| 271 |
means that the terminal is a hard-copy type |
| 272 |
(lacks destructive backspace), |
| 273 |
and cannot be used for |
| 274 |
.I curses |
| 275 |
applications. |
| 276 |
The library determines this fact by checking the terminal type's |
| 277 |
.B \%hardcopy |
| 278 |
.RB ( hc ) |
| 279 |
capability. |
| 280 |
.TP 5 |
| 281 |
.B 0 |
| 282 |
means that the terminal could not be found, |
| 283 |
or that it is a generic type, |
| 284 |
having too little information for |
| 285 |
.I curses |
| 286 |
applications to run. |
| 287 |
.IP |
| 288 |
.B \%setupterm |
| 289 |
determines if the entry is a generic type by checking the |
| 290 |
.B \%generic_type |
| 291 |
.RB ( gn ) |
| 292 |
capability. |
| 293 |
.TP 5 |
| 294 |
.B \-1 |
| 295 |
means that the |
| 296 |
.I \%term\%info |
| 297 |
database could not be found. |
| 298 |
.RE |
| 299 |
.IP |
| 300 |
If |
| 301 |
.I errret |
| 302 |
is null, |
| 303 |
.B \%setupterm |
| 304 |
reports an error message upon finding an error and exits. |
| 305 |
Thus, |
| 306 |
the simplest call is: |
| 307 |
.RS |
| 308 |
.IP |
| 309 |
.EX |
| 310 |
setupterm((char *) NULL, 1, (int *) NULL); |
| 311 |
.EE |
| 312 |
.RE |
| 313 |
.IP |
| 314 |
which uses all the defaults and sends the output to |
| 315 |
.IR stdout "." |
| 316 |
.RE |
| 317 |
.\" ******************************************************************** |
| 318 |
.SS "The Terminal State" |
| 319 |
.B \%setupterm |
| 320 |
stores its information about the terminal in a |
| 321 |
.I \%TERMINAL |
| 322 |
structure pointed to by the global variable |
| 323 |
.BR \%cur_term "." |
| 324 |
If it detects an error, |
| 325 |
or decides that the terminal is unsuitable |
| 326 |
(hardcopy or generic), |
| 327 |
it discards this information, |
| 328 |
making it unavailable to applications. |
| 329 |
.PP |
| 330 |
If |
| 331 |
.B \%setupterm |
| 332 |
is called repeatedly for the same terminal type, |
| 333 |
it reuses the information. |
| 334 |
It maintains only one copy of a given type's capabilities in memory. |
| 335 |
If called for different types, |
| 336 |
.B \%setupterm |
| 337 |
allocates new storage for each set of terminal capabilities. |
| 338 |
.PP |
| 339 |
.B \%set_curterm |
| 340 |
sets |
| 341 |
.B \%cur_term |
| 342 |
to |
| 343 |
.IR \%nterm "," |
| 344 |
making all of the |
| 345 |
.I \%term\%info |
| 346 |
Boolean, |
| 347 |
numeric, |
| 348 |
and string capabilities use the values from |
| 349 |
.IR \%nterm "." |
| 350 |
It returns the old value of |
| 351 |
.BR \%cur_term "." |
| 352 |
.PP |
| 353 |
.B \%del_curterm |
| 354 |
releases the memory pointed to by |
| 355 |
.IR \%oterm "." |
| 356 |
If |
| 357 |
.I \%oterm |
| 358 |
is |
| 359 |
the same as |
| 360 |
.BR \%cur_term "," |
| 361 |
references to any of the |
| 362 |
.I \%term\%info |
| 363 |
Boolean, |
| 364 |
numeric, |
| 365 |
and string capabilities thereafter may refer to invalid memory locations |
| 366 |
until |
| 367 |
.B \%setupterm |
| 368 |
is called again. |
| 369 |
.PP |
| 370 |
.B \%restartterm |
| 371 |
is similar to |
| 372 |
.BR \%setupterm "," |
| 373 |
but is intended for use after restoring program memory |
| 374 |
to a previous state |
| 375 |
(for example, |
| 376 |
when reloading an application that has been suspended from one terminal |
| 377 |
session and restored in another). |
| 378 |
.B \%restartterm |
| 379 |
assumes that the display dimensions |
| 380 |
and the input and output options are the same as when memory was saved, |
| 381 |
but the terminal type and line speed may differ. |
| 382 |
Accordingly, |
| 383 |
.B \%restartterm |
| 384 |
saves relevant terminal state, |
| 385 |
calls |
| 386 |
.BR \%setupterm "," |
| 387 |
then restores that state. |
| 388 |
.\" ******************************************************************** |
| 389 |
.SS "Formatting Output" |
| 390 |
\fB\%tparm\fP instantiates the string |
| 391 |
.I str |
| 392 |
with parameters |
| 393 |
.IR pi "." |
| 394 |
It returns a pointer to a character string representing |
| 395 |
.I str |
| 396 |
with the parameters applied to \*(``%\*('' expressions within. |
| 397 |
.\" XXX: Whose responsibility is it to free that string? |
| 398 |
Application developers should keep in mind some quirks of the interface. |
| 399 |
.bP |
| 400 |
Although \fB\%tparm\fP's actual parameters may be integers or strings, |
| 401 |
the prototype expects |
| 402 |
.I long |
| 403 |
(integer) values. |
| 404 |
.bP |
| 405 |
Aside from the |
| 406 |
.B \%set_attributes\fP |
| 407 |
.RB ( sgr ) |
| 408 |
capability, |
| 409 |
most terminal capabilities require no more than one or two parameters. |
| 410 |
.bP |
| 411 |
Padding information is ignored by \fB\%tparm\fP; |
| 412 |
it is interpreted by \fB\%tputs\fP. |
| 413 |
.bP |
| 414 |
The capability string is null-terminated. |
| 415 |
Use \*(``\e200\*('' where an ASCII NUL is needed in the output. |
| 416 |
.PP |
| 417 |
\fB\%tiparm\fP is a newer form of \fB\%tparm\fP that uses |
| 418 |
.I \%stdarg.h |
| 419 |
rather than a fixed-length parameter list. |
| 420 |
Its numeric parameters are |
| 421 |
.IR int s |
| 422 |
rather than |
| 423 |
.IR long "s." |
| 424 |
.PP |
| 425 |
.B \%tparm |
| 426 |
and |
| 427 |
.B \%tiparm |
| 428 |
assume that the application |
| 429 |
passes parameters consistent with the terminal description. |
| 430 |
.I \%ncurses |
| 431 |
provides two extensions as alternatives to deal with untrusted data. |
| 432 |
.bP |
| 433 |
The |
| 434 |
.B \%tiparm_s |
| 435 |
extension is a safer formatting function than |
| 436 |
.B \%tparm |
| 437 |
or |
| 438 |
.BR \%tiparm "," |
| 439 |
because it allows the developer to tell the |
| 440 |
.I curses |
| 441 |
library how many parameters to expect in the parameter list, |
| 442 |
and which may be string parameters. |
| 443 |
.IP |
| 444 |
The |
| 445 |
.I mask |
| 446 |
parameter has one bit set for each of the parameters |
| 447 |
(up to 9) |
| 448 |
passed as |
| 449 |
.I char |
| 450 |
pointers rather than numbers. |
| 451 |
.bP |
| 452 |
The extension |
| 453 |
.B \%tiscan_s |
| 454 |
allows the application |
| 455 |
to inspect a formatting capability to see what the |
| 456 |
.I curses |
| 457 |
library would assume. |
| 458 |
.\" ******************************************************************** |
| 459 |
.SS "Output Functions" |
| 460 |
String capabilities can contain |
| 461 |
.IR padding "," |
| 462 |
a time delay |
| 463 |
(accommodating performance limitations of hardware terminals) |
| 464 |
expressed as |
| 465 |
.BI $< n >\c |
| 466 |
, |
| 467 |
where |
| 468 |
.I n |
| 469 |
is a nonnegative integral count of milliseconds. |
| 470 |
If |
| 471 |
.I n |
| 472 |
exceeds 30,000 |
| 473 |
(thirty seconds), |
| 474 |
.I \%ncurses |
| 475 |
caps it at that value. |
| 476 |
.PP |
| 477 |
.B \%tputs |
| 478 |
interprets time delays in the string |
| 479 |
.I str |
| 480 |
and acts upon them. |
| 481 |
.bP |
| 482 |
The |
| 483 |
.I str |
| 484 |
parameter must be a |
| 485 |
.I \%term\%info |
| 486 |
string capability or the return value of |
| 487 |
.B \%tparm |
| 488 |
or |
| 489 |
.BR \%tiparm "." |
| 490 |
.bP |
| 491 |
.I affcnt |
| 492 |
is the number of lines affected, |
| 493 |
or |
| 494 |
.B 1 |
| 495 |
if not applicable. |
| 496 |
.bP |
| 497 |
.I putc |
| 498 |
is a |
| 499 |
.IR \%putchar -like |
| 500 |
function to which the characters are passed, |
| 501 |
one at a time. |
| 502 |
.PP |
| 503 |
.B \%tputs |
| 504 |
processes each time delay with the \fB\%delay_output\fP(3NCURSES) function, |
| 505 |
routing any resulting padding characters through this function. |
| 506 |
.PP |
| 507 |
\fB\%putp\fR calls |
| 508 |
.RB \%\*(`` tputs(\c |
| 509 |
.IB str ", 1, putchar)\c" |
| 510 |
\*(''. |
| 511 |
The output of \fB\%putp\fP always goes to |
| 512 |
.IR stdout "," |
| 513 |
rather than the |
| 514 |
.I \%file\%des |
| 515 |
specified in \fB\%setupterm\fP. |
| 516 |
.PP |
| 517 |
\fB\%vidputs\fP displays the string on the terminal in the video |
| 518 |
attribute mode |
| 519 |
.IR attrs "," |
| 520 |
which is any combination of the attributes listed in \fB\%ncurses\fP(3NCURSES). |
| 521 |
The characters are passed to the |
| 522 |
.IR \%putchar -like |
| 523 |
function |
| 524 |
.IR putc "." |
| 525 |
.PP |
| 526 |
\fB\%vidattr\fP is like \fB\%vidputs\fP, |
| 527 |
except that it outputs through \fI\%putchar\fP(3). |
| 528 |
.PP |
| 529 |
.B \%vid_attr |
| 530 |
and |
| 531 |
.B \%vid_puts |
| 532 |
correspond to |
| 533 |
.B \%vidattr |
| 534 |
and |
| 535 |
.BR \%vidputs "," |
| 536 |
respectively. |
| 537 |
They use multiple parameters to represent the character attributes and |
| 538 |
color; |
| 539 |
namely, |
| 540 |
.bP |
| 541 |
.IR \%attrs "," |
| 542 |
of type |
| 543 |
.IR \%attr_t "," |
| 544 |
for the attributes and |
| 545 |
.bP |
| 546 |
.IR pair "," |
| 547 |
of type |
| 548 |
.IR short "," |
| 549 |
for the color pair number. |
| 550 |
.PP |
| 551 |
Use the attribute constants prefixed with |
| 552 |
.RB \*(`` WA_ \*('' |
| 553 |
with |
| 554 |
.B \%vid_attr |
| 555 |
and |
| 556 |
.BR \%vid_puts "." |
| 557 |
.PP |
| 558 |
X/Open Curses reserves the |
| 559 |
.I opts |
| 560 |
argument for future use, |
| 561 |
saying that applications must provide a null pointer for that argument; |
| 562 |
but see section \*(``EXTENSIONS\*('' below. |
| 563 |
.PP |
| 564 |
While |
| 565 |
.B \%putp |
| 566 |
is a lower-level function |
| 567 |
that does not use higher-level |
| 568 |
.I curses |
| 569 |
state, |
| 570 |
.I \%ncurses |
| 571 |
declares it in |
| 572 |
.I \%curses.h |
| 573 |
because System\ V did so |
| 574 |
(see section \*(``HISTORY\*('' below). |
| 575 |
.\" ******************************************************************** |
| 576 |
.SS "Terminal Capability Functions" |
| 577 |
.BR \%tigetflag "," |
| 578 |
.BR \%tigetnum "," |
| 579 |
and |
| 580 |
.B \%tigetstr |
| 581 |
return the value of the capability corresponding to |
| 582 |
the |
| 583 |
.I \%term\%info |
| 584 |
.IR cap-code "," |
| 585 |
such as |
| 586 |
.BR xenl "," |
| 587 |
passed to them. |
| 588 |
The |
| 589 |
.I cap-code |
| 590 |
for each capability is given in the table column of that name |
| 591 |
in the \*(``Capabilities\*('' section of \fB\%terminfo\fP(5). |
| 592 |
.PP |
| 593 |
These functions return special values to denote errors. |
| 594 |
.PP |
| 595 |
.B \%tigetflag |
| 596 |
returns |
| 597 |
.TP |
| 598 |
.B \-1 |
| 599 |
if |
| 600 |
.I cap-code |
| 601 |
is not a Boolean capability, |
| 602 |
or |
| 603 |
.TP |
| 604 |
.B 0 |
| 605 |
if it is canceled or absent from the terminal description. |
| 606 |
.PP |
| 607 |
.B \%tigetnum |
| 608 |
returns |
| 609 |
.TP |
| 610 |
.B \-2 |
| 611 |
if |
| 612 |
.I cap-code |
| 613 |
is not a numeric capability, |
| 614 |
or |
| 615 |
.TP |
| 616 |
.B \-1 |
| 617 |
if it is canceled or absent from the terminal description. |
| 618 |
.PP |
| 619 |
.B \%tigetstr |
| 620 |
returns |
| 621 |
.TP |
| 622 |
.B "(char *)\-1" |
| 623 |
if |
| 624 |
.I cap-code |
| 625 |
is not a string capability, |
| 626 |
or |
| 627 |
.TP |
| 628 |
.B NULL |
| 629 |
if it is canceled or absent from the terminal description. |
| 630 |
.\" ******************************************************************** |
| 631 |
.SS "Terminal Capability Names" |
| 632 |
These null-terminated arrays contain |
| 633 |
.bP |
| 634 |
the short \fI\%term\%info\fP names (\*(``codes\*(''), |
| 635 |
.bP |
| 636 |
the \fItermcap\fP names (\*(``names\*(''), |
| 637 |
and |
| 638 |
.bP |
| 639 |
the long \fI\%term\%info\fP names (\*(``fnames\*('') |
| 640 |
.PP |
| 641 |
for each standard |
| 642 |
.I \%term\%info |
| 643 |
capability name. |
| 644 |
.PP |
| 645 |
.RS |
| 646 |
.nf |
| 647 |
\fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP |
| 648 |
\fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP |
| 649 |
\fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP |
| 650 |
.fi |
| 651 |
.RE |
| 652 |
.\" ******************************************************************** |
| 653 |
.SS "Releasing Memory" |
| 654 |
Each successful call to \fB\%setupterm\fP allocates memory to hold the |
| 655 |
terminal description. |
| 656 |
As a side effect, |
| 657 |
it sets \fB\%cur_term\fP to point to this memory. |
| 658 |
If an application calls |
| 659 |
.RS |
| 660 |
.EX |
| 661 |
del_curterm(cur_term); |
| 662 |
.EE |
| 663 |
.RE |
| 664 |
the memory will be freed. |
| 665 |
.PP |
| 666 |
The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the |
| 667 |
storage allocated by \fB\%setupterm\fP as follows. |
| 668 |
.bP |
| 669 |
They add the \*(``static\*('' |
| 670 |
.I \%term\%info |
| 671 |
variables [a-z]. |
| 672 |
Before |
| 673 |
.I \%ncurses |
| 674 |
6.3, |
| 675 |
those were shared by all screens. |
| 676 |
With |
| 677 |
.I \%ncurses |
| 678 |
6.3, |
| 679 |
those are allocated per screen. |
| 680 |
See \fB\%terminfo\fP(5). |
| 681 |
.bP |
| 682 |
To improve performance, |
| 683 |
.I \%ncurses |
| 684 |
6.3 caches the result of analyzing |
| 685 |
.I \%term\%info |
| 686 |
strings for their parameter types. |
| 687 |
That is stored as a binary tree referenced from the |
| 688 |
.I \%TERMINAL |
| 689 |
structure. |
| 690 |
.PP |
| 691 |
The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use |
| 692 |
\fB\%setupterm\fP. |
| 693 |
Normally they do not free this memory, |
| 694 |
but it is possible to do that using the \fB\%delscreen\fP(3NCURSES) function. |
| 695 |
.\" ******************************************************************** |
| 696 |
.SH RETURN VALUE |
| 697 |
Functions that return integers return |
| 698 |
.B ERR |
| 699 |
upon failure and |
| 700 |
.B OK |
| 701 |
upon success. |
| 702 |
.PP |
| 703 |
In |
| 704 |
.IR \%ncurses "," |
| 705 |
.TP 5 |
| 706 |
.B del_curterm |
| 707 |
fails if its terminal parameter is null. |
| 708 |
.TP 5 |
| 709 |
.B putp |
| 710 |
calls \fB\%tputs\fP, |
| 711 |
returning the same error codes. |
| 712 |
.TP 5 |
| 713 |
.B restartterm |
| 714 |
fails if the associated call to \fB\%setupterm\fP returns |
| 715 |
.BR ERR "." |
| 716 |
.TP 5 |
| 717 |
.B setupterm |
| 718 |
fails if it cannot allocate enough memory, |
| 719 |
or create the initial windows |
| 720 |
.RB \%( stdscr , |
| 721 |
.BR \%curscr "," |
| 722 |
and |
| 723 |
.BR \%newscr ")." |
| 724 |
Other error conditions are documented above. |
| 725 |
.TP 5 |
| 726 |
.B tparm |
| 727 |
returns a null pointer if the capability would require unexpected |
| 728 |
parameters; |
| 729 |
that is, |
| 730 |
too many, |
| 731 |
too few, |
| 732 |
or incorrect types |
| 733 |
(strings where integers are expected, |
| 734 |
or vice versa). |
| 735 |
.TP 5 |
| 736 |
.B tputs |
| 737 |
fails if the string parameter is null. |
| 738 |
It does not detect I/O errors: |
| 739 |
X/Open Curses states that \fB\%tputs\fP ignores the return value |
| 740 |
of the output function \fI\%putc\fP. |
| 741 |
.\" ******************************************************************** |
| 742 |
.SH NOTES |
| 743 |
The |
| 744 |
.B \%vid_attr |
| 745 |
function in |
| 746 |
.I \%ncurses |
| 747 |
is a special case. |
| 748 |
It was originally implemented based on a draft of X/Open Curses, |
| 749 |
as a macro, |
| 750 |
before other parts of the |
| 751 |
.I \%ncurses |
| 752 |
wide-character API were developed, |
| 753 |
and unlike the other wide-character functions, |
| 754 |
is also provided in the non-wide-character configuration. |
| 755 |
.\" ******************************************************************** |
| 756 |
.SH EXTENSIONS |
| 757 |
The functions marked as extensions originated in |
| 758 |
.IR \%ncurses "," |
| 759 |
and are not found in SVr4 |
| 760 |
.IR curses "," |
| 761 |
4.4BSD |
| 762 |
.IR curses "," |
| 763 |
or any other previous |
| 764 |
.I curses |
| 765 |
implementation. |
| 766 |
.PP |
| 767 |
.I \%ncurses |
| 768 |
allows |
| 769 |
.I opts |
| 770 |
to be a pointer to |
| 771 |
.IR int "," |
| 772 |
which overrides the |
| 773 |
.I pair |
| 774 |
.RI ( short ) |
| 775 |
argument. |
| 776 |
.\" ******************************************************************** |
| 777 |
.SH PORTABILITY |
| 778 |
Except for |
| 779 |
.IR \%setterm "," |
| 780 |
X/Open Curses Issue\ 4 describes these functions. |
| 781 |
It specifies no error conditions for them. |
| 782 |
.PP |
| 783 |
SVr4 describes a successful return value |
| 784 |
except where \*(``otherwise noted\*('' |
| 785 |
as |
| 786 |
\*(``an integer value other than |
| 787 |
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 539 |
| 788 |
.SS "Header Files" |
| 789 |
On legacy |
| 790 |
.I curses |
| 791 |
systems, |
| 792 |
include |
| 793 |
.I \%curses.h |
| 794 |
and |
| 795 |
.I \%term.h |
| 796 |
in that order |
| 797 |
to make visible the definitions of the string arrays |
| 798 |
storing the capability names and codes. |
| 799 |
.SS "Compatibility Macros" |
| 800 |
.I \%ncurses |
| 801 |
implements a few macros for early System\ V |
| 802 |
.I curses |
| 803 |
compatibility |
| 804 |
(see section \*(``HISTORY\*('' below). |
| 805 |
They include |
| 806 |
.IR \%crmode "," |
| 807 |
.IR \%fixterm "," |
| 808 |
.IR \%gettmode "," |
| 809 |
.IR \%nocrmode "," |
| 810 |
.IR \%resetterm "," |
| 811 |
.IR \%saveterm "," |
| 812 |
and |
| 813 |
.IR \%setterm "." |
| 814 |
.PP |
| 815 |
In SVr4, |
| 816 |
these are found in |
| 817 |
.IR \%curses.h "," |
| 818 |
but except for |
| 819 |
.IR \%setterm "," |
| 820 |
are likewise macros. |
| 821 |
The one function, |
| 822 |
.IR \%setterm "," |
| 823 |
is mentioned in the manual page. |
| 824 |
It further notes that |
| 825 |
.I \%setterm |
| 826 |
was replaced by |
| 827 |
.IR \%setupterm "," |
| 828 |
stating that the call |
| 829 |
.RS |
| 830 |
.EX |
| 831 |
.RI setupterm( term ", 1, (int *)0)" |
| 832 |
.EE |
| 833 |
.RE |
| 834 |
provides the same functionality as |
| 835 |
.RS |
| 836 |
.EX |
| 837 |
.RI setterm( term ) |
| 838 |
.EE |
| 839 |
.RE |
| 840 |
and discouraging the latter for new programs. |
| 841 |
.SS "Legacy Data" |
| 842 |
.I \%setupterm |
| 843 |
copies the terminal name to the array |
| 844 |
.IR \%ttytype "." |
| 845 |
This behavior is not specified by X/Open Curses, |
| 846 |
but is assumed by some applications. |
| 847 |
.PP |
| 848 |
Other implementations may not declare the capability name arrays. |
| 849 |
Some provide them without declaring them. |
| 850 |
X/Open Curses does not specify them. |
| 851 |
.PP |
| 852 |
Extended terminal capability names, |
| 853 |
as defined by |
| 854 |
.RB \%\*(`` "tic \-x" \*('', |
| 855 |
are not stored in the arrays described here. |
| 856 |
.SS "Output Buffering" |
| 857 |
Older versions of |
| 858 |
.I \%ncurses |
| 859 |
assumed that the file descriptor passed to |
| 860 |
.I \%setupterm |
| 861 |
from |
| 862 |
.I \%initscr |
| 863 |
or |
| 864 |
.I \%newterm |
| 865 |
used buffered I/O, |
| 866 |
and wrote to the corresponding |
| 867 |
.I stdio |
| 868 |
stream. |
| 869 |
In addition to the limitation that the terminal was left in |
| 870 |
block-buffered mode on exit |
| 871 |
(like System\ V |
| 872 |
.IR curses ")," |
| 873 |
it was problematic because |
| 874 |
.I \%ncurses |
| 875 |
did not allow a reliable way to clean up on receiving |
| 876 |
.IR SIGTSTP "." |
| 877 |
.PP |
| 878 |
.I \%ncurses |
| 879 |
.RI 6. x |
| 880 |
uses output buffers managed directly by |
| 881 |
.IR \%ncurses "." |
| 882 |
The lower-level functions described here |
| 883 |
that write to the terminal device |
| 884 |
do so via the standard output stream; |
| 885 |
they thus are not signal-safe. |
| 886 |
The higher-level functions in |
| 887 |
.I \%ncurses |
| 888 |
employ alternate versions of these functions |
| 889 |
using a more reliable buffering scheme. |
| 890 |
.SS "Function Prototypes" |
| 891 |
The X/Open Curses prototypes are based on the SVr4 |
| 892 |
.I curses |
| 893 |
header declarations, |
| 894 |
which were defined at the same time the C language was first |
| 895 |
standardized in the late 1980s. |
| 896 |
.bP |
| 897 |
X/Open Curses uses |
| 898 |
.I \%const |
| 899 |
less effectively than a later design might, |
| 900 |
sometimes applying it needlessly to function parameters |
| 901 |
that are passed by value |
| 902 |
(and therefore copied), |
| 903 |
and in most cases overlooking parameters |
| 904 |
that normally would benefit from |
| 905 |
.IR \%const "." |
| 906 |
Passing |
| 907 |
.IR \%const -qualified |
| 908 |
parameters to functions that do not declare them |
| 909 |
.I \%const |
| 910 |
may prevent the program from compiling. |
| 911 |
On the other hand, |
| 912 |
\*(``writable strings\*('' are an obsolescent C language feature. |
| 913 |
.IP |
| 914 |
As an extension, |
| 915 |
.I \%ncurses |
| 916 |
can be configured to change the function prototypes |
| 917 |
to use the |
| 918 |
.I \%const |
| 919 |
keyword. |
| 920 |
The |
| 921 |
.I \%ncurses |
| 922 |
ABI 6 enables this feature by default. |
| 923 |
.bP |
| 924 |
X/Open Curses prototypes |
| 925 |
.I \%tparm |
| 926 |
with a fixed number of parameters, |
| 927 |
rather than a variable argument list. |
| 928 |
.IP |
| 929 |
.I \%ncurses |
| 930 |
uses a variable argument list, |
| 931 |
but can be configured to use the fixed-parameter list. |
| 932 |
Portable applications should provide nine parameters after the format; |
| 933 |
zeroes are fine for this purpose. |
| 934 |
.IP |
| 935 |
In response to review comments by Thomas E. Dickey, |
| 936 |
X/Open Curses Issue\ 7 proposed the |
| 937 |
.I \%tiparm |
| 938 |
function in mid-2009. |
| 939 |
.IP |
| 940 |
While |
| 941 |
.I \%tiparm |
| 942 |
is always provided in |
| 943 |
.IR \%ncurses "," |
| 944 |
the older form is available only as a build-time configuration option. |
| 945 |
If not specially configured, |
| 946 |
.I \%tparm |
| 947 |
is the same as |
| 948 |
.IR \%tiparm "." |
| 949 |
.PP |
| 950 |
Both forms of |
| 951 |
.I \%tparm |
| 952 |
have drawbacks. |
| 953 |
.bP |
| 954 |
Most calls to |
| 955 |
.I \%tparm |
| 956 |
require only one or two parameters. |
| 957 |
Passing nine on each call is awkward. |
| 958 |
.IP |
| 959 |
Using |
| 960 |
.I long |
| 961 |
for the numeric parameter type is a workaround to make the parameter use |
| 962 |
the same amount of stack memory as a pointer. |
| 963 |
That approach dates to the mid-1980s, |
| 964 |
before C was standardized. |
| 965 |
Since ANSI\ C (1989), |
| 966 |
C language standards do not require a pointer to fit in a |
| 967 |
.IR long ")." |
| 968 |
.bP |
| 969 |
Providing the right number of parameters for a variadic function |
| 970 |
such as |
| 971 |
.I \%tiparm |
| 972 |
can be a problem, |
| 973 |
in particular for string parameters. |
| 974 |
However, |
| 975 |
only a few |
| 976 |
.I \%term\%info |
| 977 |
capabilities use string parameters |
| 978 |
(for instance, |
| 979 |
the ones used for programmable function keys). |
| 980 |
.IP |
| 981 |
The |
| 982 |
.I \%ncurses |
| 983 |
library checks usage of these capabilities, |
| 984 |
and returns |
| 985 |
.I ERR |
| 986 |
if the capability mishandles string parameters. |
| 987 |
But it cannot check if a calling program provides strings in the right |
| 988 |
places for the |
| 989 |
.I \%tparm |
| 990 |
calls. |
| 991 |
.IP |
| 992 |
.IR \%ncurses 's |
| 993 |
\fB\%tput\fR(1) checks its use of these capabilities with a table, |
| 994 |
so that it calls |
| 995 |
.I \%tparm |
| 996 |
correctly. |
| 997 |
.SS "Special \fITERM\fP treatment" |
| 998 |
If |
| 999 |
.I \%ncurses |
| 1000 |
is configured to use a terminal driver |
| 1001 |
that does not employ the POSIX |
| 1002 |
.I \%termios |
| 1003 |
API, |
| 1004 |
as with the MinGW port, |
| 1005 |
.bP |
| 1006 |
.I \%setupterm |
| 1007 |
interprets a missing or empty |
| 1008 |
.I TERM |
| 1009 |
variable as the special value \*(``unknown\*(''. |
| 1010 |
.IP |
| 1011 |
SVr4 |
| 1012 |
.I curses |
| 1013 |
uses the special value \*(``dumb\*(''. |
| 1014 |
.IP |
| 1015 |
The difference between the two is that the former uses the |
| 1016 |
.B \%generic_type |
| 1017 |
.RB ( gn ) |
| 1018 |
.I \%term\%info |
| 1019 |
capability, |
| 1020 |
while the latter does not. |
| 1021 |
A generic terminal is unsuitable for full-screen applications. |
| 1022 |
.bP |
| 1023 |
.I \%setupterm |
| 1024 |
allows explicit use of the Microsoft Windows console driver by checking |
| 1025 |
whether the |
| 1026 |
.I TERM |
| 1027 |
environment variable has the value \*(``#win32con\*('' |
| 1028 |
or an abbreviation of that string. |
| 1029 |
.SS "Other Portability Issues" |
| 1030 |
In SVr4, |
| 1031 |
.I \%set_curterm |
| 1032 |
returns an |
| 1033 |
.IR int "," |
| 1034 |
.I OK |
| 1035 |
or |
| 1036 |
.IR ERR "." |
| 1037 |
We have chosen to implement the X/Open Curses semantics. |
| 1038 |
.PP |
| 1039 |
In SVr4, |
| 1040 |
the third argument of |
| 1041 |
.I \%tputs |
| 1042 |
has the type |
| 1043 |
.RB \*(`` "int (*)(char)" \*(''. |
| 1044 |
.PP |
| 1045 |
At least one implementation of X/Open Curses |
| 1046 |
(Solaris |
| 1047 |
.IR \%xcurses ")" |
| 1048 |
returns a value other than |
| 1049 |
.I OK |
| 1050 |
or |
| 1051 |
.I ERR |
| 1052 |
from |
| 1053 |
.IR \%tputs "." |
| 1054 |
It instead returns the length of the string, |
| 1055 |
and does no error checking. |
| 1056 |
.PP |
| 1057 |
Very old versions of AIX |
| 1058 |
.\" Can we be more specific? Like, AIX 4.3.3 and earlier? --GBR |
| 1059 |
.I curses |
| 1060 |
required inclusion of |
| 1061 |
.I \%curses.h |
| 1062 |
before |
| 1063 |
.IR \%term.h . |
| 1064 |
.\" ******************************************************************** |
| 1065 |
.SH HISTORY |
| 1066 |
SVr2 (1984) introduced the |
| 1067 |
.I \%term\%info |
| 1068 |
feature. |
| 1069 |
Its programming manual mentioned the following low-level functions. |
| 1070 |
.PP |
| 1071 |
.TS |
| 1072 |
Lb Lb |
| 1073 |
Li Lw(47n)x. |
| 1074 |
Function Description |
| 1075 |
_ |
| 1076 |
fixterm restore terminal to \*(``in \fIcurses\fP\*('' state |
| 1077 |
gettmode establish current terminal modes |
| 1078 |
mvcur low level cursor motion |
| 1079 |
putp use \fItputs\fP to send characters via \fIputchar\fP |
| 1080 |
resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\ |
| 1081 |
state |
| 1082 |
resetty reset terminal flags to stored value |
| 1083 |
saveterm save current modes as \*(``in \fIcurses\fP\*('' state |
| 1084 |
savetty store current terminal flags |
| 1085 |
setterm establish terminal with given type |
| 1086 |
setupterm establish terminal with given type |
| 1087 |
tparm interpolate parameters into string capability |
| 1088 |
tputs apply padding information to a string |
| 1089 |
vidattr like \fIvidputs\fP, but output through \fIputchar\fP |
| 1090 |
vidputs T{ |
| 1091 |
write string to terminal, applying specified attributes |
| 1092 |
T} |
| 1093 |
.TE |
| 1094 |
.PP |
| 1095 |
The programming manual also mentioned |
| 1096 |
functions provided for |
| 1097 |
.I termcap |
| 1098 |
compatibility |
| 1099 |
(commenting that they \*(``may go away at a later date\*(''). |
| 1100 |
.PP |
| 1101 |
.TS |
| 1102 |
Lb Lb |
| 1103 |
Li Lw(48n)x. |
| 1104 |
Function Description |
| 1105 |
_ |
| 1106 |
tgetent look up \fItermcap\fP entry for given \fIname\fP |
| 1107 |
tgetflag get Boolean entry for given \fIid\fP |
| 1108 |
tgetnum get numeric entry for given \fIid\fP |
| 1109 |
tgetstr get string entry for given \fIid\fP |
| 1110 |
tgoto apply parameters to given capability |
| 1111 |
tputs T{ |
| 1112 |
write characters via a function parameter, applying padding |
| 1113 |
T} |
| 1114 |
.TE |
| 1115 |
.PP |
| 1116 |
Early |
| 1117 |
.I \%term\%info |
| 1118 |
programs obtained capability values from the |
| 1119 |
.I \%TERMINAL |
| 1120 |
structure initialized by |
| 1121 |
.IR \%setupterm "." |
| 1122 |
.PP |
| 1123 |
SVr3 (1987) extended |
| 1124 |
.I \%term\%info |
| 1125 |
by adding functions to retrieve capability values |
| 1126 |
(like the |
| 1127 |
.I termcap |
| 1128 |
interface), |
| 1129 |
and reusing |
| 1130 |
.I \%tgoto |
| 1131 |
and |
| 1132 |
.IR \%tputs "." |
| 1133 |
.PP |
| 1134 |
.ne 4v |
| 1135 |
.TS |
| 1136 |
Lb Lb |
| 1137 |
LI Lx. |
| 1138 |
Function Description |
| 1139 |
_ |
| 1140 |
tigetflag get Boolean entry for given \fIid\fP |
| 1141 |
tigetnum get numeric entry for given \fIid\fP |
| 1142 |
tigetstr get string entry for given \fIid\fP |
| 1143 |
.TE |
| 1144 |
.PP |
| 1145 |
SVr3 also replaced several of the SVr2 |
| 1146 |
.I \%term\%info |
| 1147 |
functions that had no counterpart in the |
| 1148 |
.I termcap |
| 1149 |
interface, |
| 1150 |
documenting them as obsolete. |
| 1151 |
.PP |
| 1152 |
.TS |
| 1153 |
Lb Lb |
| 1154 |
Li Lix. |
| 1155 |
Function Replaced by |
| 1156 |
_ |
| 1157 |
crmode cbreak |
| 1158 |
fixterm reset_prog_mode |
| 1159 |
gettmode \fRn/a\fP |
| 1160 |
nocrmode nocbreak |
| 1161 |
resetterm reset_shell_mode |
| 1162 |
saveterm def_prog_mode |
| 1163 |
setterm setupterm |
| 1164 |
.TE |
| 1165 |
.PP |
| 1166 |
SVr3 kept the |
| 1167 |
.IR \%mvcur "," |
| 1168 |
.IR \%vidattr "," |
| 1169 |
and |
| 1170 |
.I \%vidputs |
| 1171 |
functions, |
| 1172 |
along with |
| 1173 |
.IR \%putp "," |
| 1174 |
.IR \%tparm "," |
| 1175 |
and |
| 1176 |
.IR \%tputs "." |
| 1177 |
The latter were needed to support padding, |
| 1178 |
and to handle capabilities accessed by functions such as |
| 1179 |
.I \%vidattr |
| 1180 |
(which used more than the two parameters supported by |
| 1181 |
.IR \%tgoto ")." |
| 1182 |
.PP |
| 1183 |
SVr3 introduced the functions for switching between terminal |
| 1184 |
descriptions; |
| 1185 |
for example, |
| 1186 |
.IR \%set_curterm "." |
| 1187 |
Some changes reflected incremental improvements to the SVr2 library. |
| 1188 |
.bP |
| 1189 |
The |
| 1190 |
.I \%TERMINAL |
| 1191 |
type definition was introduced in SVr3.01, |
| 1192 |
for the |
| 1193 |
.I term |
| 1194 |
structure provided in SVr2. |
| 1195 |
.bP |
| 1196 |
Various global variables such as |
| 1197 |
.I \%boolnames |
| 1198 |
were mentioned in the programming manual at this point, |
| 1199 |
though the variables had been provided in SVr2. |
| 1200 |
.PP |
| 1201 |
SVr4 (1989) added the |
| 1202 |
.I \%vid_attr |
| 1203 |
and |
| 1204 |
.I \%vid_puts |
| 1205 |
functions. |
| 1206 |
.PP |
| 1207 |
Other low-level functions are declared in the |
| 1208 |
.I curses |
| 1209 |
header files of Unix systems, |
| 1210 |
but none are documented. |
| 1211 |
Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's |
| 1212 |
\fIvi\fP(1) editor. |
| 1213 |
.SH SEE ALSO |
| 1214 |
\fB\%ncurses\fP(3NCURSES), |
| 1215 |
\fB\%initscr\fP(3NCURSES), |
| 1216 |
\fB\%kernel\fP(3NCURSES), |
| 1217 |
\fB\%memleaks\fP(3NCURSES), |
| 1218 |
\fB\%termcap\fP(3NCURSES), |
| 1219 |
\fB\%curses_variables\fP(3NCURSES), |
| 1220 |
\fB\%putc\fP(3), |
| 1221 |
\fB\%terminfo_variables\fP(3NCURSES), |
| 1222 |
\fB\%terminfo\fP(5) |