ncurses 6.0 - patch 20170401
[ncurses.git] / doc / html / man / curs_trace.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 2000-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_trace.3x,v 1.18 2017/01/14 19:46:40 tom Exp @
30 -->
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
32 <HTML>
33 <HEAD>
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_trace 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 </HEAD>
40 <BODY>
41 <H1 class="no-header">curs_trace 3x</H1>
42 <PRE>
43 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>                                           <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
44
45
46
47
48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
49        <STRONG>trace</STRONG>, <STRONG>_tracef</STRONG>, <STRONG>_traceattr</STRONG>, <STRONG>_traceattr2</STRONG>, <STRONG>_tracecchar_t</STRONG>,
50        <STRONG>_tracecchar_t2</STRONG>, <STRONG>_tracechar</STRONG>, <STRONG>_tracechtype</STRONG>, <STRONG>_tracechtype2</STRONG>,
51        <STRONG>_nc_tracebits</STRONG>, <STRONG>_tracedump</STRONG>, <STRONG>_tracemouse</STRONG> - <STRONG>curses</STRONG> debugging
52        routines
53
54
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
57
58        <STRONG>void</STRONG> <STRONG>trace(const</STRONG> <STRONG>unsigned</STRONG> <STRONG>int</STRONG> <EM>param</EM><STRONG>);</STRONG>
59
60        <STRONG>void</STRONG> <STRONG>_tracef(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>format</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
61
62        <STRONG>char</STRONG> <STRONG>*_traceattr(attr_t</STRONG> <EM>attr</EM><STRONG>);</STRONG>
63        <STRONG>char</STRONG> <STRONG>*_traceattr2(int</STRONG> <EM>buffer</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
64        <STRONG>char</STRONG> <STRONG>*_tracecchar_t(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>string</EM><STRONG>);</STRONG>
65        <STRONG>char</STRONG> <STRONG>*_tracecchar_t2(int</STRONG> <EM>buffer</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>string</EM><STRONG>);</STRONG>
66        <STRONG>char</STRONG> <STRONG>*_tracechar(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
67        <STRONG>char</STRONG> <STRONG>*_tracechtype(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
68        <STRONG>char</STRONG> <STRONG>*_tracechtype2(int</STRONG> <EM>buffer</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
69
70        <STRONG>void</STRONG> <STRONG>_tracedump(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
71        <STRONG>char</STRONG> <STRONG>*_nc_tracebits(void);</STRONG>
72        <STRONG>char</STRONG> <STRONG>*_tracemouse(const</STRONG> <STRONG>MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
73
74
75 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
76        The <STRONG>trace</STRONG> routines are used for debugging the ncurses  li-
77        braries, as well as applications which use the ncurses li-
78        braries.  These functions are normally available only with
79        the  debugging  library  e.g.,  <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>, but may be
80        compiled into  any  model  (shared,  static,  profile)  by
81        defining  the  symbol <STRONG>TRACE</STRONG>.  Additionally, some functions
82        are only available with the  wide-character  configuration
83        of the libraries.
84
85
86 </PRE><H3><a name="h3-Functions">Functions</a></H3><PRE>
87        The principal parts of this interface are
88
89        <STRONG>o</STRONG>   <STRONG>trace</STRONG>,  which  selectively  enables  different tracing
90            features, and
91
92        <STRONG>o</STRONG>   <STRONG>_tracef</STRONG>, which writes  formatted  data  to  the  <EM>trace</EM>
93            file.
94
95        Calling  <STRONG>trace</STRONG>  with  a nonzero parameter creates the file
96        <STRONG>trace</STRONG> in the current directory for output.   If  the  file
97        already exists, no tracing is done.
98
99        The  other  functions either return a pointer to a string-
100        area (allocated by the corresponding function), or  return
101        no  value (such as <STRONG>_tracedump</STRONG>, which implements the screen
102        dump for <STRONG>TRACE_UPDATE</STRONG>).  The caller should not free  these
103        strings,  since  the  allocation  is  reused on successive
104        calls.  To work around the problem of a single string-area
105        per  function, some use a buffer-number parameter, telling
106        the library to allocate additional string-areas.
107
108
109 </PRE><H3><a name="h3-Trace-Parameter">Trace Parameter</a></H3><PRE>
110        The trace parameter is formed by OR'ing  values  from  the
111        list  of  <STRONG>TRACE_</STRONG><EM>xxx</EM>  definitions in <STRONG>&lt;curses.h&gt;</STRONG>.  These in-
112        clude:
113
114        <STRONG>TRACE_DISABLE</STRONG>
115             turn off tracing by passing a zero parameter.
116
117             The library flushes the output file, but  retains  an
118             open file-descriptor to the trace file so that it can
119             resume tracing later if a nonzero parameter is passed
120             to the <STRONG>trace</STRONG> function.
121
122        <STRONG>TRACE_TIMES</STRONG>
123             trace user and system times of updates.
124
125        <STRONG>TRACE_TPUTS</STRONG>
126             trace <STRONG><A HREF="curs_terminfo.3x.html">tputs(3x)</A></STRONG> calls.
127
128        <STRONG>TRACE_UPDATE</STRONG>
129             trace update actions, old &amp; new screens.
130
131        <STRONG>TRACE_MOVE</STRONG>
132             trace cursor movement and scrolling.
133
134        <STRONG>TRACE_CHARPUT</STRONG>
135             trace all character outputs.
136
137        <STRONG>TRACE_ORDINARY</STRONG>
138             trace  all  update  actions.   The old and new screen
139             contents are written to the trace file for  each  re-
140             fresh.
141
142        <STRONG>TRACE_CALLS</STRONG>
143             trace all curses calls.  The parameters for each call
144             are traced, as well as return values.
145
146        <STRONG>TRACE_VIRTPUT</STRONG>
147             trace virtual character puts, i.e., calls to <STRONG>addch</STRONG>.
148
149        <STRONG>TRACE_IEVENT</STRONG>
150             trace low-level input processing, including timeouts.
151
152        <STRONG>TRACE_BITS</STRONG>
153             trace state of TTY control bits.
154
155        <STRONG>TRACE_ICALLS</STRONG>
156             trace internal/nested calls.
157
158        <STRONG>TRACE_CCALLS</STRONG>
159             trace per-character calls.
160
161        <STRONG>TRACE_DATABASE</STRONG>
162             trace read/write of terminfo/termcap data.
163
164        <STRONG>TRACE_ATTRS</STRONG>
165             trace changes to video attributes and colors.
166
167        <STRONG>TRACE_MAXIMUM</STRONG>
168             maximum trace level,  enables  all  of  the  separate
169             trace features.
170
171        Some  tracing  features are enabled whenever the <STRONG>trace</STRONG> pa-
172        rameter is nonzero.  Some features overlap.  The  specific
173        names are used as a guideline.
174
175
176 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
177        These  functions check the <STRONG>NCURSES_TRACE</STRONG> environment vari-
178        able, to set the tracing feature as if <STRONG>trace</STRONG> was called:
179
180            filter, initscr, new_prescr, newterm, nofilter,
181            restartterm, ripoffline, setupterm, slk_init, tgetent,
182            use_env, use_extended_names, use_tioctl
183
184
185 </PRE><H3><a name="h3-Command-line-Utilities">Command-line Utilities</a></H3><PRE>
186        The command-line utilities such as <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> provide  a  ver-
187        bose  option which extends the set of messages written us-
188        ing the <STRONG>trace</STRONG> function.  Both of these (<STRONG>-v</STRONG> and <STRONG>trace</STRONG>)  use
189        the same variable (<STRONG>_nc_tracing</STRONG>), which determines the mes-
190        sages which are written.
191
192        Because the command-line utilities may call initialization
193        functions   such  as  <STRONG>setupterm</STRONG>,  <STRONG>tgetent</STRONG>  or  <STRONG>use_extend-</STRONG>
194        <STRONG>ed_names</STRONG>, some of their debugging output may  be  directed
195        to  the  <EM>trace</EM> file if the <STRONG>NCURSES_TRACE</STRONG> environment vari-
196        able is set:
197
198        <STRONG>o</STRONG>   messages produced in the utility are  written  to  the
199            standard error.
200
201        <STRONG>o</STRONG>   messages  produced by the underlying library are writ-
202            ten to <EM>trace</EM>.
203
204        If ncurses is built without tracing, none  of  the  latter
205        are  produced,  and  fewer diagnostics are provided by the
206        command-line utilities.
207
208
209 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
210        Routines which return a value are designed to be  used  as
211        parameters to the <STRONG>_tracef</STRONG> routine.
212
213
214 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
215        These  functions  are not part of the XSI interface.  Some
216        other curses implementations are known  to  have  similar,
217        undocumented  features,  but  they are not compatible with
218        ncurses.
219
220        A few functions are not provided when symbol versioning is
221        used:
222
223            _nc_tracebits, _tracedump, _tracemouse
224
225
226 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
227        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
228
229
230
231                                                          <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
232 </PRE>
233 <div class="nav">
234 <ul>
235 <li><a href="#h2-NAME">NAME</a></li>
236 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
237 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
238 <ul>
239 <li><a href="#h3-Functions">Functions</a></li>
240 <li><a href="#h3-Trace-Parameter">Trace Parameter</a></li>
241 <li><a href="#h3-Initialization">Initialization</a></li>
242 <li><a href="#h3-Command-line-Utilities">Command-line Utilities</a></li>
243 </ul>
244 </li>
245 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
246 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
247 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
248 </ul>
249 </div>
250 </BODY>
251 </HTML>