X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_trace.3x.html;h=85ffaad03b7ac8008e0ed04e062f224aa42154f0;hp=ab4eaef99224f8fe054f6800691e988ad3770baf;hb=3eda6f30a84d53844d2ebceadb457e2e7e9cfbf3;hpb=6208c89f98f1cf9fe0980bd8e791846ce007a13d diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index ab4eaef9..85ffaad0 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -1,6 +1,6 @@ @@ -46,27 +46,30 @@
- _tracef, _tracedump, _traceattr, _traceattr2, - _nc_tracebits, _tracecchar_t, _tracecchar_t2, _tracechar, - _tracechtype, _tracechtype2, _tracemouse, trace - curses - debugging routines + 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, ...); - void _tracedump(const char *label, WINDOW *win); + char *_traceattr(attr_t attr); char *_traceattr2(int buffer, chtype ch); - char *_nc_tracebits(void); - char * _tracecchar_t(const cchar_t *string); - char * _tracecchar_t2(int buffer, const cchar_t *string); + 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); - void trace(const unsigned int param);
@@ -79,6 +82,8 @@ 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 @@ -87,19 +92,38 @@ o _tracef, which writes formatted data to the trace file. - Calling trace with a nonzero parameter opens the file - trace in the current directory for output. The parameter - is formed by OR'ing values from the list of TRACE_xxx def- - initions in <curses.h>. These include: + 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. + 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 tputs(3x) calls. TRACE_UPDATE trace update actions, old & new screens. @@ -111,8 +135,8 @@ 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- + trace all update actions. The old and new screen + contents are written to the trace file for each re- fresh. TRACE_CALLS @@ -141,28 +165,45 @@ trace changes to video attributes and colors. TRACE_MAXIMUM - maximum trace level, enables all of the separate + 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 + Some tracing features are enabled whenever the trace pa- + rameter is nonzero. Some features overlap. The specific names are used as a guideline. - 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. +
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, tge- - tent, use_env, use_extended_names, use_tioctl + 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.
@@ -176,6 +217,11 @@ 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). @@ -188,7 +234,14 @@