X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_trace.3x;h=792b7e95a4ab381d96b2dab3313946e9105cae18;hp=85df283c2c522716c294a3d2203da3e567c76334;hb=b60a2772d9f149d8e900c1d5a09a53a56a0837a8;hpb=c3b21f65a2687f3894a0d3217006c23f162c893a

diff --git a/man/curs_trace.3x b/man/curs_trace.3x
index 85df283c..792b7e95 100644
--- a/man/curs_trace.3x
+++ b/man/curs_trace.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 2000-2015,2016 Free Software Foundation, Inc.              *
+.\" 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            *
@@ -26,54 +26,55 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_trace.3x,v 1.14 2016/10/15 17:26:09 tom Exp $
+.\" $Id: curs_trace.3x,v 1.19 2017/11/18 23:47:37 tom Exp $
 .de bP
-.IP \(bu 4
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
 ..
 .TH curs_trace 3X ""
 .na
 .hy 0
 .SH NAME
+\fBtrace\fR,
 \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
+\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
-.br
-\fBvoid _tracedump(const char *\fP\fIlabel\fP\fB, WINDOW *\fP\fIwin\fP\fB);\fR
-.br
+.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 *_nc_tracebits(void);\fR
-.br
-\fBchar * _tracecchar_t(const cchar_t *\fP\fIstring\fP\fB);\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
+\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 *_tracemouse(const MEVENT *\fP\fIevent\fP\fB);\fR
+\fBchar *_nc_tracebits(void);\fR
 .br
-\fBvoid trace(const unsigned int \fP\fIparam\fP\fB);\fR
+\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.
@@ -82,27 +83,44 @@ 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.
-.PP
+.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 opens the file \fBtrace\fR
+Calling \fBtrace\fR with a nonzero parameter creates the file \fBtrace\fR
 in the current directory for output.
-The parameter is formed by OR'ing
+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.
+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 calls.
+trace \fBtputs\fP(3X) calls.
 .TP 5
 .B TRACE_UPDATE
 trace update actions, old & new screens.
@@ -150,22 +168,13 @@ Some tracing features are enabled whenever the \fBtrace\fR parameter
 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
+.SS Initialization
 These functions check the \fBNCURSES_TRACE\fP environment variable,
 to set the tracing feature as if \fBtrace\fP was called:
-.RS
+.RS 4
 .PP
 .na
+.hy 0
 filter,
 initscr,
 new_prescr,
@@ -179,8 +188,28 @@ 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.
@@ -189,5 +218,13 @@ 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).