Debian Codegraph @

upstream/debian-unstable/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.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)