| 1 |
.\"*************************************************************************** |
| 2 |
.\" Copyright 2019-2024,2025 Thomas E. Dickey * |
| 3 |
.\" Copyright 2000-2016,2017 Free Software Foundation, Inc. * |
| 4 |
.\" * |
| 5 |
.\" Permission is hereby granted, free of charge, to any person obtaining a * |
| 6 |
.\" copy of this software and associated documentation files (the * |
| 7 |
.\" "Software"), to deal in the Software without restriction, including * |
| 8 |
.\" without limitation the rights to use, copy, modify, merge, publish, * |
| 9 |
.\" distribute, distribute with modifications, sublicense, and/or sell * |
| 10 |
.\" copies of the Software, and to permit persons to whom the Software is * |
| 11 |
.\" furnished to do so, subject to the following conditions: * |
| 12 |
.\" * |
| 13 |
.\" The above copyright notice and this permission notice shall be included * |
| 14 |
.\" in all copies or substantial portions of the Software. * |
| 15 |
.\" * |
| 16 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| 17 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| 18 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| 19 |
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| 20 |
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| 21 |
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| 22 |
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| 23 |
.\" * |
| 24 |
.\" Except as contained in this notice, the name(s) of the above copyright * |
| 25 |
.\" holders shall not be used in advertising or otherwise to promote the * |
| 26 |
.\" sale, use or other dealings in this Software without prior written * |
| 27 |
.\" authorization. * |
| 28 |
.\"*************************************************************************** |
| 29 |
.\" |
| 30 |
.\" $Id: curs_trace.3x,v 1.55 2025/01/19 00:51:10 tom Exp $ |
| 31 |
.TH trace 3NCURSES 2025-01-18 "ncurses 6.6" "Library calls" |
| 32 |
.ie \n(.g \{\ |
| 33 |
.ds `` \(lq |
| 34 |
.ds '' \(rq |
| 35 |
.\} |
| 36 |
.el \{\ |
| 37 |
.ie t .ds `` `` |
| 38 |
.el .ds `` "" |
| 39 |
.ie t .ds '' '' |
| 40 |
.el .ds '' "" |
| 41 |
.\} |
| 42 |
. |
| 43 |
.de bP |
| 44 |
.ie n .IP \(bu 4 |
| 45 |
.el .IP \(bu 2 |
| 46 |
.. |
| 47 |
. |
| 48 |
.de dS \" Start unfilled display. |
| 49 |
.nr aD \n(.j |
| 50 |
.na |
| 51 |
.. |
| 52 |
. |
| 53 |
.de dE \" End unfilled display. |
| 54 |
.ad \n(.j |
| 55 |
.rr aD |
| 56 |
.. |
| 57 |
. |
| 58 |
.SH NAME |
| 59 |
\fB\%curses_trace\fP, |
| 60 |
\fB\%trace\fP, |
| 61 |
\fB\%_tracef\fP, |
| 62 |
\fB\%_traceattr\fP, |
| 63 |
\fB\%_traceattr2\fP, |
| 64 |
\fB\%_tracecchar_t\fP, |
| 65 |
\fB\%_tracecchar_t2\fP, |
| 66 |
\fB\%_tracechar\fP, |
| 67 |
\fB\%_tracechtype\fP, |
| 68 |
\fB\%_tracechtype2\fP, |
| 69 |
\fB\%_nc_tracebits\fP, |
| 70 |
\fB\%_tracedump\fP, |
| 71 |
\fB\%_tracemouse\fP \- |
| 72 |
\fIcurses\fR debugging routines |
| 73 |
.SH SYNOPSIS |
| 74 |
.nf |
| 75 |
\fB#include <curses.h> |
| 76 |
.PP |
| 77 |
\fBunsigned curses_trace(const unsigned \fItrace-mask\fP); |
| 78 |
.PP |
| 79 |
\fBvoid _tracef(const char *\fIformat\fP, ...); |
| 80 |
.PP |
| 81 |
\fBchar *_traceattr(attr_t \fIattr\fP); |
| 82 |
\fBchar *_traceattr2(int \fIbuffer\fP, chtype \fIch\fP); |
| 83 |
\fBchar *_tracecchar_t(const cchar_t *\fIstring\fP); |
| 84 |
\fBchar *_tracecchar_t2(int \fIbuffer\fP, const cchar_t *\fIstring\fP); |
| 85 |
\fBchar *_tracechar(int \fIc\fP); |
| 86 |
\fBchar *_tracechtype(chtype \fIch\fP); |
| 87 |
\fBchar *_tracechtype2(int \fIbuffer\fP, chtype \fIch\fP); |
| 88 |
.PP |
| 89 |
\fBvoid _tracedump(const char *\fIlabel\fP, WINDOW *\fIwin\fP); |
| 90 |
\fBchar *_nc_tracebits(void); |
| 91 |
\fBchar *_tracemouse(const MEVENT *\fIevent\fP); |
| 92 |
.PP |
| 93 |
\fI/* deprecated */\fP |
| 94 |
\fBvoid trace(const unsigned int \fItrace-mask\fP); |
| 95 |
.fi |
| 96 |
.SH DESCRIPTION |
| 97 |
The \fIcurses trace\fP routines are used for debugging the |
| 98 |
\fI\%ncurses\fP libraries, |
| 99 |
as well as applications which use the \fI\%ncurses\fP libraries. |
| 100 |
Some limitations apply: |
| 101 |
.bP |
| 102 |
Aside from \fBcurses_trace\fP, |
| 103 |
the other functions are normally available only with the debugging library |
| 104 |
e.g., \fBlibncurses_g.a\fP. |
| 105 |
.IP |
| 106 |
All of the trace functions may be compiled into any model (shared, static, |
| 107 |
profile) by defining the symbol \fBTRACE\fP. |
| 108 |
.bP |
| 109 |
Additionally, the functions which use \fBcchar_t\fP |
| 110 |
are only available with the wide-character configuration of the libraries. |
| 111 |
.SS Functions |
| 112 |
The principal parts of this interface are |
| 113 |
.bP |
| 114 |
\fBcurses_trace\fP, which selectively enables different tracing features, and |
| 115 |
.bP |
| 116 |
\fB_tracef\fP, which writes formatted data to the \fItrace\fP file. |
| 117 |
.IP |
| 118 |
The other functions either return a pointer to a string-area |
| 119 |
(allocated by the corresponding function), or return no value |
| 120 |
(such as \fB_tracedump\fP, |
| 121 |
which implements the screen dump for \fBTRACE_UPDATE\fP). |
| 122 |
The caller should not free these strings, |
| 123 |
since the allocation is reused on successive calls. |
| 124 |
To work around the problem of a single string-area per function, |
| 125 |
some use a buffer-number parameter, telling the library to allocate |
| 126 |
additional string-areas. |
| 127 |
.PP |
| 128 |
The \fBcurses_trace\fP function is always available, |
| 129 |
whether or not the other trace functions are available: |
| 130 |
.bP |
| 131 |
If tracing is available, |
| 132 |
calling \fBcurses_trace\fP with a nonzero parameter |
| 133 |
updates the trace mask, |
| 134 |
and returns the previous trace mask. |
| 135 |
.IP |
| 136 |
When the trace mask is nonzero, |
| 137 |
\fI\%ncurses\fP creates the file \*(``trace\*('' in the current directory for output. |
| 138 |
If the file already exists, no tracing is done. |
| 139 |
.bP |
| 140 |
If tracing is not available, \fBcurses_trace\fP returns zero (0). |
| 141 |
.SS "Trace Parameter" |
| 142 |
The trace parameter is formed by logically \*(``or\*(''-ing |
| 143 |
values from the list of \fBTRACE_\fIxxx\fR definitions in \fB<curses.h>\fR. |
| 144 |
These include: |
| 145 |
.TP 5 |
| 146 |
.B TRACE_DISABLE |
| 147 |
turn off tracing by passing a zero parameter. |
| 148 |
.IP |
| 149 |
The library flushes the output file, |
| 150 |
but retains an open file-descriptor to the trace file |
| 151 |
so that it can resume tracing later if a nonzero parameter is passed |
| 152 |
to the \fBcurses_trace\fP function. |
| 153 |
.TP 5 |
| 154 |
.B TRACE_TIMES |
| 155 |
trace user and system times of updates. |
| 156 |
.TP 5 |
| 157 |
.B TRACE_TPUTS |
| 158 |
trace \fBtputs\fP(3NCURSES) calls. |
| 159 |
.TP 5 |
| 160 |
.B TRACE_UPDATE |
| 161 |
trace update actions, old & new screens. |
| 162 |
.TP 5 |
| 163 |
.B TRACE_MOVE |
| 164 |
trace cursor movement and scrolling. |
| 165 |
.TP 5 |
| 166 |
.B TRACE_CHARPUT |
| 167 |
trace all character outputs. |
| 168 |
.TP 5 |
| 169 |
.B TRACE_ORDINARY |
| 170 |
trace all update actions. |
| 171 |
The old and new screen contents are written to the trace file |
| 172 |
for each refresh. |
| 173 |
.TP 5 |
| 174 |
.B TRACE_CALLS |
| 175 |
trace all curses calls. |
| 176 |
The parameters for each call are traced, as well as return values. |
| 177 |
.TP 5 |
| 178 |
.B TRACE_VIRTPUT |
| 179 |
trace virtual character puts, i.e., calls to \fBaddch\fP. |
| 180 |
.TP 5 |
| 181 |
.B TRACE_IEVENT |
| 182 |
trace low-level input processing, including timeouts. |
| 183 |
.TP 5 |
| 184 |
.B TRACE_BITS |
| 185 |
trace state of TTY control bits. |
| 186 |
.TP 5 |
| 187 |
.B TRACE_ICALLS |
| 188 |
trace internal/nested calls. |
| 189 |
.TP 5 |
| 190 |
.B TRACE_CCALLS |
| 191 |
trace per-character calls. |
| 192 |
.TP 5 |
| 193 |
.B TRACE_DATABASE |
| 194 |
trace read/write of terminfo/termcap data. |
| 195 |
.TP 5 |
| 196 |
.B TRACE_ATTRS |
| 197 |
trace changes to video attributes and colors. |
| 198 |
.TP 5 |
| 199 |
.B TRACE_MAXIMUM |
| 200 |
maximum trace level, enables all of the separate trace features. |
| 201 |
.PP |
| 202 |
Some tracing features are enabled whenever the \fBcurses_trace\fP parameter |
| 203 |
is nonzero. |
| 204 |
Some features overlap. |
| 205 |
The specific names are used as a guideline. |
| 206 |
.SS "Command-line Utilities" |
| 207 |
The command-line utilities such as \fBtic\fP(1) provide a verbose option |
| 208 |
which extends the set of messages written using the \fBcurses_trace\fP function. |
| 209 |
Both of these (\fB\-v\fP and \fBcurses_trace\fP) |
| 210 |
use the same variable (\fB_nc_tracing\fP), |
| 211 |
which determines the messages which are written. |
| 212 |
.PP |
| 213 |
Because the command-line utilities may call initialization functions |
| 214 |
such as \fBsetupterm\fP, \fBtgetent\fP or \fBuse_extended_names\fP, |
| 215 |
some of their debugging output may be directed to the \fItrace\fP file |
| 216 |
if the \fI\%NCURSES_TRACE\fP environment variable is set: |
| 217 |
.bP |
| 218 |
messages produced in the utility are written to the standard error. |
| 219 |
.bP |
| 220 |
messages produced by the underlying library are written to \fItrace\fP. |
| 221 |
.PP |
| 222 |
If \fI\%ncurses\fP is built without tracing, |
| 223 |
none of the latter are produced, |
| 224 |
and fewer diagnostics are provided by the command-line utilities. |
| 225 |
.SH RETURN VALUE |
| 226 |
Routines which return a value are designed to be used as parameters |
| 227 |
to the \fB_tracef\fP routine. |
| 228 |
.SH ENVIRONMENT |
| 229 |
.SS NCURSES_TRACE |
| 230 |
A positive integral value stored in this variable causes the following |
| 231 |
functions to enable the tracing feature as if |
| 232 |
.B \%curses_trace |
| 233 |
were called. |
| 234 |
.PP |
| 235 |
.dS |
| 236 |
.RS 4 |
| 237 |
\fB\%filter\fP, |
| 238 |
\fB\%initscr\fP, |
| 239 |
\fB\%new_prescr\fP, |
| 240 |
\fB\%newterm\fP, |
| 241 |
\fB\%nofilter\fP, |
| 242 |
\fB\%restartterm\fP, |
| 243 |
\fB\%ripoffline\fP, |
| 244 |
\fB\%setupterm\fP, |
| 245 |
\fB\%slk_init\fP, |
| 246 |
\fB\%tgetent\fP, |
| 247 |
\fB\%use_env\fP, |
| 248 |
\fB\%use_extended_names\fP, |
| 249 |
\fB\%use_tioctl\fP |
| 250 |
.RE |
| 251 |
.dE |
| 252 |
.SH PORTABILITY |
| 253 |
These functions are not part of the X/Open Curses interface. |
| 254 |
Some other curses implementations are known to |
| 255 |
have similar features, |
| 256 |
but they are not compatible with \fI\%ncurses\fP: |
| 257 |
.bP |
| 258 |
SVr4 provided \fBtraceon\fP and \fBtraceoff\fP, |
| 259 |
to control whether debugging information was written |
| 260 |
to the \*(``trace\*('' file. |
| 261 |
While the functions were always available, |
| 262 |
this feature was only enabled |
| 263 |
if \fBDEBUG\fP was defined when building the library. |
| 264 |
.IP |
| 265 |
The SVr4 tracing feature is undocumented. |
| 266 |
.bP |
| 267 |
.I \%PDCurses |
| 268 |
provides \fBtraceon\fP and \fBtraceoff\fP, |
| 269 |
which (like SVr4) are always available, |
| 270 |
and enable tracing |
| 271 |
to the \*(``trace\*('' file |
| 272 |
only when a debug-library is built. |
| 273 |
.IP |
| 274 |
.I \%PDCurses |
| 275 |
has a short description of these functions, |
| 276 |
with a note that they are not present in X/Open Curses, |
| 277 |
\fI\%ncurses\fP or NetBSD. |
| 278 |
It does not mention SVr4, |
| 279 |
but the functions' inclusion in a header file section |
| 280 |
labeled \*(``Quasi-standard\*('' hints at the origin. |
| 281 |
.bP |
| 282 |
NetBSD does not provide functions for enabling/disabling traces. |
| 283 |
It uses environment variables |
| 284 |
\fI\%CURSES_TRACE_MASK\fP and |
| 285 |
\fI\%CURSES_TRACE_FILE\fP to determine what is traced, |
| 286 |
and where the results are written. |
| 287 |
This is available only when a debug-library is built. |
| 288 |
.IP |
| 289 |
The NetBSD tracing feature is undocumented. |
| 290 |
.PP |
| 291 |
A few \fI\%ncurses\fP functions are not provided when symbol versioning |
| 292 |
is used: |
| 293 |
.RS 4 |
| 294 |
.PP |
| 295 |
_nc_tracebits, |
| 296 |
_tracedump, |
| 297 |
_tracemouse |
| 298 |
.RE |
| 299 |
.PP |
| 300 |
The original \fBtrace\fP routine was deprecated because |
| 301 |
it often conflicted with application names. |
| 302 |
.SH SEE ALSO |
| 303 |
\fB\%ncurses\fP(3NCURSES) |