ncurses 5.3
[ncurses.git] / doc / html / man / curs_terminfo.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   ****************************************************************************
4   * Copyright (c) 1999-2000,2002 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.16 2002/07/20 16:05:19 tom Exp @
31 -->
32 <HTML>
33 <HEAD>
34 <TITLE>curs_terminfo 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
37 </HEAD>
38 <BODY>
39 <H1>curs_terminfo 3x</H1>
40 <HR>
41 <PRE>
42 <!-- Manpage converted by man2html 3.0.1 -->
43
44 </PRE>
45 <H2>NAME</H2><PRE>
46        <STRONG>del_curterm</STRONG>,  <STRONG>mvcur</STRONG>,  <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>set-</STRONG>
47        <STRONG>term</STRONG>, <STRONG>setupterm</STRONG>,  <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG>,  <STRONG>tigetstr</STRONG>,  <STRONG>tparm</STRONG>,
48        <STRONG>tputs</STRONG>,  <STRONG>vid_attr</STRONG>,  <STRONG>vid_puts</STRONG>,  <STRONG>vidattr</STRONG>,  <STRONG>vidputs</STRONG>  -  <STRONG>curses</STRONG>
49        interfaces to terminfo database
50
51
52 </PRE>
53 <H2>SYNOPSIS</H2><PRE>
54        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
55        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
56
57        <STRONG>int</STRONG> <STRONG>setupterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
58        <STRONG>int</STRONG> <STRONG>setterm(char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
59        <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
60        <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
61        <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fildes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
62        <STRONG>char</STRONG> <STRONG>*tparm(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
63        <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>
64        <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
65        <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
66        <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
67        <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>)(char));</STRONG>
68        <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>
69        <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>
70        <STRONG>int</STRONG> <STRONG>tigetflag(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
71        <STRONG>int</STRONG> <STRONG>tigetnum(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
72        <STRONG>char</STRONG> <STRONG>*tigetstr(char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
73
74
75 </PRE>
76 <H2>DESCRIPTION</H2><PRE>
77        These low-level routines must be called by  programs  that
78        have to deal directly with the <STRONG>terminfo</STRONG> database to handle
79        certain terminal capabilities, such as  programming  func-
80        tion  keys.   For all other functionality, <STRONG>curses</STRONG> routines
81        are more suitable and their use is recommended.
82
83        Initially,  <STRONG>setupterm</STRONG>  should  be   called.    Note   that
84        <STRONG>setupterm</STRONG>  is automatically called by <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG>.
85        This  defines  the  set  of  terminal-dependent  variables
86        [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].  The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and
87        <STRONG>columns</STRONG>  are  initialized  by  <STRONG>setupterm</STRONG>  as  follows:  If
88        <STRONG>use_env(FALSE)</STRONG>  has  been  called,  values  for  <STRONG>lines</STRONG> and
89        <STRONG>columns</STRONG> specified in <STRONG>terminfo</STRONG> are used.  Otherwise, if the
90        environment  variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist, their val-
91        ues are used.  If these environment variables do not exist
92        and the program is running in a window, the current window
93        size is used.  Otherwise, if the environment variables  do
94        not  exist,  the values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in
95        the <STRONG>terminfo</STRONG> database are used.
96
97        The header files <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG>  should  be  included
98        (in  this order) to get the definitions for these strings,
99        numbers,  and  flags.   Parameterized  strings  should  be
100        passed  through  <STRONG>tparm</STRONG>  to instantiate them.  All <STRONG>terminfo</STRONG>
101        strings [including the output of <STRONG>tparm</STRONG>] should be  printed
102        with  <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call the <STRONG>reset_shell_mode</STRONG> to restore
103        the tty modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].   Pro-
104        grams   which   use   cursor   addressing   should  output
105        <STRONG>enter_ca_mode</STRONG> upon startup and should output  <STRONG>exit_ca_mode</STRONG>
106        before  exiting.   Programs  desiring shell escapes should
107        call
108
109        <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the  shell
110        is   called  and  should  output  <STRONG>enter_ca_mode</STRONG>  and  call
111        <STRONG>reset_prog_mode</STRONG> after returning from the shell.
112
113        The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, ini-
114        tializing the <STRONG>terminfo</STRONG> structures, but does not set up the
115        output virtualization structures used by <STRONG>curses</STRONG>.  The ter-
116        minal  type is the character string <EM>term</EM>; if <EM>term</EM> is null,
117        the environment variable <STRONG>TERM</STRONG> is used.  All output  is  to
118        file  descriptor  <STRONG>fildes</STRONG>  which is initialized for output.
119        If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG> returns  <STRONG>OK</STRONG>  or  <STRONG>ERR</STRONG>
120        and  stores  a  status  value in the integer pointed to by
121        <EM>errret</EM>.  A return value of <STRONG>OK</STRONG> combined with status of <STRONG>1</STRONG> in
122        <EM>errret</EM> is normal.  If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
123
124               <STRONG>1</STRONG>    means that the terminal is hardcopy, cannot be
125                    used for curses applications.
126
127               <STRONG>0</STRONG>    means that the terminal could not be found, or
128                    that  it  is a generic type, having too little
129                    information for curses applications to run.
130
131               <STRONG>-1</STRONG>   means that the <STRONG>terminfo</STRONG> database could not  be
132                    found.
133
134        If  <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon
135        finding an error and exits.  Thus, the simplest call is:
136
137              <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
138
139        which uses all the defaults and sends the output  to  <STRONG>std-</STRONG>
140        <STRONG>out</STRONG>.
141
142        The  <STRONG>setterm</STRONG>  routine is being replaced by <STRONG>setupterm</STRONG>.  The
143        call:
144
145              <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
146
147        provides the same  functionality  as  <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>.   The
148        <STRONG>setterm</STRONG>  routine  is  included here for BSD compatibility,
149        and is not recommended for new programs.
150
151        The <STRONG>set_curterm</STRONG> routine  sets  the  variable  <STRONG>cur_term</STRONG>  to
152        <EM>nterm</EM>, and makes all of the <STRONG>terminfo</STRONG> boolean, numeric, and
153        string variables use the values from  <EM>nterm</EM>.   It  returns
154        the old value of <STRONG>cur_term</STRONG>.
155
156        The  <STRONG>del_curterm</STRONG>  routine  frees  the  space pointed to by
157        <EM>oterm</EM> and makes it available for further use.  If <EM>oterm</EM> is
158        the  same  as  <STRONG>cur_term</STRONG>, references to any of the <STRONG>terminfo</STRONG>
159        boolean, numeric,  and  string  variables  thereafter  may
160        refer  to invalid memory locations until another <STRONG>setupterm</STRONG>
161        has been called.
162
163        The  <STRONG>restartterm</STRONG>  routine  is  similar  to  <STRONG>setupterm</STRONG>  and
164        <STRONG>initscr</STRONG>,  except  that it is called after restoring memory
165        to a previous state (for example, when  reloading  a  game
166        saved  as a core image dump).  It assumes that the windows
167        and the input and output options are the same as when mem-
168        ory  was saved, but the terminal type and baud rate may be
169        different.  Accordingly, it saves various tty state  bits,
170        does a setupterm, and then restores the bits.
171
172        The <STRONG>tparm</STRONG> routine instantiates the string <EM>str</EM> with parame-
173        ters <EM>pi</EM>.  A pointer is returned to the result of <EM>str</EM>  with
174        the parameters applied.
175
176        The  <STRONG>tputs</STRONG>  routine  applies  padding  information  to the
177        string <EM>str</EM> and outputs it.  The <EM>str</EM>  must  be  a  terminfo
178        string  variable  or the return value from <STRONG>tparm</STRONG>, <STRONG>tgetstr</STRONG>,
179        or <STRONG>tgoto</STRONG>.  <EM>affcnt</EM> is the number of lines affected, or 1 if
180        not  applicable.   <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which
181        the characters are passed, one at a time.
182
183        The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>.  Note  that
184        the  output  of  <STRONG>putp</STRONG>  always  goes  to <STRONG>stdout</STRONG>, not to the
185        <EM>fildes</EM> specified in <STRONG>setupterm</STRONG>.
186
187        The <STRONG>vidputs</STRONG> routine displays the string on the terminal in
188        the  video  attribute mode <EM>attrs</EM>, which is any combination
189        of the attributes listed in  <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.   The  characters
190        are passed to the <STRONG>putchar</STRONG>-like routine <EM>putc</EM>.
191
192        The  <STRONG>vidattr</STRONG>  routine  is like the <STRONG>vidputs</STRONG> routine, except
193        that it outputs through <STRONG>putchar</STRONG>.
194
195        The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond  to  vidattr
196        and  vidputs,  respectively.   They use a set of arguments
197        for representing the video attributes  plus  color,  i.e.,
198        one of type attr_t for the attributes and one of short for
199        the color_pair number.  The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines
200        are  designed  to use the attribute constants with the <EM>WA</EM><STRONG>_</STRONG>
201        prefix.  The opts argument is  reserved  for  future  use.
202        Currently,  applications  must  provide a null pointer for
203        that argument.
204
205        The <STRONG>mvcur</STRONG> routine provides low-level  cursor  motion.   It
206        takes   effect   immediately  (rather  than  at  the  next
207        refresh).
208
209        The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines  return  the
210        value  of  the  capability  corresponding  to the <STRONG>terminfo</STRONG>
211        <EM>capname</EM> passed to them, such as <STRONG>xenl</STRONG>.
212
213        The <STRONG>tigetflag</STRONG> routine returns the value <STRONG>-1</STRONG> if  <EM>capname</EM>  is
214        not a boolean capability, or <STRONG>0</STRONG> if it is canceled or absent
215        from the terminal description.
216
217        The <STRONG>tigetnum</STRONG> routine returns the value <STRONG>-2</STRONG>  if  <EM>capname</EM>  is
218        not  a  numeric  capability,  or  <STRONG>-1</STRONG>  if it is canceled or
219        absent from the terminal description.
220
221        The <STRONG>tigetstr</STRONG> routine returns the value <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> if  <EM>cap-</EM>
222        <EM>name</EM> is not a string capability, or <STRONG>0</STRONG> if it is canceled or
223        absent from the terminal description.
224
225        The <EM>capname</EM> for each capability is given in the table col-
226        umn  entitled  <EM>capname</EM> code in the capabilities section of
227        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
228
229        <STRONG>char</STRONG> <STRONG>*boolnames</STRONG>, <STRONG>*boolcodes</STRONG>, <STRONG>*boolfnames</STRONG>
230
231        <STRONG>char</STRONG> <STRONG>*numnames</STRONG>, <STRONG>*numcodes</STRONG>, <STRONG>*numfnames</STRONG>
232
233        <STRONG>char</STRONG> <STRONG>*strnames</STRONG>, <STRONG>*strcodes</STRONG>, <STRONG>*strfnames</STRONG>
234
235        These null-terminated arrays  contain  the  <EM>capnames</EM>,  the
236        <STRONG>termcap</STRONG>  codes, and the full C names, for each of the <STRONG>ter-</STRONG>
237        <STRONG>minfo</STRONG> variables.
238
239
240 </PRE>
241 <H2>RETURN VALUE</H2><PRE>
242        Routines that return an integer return  <STRONG>ERR</STRONG>  upon  failure
243        and  <STRONG>OK</STRONG>  (SVr4 only specifies "an integer value other than
244        <STRONG>ERR</STRONG>") upon successful completion, unless  otherwise  noted
245        in the preceding routine descriptions.
246
247        Routines that return pointers always return <STRONG>NULL</STRONG> on error.
248
249
250 </PRE>
251 <H2>NOTES</H2><PRE>
252        The <STRONG>setupterm</STRONG> routine should be used in place of  <STRONG>setterm</STRONG>.
253        It  may be useful when you want to test for terminal capa-
254        bilities without committing to the allocation  of  storage
255        involved in <STRONG>initscr</STRONG>.
256
257        Note that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
258
259
260 </PRE>
261 <H2>PORTABILITY</H2><PRE>
262        The  function  <STRONG>setterm</STRONG>  is not described in the XSI Curses
263        standard and must be considered non-portable.   All  other
264        functions are as described in the XSI curses standard.
265
266        In  System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type
267        and returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>.  We have chosen  to  implement  the
268        XSI Curses semantics.
269
270        In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
271        type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
272
273        The XSI Curses standard prototypes <STRONG>tparm</STRONG> with a fixed num-
274        ber  of  parameters, rather than a variable argument list.
275        This  implementation  uses  a  variable   argument   list.
276        Portable  applications  should  provide 9 parameters after
277        the format; zeroes are fine for this purpose.
278
279        XSI notes that after calling <STRONG>mvcur</STRONG>, the curses  state  may
280        not  match the actual terminal state, and that an applica-
281        tion should touch and refresh the window  before  resuming
282        normal  curses calls.  Both ncurses and System V Release 4
283        curses implement <STRONG>mvcur</STRONG> using the SCREEN data allocated  in
284        either  <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is documented as
285        a terminfo function, <STRONG>mvcur</STRONG> is  really  a  curses  function
286        which is not well specified.
287
288
289 </PRE>
290 <H2>SEE ALSO</H2><PRE>
291        <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>
292        <STRONG><A HREF="curs_termcap.3x.html">cap(3x)</A></STRONG>, <STRONG><A HREF="putc.3S.html">putc(3S)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327 </PRE>
328 <HR>
329 <ADDRESS>
330 Man(1) output converted with
331 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
332 </ADDRESS>
333 </BODY>
334 </HTML>