2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
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: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
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. *
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 *
29 .\"***************************************************************************
31 .\" $Id: curs_terminfo.3x,v 1.140 2024/06/01 22:29:08 tom Exp $
32 .TH curs_terminfo 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
67 \fIcurses\fR interfaces to \fI\%term\%info\fR database
70 \fB#include <curses.h>
73 \fBTERMINAL *cur_term;
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[];
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);
90 \fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
92 \fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
94 \fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
95 \fBint putp(const char *\fIstr\fP);
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);
102 \fBint tigetflag(const char *\fIcap-code\fP);
103 \fBint tigetnum(const char *\fIcap-code\fP);
104 \fBchar *tigetstr(const char *\fIcap-code\fP);
106 \fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
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);
113 \fBint setterm(const char *\fIterm\fP);
116 These low-level functions must be called by programs that deal directly
119 database to handle certain terminal capabilities,
120 such as programming function keys.
121 For all other functionality,
123 functions are more suitable and their use is recommended.
125 None of these functions use
127 multibyte character strings such as UTF-8.
129 Capability names and codes use the POSIX portable character set.
131 Capability string values have no associated encoding;
132 they are strings of 8-bit characters.
135 \fB\%setupterm\fP should be called.
138 functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
139 initialize the low-level set of terminal-dependent variables listed in
140 \fB\%term_variables\fP(3X).
142 Applications can use the terminal capabilities either directly
143 (via header definitions),
144 or by special functions.
151 to get the definitions for these strings,
161 are initialized by \fB\%setupterm\fP as follows.
163 If \fB\%use_env(FALSE)\fP has been called,
173 if the environment variables
178 their values are used.
179 If these environment variables do not exist and the program is running
181 the current window size
184 if the environment variables do not exist,
193 Parameterized strings should be passed through \fB\%tparm\fP to
198 (including the output of \fB\%tparm\fP)
199 should be sent to the terminal device with \fB\%tputs\fP or
201 Call \fB\%reset_shell_mode\fP to restore the terminal modes before
203 see \fB\%curs_kernel\fP(3X).
206 cursor addressing should
208 output \fB\%enter_ca_mode\fP upon startup and
210 output \fB\%exit_ca_mode\fP before exiting.
212 Programs that execute shell subprocesses should
214 call \fB\%reset_shell_mode\fP and
215 output \fB\%exit_ca_mode\fP before the shell
218 output \fB\%enter_ca_mode\fP and
219 call \fB\%reset_prog_mode\fP after returning from the shell.
221 \fB\%setupterm\fP reads in the
227 but does not set up the output virtualization structures used by
229 Its parameters follow.
233 is the terminal type,
238 the environment variable
243 is the file descriptor used for getting and setting terminal I/O modes.
245 Higher-level applications use \fB\%newterm\fP(3X) to initialize the
253 the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
254 passing the file descriptor derived from its output stream parameter.
257 points to an optional location where an error status can be returned to
262 then \fB\%setupterm\fP returns
266 and stores a status value in the integer pointed to by
270 combined with status of
284 means that the terminal is hardcopy,
285 and cannot be used for
289 \fB\%setupterm\fP determines if the entry is a hardcopy type by
296 means that the terminal could not be found,
297 or that it is a generic type,
298 having too little information for
302 \fB\%setupterm\fP determines if the entry is a generic type by
311 database could not be found.
317 \fB\%setupterm\fP reports an error message upon finding an error and
320 the simplest call is:
324 setupterm((char *)0, 1, (int *)0);
328 which uses all the defaults and sends the output to
331 .\" ********************************************************************
332 .SS "The Terminal State"
333 \fB\%setupterm\fP stores its information about the terminal in a
335 structure pointed to by the global variable \fB\%cur_term\fP.
336 If it detects an error,
337 or decides that the terminal is unsuitable
338 (hardcopy or generic),
339 it discards this information,
340 making it not available to applications.
342 If \fB\%setupterm\fP is called repeatedly for the same terminal type,
343 it will reuse the information.
344 It maintains only one copy of a given terminal's capabilities in memory.
345 If it is called for different terminal types,
346 \fB\%setupterm\fP allocates new storage for each set of terminal
349 \fB\%set_curterm\fP sets \fB\%cur_term\fP to
355 and string variables use the values from
357 It returns the old value of \fB\%cur_term\fP.
359 \fB\%del_curterm\fP frees the space pointed to by
361 and makes it available for further use.
365 the same as \fB\%cur_term\fP,
366 references to any of the
370 and string variables thereafter may refer to invalid memory locations
371 until another \fB\%setupterm\fP has been called.
373 \fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP,
374 except that it is called after restoring memory to a previous state
376 when reloading a game saved as a core image dump).
377 \fB\%restartterm\fP assumes that the windows and the input and output
378 options are the same as when memory was saved,
379 but the terminal type and baud rate may be different.
381 \fB\%restartterm\fP saves various terminal state bits,
382 calls \fB\%setupterm\fP,
383 and then restores the bits.
384 .\" ********************************************************************
385 .SS "Formatting Output"
386 \fB\%tparm\fP instantiates the string
390 A pointer is returned to the result of
392 with the parameters applied.
393 Application developers should keep in mind these quirks of the
396 Although \fB\%tparm\fP's actual parameters may be integers or strings,
397 the prototype expects
402 .B \%set_attributes\fP
405 most terminal capabilities require no more than one or two parameters.
407 Padding information is ignored by \fB\%tparm\fP;
408 it is interpreted by \fB\%tputs\fP.
410 The capability string is null-terminated.
411 Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
413 \fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses
415 rather than a fixed-parameter list.
416 Its numeric parameters are
421 Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
422 parameters consistent with the terminal description.
423 Two extensions are provided as alternatives to deal with untrusted data.
425 \fB\%tiparm_s\fP is an extension which is a safer formatting function
426 than \fB\%tparm\fR or \fB\%tiparm\fR,
427 because it allows the developer to tell the
429 library how many parameters to expect in the parameter list,
430 and which may be string parameters.
432 The \fImask\fP parameter has one bit set for each of the parameters
436 pointers rather than numbers.
438 The extension \fB\%tiscan_s\fP allows the application to inspect a
439 formatting capability to see what the
441 library would assume.
442 .\" ********************************************************************
443 .SS "Output Functions"
444 String capabilities can contain padding information,
446 (accommodating performance limitations of hardware terminals)
447 expressed as \fB$<\fIn\fB>\fR,
448 where \fIn\fP is a nonnegative integral count of milliseconds.
449 If \fIn\fP exceeds 30,000
451 it is capped at that value.
453 \fB\%tputs\fP interprets time-delay information in the string
456 executing the delays:
462 string variable or the return value of
468 is the number of lines affected,
476 function to which the characters are passed,
479 If \fB\%tputs\fP processes a time-delay,
480 it uses the \fB\%delay_output\fP(3X) function,
481 routing any resulting padding characters through this function.
485 .IB str ", 1, putchar)\c"
487 The output of \fB\%putp\fP always goes to
491 specified in \fB\%setupterm\fP.
493 \fB\%vidputs\fP displays the string on the terminal in the video
496 which is any combination of the attributes listed in \fB\%curses\fP(3X).
497 The characters are passed to the
502 \fB\%vidattr\fP is like \fB\%vidputs\fP,
503 except that it outputs through \fI\%putchar\fP(3).
513 They use multiple parameters to represent the character attributes and
520 for the attributes and
525 for the color pair number.
527 Use the attribute constants prefixed with
534 X/Open Curses reserves the
536 argument for future use,
537 saying that applications must provide a null pointer for that argument;
538 but see section \*(``EXTENSIONS\*('' below.
540 While \fB\%putp\fP is a low-level function that does not use high-level
546 because System\ V did this
547 (see section \*(``HISTORY\*('' below).
548 .\" ********************************************************************
549 .SS "Terminal Capability Functions"
552 and \fB\%tigetstr\fP return the value of the capability corresponding to
561 for each capability is given in the table column entitled
563 code in the capabilities section of \fB\%terminfo\fP(5).
565 These functions return special values to denote errors.
567 \fB\%tigetflag\fP returns
572 is not a Boolean capability,
576 if it is canceled or absent from the terminal description.
578 \fB\%tigetnum\fP returns
583 is not a numeric capability,
587 if it is canceled or absent from the terminal description.
589 \fB\%tigetstr\fP returns
594 is not a string capability,
598 if it is canceled or absent from the terminal description.
599 .\" ********************************************************************
600 .SS "Terminal Capability Names"
601 These null-terminated arrays contain
603 the short \fI\%term\%info\fP names (\*(``codes\*(''),
605 the \fItermcap\fP names (\*(``names\*(''),
608 the long \fI\%term\%info\fP names (\*(``fnames\*('')
610 for each of the predefined
616 \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
617 \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
618 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
621 .\" ********************************************************************
622 .SS "Releasing Memory"
623 Each successful call to \fB\%setupterm\fP allocates memory to hold the
624 terminal description.
626 it sets \fB\%cur_term\fP to point to this memory.
627 If an application calls
630 del_curterm(cur_term);
633 the memory will be freed.
635 The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
636 storage allocated by \fB\%setupterm\fP as follows.
638 They add the \*(``static\*(''
644 those were shared by all screens.
648 those are allocated per screen.
649 See \fB\%terminfo\fP(5).
651 To improve performance,
653 6.3 caches the result of analyzing
655 strings for their parameter types.
656 That is stored as a binary tree referenced from the
660 The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
662 Normally they do not free this memory,
663 but it is possible to do that using the \fB\%delscreen\fP(3X) function.
664 .\" ********************************************************************
666 X/Open Curses defines no failure conditions.
671 fails if its terminal parameter is null.
675 returning the same error codes.
678 fails if the associated call to \fB\%setupterm\fP returns
682 fails if it cannot allocate enough memory,
683 or create the initial windows
688 Other error conditions are documented above.
691 returns a null pointer if the capability would require unexpected
697 (strings where integers are expected,
701 fails if the string parameter is null.
702 It does not detect I/O errors:
703 X/Open Curses states that \fB\%tputs\fP ignores the return value
704 of the output function \fI\%putc\fP.
705 .\" ********************************************************************
712 It was originally implemented based on a draft of X/Open Curses,
714 before other parts of the
716 wide-character API were developed,
717 and unlike the other wide-character functions,
718 is also provided in the non-wide-character configuration.
719 .\" ********************************************************************
721 The functions marked as extensions were designed for
723 and are not found in SVr4
727 or any other previous
740 .\" ********************************************************************
742 \fB\%setterm\fP is not described by X/Open and must be considered
744 All other functions are as described by X/Open.
745 .SS "Compatibility Macros"
746 This implementation provides a few macros for compatibility with systems
748 (see section \*(``HISTORY\*('' below).
762 but except for \fB\%setterm\fP,
766 is mentioned in the manual page.
767 It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP,
768 stating that the call
771 setupterm(\fIterm\fP, 1, (int *)0)
774 provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
775 discouraging the latter for new programs.
777 implements each of these symbols as macros for BSD
781 \fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
782 This is not part of X/Open Curses,
783 but is assumed by some applications.
785 Other implementions may not declare the capability name arrays.
786 Some provide them without declaring them.
787 X/Open Curses does not specify them.
789 Extended terminal capability names,
791 .RB \%\*(`` "@TIC@ \-x" \*('',
792 are not stored in the arrays described here.
793 .SS "Output Buffering"
794 Older versions of \fI\%ncurses\fP assumed that the file descriptor
795 passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses
797 and would write to the corresponding stream.
798 In addition to the limitation that the terminal was left in
799 block-buffered mode on exit
802 it was problematic because
804 did not allow a reliable way to clean up on receiving
807 The current version (ncurses6)
808 uses output buffers managed directly by
810 Some of the low-level functions described in this manual page write
811 to the standard output.
812 They are not signal-safe.
813 The high-level functions in
815 employ alternate versions of these functions using the more reliable
817 .SS "Function Prototypes"
818 The X/Open Curses prototypes are based on the SVr4
821 which were defined at the same time the C language was first
822 standardized in the late 1980s.
826 less effectively than a later design might,
827 sometimes applying it needlessly to values that are already constant,
828 and in most cases overlooking parameters that normally would use
831 .IR \%const -qualified
832 parameters to functions that do not declare them
834 may prevent the program from compiling.
836 \*(``writable strings\*('' are an obsolescent feature.
839 this implementation can be configured to change the function prototypes
845 ABI 6 enables this feature by default.
847 X/Open Curses prototypes \fB\%tparm\fP with a fixed number of
849 rather than a variable argument list.
851 This implementation uses a variable argument list,
852 but can be configured to use the fixed-parameter list.
853 Portable applications should provide nine parameters after the format;
854 zeroes are fine for this purpose.
856 In response to review comments by Thomas E. Dickey,
857 X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009.
859 While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
860 the older form is only available as a build-time configuration option.
861 If not specially configured,
862 \fB\%tparm\fP is the same as \fB\%tiparm\fP.
864 Both forms of \fB\%tparm\fP have drawbacks:
866 Most of the calls to \fB\%tparm\fP use only one or two parameters.
867 Passing nine on each call is awkward.
871 for the numeric parameter type is a workaround to make the parameter use
872 the same amount of stack as a pointer.
873 That approach dates back to the mid-1980s,
874 before C was standardized.
877 (and pointers are not required to fit in a
880 Providing the right number of parameters for a variadic function
881 such as \fB\%tiparm\fP can be a problem,
882 in particular for string parameters.
886 capabilities use string parameters
888 the ones used for programmable function keys).
890 The \fI\%ncurses\fP library checks usage of these capabilities,
893 if the capability mishandles string parameters.
894 But it cannot check if a calling program provides strings in the right
895 places for the \fB\%tparm\fP calls.
897 The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
899 so that it calls \fB\%tparm\fP correctly.
900 .SS "Special \fITERM\fP treatment"
901 If configured to use the terminal driver,
902 .\" XXX: as opposed to the Unix terminal driver, termio(s)?
903 as with the MinGW port,
905 \fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
906 special value \*(``unknown\*(''.
910 uses the special value \*(``dumb\*(''.
912 The difference between the two is that the former uses the
917 while the latter does not.
918 A generic terminal is unsuitable for full-screen applications.
920 \fB\%setupterm\fP allows explicit use of the
921 the windows console driver by checking if \fB$TERM\fP is set to
922 \*(``#win32con\*('' or an abbreviation of that string.
923 .SS "Other Portability Issues"
925 \fB\%set_curterm\fP returns an
930 We have chosen to implement the X/Open Curses semantics.
933 the third argument of \fB\%tputs\fP has the type
934 .RB \*(`` "int (*putc)(char)" \*(''.
936 At least one implementation of X/Open Curses (Solaris) returns a value
942 It instead returns the length of the string,
943 and does no error checking.
944 .\" ********************************************************************
946 SVr2 (1984) introduced the
949 Its programming manual mentioned the following low-level functions.
956 fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
957 gettmode establish current terminal modes
958 mvcur low level cursor motion
959 putp use \fBtputs\fP to send characters via \fIputchar\fP
960 resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
962 resetty reset terminal flags to stored value
963 saveterm save current modes as \*(``in \fIcurses\fP\*('' state
964 savetty store current terminal flags
965 setterm establish terminal with given type
966 setupterm establish terminal with given type
967 tparm interpolate parameters into string capability
968 tputs apply padding information to a string
969 vidattr like \fBvidputs\fP, but output through \fIputchar\fP
971 write string to terminal, applying specified attributes
975 The programming manual also mentioned
976 functions provided for
979 (commenting that they \*(``may go away at a later date\*('').
986 tgetent look up \fItermcap\fP entry for given \fIname\fP
987 tgetflag get Boolean entry for given \fIid\fP
988 tgetnum get numeric entry for given \fIid\fP
989 tgetstr get string entry for given \fIid\fP
990 tgoto apply parameters to given capability
992 write characters via a function parameter, applying padding
998 programs obtained capability values from the
1000 structure initialized by \fB\%setupterm\fP.
1002 SVr3 (1987) extended
1004 by adding functions to retrieve capability values
1008 and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
1013 Function Description
1015 tigetflag get Boolean entry for given \fIid\fP
1016 tigetnum get numeric entry for given \fIid\fP
1017 tigetstr get string entry for given \fIid\fP
1020 SVr3 also replaced several of the SVr2
1022 functions that had no counterpart in the
1025 documenting them as obsolete.
1030 Function Replaced by
1033 fixterm reset_prog_mode
1036 resetterm reset_shell_mode
1037 saveterm def_prog_mode
1041 SVr3 kept the \fB\%mvcur\fP,
1043 and \fB\%vidputs\fP functions,
1044 along with \fB\%putp\fP,
1047 The latter were needed to support padding,
1048 and to handle capabilities accessed by functions such as \fB\%vidattr\fP
1049 (which used more than the two parameters supported by \fB\%tgoto\fP).
1051 SVr3 introduced the functions for switching between terminal
1054 \fB\%set_curterm\fP.
1055 Some changes reflected incremental improvements to the SVr2 library.
1059 type definition was introduced in SVr3.01,
1062 structure provided in SVr2.
1064 Various global variables such as \fB\%boolnames\fP were mentioned
1065 in the programming manual at this point,
1066 though the variables had been provided in SVr2.
1068 SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
1070 Other low-level functions are declared in the
1072 header files of Unix systems,
1073 but none are documented.
1074 Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
1078 \fB\%curs_initscr\fP(3X),
1079 \fB\%curs_kernel\fP(3X),
1080 \fB\%curs_memleaks\fP(3X),
1081 \fB\%curs_termcap\fP(3X),
1082 \fB\%curs_variables\fP(3X),
1084 \fB\%term_variables\fP(3X),