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>" | |
18 | ||
19 | .BI "void trace(unsigned " l ", const char *" f ", ...);" | |
2b1924c2 MW |
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 ); | |
d1836466 | 23 | |
24 | .BI "void trace_on(FILE *" fp ", unsigned " l ); | |
2b1924c2 MW |
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 ); | |
d1836466 | 30 | .BI "void trace_level(unsigned " l ); |
31 | .BI "unsigned tracing(void);" | |
32 | ||
2b1924c2 MW |
33 | .ds mT \fBunsigned traceopt( |
34 | .BI "\*(mTconst trace_opt *" t ", const char *" p , | |
35 | .BI "\h'\w'\*(mT'u'unsigned " f ", unsigned " bad ); | |
d1836466 | 36 | |
37 | .BI T( statements\fR... ) | |
38 | .BI "IF_TRACING(unsigned " l ", " statements\fR... ) | |
39 | .fi | |
40 | .SH "DESCRIPTION" | |
41 | The | |
42 | .B <mLib/trace.h> | |
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 | |
46 | for later. | |
47 | .SS "Trace levels" | |
48 | Each trace message is assigned a | |
49 | .I level | |
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" | |
57 | The basic function is | |
58 | .BR trace . | |
59 | It is passed an integer message level and a | |
60 | .BR printf (3)-style | |
61 | format string together with arguments for the placeholders and emits the | |
62 | resulting message. | |
63 | .PP | |
64 | The function | |
65 | .B trace_block | |
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 | |
69 | in bytes. | |
70 | .SS "Configuring trace output" | |
71 | The tracing destination is set with the function | |
72 | .BR trace_on : | |
73 | it is passed a | |
74 | .B stdio | |
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 | |
77 | on its own using | |
78 | .BR trace_level , | |
79 | which takes the new level as its single argument. The function | |
80 | .B tracing | |
81 | returns the current trace level, or zero if there is no trace | |
82 | destination set. | |
0680be67 | 83 | .PP |
84 | For more advanced programs, a custom output function may be provided by | |
85 | .B trace_custom | |
86 | and passing a function which will write a buffer of data somewhere | |
87 | sensible. | |
d1836466 | 88 | .SS "Parsing user trace options" |
89 | The function | |
90 | .B traceopt | |
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 | |
94 | number of | |
95 | .B trace_opt | |
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: | |
98 | .TP | |
99 | .B "char ch;" | |
100 | The character used to select this bit or collection of bits. | |
101 | .TP | |
102 | .B "unsigned f;" | |
103 | The level bits for this option. | |
104 | .TP | |
105 | .B "const char *help;" | |
106 | A help string describing this option. | |
107 | .PP | |
108 | The table is terminated by an entry whose | |
109 | .B ch | |
110 | member is zero. | |
111 | .PP | |
112 | The arguments to | |
113 | .B traceopt | |
114 | are: | |
115 | .TP | |
116 | .BI "trace_opt *" t | |
117 | Pointer to the trace options table. | |
118 | .TP | |
119 | .BI "const char *" p | |
120 | Pointer to the user's option string. | |
121 | .TP | |
122 | .BI "unsigned " f | |
123 | The default trace options, or the previously-set options. | |
124 | .TP | |
125 | .BI "unsigned " bad | |
126 | A bitmask of level bits which should be disallowed. | |
127 | .PP | |
128 | If the option string | |
129 | .I p | |
130 | is a null pointer or contains only a | |
131 | .RB ` ? ' | |
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 | |
135 | .RB ` + ' | |
136 | and | |
137 | .RB ` \- ' | |
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 | |
140 | allowed. | |
141 | .PP | |
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 | |
146 | program can set the | |
147 | .I bad | |
148 | mask to prevent access to secret information when running setuid, or to | |
149 | zero when not. | |
150 | .SS "Macro support for tracing" | |
151 | The tracing macros are intended to make insertion of tracing information | |
152 | unobtrusive and painless. If the | |
153 | .B NTRACE | |
154 | macro is defined, all of the tracing macros are disabled and generate no | |
155 | code; otherwise they do their normal jobs. | |
156 | .PP | |
157 | The | |
158 | .B T | |
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 | |
76809a64 | 162 | .RB ` "#ifndef NTRACE" '/` #endif ' |
d1836466 | 163 | pairs for clarity's sake.) |
164 | .PP | |
165 | For slightly larger code chunks which do some processing to generate | |
166 | trace output, the | |
167 | .B IF_TRACING | |
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. | |
172 | .SH "SEE ALSO" | |
173 | .BR mLib (3). | |
174 | .SH "AUTHOR" | |
9b5ac6ff | 175 | Mark Wooding, <mdw@distorted.org.uk> |