ncurses 6.0 - patch 20170401
[ncurses.git] / doc / html / man / curs_terminfo.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 1999-2016,2017 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.55 2017/03/31 15:16:15 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 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">
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>,
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
58
59
60 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
61        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
62        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
63
64        <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
65
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>
75
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>
81
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>
85
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>
90
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>
92
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>
96
97        <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
98
99
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.
106
107
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>].
113
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,
118        numbers, and flags.
119
120        The  <STRONG>terminfo</STRONG>  variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized
121        by <STRONG>setupterm</STRONG> as follows:
122
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.
125
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>
132            database are used.
133
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>].
139
140        Programs which use cursor addressing should
141
142        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and
143
144        <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.
145
146        Programs which execute shell subprocesses should
147
148        <STRONG>o</STRONG>   call  <STRONG>reset_shell_mode</STRONG>  and output <STRONG>exit_ca_mode</STRONG> before
149            the shell is called and
150
151        <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> and  call  <STRONG>reset_prog_mode</STRONG>  after
152            returning from the shell.
153
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
157        are its parameters:
158
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.
161
162           <EM>filedes</EM>
163                is the file descriptor used for all output.
164
165           <EM>errret</EM>
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.
172
173                If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
174
175                <STRONG>1</STRONG>    means that the terminal is  hardcopy,  cannot
176                     be used for curses applications.
177
178                     <STRONG>setupterm</STRONG>  determines if the entry is a hard-
179                     copy type by checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capa-
180                     bility.
181
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
185                     run.
186
187                     <STRONG>setupterm</STRONG> determines if the entry is a gener-
188                     ic type by checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capabil-
189                     ity.
190
191                <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not be
192                     found.
193
194                If  <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error mes-
195                sage upon finding an error and exits.   Thus,  the
196                simplest call is:
197
198                      <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
199
200                which  uses  all the defaults and sends the output
201                to <STRONG>stdout</STRONG>.
202
203        The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>.  The call:
204
205              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
206
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.
210
211
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-
218        plications.
219
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.
225
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>.
230
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>
236        has been called.
237
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
246        bits.
247
248
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:
254
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.
257
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
260            parameters.
261
262        <STRONG>tiparm</STRONG>  is  a  newer  form  of <STRONG>tparm</STRONG> which uses <EM>&lt;stdarg.h&gt;</EM>
263        rather than a fixed-parameter list.  Its  numeric  parame-
264        ters are integers (int) rather than longs.
265
266
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:
270
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>.
273
274        <STRONG>o</STRONG>   <EM>affcnt</EM>  is  the  number of lines affected, or 1 if not
275            applicable.
276
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.
279
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>.
283
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>.
288
289        The <STRONG>vidattr</STRONG> routine is like the  <STRONG>vidputs</STRONG>  routine,  except
290        that it outputs through <STRONG>putchar</STRONG>.
291
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.,
295
296        <STRONG>o</STRONG>   <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
297
298        <STRONG>o</STRONG>   <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
299
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.
302
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.
308
309        The <STRONG>mvcur</STRONG> routine provides low-level  cursor  motion.   It
310        takes  effect  immediately  (rather  than  at the next re-
311        fresh).
312
313
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>.
320
321        These routines return special values to denote errors.
322
323        The <STRONG>tigetflag</STRONG> routine returns
324
325        <STRONG>-1</STRONG>     if <EM>capname</EM> is not a boolean capability, or
326
327        <STRONG>0</STRONG>      if it is canceled or absent from the  terminal  de-
328               scription.
329
330        The <STRONG>tigetnum</STRONG> routine returns
331
332        <STRONG>-2</STRONG>     if <EM>capname</EM> is not a numeric capability, or
333
334        <STRONG>-1</STRONG>     if  it  is canceled or absent from the terminal de-
335               scription.
336
337        The <STRONG>tigetstr</STRONG> routine returns
338
339        <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
340               if <EM>capname</EM> is not a string capability, or
341
342        <STRONG>0</STRONG>      if it is canceled or absent from the  terminal  de-
343               scription.
344
345
346 </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
347        These null-terminated arrays contain
348
349        <STRONG>o</STRONG>   the short terminfo names ("codes"),
350
351        <STRONG>o</STRONG>   the <STRONG>termcap</STRONG> names ("names", and
352
353        <STRONG>o</STRONG>   the long terminfo names ("fnames")
354
355        for each of the predefined <STRONG>terminfo</STRONG> variables:
356
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>
361
362
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.
368
369        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
370
371        X/Open  defines  no error conditions.  In this implementa-
372        tion
373
374           <STRONG>del_curterm</STRONG>
375                returns an error  if  its  terminal  parameter  is
376                null.
377
378           <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
379
380           <STRONG>restartterm</STRONG>
381                returns  an  error  if  the associated call to <STRONG>se-</STRONG>
382                <STRONG>tupterm</STRONG> returns an error.
383
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-
388                mented above.
389
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-
394                tion <EM>putc</EM>.
395
396
397 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
398
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.
401
402        The function <STRONG>setterm</STRONG> is not described by X/Open  and  must
403        be  considered  non-portable.   All other functions are as
404        described by X/Open.
405
406
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
410        applications.
411
412        Other implementions may not declare  the  capability  name
413        arrays.  Some provide them without declaring them.  X/Open
414        does not specify them.
415
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.
418
419
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.
428
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.
435
436
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.
441
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
449            feature.
450
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
454            default.
455
456        <STRONG>o</STRONG>   X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number  of
457            parameters, rather than a variable argument list.
458
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.
463
464            In response to review comments by  Thomas  E.  Dickey,
465            X/Open  Curses Issue 7 proposed the <STRONG>tiparm</STRONG> function in
466            mid-2009.
467
468
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
471        MinGW port,
472
473        <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  interprets a missing/empty TERM variable as
474            the special value "unknown".
475
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.
479
480
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.
485
486        In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
487        type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
488
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.
492
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.
501
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
505        unknown.
506
507
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>
512
513
514
515                                                       <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
516 </PRE>
517 <div class="nav">
518 <ul>
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>
522 <ul>
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>
529 </ul>
530 </li>
531 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
532 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
533 <ul>
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>
540 </ul>
541 </li>
542 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
543 </ul>
544 </div>
545 </BODY>
546 </HTML>