-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathexude.3
153 lines (149 loc) · 3.65 KB
/
exude.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
.\"
.\" Copyright (c) 2011 Marco Peereboom <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 7 2011 $
.Dt EXUDE 3
.Os
.Sh NAME
.Nm exude
.Nd memory debugger
.Sh SYNOPSIS
.Fd #include <exude.h>
.Ft int
.Fn e_asprintf "char **ret" "const char *fmt" "..."
.Ft void *
.Fn e_calloc "size_t nmemb" "size_t size"
.Ft void
.Fn e_check_memory "void"
.Ft void
.Fn e_free "void **ptr"
.Ft void *
.Fn e_malloc "size_t size"
.Ft void *
.Fn e_realloc "void *ptr" "size_t size"
.Ft char *
.Fn e_strdup "const char *s"
.Ft int
.Fn e_vasprintf "char **ret" "const char *format" "va_list ap"
.Ft void
.Fn exude_version "int *major" "int *minor" "int *patch"
.Ft void
.Fn exude_enable "uint64_t debug_bit"
.Ft void
.Fn exude_disable "void"
.Ft void
.Fn exude_enable_threads "void"
.Ft void
.Fn exude_cleanup "void"
.Sh DESCRIPTION
.Nm
is a memory debugging library that aids in finding memory leaks.
.Pp
.Fn exude_enable
and
.Fn exude_disable
are routines to enable and disable debugging respectively. Debugging
is disabled by default.
The
.Fa debug_mask
parameter to
.Fn exude_enable
determines the
.Xr clog 3
debug mask that will be used by debugging functions.
The macro
.Fa EXUDE_DBG_ALWAYS
may be used to log unconditionally.
If
.Nm
is to be used in a threaded application then
.Fn exude_enable_threads
should be called before using library functions.
.Fn exude_cleanup
may be called to free any resources if the library is no longer needed.
.Pp
.Fn e_asprintf ,
.Fn e_calloc ,
.Fn e_malloc ,
.Fn e_realloc ,
.Fn e_strdup ,
and
.Fn e_vasprintf
are all wrapper functions to the standard system functions and are used
in the same way.
.Pp
.Fn e_free
is a wrapper function around
.Xr free 3 ,
but takes a pointer to a variable instead. The variable will be set to
NULL to remove references to the freed memory.
.Pp
.Fn e_check_memory
can be called to verify that all
.Nm
tracked memory allocations have been freed. This function will abort
(coredump) if not all memory has been freed. If
.Xr clog_init 3
and
.Xr clog_set_flags 3
have been called,
.Fn e_check_memory
will show all of the callers that allocated memory which have not been freed.
.Pp
.Fn exude_version
sets the values of
.Fa major ,
.Fa minor ,
and
.Fa patch
to their respected values.
.Sh EXAMPLES
The following will point
.Fa ptr
to an allocated area of memory containing the NUL-terminated string "foobar",
then free the memory:
.Bd -literal -offset indent
char *ptr;
exude_enable();
ptr = e_strdup("foobar");
e_free(&str);
.Ed
.Pp
The following use of
.Fn e_check_memory
will output memory allocation to stderr and abort due to all memory not
being freed:
.Bd -literal -offset indent
clog_init(1);
clog_set_flags(CLOG_F_ENABLE | CLOG_F_STDERR);
exude_enable();
p = e_malloc(len + 1);
e_check_memory();
.Ed
.Sh SEE ALSO
.Xr asprintf 3
.Xr calloc 3
.Xr clog_init 3
.Xr clog_set_flags 3
.Xr free 3
.Xr malloc 3
.Xr realloc 3
.Xr strdup 3
.Xr vasprintf 3
.Sh HISTORY
.An -nosplit
.Nm
was written by
.An Marco Peereboom Aq [email protected]