2 ****************************************************************************
3 * Copyright 2018,2020 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 ****************************************************************************
30 * @Id: curs_terminfo.3x,v 1.65 2020/09/29 20:07:42 Rueben.Thomas Exp @
31 * ***************************************************************************
32 * ***************************************************************************
33 * ***************************************************************************
34 * ***************************************************************************
35 * ***************************************************************************
37 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
40 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
41 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
42 <TITLE>curs_terminfo 3x</TITLE>
43 <link rel="author" href="mailto:bug-ncurses@gnu.org">
44 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
47 <H1 class="no-header">curs_terminfo 3x</H1>
49 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
54 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
55 <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>,
56 <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>,
57 <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database
60 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
61 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
62 <STRONG>#include</STRONG> <STRONG><term.h></STRONG>
64 <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
66 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG>
67 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG>
68 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG>
69 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG>
70 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG>
71 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG>
72 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG>
73 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG>
74 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>
76 <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>
77 <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
78 <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
79 <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
80 <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>
82 <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
83 <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>
84 <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
86 <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
87 <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
88 <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>
89 <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>
91 <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>, int <EM>newcol</EM><STRONG>);</STRONG>
93 <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
94 <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
95 <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
97 <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
100 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
101 These low-level routines must be called by programs that have to deal
102 directly with the <STRONG>terminfo</STRONG> database to handle certain terminal capabil-
103 ities, such as programming function keys. For all other functionality,
104 <STRONG>curses</STRONG> routines are more suitable and their use is recommended.
107 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
108 Initially, <STRONG>setupterm</STRONG> should be called. The high-level curses functions
109 <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of
110 terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
112 Applications can use the terminal capabilities either directly (via
113 header definitions), or by special functions. The header files <STRONG>curs-</STRONG>
114 <STRONG>es.h</STRONG> and <STRONG>term.h</STRONG> should be included (in this order) to get the defini-
115 tions for these strings, numbers, and flags.
117 The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
120 <STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>
121 specified in <STRONG>terminfo</STRONG> are used.
123 <STRONG>o</STRONG> Otherwise, if the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist,
124 their values are used. If these environment variables do not exist
125 and the program is running in a window, the current window size is
126 used. Otherwise, if the environment variables do not exist, the
127 values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
130 Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate
131 them. All <STRONG>terminfo</STRONG> strings (including the output of <STRONG>tparm</STRONG>) should be
132 printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> to restore the tty
133 modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
135 Programs which use cursor addressing should
137 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> upon startup and
139 <STRONG>o</STRONG> output <STRONG>exit_ca_mode</STRONG> before exiting.
141 Programs which execute shell subprocesses should
143 <STRONG>o</STRONG> call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the shell is
146 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from
149 The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing the
150 <STRONG>terminfo</STRONG> structures, but does not set up the output virtualization
151 structures used by <STRONG>curses</STRONG>. These are its parameters:
153 <EM>term</EM> is the terminal type, a character string. If <EM>term</EM> is null, the
154 environment variable <STRONG>TERM</STRONG> is used.
157 is the file descriptor used for all output.
160 points to an optional location where an error status can be re-
161 turned to the caller. If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
162 returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a status value in the integer
163 pointed to by <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with sta-
164 tus of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
166 If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
168 <STRONG>1</STRONG> means that the terminal is hardcopy, cannot be used for
171 <STRONG>setupterm</STRONG> determines if the entry is a hardcopy type by
172 checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capability.
174 <STRONG>0</STRONG> means that the terminal could not be found, or that it is
175 a generic type, having too little information for curses
178 <STRONG>setupterm</STRONG> determines if the entry is a generic type by
179 checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capability.
181 <STRONG>-1</STRONG> means that the <STRONG>terminfo</STRONG> database could not be found.
183 If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon find-
184 ing an error and exits. Thus, the simplest call is:
186 <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
188 which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
190 The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>. The call:
192 <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
194 provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>. The <STRONG>setterm</STRONG> routine
195 is provided for BSD compatibility, and is not recommended for new pro-
199 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
200 The <STRONG>setupterm</STRONG> routine stores its information about the terminal in a
201 <STRONG>TERMINAL</STRONG> structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it
202 detects an error, or decides that the terminal is unsuitable (hardcopy
203 or generic), it discards this information, making it not available to
206 If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type, it will
207 reuse the information. It maintains only one copy of a given termi-
208 nal's capabilities in memory. If it is called for different terminal
209 types, <STRONG>setupterm</STRONG> allocates new storage for each set of terminal capa-
212 The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the
213 <STRONG>terminfo</STRONG> boolean, numeric, and string variables use the values from
214 <EM>nterm</EM>. It returns the old value of <STRONG>cur_term</STRONG>.
216 The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM> and makes
217 it available for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, refer-
218 ences to any of the <STRONG>terminfo</STRONG> boolean, numeric, and string variables
219 thereafter may refer to invalid memory locations until another <STRONG>se-</STRONG>
220 <STRONG>tupterm</STRONG> has been called.
222 The <STRONG>restartterm</STRONG> routine is similar to <STRONG>setupterm</STRONG> and <STRONG>initscr</STRONG>, except
223 that it is called after restoring memory to a previous state (for exam-
224 ple, when reloading a game saved as a core image dump). <STRONG>restartterm</STRONG>
225 assumes that the windows and the input and output options are the same
226 as when memory was saved, but the terminal type and baud rate may be
227 different. Accordingly, <STRONG>restartterm</STRONG> saves various tty state bits,
228 calls <STRONG>setupterm</STRONG>, and then restores the bits.
231 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
232 The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parameters <EM>pi</EM>. A
233 pointer is returned to the result of <EM>str</EM> with the parameters applied.
234 Application developers should keep in mind these quirks of the inter-
237 <STRONG>o</STRONG> Although <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the
238 prototype expects <STRONG>long</STRONG> (integer) values.
240 <STRONG>o</STRONG> Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal capa-
241 bilities require no more than one or two parameters.
243 <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM><stdarg.h></EM> rather than a
244 fixed-parameter list. Its numeric parameters are integers (int) rather
248 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
249 The <STRONG>tputs</STRONG> routine applies padding information to the string <EM>str</EM> and
252 <STRONG>o</STRONG> The <EM>str</EM> parameter must be a terminfo string variable or the return
253 value from <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
255 The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface,
256 which happens to share this function name with the <EM>terminfo</EM> inter-
259 <STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or 1 if not applicable.
261 <STRONG>o</STRONG> <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters are passed,
264 The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>. The output of <STRONG>putp</STRONG> al-
265 ways goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.
267 The <STRONG>vidputs</STRONG> routine displays the string on the terminal in the video
268 attribute mode <EM>attrs</EM>, which is any combination of the attributes listed
269 in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. The characters are passed to the <STRONG>putchar</STRONG>-like routine
272 The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
273 through <STRONG>putchar</STRONG>.
275 The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond to vidattr and vidputs,
276 respectively. They use a set of arguments for representing the video
277 attributes plus color, i.e.,
279 <STRONG>o</STRONG> <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
281 <STRONG>o</STRONG> <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
283 The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the attribute
284 constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
286 X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that
287 applications must provide a null pointer for that argument. As an ex-
288 tension, this implementation allows <EM>opts</EM> to be used as a pointer to
289 <STRONG>int</STRONG>, which overrides the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
291 The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It takes effect
292 immediately (rather than at the next refresh).
295 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
296 The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value of the
297 capability corresponding to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to them, such
298 as <STRONG>xenl</STRONG>. The <EM>capname</EM> for each capability is given in the table column
299 entitled <EM>capname</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
301 These routines return special values to denote errors.
303 The <STRONG>tigetflag</STRONG> routine returns
305 <STRONG>-1</STRONG> if <EM>capname</EM> is not a boolean capability, or
307 <STRONG>0</STRONG> if it is canceled or absent from the terminal description.
309 The <STRONG>tigetnum</STRONG> routine returns
311 <STRONG>-2</STRONG> if <EM>capname</EM> is not a numeric capability, or
313 <STRONG>-1</STRONG> if it is canceled or absent from the terminal description.
315 The <STRONG>tigetstr</STRONG> routine returns
317 <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
318 if <EM>capname</EM> is not a string capability, or
320 <STRONG>0</STRONG> if it is canceled or absent from the terminal description.
323 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
324 These null-terminated arrays contain
326 <STRONG>o</STRONG> the short terminfo names ("codes"),
328 <STRONG>o</STRONG> the <STRONG>termcap</STRONG> names ("names"), and
330 <STRONG>o</STRONG> the long terminfo names ("fnames")
332 for each of the predefined <STRONG>terminfo</STRONG> variables:
334 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
335 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
336 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
339 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
340 Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
341 only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
342 pletion, unless otherwise noted in the preceding routine descriptions.
344 Routines that return pointers always return <STRONG>NULL</STRONG> on error.
346 X/Open defines no error conditions. In this implementation
348 <STRONG>del_curterm</STRONG>
349 returns an error if its terminal parameter is null.
351 <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
353 <STRONG>restartterm</STRONG>
354 returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
357 <STRONG>setupterm</STRONG>
358 returns an error if it cannot allocate enough memory, or create
359 the initial windows (stdscr, curscr, newscr). Other error con-
360 ditions are documented above.
362 <STRONG>tputs</STRONG>
363 returns an error if the string parameter is null. It does not
364 detect I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
365 value of the output function <EM>putc</EM>.
368 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
369 SVr2 introduced the terminfo feature. Its programming manual mentioned
370 these low-level functions:
372 <STRONG>Function</STRONG> <STRONG>Description</STRONG>
373 ------------------------------------------------------------
374 fixterm restore tty to "in curses" state
375 gettmode establish current tty modes
376 mvcur low level cursor motion
377 putp utility function that uses <STRONG>tputs</STRONG> to send char-
378 acters via <STRONG>putchar</STRONG>.
379 resetterm set tty modes to "out of curses" state
380 resetty reset tty flags to stored value
381 saveterm save current modes as "in curses" state
382 savetty store current tty flags
383 setterm establish terminal with given type
384 setupterm establish terminal with given type
385 tparm instantiate a string expression with parameters
386 tputs apply padding information to a string
387 vidattr like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
388 vidputs output a string to put terminal in a specified
391 The programming manual also mentioned functions provided for termcap
392 compatibility (commenting that they "may go away at a later date"):
394 <STRONG>Function</STRONG> <STRONG>Description</STRONG>
395 ------------------------------------------------
396 tgetent look up termcap entry for given <EM>name</EM>
397 tgetflag get boolean entry for given <EM>id</EM>
398 tgetnum get numeric entry for given <EM>id</EM>
399 tgetstr get string entry for given <EM>id</EM>
400 tgoto apply parameters to given capability
401 tputs apply padding to capability, calling
402 a function to put characters
404 Early terminfo programs obtained capability values from the <STRONG>TERMINAL</STRONG>
405 structure initialized by <STRONG>setupterm</STRONG>.
407 SVr3 extended terminfo by adding functions to retrieve capability val-
408 ues (like the termcap interface), and reusing tgoto and tputs:
410 <STRONG>Function</STRONG> <STRONG>Description</STRONG>
411 -------------------------------------------
412 tigetflag get boolean entry for given <EM>id</EM>
413 tigetnum get numeric entry for given <EM>id</EM>
414 tigetstr get string entry for given <EM>id</EM>
416 SVr3 also replaced several of the SVr2 terminfo functions which had no
417 counterpart in the termcap interface, documenting them as obsolete:
419 <STRONG>Function</STRONG> <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
420 -----------------------------
422 fixterm reset_prog_mode
425 resetterm reset_shell_mode
426 saveterm def_prog_mode
429 SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
430 <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>. The latter were needed to support padding, and han-
431 dling functions such as <STRONG>vidattr</STRONG> (which used more than the two parame-
432 ters supported by <STRONG>tgoto</STRONG>).
434 SVr3 introduced the functions for switching between terminal descrip-
435 tions, e.g., <STRONG>set_curterm</STRONG>. The various global variables such as <STRONG>bool-</STRONG>
436 <STRONG>names</STRONG> were mentioned in the programming manual at this point.
438 SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
440 There are other low-level functions declared in the curses header files
441 on Unix systems, but none were documented. The functions marked "obso-
442 lete" remained in use by the Unix <STRONG>vi</STRONG> editor.
445 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
447 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
448 X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
450 The function <STRONG>setterm</STRONG> is not described by X/Open and must be considered
451 non-portable. All other functions are as described by X/Open.
454 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
455 <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not
456 part of X/Open Curses, but is assumed by some applications.
458 Other implementions may not declare the capability name arrays. Some
459 provide them without declaring them. X/Open does not specify them.
461 Extended terminal capability names, e.g., as defined by <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not
462 stored in the arrays described here.
465 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
466 Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor passed to
467 <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
468 the corresponding stream. In addition to the limitation that the ter-
469 minal was left in block-buffered mode on exit (like System V curses),
470 it was problematic because <STRONG>ncurses</STRONG> did not allow a reliable way to
471 cleanup on receiving SIGTSTP.
473 The current version (ncurses6) uses output buffers managed directly by
474 <STRONG>ncurses</STRONG>. Some of the low-level functions described in this manual page
475 write to the standard output. They are not signal-safe. The high-lev-
476 el functions in <STRONG>ncurses</STRONG> use alternate versions of these functions using
477 the more reliable buffering scheme.
480 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
481 The X/Open Curses prototypes are based on the SVr4 curses header decla-
482 rations, which were defined at the same time the C language was first
483 standardized in the late 1980s.
485 <STRONG>o</STRONG> X/Open Curses uses <STRONG>const</STRONG> less effectively than a later design
486 might, in some cases applying it needlessly to values are already
487 constant, and in most cases overlooking parameters which normally
488 would use <STRONG>const</STRONG>. Using constant parameters for functions which do
489 not use <STRONG>const</STRONG> may prevent the program from compiling. On the other
490 hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent feature.
492 As an extension, this implementation can be configured to change
493 the function prototypes to use the <STRONG>const</STRONG> keyword. The ncurses ABI
494 6 enables this feature by default.
496 <STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
497 rather than a variable argument list.
499 This implementation uses a variable argument list, but can be con-
500 figured to use the fixed-parameter list. Portable applications
501 should provide 9 parameters after the format; zeroes are fine for
504 In response to review comments by Thomas E. Dickey, X/Open Curses
505 Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
508 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
509 If configured to use the terminal-driver, e.g., for the MinGW port,
511 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty TERM variable as the special
514 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver by
515 checking if $TERM is set to "#win32con" or an abbreviation of that
519 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
520 In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type and returns
521 <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to implement the X/Open Curses semantics.
523 In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the type <STRONG>int</STRONG>
524 <STRONG>(*putc)(char)</STRONG>.
526 At least one implementation of X/Open Curses (Solaris) returns a value
527 other than <STRONG>OK</STRONG>/<STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. That returns the length of the string,
528 and does no error-checking.
530 X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state may not match
531 the actual terminal state, and that an application should touch and re-
532 fresh the window before resuming normal curses calls. Both <STRONG>ncurses</STRONG> and
533 System V Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
534 cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as a
535 terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not well
538 X/Open states that the old location must be given for <STRONG>mvcur</STRONG>. This im-
539 plementation allows the caller to use -1's for the old ordinates. In
540 that case, the old location is unknown.
543 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
544 <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_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
545 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
549 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
553 <li><a href="#h2-NAME">NAME</a></li>
554 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
555 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
557 <li><a href="#h3-Initialization">Initialization</a></li>
558 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
559 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
560 <li><a href="#h3-Output-Functions">Output Functions</a></li>
561 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
562 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
565 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
566 <li><a href="#h2-HISTORY">HISTORY</a></li>
567 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
569 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
570 <li><a href="#h3-Legacy-data">Legacy data</a></li>
571 <li><a href="#h3-Output-buffering">Output buffering</a></li>
572 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
573 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
574 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
577 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>