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,
37 /*----- Options and conventions -------------------------------------------*
39 * The following macros affect the tracking system:
41 * @TRACK_ENABLE@: Enable tracking of memory allocations
42 * @TRACK_BLAME@: Register my context blocks in allocations
44 * The reason there are two switches is simple. It's often the case that a
45 * library routine allocates memory for its client. Therefore, whether we
46 * want to record the library or the client depends on how much we trust
47 * the two pieces of software. Setting @TRACK_ENABLE@ and @TRACK_BLAME@
48 * suggests that the current source file might leak memory, so we want its
49 * context markers in the list. Setting @TRACK_ENABLE@ but not
50 * @TRACK_BLAME@ suggests that we trust this code, but not the code which
51 * calls it, so we want to preserve the caller's context markers.
56 /*----- Type definitions --------------------------------------------------*/
58 /* --- A context buffer --- */
60 typedef struct track_ctx {
61 struct track_ctx *next;
65 /*----- Functions provided ------------------------------------------------*/
67 /* --- @track_level@ --- *
69 * Arguments: @unsigned int l@ = tracing level for allocation messages
73 * Use: Sets the trace level for allocation messages.
76 extern void track_level(unsigned int /*l*/);
78 /* --- @track_push@ --- *
80 * Arguments: @track_ctx *ctx@ = context holder to push
84 * Use: Pushes the given context block onto the stack.
87 extern void track_push(track_ctx */*ctx*/);
89 /* --- @track_pop@ --- *
91 * Arguments: @track_ctx *ctx@ = context holder to pop
95 * Use: Removes the given context block from the stack.
98 extern void track_pop(track_ctx */*ctx*/);
100 /* --- @track_malloc@ --- *
102 * Arguments: @size_t sz@ = size requested
104 * Returns: Pointer to allocated space, or null
106 * Use: Allocates memory, and tracks how much is allocated.
109 extern void *track_malloc(size_t /*sz*/);
111 /* --- @track_free@ --- *
113 * Arguments: @void *p@ = pointer to an allocated block
117 * Use: Frees memory, and tracks how much is still allocated.
120 extern void track_free(void */*p*/);
122 /* --- @track_realloc@ --- *
124 * Arguments: @void *p@ = pointer to an allocated block
125 * @size_t sz@ = how big it wants to be
127 * Returns: Pointer to the new block.
129 * Use: Reallocates a block, tracking how much memory is still
133 extern void *track_realloc(void */*p*/, size_t /*sz*/);
135 /* --- @track_used@ --- *
139 * Returns: A count of how much memory is used currently.
141 * Use: Returns the amount of memory which the @track_@-functions
142 * above have counted as being currently allocated.
145 extern unsigned long track_used(void);
147 /* --- @track_list@ --- *
149 * Arguments: @unsigned int l@ = trace level to use
153 * Use: Traces a dump of the currently known blocks. Combined with
154 * a verbose dump of allocations and deallocations, and a
155 * good idea of which blocks were allocated where, this can
156 * be useful for locating memory leaks. It's not exactly a
160 extern void track_list(unsigned int l);
162 /*----- Macro wrappers ----------------------------------------------------*/
164 /* --- If tracking is to be done, set it up --- */
168 # define malloc(sz) track_malloc(sz)
170 # define free(p) track_free(p)
172 # define realloc(p, sz) track_realloc(p, sz)
175 /* --- Provide a context for doing track-related things --- */
183 /* --- Handle contexts --- */
185 #if defined(TRACK_ENABLE) && defined(TRACK_BLAME)
186 # define TRACK_NCTX(name, string) track_ctx name = { 0, string }
187 # define TRACK_NPUSH(name) track_push(name)
188 # define TRACK_NPOP(name) track_pop(name)
189 # define TRACK_CTX(string) TRACK_NCTX(__track_ctx, string)
190 # define TRACK_PUSH TRACK_NPUSH(__track_ctx)
191 # define TRACK_POP TRACK_NPOP(__track_ctx)
193 # define TRACK_NCTX(name, string)
194 # define TRACK_NPUSH(name) ((void)0)
195 # define TRACK_NPOP(name) ((void)0)
196 # define TRACK_CTX(string)
197 # define TRACK_PUSH ((void)0)
198 # define TRACK_POP ((void)0)
201 /*----- That's all, folks -------------------------------------------------*/