-
-
Notifications
You must be signed in to change notification settings - Fork 44
/
INSTALL.txt
281 lines (203 loc) · 15.9 KB
/
INSTALL.txt
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
-------------------------------------------------------------------------------
2.1 How to Install the Library
==============================
To configure, compile, and install the library, follow these steps carefully.
1. Download the latest version of the library available from `https://dmalloc.com/'.
2. The release files have a `.tgz' file extension which means that they are a tar'd gzip'd
directory of files. You will need to ungzip and then untar the release file into your source
work directory. You may have to rename the file to `.tar.gz' to get some old zip programs to
handle the file correctly.
3. You may want to edit or at least review the settings in `settings.dist' to tune specific
features of the library. The `configure' script will copy this file to `settings.h' which is
where you should be adding per-architecture settings.
4. Type `sh ./configure' to configure the library. You may want to first examine `sh ./configure
--help' output for some information about configure. You may want to use the `--disable-cxx'
option if you do not want the Makefile to build the C++ version of dmalloc. You may want to
use the `--enable-threads' option to build the threaded version of dmalloc. You may want to
use the `--enable-shlib' option to build the shared versions of the dmalloc libraries. `sh
./configure --help' lists the available options to configure. Configure should generate the
`Makefile' and configuration files automatically.
5. You may want to examine the `Makefile' and `conf.h' files created by configure to make sure it
did its job correctly.
6. You might want to tune the settings in `settings.h' file to tune the library to the local
architecture. This file contains relevant settings if you are using pthreads or another
thread library. *Note Using With Threads::. The `configure' script created this file from
the `settings.dist' file. Any permanent changes to these settings should made to the
`settings.dist' file. You then can run `config.status' to re-create the `settings.h' file.
7. The `DMALLOC_SIZE' variable gets auto-configured in `dmalloc.h.2' but it may not generate
correct settings for all systems. You may have to alter the definitions in this file to get
things to stop complaining when you go to compile about the size arguments to malloc routines.
Comments on this please.
8. Typing `make' should be enough to build `libdmalloc.a', and `dmalloc' program. If you figure
your problem out, please send me some notes so future users can profit from your experiences.
_NOTE_: You may experience some errors compiling some of the `return.h' assembly macros which
attempt to determine the callers address for logging purposes. *Note Portability::. You may
want to first try disabling any compiler optimization flags. If this doesn't work then you
may need to disable the `USE_RETURN_MACROS' variable in the `settings.h' file.
_NOTE_: The code is dependent on an ANSI-C compiler. If the configure script gives the
`WARNING' that you do not have an ANSI-C compiler, you may still be able to add some sort of
option to your compiler to make it ANSI. If there such is an option, please send it to the
author so it can be added to the configure script.
9. If you use threads and did not add the `--enable-threads' argument to configure, typing `make
threads' should be enough to build `libdmallocth.a' which is the threaded version of the
library. This may or may not work depending on the configuration scripts ability to detect
your local thread functionality. Feel free to send me mail with improvements.
See the section of the manual on threads for more information about the operation of the
library with your threaded program. *Note Using With Threads::.
10. If you have a C++ compiler installed, the library should have automatically built
`libdmallocxx.a' which is the C++ version of the library. If it was not done automatically,
you can build it by typing `make cxx'. You should link this library into your C++ programs
instead of `libdmalloc.a'. See the `dmallocc.cc' C++ file which contains basic code to
overload the `new', `new[]', `delete', and `delete[]' C++ operators. My apologies on the
minimal C++ support. I am still living in a mostly C world. Any help improving this interface
without sacrificing portability would be appreciated.
11. Typing `make light' should build and run the `dmalloc_t' test program through a set of light
trials. By default this will execute `dmalloc_t' 5 times - each time will execute 10,000
malloc operations in a very random manner. Anal folks can type `make heavy' to up the ante.
Use `dmalloc_t --usage' for the list of all `dmalloc_t' options.
12. Typing `make install' should install the `libdmalloc.a' library in `/usr/local/lib', the
`dmalloc.h' include file in `/usr/local/include', and the `dmalloc' utility in
`/usr/local/bin'. You may also want to type `make installth' to install the thread library
into place and/or `make installcc' to install the C++ library into place.
You may have specified a `--prefix=PATH' option to configure in which case `/usr/local' will
have been replaced with `PATH'.
See the "Getting Started" section to get up and running with the library. *Note Getting
Started::.
-------------------------------------------------------------------------------
2.2 Getting Started with the Library
====================================
This section should give you a quick idea on how to get going. Basically, you need to do the
following things to make use of the library:
1. Download the latest version of the library from `https://dmalloc.com/'.
2. Run `./configure' to configure the library. Follow the installation instructions on how to
configure, make, and install the library (i.e. type: `make install'). *Note Installation::.
3. Run `./make install' to install the library on your system.
4. You need to make sure that the library configuration and build process above was able to
locate one of the `on_exit' function, `atexit' function, or had compiler destructor support.
If one of these functions or support is available then the dmalloc library should be able to
automatically shut itself down when the program exits. This causes the memory statistics and
unfreed information to be dumped to the log file. However, if your system has none of the
above, then you will need to call `dmalloc_shutdown' yourself before your program exits.
5. To get the dmalloc utility to work you need to add an alias for dmalloc to your shell's
runtime configuration file if supported. The idea is to have the shell capture the dmalloc
program's output and adjust the environment.
After you add the alias to the shell config file you need to log out and log back in to have
it take effect, or you can execute the appropriate command below on the command line directly.
After you setup the alias, if you enter `dmalloc runtime' and see any output with
DMALLOC_OPTIONS in it then the alias did not take effect.
Bash, ksh, and zsh (`https://zsh.org/') users should add the following to their `.bashrc',
`.profile', or `.zshrc' file respectively (notice the `-b' option for bourne shell output):
function dmalloc { eval `command dmalloc -b $*`; }
If your shell does not support the `command' function then try:
function dmalloc { eval `\dmalloc -b $*`; }
or use a full path to where the dmalloc binary is installed:
function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }
If you are still using csh or tcsh, you should add the following to your `.cshrc' file (notice
the `-C' option for c-shell output):
alias dmalloc 'eval `\dmalloc -C \!*`'
If you are using rc shell, you should add the following to your `.rcrc' file (notice the `-R'
option for rc-shell output):
fn dmalloc {eval `{/usr/local/bin/dmalloc $*}}
6. Although not necessary, you may want to include `dmalloc.h' in your C files and recompile.
This will allow the library to report the file/line numbers of calls that generate problems.
*Note Allocation Macros::. It should be inserted at the _bottom_ of your include files as to
not conflict with other includes. You may want to ifdef it as well and compile with `cc
-DDMALLOC ...':
/* other includes above ^^^ */
#ifdef DMALLOC
#include "dmalloc.h"
#endif
7. Another optional task is to compile all of your source with the `dmalloc.h' with the
`DMALLOC_FUNC_CHECK' compilation flag. This will allow the library to check all of the
arguments of a number of common string and utility routines. *Note Argument Checking::.
cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c
8. Link the dmalloc library into your program. The dmalloc library should probably be placed at
or near the end of the library list.
9. Enable the debugging features by typing `dmalloc -l logfile -i 100 low' (for example). You
should not see any messages printed by the dmalloc utility (see NOTE below). This will:
* Set the malloc logfile name to `logfile' (`-l logfile'). For programs which change
directories, you may want to specify the full path to your logfile.
* Have the library check itself every 100 iterations (`-i 100'). This controls how fast
your program will run. Larger numbers check the heap less and so it will run faster.
Lower numbers will be more likely to catch memory problems.
* Enable a number of debug features (`low'). You can also try `runtime' for minimal
checking or `medium' or `high' for more extensive heap verification.
* By default, the low, medium, and high values enable the `error-abort' token which will
cause the library to abort and usually dump core immediately upon seeing an error. *Note
Dumping Core::. You can disable this feature by entering `dmalloc -m error-abort' (-m
for minus) to remove the `error-abort' token and your program will just log errors and
continue.
`dmalloc --usage' will provide verbose usage info for the dmalloc program. *Note Dmalloc
Program::.
You may also want to install the `dmallocrc' file in your home directory as `.dmallocrc'.
This allows you to add your own combination of debug tokens. *Note RC File::.
_NOTE_: The output from the dmalloc utility should be captured by your shell. If you see a
bunch of stuff which includes the string `DMALLOC_OPTIONS' then the alias you should have
created above is not working and he environmental variables are not being set. Make sure
you've logged out and back in to have the alias take effect.
10. Run your program, examine the logfile that should have been created by `dmalloc_shutdown', and
use its information to help debug your program.
-------------------------------------------------------------------------------
6 Some Solutions to Common Problems
***********************************
This section provides some answers to some common problems and questions. Please send me mail with
any additions to this list - either problems you are still having or tips that you would like to
pass on.
When diagnosing a problem, if possible, always make sure you are running the most up to date
version of Dmalloc available from the home page at URL `https://dmalloc.com/'. Problems are often
fixed and a new release can be published before people encounter them.
`Why does my program run so slow?'
This library has never been (and maybe never will be) optimized for space nor speed. Some of
its features make it unable to use some of the organizational methods of other more efficient
heap libraries.
If you have the `check-heap' token enabled, your program might run slow or seem to hang. This
is because by default, the library will run a full check of the heap with every memory
allocation or free. You can have the library check itself less frequently by using the `-i'
option to the dmalloc utility. *Note Dmalloc Program::. If you are using the `high' token
and you need your program to run faster, try the `medium' or `low' tokens which don't check as
many heap features and so run faster although they will not catch as many problems. *Note RC
File::.
`Why was a log-file not produced after I ran my program?'
This could be caused by a number of different problems.
1. Are you sure you followed all of the items in the "Getting Started" section? Please
review them if there is any doubt. *Note Getting Started::.
2. Use the `env' or `printenv' commands to make sure that the `DMALLOC_OPTIONS' variable is
set in your exported environment. *Note Environment Variable::.
3. Make sure that your program has been compiled correctly with the dmalloc library. The
`ident' program should show chunk.c and other dmalloc files compiled into your program.
You can also do `strings -a your-program | grep chunk.c' and look for something like
`$Id: chunk.c,v 1.152 1999/08/25 12:37:01 gray Exp $' with different versions and date
information. If this doesn't show up then chances are dmalloc was not linked into your
program.
4. If your program changes its working directory, it may write the dmalloc log-file
somewhere else in the filesystem. You will need to check both where the program was
started and to where it might change directory.
5. The logfile is only produced when `dmalloc_shutdown()' is called. By default it will be
called when `exit()' gets called. If you are running your program and press `Control-C'
under Unix the program will stop immediately and `dmalloc_shutdown()' will not get
called. You can either setup a signal handler for `SIGINTR' and call exit yourself, or
you can enable the `catch-signals' token. *Note Debug Tokens::.
6. If your program is segfaulting or otherwise crashing when it exits, the `exit()' routine
may not being called. You will have to resolve these issues so the dmalloc library can
gracefully exit and write its log file.
7. You may want to call `dmalloc_log_stats()' and `dmalloc_log_unfreed()' (or
`dmalloc_log_changed()') directly to have the library write its log file. Some system
modules may not have shutdown if you call this before `exit()' so extra unfreed memory
may be reported.
`I don't see any information about my non-freed (leaked) memory?'
The library will not (by default) report on "unknown" non-freed memory. Unknown means memory
that does not have associated file and line information.
This will be necessary if you are _not_ including `dmalloc.h' in all of your C files or if you
are interested in tracking leaks in system functions.
`Dmalloc is returning the error "malloc library has gone recursive"'
This most likely indicates that you are using the Dmalloc library within a threaded
application and two threads are trying to use the dmalloc library at once. Please see the
section of the manual about threads for more information about properly configuring the
library. *Note Using With Threads::.
If you are not using threads, then your program could have caught a signal while within
Dmalloc, which then in turn called a memory allocation routine. It is unwise to allocate
memory on the heap in most signal handlers. Lastly, some functions called by the library may
call memory routines that it does not anticipate. If you think this the case, please report
the problem and include a stack trace, operating system version/type, and the version of
Dmalloc you are using.
-------------------------------------------------------------------------------