chiark / gitweb /
~mdw / mLib / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
Ooops. Fix distribution.
[mLib] / trace.h
... / ...
CommitLineData
1/* -*-c-*-
2 *
3 * $Id: trace.h,v 1.6 2001/02/03 16:23:55 mdw Exp $
4 *
5 * Tracing functions for debugging
6 *
7 * (c) 1998 Straylight/Edgeware
8 */
9
10/*----- Licensing notice --------------------------------------------------*
11 *
12 * This file is part of the mLib utilities library.
13 *
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.
18 *
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.
23 *
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,
27 * MA 02111-1307, USA.
28 */
29
30/*----- Revision history --------------------------------------------------*
31 *
32 * $Log: trace.h,v $
33 * Revision 1.6 2001/02/03 16:23:55 mdw
34 * New custom trace output interface.
35 *
36 * Revision 1.5 1999/12/10 23:42:04 mdw
37 * Change header file guard names.
38 *
39 * Revision 1.4 1999/10/22 22:39:52 mdw
40 * New documented interface for tracing.
41 *
42 * Revision 1.3 1999/05/06 19:51:35 mdw
43 * Reformatted the LGPL notice a little bit.
44 *
45 * Revision 1.2 1999/05/05 18:50:31 mdw
46 * Change licensing conditions to LGPL.
47 *
48 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
49 * Initial version of mLib
50 *
51 */
52
53#ifndef MLIB_TRACE_H
54#define MLIB_TRACE_H
55
56#ifdef __cplusplus
57 extern "C" {
58#endif
59
60/*----- Header files ------------------------------------------------------*/
61
62#include <stdio.h>
63
64/*----- Data structures ---------------------------------------------------*/
65
66typedef struct trace_opt {
67 char ch;
68 unsigned f;
69 const char *help;
70} trace_opt;
71
72/*----- Functions provided ------------------------------------------------*/
73
74/* --- @trace@ --- *
75 *
76 * Arguments: @unsigned l@ = trace level for output
77 * @const char *f@ = a @printf@-style format string
78 * @...@ = other arguments
79 *
80 * Returns: ---
81 *
82 * Use: Reports a message to the trace output.
83 */
84
85extern void trace(unsigned /*l*/, const char */*f*/, ...);
86
87/* --- @trace_block@ --- *
88 *
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
93 *
94 * Returns: ---
95 *
96 * Use: Dumps the contents of a block to the trace output.
97 */
98
99extern void trace_block(unsigned /*l*/, const char */*s*/,
100 const void */*b*/, size_t /*sz*/);
101
102/* --- @trace_on@ --- *
103 *
104 * Arguments: @FILE *fp@ = a file to trace on
105 * @unsigned l@ = trace level to set
106 *
107 * Returns: ---
108 *
109 * Use: Enables tracing to a file.
110 */
111
112extern void trace_on(FILE */*fp*/, unsigned /*l*/);
113
114/* --- @trace_custom@ --- *
115 *
116 * Arguments: @void (*func)(const char *buf, size_t sz, void *v)@ =
117 * output function
118 * @void *v@ = magic handle to give to function
119 *
120 * Returns: ---
121 *
122 * Use: Sets up a custom trace handler.
123 */
124
125extern void trace_custom(void (*/*func*/)(const char */*buf*/,
126 size_t /*sz*/, void */*v*/),
127 void */*v*/);
128
129/* --- @trace_level@ --- *
130 *
131 * Arguments: @unsigned l@ = trace level to set
132 *
133 * Returns: ---
134 *
135 * Use: Sets the tracing level.
136 */
137
138extern void trace_level(unsigned /*l*/);
139
140/* --- @tracing@ --- *
141 *
142 * Arguments: ---
143 *
144 * Returns: Zero if not tracing, tracing level if tracing.
145 *
146 * Use: Informs the caller whether tracing is enabled.
147 */
148
149extern unsigned tracing(void);
150
151/* --- @traceopt@ --- *
152 *
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
157 *
158 * Returns: Trace flags as set by user.
159 *
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.
163 */
164
165extern unsigned traceopt(const trace_opt */*t*/, const char */*p*/,
166 unsigned /*f*/, unsigned /*bad*/);
167
168/*----- Tracing macros ----------------------------------------------------*/
169
170#ifndef NTRACE
171# define T(x) x
172# define IF_TRACING(l, x) if ((l) & tracing()) x
173#else
174# define T(x)
175# define IF_TRACING(l, x)
176#endif
177
178/*----- That's all, folks -------------------------------------------------*/
179
180#ifdef __cplusplus
181 }
182#endif
183
184#endif
mLib utilities library