mirror of
https://github.com/Aigor44/ncursesw-morphos.git
synced 2024-12-27 07:49:06 +08:00
06078d3fa6
+ add a note to curs_addch.3x on portability. + add a note to curs_pad.3x on the origin and portability of pads. + improve manpage description of getattrs (report by Midolikawa H). + improve manpage macros (prompted by discussion in Debian #880551. + reviewed test-programs using KEY_RESIZE, made fixes to test/worm.c + add a "-d" option to picsmap for default-colors. + modify old terminology entry and a few other terminal emulators to account for xon -TD + correct sgr string for tmux, which used screen's "standout" code rather than the standard code (patch by Roman Kagan) + correct sgr/sgr0 strings in a few other cases reported by tic, making those correspond to the non-sgr settings where they differ, but otherwise use ECMA-48 consistently: jaixterm, aixterm, att5420_2, att4424, att500, decansi, d410-7b, dm80, hpterm, emu-220, hp2, iTerm2.app, mterm-ansi, ncrvt100an, st-0.7, vi603, vwmterm -TD + build-fix for diagnostics warning in lib_mouse.c for pre-5.0 versions of gcc which did not recognize the diagnostic "push" pragma (patch by Vassili Courzakis).
231 lines
7.7 KiB
Plaintext
231 lines
7.7 KiB
Plaintext
.\"***************************************************************************
|
|
.\" Copyright (c) 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.19 2017/11/18 23:47:37 tom Exp $
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.TH curs_trace 3X ""
|
|
.na
|
|
.hy 0
|
|
.SH NAME
|
|
\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
|
|
.SH SYNOPSIS
|
|
\fB#include <curses.h>\fR
|
|
.sp
|
|
\fBvoid trace(const unsigned int \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
|
|
.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
|
|
e.g., \fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
|
|
profile) by defining the symbol \fBTRACE\fR.
|
|
Additionally, some functions are only available with the wide-character
|
|
configuration of the libraries.
|
|
.SS Functions
|
|
The principal parts of this interface are
|
|
.bP
|
|
\fBtrace\fR, which selectively enables different tracing features, and
|
|
.bP
|
|
\fB_tracef\fR, which writes formatted data to the \fItrace\fR file.
|
|
.PP
|
|
Calling \fBtrace\fR with a nonzero parameter creates the file \fBtrace\fR
|
|
in the current directory for output.
|
|
If the file already exists, no tracing is done.
|
|
.PP
|
|
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.
|
|
.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.
|
|
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 \fBtrace\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\fR.
|
|
.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 \fBtrace\fR parameter
|
|
is nonzero.
|
|
Some features overlap.
|
|
The specific names are used as a guideline.
|
|
.SS Initialization
|
|
These functions check the \fBNCURSES_TRACE\fP environment variable,
|
|
to set the tracing feature as if \fBtrace\fP was called:
|
|
.RS 4
|
|
.PP
|
|
.na
|
|
.hy 0
|
|
filter,
|
|
initscr,
|
|
new_prescr,
|
|
newterm,
|
|
nofilter,
|
|
restartterm,
|
|
ripoffline,
|
|
setupterm,
|
|
slk_init,
|
|
tgetent,
|
|
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 \fBtrace\fP function.
|
|
Both of these (\fB\-v\fP and \fBtrace\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 \fBNCURSES_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 ncurses 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.
|
|
.SH PORTABILITY
|
|
These functions are not part of the XSI interface.
|
|
Some other curses implementations are known to
|
|
have similar, undocumented features,
|
|
but they are not compatible with ncurses.
|
|
.PP
|
|
A few functions are not provided when symbol versioning is used:
|
|
.RS 4
|
|
.PP
|
|
_nc_tracebits,
|
|
_tracedump,
|
|
_tracemouse
|
|
.RE
|
|
.SH SEE ALSO
|
|
\fBcurses\fR(3X).
|