2 .TH trace 3 "21 October 1999" mLib
4 trace \- configurable tracing output
16 .B "#include <mLib/trace.h>"
18 .BI "void trace(unsigned " l ", const char *" f ", ...);"
19 .BI "void trace_block(unsigned " l ", const char *" s ,
20 .BI " const void *" b ", size_t " sz );
22 .BI "void trace_on(FILE *" fp ", unsigned " l );
23 .BI "void trace_level(unsigned " l );
24 .BI "unsigned tracing(void);"
26 .BI "unsigned traceopt(trace_opt *" t ", const char *" p ,
27 .BI " unsigned " f ", unsigned " bad );
29 .BI T( statements\fR... )
30 .BI "IF_TRACING(unsigned " l ", " statements\fR... )
35 header declares some functions and macros for handling trace output.
36 The emphasis for this system is primarily on user configurability of
37 what gets traced rather than where the output goes. That's a project
40 Each trace message is assigned a
42 by the programmer. A tracing level is set during program
43 initialization, usually by the user. A trace message is output if there
44 is a trace destination set, and the result of a bitwise AND between the
45 message level and the overall tracing level is nonzero. The idea is
46 that the programmer assigns a different bit to each group of trace
47 messages, and allows a user to select which ones are wanted.
48 .SS "Producing trace output"
51 It is passed an integer message level and a
53 format string together with arguments for the placeholders and emits the
58 formats an arbitrary block of memory as a hex dump. The arguments are,
59 in order, the message level, a pointer to the header string for the hex
60 dump, the base address of the block to dump, and the size of the block
62 .SS "Configuring trace output"
63 The tracing destination is set with the function
67 stream and a trace level to set. The stream may be null to disable
68 tracing completely (which is the default). The trace level may be set
71 which takes the new level as its single argument. The function
73 returns the current trace level, or zero if there is no trace
75 .SS "Parsing user trace options"
78 may be used to allow a user to set the trace level. It is passed a
79 table describing the available trace level bits, and some other
80 information, and returns a new trace level. The table consists of a
83 structures, each of which describes a bit or selection of bits which may
84 be controlled. The structure contains the following members, in order:
87 The character used to select this bit or collection of bits.
90 The level bits for this option.
92 .B "const char *help;"
93 A help string describing this option.
95 The table is terminated by an entry whose
104 Pointer to the trace options table.
107 Pointer to the user's option string.
110 The default trace options, or the previously-set options.
113 A bitmask of level bits which should be disallowed.
117 is a null pointer or contains only a
119 character, a help message is printed and the default is returned. Only
120 trace options which contain non-bad bits are displayed. Otherwise the
121 string contains option characters together with
125 which respectively turn on or off the following options; the default is
126 to turn options on. Again, only options which contain non-bad bits are
129 The `bad bit' mechanism is provided for setuid programs which in their
130 normal configuration deal with privileged information which mustn't be
131 given out to users. However, if run by someone with appropriate
132 privilege such options are safe and may be useful for debugging. The
135 mask to prevent access to secret information when running setuid, or to
137 .SS "Macro support for tracing"
138 The tracing macros are intended to make insertion of tracing information
139 unobtrusive and painless. If the
141 macro is defined, all of the tracing macros are disabled and generate no
142 code; otherwise they do their normal jobs.
146 macro simply expands to its argument. It may be wrapped around small
147 pieces of code which is only needed when compiling with tracing
148 enabled. (Larger blocks, of course, should use
149 .RB ` #ifndef NTRACE '/` #endif '
150 pairs for clarity's sake.)
152 For slightly larger code chunks which do some processing to generate
155 macro is useful. Its first argument is a message level; if the trace
156 level is set such that the message will be printed, the code in the
157 second argument is executed. If code is being compiled without tracing,
158 of course, the entire contents of the macro is ignored.
162 Mark Wooding, <mdw@nsict.org>