2 ****************************************************************************
3 * Copyright (c) 1999-2016,2017 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************
29 * @Id: curs_terminfo.3x,v 1.55 2017/03/31 15:16:15 tom Exp @
30 * ***************************************************************************
31 * ***************************************************************************
32 * ***************************************************************************
33 * ***************************************************************************
34 * ***************************************************************************
36 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
39 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
40 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
41 <TITLE>curs_terminfo 3x</TITLE>
42 <link rev=made href="mailto:bug-ncurses@gnu.org">
43 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
46 <H1 class="no-header">curs_terminfo 3x</H1>
48 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
53 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
54 <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>,
55 <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>, <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>,
56 <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> -
57 <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
102 have to deal directly with the <STRONG>terminfo</STRONG> database to handle
103 certain terminal capabilities, such as programming func-
104 tion keys. For all other functionality, <STRONG>curses</STRONG> routines
105 are more suitable and their use is recommended.
108 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
109 Initially, <STRONG>setupterm</STRONG> should be called. The high-level
110 curses functions <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to
111 initialize the low-level set of terminal-dependent vari-
112 ables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
114 Applications can use the terminal capabilities either di-
115 rectly (via header definitions), or by special functions.
116 The header files <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG> should be included
117 (in this order) to get the definitions for these strings,
120 The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized
121 by <STRONG>setupterm</STRONG> as follows:
123 <STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG>
124 and <STRONG>columns</STRONG> specified in <STRONG>terminfo</STRONG> are used.
126 <STRONG>o</STRONG> Otherwise, if the environment variables <STRONG>LINES</STRONG> and <STRONG>COL-</STRONG>
127 <STRONG>UMNS</STRONG> exist, their values are used. If these environ-
128 ment variables do not exist and the program is running
129 in a window, the current window size is used. Other-
130 wise, if the environment variables do not exist, the
131 values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG>
134 Parameterized strings should be passed through <STRONG>tparm</STRONG> to
135 instantiate them. All <STRONG>terminfo</STRONG> strings [including the
136 output of <STRONG>tparm</STRONG>] should be printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.
137 Call <STRONG>reset_shell_mode</STRONG> to restore the tty modes before ex-
138 iting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
140 Programs which use cursor addressing should
142 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> upon startup and
144 <STRONG>o</STRONG> output <STRONG>exit_ca_mode</STRONG> before exiting.
146 Programs which execute shell subprocesses should
148 <STRONG>o</STRONG> call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before
149 the shell is called and
151 <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after
152 returning from the shell.
154 The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, ini-
155 tializing the <STRONG>terminfo</STRONG> structures, but does not set up the
156 output virtualization structures used by <STRONG>curses</STRONG>. These
159 <EM>term</EM> is the terminal type, a character string. If <EM>term</EM>
160 is null, the environment variable <STRONG>TERM</STRONG> is used.
163 is the file descriptor used for all output.
166 points to an optional location where an error sta-
167 tus can be returned to the caller. If <EM>errret</EM> is
168 not null, then <STRONG>setupterm</STRONG> returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and
169 stores a status value in the integer pointed to by
170 <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with status
171 of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
173 If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
175 <STRONG>1</STRONG> means that the terminal is hardcopy, cannot
176 be used for curses applications.
178 <STRONG>setupterm</STRONG> determines if the entry is a hard-
179 copy type by checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capa-
182 <STRONG>0</STRONG> means that the terminal could not be found,
183 or that it is a generic type, having too lit-
184 tle information for curses applications to
187 <STRONG>setupterm</STRONG> determines if the entry is a gener-
188 ic type by checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capabil-
191 <STRONG>-1</STRONG> means that the <STRONG>terminfo</STRONG> database could not be
194 If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error mes-
195 sage upon finding an error and exits. Thus, the
198 <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
200 which uses all the defaults and sends the output
201 to <STRONG>stdout</STRONG>.
203 The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>. The call:
205 <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
207 provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>. The
208 <STRONG>setterm</STRONG> routine is provided for BSD compatibility, and is
209 not recommended for new programs.
212 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
213 The <STRONG>setupterm</STRONG> routine stores its information about the
214 terminal in a <STRONG>TERMINAL</STRONG> structure pointed to by the global
215 variable <STRONG>cur_term</STRONG>. If it detects an error, or decides
216 that the terminal is unsuitable (hardcopy or generic), it
217 discards this information, making it not available to ap-
220 If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal
221 type, it will reuse the information. It maintains only
222 one copy of a given terminal's capabilities in memory. If
223 it is called for different terminal types, <STRONG>setupterm</STRONG> allo-
224 cates new storage for each set of terminal capabilities.
226 The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes
227 all of the <STRONG>terminfo</STRONG> boolean, numeric, and string variables
228 use the values from <EM>nterm</EM>. It returns the old value of
229 <STRONG>cur_term</STRONG>.
231 The <STRONG>del_curterm</STRONG> routine frees the space pointed to by
232 <EM>oterm</EM> and makes it available for further use. If <EM>oterm</EM> is
233 the same as <STRONG>cur_term</STRONG>, references to any of the <STRONG>terminfo</STRONG>
234 boolean, numeric, and string variables thereafter may re-
235 fer to invalid memory locations until another <STRONG>setupterm</STRONG>
238 The <STRONG>restartterm</STRONG> routine is similar to <STRONG>setupterm</STRONG> and
239 <STRONG>initscr</STRONG>, except that it is called after restoring memory
240 to a previous state (for example, when reloading a game
241 saved as a core image dump). <STRONG>restartterm</STRONG> assumes that the
242 windows and the input and output options are the same as
243 when memory was saved, but the terminal type and baud rate
244 may be different. Accordingly, <STRONG>restartterm</STRONG> saves various
245 tty state bits, calls <STRONG>setupterm</STRONG>, and then restores the
249 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
250 The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parame-
251 ters <EM>pi</EM>. A pointer is returned to the result of <EM>str</EM> with
252 the parameters applied. Application developers should
253 keep in mind these quirks of the interface:
255 <STRONG>o</STRONG> Although <STRONG>tparm</STRONG>'s actual parameters may be integers or
256 strings, the prototype expects <STRONG>long</STRONG> (integer) values.
258 <STRONG>o</STRONG> Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most
259 terminal capabilities require no more than one or two
262 <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM><stdarg.h></EM>
263 rather than a fixed-parameter list. Its numeric parame-
264 ters are integers (int) rather than longs.
267 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
268 The <STRONG>tputs</STRONG> routine applies padding information to the
269 string <EM>str</EM> and outputs it:
271 <STRONG>o</STRONG> The <EM>str</EM> must be a terminfo string variable or the re-
272 turn value from <STRONG>tparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
274 <STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or 1 if not
277 <STRONG>o</STRONG> <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters
278 are passed, one at a time.
280 The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>. The output
281 of <STRONG>putp</STRONG> always goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM>
282 specified in <STRONG>setupterm</STRONG>.
284 The <STRONG>vidputs</STRONG> routine displays the string on the terminal in
285 the video attribute mode <EM>attrs</EM>, which is any combination
286 of the attributes listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. The characters
287 are passed to the <STRONG>putchar</STRONG>-like routine <EM>putc</EM>.
289 The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except
290 that it outputs through <STRONG>putchar</STRONG>.
292 The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond to vidattr
293 and vidputs, respectively. They use a set of arguments
294 for representing the video attributes plus color, i.e.,
296 <STRONG>o</STRONG> <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
298 <STRONG>o</STRONG> <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
300 The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the
301 attribute constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
303 X/Open Curses reserves the <EM>opts</EM> argument for future use,
304 saying that applications must provide a null pointer for
305 that argument. As an extension, this implementation al-
306 lows <EM>opts</EM> to be used as a pointer to <STRONG>int</STRONG>, which overrides
307 the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
309 The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It
310 takes effect immediately (rather than at the next re-
314 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
315 The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the
316 value of the capability corresponding to the <STRONG>terminfo</STRONG> <EM>cap-</EM>
317 <EM>name</EM> passed to them, such as <STRONG>xenl</STRONG>. The <EM>capname</EM> for each
318 capability is given in the table column entitled <EM>capname</EM>
319 code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
321 These routines return special values to denote errors.
323 The <STRONG>tigetflag</STRONG> routine returns
325 <STRONG>-1</STRONG> if <EM>capname</EM> is not a boolean capability, or
327 <STRONG>0</STRONG> if it is canceled or absent from the terminal de-
330 The <STRONG>tigetnum</STRONG> routine returns
332 <STRONG>-2</STRONG> if <EM>capname</EM> is not a numeric capability, or
334 <STRONG>-1</STRONG> if it is canceled or absent from the terminal de-
337 The <STRONG>tigetstr</STRONG> routine returns
339 <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
340 if <EM>capname</EM> is not a string capability, or
342 <STRONG>0</STRONG> if it is canceled or absent from the terminal de-
346 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
347 These null-terminated arrays contain
349 <STRONG>o</STRONG> the short terminfo names ("codes"),
351 <STRONG>o</STRONG> the <STRONG>termcap</STRONG> names ("names", and
353 <STRONG>o</STRONG> the long terminfo names ("fnames")
355 for each of the predefined <STRONG>terminfo</STRONG> variables:
357 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolf-</STRONG>
358 <STRONG>names[]</STRONG>
359 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
360 <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
363 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
364 Routines that return an integer return <STRONG>ERR</STRONG> upon failure
365 and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other than
366 <STRONG>ERR</STRONG>") upon successful completion, unless otherwise noted
367 in the preceding routine descriptions.
369 Routines that return pointers always return <STRONG>NULL</STRONG> on error.
371 X/Open defines no error conditions. In this implementa-
374 <STRONG>del_curterm</STRONG>
375 returns an error if its terminal parameter is
378 <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
380 <STRONG>restartterm</STRONG>
381 returns an error if the associated call to <STRONG>se-</STRONG>
382 <STRONG>tupterm</STRONG> returns an error.
384 <STRONG>setupterm</STRONG>
385 returns an error if it cannot allocate enough mem-
386 ory, or create the initial windows (stdscr,
387 curscr, newscr). Other error conditions are docu-
390 <STRONG>tputs</STRONG>
391 returns an error if the string parameter is null.
392 It does not detect I/O errors: X/Open states that
393 <STRONG>tputs</STRONG> ignores the return value of the output func-
397 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
399 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
400 X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
402 The function <STRONG>setterm</STRONG> is not described by X/Open and must
403 be considered non-portable. All other functions are as
407 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
408 <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>.
409 This is not part of X/Open Curses, but is assumed by some
412 Other implementions may not declare the capability name
413 arrays. Some provide them without declaring them. X/Open
414 does not specify them.
416 Extended terminal capability names, e.g., as defined by
417 <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not stored in the arrays described here.
420 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
421 Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor
422 passed to <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered
423 I/O, and would write to the corresponding stream. In ad-
424 dition to the limitation that the terminal was left in
425 block-buffered mode on exit (like System V curses), it was
426 problematic because <STRONG>ncurses</STRONG> did not allow a reliable way
427 to cleanup on receiving SIGTSTP.
429 The current version (ncurses6) uses output buffers managed
430 directly by <STRONG>ncurses</STRONG>. Some of the low-level functions de-
431 scribed in this manual page write to the standard output.
432 They are not signal-safe. The high-level functions in
433 <STRONG>ncurses</STRONG> use alternate versions of these functions using
434 the more reliable buffering scheme.
437 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
438 The X/Open Curses prototypes are based on the SVr4 curses
439 header declarations, which were defined at the same time
440 the C language was first standardized in the late 1980s.
442 <STRONG>o</STRONG> X/Open Curses uses <STRONG>const</STRONG> less effectively than a later
443 design might, in some cases applying it needlessly to
444 values are already constant, and in most cases over-
445 looking parameters which normally would use <STRONG>const</STRONG>.
446 Using constant parameters for functions which do not
447 use <STRONG>const</STRONG> may prevent the program from compiling. On
448 the other hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent
451 As an extension, this implementation can be configured
452 to change the function prototypes to use the <STRONG>const</STRONG>
453 keyword. The ncurses ABI 6 enables this feature by
456 <STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of
457 parameters, rather than a variable argument list.
459 This implementation uses a variable argument list, but
460 can be configured to use the fixed-parameter list.
461 Portable applications should provide 9 parameters af-
462 ter the format; zeroes are fine for this purpose.
464 In response to review comments by Thomas E. Dickey,
465 X/Open Curses Issue 7 proposed the <STRONG>tiparm</STRONG> function in
469 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
470 If configured to use the terminal-driver, e.g., for the
473 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty TERM variable as
474 the special value "unknown".
476 <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows con-
477 sole driver by checking if $TERM is set to "#win32con"
478 or an abbreviation of that string.
481 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
482 In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type
483 and returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to implement the
484 X/Open Curses semantics.
486 In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
487 type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
489 At least one implementation of X/Open Curses (Solaris) re-
490 turns a value other than OK/ERR from <STRONG>tputs</STRONG>. That returns
491 the length of the string, and does no error-checking.
493 X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state
494 may not match the actual terminal state, and that an ap-
495 plication should touch and refresh the window before re-
496 suming normal curses calls. Both <STRONG>ncurses</STRONG> and System V Re-
497 lease 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
498 cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is docu-
499 mented as a terminfo function, <STRONG>mvcur</STRONG> is really a curses
500 function which is not well specified.
502 X/Open states that the old location must be given for
503 <STRONG>mvcur</STRONG>. This implementation allows the caller to use -1's
504 for the old ordinates. In that case, the old location is
508 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
509 <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>curs_term-</STRONG>
510 <STRONG><A HREF="curs_termcap.3x.html">cap(3x)</A></STRONG>, <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>,
511 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
515 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
519 <li><a href="#h2-NAME">NAME</a></li>
520 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
521 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
523 <li><a href="#h3-Initialization">Initialization</a></li>
524 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
525 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
526 <li><a href="#h3-Output-Functions">Output Functions</a></li>
527 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
528 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
531 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
532 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
534 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
535 <li><a href="#h3-Legacy-data">Legacy data</a></li>
536 <li><a href="#h3-Output-buffering">Output buffering</a></li>
537 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
538 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
539 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
542 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>