]> ncurses.scripts.mit.edu Git - ncurses.git/blob - doc/html/man/curs_terminfo.3x.html
ncurses 6.3 - patch 20220924
[ncurses.git] / doc / html / man / curs_terminfo.3x.html
1 <!--
2   ****************************************************************************
3   * Copyright 2018-2022,2022 Thomas E. Dickey                                *
4   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
5   *                                                                          *
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:                 *
13   *                                                                          *
14   * The above copyright notice and this permission notice shall be included  *
15   * in all copies or substantial portions of the Software.                   *
16   *                                                                          *
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.                               *
24   *                                                                          *
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       *
28   * authorization.                                                           *
29   ****************************************************************************
30   * @Id: curs_terminfo.3x,v 1.82 2022/06/04 22:47:05 tom Exp @
31   * ***************************************************************************
32   * ***************************************************************************
33   * ***************************************************************************
34   * ***************************************************************************
35   * ***************************************************************************
36   * ***************************************************************************
37   * ***************************************************************************
38   * ***************************************************************************
39   * ***************************************************************************
40 -->
41 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
42 <HTML>
43 <HEAD>
44 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
45 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
46 <TITLE>curs_terminfo 3x</TITLE>
47 <link rel="author" href="mailto:bug-ncurses@gnu.org">
48
49 </HEAD>
50 <BODY>
51 <H1 class="no-header">curs_terminfo 3x</H1>
52 <PRE>
53 <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
55
56
57
58 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
59        <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>,
60        <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>,
61        <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database
62
63
64 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
65        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
66        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
67
68        <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
69
70        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG>
71        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG>
72        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG>
73        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG>
74        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG>
75        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG>
76        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG>
77        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG>
78        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>
79
80        <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>
81        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
82        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
83        <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>
84
85        <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
86        <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>
87        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
88
89        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
90        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
91        <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>
92        <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>
93
94        <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>
95
96        <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
97        <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
98        <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
99
100        <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
101
102
103 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
104        These  low-level  routines must be called by programs that have to deal
105        directly with the <STRONG>terminfo</STRONG> database to handle certain terminal capabil-
106        ities, such as programming function keys.  For all other functionality,
107        <STRONG>curses</STRONG> routines are more suitable and their use is recommended.
108
109        None of these functions use  (or  are  aware  of)  multibyte  character
110        strings such as UTF-8:
111
112        <STRONG>o</STRONG>   capability names use the POSIX portable character set
113
114        <STRONG>o</STRONG>   capability  string  values  have  no  associated encoding; they are
115            strings of 8-bit characters.
116
117
118 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
119        Initially, <STRONG>setupterm</STRONG> should be called.  The high-level curses functions
120        <STRONG>initscr</STRONG>  and  <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of
121        terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
122
123        Applications can use the terminal  capabilities  either  directly  (via
124        header  definitions),  or by special functions.  The header files <STRONG>curs-</STRONG>
125        <STRONG>es.h</STRONG> and <STRONG>term.h</STRONG> should be included (in this order) to get  the  defini-
126        tions for these strings, numbers, and flags.
127
128        The  <STRONG>terminfo</STRONG>  variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
129        as follows:
130
131        <STRONG>o</STRONG>   If <STRONG>use_env(FALSE)</STRONG> has been called, values  for  <STRONG>lines</STRONG>  and  <STRONG>columns</STRONG>
132            specified in <STRONG>terminfo</STRONG> are used.
133
134        <STRONG>o</STRONG>   Otherwise,  if  the  environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist,
135            their values are used.  If these environment variables do not exist
136            and  the program is running in a window, the current window size is
137            used.  Otherwise, if the environment variables do  not  exist,  the
138            values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
139            used.
140
141        Parameterized strings should be passed  through  <STRONG>tparm</STRONG>  to  instantiate
142        them.   All  <STRONG>terminfo</STRONG> strings (including the output of <STRONG>tparm</STRONG>) should be
143        printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call <STRONG>reset_shell_mode</STRONG> to restore  the  tty
144        modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
145
146        Programs which use cursor addressing should
147
148        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and
149
150        <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.
151
152        Programs which execute shell subprocesses should
153
154        <STRONG>o</STRONG>   call  <STRONG>reset_shell_mode</STRONG>  and output <STRONG>exit_ca_mode</STRONG> before the shell is
155            called and
156
157        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning  from
158            the shell.
159
160        The  <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing the
161        <STRONG>terminfo</STRONG> structures, but does not  set  up  the  output  virtualization
162        structures used by <STRONG>curses</STRONG>.  These are its parameters:
163
164           <EM>term</EM> is the terminal type, a character string.  If <EM>term</EM> is null, the
165                environment variable <STRONG>TERM</STRONG> is used.
166
167           <EM>filedes</EM>
168                is the file descriptor used for all output.
169
170           <EM>errret</EM>
171                points to an optional location where an error status can be re-
172                turned  to  the  caller.  If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
173                returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a  status  value  in  the  integer
174                pointed  to by <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with sta-
175                tus of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
176
177                If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
178
179                <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot  be  used  for
180                     curses applications.
181
182                     <STRONG>setupterm</STRONG>  determines  if  the entry is a hardcopy type by
183                     checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capability.
184
185                <STRONG>0</STRONG>    means that the terminal could not be found, or that it  is
186                     a  generic  type, having too little information for curses
187                     applications to run.
188
189                     <STRONG>setupterm</STRONG> determines if the entry is  a  generic  type  by
190                     checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capability.
191
192                <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not be found.
193
194                If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon find-
195                ing an error and exits.  Thus, the simplest call is:
196
197                      <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
198
199                which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
200
201
202 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
203        The <STRONG>setupterm</STRONG> routine stores its information about the  terminal  in  a
204        <STRONG>TERMINAL</STRONG>  structure  pointed to by the global variable <STRONG>cur_term</STRONG>.  If it
205        detects an error, or decides that the terminal is unsuitable  (hardcopy
206        or  generic),  it discards this information, making it not available to
207        applications.
208
209        If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type,  it  will
210        reuse  the  information.   It maintains only one copy of a given termi-
211        nal's capabilities in memory.  If it is called for  different  terminal
212        types,  <STRONG>setupterm</STRONG>  allocates new storage for each set of terminal capa-
213        bilities.
214
215        The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes  all  of  the
216        <STRONG>terminfo</STRONG>  boolean,  numeric,  and  string variables use the values from
217        <EM>nterm</EM>.  It returns the old value of <STRONG>cur_term</STRONG>.
218
219        The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM>  and  makes
220        it available for further use.  If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, refer-
221        ences to any of the <STRONG>terminfo</STRONG> boolean,  numeric,  and  string  variables
222        thereafter  may  refer  to  invalid  memory locations until another <STRONG>se-</STRONG>
223        <STRONG>tupterm</STRONG> has been called.
224
225        The <STRONG>restartterm</STRONG> routine is similar to  <STRONG>setupterm</STRONG>  and  <STRONG>initscr</STRONG>,  except
226        that it is called after restoring memory to a previous state (for exam-
227        ple, when reloading a game saved as a core  image  dump).   <STRONG>restartterm</STRONG>
228        assumes  that the windows and the input and output options are the same
229        as when memory was saved, but the terminal type and baud  rate  may  be
230        different.   Accordingly,  <STRONG>restartterm</STRONG>  saves  various  tty state bits,
231        calls <STRONG>setupterm</STRONG>, and then restores the bits.
232
233
234 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
235        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with  parameters  <EM>pi</EM>.   A
236        pointer  is  returned to the result of <EM>str</EM> with the parameters applied.
237        Application developers should keep in mind these quirks of  the  inter-
238        face:
239
240        <STRONG>o</STRONG>   Although  <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the
241            prototype expects <STRONG>long</STRONG> (integer) values.
242
243        <STRONG>o</STRONG>   Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal capa-
244            bilities require no more than one or two parameters.
245
246        <STRONG>o</STRONG>   Padding  information  is  ignored  by  <STRONG>tparm</STRONG>;  it is interpreted by
247            <STRONG>tputs</STRONG>.
248
249        <STRONG>o</STRONG>   The capability string is  null-terminated.   Use  "\200"  where  an
250            ASCII NUL is needed in the output.
251
252        <STRONG>tiparm</STRONG>  is  a  newer  form of <STRONG>tparm</STRONG> which uses <EM>&lt;stdarg.h&gt;</EM> rather than a
253        fixed-parameter list.  Its numeric parameters are integers (int) rather
254        than longs.
255
256
257 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
258        The  <STRONG>tputs</STRONG>  routine  applies padding information (i.e., by interpreting
259        marker embedded in the terminfo capability such as  "$&lt;5&gt;"  as  5  mil-
260        liseconds) to the string <EM>str</EM> and outputs it:
261
262        <STRONG>o</STRONG>   The  <EM>str</EM> parameter must be a terminfo string variable or the return
263            value from <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
264
265            The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM>  interface,
266            which  happens to share this function name with the <EM>terminfo</EM> inter-
267            face.
268
269        <STRONG>o</STRONG>   <EM>affcnt</EM> is the number of lines affected, or 1 if not applicable.
270
271        <STRONG>o</STRONG>   <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters are  passed,
272            one at a time.
273
274        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-
275        ways goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.
276
277        The <STRONG>vidputs</STRONG> routine displays the string on the terminal  in  the  video
278        attribute mode <EM>attrs</EM>, which is any combination of the attributes listed
279        in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.  The characters are passed to the  <STRONG>putchar</STRONG>-like  routine
280        <EM>putc</EM>.
281
282        The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
283        through <STRONG>putchar</STRONG>.
284
285        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond to vidattr  and  vidputs,
286        respectively.   They  use a set of arguments for representing the video
287        attributes plus color, i.e.,
288
289        <STRONG>o</STRONG>   <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
290
291        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
292
293        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to  use  the  attribute
294        constants with the <STRONG>WA_</STRONG> prefix.
295
296        X/Open  Curses  reserves  the <EM>opts</EM> argument for future use, saying that
297        applications must provide a null pointer for that argument.  As an  ex-
298        tension,  this  implementation  allows  <EM>opts</EM> to be used as a pointer to
299        <STRONG>int</STRONG>, which overrides the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
300
301        The <STRONG>mvcur</STRONG> routine provides low-level cursor motion.   It  takes  effect
302        immediately (rather than at the next refresh).
303
304        While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions which do not use the high-
305        level curses state, they are declared in <STRONG>&lt;curses.h&gt;</STRONG> because SystemV did
306        this (see <EM>HISTORY</EM>).
307
308
309 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
310        The  <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value of the
311        capability corresponding to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to  them,  such
312        as  <STRONG>xenl</STRONG>.  The <EM>capname</EM> for each capability is given in the table column
313        entitled <EM>capname</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
314
315        These routines return special values to denote errors.
316
317        The <STRONG>tigetflag</STRONG> routine returns
318
319        <STRONG>-1</STRONG>     if <EM>capname</EM> is not a boolean capability, or
320
321        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
322
323        The <STRONG>tigetnum</STRONG> routine returns
324
325        <STRONG>-2</STRONG>     if <EM>capname</EM> is not a numeric capability, or
326
327        <STRONG>-1</STRONG>     if it is canceled or absent from the terminal description.
328
329        The <STRONG>tigetstr</STRONG> routine returns
330
331        <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
332               if <EM>capname</EM> is not a string capability, or
333
334        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
335
336
337 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
338        These null-terminated arrays contain
339
340        <STRONG>o</STRONG>   the short terminfo names ("codes"),
341
342        <STRONG>o</STRONG>   the <STRONG>termcap</STRONG> names ("names"), and
343
344        <STRONG>o</STRONG>   the long terminfo names ("fnames")
345
346        for each of the predefined <STRONG>terminfo</STRONG> variables:
347
348               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
349               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
350               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
351
352
353 </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
354        Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal
355        description.  As a side-effect, it sets <STRONG>cur_term</STRONG> to point to this memo-
356        ry.  If an application calls
357
358             <STRONG>del_curterm(cur_term);</STRONG>
359
360        the memory will be freed.
361
362        The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage  allocated
363        by <STRONG>setupterm</STRONG>:
364
365        <STRONG>o</STRONG>   the  "static"  terminfo variables [a-z].  Before ncurses 6.3, those
366            were shared by all screens.  With ncurses 6.3, those are  allocated
367            per screen.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
368
369        <STRONG>o</STRONG>   to  improve performance, ncurses 6.3 caches the result of analyzing
370            terminfo strings for their parameter types.  That is  stored  as  a
371            binary tree referenced from the <STRONG>TERMINAL</STRONG> structure.
372
373        The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>.  Normally
374        they do not free this memory, but it is possible to do that  using  the
375        <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function.
376
377
378 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
379        Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
380        only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful  com-
381        pletion, unless otherwise noted in the preceding routine descriptions.
382
383        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
384
385        X/Open defines no error conditions.  In this implementation
386
387           <STRONG>del_curterm</STRONG>
388                returns an error if its terminal parameter is null.
389
390           <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
391
392           <STRONG>restartterm</STRONG>
393                returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
394                error.
395
396           <STRONG>setupterm</STRONG>
397                returns an error if it cannot allocate enough memory, or create
398                the initial windows (stdscr, curscr, newscr).  Other error con-
399                ditions are documented above.
400
401           <STRONG>tputs</STRONG>
402                returns an error if the string parameter is null.  It does  not
403                detect  I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
404                value of the output function <EM>putc</EM>.
405
406
407 </PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
408        This implementation provides a few macros for compatibility  with  sys-
409        tems  before  SVr4  (see  <EM>HISTORY</EM>).   Those  include  <STRONG>crmode</STRONG>,  <STRONG>fixterm</STRONG>,
410        <STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
411
412        In SVr4, those are found in <STRONG>&lt;curses.h&gt;</STRONG>, but  except  for  <STRONG>setterm</STRONG>,  are
413        likewise macros.  The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
414        page.  The manual page notes that the <STRONG>setterm</STRONG> routine was  replaced  by
415        <STRONG>setupterm</STRONG>, stating that the call:
416
417              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
418
419        provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, and is not recommend-
420        ed for new programs.  This implementation provides each of  those  sym-
421        bols as macros for BSD compatibility,
422
423
424 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
425        SVr2 introduced the terminfo feature.  Its programming manual mentioned
426        these low-level functions:
427
428        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
429        ------------------------------------------------------------
430        fixterm     restore tty to "in curses" state
431        gettmode    establish current tty modes
432        mvcur       low level cursor motion
433        putp        utility function that uses <STRONG>tputs</STRONG> to send  char-
434                    acters via <STRONG>putchar</STRONG>.
435        resetterm   set tty modes to "out of curses" state
436        resetty     reset tty flags to stored value
437        saveterm    save current modes as "in curses" state
438        savetty     store current tty flags
439        setterm     establish terminal with given type
440        setupterm   establish terminal with given type
441        tparm       instantiate a string expression with parameters
442        tputs       apply padding information to a string
443        vidattr     like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
444        vidputs     output  a string to put terminal in a specified
445                    video attribute mode
446
447        The programming manual also mentioned functions  provided  for  termcap
448        compatibility (commenting that they "may go away at a later date"):
449
450        <STRONG>Function</STRONG>   <STRONG>Description</STRONG>
451        ------------------------------------------------
452        tgetent    look up termcap entry for given <EM>name</EM>
453        tgetflag   get boolean entry for given <EM>id</EM>
454        tgetnum    get numeric entry for given <EM>id</EM>
455        tgetstr    get string entry for given <EM>id</EM>
456        tgoto      apply parameters to given capability
457        tputs      apply padding to capability, calling
458                   a function to put characters
459
460        Early terminfo programs obtained capability values  from  the  <STRONG>TERMINAL</STRONG>
461        structure initialized by <STRONG>setupterm</STRONG>.
462
463        SVr3  extended terminfo by adding functions to retrieve capability val-
464        ues (like the termcap interface), and reusing tgoto and tputs:
465
466        <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
467        -------------------------------------------
468        tigetflag   get boolean entry for given <EM>id</EM>
469
470        tigetnum    get numeric entry for given <EM>id</EM>
471        tigetstr    get string entry for given <EM>id</EM>
472
473        SVr3 also replaced several of the SVr2 terminfo functions which had  no
474        counterpart in the termcap interface, documenting them as obsolete:
475
476        <STRONG>Function</STRONG>    <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
477        -----------------------------
478        crmode      cbreak
479        fixterm     reset_prog_mode
480        gettmode    N/A
481        nocrmode    nocbreak
482        resetterm   reset_shell_mode
483        saveterm    def_prog_mode
484        setterm     setupterm
485
486        SVr3  kept  the  <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
487        <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>.  The latter were needed to support padding,  and  han-
488        dling  functions  such as <STRONG>vidattr</STRONG> (which used more than the two parame-
489        ters supported by <STRONG>tgoto</STRONG>).
490
491        SVr3 introduced the functions for switching between  terminal  descrip-
492        tions, e.g., <STRONG>set_curterm</STRONG>.  Some of that was incremental improvements to
493        the SVr2 library:
494
495        <STRONG>o</STRONG>   The <STRONG>TERMINAL</STRONG> type definition was introduced  in  SVr3.01,  for  the
496            <STRONG>term</STRONG> structure provided in SVr2.
497
498        <STRONG>o</STRONG>   The  various  global  variables such as <STRONG>boolnames</STRONG> were mentioned in
499            the programming manual at this point,  though  the  variables  were
500            provided in SVr2.
501
502        SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
503
504        There are other low-level functions declared in the curses header files
505        on Unix systems, but none were documented.  The functions marked "obso-
506        lete" remained in use by the Unix <STRONG>vi(1)</STRONG> editor.
507
508
509 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
510
511 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
512        X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
513
514        The  function <STRONG>setterm</STRONG> is not described by X/Open and must be considered
515        non-portable.  All other functions are as described by X/Open.
516
517
518 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
519        <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>.  This  is  not
520        part of X/Open Curses, but is assumed by some applications.
521
522        Other  implementions  may not declare the capability name arrays.  Some
523        provide them without declaring them.  X/Open does not specify them.
524
525        Extended terminal capability names, e.g., as defined by <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not
526        stored in the arrays described here.
527
528
529 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
530        Older  versions  of  <STRONG>ncurses</STRONG> assumed that the file descriptor passed to
531        <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
532        the  corresponding stream.  In addition to the limitation that the ter-
533        minal was left in block-buffered mode on exit (like System  V  curses),
534        it  was  problematic  because  <STRONG>ncurses</STRONG>  did not allow a reliable way to
535        cleanup on receiving SIGTSTP.
536
537        The current version (ncurses6) uses output buffers managed directly  by
538        <STRONG>ncurses</STRONG>.  Some of the low-level functions described in this manual page
539        write to the standard output.  They are not signal-safe.  The high-lev-
540        el functions in <STRONG>ncurses</STRONG> use alternate versions of these functions using
541        the more reliable buffering scheme.
542
543
544 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
545        The X/Open Curses prototypes are based on the SVr4 curses header decla-
546        rations,  which  were defined at the same time the C language was first
547        standardized in the late 1980s.
548
549        <STRONG>o</STRONG>   X/Open Curses uses <STRONG>const</STRONG>  less  effectively  than  a  later  design
550            might,  in  some cases applying it needlessly to values are already
551            constant, and in most cases overlooking parameters  which  normally
552            would  use <STRONG>const</STRONG>.  Using constant parameters for functions which do
553            not use <STRONG>const</STRONG> may prevent the program from compiling.  On the other
554            hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent feature.
555
556            As  an  extension,  this implementation can be configured to change
557            the function prototypes to use the <STRONG>const</STRONG> keyword.  The ncurses  ABI
558            6 enables this feature by default.
559
560        <STRONG>o</STRONG>   X/Open  Curses  prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
561            rather than a variable argument list.
562
563            This implementation uses a variable argument list, but can be  con-
564            figured  to  use  the  fixed-parameter list.  Portable applications
565            should provide 9 parameters after the format; zeroes are  fine  for
566            this purpose.
567
568            In  response  to review comments by Thomas E. Dickey, X/Open Curses
569            Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
570
571
572 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
573        If configured to use the terminal-driver, e.g., for the MinGW port,
574
575        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG> interprets a missing/empty TERM variable as  the  special
576            value "unknown".
577
578        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  allows explicit use of the the windows console driver by
579            checking if $TERM is set to "#win32con" or an abbreviation of  that
580            string.
581
582
583 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
584        In  System  V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type and returns
585        <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen to implement the X/Open Curses semantics.
586
587        In System V Release 4, the third argument of <STRONG>tputs</STRONG>  has  the  type  <STRONG>int</STRONG>
588        <STRONG>(*putc)(char)</STRONG>.
589
590        At  least one implementation of X/Open Curses (Solaris) returns a value
591        other than <STRONG>OK</STRONG>/<STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>.  That returns the length of  the  string,
592        and does no error-checking.
593
594        X/Open  notes  that after calling <STRONG>mvcur</STRONG>, the curses state may not match
595        the actual terminal state, and that an application should touch and re-
596        fresh the window before resuming normal curses calls.  Both <STRONG>ncurses</STRONG> and
597        System V Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN  data  allo-
598        cated  in  either  <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is documented as a
599        terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not  well
600        specified.
601
602        X/Open  states that the old location must be given for <STRONG>mvcur</STRONG>.  This im-
603        plementation allows the caller to use -1's for the old  ordinates.   In
604        that case, the old location is unknown.
605
606
607 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
608        <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>,
609        <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><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG>ter-</STRONG>
610        <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG>
611
612
613
614                                                              <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
615 </PRE>
616 <div class="nav">
617 <ul>
618 <li><a href="#h2-NAME">NAME</a></li>
619 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
620 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
621 <ul>
622 <li><a href="#h3-Initialization">Initialization</a></li>
623 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
624 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
625 <li><a href="#h3-Output-Functions">Output Functions</a></li>
626 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
627 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
628 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
629 </ul>
630 </li>
631 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a>
632 <ul>
633 <li><a href="#h3-Compatibility-macros">Compatibility macros</a></li>
634 </ul>
635 </li>
636 <li><a href="#h2-HISTORY">HISTORY</a></li>
637 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
638 <ul>
639 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
640 <li><a href="#h3-Legacy-data">Legacy data</a></li>
641 <li><a href="#h3-Output-buffering">Output buffering</a></li>
642 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
643 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
644 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
645 </ul>
646 </li>
647 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
648 </ul>
649 </div>
650 </BODY>
651 </HTML>