3 * $Id: trace.h,v 1.6 2001/02/03 16:23:55 mdw Exp $
5 * Tracing functions for debugging
7 * (c) 1998 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * mLib is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.6 2001/02/03 16:23:55 mdw
34 * New custom trace output interface.
36 * Revision 1.5 1999/12/10 23:42:04 mdw
37 * Change header file guard names.
39 * Revision 1.4 1999/10/22 22:39:52 mdw
40 * New documented interface for tracing.
42 * Revision 1.3 1999/05/06 19:51:35 mdw
43 * Reformatted the LGPL notice a little bit.
45 * Revision 1.2 1999/05/05 18:50:31 mdw
46 * Change licensing conditions to LGPL.
48 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
49 * Initial version of mLib
60 /*----- Header files ------------------------------------------------------*/
64 /*----- Data structures ---------------------------------------------------*/
66 typedef struct trace_opt
{
72 /*----- Functions provided ------------------------------------------------*/
76 * Arguments: @unsigned l@ = trace level for output
77 * @const char *f@ = a @printf@-style format string
78 * @...@ = other arguments
82 * Use: Reports a message to the trace output.
85 extern void trace(unsigned /*l*/, const char */
*f*/
, ...);
87 /* --- @trace_block@ --- *
89 * Arguments: @unsigned l@ = trace level for output
90 * @const char *s@ = some header string to write
91 * @const void *b@ = pointer to a block of memory to dump
92 * @size_t sz@ = size of the block of memory
96 * Use: Dumps the contents of a block to the trace output.
99 extern void trace_block(unsigned /*l*/, const char */
*s*/
,
100 const void */
*b*/
, size_t /*sz*/);
102 /* --- @trace_on@ --- *
104 * Arguments: @FILE *fp@ = a file to trace on
105 * @unsigned l@ = trace level to set
109 * Use: Enables tracing to a file.
112 extern void trace_on(FILE */
*fp*/
, unsigned /*l*/);
114 /* --- @trace_custom@ --- *
116 * Arguments: @void (*func)(const char *buf, size_t sz, void *v)@ =
118 * @void *v@ = magic handle to give to function
122 * Use: Sets up a custom trace handler.
125 extern void trace_custom(void (*/
*func*/
)(const char */
*buf*/
,
126 size_t /*sz*/, void */
*v*/
),
129 /* --- @trace_level@ --- *
131 * Arguments: @unsigned l@ = trace level to set
135 * Use: Sets the tracing level.
138 extern void trace_level(unsigned /*l*/);
140 /* --- @tracing@ --- *
144 * Returns: Zero if not tracing, tracing level if tracing.
146 * Use: Informs the caller whether tracing is enabled.
149 extern unsigned tracing(void);
151 /* --- @traceopt@ --- *
153 * Arguments: @const trace_opt *t@ = pointer to trace options table
154 * @const char *p@ = option string supplied by user
155 * @unsigned f@ = initial tracing flags
156 * @unsigned bad@ = forbidden tracing flags
158 * Returns: Trace flags as set by user.
160 * Use: Parses an option string from the user and sets the
161 * appropriate trace flags. If the argument is null or a single
162 * `?' character, a help message is displayed.
165 extern unsigned traceopt(const trace_opt */
*t*/
, const char */
*p*/
,
166 unsigned /*f*/, unsigned /*bad*/);
168 /*----- Tracing macros ----------------------------------------------------*/
172 # define IF_TRACING(l, x) if ((l) & tracing()) x
175 # define IF_TRACING(l, x)
178 /*----- That's all, folks -------------------------------------------------*/