curs_trace(3x) curs_trace(3x)
trace, _tracef, _traceattr, _traceattr2, _tracecchar_t,
_tracecchar_t2, _tracechar, _tracechtype, _tracechtype2,
_nc_tracebits, _tracedump, _tracemouse - curses debugging
routines
#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);
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.
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.
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.
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
Routines which return a value are designed to be used as
parameters to the _tracef routine.
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
curses(3x).
curs_trace(3x)