mdw@git.distorted.org.uk Git - mLib/blob - trace/trace.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for tracing
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2017, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH trace 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @trace
  33 .\" @trace_block
  34 .\" @trace_on
  35 .\" @trace_custom
  36 .\" @trace_level
  37 .\" @tracing
  38 .\" @traceopt
  39 .\" @NTRACE
  40 .\" @T
  41 .\" @IF_TRACING
  42 .
  43 .\"--------------------------------------------------------------------------
  44 .SH "NAME"
  45 trace \- configurable tracing output
  46 .
  47 .\"--------------------------------------------------------------------------
  48 .SH "SYNOPSIS"
  49 .
  50 .nf
  51 .B "#include <mLib/trace.h>"
  52 .PP
  53 .BI "void trace(unsigned " l ", const char *" f ", ...);"
  54 .ta \w'\fBvoid trace_block('u
  55 .BI "void trace_block(unsigned " l ", const char *" s ,
  56 .BI "   const void *" b ", size_t " sz );
  57 .PP
  58 .BI "void trace_on(FILE *" fp ", unsigned " l );
  59 .ta \w'\fBvoid trace_custom('u +\w'\fBvoid (*\,\fIfunc\/\fB)('u
  60 .BI "void trace_custom(void (*" func ")(const char *" buf ,
  61 .BI "           size_t " sz ", void *" v ),
  62 .BI "   void *" v );
  63 .BI "void trace_level(unsigned " l );
  64 .BI "unsigned tracing(void);"
  65 .PP
  66 .ta \w'\fBunsigned traceopt('u
  67 .BI "unsigned traceopt(const trace_opt *" t ", const char *" p ,
  68 .BI "   unsigned " f ", unsigned " bad );
  69 .PP
  70 .BI T( statements\fR... )
  71 .BI "IF_TRACING(unsigned " l ", " statements\fR... )
  72 .fi
  73 .
  74 .\"--------------------------------------------------------------------------
  75 .SH "DESCRIPTION"
  76 .
  77 The
  78 .B <mLib/trace.h>
  79 header declares some functions and macros for handling trace output.
  80 The emphasis for this system is primarily on user configurability of
  81 what gets traced rather than where the output goes.  That's a project
  82 for later.
  83 .SS "Trace levels"
  84 Each trace message is assigned a
  85 .I level
  86 by the programmer.  A tracing level is set during program
  87 initialization, usually by the user.  A trace message is output if there
  88 is a trace destination set, and the result of a bitwise AND between the
  89 message level and the overall tracing level is nonzero.  The idea is
  90 that the programmer assigns a different bit to each group of trace
  91 messages, and allows a user to select which ones are wanted.
  92 .
  93 .SS "Producing trace output"
  94 The basic function is
  95 .BR trace .
  96 It is passed an integer message level and a
  97 .BR printf (3)-style
  98 format string together with arguments for the placeholders and emits the
  99 resulting message.
 100 .PP
 101 The function
 102 .B trace_block
 103 formats an arbitrary block of memory as a hex dump.  The arguments are,
 104 in order, the message level, a pointer to the header string for the hex
 105 dump, the base address of the block to dump, and the size of the block
 106 in bytes.
 107 .
 108 .SS "Configuring trace output"
 109 The tracing destination is set with the function
 110 .BR trace_on :
 111 it is passed a
 112 .B stdio
 113 stream and a trace level to set.  The stream may be null to disable
 114 tracing completely (which is the default).  The trace level may be set
 115 on its own using
 116 .BR trace_level ,
 117 which takes the new level as its single argument.  The function
 118 .B tracing
 119 returns the current trace level, or zero if there is no trace
 120 destination set.
 121 .PP
 122 For more advanced programs, a custom output function may be provided by
 123 .B trace_custom
 124 and passing a function which will write a buffer of data somewhere
 125 sensible.
 126 .
 127 .SS "Parsing user trace options"
 128 The function
 129 .B traceopt
 130 may be used to allow a user to set the trace level.  It is passed a
 131 table describing the available trace level bits, and some other
 132 information, and returns a new trace level.  The table consists of a
 133 number of
 134 .B trace_opt
 135 structures, each of which describes a bit or selection of bits which may
 136 be controlled.  The structure contains the following members, in order:
 137 .TP
 138 .B "char ch;"
 139 The character used to select this bit or collection of bits.
 140 .TP
 141 .B "unsigned f;"
 142 The level bits for this option.
 143 .TP
 144 .B "const char *help;"
 145 A help string describing this option.
 146 .PP
 147 The table is terminated by an entry whose
 148 .B ch
 149 member is zero.
 150 .PP
 151 The arguments to
 152 .B traceopt
 153 are:
 154 .TP
 155 .BI "trace_opt *" t
 156 Pointer to the trace options table.
 157 .TP
 158 .BI "const char *" p
 159 Pointer to the user's option string.
 160 .TP
 161 .BI "unsigned " f
 162 The default trace options, or the previously-set options.
 163 .TP
 164 .BI "unsigned " bad
 165 A bitmask of level bits which should be disallowed.
 166 .PP
 167 If the option string
 168 .I p
 169 is a null pointer or contains only a
 170 .RB ` ? '
 171 character, a help message is printed and the default is returned.  Only
 172 trace options which contain non-bad bits are displayed.  Otherwise the
 173 string contains option characters together with
 174 .RB ` + '
 175 and
 176 .RB ` \- '
 177 which respectively turn on or off the following options; the default is
 178 to turn options on.  Again, only options which contain non-bad bits are
 179 allowed.
 180 .PP
 181 The `bad bit' mechanism is provided for setuid programs which in their
 182 normal configuration deal with privileged information which mustn't be
 183 given out to users.  However, if run by someone with appropriate
 184 privilege such options are safe and may be useful for debugging.  The
 185 program can set the
 186 .I bad
 187 mask to prevent access to secret information when running setuid, or to
 188 zero when not.
 189 .
 190 .SS "Macro support for tracing"
 191 The tracing macros are intended to make insertion of tracing information
 192 unobtrusive and painless.  If the
 193 .B NTRACE
 194 macro is defined, all of the tracing macros are disabled and generate no
 195 code; otherwise they do their normal jobs.
 196 .PP
 197 The
 198 .B T
 199 macro simply expands to its argument.  It may be wrapped around small
 200 pieces of code which is only needed when compiling with tracing
 201 enabled.  (Larger blocks, of course, should use
 202 .RB ` "#ifndef NTRACE" '/` #endif '
 203 pairs for clarity's sake.)
 204 .PP
 205 For slightly larger code chunks which do some processing to generate
 206 trace output, the
 207 .B IF_TRACING
 208 macro is useful.  Its first argument is a message level; if the trace
 209 level is set such that the message will be printed, the code in the
 210 second argument is executed.  If code is being compiled without tracing,
 211 of course, the entire contents of the macro is ignored.
 212 .
 213 .\"--------------------------------------------------------------------------
 214 .SH "SEE ALSO"
 215 .
 216 .BR mLib (3).
 217 .
 218 .\"--------------------------------------------------------------------------
 219 .SH "AUTHOR"
 220 .
 221 Mark Wooding, <mdw@distorted.org.uk>
 222 .
 223 .\"----- That's all, folks --------------------------------------------------