| 1 | .\" -*-nroff-*- |
| 2 | .\" |
| 3 | .\" Manual for tracing |
| 4 | .\" |
| 5 | .\" (c) 1999, 2001, 2005, 2009, 2017, 2023, 2024 Straylight/Edgeware |
| 6 | .\" |
| 7 | . |
| 8 | .\"----- Licensing notice --------------------------------------------------- |
| 9 | .\" |
| 10 | .\" This file is part of the mLib utilities library. |
| 11 | .\" |
| 12 | .\" mLib is free software: you can redistribute it and/or modify it under |
| 13 | .\" the terms of the GNU Library General Public License as published by |
| 14 | .\" the Free Software Foundation; either version 2 of the License, or (at |
| 15 | .\" your option) any later version. |
| 16 | .\" |
| 17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT |
| 18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
| 20 | .\" License for more details. |
| 21 | .\" |
| 22 | .\" You should have received a copy of the GNU Library General Public |
| 23 | .\" License along with mLib. If not, write to the Free Software |
| 24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, |
| 25 | .\" USA. |
| 26 | . |
| 27 | .\"-------------------------------------------------------------------------- |
| 28 | .so ../defs.man \" @@@PRE@@@ |
| 29 | . |
| 30 | .\"-------------------------------------------------------------------------- |
| 31 | .TH trace 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library" |
| 32 | .\" @trace |
| 33 | .\" @trace_block |
| 34 | .\" @trace_on |
| 35 | .\" @trace_custom |
| 36 | .\" @trace_level |
| 37 | .\" @tracing |
| 38 | .\" @traceopt |
| 39 | .\" @NTRACE |
| 40 | .\" @T |
| 41 | .\" IF_TRACING |
| 42 | . |
| 43 | .\"-------------------------------------------------------------------------- |
| 44 | .SH "NAME" |
| 45 | trace \- configurable tracing output |
| 46 | . |
| 47 | .\"-------------------------------------------------------------------------- |
| 48 | .SH "SYNOPSIS" |
| 49 | . |
| 50 | .nf |
| 51 | .B "#include <mLib/trace.h>" |
| 52 | .PP |
| 53 | .BI "void trace(unsigned " l ", const char *" f ", ...);" |
| 54 | .ta \w'\fBvoid trace_block('u |
| 55 | .BI "void trace_block(unsigned " l ", const char *" s , |
| 56 | .BI " const void *" b ", size_t " sz ); |
| 57 | .PP |
| 58 | .BI "void trace_on(FILE *" fp ", unsigned " l ); |
| 59 | .ta \w'\fBvoid trace_custom('u +\w'\fBvoid (*\,\fIfunc\/\fB)('u |
| 60 | .BI "void trace_custom(void (*" func ")(const char *" buf , |
| 61 | .BI " size_t " sz ", void *" v ), |
| 62 | .BI " void *" v ); |
| 63 | .BI "void trace_level(unsigned " l ); |
| 64 | .BI "unsigned tracing(void);" |
| 65 | .PP |
| 66 | .ta \w'\fBunsigned traceopt('u |
| 67 | .BI "unsigned traceopt(const trace_opt *" t ", const char *" p , |
| 68 | .BI " unsigned " f ", unsigned " bad ); |
| 69 | .PP |
| 70 | .BI T( statements\fR... ) |
| 71 | .BI "IF_TRACING(unsigned " l ", " statements\fR... ) |
| 72 | .fi |
| 73 | . |
| 74 | .\"-------------------------------------------------------------------------- |
| 75 | .SH "DESCRIPTION" |
| 76 | . |
| 77 | The |
| 78 | .B <mLib/trace.h> |
| 79 | header declares some functions and macros for handling trace output. |
| 80 | The emphasis for this system is primarily on user configurability of |
| 81 | what gets traced rather than where the output goes. That's a project |
| 82 | for later. |
| 83 | .SS "Trace levels" |
| 84 | Each trace message is assigned a |
| 85 | .I level |
| 86 | by the programmer. A tracing level is set during program |
| 87 | initialization, usually by the user. A trace message is output if there |
| 88 | is a trace destination set, and the result of a bitwise AND between the |
| 89 | message level and the overall tracing level is nonzero. The idea is |
| 90 | that the programmer assigns a different bit to each group of trace |
| 91 | messages, and allows a user to select which ones are wanted. |
| 92 | . |
| 93 | .SS "Producing trace output" |
| 94 | The basic function is |
| 95 | .BR trace . |
| 96 | It is passed an integer message level and a |
| 97 | .BR printf (3)-style |
| 98 | format string together with arguments for the placeholders and emits the |
| 99 | resulting message. |
| 100 | .PP |
| 101 | The function |
| 102 | .B trace_block |
| 103 | formats an arbitrary block of memory as a hex dump. The arguments are, |
| 104 | in order, the message level, a pointer to the header string for the hex |
| 105 | dump, the base address of the block to dump, and the size of the block |
| 106 | in bytes. |
| 107 | . |
| 108 | .SS "Configuring trace output" |
| 109 | The tracing destination is set with the function |
| 110 | .BR trace_on : |
| 111 | it is passed a |
| 112 | .B stdio |
| 113 | stream and a trace level to set. The stream may be null to disable |
| 114 | tracing completely (which is the default). The trace level may be set |
| 115 | on its own using |
| 116 | .BR trace_level , |
| 117 | which takes the new level as its single argument. The function |
| 118 | .B tracing |
| 119 | returns the current trace level, or zero if there is no trace |
| 120 | destination set. |
| 121 | .PP |
| 122 | For more advanced programs, a custom output function may be provided by |
| 123 | .B trace_custom |
| 124 | and passing a function which will write a buffer of data somewhere |
| 125 | sensible. |
| 126 | . |
| 127 | .SS "Parsing user trace options" |
| 128 | The function |
| 129 | .B traceopt |
| 130 | may be used to allow a user to set the trace level. It is passed a |
| 131 | table describing the available trace level bits, and some other |
| 132 | information, and returns a new trace level. The table consists of a |
| 133 | number of |
| 134 | .B trace_opt |
| 135 | structures, each of which describes a bit or selection of bits which may |
| 136 | be controlled. The structure contains the following members, in order: |
| 137 | .TP |
| 138 | .B "char ch;" |
| 139 | The character used to select this bit or collection of bits. |
| 140 | .TP |
| 141 | .B "unsigned f;" |
| 142 | The level bits for this option. |
| 143 | .TP |
| 144 | .B "const char *help;" |
| 145 | A help string describing this option. |
| 146 | .PP |
| 147 | The table is terminated by an entry whose |
| 148 | .B ch |
| 149 | member is zero. |
| 150 | .PP |
| 151 | The arguments to |
| 152 | .B traceopt |
| 153 | are: |
| 154 | .TP |
| 155 | .BI "trace_opt *" t |
| 156 | Pointer to the trace options table. |
| 157 | .TP |
| 158 | .BI "const char *" p |
| 159 | Pointer to the user's option string. |
| 160 | .TP |
| 161 | .BI "unsigned " f |
| 162 | The default trace options, or the previously-set options. |
| 163 | .TP |
| 164 | .BI "unsigned " bad |
| 165 | A bitmask of level bits which should be disallowed. |
| 166 | .PP |
| 167 | If the option string |
| 168 | .I p |
| 169 | is a null pointer or contains only a |
| 170 | .RB ` ? ' |
| 171 | character, a help message is printed and the default is returned. Only |
| 172 | trace options which contain non-bad bits are displayed. Otherwise the |
| 173 | string contains option characters together with |
| 174 | .RB ` + ' |
| 175 | and |
| 176 | .RB ` \- ' |
| 177 | which respectively turn on or off the following options; the default is |
| 178 | to turn options on. Again, only options which contain non-bad bits are |
| 179 | allowed. |
| 180 | .PP |
| 181 | The `bad bit' mechanism is provided for setuid programs which in their |
| 182 | normal configuration deal with privileged information which mustn't be |
| 183 | given out to users. However, if run by someone with appropriate |
| 184 | privilege such options are safe and may be useful for debugging. The |
| 185 | program can set the |
| 186 | .I bad |
| 187 | mask to prevent access to secret information when running setuid, or to |
| 188 | zero when not. |
| 189 | . |
| 190 | .SS "Macro support for tracing" |
| 191 | The tracing macros are intended to make insertion of tracing information |
| 192 | unobtrusive and painless. If the |
| 193 | .B NTRACE |
| 194 | macro is defined, all of the tracing macros are disabled and generate no |
| 195 | code; otherwise they do their normal jobs. |
| 196 | .PP |
| 197 | The |
| 198 | .B T |
| 199 | macro simply expands to its argument. It may be wrapped around small |
| 200 | pieces of code which is only needed when compiling with tracing |
| 201 | enabled. (Larger blocks, of course, should use |
| 202 | .RB ` "#ifndef NTRACE" '/` #endif ' |
| 203 | pairs for clarity's sake.) |
| 204 | .PP |
| 205 | For slightly larger code chunks which do some processing to generate |
| 206 | trace output, the |
| 207 | .B IF_TRACING |
| 208 | macro is useful. Its first argument is a message level; if the trace |
| 209 | level is set such that the message will be printed, the code in the |
| 210 | second argument is executed. If code is being compiled without tracing, |
| 211 | of course, the entire contents of the macro is ignored. |
| 212 | . |
| 213 | .\"-------------------------------------------------------------------------- |
| 214 | .SH "SEE ALSO" |
| 215 | . |
| 216 | .BR mLib (3). |
| 217 | . |
| 218 | .\"-------------------------------------------------------------------------- |
| 219 | .SH "AUTHOR" |
| 220 | . |
| 221 | Mark Wooding, <mdw@distorted.org.uk> |
| 222 | . |
| 223 | .\"----- That's all, folks -------------------------------------------------- |