36d4f66cc3c7e92875cb1212cfcacb9742268892
[ncurses.git] / doc / html / man / curs_terminfo.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 1999-2017,2018 Free Software Foundation, Inc.              *
4   *                                                                          *
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:                 *
12   *                                                                          *
13   * The above copyright notice and this permission notice shall be included  *
14   * in all copies or substantial portions of the Software.                   *
15   *                                                                          *
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.                               *
23   *                                                                          *
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       *
27   * authorization.                                                           *
28   ****************************************************************************
29   * @Id: curs_terminfo.3x,v 1.58 2018/04/07 21:09:12 tom Exp @
30   * ***************************************************************************
31   * ***************************************************************************
32   * ***************************************************************************
33   * ***************************************************************************
34   * ***************************************************************************
35 -->
36 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
37 <HTML>
38 <HEAD>
39 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
40 <meta name="generator" content="Manpage converted by man2html - see https://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">
44 </HEAD>
45 <BODY>
46 <H1 class="no-header">curs_terminfo 3x</H1>
47 <PRE>
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>
49
50
51
52
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>, <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>,
55        <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>,
56        <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database
57
58
59 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
60        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
61        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
62
63        <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
64
65        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG>
66        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG>
67        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG>
68        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG>
69        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG>
70        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG>
71        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG>
72        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG>
73        <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>
74
75        <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>
76        <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
77        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
78        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
79        <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>
80
81        <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
82        <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
83        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
84
85        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
86        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
87        <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
88        <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
89
90        <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM>, int <EM>newcol</EM><STRONG>);</STRONG>
91
92        <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
93        <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
94        <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
95
96        <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
97
98
99 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
100        These  low-level  routines must be called by programs that have to deal
101        directly with the <STRONG>terminfo</STRONG> database to handle certain terminal capabil-
102        ities, such as programming function keys.  For all other functionality,
103        <STRONG>curses</STRONG> routines are more suitable and their use is recommended.
104
105
106 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
107        Initially, <STRONG>setupterm</STRONG> should be called.  The high-level curses functions
108        <STRONG>initscr</STRONG>  and  <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of
109        terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
110
111        Applications can use the terminal  capabilities  either  directly  (via
112        header  definitions),  or by special functions.  The header files <STRONG>curs-</STRONG>
113        <STRONG>es.h</STRONG> and <STRONG>term.h</STRONG> should be included (in this order) to get  the  defini-
114        tions for these strings, numbers, and flags.
115
116        The  <STRONG>terminfo</STRONG>  variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
117        as follows:
118
119        <STRONG>o</STRONG>   If <STRONG>use_env(FALSE)</STRONG> has been called, values  for  <STRONG>lines</STRONG>  and  <STRONG>columns</STRONG>
120            specified in <STRONG>terminfo</STRONG> are used.
121
122        <STRONG>o</STRONG>   Otherwise,  if  the  environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist,
123            their values are used.  If these environment variables do not exist
124            and  the program is running in a window, the current window size is
125            used.  Otherwise, if the environment variables do  not  exist,  the
126            values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
127            used.
128
129        Parameterized strings should be passed  through  <STRONG>tparm</STRONG>  to  instantiate
130        them.   All  <STRONG>terminfo</STRONG> strings [including the output of <STRONG>tparm</STRONG>] should be
131        printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call <STRONG>reset_shell_mode</STRONG> to restore  the  tty
132        modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
133
134        Programs which use cursor addressing should
135
136        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and
137
138        <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.
139
140        Programs which execute shell subprocesses should
141
142        <STRONG>o</STRONG>   call  <STRONG>reset_shell_mode</STRONG>  and output <STRONG>exit_ca_mode</STRONG> before the shell is
143            called and
144
145        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning  from
146            the shell.
147
148        The  <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing the
149        <STRONG>terminfo</STRONG> structures, but does not  set  up  the  output  virtualization
150        structures used by <STRONG>curses</STRONG>.  These are its parameters:
151
152           <EM>term</EM> is the terminal type, a character string.  If <EM>term</EM> is null, the
153                environment variable <STRONG>TERM</STRONG> is used.
154
155           <EM>filedes</EM>
156                is the file descriptor used for all output.
157
158           <EM>errret</EM>
159                points to an optional location where an error status can be re-
160                turned  to  the  caller.  If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
161                returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a  status  value  in  the  integer
162                pointed  to by <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with sta-
163                tus of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
164
165                If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
166
167                <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot  be  used  for
168                     curses applications.
169
170                     <STRONG>setupterm</STRONG>  determines  if  the entry is a hardcopy type by
171                     checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capability.
172
173                <STRONG>0</STRONG>    means that the terminal could not be found, or that it  is
174                     a  generic  type, having too little information for curses
175                     applications to run.
176
177                     <STRONG>setupterm</STRONG> determines if the entry is  a  generic  type  by
178                     checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capability.
179
180                <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not be found.
181
182                If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon find-
183                ing an error and exits.  Thus, the simplest call is:
184
185                      <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
186
187                which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
188
189        The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>.  The call:
190
191              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
192
193        provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>.  The <STRONG>setterm</STRONG>  routine
194        is  provided for BSD compatibility, and is not recommended for new pro-
195        grams.
196
197
198 </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
199        The <STRONG>setupterm</STRONG> routine stores its information about the  terminal  in  a
200        <STRONG>TERMINAL</STRONG>  structure  pointed to by the global variable <STRONG>cur_term</STRONG>.  If it
201        detects an error, or decides that the terminal is unsuitable  (hardcopy
202        or  generic),  it discards this information, making it not available to
203        applications.
204
205        If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type,  it  will
206        reuse  the  information.   It maintains only one copy of a given termi-
207        nal's capabilities in memory.  If it is called for  different  terminal
208        types,  <STRONG>setupterm</STRONG>  allocates new storage for each set of terminal capa-
209        bilities.
210
211        The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes  all  of  the
212        <STRONG>terminfo</STRONG>  boolean,  numeric,  and  string variables use the values from
213        <EM>nterm</EM>.  It returns the old value of <STRONG>cur_term</STRONG>.
214
215        The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM>  and  makes
216        it available for further use.  If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, refer-
217        ences to any of the <STRONG>terminfo</STRONG> boolean,  numeric,  and  string  variables
218        thereafter  may  refer  to  invalid  memory locations until another <STRONG>se-</STRONG>
219        <STRONG>tupterm</STRONG> has been called.
220
221        The <STRONG>restartterm</STRONG> routine is similar to  <STRONG>setupterm</STRONG>  and  <STRONG>initscr</STRONG>,  except
222        that it is called after restoring memory to a previous state (for exam-
223        ple, when reloading a game saved as a core  image  dump).   <STRONG>restartterm</STRONG>
224        assumes  that the windows and the input and output options are the same
225        as when memory was saved, but the terminal type and baud  rate  may  be
226        different.   Accordingly,  <STRONG>restartterm</STRONG>  saves  various  tty state bits,
227        calls <STRONG>setupterm</STRONG>, and then restores the bits.
228
229
230 </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
231        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with  parameters  <EM>pi</EM>.   A
232        pointer  is  returned to the result of <EM>str</EM> with the parameters applied.
233        Application developers should keep in mind these quirks of  the  inter-
234        face:
235
236        <STRONG>o</STRONG>   Although  <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the
237            prototype expects <STRONG>long</STRONG> (integer) values.
238
239        <STRONG>o</STRONG>   Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal capa-
240            bilities require no more than one or two parameters.
241
242        <STRONG>tiparm</STRONG>  is  a  newer  form of <STRONG>tparm</STRONG> which uses <EM>&lt;stdarg.h&gt;</EM> rather than a
243        fixed-parameter list.  Its numeric parameters are integers (int) rather
244        than longs.
245
246
247 </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
248        The  <STRONG>tputs</STRONG>  routine  applies  padding information to the string <EM>str</EM> and
249        outputs it:
250
251        <STRONG>o</STRONG>   The <EM>str</EM> parameter must be a terminfo string variable or the  return
252            value from <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
253
254            The  <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface,
255            which happens to share this function name with the <EM>terminfo</EM>  inter-
256            face.
257
258        <STRONG>o</STRONG>   <EM>affcnt</EM> is the number of lines affected, or 1 if not applicable.
259
260        <STRONG>o</STRONG>   <EM>putc</EM>  is a <STRONG>putchar</STRONG>-like routine to which the characters are passed,
261            one at a time.
262
263        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-
264        ways goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.
265
266        The  <STRONG>vidputs</STRONG>  routine  displays the string on the terminal in the video
267        attribute mode <EM>attrs</EM>, which is any combination of the attributes listed
268        in  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.   The characters are passed to the <STRONG>putchar</STRONG>-like routine
269        <EM>putc</EM>.
270
271        The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
272        through <STRONG>putchar</STRONG>.
273
274        The  <STRONG>vid_attr</STRONG>  and <STRONG>vid_puts</STRONG> routines correspond to vidattr and vidputs,
275        respectively.  They use a set of arguments for representing  the  video
276        attributes plus color, i.e.,
277
278        <STRONG>o</STRONG>   <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
279
280        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
281
282        The  <STRONG>vid_attr</STRONG>  and  <STRONG>vid_puts</STRONG> routines are designed to use the attribute
283        constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
284
285        X/Open Curses reserves the <EM>opts</EM> argument for future  use,  saying  that
286        applications  must provide a null pointer for that argument.  As an ex-
287        tension, this implementation allows <EM>opts</EM> to be used  as  a  pointer  to
288        <STRONG>int</STRONG>, which overrides the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
289
290        The  <STRONG>mvcur</STRONG>  routine  provides low-level cursor motion.  It takes effect
291        immediately (rather than at the next refresh).
292
293
294 </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
295        The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value  of  the
296        capability  corresponding  to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to them, such
297        as <STRONG>xenl</STRONG>.  The <EM>capname</EM> for each capability is given in the table  column
298        entitled <EM>capname</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
299
300        These routines return special values to denote errors.
301
302        The <STRONG>tigetflag</STRONG> routine returns
303
304        <STRONG>-1</STRONG>     if <EM>capname</EM> is not a boolean capability, or
305
306        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
307
308        The <STRONG>tigetnum</STRONG> routine returns
309
310        <STRONG>-2</STRONG>     if <EM>capname</EM> is not a numeric capability, or
311
312        <STRONG>-1</STRONG>     if it is canceled or absent from the terminal description.
313
314        The <STRONG>tigetstr</STRONG> routine returns
315
316        <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
317               if <EM>capname</EM> is not a string capability, or
318
319        <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.
320
321
322 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
323        These null-terminated arrays contain
324
325        <STRONG>o</STRONG>   the short terminfo names ("codes"),
326
327        <STRONG>o</STRONG>   the <STRONG>termcap</STRONG> names ("names", and
328
329        <STRONG>o</STRONG>   the long terminfo names ("fnames")
330
331        for each of the predefined <STRONG>terminfo</STRONG> variables:
332
333               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
334               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
335               <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
336
337
338 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
339        Routines  that  return  an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
340        only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful  com-
341        pletion, unless otherwise noted in the preceding routine descriptions.
342
343        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
344
345        X/Open defines no error conditions.  In this implementation
346
347           <STRONG>del_curterm</STRONG>
348                returns an error if its terminal parameter is null.
349
350           <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
351
352           <STRONG>restartterm</STRONG>
353                returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
354                error.
355
356           <STRONG>setupterm</STRONG>
357                returns an error if it cannot allocate enough memory, or create
358                the initial windows (stdscr, curscr, newscr).  Other error con-
359                ditions are documented above.
360
361           <STRONG>tputs</STRONG>
362                returns an error if the string parameter is null.  It does  not
363                detect  I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
364                value of the output function <EM>putc</EM>.
365
366
367 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
368
369 </PRE><H3><a name="h3-Legacy-functions">Legacy functions</a></H3><PRE>
370        X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
371
372        The function <STRONG>setterm</STRONG> is not described by X/Open and must be  considered
373        non-portable.  All other functions are as described by X/Open.
374
375
376 </PRE><H3><a name="h3-Legacy-data">Legacy data</a></H3><PRE>
377        <STRONG>setupterm</STRONG>  copies  the terminal name to the array <STRONG>ttytype</STRONG>.  This is not
378        part of X/Open Curses, but is assumed by some applications.
379
380        Other implementions may not declare the capability name  arrays.   Some
381        provide them without declaring them.  X/Open does not specify them.
382
383        Extended terminal capability names, e.g., as defined by <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not
384        stored in the arrays described here.
385
386
387 </PRE><H3><a name="h3-Output-buffering">Output buffering</a></H3><PRE>
388        Older versions of <STRONG>ncurses</STRONG> assumed that the file  descriptor  passed  to
389        <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
390        the corresponding stream.  In addition to the limitation that the  ter-
391        minal  was  left in block-buffered mode on exit (like System V curses),
392        it was problematic because <STRONG>ncurses</STRONG> did not  allow  a  reliable  way  to
393        cleanup on receiving SIGTSTP.
394
395        The  current version (ncurses6) uses output buffers managed directly by
396        <STRONG>ncurses</STRONG>.  Some of the low-level functions described in this manual page
397        write to the standard output.  They are not signal-safe.  The high-lev-
398        el functions in <STRONG>ncurses</STRONG> use alternate versions of these functions using
399        the more reliable buffering scheme.
400
401
402 </PRE><H3><a name="h3-Function-prototypes">Function prototypes</a></H3><PRE>
403        The X/Open Curses prototypes are based on the SVr4 curses header decla-
404        rations, which were defined at the same time the C language  was  first
405        standardized in the late 1980s.
406
407        <STRONG>o</STRONG>   X/Open  Curses  uses  <STRONG>const</STRONG>  less  effectively  than a later design
408            might, in some cases applying it needlessly to values  are  already
409            constant,  and  in most cases overlooking parameters which normally
410            would use <STRONG>const</STRONG>.  Using constant parameters for functions which  do
411            not use <STRONG>const</STRONG> may prevent the program from compiling.  On the other
412            hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent feature.
413
414            As an extension, this implementation can be  configured  to  change
415            the  function prototypes to use the <STRONG>const</STRONG> keyword.  The ncurses ABI
416            6 enables this feature by default.
417
418        <STRONG>o</STRONG>   X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number  of  parameters,
419            rather than a variable argument list.
420
421            This  implementation uses a variable argument list, but can be con-
422            figured to use the  fixed-parameter  list.   Portable  applications
423            should  provide  9 parameters after the format; zeroes are fine for
424            this purpose.
425
426            In response to review comments by Thomas E. Dickey,  X/Open  Curses
427            Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
428
429
430 </PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
431        If configured to use the terminal-driver, e.g., for the MinGW port,
432
433        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  interprets  a missing/empty TERM variable as the special
434            value "unknown".
435
436        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver  by
437            checking  if $TERM is set to "#win32con" or an abbreviation of that
438            string.
439
440
441 </PRE><H3><a name="h3-Other-portability-issues">Other portability issues</a></H3><PRE>
442        In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type  and  returns
443        <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen to implement the X/Open Curses semantics.
444
445        In  System  V  Release  4, the third argument of <STRONG>tputs</STRONG> has the type <STRONG>int</STRONG>
446        <STRONG>(*putc)(char)</STRONG>.
447
448        At least one implementation of X/Open Curses (Solaris) returns a  value
449        other  than  <STRONG>OK</STRONG>/<STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>.  That returns the length of the string,
450        and does no error-checking.
451
452        X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state may  not  match
453        the actual terminal state, and that an application should touch and re-
454        fresh the window before resuming normal curses calls.  Both <STRONG>ncurses</STRONG> and
455        System  V  Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
456        cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is  documented  as  a
457        terminfo  function, <STRONG>mvcur</STRONG> is really a curses function which is not well
458        specified.
459
460        X/Open states that the old location must be given for <STRONG>mvcur</STRONG>.  This  im-
461        plementation  allows  the caller to use -1's for the old ordinates.  In
462        that case, the old location is unknown.
463
464
465 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
466        <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>,
467        <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>
468
469
470
471                                                              <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
472 </PRE>
473 <div class="nav">
474 <ul>
475 <li><a href="#h2-NAME">NAME</a></li>
476 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
477 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
478 <ul>
479 <li><a href="#h3-Initialization">Initialization</a></li>
480 <li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
481 <li><a href="#h3-Formatting-Output">Formatting Output</a></li>
482 <li><a href="#h3-Output-Functions">Output Functions</a></li>
483 <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
484 <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
485 </ul>
486 </li>
487 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
488 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
489 <ul>
490 <li><a href="#h3-Legacy-functions">Legacy functions</a></li>
491 <li><a href="#h3-Legacy-data">Legacy data</a></li>
492 <li><a href="#h3-Output-buffering">Output buffering</a></li>
493 <li><a href="#h3-Function-prototypes">Function prototypes</a></li>
494 <li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
495 <li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
496 </ul>
497 </li>
498 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
499 </ul>
500 </div>
501 </BODY>
502 </HTML>