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>