vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
304 lines
9.9 KiB
Plaintext
304 lines
9.9 KiB
Plaintext
.\"***************************************************************************
|
|
.\" 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 @NCURSES_MAJOR@.@NCURSES_MINOR@" "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)
|