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