Debian Codegraph @

upstream/mageia-cauldron/man3/curs_terminfo.3x

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.164 2025/04/05 22:21:02 tom Exp $
32 .TH curs_terminfo 3X 2025-04-05 "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\%term_variables\fP(3X).
146 (A
147 .I curses
148 application calling \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) 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\%term_variables\fP(3X))
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(3X).
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(3X) to restore the terminal modes before
177 exiting.
178 (A
179 .I curses
180 application calling \fB\%endwin\fP(3X) 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(3X) 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(3X) 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(3X) 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 releases the memory pointed to by
358 .IR \%oterm "."
359 If
360 .I \%oterm
361 is
362 the same as
363 .BR \%cur_term ","
364 references to any of the
365 .I \%term\%info
366 Boolean,
367 numeric,
368 and string capabilities thereafter may refer to invalid memory locations
369 until
370 .B \%setupterm
371 is called again.
372 .PP
373 .B \%restartterm
374 is similar to
375 .BR \%setupterm ","
376 but is intended for use after restoring program memory
377 to a previous state
378 (for example,
379 when reloading an application that has been suspended from one terminal
380 session and restored in another).
381 .B \%restartterm
382 assumes that the display dimensions
383 and the input and output options are the same as when memory was saved,
384 but the terminal type and line speed may differ.
385 Accordingly,
386 .B \%restartterm
387 saves relevant terminal state,
388 calls
389 .BR \%setupterm ","
390 then restores that state.
391 .\" ********************************************************************
392 .SS "Formatting Output"
393 \fB\%tparm\fP instantiates the string
394 .I str
395 with parameters
396 .IR pi "."
397 It returns a pointer to a character string representing
398 .I str
399 with the parameters applied to \*(``%\*('' expressions within.
400 .\" XXX: Whose responsibility is it to free that string?
401 Application developers should keep in mind some quirks of the interface.
402 .bP
403 Although \fB\%tparm\fP's actual parameters may be integers or strings,
404 the prototype expects
405 .I long
406 (integer) values.
407 .bP
408 Aside from the
409 .B \%set_attributes\fP
410 .RB ( sgr )
411 capability,
412 most terminal capabilities require no more than one or two parameters.
413 .bP
414 Padding information is ignored by \fB\%tparm\fP;
415 it is interpreted by \fB\%tputs\fP.
416 .bP
417 The capability string is null-terminated.
418 Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
419 .PP
420 \fB\%tiparm\fP is a newer form of \fB\%tparm\fP that uses
421 .I \%stdarg.h
422 rather than a fixed-length parameter list.
423 Its numeric parameters are
424 .IR int s
425 rather than
426 .IR long "s."
427 .PP
428 .B \%tparm
429 and
430 .B \%tiparm
431 assume that the application
432 passes parameters consistent with the terminal description.
433 .I \%ncurses
434 provides two extensions as alternatives to deal with untrusted data.
435 .bP
436 The
437 .B \%tiparm_s
438 extension is a safer formatting function than
439 .B \%tparm
440 or
441 .BR \%tiparm ","
442 because it allows the developer to tell the
443 .I curses
444 library how many parameters to expect in the parameter list,
445 and which may be string parameters.
446 .IP
447 The
448 .I mask
449 parameter has one bit set for each of the parameters
450 (up to 9)
451 passed as
452 .I char
453 pointers rather than numbers.
454 .bP
455 The extension
456 .B \%tiscan_s
457 allows the application
458 to inspect a formatting capability to see what the
459 .I curses
460 library would assume.
461 .\" ********************************************************************
462 .SS "Output Functions"
463 String capabilities can contain
464 .IR padding ","
465 a time delay
466 (accommodating performance limitations of hardware terminals)
467 expressed as
468 .BI $< n >\c
469 ,
470 where
471 .I n
472 is a nonnegative integral count of milliseconds.
473 If
474 .I n
475 exceeds 30,000
476 (thirty seconds),
477 .I \%ncurses
478 caps it at that value.
479 .PP
480 .B \%tputs
481 interprets time delays in the string
482 .I str
483 and acts upon them.
484 .bP
485 The
486 .I str
487 parameter must be a
488 .I \%term\%info
489 string capability or the return value of
490 .B \%tparm
491 or
492 .BR \%tiparm "."
493 .bP
494 .I affcnt
495 is the number of lines affected,
496 or
497 .B 1
498 if not applicable.
499 .bP
500 .I putc
501 is a
502 .IR \%putchar -like
503 function to which the characters are passed,
504 one at a time.
505 .PP
506 .B \%tputs
507 processes each time delay with the \fB\%delay_output\fP(3X) function,
508 routing any resulting padding characters through this function.
509 .PP
510 \fB\%putp\fR calls
511 .RB \%\*(`` tputs(\c
512 .IB str ", 1, putchar)\c"
513 \*(''.
514 The output of \fB\%putp\fP always goes to
515 .IR stdout ","
516 rather than the
517 .I \%file\%des
518 specified in \fB\%setupterm\fP.
519 .PP
520 \fB\%vidputs\fP displays the string on the terminal in the video
521 attribute mode
522 .IR attrs ","
523 which is any combination of the attributes listed in \fB\%curses\fP(3X).
524 The characters are passed to the
525 .IR \%putchar -like
526 function
527 .IR putc "."
528 .PP
529 \fB\%vidattr\fP is like \fB\%vidputs\fP,
530 except that it outputs through \fI\%putchar\fP(3).
531 .PP
532 .B \%vid_attr
533 and
534 .B \%vid_puts
535 correspond to
536 .B \%vidattr
537 and
538 .BR \%vidputs ","
539 respectively.
540 They use multiple parameters to represent the character attributes and
541 color;
542 namely,
543 .bP
544 .IR \%attrs ","
545 of type
546 .IR \%attr_t ","
547 for the attributes and
548 .bP
549 .IR pair ","
550 of type
551 .IR short ","
552 for the color pair number.
553 .PP
554 Use the attribute constants prefixed with
555 .RB \*(`` WA_ \*(''
556 with
557 .B \%vid_attr
558 and
559 .BR \%vid_puts "."
560 .PP
561 X/Open Curses reserves the
562 .I opts
563 argument for future use,
564 saying that applications must provide a null pointer for that argument;
565 but see section \*(``EXTENSIONS\*('' below.
566 .PP
567 While
568 .B \%putp
569 is a lower-level function
570 that does not use higher-level
571 .I curses
572 state,
573 .I \%ncurses
574 declares it in
575 .I \%curses.h
576 because System\ V did so
577 (see section \*(``HISTORY\*('' below).
578 .\" ********************************************************************
579 .SS "Terminal Capability Functions"
580 .BR \%tigetflag ","
581 .BR \%tigetnum ","
582 and
583 .B \%tigetstr
584 return the value of the capability corresponding to
585 the
586 .I \%term\%info
587 .IR cap-code ","
588 such as
589 .BR xenl ","
590 passed to them.
591 The
592 .I cap-code
593 for each capability is given in the table column of that name
594 in the \*(``Predefined Capabilities\*('' section of \fB\%terminfo\fP(5).
595 .PP
596 These functions return special values to denote errors.
597 .PP
598 .B \%tigetflag
599 returns
600 .TP
601 .B \-1
602 if
603 .I cap-code
604 is not a Boolean capability,
605 or
606 .TP
607 .B 0
608 if it is canceled or absent from the terminal description.
609 .PP
610 .B \%tigetnum
611 returns
612 .TP
613 .B \-2
614 if
615 .I cap-code
616 is not a numeric capability,
617 or
618 .TP
619 .B \-1
620 if it is canceled or absent from the terminal description.
621 .PP
622 .B \%tigetstr
623 returns
624 .TP
625 .B "(char *)\-1"
626 if
627 .I cap-code
628 is not a string capability,
629 or
630 .TP
631 .B NULL
632 if it is canceled or absent from the terminal description.
633 .\" ********************************************************************
634 .SS "Terminal Capability Names"
635 These null-terminated arrays contain
636 .bP
637 the short \fI\%term\%info\fP names (\*(``codes\*(''),
638 .bP
639 the \fItermcap\fP names (\*(``names\*(''),
640 and
641 .bP
642 the long \fI\%term\%info\fP names (\*(``fnames\*('')
643 .PP
644 for each of the predefined
645 .I \%term\%info
646 variables:
647 .PP
648 .RS
649 .nf
650 \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
651 \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
652 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
653 .fi
654 .RE
655 .\" ********************************************************************
656 .SS "Releasing Memory"
657 Each successful call to \fB\%setupterm\fP allocates memory to hold the
658 terminal description.
659 As a side effect,
660 it sets \fB\%cur_term\fP to point to this memory.
661 If an application calls
662 .RS
663 .EX
664 del_curterm(cur_term);
665 .EE
666 .RE
667 the memory will be freed.
668 .PP
669 The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
670 storage allocated by \fB\%setupterm\fP as follows.
671 .bP
672 They add the \*(``static\*(''
673 .I \%term\%info
674 variables [a-z].
675 Before
676 .I \%ncurses
677 6.3,
678 those were shared by all screens.
679 With
680 .I \%ncurses
681 6.3,
682 those are allocated per screen.
683 See \fB\%terminfo\fP(5).
684 .bP
685 To improve performance,
686 .I \%ncurses
687 6.3 caches the result of analyzing
688 .I \%term\%info
689 strings for their parameter types.
690 That is stored as a binary tree referenced from the
691 .I \%TERMINAL
692 structure.
693 .PP
694 The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
695 \fB\%setupterm\fP.
696 Normally they do not free this memory,
697 but it is possible to do that using the \fB\%delscreen\fP(3X) function.
698 .\" ********************************************************************
699 .SH RETURN VALUE
700 Functions that return integers return
701 .B ERR
702 upon failure and
703 .B OK
704 upon success.
705 .PP
706 In
707 .IR \%ncurses ","
708 .TP 5
709 .B del_curtem
710 fails if its terminal parameter is null.
711 .TP 5
712 .B putp
713 calls \fB\%tputs\fP,
714 returning the same error codes.
715 .TP 5
716 .B restartterm
717 fails if the associated call to \fB\%setupterm\fP returns
718 .BR ERR "."
719 .TP 5
720 .B setupterm
721 fails if it cannot allocate enough memory,
722 or create the initial windows
723 .RB \%( stdscr ,
724 .BR \%curscr ","
725 and
726 .BR \%newscr ")."
727 Other error conditions are documented above.
728 .TP 5
729 .B tparm
730 returns a null pointer if the capability would require unexpected
731 parameters;
732 that is,
733 too many,
734 too few,
735 or incorrect types
736 (strings where integers are expected,
737 or vice versa).
738 .TP 5
739 .B tputs
740 fails if the string parameter is null.
741 It does not detect I/O errors:
742 X/Open Curses states that \fB\%tputs\fP ignores the return value
743 of the output function \fI\%putc\fP.
744 .\" ********************************************************************
745 .SH NOTES
746 The
747 .B \%vid_attr
748 function in
749 .I \%ncurses
750 is a special case.
751 It was originally implemented based on a draft of X/Open Curses,
752 as a macro,
753 before other parts of the
754 .I \%ncurses
755 wide-character API were developed,
756 and unlike the other wide-character functions,
757 is also provided in the non-wide-character configuration.
758 .\" ********************************************************************
759 .SH EXTENSIONS
760 The functions marked as extensions originated in
761 .IR \%ncurses ","
762 and are not found in SVr4
763 .IR curses ","
764 4.4BSD
765 .IR curses ","
766 or any other previous
767 .I curses
768 implementation.
769 .PP
770 .I \%ncurses
771 allows
772 .I opts
773 to be a pointer to
774 .IR int ","
775 which overrides the
776 .I pair
777 .RI ( short )
778 argument.
779 .\" ********************************************************************
780 .SH PORTABILITY
781 Except for
782 .IR \%setterm ","
783 X/Open Curses Issue\ 4 describes these functions.
784 It specifies no error conditions for them.
785 .PP
786 SVr4 describes a successful return value
787 except where \*(``otherwise noted\*(''
788 as
789 \*(``an integer value other than
790 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 539
791 .SS "Header Files"
792 On legacy
793 .I curses
794 systems,
795 include
796 .I \%curses.h
797 and
798 .I \%term.h
799 in that order
800 to make visible the definitions of the string arrays
801 storing the capability names and codes.
802 .SS "Compatibility Macros"
803 .I \%ncurses
804 implements a few macros for early System\ V
805 .I curses
806 compatibility
807 (see section \*(``HISTORY\*('' below).
808 They include
809 .IR \%crmode ","
810 .IR \%fixterm ","
811 .IR \%gettmode ","
812 .IR \%nocrmode ","
813 .IR \%resetterm ","
814 .IR \%saveterm ","
815 and
816 .IR \%setterm "."
817 .PP
818 In SVr4,
819 these are found in
820 .IR \%curses.h ","
821 but except for
822 .IR \%setterm ","
823 are likewise macros.
824 The one function,
825 .IR \%setterm ","
826 is mentioned in the manual page.
827 It further notes that
828 .I \%setterm
829 was replaced by
830 .IR \%setupterm ","
831 stating that the call
832 .RS
833 .EX
834 .RI setupterm( term ", 1, (int *)0)"
835 .EE
836 .RE
837 provides the same functionality as
838 .RS
839 .EX
840 .RI setterm( term )
841 .EE
842 .RE
843 and discouraging the latter for new programs.
844 .SS "Legacy Data"
845 .I \%setupterm
846 copies the terminal name to the array
847 .IR \%ttytype "."
848 This behavior is not specified by X/Open Curses,
849 but is assumed by some applications.
850 .PP
851 Other implementations may not declare the capability name arrays.
852 Some provide them without declaring them.
853 X/Open Curses does not specify them.
854 .PP
855 Extended terminal capability names,
856 as defined by
857 .RB \%\*(`` "tic \-x" \*('',
858 are not stored in the arrays described here.
859 .SS "Output Buffering"
860 Older versions of
861 .I \%ncurses
862 assumed that the file descriptor passed to
863 .I \%setupterm
864 from
865 .I \%initscr
866 or
867 .I \%newterm
868 used buffered I/O,
869 and wrote to the corresponding
870 .I stdio
871 stream.
872 In addition to the limitation that the terminal was left in
873 block-buffered mode on exit
874 (like System\ V
875 .IR curses "),"
876 it was problematic because
877 .I \%ncurses
878 did not allow a reliable way to clean up on receiving
879 .IR SIGTSTP "."
880 .PP
881 .I \%ncurses
882 .RI 6. x
883 uses output buffers managed directly by
884 .IR \%ncurses "."
885 The lower-level functions described here
886 that write to the terminal device
887 do so via the standard output stream;
888 they thus are not signal-safe.
889 The higher-level functions in
890 .I \%ncurses
891 employ alternate versions of these functions
892 using a more reliable buffering scheme.
893 .SS "Function Prototypes"
894 The X/Open Curses prototypes are based on the SVr4
895 .I curses
896 header declarations,
897 which were defined at the same time the C language was first
898 standardized in the late 1980s.
899 .bP
900 X/Open Curses uses
901 .I \%const
902 less effectively than a later design might,
903 sometimes applying it needlessly to function parameters
904 that are passed by value
905 (and therefore copied),
906 and in most cases overlooking parameters
907 that normally would benefit from
908 .IR \%const "."
909 Passing
910 .IR \%const -qualified
911 parameters to functions that do not declare them
912 .I \%const
913 may prevent the program from compiling.
914 On the other hand,
915 \*(``writable strings\*('' are an obsolescent C language feature.
916 .IP
917 As an extension,
918 .I \%ncurses
919 can be configured to change the function prototypes
920 to use the
921 .I \%const
922 keyword.
923 The
924 .I \%ncurses
925 ABI 6 enables this feature by default.
926 .bP
927 X/Open Curses prototypes
928 .I \%tparm
929 with a fixed number of parameters,
930 rather than a variable argument list.
931 .IP
932 .I \%ncurses
933 uses a variable argument list,
934 but can be configured to use the fixed-parameter list.
935 Portable applications should provide nine parameters after the format;
936 zeroes are fine for this purpose.
937 .IP
938 In response to review comments by Thomas E. Dickey,
939 X/Open Curses Issue\ 7 proposed the
940 .I \%tiparm
941 function in mid-2009.
942 .IP
943 While
944 .I \%tiparm
945 is always provided in
946 .IR \%ncurses ","
947 the older form is available only as a build-time configuration option.
948 If not specially configured,
949 .I \%tparm
950 is the same as
951 .IR \%tiparm "."
952 .PP
953 Both forms of
954 .I \%tparm
955 have drawbacks.
956 .bP
957 Most calls to
958 .I \%tparm
959 require only one or two parameters.
960 Passing nine on each call is awkward.
961 .IP
962 Using
963 .I long
964 for the numeric parameter type is a workaround to make the parameter use
965 the same amount of stack memory as a pointer.
966 That approach dates to the mid-1980s,
967 before C was standardized.
968 Since ANSI\ C (1989),
969 C language standards do not require a pointer to fit in a
970 .IR long ")."
971 .bP
972 Providing the right number of parameters for a variadic function
973 such as
974 .I \%tiparm
975 can be a problem,
976 in particular for string parameters.
977 However,
978 only a few
979 .I \%term\%info
980 capabilities use string parameters
981 (for instance,
982 the ones used for programmable function keys).
983 .IP
984 The
985 .I \%ncurses
986 library checks usage of these capabilities,
987 and returns
988 .I ERR
989 if the capability mishandles string parameters.
990 But it cannot check if a calling program provides strings in the right
991 places for the
992 .I \%tparm
993 calls.
994 .IP
995 .IR \%ncurses 's
996 \fB\%tput\fR(1) checks its use of these capabilities with a table,
997 so that it calls
998 .I \%tparm
999 correctly.
1000 .SS "Special \fITERM\fP treatment"
1001 If
1002 .I \%ncurses
1003 is configured to use a terminal driver
1004 that does not employ the POSIX
1005 .I \%termios
1006 API,
1007 as with the MinGW port,
1008 .bP
1009 .I \%setupterm
1010 interprets a missing or empty
1011 .I TERM
1012 variable as the special value \*(``unknown\*(''.
1013 .IP
1014 SVr4
1015 .I curses
1016 uses the special value \*(``dumb\*(''.
1017 .IP
1018 The difference between the two is that the former uses the
1019 .B \%generic_type
1020 .RB ( gn )
1021 .I \%term\%info
1022 capability,
1023 while the latter does not.
1024 A generic terminal is unsuitable for full-screen applications.
1025 .bP
1026 .I \%setupterm
1027 allows explicit use of the Microsoft Windows console driver by checking
1028 whether the
1029 .I TERM
1030 environment variable has the value \*(``#win32con\*(''
1031 or an abbreviation of that string.
1032 .SS "Other Portability Issues"
1033 In SVr4,
1034 .I \%set_curterm
1035 returns an
1036 .IR int ","
1037 .I OK
1038 or
1039 .IR ERR "."
1040 We have chosen to implement the X/Open Curses semantics.
1041 .PP
1042 In SVr4,
1043 the third argument of
1044 .I \%tputs
1045 has the type
1046 .RB \*(`` "int (*)(char)" \*(''.
1047 .PP
1048 At least one implementation of X/Open Curses
1049 (Solaris
1050 .IR \%xcurses ")"
1051 returns a value other than
1052 .I OK
1053 or
1054 .I ERR
1055 from
1056 .IR \%tputs "."
1057 It instead returns the length of the string,
1058 and does no error checking.
1059 .\" ********************************************************************
1060 .SH HISTORY
1061 SVr2 (1984) introduced the
1062 .I \%term\%info
1063 feature.
1064 Its programming manual mentioned the following low-level functions.
1065 .PP
1066 .TS
1067 lB lB
1068 lI lx.
1069 Function Description
1070 _
1071 fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
1072 gettmode establish current terminal modes
1073 mvcur low level cursor motion
1074 putp use \fItputs\fP to send characters via \fIputchar\fP
1075 resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
1076 state
1077 resetty reset terminal flags to stored value
1078 saveterm save current modes as \*(``in \fIcurses\fP\*('' state
1079 savetty store current terminal flags
1080 setterm establish terminal with given type
1081 setupterm establish terminal with given type
1082 tparm interpolate parameters into string capability
1083 tputs apply padding information to a string
1084 vidattr like \fIvidputs\fP, but output through \fIputchar\fP
1085 vidputs T{
1086 write string to terminal, applying specified attributes
1087 T}
1088 .TE
1089 .PP
1090 The programming manual also mentioned
1091 functions provided for
1092 .I termcap
1093 compatibility
1094 (commenting that they \*(``may go away at a later date\*('').
1095 .PP
1096 .TS
1097 lB lB
1098 lI lx.
1099 Function Description
1100 _
1101 tgetent look up \fItermcap\fP entry for given \fIname\fP
1102 tgetflag get Boolean entry for given \fIid\fP
1103 tgetnum get numeric entry for given \fIid\fP
1104 tgetstr get string entry for given \fIid\fP
1105 tgoto apply parameters to given capability
1106 tputs T{
1107 write characters via a function parameter, applying padding
1108 T}
1109 .TE
1110 .PP
1111 Early
1112 .I \%term\%info
1113 programs obtained capability values from the
1114 .I \%TERMINAL
1115 structure initialized by
1116 .IR \%setupterm "."
1117 .PP
1118 SVr3 (1987) extended
1119 .I \%term\%info
1120 by adding functions to retrieve capability values
1121 (like the
1122 .I termcap
1123 interface),
1124 and reusing
1125 .I \%tgoto
1126 and
1127 .IR \%tputs "."
1128 .PP
1129 .ne 4v
1130 .TS
1131 lB lB
1132 lI lx.
1133 Function Description
1134 _
1135 tigetflag get Boolean entry for given \fIid\fP
1136 tigetnum get numeric entry for given \fIid\fP
1137 tigetstr get string entry for given \fIid\fP
1138 .TE
1139 .PP
1140 SVr3 also replaced several of the SVr2
1141 .I \%term\%info
1142 functions that had no counterpart in the
1143 .I termcap
1144 interface,
1145 documenting them as obsolete.
1146 .PP
1147 .TS
1148 lB lB
1149 lI lIx.
1150 Function Replaced by
1151 _
1152 crmode cbreak
1153 fixterm reset_prog_mode
1154 gettmode \fRn/a\fP
1155 nocrmode nocbreak
1156 resetterm reset_shell_mode
1157 saveterm def_prog_mode
1158 setterm setupterm
1159 .TE
1160 .PP
1161 SVr3 kept the
1162 .IR \%mvcur ","
1163 .IR \%vidattr ","
1164 and
1165 .I \%vidputs
1166 functions,
1167 along with
1168 .IR \%putp ","
1169 .IR \%tparm ","
1170 and
1171 .IR \%tputs "."
1172 The latter were needed to support padding,
1173 and to handle capabilities accessed by functions such as
1174 .I \%vidattr
1175 (which used more than the two parameters supported by
1176 .IR \%tgoto ")."
1177 .PP
1178 SVr3 introduced the functions for switching between terminal
1179 descriptions;
1180 for example,
1181 .IR \%set_curterm "."
1182 Some changes reflected incremental improvements to the SVr2 library.
1183 .bP
1184 The
1185 .I \%TERMINAL
1186 type definition was introduced in SVr3.01,
1187 for the
1188 .I term
1189 structure provided in SVr2.
1190 .bP
1191 Various global variables such as
1192 .I \%boolnames
1193 were mentioned in the programming manual at this point,
1194 though the variables had been provided in SVr2.
1195 .PP
1196 SVr4 (1989) added the
1197 .I \%vid_attr
1198 and
1199 .I \%vid_puts
1200 functions.
1201 .PP
1202 Other low-level functions are declared in the
1203 .I curses
1204 header files of Unix systems,
1205 but none are documented.
1206 Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
1207 \fIvi\fP(1) editor.
1208 .SH SEE ALSO
1209 \fB\%curses\fP(3X),
1210 \fB\%curs_initscr\fP(3X),
1211 \fB\%curs_kernel\fP(3X),
1212 \fB\%curs_memleaks\fP(3X),
1213 \fB\%curs_termcap\fP(3X),
1214 \fB\%curs_variables\fP(3X),
1215 \fB\%putc\fP(3),
1216 \fB\%term_variables\fP(3X),
1217 \fB\%terminfo\fP(5)