X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_trace.3x.html;h=c1ea937fd64b6c077e56fab5333385dc21aea9fd;hb=e2153a14ebfb90265151d608778aaf9f403b3d24;hp=658be0e542d9f478490f4bc77f0a3b0d2d6fbb18;hpb=81304798ee736c467839c779c9ca5dca48db7bea;p=ncurses.git diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index 658be0e5..c1ea937f 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -1,6 +1,6 @@
--curs_trace(3x) curs_trace(3x) +curs_trace(3x) Library calls curs_trace(3x)
- curses_trace, trace, _tracef, _traceattr, _traceattr2, _tracecchar_t, + curses_trace, trace, _tracef, _traceattr, _traceattr2, _tracecchar_t, _tracecchar_t2, _tracechar, _tracechtype, _tracechtype2, _nc_tracebits, - _tracedump, _tracemouse - curses debugging routines + _tracedump, _tracemouse - curses debugging routines
#include <curses.h> - unsigned curses_trace(const unsigned param); + unsigned curses_trace(const unsigned trace-mask); void _tracef(const char *format, ...); @@ -63,7 +63,7 @@ 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 *_tracechar(int c); char *_tracechtype(chtype ch); char *_tracechtype2(int buffer, chtype ch); @@ -71,17 +71,17 @@ char *_nc_tracebits(void); char *_tracemouse(const MEVENT *event); - /* deprecated */ - void trace(const unsigned int param); + /* deprecated */ + void trace(const unsigned int trace-mask);
- The curses trace routines are used for debugging the ncurses libraries, - as well as applications which use the ncurses libraries. Some limita- - tions apply: + The curses trace routines are used for debugging the ncurses libraries, + as well as applications which use the ncurses libraries. Some + limitations apply: o Aside from curses_trace, the other functions are normally available - only with the debugging library e.g., libncurses_g.a. + 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. @@ -98,9 +98,9 @@ o _tracef, which writes formatted data to the trace file. - 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 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, @@ -109,26 +109,27 @@ 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. + o If tracing is available, calling curses_trace with a nonzero + parameter updates the trace mask, and returns the previous trace + mask. - When the trace mask is nonzero, ncurses creates the file "trace" in - the current directory for output. If the file already exists, no + 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 curses_trace function. + 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 curses_trace function. TRACE_TIMES trace user and system times of updates. @@ -146,11 +147,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 @@ -177,36 +178,27 @@ TRACE_MAXIMUM maximum trace level, enables all of the separate trace features. - Some tracing features are enabled whenever the curses_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 curses_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 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 + which extends the set of messages written using the curses_trace + function. 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: + such as setupterm, tgetent or use_extended_names, some of their + debugging output may be directed to the trace file if the NCURSES_TRACE + environment 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. @@ -215,35 +207,47 @@ the _tracef routine. +
+ +
+ A positive integral value stored in this variable causes the following + functions to enable the tracing feature as if curses_trace were called. + + filter, initscr, new_prescr, newterm, nofilter, restartterm, + ripoffline, setupterm, slk_init, tgetent, use_env, + use_extended_names, use_tioctl + +
- 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: + These functions are not part of the X/Open Curses 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 + 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. + o PDCurses provides traceon and traceoff, which (like SVr4) are + always available, and enable tracing to the "trace" file only when + a debug-library is built. - 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 + 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. + o NetBSD does not provide functions for enabling/disabling traces. + It uses environment variables CURSES_TRACE_MASK and + CURSES_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 + A few ncurses functions are not provided when symbol versioning is used: _nc_tracebits, _tracedump, _tracemouse @@ -253,11 +257,11 @@
- curses(3x). + curses(3x) - curs_trace(3x) +ncurses 6.5 2024-04-20 curs_trace(3x)