Debian Codegraph @

doc/html/man/curs_terminfo.3x.html

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