http://invisible-island.net/ncurses/man/


curs_trace 3x

curs_trace(3x)                                           curs_trace(3x)




NAME

       trace, _tracef, _traceattr, _traceattr2, _tracecchar_t,
       _tracecchar_t2, _tracechar, _tracechtype, _tracechtype2,
       _nc_tracebits, _tracedump, _tracemouse - curses debugging
       routines


SYNOPSIS

       #include <curses.h>

       void trace(const unsigned int param);

       void _tracef(const char *format, ...);

       char *_traceattr(attr_t attr);
       char *_traceattr2(int buffer, chtype ch);
       char *_tracecchar_t(const cchar_t *string);
       char *_tracecchar_t2(int buffer, const cchar_t *string);
       char *_tracechar(int ch);
       char *_tracechtype(chtype ch);
       char *_tracechtype2(int buffer, chtype ch);

       void _tracedump(const char *label, WINDOW *win);
       char *_nc_tracebits(void);
       char *_tracemouse(const MEVENT *event);


DESCRIPTION

       The trace routines are used for debugging the ncurses  li-
       braries, as well as applications which use the ncurses li-
       braries.  These functions are normally available only with
       the  debugging  library  e.g.,  libncurses_g.a, but may be
       compiled into  any  model  (shared,  static,  profile)  by
       defining  the  symbol TRACE.  Additionally, some functions
       are only available with the  wide-character  configuration
       of the libraries.


Functions

       The principal parts of this interface are

       o   trace,  which  selectively  enables  different tracing
           features, and

       o   _tracef, which writes  formatted  data  to  the  trace
           file.

       Calling  trace  with  a nonzero parameter creates the file
       trace in the current directory for output.   If  the  file
       already exists, no tracing is done.

       The  other  functions either return a pointer to a string-
       area (allocated by the corresponding function), or  return
       no  value (such as _tracedump, which implements the screen
       dump for TRACE_UPDATE).  The caller should not free  these
       strings,  since  the  allocation  is  reused on successive
       calls.  To work around the problem of a single string-area
       per  function, some use a buffer-number parameter, telling
       the library to allocate additional string-areas.


Trace Parameter

       The trace parameter is formed by OR'ing  values  from  the
       list  of  TRACE_xxx  definitions in <curses.h>.  These in-
       clude:

       TRACE_DISABLE
            turn off tracing by passing a zero parameter.

            The library flushes the output file, but  retains  an
            open file-descriptor to the trace file so that it can
            resume tracing later if a nonzero parameter is passed
            to the trace function.

       TRACE_TIMES
            trace user and system times of updates.

       TRACE_TPUTS
            trace tputs calls.

       TRACE_UPDATE
            trace update actions, old & new screens.

       TRACE_MOVE
            trace cursor movement and scrolling.

       TRACE_CHARPUT
            trace all character outputs.

       TRACE_ORDINARY
            trace  all  update  actions.   The old and new screen
            contents are written to the trace file for  each  re-
            fresh.

       TRACE_CALLS
            trace all curses calls.  The parameters for each call
            are traced, as well as return values.

       TRACE_VIRTPUT
            trace virtual character puts, i.e., calls to addch.

       TRACE_IEVENT
            trace low-level input processing, including timeouts.

       TRACE_BITS
            trace state of TTY control bits.

       TRACE_ICALLS
            trace internal/nested calls.

       TRACE_CCALLS
            trace per-character calls.

       TRACE_DATABASE
            trace read/write of terminfo/termcap data.

       TRACE_ATTRS
            trace changes to video attributes and colors.

       TRACE_MAXIMUM
            maximum trace level,  enables  all  of  the  separate
            trace features.

       Some  tracing  features are enabled whenever the trace pa-
       rameter is nonzero.  Some features overlap.  The  specific
       names are used as a guideline.


Initialization

       These  functions check the NCURSES_TRACE environment vari-
       able, to set the tracing feature as if trace was called:

           filter, initscr, new_prescr, newterm, nofilter,
           restartterm, ripoffline, setupterm, slk_init, tgetent,
           use_env, use_extended_names, use_tioctl


RETURN VALUE

       Routines which return a value are designed to be  used  as
       parameters to the _tracef routine.


PORTABILITY

       These  functions  are not part of the XSI interface.  Some
       other curses implementations are known  to  have  similar,
       undocumented  features,  but  they are not compatible with
       ncurses.

       A few functions are not provided when symbol versioning is
       used:

           _nc_tracebits, _tracedump, _tracemouse


SEE ALSO

       curses(3x).



                                                         curs_trace(3x)