chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / trace / trace.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
0875b58f 3 * Tracing functions for debugging
4 *
5 * (c) 1998 Straylight/Edgeware
6 */
7
d4efbcd9 8/*----- Licensing notice --------------------------------------------------*
0875b58f 9 *
10 * This file is part of the mLib utilities library.
11 *
12 * mLib is free software; you can redistribute it and/or modify
c846879c 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.
d4efbcd9 16 *
0875b58f 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
c846879c 20 * GNU Library General Public License for more details.
d4efbcd9 21 *
c846879c 22 * You should have received a copy of the GNU Library General Public
0bd98442 23 * License along with mLib; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
25 * MA 02111-1307, USA.
0875b58f 26 */
27
c6e0eaf0 28#ifndef MLIB_TRACE_H
29#define MLIB_TRACE_H
0875b58f 30
31#ifdef __cplusplus
32 extern "C" {
33#endif
34
de3ceebe 35/*----- Header files ------------------------------------------------------*/
36
0875b58f 37#include <stdio.h>
38
de3ceebe 39/*----- Data structures ---------------------------------------------------*/
40
41typedef struct trace_opt {
42 char ch;
43 unsigned f;
44 const char *help;
45} trace_opt;
46
0875b58f 47/*----- Functions provided ------------------------------------------------*/
48
49/* --- @trace@ --- *
50 *
de3ceebe 51 * Arguments: @unsigned l@ = trace level for output
0875b58f 52 * @const char *f@ = a @printf@-style format string
53 * @...@ = other arguments
54 *
55 * Returns: ---
56 *
57 * Use: Reports a message to the trace output.
58 */
59
de3ceebe 60extern void trace(unsigned /*l*/, const char */*f*/, ...);
0875b58f 61
62/* --- @trace_block@ --- *
63 *
de3ceebe 64 * Arguments: @unsigned l@ = trace level for output
0875b58f 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
68 *
69 * Returns: ---
70 *
71 * Use: Dumps the contents of a block to the trace output.
72 */
73
de3ceebe 74extern void trace_block(unsigned /*l*/, const char */*s*/,
0875b58f 75 const void */*b*/, size_t /*sz*/);
76
77/* --- @trace_on@ --- *
78 *
79 * Arguments: @FILE *fp@ = a file to trace on
de3ceebe 80 * @unsigned l@ = trace level to set
0875b58f 81 *
82 * Returns: ---
83 *
84 * Use: Enables tracing to a file.
85 */
86
de3ceebe 87extern void trace_on(FILE */*fp*/, unsigned /*l*/);
0875b58f 88
e4452aaa 89/* --- @trace_custom@ --- *
90 *
91 * Arguments: @void (*func)(const char *buf, size_t sz, void *v)@ =
92 * output function
93 * @void *v@ = magic handle to give to function
94 *
95 * Returns: ---
96 *
97 * Use: Sets up a custom trace handler.
98 */
99
100extern void trace_custom(void (*/*func*/)(const char */*buf*/,
101 size_t /*sz*/, void */*v*/),
102 void */*v*/);
103
de3ceebe 104/* --- @trace_level@ --- *
0875b58f 105 *
de3ceebe 106 * Arguments: @unsigned l@ = trace level to set
0875b58f 107 *
108 * Returns: ---
109 *
110 * Use: Sets the tracing level.
111 */
112
de3ceebe 113extern void trace_level(unsigned /*l*/);
0875b58f 114
115/* --- @tracing@ --- *
116 *
117 * Arguments: ---
118 *
119 * Returns: Zero if not tracing, tracing level if tracing.
120 *
121 * Use: Informs the caller whether tracing is enabled.
122 */
123
de3ceebe 124extern unsigned tracing(void);
125
126/* --- @traceopt@ --- *
127 *
e4452aaa 128 * Arguments: @const trace_opt *t@ = pointer to trace options table
de3ceebe 129 * @const char *p@ = option string supplied by user
130 * @unsigned f@ = initial tracing flags
131 * @unsigned bad@ = forbidden tracing flags
132 *
133 * Returns: Trace flags as set by user.
134 *
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.
138 */
139
e4452aaa 140extern unsigned traceopt(const trace_opt */*t*/, const char */*p*/,
de3ceebe 141 unsigned /*f*/, unsigned /*bad*/);
0875b58f 142
143/*----- Tracing macros ----------------------------------------------------*/
144
145#ifndef NTRACE
146# define T(x) x
147# define IF_TRACING(l, x) if ((l) & tracing()) x
148#else
149# define T(x)
150# define IF_TRACING(l, x)
151#endif
152
153/*----- That's all, folks -------------------------------------------------*/
154
155#ifdef __cplusplus
156 }
157#endif
158
159#endif