.\"***************************************************************************
-.\" Copyright 2019,2020 Thomas E. Dickey *
+.\" Copyright 2019-2022,2023 Thomas E. Dickey *
.\" Copyright 2000-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.21 2020/02/02 23:34:34 tom Exp $
+.\" $Id: curs_trace.3x,v 1.37 2023/09/23 20:53:33 tom Exp $
+.TH curs_trace 3X 2023-09-23 "ncurses 6.4" "Library calls"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.TH curs_trace 3X ""
-.na
-.hy 0
.SH NAME
-\fBcurses_trace\fR,
-\fBtrace\fR,
-\fB_tracef\fR,
-\fB_traceattr\fR,
-\fB_traceattr2\fR,
-\fB_tracecchar_t\fR,
-\fB_tracecchar_t2\fR,
-\fB_tracechar\fR,
-\fB_tracechtype\fR,
-\fB_tracechtype2\fR,
-\fB_nc_tracebits\fR,
-\fB_tracedump\fR,
-\fB_tracemouse\fR \- \fBcurses\fR debugging routines
-.ad
-.hy
+\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
-\fB#include <curses.h>\fR
-.sp
-\fBunsigned curses_trace(const unsigned \fP\fIparam\fP\fB);\fR
-.sp
-\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR
-.sp
-\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fR
-.br
-\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\fR
-.br
-\fBchar *_tracecchar_t2(int \fP\fIbuffer\fP\fB, const cchar_t *\fP\fIstring\fP\fB);\fR
-.br
-\fBchar *_tracechar(int \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fR
-.br
-\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.sp
-\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR
-.br
-\fBchar *_nc_tracebits(void);\fR
-.br
-\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR
-.sp
+.nf
+\fB#include <curses.h>\fP
+.PP
+\fBunsigned curses_trace(const unsigned \fIparam\fB);\fR
+.PP
+\fBvoid _tracef(const char *\fIformat\fB, ...);\fR
+.PP
+\fBchar *_traceattr(attr_t \fIattr\fB);\fR
+\fBchar *_traceattr2(int \fIbuffer\fB, chtype \fIch\fB);\fR
+\fBchar *_tracecchar_t(const cchar_t *\fIstring\fB);\fR
+\fBchar *_tracecchar_t2(int \fIbuffer\fB, const cchar_t *\fIstring\fB);\fR
+\fBchar *_tracechar(int \fIch\fB);\fR
+\fBchar *_tracechtype(chtype \fIch\fB);\fR
+\fBchar *_tracechtype2(int \fIbuffer\fB, chtype \fIch\fB);\fR
+.PP
+\fBvoid _tracedump(const char *\fIlabel\fB, WINDOW *\fIwin\fB);\fR
+\fBchar *_nc_tracebits(void);\fP
+\fBchar *_tracemouse(const MEVENT *\fIevent\fB);\fR
+.PP
/* deprecated */
-.br
-\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR
+\fBvoid trace(const unsigned int \fIparam\fB);\fR
+.fi
.SH DESCRIPTION
-The \fIcurses trace\fR routines are used for debugging the ncurses libraries,
+The \fIcurses trace\fP routines are used for debugging the ncurses libraries,
as well as applications which use the ncurses libraries.
Some limitations apply:
.bP
Aside from \fBcurses_trace\fP,
the other functions are normally available only with the debugging library
-e.g., \fIlibncurses_g.a\fR.
+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\fR.
+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\fR, which selectively enables different tracing features, and
+\fBcurses_trace\fP, which selectively enables different tracing features, and
.bP
-\fB_tracef\fR, which writes formatted data to the \fItrace\fR file.
+\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
some use a buffer-number parameter, telling the library to allocate
additional string-areas.
.PP
-The \fBcurses_trace\fR function is always available,
+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\fR with a nonzero parameter
+calling \fBcurses_trace\fP with a nonzero parameter
updates the trace mask,
and returns the previous trace mask.
.IP
If tracing is not available, \fBcurses_trace\fP returns zero (0).
.SS Trace Parameter
The trace parameter is formed by OR'ing
-values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB<curses.h>\fR.
+values from the list of \fBTRACE_\fIxxx\fR definitions in \fB<curses.h>\fR.
These include:
.TP 5
.B TRACE_DISABLE
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\fR.
+trace virtual character puts, i.e., calls to \fBaddch\fP.
.TP 5
.B TRACE_IEVENT
trace low-level input processing, including timeouts.
.B TRACE_MAXIMUM
maximum trace level, enables all of the separate trace features.
.PP
-Some tracing features are enabled whenever the \fBcurses_trace\fR parameter
+Some tracing features are enabled whenever the \fBcurses_trace\fP parameter
is nonzero.
Some features overlap.
The specific names are used as a guideline.
to set the tracing feature as if \fBcurses_trace\fP was called:
.RS 4
.PP
-.na
-.hy 0
filter,
initscr,
new_prescr,
use_env,
use_extended_names,
use_tioctl
-.hy
-.ad
.RE
.SS Command-line Utilities
-.PP
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)
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\fR routine.
+to the \fB_tracef\fP routine.
.SH PORTABILITY
These functions are not part of the XSI interface.
Some other curses implementations are known to
The original \fBtrace\fP routine was deprecated because
it often conflicted with application names.
.SH SEE ALSO
-\fBcurses\fR(3X).
+\fBcurses\fP(3X).
projects / ncurses.git / blobdiff