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(3x) 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
The command-line utilities such as tic(1) provide a ver- bose option which extends the set of messages written us- ing the trace function. Both of these (-v and trace) use the same variable (_nc_tracing), which determines the mes- sages which are written. Because the command-line utilities may call initialization functions such as setupterm, tgetent or use_extend- ed_names, some of their debugging output may be directed to the trace file if the NCURSES_TRACE environment vari- able is set: o messages produced in the utility are written to the standard error. o messages produced by the underlying library are writ- ten to trace. If ncurses is built without tracing, none of the latter are produced, and fewer diagnostics are provided by the command-line utilities.
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