@@@ fltfmt wip

[mLib] / trace / trace.3.in

.\" -*-nroff-*-
.\"
.\" Manual for tracing
.\"
.\" (c) 1999, 2001, 2005, 2009, 2017, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH trace 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @trace
.\" @trace_block
.\" @trace_on
.\" @trace_custom
.\" @trace_level
.\" @tracing
.\" @traceopt
.\" @NTRACE
.\" @T
.\" @IF_TRACING
.
.\"--------------------------------------------------------------------------
.SH "NAME"
trace \- configurable tracing output
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.nf
.B "#include <mLib/trace.h>"
.PP
.BI "void trace(unsigned " l ", const char *" f ", ...);"
.ta \w'\fBvoid trace_block('u
.BI "void trace_block(unsigned " l ", const char *" s ,
.BI "	const void *" b ", size_t " sz );
.PP
.BI "void trace_on(FILE *" fp ", unsigned " l );
.ta \w'\fBvoid trace_custom('u +\w'\fBvoid (*\,\fIfunc\/\fB)('u
.BI "void trace_custom(void (*" func ")(const char *" buf ,
.BI "		size_t " sz ", void *" v ),
.BI "	void *" v );
.BI "void trace_level(unsigned " l );
.BI "unsigned tracing(void);"
.PP
.ta \w'\fBunsigned traceopt('u
.BI "unsigned traceopt(const trace_opt *" t ", const char *" p ,
.BI "	unsigned " f ", unsigned " bad );
.PP
.BI T( statements\fR... )
.BI "IF_TRACING(unsigned " l ", " statements\fR... )
.fi
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B <mLib/trace.h>
header declares some functions and macros for handling trace output.
The emphasis for this system is primarily on user configurability of
what gets traced rather than where the output goes.  That's a project
for later.
.SS "Trace levels"
Each trace message is assigned a
.I level
by the programmer.  A tracing level is set during program
initialization, usually by the user.  A trace message is output if there
is a trace destination set, and the result of a bitwise AND between the
message level and the overall tracing level is nonzero.  The idea is
that the programmer assigns a different bit to each group of trace
messages, and allows a user to select which ones are wanted.
.
.SS "Producing trace output"
The basic function is
.BR trace .
It is passed an integer message level and a
.BR printf (3)-style
format string together with arguments for the placeholders and emits the
resulting message.
.PP
The function
.B trace_block
formats an arbitrary block of memory as a hex dump.  The arguments are,
in order, the message level, a pointer to the header string for the hex
dump, the base address of the block to dump, and the size of the block
in bytes.
.
.SS "Configuring trace output"
The tracing destination is set with the function
.BR trace_on :
it is passed a
.B stdio
stream and a trace level to set.  The stream may be null to disable
tracing completely (which is the default).  The trace level may be set
on its own using
.BR trace_level ,
which takes the new level as its single argument.  The function
.B tracing
returns the current trace level, or zero if there is no trace
destination set.
.PP
For more advanced programs, a custom output function may be provided by
.B trace_custom
and passing a function which will write a buffer of data somewhere
sensible.
.
.SS "Parsing user trace options"
The function
.B traceopt
may be used to allow a user to set the trace level.  It is passed a
table describing the available trace level bits, and some other
information, and returns a new trace level.  The table consists of a
number of
.B trace_opt
structures, each of which describes a bit or selection of bits which may
be controlled.  The structure contains the following members, in order:
.TP
.B "char ch;"
The character used to select this bit or collection of bits.
.TP
.B "unsigned f;"
The level bits for this option.
.TP
.B "const char *help;"
A help string describing this option.
.PP
The table is terminated by an entry whose
.B ch
member is zero.
.PP
The arguments to
.B traceopt
are:
.TP
.BI "trace_opt *" t
Pointer to the trace options table.
.TP
.BI "const char *" p
Pointer to the user's option string.
.TP
.BI "unsigned " f
The default trace options, or the previously-set options.
.TP
.BI "unsigned " bad
A bitmask of level bits which should be disallowed.
.PP
If the option string
.I p
is a null pointer or contains only a
.RB ` ? '
character, a help message is printed and the default is returned.  Only
trace options which contain non-bad bits are displayed.  Otherwise the
string contains option characters together with
.RB ` + '
and
.RB ` \- '
which respectively turn on or off the following options; the default is
to turn options on.  Again, only options which contain non-bad bits are
allowed.
.PP
The `bad bit' mechanism is provided for setuid programs which in their
normal configuration deal with privileged information which mustn't be
given out to users.  However, if run by someone with appropriate
privilege such options are safe and may be useful for debugging.  The
program can set the
.I bad
mask to prevent access to secret information when running setuid, or to
zero when not.
.
.SS "Macro support for tracing"
The tracing macros are intended to make insertion of tracing information
unobtrusive and painless.  If the
.B NTRACE
macro is defined, all of the tracing macros are disabled and generate no
code; otherwise they do their normal jobs.
.PP
The
.B T
macro simply expands to its argument.  It may be wrapped around small
pieces of code which is only needed when compiling with tracing
enabled.  (Larger blocks, of course, should use
.RB ` "#ifndef NTRACE" '/` #endif '
pairs for clarity's sake.)
.PP
For slightly larger code chunks which do some processing to generate
trace output, the
.B IF_TRACING
macro is useful.  Its first argument is a message level; if the trace
level is set such that the message will be printed, the code in the
second argument is executed.  If code is being compiled without tracing,
of course, the entire contents of the macro is ignored.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR mLib (3).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------