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.136 2024/04/14 00:14:40 tom Exp $
32 .TH curs_terminfo 3X 2024-04-13 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
68 \fIcurses\fR interfaces to \fI\%term\%info\fR database
71 \fB#include <curses.h>
74 \fBTERMINAL *cur_term;
76 \fBconst char * const boolnames[];
77 \fBconst char * const boolcodes[];
78 \fBconst char * const boolfnames[];
79 \fBconst char * const numnames[];
80 \fBconst char * const numcodes[];
81 \fBconst char * const numfnames[];
82 \fBconst char * const strnames[];
83 \fBconst char * const strcodes[];
84 \fBconst char * const strfnames[];
86 \fBint setupterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
87 \fBTERMINAL *set_curterm(TERMINAL *\fInterm\fP);
88 \fBint del_curterm(TERMINAL *\fIoterm\fP);
89 \fBint restartterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
91 \fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
93 \fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
95 \fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
96 \fBint putp(const char *\fIstr\fP);
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, int (*\fIputc\fP)(int));
101 \fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
103 \fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
105 \fBint tigetflag(const char *\fIcap-code\fP);
106 \fBint tigetnum(const char *\fIcap-code\fP);
107 \fBchar *tigetstr(const char *\fIcap-code\fP);
109 \fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
112 \fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...);
113 \fBint tiscan_s(int *\fIexpected\fP, int *\fImask\fP, const char *\fIstr\fP);
116 \fBint setterm(const char *\fIterm\fP);
119 These low-level functions must be called by programs that deal directly
122 database to handle certain terminal capabilities,
123 such as programming function keys.
124 For all other functionality,
126 functions are more suitable and their use is recommended.
128 None of these functions use
130 multibyte character strings such as UTF-8.
132 Capability names and codes use the POSIX portable character set.
134 Capability string values have no associated encoding;
135 they are strings of 8-bit characters.
138 \fB\%setupterm\fP should be called.
141 functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
142 initialize the low-level set of terminal-dependent variables listed in
143 \fB\%term_variables\fP(3X).
145 Applications can use the terminal capabilities either directly
146 (via header definitions),
147 or by special functions.
154 to get the definitions for these strings,
164 are initialized by \fB\%setupterm\fP as follows.
166 If \fB\%use_env(FALSE)\fP has been called,
176 if the environment variables
181 their values are used.
182 If these environment variables do not exist and the program is running
184 the current window size
187 if the environment variables do not exist,
196 Parameterized strings should be passed through \fB\%tparm\fP to
201 (including the output of \fB\%tparm\fP)
202 should be sent to the terminal device with \fB\%tputs\fP or
204 Call \fB\%reset_shell_mode\fP to restore the terminal modes before
206 see \fB\%curs_kernel\fP(3X).
209 cursor addressing should
211 output \fB\%enter_ca_mode\fP upon startup and
213 output \fB\%exit_ca_mode\fP before exiting.
215 Programs that execute shell subprocesses should
217 call \fB\%reset_shell_mode\fP and
218 output \fB\%exit_ca_mode\fP before the shell
221 output \fB\%enter_ca_mode\fP and
222 call \fB\%reset_prog_mode\fP after returning from the shell.
224 \fB\%setupterm\fP reads in the
230 but does not set up the output virtualization structures used by
232 Its parameters follow.
236 is the terminal type,
241 the environment variable
246 is the file descriptor used for getting and setting terminal I/O modes.
248 Higher-level applications use \fB\%newterm\fP(3X) to initialize the
256 the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
257 passing the file descriptor derived from its output stream parameter.
260 points to an optional location where an error status can be returned to
265 then \fB\%setupterm\fP returns
269 and stores a status value in the integer pointed to by
273 combined with status of
287 means that the terminal is hardcopy,
288 and cannot be used for
292 \fB\%setupterm\fP determines if the entry is a hardcopy type by
299 means that the terminal could not be found,
300 or that it is a generic type,
301 having too little information for
305 \fB\%setupterm\fP determines if the entry is a generic type by
314 database could not be found.
320 \fB\%setupterm\fP reports an error message upon finding an error and
323 the simplest call is:
327 setupterm((char *)0, 1, (int *)0);
331 which uses all the defaults and sends the output to
334 .\" ********************************************************************
335 .SS "The Terminal State"
336 \fB\%setupterm\fP stores its information about the terminal in a
338 structure pointed to by the global variable \fB\%cur_term\fP.
339 If it detects an error,
340 or decides that the terminal is unsuitable
341 (hardcopy or generic),
342 it discards this information,
343 making it not available to applications.
345 If \fB\%setupterm\fP is called repeatedly for the same terminal type,
346 it will reuse the information.
347 It maintains only one copy of a given terminal's capabilities in memory.
348 If it is called for different terminal types,
349 \fB\%setupterm\fP allocates new storage for each set of terminal
352 \fB\%set_curterm\fP sets \fB\%cur_term\fP to
358 and string variables use the values from
360 It returns the old value of \fB\%cur_term\fP.
362 \fB\%del_curterm\fP frees the space pointed to by
364 and makes it available for further use.
368 the same as \fB\%cur_term\fP,
369 references to any of the
373 and string variables thereafter may refer to invalid memory locations
374 until another \fB\%setupterm\fP has been called.
376 \fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP,
377 except that it is called after restoring memory to a previous state
379 when reloading a game saved as a core image dump).
380 \fB\%restartterm\fP assumes that the windows and the input and output
381 options are the same as when memory was saved,
382 but the terminal type and baud rate may be different.
384 \fB\%restartterm\fP saves various terminal state bits,
385 calls \fB\%setupterm\fP,
386 and then restores the bits.
387 .\" ********************************************************************
388 .SS "Formatting Output"
389 \fB\%tparm\fP instantiates the string
393 A pointer is returned to the result of
395 with the parameters applied.
396 Application developers should keep in mind these quirks of the
399 Although \fB\%tparm\fP's actual parameters may be integers or strings,
400 the prototype expects
405 .B \%set_attributes\fP
408 most terminal capabilities require no more than one or two parameters.
410 Padding information is ignored by \fB\%tparm\fP;
411 it is interpreted by \fB\%tputs\fP.
413 The capability string is null-terminated.
414 Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
416 \fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses
418 rather than a fixed-parameter list.
419 Its numeric parameters are
424 Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
425 parameters consistent with the terminal description.
426 Two extensions are provided as alternatives to deal with untrusted data.
428 \fB\%tiparm_s\fP is an extension which is a safer formatting function
429 than \fB\%tparm\fR or \fB\%tiparm\fR,
430 because it allows the developer to tell the
432 library how many parameters to expect in the parameter list,
433 and which may be string parameters.
435 The \fImask\fP parameter has one bit set for each of the parameters
439 pointers rather than numbers.
441 The extension \fB\%tiscan_s\fP allows the application to inspect a
442 formatting capability to see what the
444 library would assume.
445 .\" ********************************************************************
446 .SS "Output Functions"
447 String capabilities can contain padding information,
449 (accommodating performance limitations of hardware terminals)
450 expressed as \fB$<\fIn\fB>\fR,
451 where \fIn\fP is a nonnegative integral count of milliseconds.
452 If \fIn\fP exceeds 30,000
454 it is capped at that value.
456 \fB\%tputs\fP interprets time-delay information in the string
459 executing the delays:
465 string variable or the return value of
471 The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
474 which happens to share these function names with the
479 is the number of lines affected,
487 function to which the characters are passed,
490 If \fB\%tputs\fP processes a time-delay,
491 it uses the \fB\%delay_output\fP(3X) function,
492 routing any resulting padding characters through this function.
496 .IB str ", 1, putchar)\c"
498 The output of \fB\%putp\fP always goes to
502 specified in \fB\%setupterm\fP.
504 \fB\%vidputs\fP displays the string on the terminal in the video
507 which is any combination of the attributes listed in \fB\%curses\fP(3X).
508 The characters are passed to the
513 \fB\%vidattr\fP is like \fB\%vidputs\fP,
514 except that it outputs through \fI\%putchar\fP(3).
524 They use multiple parameters to represent the character attributes and
531 for the attributes and
536 for the color pair number.
538 Use the attribute constants prefixed with
545 X/Open Curses reserves the
547 argument for future use,
548 saying that applications must provide a null pointer for that argument;
549 but see section \*(``EXTENSIONS\*('' below.
551 \fB\%mvcur\fP provides low-level cursor motion.
552 It takes effect immediately
553 (rather than at the next refresh).
554 Unlike the other low-level output functions,
555 which either write to the standard output or pass an output function
557 \fB\%mvcur\fP uses an output file descriptor derived from
558 the output stream parameter of \fB\%newterm\fP(3X).
560 While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
567 because System\ V did this
568 (see section \*(``HISTORY\*('' below).
569 .\" ********************************************************************
570 .SS "Terminal Capability Functions"
573 and \fB\%tigetstr\fP return the value of the capability corresponding to
582 for each capability is given in the table column entitled
584 code in the capabilities section of \fB\%terminfo\fP(5).
586 These functions return special values to denote errors.
588 \fB\%tigetflag\fP returns
593 is not a Boolean capability,
597 if it is canceled or absent from the terminal description.
599 \fB\%tigetnum\fP returns
604 is not a numeric capability,
608 if it is canceled or absent from the terminal description.
610 \fB\%tigetstr\fP returns
615 is not a string capability,
619 if it is canceled or absent from the terminal description.
620 .\" ********************************************************************
621 .SS "Terminal Capability Names"
622 These null-terminated arrays contain
624 the short \fI\%term\%info\fP names (\*(``codes\*(''),
626 the \fItermcap\fP names (\*(``names\*(''),
629 the long \fI\%term\%info\fP names (\*(``fnames\*('')
631 for each of the predefined
637 \fBconst char *boolnames[]\fP, \fB*boolcodes[]\fP, \fB*boolfnames[]\fP
638 \fBconst char *numnames[]\fP, \fB*numcodes[]\fP, \fB*numfnames[]\fP
639 \fBconst char *strnames[]\fP, \fB*strcodes[]\fP, \fB*strfnames[]\fP
642 .\" ********************************************************************
643 .SS "Releasing Memory"
644 Each successful call to \fB\%setupterm\fP allocates memory to hold the
645 terminal description.
647 it sets \fB\%cur_term\fP to point to this memory.
648 If an application calls
651 del_curterm(cur_term);
654 the memory will be freed.
656 The formatting functions \fB\%tparm\fP and \fB\%tiparm\fP extend the
657 storage allocated by \fB\%setupterm\fP as follows.
659 They add the \*(``static\*(''
665 those were shared by all screens.
669 those are allocated per screen.
670 See \fB\%terminfo\fP(5).
672 To improve performance,
674 6.3 caches the result of analyzing
676 strings for their parameter types.
677 That is stored as a binary tree referenced from the
681 The higher-level \fB\%initscr\fP and \fB\%newterm\fP functions use
683 Normally they do not free this memory,
684 but it is possible to do that using the \fB\%delscreen\fP(3X) function.
685 .\" ********************************************************************
687 X/Open Curses defines no failure conditions.
692 fails if its terminal parameter is null.
696 returning the same error codes.
699 fails if the associated call to \fB\%setupterm\fP returns an error.
702 fails if it cannot allocate enough memory,
703 or create the initial windows
708 Other error conditions are documented above.
711 returns a null pointer if the capability would require unexpected
717 (strings where integers are expected,
721 fails if the string parameter is null.
722 It does not detect I/O errors:
723 X/Open Curses states that \fB\%tputs\fP ignores the return value
724 of the output function \fI\%putc\fP.
725 .\" ********************************************************************
732 It was originally implemented based on a draft of X/Open Curses,
734 before other parts of the
736 wide-character API were developed,
737 and unlike the other wide-character functions,
738 is also provided in the non-wide-character configuration.
739 .\" ********************************************************************
741 The functions marked as extensions were designed for
743 and are not found in SVr4
747 or any other previous
760 .\" ********************************************************************
762 \fB\%setterm\fP is not described by X/Open and must be considered
764 All other functions are as described by X/Open.
765 .SS "Compatibility Macros"
766 This implementation provides a few macros for compatibility with systems
768 (see section \*(``HISTORY\*('' below).
782 but except for \fB\%setterm\fP,
786 is mentioned in the manual page.
787 It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP,
788 stating that the call
791 setupterm(\fIterm\fP, 1, (int *)0)
794 provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
795 discouraging the latter for new programs.
797 implements each of these symbols as macros for BSD
801 \fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
802 This is not part of X/Open Curses,
803 but is assumed by some applications.
805 Other implementions may not declare the capability name arrays.
806 Some provide them without declaring them.
807 X/Open Curses does not specify them.
809 Extended terminal capability names,
811 .RB \%\*(`` "@TIC@ \-x" \*('',
812 are not stored in the arrays described here.
813 .SS "Output Buffering"
814 Older versions of \fI\%ncurses\fP assumed that the file descriptor
815 passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses
817 and would write to the corresponding stream.
818 In addition to the limitation that the terminal was left in
819 block-buffered mode on exit
822 it was problematic because
824 did not allow a reliable way to clean up on receiving
827 The current version (ncurses6)
828 uses output buffers managed directly by
830 Some of the low-level functions described in this manual page write
831 to the standard output.
832 They are not signal-safe.
833 The high-level functions in
835 employ alternate versions of these functions using the more reliable
837 .SS "Function Prototypes"
838 The X/Open Curses prototypes are based on the SVr4
841 which were defined at the same time the C language was first
842 standardized in the late 1980s.
846 less effectively than a later design might,
847 sometimes applying it needlessly to values that are already constant,
848 and in most cases overlooking parameters that normally would use
851 .IR \%const -qualified
852 parameters to functions that do not declare them
854 may prevent the program from compiling.
856 \*(``writable strings\*('' are an obsolescent feature.
859 this implementation can be configured to change the function prototypes
865 ABI 6 enables this feature by default.
867 X/Open Curses prototypes \fB\%tparm\fP with a fixed number of
869 rather than a variable argument list.
871 This implementation uses a variable argument list,
872 but can be configured to use the fixed-parameter list.
873 Portable applications should provide nine parameters after the format;
874 zeroes are fine for this purpose.
876 In response to review comments by Thomas E. Dickey,
877 X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009.
879 While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
880 the older form is only available as a build-time configuration option.
881 If not specially configured,
882 \fB\%tparm\fP is the same as \fB\%tiparm\fP.
884 Both forms of \fB\%tparm\fP have drawbacks:
886 Most of the calls to \fB\%tparm\fP use only one or two parameters.
887 Passing nine on each call is awkward.
891 for the numeric parameter type is a workaround to make the parameter use
892 the same amount of stack as a pointer.
893 That approach dates back to the mid-1980s,
894 before C was standardized.
897 (and pointers are not required to fit in a
900 Providing the right number of parameters for a variadic function
901 such as \fB\%tiparm\fP can be a problem,
902 in particular for string parameters.
906 capabilities use string parameters
908 the ones used for programmable function keys).
910 The \fI\%ncurses\fP library checks usage of these capabilities,
911 and returns an error if the capability mishandles string parameters.
912 But it cannot check if a calling program provides strings in the right
913 places for the \fB\%tparm\fP calls.
915 The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
917 so that it calls \fB\%tparm\fP correctly.
918 .SS "Special \fITERM\fP treatment"
919 If configured to use the terminal driver,
920 .\" XXX: as opposed to the Unix terminal driver, termio(s)?
921 as with the MinGW port,
923 \fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
924 special value \*(``unknown\*(''.
928 uses the special value \*(``dumb\*(''.
930 The difference between the two is that the former uses the
935 while the latter does not.
936 A generic terminal is unsuitable for full-screen applications.
938 \fB\%setupterm\fP allows explicit use of the
939 the windows console driver by checking if \fB$TERM\fP is set to
940 \*(``#win32con\*('' or an abbreviation of that string.
941 .SS "Other Portability Issues"
943 \fB\%set_curterm\fP returns an
948 We have chosen to implement the X/Open Curses semantics.
951 the third argument of \fB\%tputs\fP has the type
952 .RB \*(`` "int (*putc)(char)" \*(''.
954 At least one implementation of X/Open Curses (Solaris) returns a value
960 It instead returns the length of the string,
961 and does no error checking.
963 X/Open Curses notes that after calling \fB\%mvcur\fP,
966 state may not match the actual terminal state,
967 and that an application should touch and refresh the window before
975 implement \fB\%mvcur\fP using the
977 data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
978 So though it is documented as a
981 \fB\%mvcur\fP is really a
983 function that is not well specified.
985 X/Open Curses states that the old location must be given for
986 \fB\%mvcur\fP to accommodate terminals that lack absolute cursor
988 .\" X/Open Curses Issue 7, p. 161
990 allows the caller to use \-1 for either or both old coordinates.
993 that the old location is unknown,
994 and that it must use only absolute motion,
999 rather than the least costly combination of absolute and relative
1001 .\" ********************************************************************
1003 SVr2 (1984) introduced the
1006 Its programming manual mentioned the following low-level functions.
1011 Function Description
1013 fixterm restore terminal to \*(``in \fIcurses\fP\*('' state
1014 gettmode establish current terminal modes
1015 mvcur low level cursor motion
1016 putp use \fBtputs\fP to send characters via \fIputchar\fP
1017 resetterm set terminal modes to \*(``out of \fIcurses\fP\*(''\
1019 resetty reset terminal flags to stored value
1020 saveterm save current modes as \*(``in \fIcurses\fP\*('' state
1021 savetty store current terminal flags
1022 setterm establish terminal with given type
1023 setupterm establish terminal with given type
1024 tparm interpolate parameters into string capability
1025 tputs apply padding information to a string
1026 vidattr like \fBvidputs\fP, but output through \fIputchar\fP
1028 write string to terminal, applying specified attributes
1032 The programming manual also mentioned
1033 functions provided for
1036 (commenting that they \*(``may go away at a later date\*('').
1041 Function Description
1043 tgetent look up \fItermcap\fP entry for given \fIname\fP
1044 tgetflag get Boolean entry for given \fIid\fP
1045 tgetnum get numeric entry for given \fIid\fP
1046 tgetstr get string entry for given \fIid\fP
1047 tgoto apply parameters to given capability
1049 write characters via a function parameter, applying padding
1055 programs obtained capability values from the
1057 structure initialized by \fB\%setupterm\fP.
1059 SVr3 (1987) extended
1061 by adding functions to retrieve capability values
1065 and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
1070 Function Description
1072 tigetflag get Boolean entry for given \fIid\fP
1073 tigetnum get numeric entry for given \fIid\fP
1074 tigetstr get string entry for given \fIid\fP
1077 SVr3 also replaced several of the SVr2
1079 functions that had no counterpart in the
1082 documenting them as obsolete.
1087 Function Replaced by
1090 fixterm reset_prog_mode
1093 resetterm reset_shell_mode
1094 saveterm def_prog_mode
1098 SVr3 kept the \fB\%mvcur\fP,
1100 and \fB\%vidputs\fP functions,
1101 along with \fB\%putp\fP,
1104 The latter were needed to support padding,
1105 and to handle capabilities accessed by functions such as \fB\%vidattr\fP
1106 (which used more than the two parameters supported by \fB\%tgoto\fP).
1108 SVr3 introduced the functions for switching between terminal
1111 \fB\%set_curterm\fP.
1112 Some changes reflected incremental improvements to the SVr2 library.
1116 type definition was introduced in SVr3.01,
1119 structure provided in SVr2.
1121 Various global variables such as \fB\%boolnames\fP were mentioned
1122 in the programming manual at this point,
1123 though the variables had been provided in SVr2.
1125 SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
1127 Other low-level functions are declared in the
1129 header files of Unix systems,
1130 but none are documented.
1131 Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
1135 \fB\%curs_initscr\fP(3X),
1136 \fB\%curs_kernel\fP(3X),
1137 \fB\%curs_memleaks\fP(3X),
1138 \fB\%curs_termcap\fP(3X),
1139 \fB\%curs_variables\fP(3X),
1141 \fB\%term_variables\fP(3X),