ncurses 6.0 - patch 20161112
[ncurses.git] / man / curs_trace.3x
index a9dc57c7c7b3c44ebe00360af9e255f5cdbb93f3..85df283c2c522716c294a3d2203da3e567c76334 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 2000 Free Software Foundation, Inc.                        *
+.\" Copyright (c) 2000-2015,2016 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.3 2000/07/29 16:34:24 tom Exp $
+.\" $Id: curs_trace.3x,v 1.14 2016/10/15 17:26:09 tom Exp $
+.de bP
+.IP \(bu 4
+..
 .TH curs_trace 3X ""
+.na
+.hy 0
 .SH NAME
 \fB_tracef\fR,
 \fB_tracedump\fR,
 \fB_traceattr\fR,
 \fB_traceattr2\fR,
 \fB_nc_tracebits\fR,
+\fB_tracecchar_t\fR,
+\fB_tracecchar_t2\fR,
 \fB_tracechar\fR,
 \fB_tracechtype\fR,
 \fB_tracechtype2\fR,
 \fB_tracemouse\fR,
-\fBtrace\fR - \fBcurses\fR debugging routines
+\fBtrace\fR \- \fBcurses\fR debugging routines
+.ad
+.hy
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
+.sp
+\fBvoid _tracef(const char *\fP\fIformat\fP\fB, ...);\fR
 .br
-\fBvoid _tracef(const char *format, ...);\fR
-.br
-\fBvoid _tracedump(const char *label, WINDOW *win);\fR
+\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR
 .br
-\fBchar *_traceattr(attr_t attr);\fR
+\fBchar *_traceattr(attr_t \fP\fIattr\fP\fB);\fR
 .br
-\fBchar *_traceattr2(int buffer, chtype ch);\fR
+\fBchar *_traceattr2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
 .br
 \fBchar *_nc_tracebits(void);\fR
 .br
-\fBchar *_tracechar(const unsigned char ch);\fR
+\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 *_tracechtype(chtype ch);\fR
+\fBchar *_tracechar(int \fP\fIch\fP\fB);\fR
 .br
-\fBchar *_tracechtype2(int buffer, chtype ch);\fR
+\fBchar *_tracechtype(chtype \fP\fIch\fP\fB);\fR
 .br
-\fBchar *_tracemouse(const MEVENT *event);\fR
+\fBchar *_tracechtype2(int \fP\fIbuffer\fP\fB, chtype \fP\fIch\fP\fB);\fR
 .br
-\fBvoid trace(const unsigned int param);\fR
+\fBchar *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR
+.br
+\fBvoid trace(const unsigned int \fP\fIparam\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
-\fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
+e.g., \fIlibncurses_g.a\fR, but may be compiled into any model (shared, static,
 profile) by defining the symbol \fBTRACE\fR.
-
-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.
-
+Additionally, some functions are only available with the wide-character
+configuration of the libraries.
+.PP
+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 opens the file \fBtrace\fR
-in the current directory for output.  The parameter is formed by OR'ing
+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.
 These include:
 .TP 5
-TRACE_DISABLE
+.B TRACE_DISABLE
 turn off tracing.
 .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 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
+.B TRACE_VIRTPUT
 trace virtual character puts, i.e., calls to \fBaddch\fR.
 .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.
+is nonzero.
+Some features overlap.
 The specific names are used as a guideline.
-..
+.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.
+.PP
+These functions check the \fBNCURSES_TRACE\fP environment variable,
+to set the tracing feature as if \fBtrace\fP was called:
+.RS
+.PP
+.na
+filter,
+initscr,
+new_prescr,
+newterm,
+nofilter,
+restartterm,
+ripoffline,
+setupterm,
+slk_init,
+tgetent,
+use_env,
+use_extended_names,
+use_tioctl
+.ad
+.RE
 .SH RETURN VALUE
 Routines which return a value are designed to be used as parameters
 to the \fB_tracef\fR routine.
@@ -142,9 +191,3 @@ have similar, undocumented features,
 but they are not compatible with ncurses.
 .SH SEE ALSO
 \fBcurses\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: