X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_trace.3x.html;h=a60ae970276dc6d0273afbf1e9cb70f0ed8cb48f;hp=655998f0e942ab14d45a471cec3966e01a6a4570;hb=a90dd7b66fa711acd24d8181ea20e4f57d4b36cd;hpb=bca50d0d8592defee6c584fdedd25f4b1a31345b;ds=sidebyside diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index 655998f0..a60ae970 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -1,6 +1,7 @@ @@ -34,7 +35,7 @@
- trace, _tracef, _traceattr, _traceattr2, _tracecchar_t, _tracecchar_t2, - _tracechar, _tracechtype, _tracechtype2, _nc_tracebits, _tracedump, - _tracemouse - curses debugging routines + curses_trace, 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); + unsigned curses_trace(const unsigned param); void _tracef(const char *format, ...); @@ -70,46 +71,64 @@ char *_nc_tracebits(void); char *_tracemouse(const MEVENT *event); + /* deprecated */ + void trace(const unsigned int param); +
- 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 curses trace routines are used for debugging the ncurses libraries, + as well as applications which use the ncurses libraries. Some limita- + tions apply: + + o Aside from curses_trace, the other functions are normally available + only with the debugging library e.g., libncurses_g.a. + + All of the trace functions may be compiled into any model (shared, + static, profile) by defining the symbol TRACE. + + o Additionally, the functions which use cchar_t 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 curses_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 (allo- + cated 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 curses_trace function is always available, whether or not the other + trace functions are available: + + o If tracing is available, calling curses_trace with a nonzero param- + eter updates the trace mask, and returns the previous trace mask. - 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. + When the trace mask is nonzero, ncurses creates the file "trace" in + the current directory for output. If the file already exists, no + tracing is done. + + o If tracing is not available, curses_trace returns zero (0).
- The trace parameter is formed by OR'ing values from the list of + 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. + 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 curses_trace function. TRACE_TIMES trace user and system times of updates. @@ -127,11 +146,11 @@ trace all character outputs. TRACE_ORDINARY - trace all update actions. The old and new screen contents are + 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, + trace all curses calls. The parameters for each call are traced, as well as return values. TRACE_VIRTPUT @@ -158,14 +177,14 @@ TRACE_MAXIMUM maximum trace level, enables all of the separate trace features. - Some tracing features are enabled whenever the trace parameter is - nonzero. Some features overlap. The specific names are used as a + Some tracing features are enabled whenever the curses_trace parameter + is nonzero. Some features overlap. The specific names are used as a guideline.
- These functions check the NCURSES_TRACE environment variable, to set - the tracing feature as if trace was called: + These functions check the NCURSES_TRACE environment variable, to set + the tracing feature as if curses_trace was called: filter, initscr, new_prescr, newterm, nofilter, restartterm, ripoffline, setupterm, slk_init, tgetent, use_env, @@ -173,38 +192,65 @@
- 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. - - 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- + The command-line utilities such as tic(1) provide a verbose option + which extends the set of messages written using the curses_trace func- + tion. Both of these (-v and curses_trace) use the same variable + (_nc_tracing), which determines the messages which are written. + + 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, + 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 + 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. + These functions are not part of the XSI interface. Some other curses + implementations are known to have similar features, but they are not + compatible with ncurses: + + o SVr4 provided traceon and traceoff, to control whether debugging + information was written to the "trace" file. While the functions + were always available, this feature was only enabled if DEBUG was + defined when building the library. + + The SVr4 tracing feature is undocumented. + + o PDCurses provides traceon and traceoff, which (like SVr4) are al- + ways available, and enable tracing to the "trace" file only when a + debug-library is built. - A few functions are not provided when symbol versioning is used: + PDCurses has a short description of these functions, with a note + that they are not present in X/Open Curses, ncurses or NetBSD. It + does not mention SVr4, but the functions' inclusion in a header + file section labeled "Quasi-standard" hints at the origin. + + o NetBSD does not provide functions for enabling/disabling traces. + It uses environment variables CURSES_TRACE_MASK and CURS- + ES_TRACE_FILE to determine what is traced, and where the results + are written. This is available only when a debug-library is built. + + The NetBSD tracing feature is undocumented. + + A few ncurses functions are not provided when symbol versioning is + used: _nc_tracebits, _tracedump, _tracemouse + The original trace routine was deprecated because it often conflicted + with application names. +
curses(3x).