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