+++ /dev/null
-.\" -*-nroff-*-
-.TH trace 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-trace \- configurable tracing output
-.\" @trace
-.\" @trace_block
-.\" @trace_on
-.\" @trace_custom
-.\" @trace_level
-.\" @tracing
-.\" @traceopt
-.\" @NTRACE
-.\" @T
-.\" IF_TRACING
-.SH "SYNOPSIS"
-.nf
-.B "#include <mLib/trace.h>"
-
-.BI "void trace(unsigned " l ", const char *" f ", ...);"
-.BI "void trace_block(unsigned " l ", const char *" s ,
-.BI " const void *" b ", size_t " sz );
-
-.BI "void trace_on(FILE *" fp ", unsigned " l );
-.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);"
-
-.BI "unsigned traceopt(const trace_opt *" t ", const char *" p ,
-.BI " unsigned " f ", unsigned " bad );
-
-.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>
~mdw / mLib / blobdiff