.\"***************************************************************************
-.\" Copyright (c) 2000-2002,2005 Free Software Foundation, Inc. *
+.\" Copyright 2019-2023,2024 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.7 2005/05/15 17:02:54 tom Exp $
-.TH curs_trace 3X ""
+.\" $Id: curs_trace.3x,v 1.50 2024/04/20 21:24:19 tom Exp $
+.TH curs_trace 3X 2024-04-20 "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
-.hy 0
+..
+.
+.de dE \" End unfilled display.
+.ad \n(.j
+.rr aD
+..
+.
.SH NAME
-\fB_tracef\fR,
-\fB_tracedump\fR,
-\fB_traceattr\fR,
-\fB_traceattr2\fR,
-\fB_nc_tracebits\fR,
-\fB_tracechar\fR,
-\fB_tracechtype\fR,
-\fB_tracechtype2\fR,
-\fB_tracemouse\fR,
-\fBtrace\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
-\fBvoid _tracef(const char *format, ...);\fR
-.br
-\fBvoid _tracedump(const char *label, WINDOW *win);\fR
-.br
-\fBchar *_traceattr(attr_t attr);\fR
-.br
-\fBchar *_traceattr2(int buffer, chtype ch);\fR
-.br
-\fBchar *_nc_tracebits(void);\fR
-.br
-\fBchar *_tracechar(const unsigned char ch);\fR
-.br
-\fBchar *_tracechtype(chtype ch);\fR
-.br
-\fBchar *_tracechtype2(int buffer, chtype ch);\fR
-.br
-\fBchar *_tracemouse(const MEVENT *event);\fR
-.br
-\fBvoid trace(const unsigned int param);\fR
-.SH DESCRIPTION
-The \fBtrace\fR routines are used for debugging the ncurses libraries,
-as well as applications which use the ncurses libraries.
-These functions are normally available only with the debugging library
-\fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
-profile) by defining the symbol \fBTRACE\fR.
+.nf
+\fB#include <curses.h>
+.PP
+\fBunsigned curses_trace(const unsigned \fItrace-mask\fP);
+.PP
+\fBvoid _tracef(const char *\fIformat\fP, ...);
.PP
-The principal parts of this interface are the \fBtrace\fR routine which
-selectively enables different tracing features, and the \fB_tracef\fR
-routine which writes formatted data to the \fItrace\fR file.
+\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
-Calling \fBtrace\fR with a nonzero parameter opens the file \fBtrace\fR
-in the current directory for output. The parameter is formed by OR'ing
-values from the list of \fBTRACE_\fP\fIxxx\fR definitions in \fB<curses.h>\fR.
+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 OR'ing
+values from the list of \fBTRACE_\fIxxx\fR definitions in \fB<curses.h>\fR.
These include:
.TP 5
-TRACE_DISABLE
-turn off tracing.
+.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
-TRACE_TIMES
+.B TRACE_TIMES
trace user and system times of updates.
.TP 5
-TRACE_TPUTS
-trace tputs calls.
+.B TRACE_TPUTS
+trace \fBtputs\fP(3X) calls.
.TP 5
-TRACE_UPDATE
+.B TRACE_UPDATE
trace update actions, old & new screens.
.TP 5
-TRACE_MOVE
+.B TRACE_MOVE
trace cursor movement and scrolling.
.TP 5
-TRACE_CHARPUT
+.B TRACE_CHARPUT
trace all character outputs.
.TP 5
-TRACE_ORDINARY
+.B TRACE_ORDINARY
trace all update actions.
The old and new screen contents are written to the trace file
for each refresh.
.TP 5
-TRACE_CALLS
+.B TRACE_CALLS
trace all curses calls.
The parameters for each call are traced, as well as return values.
.TP 5
-TRACE_VIRTPUT
-trace virtual character puts, i.e., calls to \fBaddch\fR.
+.B TRACE_VIRTPUT
+trace virtual character puts, i.e., calls to \fBaddch\fP.
.TP 5
-TRACE_IEVENT
+.B TRACE_IEVENT
trace low-level input processing, including timeouts.
.TP 5
-TRACE_BITS
+.B TRACE_BITS
trace state of TTY control bits.
.TP 5
-TRACE_ICALLS
+.B TRACE_ICALLS
trace internal/nested calls.
.TP 5
-TRACE_CCALLS
+.B TRACE_CCALLS
trace per-character calls.
.TP 5
-TRACE_DATABASE
+.B TRACE_DATABASE
trace read/write of terminfo/termcap data.
.TP 5
-TRACE_ATTRS
+.B TRACE_ATTRS
trace changes to video attributes and colors.
.TP 5
-TRACE_MAXIMUM
+.B TRACE_MAXIMUM
maximum trace level, enables all of the separate trace features.
.PP
-Some tracing features are enabled whenever the \fBtrace\fR parameter
-is nonzero. Some features overlap.
+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\fR routine.
+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 XSI interface.
+These functions are not part of the X/Open Curses interface.
Some other curses implementations are known to
-have similar, undocumented features,
-but they are not compatible with ncurses.
+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
+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
+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
-\fBcurses\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fB\%curses\fP(3X)
projects / ncurses.git / blobdiff