Debian Codegraph @

upstream/debian-trixie/man3/terminfo.3ncurses

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