chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / trace / trace.3
CommitLineData
d1836466 1.\" -*-nroff-*-
fbf20b5b 2.TH trace 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
d1836466 3.SH "NAME"
4trace \- configurable tracing output
5.\" @trace
6.\" @trace_block
7.\" @trace_on
0680be67 8.\" @trace_custom
d1836466 9.\" @trace_level
10.\" @tracing
11.\" @traceopt
12.\" @NTRACE
13.\" @T
14.\" IF_TRACING
15.SH "SYNOPSIS"
16.nf
17.B "#include <mLib/trace.h>"
18
19.BI "void trace(unsigned " l ", const char *" f ", ...);"
20.BI "void trace_block(unsigned " l ", const char *" s ,
21.BI " const void *" b ", size_t " sz );
22
23.BI "void trace_on(FILE *" fp ", unsigned " l );
0680be67 24.BI "void trace_custom(void (*" func ")(const char *" buf ,
25.BI " size_t " sz ", void *" v ),
26.BI " void *" v );
d1836466 27.BI "void trace_level(unsigned " l );
28.BI "unsigned tracing(void);"
29
0680be67 30.BI "unsigned traceopt(const trace_opt *" t ", const char *" p ,
d1836466 31.BI " unsigned " f ", unsigned " bad );
32
33.BI T( statements\fR... )
34.BI "IF_TRACING(unsigned " l ", " statements\fR... )
35.fi
36.SH "DESCRIPTION"
37The
38.B <mLib/trace.h>
39header declares some functions and macros for handling trace output.
40The emphasis for this system is primarily on user configurability of
41what gets traced rather than where the output goes. That's a project
42for later.
43.SS "Trace levels"
44Each trace message is assigned a
45.I level
46by the programmer. A tracing level is set during program
47initialization, usually by the user. A trace message is output if there
48is a trace destination set, and the result of a bitwise AND between the
49message level and the overall tracing level is nonzero. The idea is
50that the programmer assigns a different bit to each group of trace
51messages, and allows a user to select which ones are wanted.
52.SS "Producing trace output"
53The basic function is
54.BR trace .
55It is passed an integer message level and a
56.BR printf (3)-style
57format string together with arguments for the placeholders and emits the
58resulting message.
59.PP
60The function
61.B trace_block
62formats an arbitrary block of memory as a hex dump. The arguments are,
63in order, the message level, a pointer to the header string for the hex
64dump, the base address of the block to dump, and the size of the block
65in bytes.
66.SS "Configuring trace output"
67The tracing destination is set with the function
68.BR trace_on :
69it is passed a
70.B stdio
71stream and a trace level to set. The stream may be null to disable
72tracing completely (which is the default). The trace level may be set
73on its own using
74.BR trace_level ,
75which takes the new level as its single argument. The function
76.B tracing
77returns the current trace level, or zero if there is no trace
78destination set.
0680be67 79.PP
80For more advanced programs, a custom output function may be provided by
81.B trace_custom
82and passing a function which will write a buffer of data somewhere
83sensible.
d1836466 84.SS "Parsing user trace options"
85The function
86.B traceopt
87may be used to allow a user to set the trace level. It is passed a
88table describing the available trace level bits, and some other
89information, and returns a new trace level. The table consists of a
90number of
91.B trace_opt
92structures, each of which describes a bit or selection of bits which may
93be controlled. The structure contains the following members, in order:
94.TP
95.B "char ch;"
96The character used to select this bit or collection of bits.
97.TP
98.B "unsigned f;"
99The level bits for this option.
100.TP
101.B "const char *help;"
102A help string describing this option.
103.PP
104The table is terminated by an entry whose
105.B ch
106member is zero.
107.PP
108The arguments to
109.B traceopt
110are:
111.TP
112.BI "trace_opt *" t
113Pointer to the trace options table.
114.TP
115.BI "const char *" p
116Pointer to the user's option string.
117.TP
118.BI "unsigned " f
119The default trace options, or the previously-set options.
120.TP
121.BI "unsigned " bad
122A bitmask of level bits which should be disallowed.
123.PP
124If the option string
125.I p
126is a null pointer or contains only a
127.RB ` ? '
128character, a help message is printed and the default is returned. Only
129trace options which contain non-bad bits are displayed. Otherwise the
130string contains option characters together with
131.RB ` + '
132and
133.RB ` \- '
134which respectively turn on or off the following options; the default is
135to turn options on. Again, only options which contain non-bad bits are
136allowed.
137.PP
138The `bad bit' mechanism is provided for setuid programs which in their
139normal configuration deal with privileged information which mustn't be
140given out to users. However, if run by someone with appropriate
141privilege such options are safe and may be useful for debugging. The
142program can set the
143.I bad
144mask to prevent access to secret information when running setuid, or to
145zero when not.
146.SS "Macro support for tracing"
147The tracing macros are intended to make insertion of tracing information
148unobtrusive and painless. If the
149.B NTRACE
150macro is defined, all of the tracing macros are disabled and generate no
151code; otherwise they do their normal jobs.
152.PP
153The
154.B T
155macro simply expands to its argument. It may be wrapped around small
156pieces of code which is only needed when compiling with tracing
157enabled. (Larger blocks, of course, should use
158.RB ` #ifndef NTRACE '/` #endif '
159pairs for clarity's sake.)
160.PP
161For slightly larger code chunks which do some processing to generate
162trace output, the
163.B IF_TRACING
164macro is useful. Its first argument is a message level; if the trace
165level is set such that the message will be printed, the code in the
166second argument is executed. If code is being compiled without tracing,
167of course, the entire contents of the macro is ignored.
168.SH "SEE ALSO"
169.BR mLib (3).
170.SH "AUTHOR"
9b5ac6ff 171Mark Wooding, <mdw@distorted.org.uk>