.\"***************************************************************************
.\" Copyright 2019-2024,2025 Thomas E. Dickey                                *
.\" Copyright 2000-2016,2017 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_trace.3x,v 1.55 2025/01/19 00:51:10 tom Exp $
.TH curs_trace 3X 2025-01-18 "ncurses 6.5" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\}
.el \{\
.ie t .ds `` ``
.el   .ds `` ""
.ie t .ds '' ''
.el   .ds '' ""
.\}
.
.de bP
.ie n  .IP \(bu 4
.el    .IP \(bu 2
..
.
.de dS \" Start unfilled display.
.nr aD \n(.j
.na
..
.
.de dE \" End unfilled display.
.ad \n(.j
.rr aD
..
.
.SH NAME
\fB\%curses_trace\fP,
\fB\%trace\fP,
\fB\%_tracef\fP,
\fB\%_traceattr\fP,
\fB\%_traceattr2\fP,
\fB\%_tracecchar_t\fP,
\fB\%_tracecchar_t2\fP,
\fB\%_tracechar\fP,
\fB\%_tracechtype\fP,
\fB\%_tracechtype2\fP,
\fB\%_nc_tracebits\fP,
\fB\%_tracedump\fP,
\fB\%_tracemouse\fP \-
\fIcurses\fR debugging routines
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBunsigned curses_trace(const unsigned \fItrace-mask\fP);
.PP
\fBvoid _tracef(const char *\fIformat\fP, ...);
.PP
\fBchar *_traceattr(attr_t \fIattr\fP);
\fBchar *_traceattr2(int \fIbuffer\fP, chtype \fIch\fP);
\fBchar *_tracecchar_t(const cchar_t *\fIstring\fP);
\fBchar *_tracecchar_t2(int \fIbuffer\fP, const cchar_t *\fIstring\fP);
\fBchar *_tracechar(int \fIc\fP);
\fBchar *_tracechtype(chtype \fIch\fP);
\fBchar *_tracechtype2(int \fIbuffer\fP, chtype \fIch\fP);
.PP
\fBvoid _tracedump(const char *\fIlabel\fP, WINDOW *\fIwin\fP);
\fBchar *_nc_tracebits(void);
\fBchar *_tracemouse(const MEVENT *\fIevent\fP);
.PP
\fI/* deprecated */\fP
\fBvoid trace(const unsigned int \fItrace-mask\fP);
.fi
.SH DESCRIPTION
The \fIcurses trace\fP routines are used for debugging the
\fI\%ncurses\fP libraries,
as well as applications which use the \fI\%ncurses\fP libraries.
Some limitations apply:
.bP
Aside from \fBcurses_trace\fP,
the other functions are normally available only with the debugging library
e.g., \fBlibncurses_g.a\fP.
.IP
All of the trace functions may be compiled into any model (shared, static,
profile) by defining the symbol \fBTRACE\fP.
.bP
Additionally, the functions which use \fBcchar_t\fP
are only available with the wide-character configuration of the libraries.
.SS Functions
The principal parts of this interface are
.bP
\fBcurses_trace\fP, which selectively enables different tracing features, and
.bP
\fB_tracef\fP, which writes formatted data to the \fItrace\fP file.
.IP
The other functions either return a pointer to a string-area
(allocated by the corresponding function), or return no value
(such as \fB_tracedump\fP,
which implements the screen dump for \fBTRACE_UPDATE\fP).
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.
.PP
The \fBcurses_trace\fP function is always available,
whether or not the other trace functions are available:
.bP
If tracing is available,
calling \fBcurses_trace\fP with a nonzero parameter
updates the trace mask,
and returns the previous trace mask.
.IP
When the trace mask is nonzero,
\fI\%ncurses\fP creates the file \*(``trace\*('' in the current directory for output.
If the file already exists, no tracing is done.
.bP
If tracing is not available, \fBcurses_trace\fP returns zero (0).
.SS "Trace Parameter"
The trace parameter is formed by logically \*(``or\*(''-ing
values from the list of \fBTRACE_\fIxxx\fR definitions in \fB<curses.h>\fR.
These include:
.TP 5
.B TRACE_DISABLE
turn off tracing by passing a zero parameter.
.IP
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 \fBcurses_trace\fP function.
.TP 5
.B TRACE_TIMES
trace user and system times of updates.
.TP 5
.B TRACE_TPUTS
trace \fBtputs\fP(3X) calls.
.TP 5
.B TRACE_UPDATE
trace update actions, old & new screens.
.TP 5
.B TRACE_MOVE
trace cursor movement and scrolling.
.TP 5
.B TRACE_CHARPUT
trace all character outputs.
.TP 5
.B TRACE_ORDINARY
trace all update actions.
The old and new screen contents are written to the trace file
for each refresh.
.TP 5
.B TRACE_CALLS
trace all curses calls.
The parameters for each call are traced, as well as return values.
.TP 5
.B TRACE_VIRTPUT
trace virtual character puts, i.e., calls to \fBaddch\fP.
.TP 5
.B TRACE_IEVENT
trace low-level input processing, including timeouts.
.TP 5
.B TRACE_BITS
trace state of TTY control bits.
.TP 5
.B TRACE_ICALLS
trace internal/nested calls.
.TP 5
.B TRACE_CCALLS
trace per-character calls.
.TP 5
.B TRACE_DATABASE
trace read/write of terminfo/termcap data.
.TP 5
.B TRACE_ATTRS
trace changes to video attributes and colors.
.TP 5
.B TRACE_MAXIMUM
maximum trace level, enables all of the separate trace features.
.PP
Some tracing features are enabled whenever the \fBcurses_trace\fP parameter
is nonzero.
Some features overlap.
The specific names are used as a guideline.
.SS "Command-line Utilities"
The command-line utilities such as \fBtic\fP(1) provide a verbose option
which extends the set of messages written using the \fBcurses_trace\fP function.
Both of these (\fB\-v\fP and \fBcurses_trace\fP)
use the same variable (\fB_nc_tracing\fP),
which determines the messages which are written.
.PP
Because the command-line utilities may call initialization functions
such as \fBsetupterm\fP, \fBtgetent\fP or \fBuse_extended_names\fP,
some of their debugging output may be directed to the \fItrace\fP file
if the \fI\%NCURSES_TRACE\fP environment variable is set:
.bP
messages produced in the utility are written to the standard error.
.bP
messages produced by the underlying library are written to \fItrace\fP.
.PP
If \fI\%ncurses\fP is built without tracing,
none of the latter are produced,
and fewer diagnostics are provided by the command-line utilities.
.SH RETURN VALUE
Routines which return a value are designed to be used as parameters
to the \fB_tracef\fP routine.
.SH ENVIRONMENT
.SS NCURSES_TRACE
A positive integral value stored in this variable causes the following
functions to enable the tracing feature as if
.B \%curses_trace
were called.
.PP
.dS
.RS 4
\fB\%filter\fP,
\fB\%initscr\fP,
\fB\%new_prescr\fP,
\fB\%newterm\fP,
\fB\%nofilter\fP,
\fB\%restartterm\fP,
\fB\%ripoffline\fP,
\fB\%setupterm\fP,
\fB\%slk_init\fP,
\fB\%tgetent\fP,
\fB\%use_env\fP,
\fB\%use_extended_names\fP,
\fB\%use_tioctl\fP
.RE
.dE
.SH PORTABILITY
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 \fI\%ncurses\fP:
.bP
SVr4 provided \fBtraceon\fP and \fBtraceoff\fP,
to control whether debugging information was written
to the \*(``trace\*('' file.
While the functions were always available,
this feature was only enabled
if \fBDEBUG\fP was defined when building the library.
.IP
The SVr4 tracing feature is undocumented.
.bP
.I \%PDCurses
provides \fBtraceon\fP and \fBtraceoff\fP,
which (like SVr4) are always available,
and enable tracing
to the \*(``trace\*('' file
only when a debug-library is built.
.IP
.I \%PDCurses
has a short description of these functions,
with a note that they are not present in X/Open Curses,
\fI\%ncurses\fP or NetBSD.
It does not mention SVr4,
but the functions' inclusion in a header file section
labeled \*(``Quasi-standard\*('' hints at the origin.
.bP
NetBSD does not provide functions for enabling/disabling traces.
It uses environment variables
\fI\%CURSES_TRACE_MASK\fP and
\fI\%CURSES_TRACE_FILE\fP to determine what is traced,
and where the results are written.
This is available only when a debug-library is built.
.IP
The NetBSD tracing feature is undocumented.
.PP
A few \fI\%ncurses\fP functions are not provided when symbol versioning
is used:
.RS 4
.PP
_nc_tracebits,
_tracedump,
_tracemouse
.RE
.PP
The original \fBtrace\fP routine was deprecated because
it often conflicted with application names.
.SH SEE ALSO
\fB\%curses\fP(3X)