2 .TH trace 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
4 trace \- configurable tracing output
17 .B "#include <mLib/trace.h>"
19 .BI "void trace(unsigned " l ", const char *" f ", ...);"
20 .ds mT \fBvoid trace_block(
21 .BI "\*(mTunsigned " l ", const char *" s ,
22 .BI "\h'\w'\*(mT'u'const void *" b ", size_t " sz );
24 .BI "void trace_on(FILE *" fp ", unsigned " l );
25 .ds mT \fBvoid trace_custom(
26 .ds mU \*(mTvoid (*\fIfunc\fB)(
27 .BI "\*(mUconst char *" buf ,
28 .BI "\h'\w'\*(mU'u'size_t " sz ", void *" v ),
29 .BI "\h'\w'\*(mT'u'void *" v );
30 .BI "void trace_level(unsigned " l );
31 .BI "unsigned tracing(void);"
33 .ds mT \fBunsigned traceopt(
34 .BI "\*(mTconst trace_opt *" t ", const char *" p ,
35 .BI "\h'\w'\*(mT'u'unsigned " f ", unsigned " bad );
37 .BI T( statements\fR... )
38 .BI "IF_TRACING(unsigned " l ", " statements\fR... )
43 header declares some functions and macros for handling trace output.
44 The emphasis for this system is primarily on user configurability of
45 what gets traced rather than where the output goes. That's a project
48 Each trace message is assigned a
50 by the programmer. A tracing level is set during program
51 initialization, usually by the user. A trace message is output if there
52 is a trace destination set, and the result of a bitwise AND between the
53 message level and the overall tracing level is nonzero. The idea is
54 that the programmer assigns a different bit to each group of trace
55 messages, and allows a user to select which ones are wanted.
56 .SS "Producing trace output"
59 It is passed an integer message level and a
61 format string together with arguments for the placeholders and emits the
66 formats an arbitrary block of memory as a hex dump. The arguments are,
67 in order, the message level, a pointer to the header string for the hex
68 dump, the base address of the block to dump, and the size of the block
70 .SS "Configuring trace output"
71 The tracing destination is set with the function
75 stream and a trace level to set. The stream may be null to disable
76 tracing completely (which is the default). The trace level may be set
79 which takes the new level as its single argument. The function
81 returns the current trace level, or zero if there is no trace
84 For more advanced programs, a custom output function may be provided by
86 and passing a function which will write a buffer of data somewhere
88 .SS "Parsing user trace options"
91 may be used to allow a user to set the trace level. It is passed a
92 table describing the available trace level bits, and some other
93 information, and returns a new trace level. The table consists of a
96 structures, each of which describes a bit or selection of bits which may
97 be controlled. The structure contains the following members, in order:
100 The character used to select this bit or collection of bits.
103 The level bits for this option.
105 .B "const char *help;"
106 A help string describing this option.
108 The table is terminated by an entry whose
117 Pointer to the trace options table.
120 Pointer to the user's option string.
123 The default trace options, or the previously-set options.
126 A bitmask of level bits which should be disallowed.
130 is a null pointer or contains only a
132 character, a help message is printed and the default is returned. Only
133 trace options which contain non-bad bits are displayed. Otherwise the
134 string contains option characters together with
138 which respectively turn on or off the following options; the default is
139 to turn options on. Again, only options which contain non-bad bits are
142 The `bad bit' mechanism is provided for setuid programs which in their
143 normal configuration deal with privileged information which mustn't be
144 given out to users. However, if run by someone with appropriate
145 privilege such options are safe and may be useful for debugging. The
148 mask to prevent access to secret information when running setuid, or to
150 .SS "Macro support for tracing"
151 The tracing macros are intended to make insertion of tracing information
152 unobtrusive and painless. If the
154 macro is defined, all of the tracing macros are disabled and generate no
155 code; otherwise they do their normal jobs.
159 macro simply expands to its argument. It may be wrapped around small
160 pieces of code which is only needed when compiling with tracing
161 enabled. (Larger blocks, of course, should use
162 .RB ` "#ifndef NTRACE" '/` #endif '
163 pairs for clarity's sake.)
165 For slightly larger code chunks which do some processing to generate
168 macro is useful. Its first argument is a message level; if the trace
169 level is set such that the message will be printed, the code in the
170 second argument is executed. If code is being compiled without tracing,
171 of course, the entire contents of the macro is ignored.
175 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob