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