diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man3/trace.3ncurses | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man3/trace.3ncurses b/upstream/opensuse-leap-15-6/man3/trace.3ncurses new file mode 100644 index 00000000..ae8cf59f --- /dev/null +++ b/upstream/opensuse-leap-15-6/man3/trace.3ncurses @@ -0,0 +1,230 @@ +.\"*************************************************************************** +.\" 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 trace 3NCURSES "" +.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 <ncursesw/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 +\fBncurses\fR(3NCURSES). |