ncurses 5.5
[ncurses.git] / doc / html / man / curs_termcap.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   ****************************************************************************
4   * Copyright (c) 1998-2002,2003 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_termcap.3x,v 1.18 2003/02/08 22:25:47 tom Exp @
31 -->
32 <HTML>
33 <HEAD>
34 <TITLE>curs_termcap 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_termcap 3x</H1>
40 <HR>
41 <PRE>
42 <!-- Manpage converted by man2html 3.0.1 -->
43 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>                                       <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
44
45
46
47
48 </PRE>
49 <H2>NAME</H2><PRE>
50        <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, <STRONG>tgetstr</STRONG>, <STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG> - direct
51        <STRONG>curses</STRONG> interface to the terminfo capability database
52
53
54 </PRE>
55 <H2>SYNOPSIS</H2><PRE>
56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
57        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
58        <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>PC;</STRONG> <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG> <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG> <STRONG>extern</STRONG>
59        <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
60        <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*bp,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*name);</STRONG>
61        <STRONG>int</STRONG> <STRONG>tgetflag(char</STRONG> <STRONG>*id);</STRONG>
62        <STRONG>int</STRONG> <STRONG>tgetnum(char</STRONG> <STRONG>*id);</STRONG>
63        <STRONG>char</STRONG> <STRONG>*tgetstr(char</STRONG> <STRONG>*id,</STRONG> <STRONG>char</STRONG> <STRONG>**area);</STRONG>
64        <STRONG>char</STRONG> <STRONG>*tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*cap,</STRONG> <STRONG>int</STRONG> <STRONG>col,</STRONG> <STRONG>int</STRONG> <STRONG>row);</STRONG>
65        <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>affcnt,</STRONG> <STRONG>int</STRONG> <STRONG>(*putc)(int));</STRONG>
66
67
68 </PRE>
69 <H2>DESCRIPTION</H2><PRE>
70        These  routines  are included as a conversion aid for pro-
71        grams that use the <EM>termcap</EM> library.  Their parameters  are
72        the  same and the routines are emulated using the <EM>terminfo</EM>
73        database.  Thus, they can only be used to query the  capa-
74        bilities  of  entries  for which a terminfo entry has been
75        compiled.
76
77        The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>.  It  returns
78        1  on  success, 0 if there is no such entry, and -1 if the
79        terminfo database  could  not  be  found.   The  emulation
80        ignores the buffer pointer <EM>bp</EM>.
81
82        The  <STRONG>tgetflag</STRONG>  routine  gets  the boolean entry for <EM>id</EM>, or
83        zero if it is not available.
84
85        The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>,  or  -1
86        if it is not available.
87
88        The  <STRONG>tgetstr</STRONG>  routine  returns the string entry for <EM>id</EM>, or
89        zero if it is not available.   Use  <STRONG>tputs</STRONG>  to  output  the
90        returned  string.  The return value will also be copied to
91        the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will  be
92        updated to point past the null ending this value.
93
94        Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tget-</STRONG>
95        <STRONG>flag</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetstr</STRONG> are compared in lookups.
96
97        The <STRONG>tgoto</STRONG> routine instantiates  the  parameters  into  the
98        given  capability.   The output from this routine is to be
99        passed to <STRONG>tputs</STRONG>.
100
101        The <STRONG>tputs</STRONG> routine is described  on  the  <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
102        manual page.  It can retrieve capabilities by either term-
103        cap or terminfo name.
104
105        The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the ter-
106        minfo   entry's   data   for   <STRONG>pad_char</STRONG>,   <STRONG>cursor_up</STRONG>   and
107        <STRONG>backspace_if_not_bs</STRONG>, respectively.   <STRONG>UP</STRONG>  is  not  used  by
108        ncurses.  <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function.  <STRONG>BC</STRONG> is
109        used in the <STRONG>tgoto</STRONG> emulation.  The variable <STRONG>ospeed</STRONG>  is  set
110        by ncurses in a system-specific coding to reflect the ter-
111        minal speed.
112
113
114
115 </PRE>
116 <H2>RETURN VALUE</H2><PRE>
117        Except where explicitly noted,  routines  that  return  an
118        integer   return  <STRONG>ERR</STRONG>  upon  failure  and  <STRONG>OK</STRONG>  (SVr4  only
119        specifies "an integer value other than <STRONG>ERR</STRONG>") upon success-
120        ful completion.
121
122        Routines that return pointers return <STRONG>NULL</STRONG> on error.
123
124
125 </PRE>
126 <H2>BUGS</H2><PRE>
127        If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized
128        string, be aware that it  will  be  returned  in  terminfo
129        notation,  not  the older and not-quite-compatible termcap
130        notation.  This won't cause problems if all you do with it
131        is  call  <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo-style
132        strings as terminfo.  (The <STRONG>tgoto</STRONG> function,  if  configured
133        to  support  termcap,  will  check if the string is indeed
134        terminfo-style by looking for "%p" parameters  or  "$&lt;..&gt;"
135        delays,  and  invoke  a termcap-style parser if the string
136        does not appear to be terminfo).
137
138        Because terminfo conventions for representing  padding  in
139        string  capabilities  differ  from termcap's, <STRONG>tputs("50");</STRONG>
140        will put out a literal "50" rather than  busy-waiting  for
141        50 milliseconds.  Cope with it.
142
143        Note  that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG>
144        string.  One consequence of this is that termcap  applica-
145        tions  assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter-
146        nate character set.  This implementation checks  for,  and
147        modifies the data shown to the termcap interface to accom-
148        modate termcap's limitation in this respect.
149
150
151 </PRE>
152 <H2>PORTABILITY</H2><PRE>
153        The XSI Curses standard, Issue  4  describes  these  func-
154        tions.   However,  they are marked TO BE WITHDRAWN and may
155        be removed in future versions.
156
157        Neither the XSI Curses standard nor  the  SVr4  man  pages
158        documented  the return values of <STRONG>tgetent</STRONG> correctly, though
159        all three were in fact returned ever since SVr1.  In  par-
160        ticular,  an  omission in the XSI Curses documentation has
161        been misinterpreted to mean that  <STRONG>tgetent</STRONG>  returns  <STRONG>OK</STRONG>  or
162        <STRONG>ERR</STRONG>.  Because the purpose of these functions is to provide
163        compatibility with the <EM>termcap</EM> library, that is  a  defect
164        in XCurses, Issue 4, Version 2 rather than in ncurses.
165
166        External  variables  are  provided  for support of certain
167        termcap applications.  However, termcap applications'  use
168        of those variables is poorly documented, e.g., not distin-
169        guishing between input and output.   In  particular,  some
170        applications are reported to declare and/or modify <STRONG>ospeed</STRONG>.
171
172
173 </PRE>
174 <H2>SEE ALSO</H2><PRE>
175        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="putc.3S.html">putc(3S)</A></STRONG>.
176
177
178
179                                                        <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
180 </PRE>
181 <HR>
182 <ADDRESS>
183 Man(1) output converted with
184 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
185 </ADDRESS>
186 </BODY>
187 </HTML>