3 * Tracing functions for debugging
5 * (c) 1998 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the mLib utilities library.
12 * mLib is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * mLib is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with mLib; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
35 /*----- Header files ------------------------------------------------------*/
39 /*----- Data structures ---------------------------------------------------*/
41 typedef struct trace_opt {
47 /*----- Functions provided ------------------------------------------------*/
51 * Arguments: @unsigned l@ = trace level for output
52 * @const char *f@ = a @printf@-style format string
53 * @...@ = other arguments
57 * Use: Reports a message to the trace output.
60 extern void trace(unsigned /*l*/, const char */*f*/, ...);
62 /* --- @trace_block@ --- *
64 * Arguments: @unsigned l@ = trace level for output
65 * @const char *s@ = some header string to write
66 * @const void *b@ = pointer to a block of memory to dump
67 * @size_t sz@ = size of the block of memory
71 * Use: Dumps the contents of a block to the trace output.
74 extern void trace_block(unsigned /*l*/, const char */*s*/,
75 const void */*b*/, size_t /*sz*/);
77 /* --- @trace_on@ --- *
79 * Arguments: @FILE *fp@ = a file to trace on
80 * @unsigned l@ = trace level to set
84 * Use: Enables tracing to a file.
87 extern void trace_on(FILE */*fp*/, unsigned /*l*/);
89 /* --- @trace_custom@ --- *
91 * Arguments: @void (*func)(const char *buf, size_t sz, void *v)@ =
93 * @void *v@ = magic handle to give to function
97 * Use: Sets up a custom trace handler.
100 extern void trace_custom(void (*/*func*/)(const char */*buf*/,
101 size_t /*sz*/, void */*v*/),
104 /* --- @trace_level@ --- *
106 * Arguments: @unsigned l@ = trace level to set
110 * Use: Sets the tracing level.
113 extern void trace_level(unsigned /*l*/);
115 /* --- @tracing@ --- *
119 * Returns: Zero if not tracing, tracing level if tracing.
121 * Use: Informs the caller whether tracing is enabled.
124 extern unsigned tracing(void);
126 /* --- @traceopt@ --- *
128 * Arguments: @const trace_opt *t@ = pointer to trace options table
129 * @const char *p@ = option string supplied by user
130 * @unsigned f@ = initial tracing flags
131 * @unsigned bad@ = forbidden tracing flags
133 * Returns: Trace flags as set by user.
135 * Use: Parses an option string from the user and sets the
136 * appropriate trace flags. If the argument is null or a single
137 * `?' character, a help message is displayed.
140 extern unsigned traceopt(const trace_opt */*t*/, const char */*p*/,
141 unsigned /*f*/, unsigned /*bad*/);
143 /*----- Tracing macros ----------------------------------------------------*/
147 # define IF_TRACING(l, x) if ((l) & tracing()) x
150 # define IF_TRACING(l, x)
153 /*----- That's all, folks -------------------------------------------------*/