X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_trace.3x.html;h=7cb64bd4cece0bcfe57e6c7612fd7174a9c35d31;hp=f56481db552b2bc2b99d2e3e95ab7911b6e9318b;hb=06078d3fa68db669ed37178c01873546b4b28745;hpb=71c0306f0824ef2b10c4c5813fb003db48f3012e diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index f56481db..7cb64bd4 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -1,7 +1,6 @@ - +
+ +- -curs_trace(3x) curs_trace(3x) +curs_trace(3x) curs_trace(3x) --
- _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 _tracef(const char *format, ...); - void _tracedump(const char *label, WINDOW *win); - char *_traceattr(attr_t attr); - char *_traceattr2(int buffer, chtype ch); + 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 * _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); - char *_tracemouse(const MEVENT *event); - void trace(const unsigned int param); + 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 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 li- - braries. - - The principal parts of this interface are the trace rou- - tine which selectively enables different tracing features, - and the _tracef routine 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: - - TRACE_DISABLE - turn off tracing. - - TRACE_TIMES +
+ The trace routines are used for debugging the ncurses libraries, as + well as applications which use the ncurses libraries. These functions + are normally available only with the debugging library e.g., libncurs- + es_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 func- + tion, some use a buffer-number parameter, telling the library to allo- + cate additional string-areas. + + +
+ The trace parameter is formed by OR'ing values from the list of + TRACE_xxx definitions in <curses.h>. These include: + + TRACE_DISABLE + turn off tracing by passing a zero parameter. + + The library flushes the output file, but retains an open file-de- + scriptor 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 + trace tputs(3x) calls. - TRACE_UPDATE + TRACE_UPDATE trace update actions, old & new screens. - TRACE_MOVE + TRACE_MOVE trace cursor movement and scrolling. - TRACE_CHARPUT + 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_ORDINARY + trace all update actions. The old and new screen contents are + written to the trace file for each refresh. - TRACE_CALLS - trace all curses calls. The parameters for each call - are traced, as well as return values. + TRACE_CALLS + trace all curses calls. The parameters for each call are traced, + as well as return values. - TRACE_VIRTPUT + TRACE_VIRTPUT trace virtual character puts, i.e., calls to addch. - TRACE_IEVENT + TRACE_IEVENT trace low-level input processing, including timeouts. - TRACE_BITS + TRACE_BITS trace state of TTY control bits. - TRACE_ICALLS + TRACE_ICALLS trace internal/nested calls. - TRACE_CCALLS + TRACE_CCALLS trace per-character calls. - TRACE_DATABASE + TRACE_DATABASE trace read/write of terminfo/termcap data. - TRACE_ATTRS + TRACE_ATTRS trace changes to video attributes and colors. - TRACE_MAXIMUM - maximum trace level, enables all of the separate - trace features. + 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. + Some tracing features are enabled whenever the trace parameter 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, - ripoffline, setupterm, slk_init, tgetent +
+ These functions check the NCURSES_TRACE environment variable, 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. +
+ The command-line utilities such as tic(1) provide a verbose option + which extends the set of messages written using the trace function. + Both of these (-v and trace) use the same variable (_nc_tracing), which + determines the messages which are written. --
- 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. + Because the command-line utilities may call initialization functions + such as setupterm, tgetent or use_extended_names, some of their debug- + ging output may be directed to the trace file if the NCURSES_TRACE en- + vironment variable is set: + o messages produced in the utility are written to the standard error. --
+ o messages produced by the underlying library are written 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 + + +
curses(3x). - curs_trace(3x) + curs_trace(3x)-