doc/html/man/curs_trace.3x.html

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