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>