1<!-- 2 * t 3 **************************************************************************** 4 * Copyright 2018-2023,2024 Thomas E. Dickey * 5 * Copyright 1998-2016,2017 Free Software Foundation, Inc. * 6 * * 7 * Permission is hereby granted, free of charge, to any person obtaining a * 8 * copy of this software and associated documentation files (the * 9 * "Software"), to deal in the Software without restriction, including * 10 * without limitation the rights to use, copy, modify, merge, publish, * 11 * distribute, distribute with modifications, sublicense, and/or sell * 12 * copies of the Software, and to permit persons to whom the Software is * 13 * furnished to do so, subject to the following conditions: * 14 * * 15 * The above copyright notice and this permission notice shall be included * 16 * in all copies or substantial portions of the Software. * 17 * * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 25 * * 26 * Except as contained in this notice, the name(s) of the above copyright * 27 * holders shall not be used in advertising or otherwise to promote the * 28 * sale, use or other dealings in this Software without prior written * 29 * authorization. * 30 **************************************************************************** 31 * @Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp @ 32--> 33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 34<HTML> 35<HEAD> 36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> 38<TITLE>curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> 39<link rel="author" href="mailto:bug-ncurses@gnu.org"> 40 41</HEAD> 42<BODY> 43<H1 class="no-header">curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</H1> 44<PRE> 45<STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> 46 47 48 49 50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 51 <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>, 52 <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tiparm_s</STRONG>, <STRONG>tiscan_s</STRONG>, <STRONG>tparm</STRONG>, 53 <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <EM>curses</EM> interfaces to 54 <EM>terminfo</EM> database 55 56 57</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 58 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> 59 <STRONG>#include</STRONG> <STRONG><term.h></STRONG> 60 61 <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG> 62 63 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG> 64 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG> 65 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG> 66 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG> 67 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG> 68 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG> 69 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG> 70 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG> 71 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG> 72 73 <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> 74 <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG> 75 <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG> 76 <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> 77 78 <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> 79 <EM>/*</EM> <EM>or</EM> <EM>*/</EM> 80 <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG> 81 82 <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> 83 <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> 84 85 <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> 86 <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> 87 <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> 88 <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG> 89 90 <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> 91 92 <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> 93 <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> 94 <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> 95 96 <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> 97 98 <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> 99 <STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> 100 <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> 101 102 <EM>/*</EM> <EM>deprecated</EM> <EM>*/</EM> 103 <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG> 104 105 106</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 107 These low-level functions must be called by programs that deal directly 108 with the <EM>terminfo</EM> database to handle certain terminal capabilities, 109 such as programming function keys. For all other functionality, <EM>curses</EM> 110 functions are more suitable and their use is recommended. 111 112 None of these functions use (or are aware of) multibyte character 113 strings such as UTF-8. 114 115 <STRONG>o</STRONG> Capability names and codes use the POSIX portable character set. 116 117 <STRONG>o</STRONG> Capability string values have no associated encoding; they are 118 strings of 8-bit characters. 119 120 121</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> 122 Initially, <STRONG>setupterm</STRONG> should be called. The high-level <EM>curses</EM> functions 123 <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of 124 terminal-dependent variables listed in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>. 125 126 Applications can use the terminal capabilities either directly (via 127 header definitions), or by special functions. The header files 128 <EM>curses.h</EM> and <EM>term.h</EM> should be included (in that order) to get the 129 definitions for these strings, numbers, and flags. 130 131 The <EM>terminfo</EM> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG> 132 as follows. 133 134 <STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> 135 specified in <EM>terminfo</EM> are used. 136 137 <STRONG>o</STRONG> Otherwise, if the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> exist, 138 their values are used. If these environment variables do not exist 139 and the program is running in a window, the current window size is 140 used. Otherwise, if the environment variables do not exist, the 141 values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <EM>terminfo</EM> database are 142 used. 143 144 Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate 145 them. All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>) should be 146 sent to the terminal device with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> 147 to restore the terminal modes before exiting; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>. 148 149 Programs that use cursor addressing should 150 151 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> upon startup and 152 153 <STRONG>o</STRONG> output <STRONG>exit_ca_mode</STRONG> before exiting. 154 155 Programs that execute shell subprocesses should 156 157 <STRONG>o</STRONG> call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the shell is 158 called and 159 160 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from 161 the shell. 162 163 <STRONG>setupterm</STRONG> reads in the <EM>terminfo</EM> database, initializing the <EM>terminfo</EM> 164 structures, but does not set up the output virtualization structures 165 used by <EM>curses</EM>. Its parameters follow. 166 167 <EM>term</EM> is the terminal type, a character string. If <EM>term</EM> is null, the 168 environment variable <EM>TERM</EM> is read. 169 170 <EM>filedes</EM> 171 is the file descriptor used for getting and setting terminal 172 I/O modes. 173 174 Higher-level applications use <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> to initialize the 175 terminal, passing an output <EM>stream</EM> rather than a <EM>descriptor</EM>. 176 In <EM>curses</EM>, the two are the same because <STRONG>newterm</STRONG> calls 177 <STRONG>setupterm</STRONG>, passing the file descriptor derived from its output 178 stream parameter. 179 180 <EM>errret</EM> 181 points to an optional location where an error status can be 182 returned to the caller. If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG> 183 returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a status value in the integer 184 pointed to by <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with 185 status of <STRONG>1</STRONG> in <EM>errret</EM> is normal. 186 187 If <STRONG>ERR</STRONG> is returned, examine <EM>errret:</EM> 188 189 <STRONG>1</STRONG> means that the terminal is hardcopy, and cannot be used 190 for <EM>curses</EM> applications. 191 192 <STRONG>setupterm</STRONG> determines if the entry is a hardcopy type by 193 checking the <STRONG>hardcopy</STRONG> (<STRONG>hc</STRONG>) capability. 194 195 <STRONG>0</STRONG> means that the terminal could not be found, or that it is 196 a generic type, having too little information for <EM>curses</EM> 197 applications to run. 198 199 <STRONG>setupterm</STRONG> determines if the entry is a generic type by 200 checking the <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) capability. 201 202 <STRONG>-1</STRONG> means that the <EM>terminfo</EM> database could not be found. 203 204 If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> reports an error message upon 205 finding an error and exits. Thus, the simplest call is: 206 207 setupterm((char *)0, 1, (int *)0); 208 209 which uses all the defaults and sends the output to <STRONG>stdout</STRONG>. 210 211 212</PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE> 213 <STRONG>setupterm</STRONG> stores its information about the terminal in a <EM>TERMINAL</EM> 214 structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it detects an 215 error, or decides that the terminal is unsuitable (hardcopy or 216 generic), it discards this information, making it not available to 217 applications. 218 219 If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type, it will 220 reuse the information. It maintains only one copy of a given 221 terminal's capabilities in memory. If it is called for different 222 terminal types, <STRONG>setupterm</STRONG> allocates new storage for each set of 223 terminal capabilities. 224 225 <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the <EM>terminfo</EM> 226 Boolean, numeric, and string variables use the values from <EM>nterm</EM>. It 227 returns the old value of <STRONG>cur_term</STRONG>. 228 229 <STRONG>del_curterm</STRONG> frees the space pointed to by <EM>oterm</EM> and makes it available 230 for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, references to any 231 of the <EM>terminfo</EM> Boolean, numeric, and string variables thereafter may 232 refer to invalid memory locations until another <STRONG>setupterm</STRONG> has been 233 called. 234 235 <STRONG>restartterm</STRONG> is similar to <STRONG>setupterm</STRONG> and <STRONG>initscr</STRONG>, except that it is 236 called after restoring memory to a previous state (for example, when 237 reloading a game saved as a core image dump). <STRONG>restartterm</STRONG> assumes that 238 the windows and the input and output options are the same as when 239 memory was saved, but the terminal type and baud rate may be different. 240 Accordingly, <STRONG>restartterm</STRONG> saves various terminal state bits, calls 241 <STRONG>setupterm</STRONG>, and then restores the bits. 242 243 244</PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE> 245 <STRONG>tparm</STRONG> instantiates the string <EM>str</EM> with parameters <EM>pi</EM>. A pointer is 246 returned to the result of <EM>str</EM> with the parameters applied. Application 247 developers should keep in mind these quirks of the interface: 248 249 <STRONG>o</STRONG> Although <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the 250 prototype expects <EM>long</EM> (integer) values. 251 252 <STRONG>o</STRONG> Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal 253 capabilities require no more than one or two parameters. 254 255 <STRONG>o</STRONG> Padding information is ignored by <STRONG>tparm</STRONG>; it is interpreted by 256 <STRONG>tputs</STRONG>. 257 258 <STRONG>o</STRONG> The capability string is null-terminated. Use "\200" where an 259 ASCII NUL is needed in the output. 260 261 <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM>stdarg.h</EM> rather than a 262 fixed-parameter list. Its numeric parameters are <EM>int</EM>s rather than 263 <EM>long</EM>s. 264 265 Both <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that the application passes parameters 266 consistent with the terminal description. Two extensions are provided 267 as alternatives to deal with untrusted data. 268 269 <STRONG>o</STRONG> <STRONG>tiparm_s</STRONG> is an extension which is a safer formatting function than 270 <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>, because it allows the developer to tell the <EM>curses</EM> 271 library how many parameters to expect in the parameter list, and 272 which may be string parameters. 273 274 The <EM>mask</EM> parameter has one bit set for each of the parameters (up 275 to 9) passed as <EM>char</EM> pointers rather than numbers. 276 277 <STRONG>o</STRONG> The extension <STRONG>tiscan_s</STRONG> allows the application to inspect a 278 formatting capability to see what the <EM>curses</EM> library would assume. 279 280 281</PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE> 282 String capabilities can contain padding information, a time delay 283 (accommodating performance limitations of hardware terminals) expressed 284 as <STRONG>$<</STRONG><EM>n</EM><STRONG>></STRONG>, where <EM>n</EM> is a nonnegative integral count of milliseconds. If <EM>n</EM> 285 exceeds 30,000 (thirty seconds), it is capped at that value. 286 287 <STRONG>tputs</STRONG> interprets time-delay information in the string <EM>str</EM> and outputs 288 it, executing the delays: 289 290 <STRONG>o</STRONG> The <EM>str</EM> parameter must be a <EM>terminfo</EM> string variable or the return 291 value of <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>. 292 293 The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface, 294 which happens to share these function names with the <EM>terminfo</EM> API. 295 296 <STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or <STRONG>1</STRONG> if not applicable. 297 298 <STRONG>o</STRONG> <EM>putc</EM> is a <EM>putchar</EM>-like function to which the characters are passed, 299 one at a time. 300 301 If <STRONG>tputs</STRONG> processes a time-delay, it uses the <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG> 302 function, routing any resulting padding characters through this 303 function. 304 305 <STRONG>putp</STRONG> calls "<STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>". The output of <STRONG>putp</STRONG> always goes to 306 <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>. 307 308 <STRONG>vidputs</STRONG> displays the string on the terminal in the video attribute mode 309 <EM>attrs</EM>, which is any combination of the attributes listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. 310 The characters are passed to the <EM>putchar</EM>-like function <EM>putc</EM>. 311 312 <STRONG>vidattr</STRONG> is like <STRONG>vidputs</STRONG>, except that it outputs through <STRONG>putchar(3)</STRONG>. 313 314 <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively. 315 They use multiple parameters to represent the character attributes and 316 color; namely, 317 318 <STRONG>o</STRONG> <EM>attrs</EM>, of type <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, for the attributes and 319 320 <STRONG>o</STRONG> <EM>pair</EM>, of type <EM>short</EM>, for the color pair number. 321 322 Use the attribute constants prefixed with "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and 323 <STRONG>vid_puts</STRONG>. 324 325 X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that 326 applications must provide a null pointer for that argument; but see 327 section "EXTENSIONS" below. 328 329 <STRONG>mvcur</STRONG> provides low-level cursor motion. It takes effect immediately 330 (rather than at the next refresh). Unlike the other low-level output 331 functions, which either write to the standard output or pass an output 332 function parameter, <STRONG>mvcur</STRONG> uses an output file descriptor derived from 333 the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. 334 335 While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions that do not use high-level 336 <EM>curses</EM> state, <EM>ncurses</EM> declares them in <EM>curses.h</EM> because System V did 337 this (see section "HISTORY" below). 338 339 340</PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE> 341 <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, and <STRONG>tigetstr</STRONG> return the value of the capability 342 corresponding to the <EM>terminfo</EM> <EM>cap-code</EM>, such as <STRONG>xenl</STRONG>, passed to them. 343 The <EM>cap-code</EM> for each capability is given in the table column entitled 344 <EM>cap-code</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. 345 346 These functions return special values to denote errors. 347 348 <STRONG>tigetflag</STRONG> returns 349 350 <STRONG>-1</STRONG> if <EM>cap-code</EM> is not a Boolean capability, or 351 352 <STRONG>0</STRONG> if it is canceled or absent from the terminal description. 353 354 <STRONG>tigetnum</STRONG> returns 355 356 <STRONG>-2</STRONG> if <EM>cap-code</EM> is not a numeric capability, or 357 358 <STRONG>-1</STRONG> if it is canceled or absent from the terminal description. 359 360 <STRONG>tigetstr</STRONG> returns 361 362 <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> 363 if <EM>cap-code</EM> is not a string capability, or 364 365 <STRONG>0</STRONG> if it is canceled or absent from the terminal description. 366 367 368</PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE> 369 These null-terminated arrays contain 370 371 <STRONG>o</STRONG> the short <EM>terminfo</EM> names ("codes"), 372 373 <STRONG>o</STRONG> the <EM>termcap</EM> names ("names"), and 374 375 <STRONG>o</STRONG> the long <EM>terminfo</EM> names ("fnames") 376 377 for each of the predefined <EM>terminfo</EM> variables: 378 379 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG> 380 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG> 381 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG> 382 383 384</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE> 385 Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal 386 description. As a side effect, it sets <STRONG>cur_term</STRONG> to point to this 387 memory. If an application calls 388 389 del_curterm(cur_term); 390 391 the memory will be freed. 392 393 The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated 394 by <STRONG>setupterm</STRONG> as follows. 395 396 <STRONG>o</STRONG> They add the "static" <EM>terminfo</EM> variables [a-z]. Before <EM>ncurses</EM> 397 6.3, those were shared by all screens. With <EM>ncurses</EM> 6.3, those are 398 allocated per screen. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. 399 400 <STRONG>o</STRONG> To improve performance, <EM>ncurses</EM> 6.3 caches the result of analyzing 401 <EM>terminfo</EM> strings for their parameter types. That is stored as a 402 binary tree referenced from the <EM>TERMINAL</EM> structure. 403 404 The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>. Normally 405 they do not free this memory, but it is possible to do that using the 406 <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function. 407 408 409</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> 410 X/Open Curses defines no failure conditions. In <EM>ncurses</EM>, 411 412 <STRONG>del_curtem</STRONG> 413 fails if its terminal parameter is null. 414 415 <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error codes. 416 417 <STRONG>restartterm</STRONG> 418 fails if the associated call to <STRONG>setupterm</STRONG> returns an error. 419 420 <STRONG>setupterm</STRONG> 421 fails if it cannot allocate enough memory, or create the initial 422 windows (<STRONG>stdscr</STRONG>, <STRONG>curscr</STRONG>, and <STRONG>newscr</STRONG>) Other error conditions are 423 documented above. 424 425 <STRONG>tparm</STRONG> 426 returns a null pointer if the capability would require unexpected 427 parameters; that is, too many, too few, or incorrect types 428 (strings where integers are expected, or vice versa). 429 430 <STRONG>tputs</STRONG> 431 fails if the string parameter is null. It does not detect I/O 432 errors: X/Open Curses states that <STRONG>tputs</STRONG> ignores the return value 433 of the output function <EM>putc</EM>. 434 435 436</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> 437 The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> is a special case. It was originally 438 implemented based on a draft of X/Open Curses, as a macro, before other 439 parts of the <EM>ncurses</EM> wide-character API were developed, and unlike the 440 other wide-character functions, is also provided in the non-wide- 441 character configuration. 442 443 444</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> 445 The functions marked as extensions were designed for <EM>ncurses</EM>, and are 446 not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> 447 implementation. 448 449 <EM>ncurses</EM> allows <EM>opts</EM> to be a pointer to <EM>int</EM>, which overrides the <EM>pair</EM> 450 (<EM>short</EM>) argument. 451 452 453</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 454 <STRONG>setterm</STRONG> is not described by X/Open and must be considered non-portable. 455 All other functions are as described by X/Open. 456 457 458</PRE><H3><a name="h3-Compatibility-Macros">Compatibility Macros</a></H3><PRE> 459 This implementation provides a few macros for compatibility with 460 systems before SVr4 (see section "HISTORY" below). They include 461 <STRONG>Bcrmode</STRONG>, <STRONG>Bfixterm</STRONG>, <STRONG>Bgettmode</STRONG>, <STRONG>Bnocrmode</STRONG>, <STRONG>Bresetterm</STRONG>, <STRONG>Bsaveterm</STRONG>, and 462 <STRONG>Bsetterm</STRONG>. 463 464 In SVr4, these are found in <EM>curses.h</EM>, but except for <STRONG>setterm</STRONG>, are 465 likewise macros. The one function, <STRONG>setterm</STRONG>, is mentioned in the manual 466 page. It further notes that <STRONG>setterm</STRONG> was replaced by <STRONG>setupterm</STRONG>, stating 467 that the call 468 setupterm(<EM>term</EM>, 1, (int *)0) 469 provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, discouraging the 470 latter for new programs. <EM>ncurses</EM> implements each of these symbols as 471 macros for BSD <EM>curses</EM> compatibility. 472 473 474</PRE><H3><a name="h3-Legacy-Data">Legacy Data</a></H3><PRE> 475 <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not 476 part of X/Open Curses, but is assumed by some applications. 477 478 Other implementions may not declare the capability name arrays. Some 479 provide them without declaring them. X/Open Curses does not specify 480 them. 481 482 Extended terminal capability names, as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not 483 stored in the arrays described here. 484 485 486</PRE><H3><a name="h3-Output-Buffering">Output Buffering</a></H3><PRE> 487 Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to 488 <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to 489 the corresponding stream. In addition to the limitation that the 490 terminal was left in block-buffered mode on exit (like System V 491 <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not allow a reliable 492 way to clean up on receiving <STRONG>SIGTSTP</STRONG>. 493 494 The current version (ncurses6) uses output buffers managed directly by 495 <EM>ncurses</EM>. Some of the low-level functions described in this manual page 496 write to the standard output. They are not signal-safe. The high- 497 level functions in <EM>ncurses</EM> employ alternate versions of these functions 498 using the more reliable buffering scheme. 499 500 501</PRE><H3><a name="h3-Function-Prototypes">Function Prototypes</a></H3><PRE> 502 The X/Open Curses prototypes are based on the SVr4 <EM>curses</EM> header 503 declarations, which were defined at the same time the C language was 504 first standardized in the late 1980s. 505 506 <STRONG>o</STRONG> X/Open Curses uses <EM>const</EM> less effectively than a later design 507 might, sometimes applying it needlessly to values that are already 508 constant, and in most cases overlooking parameters that normally 509 would use <EM>const</EM>. Passing <EM>const</EM>-qualified parameters to functions 510 that do not declare them <EM>const</EM> may prevent the program from 511 compiling. On the other hand, "writable strings" are an 512 obsolescent feature. 513 514 As an extension, this implementation can be configured to change 515 the function prototypes to use the <EM>const</EM> keyword. The <EM>ncurses</EM> ABI 516 6 enables this feature by default. 517 518 <STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of parameters, 519 rather than a variable argument list. 520 521 This implementation uses a variable argument list, but can be 522 configured to use the fixed-parameter list. Portable applications 523 should provide nine parameters after the format; zeroes are fine 524 for this purpose. 525 526 In response to review comments by Thomas E. Dickey, X/Open Curses 527 Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009. 528 529 While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is only 530 available as a build-time configuration option. If not specially 531 configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>. 532 533 Both forms of <STRONG>tparm</STRONG> have drawbacks: 534 535 <STRONG>o</STRONG> Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters. Passing 536 nine on each call is awkward. 537 538 Using <EM>long</EM> for the numeric parameter type is a workaround to make 539 the parameter use the same amount of stack as a pointer. That 540 approach dates back to the mid-1980s, before C was standardized. 541 Since then, there is a standard (and pointers are not required to 542 fit in a <EM>long</EM>). 543 544 <STRONG>o</STRONG> Providing the right number of parameters for a variadic function 545 such as <STRONG>tiparm</STRONG> can be a problem, in particular for string 546 parameters. However, only a few <EM>terminfo</EM> capabilities use string 547 parameters (for instance, the ones used for programmable function 548 keys). 549 550 The <EM>ncurses</EM> library checks usage of these capabilities, and returns 551 an error if the capability mishandles string parameters. But it 552 cannot check if a calling program provides strings in the right 553 places for the <STRONG>tparm</STRONG> calls. 554 555 The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a 556 table, so that it calls <STRONG>tparm</STRONG> correctly. 557 558 <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG> 559 If configured to use the terminal driver, as with the MinGW port, 560 561 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty <EM>TERM</EM> variable as the special 562 value "unknown". 563 564 SVr4 <EM>curses</EM> uses the special value "dumb". 565 566 The difference between the two is that the former uses the 567 <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) <EM>terminfo</EM> capability, while the latter does not. 568 A generic terminal is unsuitable for full-screen applications. 569 570 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver by 571 checking if <STRONG>$TERM</STRONG> is set to "#win32con" or an abbreviation of that 572 string. 573 574 575</PRE><H3><a name="h3-Other-Portability-Issues">Other Portability Issues</a></H3><PRE> 576 In SVr4, <STRONG>set_curterm</STRONG> returns an <EM>int</EM>, <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to 577 implement the X/Open Curses semantics. 578 579 In SVr4, the third argument of <STRONG>tputs</STRONG> has the type "<STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>". 580 581 At least one implementation of X/Open Curses (Solaris) returns a value 582 other than <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. It instead returns the length of the 583 string, and does no error checking. 584 585 X/Open Curses notes that after calling <STRONG>mvcur</STRONG>, the <EM>curses</EM> state may not 586 match the actual terminal state, and that an application should touch 587 and refresh the window before resuming normal <EM>curses</EM> calls. Both 588 <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data allocated 589 in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as a <EM>terminfo</EM> 590 function, <STRONG>mvcur</STRONG> is really a <EM>curses</EM> function that is not well specified. 591 592 X/Open Curses states that the old location must be given for <STRONG>mvcur</STRONG> to 593 accommodate terminals that lack absolute cursor positioning. <EM>ncurses</EM> 594 allows the caller to use -1 for either or both old coordinates. The -1 595 tells <EM>ncurses</EM> that the old location is unknown, and that it must use 596 only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability, 597 rather than the least costly combination of absolute and relative 598 motion. 599 600 601</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> 602 SVr2 (1984) introduced the <EM>terminfo</EM> feature. Its programming manual 603 mentioned the following low-level functions. 604 605 <STRONG>Function</STRONG> <STRONG>Description</STRONG> 606 ------------------------------------------------------------------------ 607 <STRONG>fixterm</STRONG> restore terminal to "in <EM>curses</EM>" state 608 <STRONG>gettmode</STRONG> establish current terminal modes 609 <STRONG>mvcur</STRONG> low level cursor motion 610 <STRONG>putp</STRONG> use <STRONG>tputs</STRONG> to send characters via <EM>putchar</EM> 611 <STRONG>resetterm</STRONG> set terminal modes to "out of <EM>curses</EM>" state 612 613 <STRONG>resetty</STRONG> reset terminal flags to stored value 614 <STRONG>saveterm</STRONG> save current modes as "in <EM>curses</EM>" state 615 <STRONG>savetty</STRONG> store current terminal flags 616 <STRONG>setterm</STRONG> establish terminal with given type 617 <STRONG>setupterm</STRONG> establish terminal with given type 618 <STRONG>tparm</STRONG> interpolate parameters into string capability 619 <STRONG>tputs</STRONG> apply padding information to a string 620 <STRONG>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but output through <EM>putchar</EM> 621 <STRONG>vidputs</STRONG> write string to terminal, applying specified attributes 622 623 The programming manual also mentioned functions provided for <EM>termcap</EM> 624 compatibility (commenting that they "may go away at a later date"). 625 626 <STRONG>Function</STRONG> <STRONG>Description</STRONG> 627 ------------------------------------------------------------------------ 628 <STRONG>tgetent</STRONG> look up <EM>termcap</EM> entry for given <EM>name</EM> 629 <STRONG>tgetflag</STRONG> get Boolean entry for given <EM>id</EM> 630 <STRONG>tgetnum</STRONG> get numeric entry for given <EM>id</EM> 631 <STRONG>tgetstr</STRONG> get string entry for given <EM>id</EM> 632 <STRONG>tgoto</STRONG> apply parameters to given capability 633 <STRONG>tputs</STRONG> write characters via a function parameter, applying padding 634 635 Early <EM>terminfo</EM> programs obtained capability values from the <EM>TERMINAL</EM> 636 structure initialized by <STRONG>setupterm</STRONG>. 637 638 SVr3 (1987) extended <EM>terminfo</EM> by adding functions to retrieve 639 capability values (like the <EM>termcap</EM> interface), and reusing <STRONG>tgoto</STRONG> and 640 <STRONG>tputs</STRONG>. 641 642 <STRONG>Function</STRONG> <STRONG>Description</STRONG> 643 ------------------------------------------------------------------------ 644 <STRONG>tigetflag</STRONG> get Boolean entry for given <EM>id</EM> 645 <STRONG>tigetnum</STRONG> get numeric entry for given <EM>id</EM> 646 <STRONG>tigetstr</STRONG> get string entry for given <EM>id</EM> 647 648 SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions that had no 649 counterpart in the <EM>termcap</EM> interface, documenting them as obsolete. 650 651 <STRONG>Function</STRONG> <STRONG>Replaced</STRONG> <STRONG>by</STRONG> 652 ------------------------------------------------------------------------ 653 crmode cbreak 654 fixterm reset_prog_mode 655 gettmode <EM>n/a</EM> 656 nocrmode nocbreak 657 resetterm reset_shell_mode 658 saveterm def_prog_mode 659 setterm setupterm 660 661 SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG>, and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>, 662 <STRONG>tparm</STRONG>, and <STRONG>tputs</STRONG>. The latter were needed to support padding, and to 663 handle capabilities accessed by functions such as <STRONG>vidattr</STRONG> (which used 664 more than the two parameters supported by <STRONG>tgoto</STRONG>). 665 666 SVr3 introduced the functions for switching between terminal 667 descriptions; for example, <STRONG>set_curterm</STRONG>. Some changes reflected 668 incremental improvements to the SVr2 library. 669 670 <STRONG>o</STRONG> The <EM>TERMINAL</EM> type definition was introduced in SVr3.01, for the 671 <EM>term</EM> structure provided in SVr2. 672 673 <STRONG>o</STRONG> Various global variables such as <STRONG>boolnames</STRONG> were mentioned in the 674 programming manual at this point, though the variables had been 675 provided in SVr2. 676 677 SVr4 (1989) added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions. 678 679 Other low-level functions are declared in the <EM>curses</EM> header files of 680 Unix systems, but none are documented. Those noted as "obsolete" by 681 SVr3 remained in use by System V's <STRONG>vi(1)</STRONG> editor. 682 683 684</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 685 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>, 686 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, 687 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> 688 689 690 691ncurses 6.5 2024-04-13 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> 692</PRE> 693<div class="nav"> 694<ul> 695<li><a href="#h2-NAME">NAME</a></li> 696<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 697<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> 698<ul> 699<li><a href="#h3-Initialization">Initialization</a></li> 700<li><a href="#h3-The-Terminal-State">The Terminal State</a></li> 701<li><a href="#h3-Formatting-Output">Formatting Output</a></li> 702<li><a href="#h3-Output-Functions">Output Functions</a></li> 703<li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li> 704<li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li> 705<li><a href="#h3-Releasing-Memory">Releasing Memory</a></li> 706</ul> 707</li> 708<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> 709<li><a href="#h2-NOTES">NOTES</a></li> 710<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> 711<li><a href="#h2-PORTABILITY">PORTABILITY</a> 712<ul> 713<li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li> 714<li><a href="#h3-Legacy-Data">Legacy Data</a></li> 715<li><a href="#h3-Output-Buffering">Output Buffering</a></li> 716<li><a href="#h3-Function-Prototypes">Function Prototypes</a></li> 717<li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li> 718</ul> 719</li> 720<li><a href="#h2-HISTORY">HISTORY</a></li> 721<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 722</ul> 723</div> 724</BODY> 725</HTML> 726