ncurses 6.1 - patch 20191207
[ncurses.git] / doc / html / man / curs_trace.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 2000-2017,2019 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.20 2019/12/07 18:55:02 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 https://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_trace 3x</TITLE>
37 <link rel="author" 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>curses_trace</STRONG>, <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>, <STRONG>_nc_tracebits</STRONG>,
51        <STRONG>_tracedump</STRONG>, <STRONG>_tracemouse</STRONG> - <STRONG>curses</STRONG> debugging routines
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
56
57        <STRONG>unsigned</STRONG> <STRONG>curses_trace(const</STRONG> <STRONG>unsigned</STRONG> <EM>param</EM><STRONG>);</STRONG>
58
59        <STRONG>void</STRONG> <STRONG>_tracef(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>format</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
60
61        <STRONG>char</STRONG> <STRONG>*_traceattr(attr_t</STRONG> <EM>attr</EM><STRONG>);</STRONG>
62        <STRONG>char</STRONG> <STRONG>*_traceattr2(int</STRONG> <EM>buffer</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
63        <STRONG>char</STRONG> <STRONG>*_tracecchar_t(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>string</EM><STRONG>);</STRONG>
64        <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>
65        <STRONG>char</STRONG> <STRONG>*_tracechar(int</STRONG> <EM>ch</EM><STRONG>);</STRONG>
66        <STRONG>char</STRONG> <STRONG>*_tracechtype(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
67        <STRONG>char</STRONG> <STRONG>*_tracechtype2(int</STRONG> <EM>buffer</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
68
69        <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>
70        <STRONG>char</STRONG> <STRONG>*_nc_tracebits(void);</STRONG>
71        <STRONG>char</STRONG> <STRONG>*_tracemouse(const</STRONG> <STRONG>MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG>
72
73        /* deprecated */
74        <STRONG>void</STRONG> <STRONG>trace(const</STRONG> <STRONG>unsigned</STRONG> <STRONG>int</STRONG> <EM>param</EM><STRONG>);</STRONG>
75
76
77 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
78        The <EM>curses</EM> <EM>trace</EM> routines are used for debugging the ncurses libraries,
79        as well as applications which use the ncurses libraries.  Some  limita-
80        tions apply:
81
82        <STRONG>o</STRONG>   Aside from <STRONG>curses_trace</STRONG>, the other functions are normally available
83            only with the debugging library e.g., <EM>libncurses</EM><STRONG>_</STRONG><EM>g.a</EM>.
84
85            All of the trace functions may be compiled into any model  (shared,
86            static, profile) by defining the symbol <STRONG>TRACE</STRONG>.
87
88        <STRONG>o</STRONG>   Additionally,  the  functions  which use <STRONG>cchar_t</STRONG> are only available
89            with the wide-character configuration of the libraries.
90
91
92 </PRE><H3><a name="h3-Functions">Functions</a></H3><PRE>
93        The principal parts of this interface are
94
95        <STRONG>o</STRONG>   <STRONG>curses_trace</STRONG>, which selectively enables different tracing features,
96            and
97
98        <STRONG>o</STRONG>   <STRONG>_tracef</STRONG>, which writes formatted data to the <EM>trace</EM> file.
99
100            The other functions either return a pointer to a string-area (allo-
101            cated by the corresponding function), or return no value  (such  as
102            <STRONG>_tracedump</STRONG>,  which  implements  the  screen dump for <STRONG>TRACE_UPDATE</STRONG>).
103            The caller should not free these strings, since the  allocation  is
104            reused on successive calls.  To work around the problem of a single
105            string-area per  function,  some  use  a  buffer-number  parameter,
106            telling the library to allocate additional string-areas.
107
108        The <STRONG>curses_trace</STRONG> function is always available, whether or not the other
109        trace functions are available:
110
111        <STRONG>o</STRONG>   If tracing is available, calling <STRONG>curses_trace</STRONG> with a nonzero param-
112            eter updates the trace mask, and returns the previous trace mask.
113
114            When the trace mask is nonzero, ncurses creates the file "trace" in
115            the current directory for output.  If the file already  exists,  no
116            tracing is done.
117
118        <STRONG>o</STRONG>   If tracing is not available, <STRONG>curses_trace</STRONG> returns zero (0).
119
120
121 </PRE><H3><a name="h3-Trace-Parameter">Trace Parameter</a></H3><PRE>
122        The  trace  parameter  is  formed  by  OR'ing  values  from the list of
123        <STRONG>TRACE_</STRONG><EM>xxx</EM> definitions in <STRONG>&lt;curses.h&gt;</STRONG>.  These include:
124
125        <STRONG>TRACE_DISABLE</STRONG>
126             turn off tracing by passing a zero parameter.
127
128             The library flushes the output file, but retains an open  file-de-
129             scriptor  to the trace file so that it can resume tracing later if
130             a nonzero parameter is passed to the <STRONG>curses_trace</STRONG> function.
131
132        <STRONG>TRACE_TIMES</STRONG>
133             trace user and system times of updates.
134
135        <STRONG>TRACE_TPUTS</STRONG>
136             trace <STRONG><A HREF="curs_terminfo.3x.html">tputs(3x)</A></STRONG> calls.
137
138        <STRONG>TRACE_UPDATE</STRONG>
139             trace update actions, old &amp; new screens.
140
141        <STRONG>TRACE_MOVE</STRONG>
142             trace cursor movement and scrolling.
143
144        <STRONG>TRACE_CHARPUT</STRONG>
145             trace all character outputs.
146
147        <STRONG>TRACE_ORDINARY</STRONG>
148             trace all update actions.  The old and  new  screen  contents  are
149             written to the trace file for each refresh.
150
151        <STRONG>TRACE_CALLS</STRONG>
152             trace  all curses calls.  The parameters for each call are traced,
153             as well as return values.
154
155        <STRONG>TRACE_VIRTPUT</STRONG>
156             trace virtual character puts, i.e., calls to <STRONG>addch</STRONG>.
157
158        <STRONG>TRACE_IEVENT</STRONG>
159             trace low-level input processing, including timeouts.
160
161        <STRONG>TRACE_BITS</STRONG>
162             trace state of TTY control bits.
163
164        <STRONG>TRACE_ICALLS</STRONG>
165             trace internal/nested calls.
166
167        <STRONG>TRACE_CCALLS</STRONG>
168             trace per-character calls.
169
170        <STRONG>TRACE_DATABASE</STRONG>
171             trace read/write of terminfo/termcap data.
172
173        <STRONG>TRACE_ATTRS</STRONG>
174             trace changes to video attributes and colors.
175
176        <STRONG>TRACE_MAXIMUM</STRONG>
177             maximum trace level, enables all of the separate trace features.
178
179        Some tracing features are enabled whenever the  <STRONG>curses_trace</STRONG>  parameter
180        is  nonzero.   Some features overlap.  The specific names are used as a
181        guideline.
182
183
184 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
185        These functions check the <STRONG>NCURSES_TRACE</STRONG> environment  variable,  to  set
186        the tracing feature as if <STRONG>curses_trace</STRONG> was called:
187
188            filter, initscr, new_prescr, newterm, nofilter, restartterm,
189            ripoffline, setupterm, slk_init, tgetent, use_env,
190            use_extended_names, use_tioctl
191
192
193 </PRE><H3><a name="h3-Command-line-Utilities">Command-line Utilities</a></H3><PRE>
194        The  command-line  utilities  such  as  <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> provide a verbose option
195        which extends the set of messages written using the <STRONG>curses_trace</STRONG>  func-
196        tion.   Both  of  these  (<STRONG>-v</STRONG>  and  <STRONG>curses_trace</STRONG>)  use the same variable
197        (<STRONG>_nc_tracing</STRONG>), which determines the messages which are written.
198
199        Because the command-line utilities may  call  initialization  functions
200        such  as <STRONG>setupterm</STRONG>, <STRONG>tgetent</STRONG> or <STRONG>use_extended_names</STRONG>, some of their debug-
201        ging output may be directed to the <EM>trace</EM> file if the <STRONG>NCURSES_TRACE</STRONG>  en-
202        vironment variable is set:
203
204        <STRONG>o</STRONG>   messages produced in the utility are written to the standard error.
205
206        <STRONG>o</STRONG>   messages produced by the underlying library are written to <EM>trace</EM>.
207
208        If  ncurses  is built without tracing, none of the latter are produced,
209        and fewer diagnostics are provided by the command-line utilities.
210
211
212 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
213        Routines which return a value are designed to be used as parameters  to
214        the <STRONG>_tracef</STRONG> routine.
215
216
217 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
218        These  functions  are not part of the XSI interface.  Some other curses
219        implementations are known to have similar features, but  they  are  not
220        compatible with ncurses:
221
222        <STRONG>o</STRONG>   SVr4  provided  <STRONG>traceon</STRONG>  and <STRONG>traceoff</STRONG>, to control whether debugging
223            information was written to the "trace" file.  While  the  functions
224            were  always  available, this feature was only enabled if <STRONG>DEBUG</STRONG> was
225            defined when building the library.
226
227            The SVr4 tracing feature is undocumented.
228
229        <STRONG>o</STRONG>   PDCurses provides <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, which (like SVr4)  are  al-
230            ways  available, and enable tracing to the "trace" file only when a
231            debug-library is built.
232
233            PDCurses has a short description of these functions,  with  a  note
234            that  they are not present in X/Open Curses, ncurses or NetBSD.  It
235            does not mention SVr4, but the functions'  inclusion  in  a  header
236            file section labeled "Quasi-standard" hints at the origin.
237
238        <STRONG>o</STRONG>   NetBSD  does  not  provide functions for enabling/disabling traces.
239            It  uses  environment   variables   <STRONG>CURSES_TRACE_MASK</STRONG>   and   <STRONG>CURS-</STRONG>
240            <STRONG>ES_TRACE_FILE</STRONG>  to  determine  what is traced, and where the results
241            are written.  This is available only when a debug-library is built.
242
243            The NetBSD tracing feature is undocumented.
244
245        A few ncurses functions are not  provided  when  symbol  versioning  is
246        used:
247
248            _nc_tracebits, _tracedump, _tracemouse
249
250        The  original  <STRONG>trace</STRONG> routine was deprecated because it often conflicted
251        with application names.
252
253
254 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
255        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
256
257
258
259                                                                 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
260 </PRE>
261 <div class="nav">
262 <ul>
263 <li><a href="#h2-NAME">NAME</a></li>
264 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
265 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
266 <ul>
267 <li><a href="#h3-Functions">Functions</a></li>
268 <li><a href="#h3-Trace-Parameter">Trace Parameter</a></li>
269 <li><a href="#h3-Initialization">Initialization</a></li>
270 <li><a href="#h3-Command-line-Utilities">Command-line Utilities</a></li>
271 </ul>
272 </li>
273 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
274 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
275 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
276 </ul>
277 </div>
278 </BODY>
279 </HTML>