| 1 |
------------------------------------------------------------------------------- |
| 2 |
|
| 3 |
2.1 How to Install the Library |
| 4 |
============================== |
| 5 |
|
| 6 |
To configure, compile, and install the library, follow these steps |
| 7 |
carefully. |
| 8 |
|
| 9 |
1. Make sure you have downloaded the latest version of the library |
| 10 |
available from the home page at URL `http://dmalloc.com/'. |
| 11 |
|
| 12 |
2. The release files have a `.tgz' file extension which means that |
| 13 |
they are a tar'd gzip'd directory of files. You will need to |
| 14 |
ungzip and then untar the release file into your source work |
| 15 |
directory. You may have to rename the file to `.tar.gz' to get |
| 16 |
some old zip programs to handle the file correctly. |
| 17 |
|
| 18 |
3. You may want to edit or at least review the settings in |
| 19 |
`settings.dist' to tune specific features of the library. The |
| 20 |
`configure' script will copy this file to `settings.h' which is |
| 21 |
where you should be adding per-architecture settings. |
| 22 |
|
| 23 |
4. Type `sh ./configure' to configure the library. You may want to |
| 24 |
first examine the `config.help' file for some information about |
| 25 |
configure. You may want to use the `--disable-cxx' option if you |
| 26 |
do not want the Makefile to build the C++ version of dmalloc. You |
| 27 |
may want to use the `--enable-threads' option to build the |
| 28 |
threaded version of dmalloc. You may want to use the |
| 29 |
`--enable-shlib' option to build the shared versions of the |
| 30 |
dmalloc libraries. `sh ./configure --help' lists the available |
| 31 |
options to configure. Configure should generate the `Makefile' |
| 32 |
and configuration files automatically. |
| 33 |
|
| 34 |
5. You may want to examine the `Makefile' and `conf.h' files created |
| 35 |
by configure to make sure it did its job correctly. |
| 36 |
|
| 37 |
6. You might want to tune the settings in `settings.h' file to tune |
| 38 |
the library to the local architecture. This file contains relevant |
| 39 |
settings if you are using pthreads or another thread library. |
| 40 |
*Note Using With Threads::. The `configure' script created this |
| 41 |
file from the `settings.dist' file. Any permanent changes to these |
| 42 |
settings should made to the `settings.dist' file. You then can run |
| 43 |
`config.status' to re-create the `settings.h' file. |
| 44 |
|
| 45 |
7. The `DMALLOC_SIZE' variable gets auto-configured in `dmalloc.h.2' |
| 46 |
but it may not generate correct settings for all systems. You may |
| 47 |
have to alter the definitions in this file to get things to stop |
| 48 |
complaining when you go to compile about the size arguments to |
| 49 |
malloc routines. Comments on this please. |
| 50 |
|
| 51 |
8. Typing `make' should be enough to build `libdmalloc.a', and |
| 52 |
`dmalloc' program. If it does not work, please see if there are |
| 53 |
any notes in the contrib directory about your system-type. If not |
| 54 |
and you figure your problem out, please send me some notes so |
| 55 |
future users can profit from your experiences. |
| 56 |
|
| 57 |
_NOTE_: You may experience some errors compiling some of the |
| 58 |
`return.h' assembly macros which attempt to determine the callers |
| 59 |
address for logging purposes. *Note Portability::. You may want |
| 60 |
to first try disabling any compiler optimization flags. If this |
| 61 |
doesn't work then you may need to disable the `USE_RETURN_MACROS' |
| 62 |
variable in the `settings.h' file. |
| 63 |
|
| 64 |
_NOTE_: The code is dependent on an ANSI-C compiler. If the |
| 65 |
configure script gives the `WARNING' that you do not have an ANSI-C |
| 66 |
compiler, you may still be able to add some sort of option to your |
| 67 |
compiler to make it ANSI. If there such is an option, please send |
| 68 |
it to the author so it can be added to the configure script. |
| 69 |
|
| 70 |
9. If you use threads and did not add the `--enable-threads' argument |
| 71 |
to configure, typing `make threads' should be enough to build |
| 72 |
`libdmallocth.a' which is the threaded version of the library. |
| 73 |
This may or may not work depending on the configuration scripts |
| 74 |
ability to detect your local thread functionality. Feel free to |
| 75 |
send me mail with improvements. |
| 76 |
|
| 77 |
See the section of the manual on threads for more information about |
| 78 |
the operation of the library with your threaded program. *Note |
| 79 |
Using With Threads::. |
| 80 |
|
| 81 |
10. If you have a C++ compiler installed, the library should have |
| 82 |
automatically built `libdmallocxx.a' which is the C++ version of |
| 83 |
the library. If it was not done automatically, you can build it by |
| 84 |
typing `make cxx'. You should link this library into your C++ |
| 85 |
programs instead of `libdmalloc.a'. See the `dmallocc.cc' C++ |
| 86 |
file which contains basic code to overload the `new', `new[]', |
| 87 |
`delete', and `delete[]' C++ operators. My apologies on the |
| 88 |
minimal C++ support. I am still living in a mostly C world. Any |
| 89 |
help improving this interface without sacrificing portability |
| 90 |
would be appreciated. |
| 91 |
|
| 92 |
11. Typing `make light' should build and run the `dmalloc_t' test |
| 93 |
program through a set of light trials. By default this will |
| 94 |
execute `dmalloc_t' 5 times - each time will execute 10,000 malloc |
| 95 |
operations in a very random manner. Anal folks can type `make |
| 96 |
heavy' to up the ante. Use `dmalloc_t --usage' for the list of all |
| 97 |
`dmalloc_t' options. |
| 98 |
|
| 99 |
12. Typing `make install' should install the `libdmalloc.a' library in |
| 100 |
`/usr/local/lib', the `dmalloc.h' include file in |
| 101 |
`/usr/local/include', and the `dmalloc' utility in |
| 102 |
`/usr/local/bin'. You may also want to type `make installth' to |
| 103 |
install the thread library into place and/or `make installcc' to |
| 104 |
install the C++ library into place. |
| 105 |
|
| 106 |
You may have specified a `--prefix=PATH' option to configure in |
| 107 |
which case `/usr/local' will have been replaced with `PATH'. |
| 108 |
|
| 109 |
|
| 110 |
See the "Getting Started" section to get up and running with the |
| 111 |
library. *Note Getting Started::. |
| 112 |
|
| 113 |
|
| 114 |
------------------------------------------------------------------------------- |
| 115 |
|
| 116 |
2.2 Getting Started with the Library |
| 117 |
==================================== |
| 118 |
|
| 119 |
This section should give you a quick idea on how to get going. |
| 120 |
Basically, you need to do the following things to make use of the |
| 121 |
library: |
| 122 |
|
| 123 |
1. Make sure you have downloaded the latest version of the library |
| 124 |
available from the home page at URL `http://dmalloc.com/'. |
| 125 |
|
| 126 |
2. Follow the installation instructions on how to configure, make, |
| 127 |
and install the library (i.e. type: `make install'). *Note |
| 128 |
Installation::. |
| 129 |
|
| 130 |
3. You need to make sure that the library configuration and build |
| 131 |
process above was able to locate one of the `on_exit' function, |
| 132 |
`atexit' function, or had compiler destructor support. If one of |
| 133 |
these functions or support is available then the dmalloc library |
| 134 |
should be able to automatically shut itself down when the program |
| 135 |
exits. This causes the memory statistics and unfreed information |
| 136 |
to be dumped to the log file. However, if your system has none of |
| 137 |
the above, then you will need to call `dmalloc_shutdown' yourself |
| 138 |
before your program exits. |
| 139 |
|
| 140 |
4. To get the dmalloc utility to work you need to add an alias for |
| 141 |
dmalloc to your shell's runtime configuration file if supported. |
| 142 |
The idea is to have the shell capture the dmalloc program's output |
| 143 |
and adjust the environment. |
| 144 |
|
| 145 |
After you add the alias to the shell config file you need to log |
| 146 |
out and log back in to have it take effect, or you can execute the |
| 147 |
appropriate command below on the command line directly. After you |
| 148 |
setup the alias, if you enter `dmalloc runtime' and see any output |
| 149 |
with DMALLOC_OPTIONS in it then the alias did not take effect. |
| 150 |
|
| 151 |
Bash, ksh, and zsh (`http://www.zsh.org/') users should add the |
| 152 |
following to their `.bashrc', `.profile', or `.zshrc' file |
| 153 |
respectively (notice the `-b' option for bourne shell output): |
| 154 |
|
| 155 |
function dmalloc { eval `command dmalloc -b $*`; } |
| 156 |
|
| 157 |
If your shell does not support the `command' function then try: |
| 158 |
|
| 159 |
function dmalloc { eval `\dmalloc -b $*`; } |
| 160 |
or |
| 161 |
function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; } |
| 162 |
|
| 163 |
If you are still using csh or tcsh, you should add the following to |
| 164 |
your `.cshrc' file (notice the `-C' option for c-shell output): |
| 165 |
|
| 166 |
alias dmalloc 'eval `\dmalloc -C \!*`' |
| 167 |
|
| 168 |
If you are using rc shell, you should add the following to your |
| 169 |
`.rcrc' file (notice the `-R' option for rc-shell output): |
| 170 |
|
| 171 |
fn dmalloc {eval `{/usr/local/bin/dmalloc $*}} |
| 172 |
|
| 173 |
5. Although not necessary, you may want to include `dmalloc.h' in |
| 174 |
your C files and recompile. This will allow the library to report |
| 175 |
the file/line numbers of calls that generate problems. *Note |
| 176 |
Allocation Macros::. It should be inserted at the _bottom_ of |
| 177 |
your include files as to not conflict with wother includes. You |
| 178 |
may want to ifdef it as well and compile with `cc -DDMALLOC ...': |
| 179 |
|
| 180 |
/* other includes above ^^^ */ |
| 181 |
|
| 182 |
#ifdef DMALLOC |
| 183 |
#include "dmalloc.h" |
| 184 |
#endif |
| 185 |
|
| 186 |
6. Another optional task is to compile all of your source with the |
| 187 |
`dmalloc.h' with the `DMALLOC_FUNC_CHECK' compilation flag. This |
| 188 |
willallow the library to check all of the arguments of a number of |
| 189 |
common string and utility routines. *Note Argument Checking::. |
| 190 |
|
| 191 |
cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c |
| 192 |
|
| 193 |
7. Link the dmalloc library into your program. The dmalloc library |
| 194 |
should probably be placed at or near the end of the library list. |
| 195 |
|
| 196 |
8. Enable the debugging features by typing `dmalloc -l logfile -i 100 |
| 197 |
low' (for example). You should not see any messages printed by |
| 198 |
the dmalloc utility (see NOTE below). This will: |
| 199 |
|
| 200 |
* Set the malloc logfile name to `logfile' (`-l logfile'). For |
| 201 |
programs which change directories, you may want to specify the |
| 202 |
full path to your logfile. |
| 203 |
|
| 204 |
* Have the library check itself every 100 iterations (`-i 100'). |
| 205 |
This controls how fast your program will run. Larger numbers |
| 206 |
check the heap less and so it will run faster. Lower numbers |
| 207 |
will be more likely to catch memory problems. |
| 208 |
|
| 209 |
* Enable a number of debug features (`low'). You can also try |
| 210 |
`runtime' for minimal checking or `medium' or `high' for more |
| 211 |
extensive heap verification. |
| 212 |
|
| 213 |
* By default, the low, medium, and high values enable the |
| 214 |
`error-abort' token which will cause the library to abort and |
| 215 |
usually dump core immediately upon seeing an error. *Note |
| 216 |
Dumping Core::. You can disable this feature by entering |
| 217 |
`dmalloc -m error-abort' (-m for minus) to remove the |
| 218 |
`error-abort' token and your program will just log errors and |
| 219 |
continue. |
| 220 |
|
| 221 |
|
| 222 |
`dmalloc --usage' will provide verbose usage info for the dmalloc |
| 223 |
program. *Note Dmalloc Program::. |
| 224 |
|
| 225 |
You may also want to install the `dmallocrc' file in your home |
| 226 |
directory as `.dmallocrc'. This allows you to add your own |
| 227 |
combination of debug tokens. *Note RC File::. |
| 228 |
|
| 229 |
_NOTE_: The output from the dmalloc utility should be captured by |
| 230 |
your shell. If you see a bunch of stuff which includes the string |
| 231 |
`DMALLOC_OPTIONS' then the alias you should have created above is |
| 232 |
not working and he environmental variables are not being set. Make |
| 233 |
sure you've logged out and back in to have the alias take effect. |
| 234 |
|
| 235 |
9. Run your program, examine the logfile that should have been |
| 236 |
created by `dmalloc_shutdown', and use its information to help |
| 237 |
debug your program. |
| 238 |
|
| 239 |
|
| 240 |
|
| 241 |
File: dmalloc.info, Node: Allocation Basics, Next: Features, Prev: Getting Started, Up: Overview |
| 242 |
|
| 243 |
2.3 Basic Description of Terms and Functions |
| 244 |
============================================ |
| 245 |
|
| 246 |
* Menu: |
| 247 |
|
| 248 |
* Basic Definitions:: General memory terms and concepts. |
| 249 |
* Malloc Functions:: Functionality supported by all malloc libs. |
| 250 |
|
| 251 |
|
| 252 |
File: dmalloc.info, Node: Basic Definitions, Next: Malloc Functions, Prev: Allocation Basics, Up: Allocation Basics |
| 253 |
|
| 254 |
2.3.1 General Memory Terms and Concepts |
| 255 |
--------------------------------------- |
| 256 |
|
| 257 |
Any program can be divided into 2 logical parts: text and data. Text is |
| 258 |
the actual program code in machine-readable format and data is the |
| 259 |
information that the text operates on when it is executing. The data, |
| 260 |
in turn, can be divided into 3 logical parts according to where it is |
| 261 |
stored: "static", "stack", and "heap". |
| 262 |
|
| 263 |
Static data is the information whose storage space is compiled into |
| 264 |
the program. |
| 265 |
|
| 266 |
/* global variables are allocated as static data */ |
| 267 |
int numbers[10]; |
| 268 |
|
| 269 |
main() |
| 270 |
{ |
| 271 |
... |
| 272 |
} |
| 273 |
|
| 274 |
Stack data is data allocated at runtime to hold information used |
| 275 |
inside of functions. This data is managed by the system in the space |
| 276 |
called stack space. |
| 277 |
|
| 278 |
void foo() |
| 279 |
{ |
| 280 |
/* this local variable is stored on the stack */ |
| 281 |
float total; |
| 282 |
... |
| 283 |
} |
| 284 |
|
| 285 |
main() |
| 286 |
{ |
| 287 |
foo(); |
| 288 |
} |
| 289 |
|
| 290 |
Heap data is also allocated at runtime and provides a programmer with |
| 291 |
dynamic memory capabilities. |
| 292 |
|
| 293 |
main() |
| 294 |
{ |
| 295 |
/* the address is stored on the stack */ |
| 296 |
char * string; |
| 297 |
... |
| 298 |
|
| 299 |
/* |
| 300 |
* Allocate a string of 10 bytes on the heap. Store the |
| 301 |
* address in string which is on the stack. |
| 302 |
*/ |
| 303 |
string = (char *)malloc(10); |
| 304 |
... |
| 305 |
|
| 306 |
/* de-allocate the heap memory now that we're done with it */ |
| 307 |
(void)free(string); |
| 308 |
... |
| 309 |
} |
| 310 |
|
| 311 |
It is the heap data that is managed by this library. |
| 312 |
|
| 313 |
Although the above is an example of how to use the malloc and free |
| 314 |
commands, it is not a good example of why using the heap for runtime |
| 315 |
storage is useful. |
| 316 |
|
| 317 |
Consider this: You write a program that reads a file into memory, |
| 318 |
processes it, and displays results. You would like to handle files with |
| 319 |
arbitrary size (from 10 bytes to 1.2 megabytes and more). One problem, |
| 320 |
however, is that the entire file must be in memory at one time to do the |
| 321 |
calculations. You don't want to have to allocate 1.2 megabytes when you |
| 322 |
might only be reading in a 10 byte file because it is wasteful of system |
| 323 |
resources. Also, you are worried that your program might have to handle |
| 324 |
files of more than 1.2 megabytes. |
| 325 |
|
| 326 |
A solution: first check out the file's size and then, using the |
| 327 |
heap-allocation routines, get enough storage to read the entire file |
| 328 |
into memory. The program will only be using the system resources |
| 329 |
necessary for the job and you will be guaranteed that your program can |
| 330 |
handle any sized file. |
| 331 |
|
| 332 |
|
| 333 |
File: dmalloc.info, Node: Malloc Functions, Prev: Basic Definitions, Up: Allocation Basics |
| 334 |
|
| 335 |
2.3.2 Functionality Supported by All Malloc Libraries |
| 336 |
----------------------------------------------------- |
| 337 |
|
| 338 |
All malloc libraries support 4 basic memory allocation commands. These |
| 339 |
include "malloc", "calloc", "realloc", and "free". For more |
| 340 |
information about their capabilities, check your system's manual pages |
| 341 |
- in unix, do a `man 3 malloc'. |
| 342 |
|
| 343 |
-- Function: void *malloc ( unsigned int SIZE ) |
| 344 |
Usage: `pnt = (type *)malloc(size)' |
| 345 |
|
| 346 |
The malloc routine is the basic memory allocation routine. It |
| 347 |
allocates an area of `size' bytes. It will return a pointer to |
| 348 |
the space requested. |
| 349 |
|
| 350 |
|
| 351 |
-- Function: void *calloc ( unsigned int NUMBER, unsigned intSIZE ) |
| 352 |
Usage: `pnt = (type *)calloc(number, size)' |
| 353 |
|
| 354 |
The calloc routine allocates a certain `number' of items, each of |
| 355 |
`size' bytes, and returns a pointer to the space. It is |
| 356 |
appropriate to pass in a `sizeof(type)' value as the size argument. |
| 357 |
|
| 358 |
Also, calloc nulls the space that it returns, assuring that the |
| 359 |
memory is all zeros. |
| 360 |
|
| 361 |
|
| 362 |
-- Function: void *realloc ( void *OLD_PNT, unsigned int NEW_SIZE ) |
| 363 |
Usage: `new_pnt = (type *)realloc(old_pnt, new_size)' |
| 364 |
|
| 365 |
The realloc function expands or shrinks the memory allocation in |
| 366 |
`old_pnt' to `new_size' number of bytes. Realloc copies as much |
| 367 |
of the information from `old_pnt' as it can into the `new_pnt' |
| 368 |
space it returns, up to `new_size' bytes. If there is a problem |
| 369 |
allocating this memory, 0L will be returned. |
| 370 |
|
| 371 |
If the `old_pnt' is 0L then realloc will do the equivalent of a |
| 372 |
`malloc(new_size)'. If `new_size' is 0 and `old_pnt' is not 0L, |
| 373 |
then it will do the equivalent of `free(old_pnt)' and will return |
| 374 |
0L. |
| 375 |
|
| 376 |
|
| 377 |
-- Function: void free ( void *PNT ) |
| 378 |
Usage: `free(pnt)' |
| 379 |
|
| 380 |
The free routine releases allocation in `pnt' which was returned by |
| 381 |
malloc, calloc, or realloc back to the heap. This allows other |
| 382 |
parts of the program to re-use memory that is not needed anymore. |
| 383 |
It guarantees that the process does not grow too big and swallow a |
| 384 |
large portion of the system resources. |
| 385 |
|
| 386 |
|
| 387 |
_WARNING_: there is a quite common myth that all of the space that |
| 388 |
is returned by malloc libraries has already been cleared. _Only_ the |
| 389 |
`calloc' routine will zero the memory space it returns. |
| 390 |
|
| 391 |
|
| 392 |
File: dmalloc.info, Node: Features, Next: How It Works, Prev: Allocation Basics, Up: Overview |
| 393 |
|
| 394 |
2.4 General Features of the Library |
| 395 |
=================================== |
| 396 |
|
| 397 |
The debugging features that are available in this debug malloc library |
| 398 |
can be divided into a couple basic classifications: |
| 399 |
|
| 400 |
file and line number information |
| 401 |
One of the nice things about a good debugger is its ability to |
| 402 |
provide the file and line number of an offending piece of code. |
| 403 |
This library attempts to give this functionality with the help of |
| 404 |
"cpp", the C preprocessor. *Note Allocation Macros::. |
| 405 |
|
| 406 |
return-address information |
| 407 |
To debug calls to the library from external sources (i.e. those |
| 408 |
files that could not use the allocation macros), some facilities |
| 409 |
have been provided to supply the caller's address. This address, |
| 410 |
with the help of a debugger, can help you locate the source of a |
| 411 |
problem. *Note Return Address::. |
| 412 |
|
| 413 |
fence-post (i.e. bounds) checking |
| 414 |
"Fence-post" memory is the area immediately above or below memory |
| 415 |
allocations. It is all too easy to write code that accesses above |
| 416 |
or below an allocation - especially when dealing with arrays or |
| 417 |
strings. The library can write special values in the areas around |
| 418 |
every allocation so it will notice when these areas have been |
| 419 |
overwritten. *Note Fence-Post Overruns::. |
| 420 |
|
| 421 |
_NOTE_: The library cannot notice when the program _reads_ from |
| 422 |
these areas, only when it writes values. Also, fence-post checking |
| 423 |
will increase the amount of memory the program allocates. |
| 424 |
|
| 425 |
heap-constancy verification |
| 426 |
The administration of the library is reasonably complex. If any |
| 427 |
of the heap-maintenance information is corrupted, the program will |
| 428 |
either crash or give unpredictable results. |
| 429 |
|
| 430 |
By enabling heap-consistency checking, the library will run |
| 431 |
through its administrative structures to make sure all is in |
| 432 |
order. This will mean that problems will be caught faster and |
| 433 |
diagnosed better. |
| 434 |
|
| 435 |
The drawback of this is, of course, that the library often takes |
| 436 |
quite a long time to do this. It is suitable to enable this only |
| 437 |
during development and debugging sessions. |
| 438 |
|
| 439 |
_NOTE_: the heap checking routines cannot guarantee that the tests |
| 440 |
will not cause a segmentation-fault if the heap administration |
| 441 |
structures are properly (or improperly if you will) overwritten. |
| 442 |
In other words, the tests will verify that everything is okay but |
| 443 |
may not inform the user of problems in a graceful manner. |
| 444 |
|
| 445 |
logging statistics |
| 446 |
One of the reasons why the debug malloc library was initially |
| 447 |
developed was to track programs' memory usage - specifically to |
| 448 |
locate "memory leaks" which are places where allocated memory is |
| 449 |
never getting freed. *Note Memory Leaks::. |
| 450 |
|
| 451 |
The library has a number of logging capabilities that can track |
| 452 |
un-freed memory pointers as well as runtime memory usage, memory |
| 453 |
transactions, administrative actions, and final statistics. |
| 454 |
|
| 455 |
examining freed memory |
| 456 |
Another common problem happens when a program frees a memory |
| 457 |
pointer but goes on to use it again by mistake. This can lead to |
| 458 |
mysterious crashes and unexplained problems. |
| 459 |
|
| 460 |
To combat this, the library can write special values into a block |
| 461 |
of memory after it has been freed. This serves two purposes: it |
| 462 |
will make sure that the program will get garbage data if it trying |
| 463 |
to access the area again, and it will allow the library to verify |
| 464 |
the area later for signs of overwriting. |
| 465 |
|
| 466 |
If any of the above debugging features detect an error, the library |
| 467 |
will try to recover. If logging is enabled then an error will be |
| 468 |
logged with as much information as possible. |
| 469 |
|
| 470 |
The error messages that the library displays are designed to give the |
| 471 |
most information for developers. If the error message is not |
| 472 |
understood, then it is most likely just trying to indicate that a part |
| 473 |
of the heap has been corrupted. |
| 474 |
|
| 475 |
The library can be configured to quit immediately when an error is |
| 476 |
detected and to dump a core file or memory-image. This can be examined |
| 477 |
with a debugger to determine the source of the problem. The library |
| 478 |
can either stop after dumping core or continue running. *Note Dumping |
| 479 |
Core::. |
| 480 |
|
| 481 |
_NOTE_: do not be surprised if the library catches problems with |
| 482 |
your system's routines. It took me hours to finally come to the |
| 483 |
conclusion that the localtime call, included in SunOS release 4.1, |
| 484 |
overwrites one of its fence-post markers. |
| 485 |
|
| 486 |
|
| 487 |
File: dmalloc.info, Node: How It Works, Prev: Features, Up: Overview |
| 488 |
|
| 489 |
2.5 How the Library Checks Your Program |
| 490 |
======================================= |
| 491 |
|
| 492 |
This is one of the newer sections of the library implying that it is |
| 493 |
incomplete. If you have any questions or issues that you'd like to see |
| 494 |
handled here, please let me know. |
| 495 |
|
| 496 |
The dmalloc library replaces the heap library calls normally found in |
| 497 |
your system libraries with its own versions. When you make a call to |
| 498 |
malloc (for example), you are calling dmalloc's version of the memory |
| 499 |
allocation function. When you allocate memory with these functions, the |
| 500 |
dmalloc library keeps track of a number of pieces of debugging |
| 501 |
information about your pointer including: where it was allocated, |
| 502 |
exactly how much memory was requested, when the call was made, etc.. |
| 503 |
This information can then be verified when the pointer is freed or |
| 504 |
reallocated and the details can be logged on any errors. |
| 505 |
|
| 506 |
Whenever you reallocate or free a memory address, the dmalloc library |
| 507 |
always performs a number of checks on the pointer to make sure that it |
| 508 |
is valid and has not been corrupted. You can configure the library to |
| 509 |
perform additional checks such as detected fence-post writing. The |
| 510 |
library can also be configured to overwrite memory with non-zeros (only |
| 511 |
if calloc is not called) when it is allocated and erase the memory when |
| 512 |
the pointers are freed. |
| 513 |
|
| 514 |
In addition to per-pointer checks, you can configure the library to |
| 515 |
perform complete heap checks. These complete checks verify all |
| 516 |
internal heap structures and include walking all of the known allocated |
| 517 |
pointers to verify each one in turn. You need this level of checking |
| 518 |
to find random pointers in your program which got corrupted but that |
| 519 |
won't be freed for a while. To turn on these checks, you will need to |
| 520 |
enable the `check-heap' debug token. *Note Debug Tokens::. By default |
| 521 |
this will cause the heap to be fully checked each and every time |
| 522 |
dmalloc is called whether it is a malloc, free, realloc, or another |
| 523 |
dmalloc overloaded function. |
| 524 |
|
| 525 |
Performing a full heap check can take a good bit of CPU and it may be |
| 526 |
that you will want to run it sporadically. This can be accomplished in |
| 527 |
a couple different ways including the '-i' interval argument to the |
| 528 |
dmalloc utility. *Note Dmalloc Program::. This will cause the check to |
| 529 |
be run every N-th time. For instance, 'dmalloc -i 3' will cause the |
| 530 |
heap to be checked before every 3rd call to a memory function. Values |
| 531 |
of 100 or even 1000 for high memory usage programs are more useful than |
| 532 |
smaller ones. |
| 533 |
|
| 534 |
You can also cause the program to start doing detailed heap checking |
| 535 |
after a certain point. For instance, with 'dmalloc -s 1000' option, you |
| 536 |
can tell the dmalloc library to enable the heap checks after the 1000th |
| 537 |
memory call. Examine the dmalloc log file produced and use the |
| 538 |
iteration count if you have `LOG_ITERATION_COUNT' enabled in your |
| 539 |
`settings.h' file. |
| 540 |
|
| 541 |
The start option can also have the format `file:line'. For |
| 542 |
instance, if it is set to `dmalloc_t.c:126', dmalloc will start |
| 543 |
checking the heap after it sees a dmalloc call from the `dmalloc_t.c' |
| 544 |
file, line number 126. If you use `dmalloc_t.c:0', with a 0 line |
| 545 |
number, then dmalloc will start checking the heap after it sees a call |
| 546 |
from anywhere in the `dmalloc_t.c' file. |
| 547 |
|
| 548 |
|
| 549 |
File: dmalloc.info, Node: Programming, Next: Dmalloc Program, Prev: Overview, Up: Top |
| 550 |
|
| 551 |
3 How to Program with the Library |
| 552 |
********************************* |
| 553 |
|
| 554 |
* Menu: |
| 555 |
|
| 556 |
* Allocation Macros:: Macros providing file and line information. |
| 557 |
* Return Address:: Getting caller address information. |
| 558 |
* Argument Checking:: Checking of function arguments. |
| 559 |
* Dumping Core:: Generating a core file on errors for debugging. |
| 560 |
* Extensions:: Additional non-standard routines. |
| 561 |
* Error Codes:: Description of the internal error numbers. |
| 562 |
* Disabling the Library:: How to disable the library. |
| 563 |
* Using With C++:: Using the library with C++. |
| 564 |
* Using With a Debugger:: Using a debugger with the library. |
| 565 |
* Using With Threads:: Using the library with a thread package. |
| 566 |
* Using With Cygwin:: Using the library with Cygwin environment. |
| 567 |
* Debugging A Server:: Debugging memory in a server or cgi-bin process. |
| 568 |
* Logfile Details:: Explanation of the Logfile Output. |
| 569 |
* Other Hints:: Various other hints that may help. |
| 570 |
|
| 571 |
|
| 572 |
File: dmalloc.info, Node: Allocation Macros, Next: Return Address, Prev: Programming, Up: Programming |
| 573 |
|
| 574 |
3.1 Macros Providing File and Line Information |
| 575 |
============================================== |
| 576 |
|
| 577 |
By including `dmalloc.h' in your C files, your calls to malloc, calloc, |
| 578 |
realloc, recalloc, memalign, valloc, strdup, and free are replaced with |
| 579 |
calls to _dmalloc_malloc, _dmalloc_realloc, and _dmalloc_free with |
| 580 |
various flags. Additionally the library replaces calls to xmalloc, |
| 581 |
xcalloc, xrealloc, xrecalloc, xmemalign, xvalloc, xstrdup, and xfree |
| 582 |
with associated calls. |
| 583 |
|
| 584 |
These macros use the c-preprocessor `__FILE__' and `__LINE__' macros |
| 585 |
which get replaced at compilation time with the current file and |
| 586 |
line-number of the source code in question. The routines use this |
| 587 |
information to produce verbose reports on memory problems. |
| 588 |
|
| 589 |
not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92' |
| 590 |
|
| 591 |
This line from a log file shows that memory was not freed from file |
| 592 |
`dmalloc_t.c' line 92. *Note Memory Leaks::. |
| 593 |
|
| 594 |
You may notice some non standard memory allocation functions in the |
| 595 |
above list. Recalloc is a routine like realloc that reallocates |
| 596 |
previously allocated memory to a new size. If the new memory size is |
| 597 |
larger than the old, recalloc initializes the new space to all zeros. |
| 598 |
This may or may not be supported natively by your operating system. |
| 599 |
Memalign is like malloc but should insure that the returned pointer is |
| 600 |
aligned to a certain number of specified bytes. Currently, the memalign |
| 601 |
function is not supported by the library. It defaults to returning |
| 602 |
possibly non-aligned memory for alignment values less than a block-size. |
| 603 |
Valloc is like malloc but insures that the returned pointer will be |
| 604 |
aligned to a page boundary. This may or may not be supported natively |
| 605 |
by your operating system but is fully supported by the library. Strdup |
| 606 |
is a string duplicating routine which takes in a null terminated string |
| 607 |
pointer and returns an allocated copy of the string that will need to be |
| 608 |
passed to free later to deallocate. |
| 609 |
|
| 610 |
The X versions of the standard memory functions (xmalloc, xfree, |
| 611 |
etc.) will print out an error message to standard error and will stop |
| 612 |
if the library is unable to allocate any additional memory. It is |
| 613 |
useful to use these routines instead of checking everywhere in your |
| 614 |
program for allocation routines returning NULL pointers. |
| 615 |
|
| 616 |
_WARNING_: If you are including the `dmalloc.h' file in your |
| 617 |
sources, it is recommended that it be at the end of your include file |
| 618 |
list because dmalloc uses macros and may try to change declarations of |
| 619 |
the malloc functions if they come after it. |
| 620 |
|
| 621 |
|
| 622 |
File: dmalloc.info, Node: Return Address, Next: Argument Checking, Prev: Allocation Macros, Up: Programming |
| 623 |
|
| 624 |
3.2 Getting Caller Address Information |
| 625 |
====================================== |
| 626 |
|
| 627 |
Even though the allocation macros can provide file/line information for |
| 628 |
some of your code, there are still modules which either you can't |
| 629 |
include `dmalloc.h' (such as library routines) or you just don't want |
| 630 |
to. You can still get information about the routines that call dmalloc |
| 631 |
function from the return-address information. To accomplish this, you |
| 632 |
must be using this library on one of the supported |
| 633 |
architecture/compilers. *Note Portability::. |
| 634 |
|
| 635 |
The library attempts to use some assembly hacks to get the |
| 636 |
return-address or the address of the line that called the dmalloc |
| 637 |
function. If you have unfreed memory that does not have associated file |
| 638 |
and line information, you might see the following non-freed memory |
| 639 |
messages. |
| 640 |
|
| 641 |
not freed: '0x38410' (22 bytes) from 'ra=0xdd2c' |
| 642 |
not freed: '0x38600' (10232 bytes) from 'ra=0x10234d' |
| 643 |
not freed: '0x38220' (137 bytes) from 'ra=0x82cc' |
| 644 |
|
| 645 |
With the help of a debugger, these return-addresses (or ra) can then |
| 646 |
be identified. I've provided a `ra_info.pl' perl script in the |
| 647 |
`contrib/' directory with the dmalloc sources which seems to work well |
| 648 |
with gdb. You can also use manual methods for gdb to find the |
| 649 |
return-address location. *Note Translate Return Addresses::. |
| 650 |
|
| 651 |
|
| 652 |
File: dmalloc.info, Node: Argument Checking, Next: Dumping Core, Prev: Return Address, Up: Programming |
| 653 |
|
| 654 |
3.3 Checking of Function Arguments |
| 655 |
================================== |
| 656 |
|
| 657 |
One potential problem with the library and its multitude of checks and |
| 658 |
diagnoses is that they only get performed when a dmalloc function is |
| 659 |
called. One solution this is to include `dmalloc.h' and compile your |
| 660 |
source code with the `DMALLOC_FUNC_CHECK' flag defined and enable the |
| 661 |
`check-funcs' token. *Note Debug Tokens::. |
| 662 |
|
| 663 |
cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c |
| 664 |
|
| 665 |
_NOTE_: Once you have compiled your source with DMALLOC_FUNC_CHECK |
| 666 |
enabled, you will have to recompile with it off to disconnect the |
| 667 |
library. *Note Disabling the Library::. |
| 668 |
|
| 669 |
_WARNING_: You should be sure to have `dmalloc.h' included at the |
| 670 |
end of your include file list because dmalloc uses macros and may try |
| 671 |
to change declarations of the checked functions if they come after it. |
| 672 |
|
| 673 |
When this is defined dmalloc will override a number of functions and |
| 674 |
will insert a routine which knows how to check its own arguments and |
| 675 |
then call the real function. Dmalloc can check such functions as |
| 676 |
`bcopy', `index', `strcat', and `strcasecmp'. For the full list see |
| 677 |
the end of `dmalloc.h'. |
| 678 |
|
| 679 |
When you call `strlen', for instance, dmalloc will make sure the |
| 680 |
string argument's fence-post areas have not been overwritten, its file |
| 681 |
and line number locations are good, etc. With `bcopy', dmalloc will |
| 682 |
make sure that the destination string has enough space to store the |
| 683 |
number of bytes specified. |
| 684 |
|
| 685 |
For all of the arguments checked, if the pointer is not in the heap |
| 686 |
then it is ignored since dmalloc does not know anything about it. |
| 687 |
|
| 688 |
|
| 689 |
File: dmalloc.info, Node: Dumping Core, Next: Extensions, Prev: Argument Checking, Up: Programming |
| 690 |
|
| 691 |
3.4 Generating a Core File on Errors |
| 692 |
==================================== |
| 693 |
|
| 694 |
If the `error-abort' debug token has been enabled, when the library |
| 695 |
detects any problems with the heap memory, it will immediately attempt |
| 696 |
to dump a core file. *Note Debug Tokens::. Core files are a complete |
| 697 |
copy of the program and it's state and can be used by a debugger to see |
| 698 |
specifically what is going on when the error occurred. *Note Using |
| 699 |
With a Debugger::. By default, the low, medium, and high arguments to |
| 700 |
the library utility enable the `error-abort' token. You can disable |
| 701 |
this feature by entering `dmalloc -m error-abort' (-m for minus) to |
| 702 |
remove the `error-abort' token and your program will just log errors |
| 703 |
and continue. You can also use the `error-dump' token which tries to |
| 704 |
dump core when it sees an error but still continue running. *Note |
| 705 |
Debug Tokens::. |
| 706 |
|
| 707 |
When a program dumps core, the system writes the program and all of |
| 708 |
its memory to a file on disk usually named `core'. If your program is |
| 709 |
called `foo' then your system may dump core as `foo.core'. If you are |
| 710 |
not getting a `core' file, make sure that your program has not changed |
| 711 |
to a new directory meaning that it may have written the core file in a |
| 712 |
different location. Also insure that your program has write privileges |
| 713 |
over the directory that it is in otherwise it will not be able to dump |
| 714 |
a core file. Core dumps are often security problems since they contain |
| 715 |
all program memory so systems often block their being produced. You |
| 716 |
will want to check your user and system's core dump size ulimit |
| 717 |
settings. |
| 718 |
|
| 719 |
The library by default uses the `abort' function to dump core which |
| 720 |
may or may not work depending on your operating system. If the |
| 721 |
following program does not dump core then this may be the problem. See |
| 722 |
`KILL_PROCESS' definition in `settings.dist'. |
| 723 |
|
| 724 |
main() |
| 725 |
{ |
| 726 |
abort(); |
| 727 |
} |
| 728 |
|
| 729 |
If `abort' does work then you may want to try the following setting |
| 730 |
in `settings.dist'. This code tries to generate a segmentation fault |
| 731 |
by dereferencing a `NULL' pointer. |
| 732 |
|
| 733 |
#define KILL_PROCESS { int *_int_p = 0L; *_int_p = 1; } |
| 734 |
|
| 735 |
|
| 736 |
File: dmalloc.info, Node: Extensions, Next: Error Codes, Prev: Dumping Core, Up: Programming |
| 737 |
|
| 738 |
3.5 Additional Non-standard Routines |
| 739 |
==================================== |
| 740 |
|
| 741 |
The library has a number of variables that are not a standard part of |
| 742 |
most malloc libraries: |
| 743 |
|
| 744 |
-- Variable: int dmalloc_errno |
| 745 |
This variable stores the internal dmalloc library error number |
| 746 |
like errno does for the system calls. It can be passed to |
| 747 |
`dmalloc_strerror()' (see below) to get a string version of the |
| 748 |
error. It will have a value of zero if the library has not |
| 749 |
detected any problems. |
| 750 |
|
| 751 |
|
| 752 |
-- Variable: char* dmalloc_logpath |
| 753 |
This variable can be used to set the dmalloc log filename. The env |
| 754 |
variable `DMALLOC_LOGFILE' overrides this variable. |
| 755 |
|
| 756 |
|
| 757 |
Additionally the library provides a number of non-standard malloc |
| 758 |
routines: |
| 759 |
|
| 760 |
-- Function: void dmalloc_shutdown ( void ) |
| 761 |
This function shuts the library down and logs the final statistics |
| 762 |
and information especially the non-freed memory pointers. The |
| 763 |
library has code to support auto-shutdown if your system has the |
| 764 |
`on_exit()' call, `atexit()' call, or compiler destructor support |
| 765 |
(see `conf.h'). If you do not have these, then `dmalloc_shutdown' |
| 766 |
should be called right before `exit()' or as the last function in |
| 767 |
`main()'. |
| 768 |
|
| 769 |
main() |
| 770 |
{ |
| 771 |
... |
| 772 |
dmalloc_shutdown(); |
| 773 |
exit(0); |
| 774 |
} |
| 775 |
|
| 776 |
-- Function: int dmalloc_verify ( char * PNT ) |
| 777 |
This function verifies individual memory pointers that are suspect |
| 778 |
of memory problems. To check the entire heap pass in a NULL or 0 |
| 779 |
pointer. The routine returns DMALLOC_VERIFY_ERROR or |
| 780 |
DMALLOC_VERIFY_NOERROR. |
| 781 |
|
| 782 |
_NOTE_: `dmalloc_verify()' can only check the heap with the |
| 783 |
functions that have been enabled. For example, if fence-post |
| 784 |
checking is not enabled, `dmalloc_verify()' cannot check the |
| 785 |
fence-post areas in the heap. |
| 786 |
|
| 787 |
-- Function: unsigned-int dmalloc_debug ( const unsigned int FLAGS ) |
| 788 |
This routine sets the debug functionality flags and returns the |
| 789 |
previous flag value. It is helpful in server or cgi-bin programs |
| 790 |
where environmental variables cannot be used. *Note Debugging A |
| 791 |
Server::. For instance, if debugging should never be enabled for a |
| 792 |
program, a call to `dmalloc_debug(0)' as the first call in |
| 793 |
`main()' will disable all the memory debugging from that point on. |
| 794 |
|
| 795 |
_NOTE_: you cannot add or remove certain flags such as signal |
| 796 |
handlers since they are setup at initialization time only. |
| 797 |
|
| 798 |
_NOTE_: you can also use `dmalloc_debug_setup' below. |
| 799 |
|
| 800 |
|
| 801 |
-- Function: unsigned-int dmalloc_debug_current ( void ) |
| 802 |
This routine returns the current debug functionality value value. |
| 803 |
This allows you to save a copy of the debug dmalloc settings to be |
| 804 |
changed and then restored later. |
| 805 |
|
| 806 |
|
| 807 |
-- Function: void dmalloc_debug_setup ( const char * OPTIONS_STR ) |
| 808 |
This routine sets the global debugging functionality as an option |
| 809 |
string. Normally this would be passed in in the DMALLOC_OPTIONS |
| 810 |
environmental variable. This is here to override the env or for |
| 811 |
circumstances where modifying the environment is not possible or |
| 812 |
does not apply such as servers or cgi-bin programs. *Note |
| 813 |
Debugging A Server::. |
| 814 |
|
| 815 |
Some examples: |
| 816 |
|
| 817 |
/* |
| 818 |
* debug tokens high, threaded lock-on at 20, |
| 819 |
* log to dmalloc.%p (pid) |
| 820 |
*/ |
| 821 |
dmalloc_debug_setup("debug=0x4f46d03,lockon=20,log=dmalloc.%p"); |
| 822 |
|
| 823 |
/* |
| 824 |
* turn on some debug tokens directly and log to the |
| 825 |
* file 'logfile' |
| 826 |
*/ |
| 827 |
dmalloc_debug_setup( |
| 828 |
"log-stats,log-non-free,check-fence,log=logfile"); |
| 829 |
|
| 830 |
|
| 831 |
-- Function: int dmalloc_examine ( const DMALLOC_PNT PNT, DMALLOC_SIZE |
| 832 |
* USER_SIZE_P, DMALLOC_SIZE * TOTAL_SIZE_P, char ** FILE_P, |
| 833 |
int * LINE_P, DMALLOC_PNT * RET_ADDR_P, unsigned long * |
| 834 |
USER_MARK_P, unsigned long * SEEN_P ) |
| 835 |
This function returns the size of a pointer's allocation as well |
| 836 |
as the total size given including administrative overhead, file |
| 837 |
and line or the return-address from where it was allocated, the |
| 838 |
last pointer when the pointer was "used", and the number of times |
| 839 |
the pointer has been "seen". It will return DMALLOC_NOERROR or |
| 840 |
DMALLOC_ERROR depending on whether pnt is good or not. |
| 841 |
|
| 842 |
_NOTE_: This function is _certainly_ not provided by most if not |
| 843 |
all other malloc libraries. |
| 844 |
|
| 845 |
|
| 846 |
-- Function: void dmalloc_track ( const dmalloc_track_t TRACK_FUNC ) |
| 847 |
Register an allocation tracking function which will be called each |
| 848 |
time an allocation occurs. Pass in NULL to disable. To take a |
| 849 |
look at what information is provided, see the dmalloc_track_t |
| 850 |
function typedef in dmalloc.h. |
| 851 |
|
| 852 |
|
| 853 |
-- Function: unsigned-long dmalloc_mark ( void ) |
| 854 |
Return to the caller the current "mark" which can be used later to |
| 855 |
log the pointers which have changed since this mark with the |
| 856 |
`dmalloc_log_changed' function. Multiple marks can be saved and |
| 857 |
used. |
| 858 |
|
| 859 |
This is very useful when using the library with a server which does |
| 860 |
not exit. You can then save a mark before a transaction or event |
| 861 |
happens and then check to see what has changed using the |
| 862 |
`dmalloc_log_changed' function below. *Note Debugging A Server::. |
| 863 |
|
| 864 |
If you `LOG_ITERATION' enabled in your `settings.h' file then the |
| 865 |
entries in the log file will be prepended with the number of memory |
| 866 |
transactions that the library has handled so far. You can also |
| 867 |
enable `LOG_PNT_ITERATION' in `settings.h' to store the memory |
| 868 |
transaction number with each pointer. |
| 869 |
|
| 870 |
|
| 871 |
-- Function: unsigned-long dmalloc_memory_allocated ( void ) |
| 872 |
Return to the caller the total number of bytes that have been |
| 873 |
allocated by the library. This is not the current in use but the |
| 874 |
total number of bytes returned by allocation functions. |
| 875 |
|
| 876 |
|
| 877 |
-- Function: unsigned-int dmalloc_page_size ( void ) |
| 878 |
Return to the caller the memory page-size being used by the |
| 879 |
library. This should be the same value as the one returned by the |
| 880 |
`getpagesize()' function, if available. |
| 881 |
|
| 882 |
|
| 883 |
-- Function: unsigned-long dmalloc_count_changed ( const unsigned long |
| 884 |
MARK, const int NOT_FREED_B, const int FREE_B ) |
| 885 |
Count the pointers that have changed since the mark which was |
| 886 |
returned by `dmalloc_mark'. If `not_freed_b' is set to non-0 then |
| 887 |
count the pointers that have not been freed. If `free_b' is set |
| 888 |
to non-0 then count the pointers that have been freed. |
| 889 |
|
| 890 |
This can be used in conjunction with the `dmalloc_mark()' function |
| 891 |
to help servers which never exit ensure that transactions or |
| 892 |
events are not leaking memory. *Note Debugging A Server::. |
| 893 |
|
| 894 |
unsigned long mark = dmalloc_mark() ; |
| 895 |
... |
| 896 |
assert(dmalloc_count_changed(mark, 1, 0) == 0) ; |
| 897 |
|
| 898 |
|
| 899 |
-- Function: void dmalloc_log_stats ( void ) |
| 900 |
This routine outputs the current dmalloc statistics to the log |
| 901 |
file. |
| 902 |
|
| 903 |
-- Function: void dmalloc_log_unfreed ( void ) |
| 904 |
This function logs the unfreed-memory information to the log file. |
| 905 |
This is also useful to log the currently allocated points to the |
| 906 |
log file to be compared against another dump later on. |
| 907 |
|
| 908 |
|
| 909 |
-- Function: void dmalloc_log_changed ( const unsigned long MARK, |
| 910 |
const int NOT_FREED_B, const int FREED_B, const int DETAILS_B |
| 911 |
) |
| 912 |
Log the pointers that have changed since the mark which was |
| 913 |
returned by `dmalloc_mark'. If `not_freed_b' is set to non-0 then |
| 914 |
log the pointers that have not been freed. If `free_b' is set to |
| 915 |
non-0 then log the pointers that have been freed. If `details_b' |
| 916 |
set to non-0 then log the individual pointers that have changed |
| 917 |
otherwise just log the summaries. |
| 918 |
|
| 919 |
This can be used in conjunction with the `dmalloc_mark()' function |
| 920 |
to help servers which never exit find transactions or events which |
| 921 |
are leaking memory. *Note Debugging A Server::. |
| 922 |
|
| 923 |
|
| 924 |
-- Function: void dmalloc_vmessage ( const char * FORMAT, va_list ARGS |
| 925 |
) |
| 926 |
Write a message into the dmalloc logfile using vprintf-like |
| 927 |
arguments. |
| 928 |
|
| 929 |
|
| 930 |
-- Function: void dmalloc_message ( const char * FORMAT, ... ) |
| 931 |
Write a message into the dmalloc logfile using printf-like |
| 932 |
arguments. |
| 933 |
|
| 934 |
|
| 935 |
-- Function: void dmalloc_get_stats ( DMALLOC_PNT * HEAP_LOW_P, |
| 936 |
DMALLOC_PNT * HEAP_HIGH_P, unsigned long * TOTAL_SPACE_P, |
| 937 |
unsigned long * USER_SPACE_P, unsigned long * |
| 938 |
CURRENT_ALLOCATED_P, unsigned long * CURRENT_PNT_NP, unsigned |
| 939 |
long * MAX_ALLOCATED_P, unsigned long * MAX_PNT_NP, unsigned |
| 940 |
long * MAX_ONE_P) |
| 941 |
This function return a number of statistics about the current heap. |
| 942 |
The pointers `heap_low_p' and `heap_high_p' will be set to the low |
| 943 |
and high spots in the heap. `total_space_p' will be set to the |
| 944 |
total space in the heap including user space, administrative |
| 945 |
space, and overhead. `user_space_p' will be set to the space |
| 946 |
given to the user process (allocated and free space). |
| 947 |
`current_allocated_p' will be set to the current allocated space |
| 948 |
given to the user process. `current_pnt_np' will be set to the |
| 949 |
current number of pointers allocated by the user process. |
| 950 |
`max_allocated_p' will be set to the maximum allocated space given |
| 951 |
to the user process. `max_pnt_np' will be set to the maximum |
| 952 |
number of pointers allocated by the user process. `max_on_p' will |
| 953 |
be set to the maximum space allocated with one call by the user |
| 954 |
process. |
| 955 |
|
| 956 |
|
| 957 |
-- Function: const-char* dmalloc_strerror ( const int ERROR_NUMBER ) |
| 958 |
This function returns the string representation of the error value |
| 959 |
in `error_number' (which probably should be dmalloc_errno). This |
| 960 |
allows the logging of more verbose memory error messages. |
| 961 |
|
| 962 |
You can also display the string representation of an error value |
| 963 |
by a call to the `dmalloc' program with a `-e #' option. *Note |
| 964 |
Dmalloc Program::. |
| 965 |
|
| 966 |
|
| 967 |
|
| 968 |
File: dmalloc.info, Node: Error Codes, Next: Disabling the Library, Prev: Extensions, Up: Programming |
| 969 |
|
| 970 |
3.6 Description of the Internal Error Codes |
| 971 |
=========================================== |
| 972 |
|
| 973 |
The following error codes are defined in `error_val.h'. They are used |
| 974 |
by the library to indicate a detected problem. They can be caused by |
| 975 |
the user (`ERROR_TOO_BIG') or can indicate an internal library problem |
| 976 |
(`ERROR_SLOT_CORRUPT'). The `dmalloc' utility can give you the string |
| 977 |
version of the error with the `-e' argument: |
| 978 |
|
| 979 |
$ dmalloc -e 60 |
| 980 |
dmalloc: dmalloc_errno value '60' = |
| 981 |
'pointer is not on block boundary' |
| 982 |
|
| 983 |
Here are the error codes set by the library. They are non |
| 984 |
contiguous on purpose because I add and delete codes all of the time |
| 985 |
and there are sections for various error-code types. |
| 986 |
|
| 987 |
`1 (ERROR_NONE) no error' |
| 988 |
No error. It is good coding practice to set the no-error code to |
| 989 |
be non-0 value because it forces you to set it explicitly. |
| 990 |
|
| 991 |
`2 (INVALID_ERROR)' |
| 992 |
Invalid error number. If the library outputs this error then your |
| 993 |
dmalloc utility may be out of date with the library you linked |
| 994 |
against. This will be returned with all error codes not listed |
| 995 |
here. |
| 996 |
|
| 997 |
`10 (ERROR_BAD_SETUP) initialization and setup failed' |
| 998 |
Bad setup value. This is currently unused but it is intended to |
| 999 |
report on invalid setup configuration information. |
| 1000 |
|
| 1001 |
`11 (ERROR_IN_TWICE) malloc library has gone recursive' |
| 1002 |
Library went recursive. This usually indicates that you are not |
| 1003 |
using the threaded version of the library. Or if you are then you |
| 1004 |
are not using the `-o' "lock-on" option. *Note Using With |
| 1005 |
Threads::. |
| 1006 |
|
| 1007 |
`13 (ERROR_LOCK_NOT_CONFIG) thread locking has not been configured' |
| 1008 |
Thread locking has not been configured. This indicates that you |
| 1009 |
attempted to use the `-o' "lock-on" option without linking with |
| 1010 |
the thread version of the library. You should probably be using |
| 1011 |
`-ldmallocth' _not_ `-ldmalloc' when you are linking. Or you |
| 1012 |
should include `.../lib/libdmallocth.a' on your compilation line. |
| 1013 |
|
| 1014 |
`20 (ERROR_IS_NULL) pointer is null' |
| 1015 |
Pointer is null. The program passed a NULL (0L) pointer to `free' |
| 1016 |
and you have the `error-free-null' token enabled. |
| 1017 |
|
| 1018 |
`21 (ERROR_NOT_IN_HEAP) pointer is not pointing to heap data space' |
| 1019 |
Pointer is not pointing to heap data space. This means that the |
| 1020 |
program passed an out-of-bounds pointer to `free' or `realloc'. |
| 1021 |
This could be someone trying to work with a wild pointer or trying |
| 1022 |
to free a pointer from a different source than `malloc'. |
| 1023 |
|
| 1024 |
`22 (ERROR_NOT_FOUND) cannot locate pointer in heap' |
| 1025 |
Cannot locate pointer in heap. The user passed in a pointer which |
| 1026 |
the heap did not know about. Either this pointer was allocated by |
| 1027 |
some other mechanism (like `mmap' or `sbrk' directly) or it is a |
| 1028 |
random invalid pointer. |
| 1029 |
|
| 1030 |
In some rare circumstances, sometimes seen with shared libraries, |
| 1031 |
there can be two separate copies of the dmalloc library in a |
| 1032 |
program. Each one does not know about the pointers allocated by |
| 1033 |
the other. |
| 1034 |
|
| 1035 |
`23 (ERROR_IS_FOUND) found pointer the user was looking for' |
| 1036 |
This indicates that the pointer specified in the address part of |
| 1037 |
the environmental variable was discovered by the library. *Note |
| 1038 |
Environment Variable::. This error is useful so you can put a |
| 1039 |
breakpoint in a debugger to find where a particular address was |
| 1040 |
allocated. *Note Using With a Debugger::. |
| 1041 |
|
| 1042 |
`24 (ERROR_BAD_FILE) possibly bad .c filename pointer' |
| 1043 |
A possibly invalid filename was discovered in the dmalloc |
| 1044 |
administrative sections. This could indicate some corruption of |
| 1045 |
the internal tables. It also could mean that you have a source |
| 1046 |
file whose name is longer than 100 characters. See |
| 1047 |
`MAX_FILE_LENGTH' in the `settings.dist' file. |
| 1048 |
|
| 1049 |
`25 (ERROR_BAD_LINE) possibly bad .c file line-number' |
| 1050 |
A line-number was out-of-bounds in the dmalloc administrative |
| 1051 |
sections. This could indicate some corruption of the internal |
| 1052 |
tables. It also could mean that you have a source file containing |
| 1053 |
more than `30000' lines of code. See `MAX_LINE_NUMBER' in the |
| 1054 |
`settings.dist' file. |
| 1055 |
|
| 1056 |
`26 (ERROR_UNDER_FENCE) failed UNDER picket-fence magic-number check' |
| 1057 |
This indicates that a pointer had its lower bound picket-fence |
| 1058 |
magic number overwritten. If the `check-fence' token is enabled, |
| 1059 |
the library writes magic values above and below allocations to |
| 1060 |
protect against overflow. Most likely this is because a pointer |
| 1061 |
below it went past its allocate and wrote into the next pointer's |
| 1062 |
space. |
| 1063 |
|
| 1064 |
`27 (ERROR_OVER_FENCE) failed OVER picket-fence magic-number check' |
| 1065 |
This indicates that a pointer had its upper bound picket-fence |
| 1066 |
magic space overwritten. If the `check-fence' token is enabled, |
| 1067 |
the library writes magic values above and below allocations to |
| 1068 |
protect against overflow. Most likely this is because an array or |
| 1069 |
string allocation wrote past the end of the allocation. |
| 1070 |
|
| 1071 |
Check for improper usage of `strcat', `sprintf', `strcpy', and any |
| 1072 |
other functions which work with strings and do not protect |
| 1073 |
themselves by tracking the size of the string. These functions |
| 1074 |
should _always_ be replaced with: `strncat', `snprintf', |
| 1075 |
`strncpy', and others. |
| 1076 |
|
| 1077 |
`28 (ERROR_WOULD_OVERWRITE) use of pointer would exceed allocation' |
| 1078 |
This error is generated by the function pointer checking code |
| 1079 |
usually enabled with the `check-funcs' token. Dmalloc overloads a |
| 1080 |
number of string and memory copying functions and verifies that |
| 1081 |
the buffers (if allocated in the heap) would not be overwritten by |
| 1082 |
the function. |
| 1083 |
|
| 1084 |
`30 (ERROR_NOT_START_BLOCK) pointer is not to start of memory block' |
| 1085 |
This indicates that the user passed in a pointer to be freed or |
| 1086 |
reallocated that was not at the start of the allocation. You |
| 1087 |
would get this error, for example, if you allocate and get pointer |
| 1088 |
`X' but then try to free `X+1'. |
| 1089 |
|
| 1090 |
`40 (ERROR_BAD_SIZE) invalid allocation size' |
| 1091 |
This error indicates that a size value in the internal structures |
| 1092 |
of the library were corrupted. This could be a random pointer |
| 1093 |
problem, pointer overflow, or some other corruption. |
| 1094 |
|
| 1095 |
`41 (ERROR_TOO_BIG) largest maximum allocation size exceeded' |
| 1096 |
An allocation asked for memory larger than the configured maximum. |
| 1097 |
This is a user configured setting. See `LARGEST_ALLOCATION' in |
| 1098 |
the `settings.dist' file. It is used to protect against wild |
| 1099 |
allocation sizes. If you have super large allocation sizes then |
| 1100 |
you should tune the `LARGEST_ALLOCATION' value appropriately. |
| 1101 |
|
| 1102 |
`43 (ERROR_ALLOC_FAILED) could not grow heap by allocating memory' |
| 1103 |
The library could not allocate more heap space and the program has |
| 1104 |
run out of memory. This could indicate that you've overflowed |
| 1105 |
some system imposed limit. On many operation systems, the |
| 1106 |
`ulimit' call can tune system defaults. The library uses a lot |
| 1107 |
more memory compared to the system malloc library because it |
| 1108 |
stores a lot more information about the allocated pointers. |
| 1109 |
|
| 1110 |
_NOTE_: This also may be due to an inability of your operating |
| 1111 |
system to use the `mmap' system call to allocate memory. You may |
| 1112 |
need to force the `USE_MMAP' setting to be 0. Please use the |
| 1113 |
forums at URL `http://dmalloc.com/' to report issues with this. |
| 1114 |
|
| 1115 |
`45 (ERROR_OVER_LIMIT) over user specified allocation limit' |
| 1116 |
The library has allocated more memory than was specified in the |
| 1117 |
memory-limit environmental variable. *Note Environment Variable::. |
| 1118 |
|
| 1119 |
`60 (ERROR_NOT_ON_BLOCK) pointer is not on block boundary' |
| 1120 |
The user tried to free or realloc a pointer that was not pointing |
| 1121 |
to a block boundary. You would get this error, for example, if |
| 1122 |
you allocate and get pointer `X' but then try to free `X+1'. |
| 1123 |
|
| 1124 |
`61 (ERROR_ALREADY_FREE) tried to free previously freed pointer' |
| 1125 |
The user tried to free a pointer than has already been freed. |
| 1126 |
This is a very common mistake and can lead to serious problems. |
| 1127 |
It can be because a destructor is being called twice for some |
| 1128 |
reason. Although tracking down the specific source is highly |
| 1129 |
recommended, it is good to set pointers to NULL (0L) after you |
| 1130 |
free them as a rule. |
| 1131 |
|
| 1132 |
`67 (ERROR_FREE_OVERWRITTEN) free space has been overwritten' |
| 1133 |
If either the `free-blank' or `check-blank' tokens are enabled |
| 1134 |
then the library will overwrite memory when it is freed with the |
| 1135 |
"dmalloc-free" byte (hex 0xdf, octal 0337, decimal 223). If the |
| 1136 |
program writes into this space, then the library will detect the |
| 1137 |
write and trigger this error. This could indicate that the |
| 1138 |
program is using a pointer after it has been freed. |
| 1139 |
|
| 1140 |
`70 (ERROR_ADMIN_LIST) bad admin structure list' |
| 1141 |
An internal corruption in the library's administrative structures |
| 1142 |
has been detected. This could be a random pointer problem, pointer |
| 1143 |
overflow, or some other corruption. |
| 1144 |
|
| 1145 |
`72 (ERROR_ADDRESS_LIST) internal address list corruption' |
| 1146 |
An internal corruption in the library's administrative structures |
| 1147 |
has been detected. This could be a random pointer problem, pointer |
| 1148 |
overflow, or some other corruption. |
| 1149 |
|
| 1150 |
`73 (ERROR_SLOT_CORRUPT) internal memory slot corruption' |
| 1151 |
An internal corruption in the library's administrative structures |
| 1152 |
has been detected. This could be a random pointer problem, pointer |
| 1153 |
overflow, or some other corruption. |
| 1154 |
|
| 1155 |
|
| 1156 |
|
| 1157 |
File: dmalloc.info, Node: Disabling the Library, Next: Using With C++, Prev: Error Codes, Up: Programming |
| 1158 |
|
| 1159 |
3.7 How to Disable the library |
| 1160 |
============================== |
| 1161 |
|
| 1162 |
If you would like to disable the library's detailed checking features |
| 1163 |
during a particularly allocation intensive section of code, you can do |
| 1164 |
something like the following: |
| 1165 |
|
| 1166 |
unsigned int dmalloc_flags; |
| 1167 |
... |
| 1168 |
/* turn off all debug flags and save a copy of old value */ |
| 1169 |
dmalloc_flags = dmalloc_debug(0); |
| 1170 |
|
| 1171 |
/* section of a lot of allocations */ |
| 1172 |
... |
| 1173 |
/* end of section */ |
| 1174 |
|
| 1175 |
/* restore the dmalloc flag setting */ |
| 1176 |
dmalloc_debug(dmalloc_flags); |
| 1177 |
|
| 1178 |
When you are finished with the development and debugging sessions, |
| 1179 |
you may want to disable the dmalloc library and put in its place either |
| 1180 |
the system's memory-allocation routines, gnu-malloc, or maybe your own. |
| 1181 |
Attempts have been made to make this a reasonably painless process. The |
| 1182 |
ease of the extraction depends heavily on how many of the library's |
| 1183 |
features your made use of during your coding. |
| 1184 |
|
| 1185 |
Reasonable suggestions are welcome as to how to improve this process |
| 1186 |
while maintaining the effectiveness of the debugging. |
| 1187 |
|
| 1188 |
* If you want to _totally_ disable the dmalloc library then you will |
| 1189 |
need to recompile all the C files that include `dmalloc.h' while |
| 1190 |
defining `DMALLOC_DISABLE'. This will cause the dmalloc macros to |
| 1191 |
not be applied. *Note Allocation Macros::. |
| 1192 |
|
| 1193 |
cc -g -DDMALLOC_DISABLE file.c |
| 1194 |
|
| 1195 |
An alternative is to surround the `dmalloc.h' inclusion or any |
| 1196 |
direct dmalloc references with an `#ifdef DMALLOC' and then just |
| 1197 |
remove the -DDMALLOC. |
| 1198 |
|
| 1199 |
#ifdef DMALLOC |
| 1200 |
#include "dmalloc.h" |
| 1201 |
#endif |
| 1202 |
|
| 1203 |
main() |
| 1204 |
{ |
| 1205 |
... |
| 1206 |
|
| 1207 |
#ifdef DMALLOC |
| 1208 |
dmalloc_verify(0L); |
| 1209 |
#endif |
| 1210 |
return 0; |
| 1211 |
} |
| 1212 |
|
| 1213 |
// to get dmalloc information |
| 1214 |
$ cc -DDMALLOC main.c |
| 1215 |
|
| 1216 |
// without dmalloc information |
| 1217 |
$ cc main.c |
| 1218 |
|
| 1219 |
* If you compiled any of your source modules with |
| 1220 |
`DMALLOC_FUNC_CHECK' defined then you must first recompile all |
| 1221 |
those modules without the flag enabled. |
| 1222 |
|
| 1223 |
If you have disabled dmalloc with the `DMALLOC_DISABLED' flag or |
| 1224 |
never included `dmalloc.h' in any of your C files, then you will |
| 1225 |
not need to recompile your sources when you need to disable the |
| 1226 |
library. |
| 1227 |
|
| 1228 |
If you get unresolved references like `_dmalloc_malloc' or |
| 1229 |
`_dmalloc_bcopy' then something was not disabled as it should have |
| 1230 |
been. |
| 1231 |
|
| 1232 |
|
| 1233 |
File: dmalloc.info, Node: Using With C++, Next: Using With a Debugger, Prev: Disabling the Library, Up: Programming |
| 1234 |
|
| 1235 |
3.8 Using the Library with C++ |
| 1236 |
============================== |
| 1237 |
|
| 1238 |
For those people using the C++ language, the library tries to configure |
| 1239 |
and build `libdmallocxx.a' library. This library should be linked into |
| 1240 |
your C++ programs instead of `libdmalloc.a'. |
| 1241 |
|
| 1242 |
Dmalloc is not as good with C++ as C because the dynamic memory |
| 1243 |
routines in C++ are `new()' and `delete()' as opposed to `malloc()' and |
| 1244 |
`free()'. Since new and delete are usually not used as functions but |
| 1245 |
rather as `x = new type', there is no easy way for dmalloc to pass in |
| 1246 |
file and line information unfortunately. The `libdmallocxx.a' library |
| 1247 |
provides the file `dmallocc.cc' which effectively redirects `new' to |
| 1248 |
the more familiar `malloc' and `delete' to the more familiar `free'. |
| 1249 |
|
| 1250 |
_NOTE_: The author is not a C++ hacker so feedback in the form of |
| 1251 |
other hints and ideas for C++ users would be much appreciated. |
| 1252 |
|
| 1253 |
|
| 1254 |
File: dmalloc.info, Node: Using With a Debugger, Next: Using With Threads, Prev: Using With C++, Up: Programming |
| 1255 |
|
| 1256 |
3.9 Using Dmalloc With a Debugger |
| 1257 |
================================= |
| 1258 |
|
| 1259 |
Here are a number of possible scenarios for using the dmalloc library to |
| 1260 |
track down problems with your program. |
| 1261 |
|
| 1262 |
You should first enable a logfile filename and turn on a set of debug |
| 1263 |
features. You can use `dmalloc -l logfile low' to accomplish this. If |
| 1264 |
you are interested in having the error messages printed to your |
| 1265 |
terminal as well, enable the `print-messages' token by typing `dmalloc |
| 1266 |
-p print-messages' afterwards. *Note Dmalloc Program::. |
| 1267 |
|
| 1268 |
Now you can enter your debugger (I use the _excellent_ GNU debugger |
| 1269 |
gdb), and put a break-point in `dmalloc_error()' which is the internal |
| 1270 |
error routine for the library. When your program is run, it will stop |
| 1271 |
there if a memory problem is detected. |
| 1272 |
|
| 1273 |
If you are using GDB, I would recommend adding the contents of |
| 1274 |
`dmalloc.gdb' in the `contrib' subdirectory to your `.gdbinit' file in |
| 1275 |
your home directory. This enables the `dmalloc' command which will |
| 1276 |
prompt you for the arguments to the dmalloc command and will set a |
| 1277 |
break point in `dmalloc_error()' automatically. |
| 1278 |
|
| 1279 |
If you are using shared libraries, you may want to execute the |
| 1280 |
following commands initially to load in dmalloc and other library |
| 1281 |
symbols: |
| 1282 |
|
| 1283 |
(gdb) sharedlibrary |
| 1284 |
(gdb) add-shared-symbol-files |
| 1285 |
|
| 1286 |
* Menu: |
| 1287 |
|
| 1288 |
* General Errors:: Diagnosing general problems with a debugger. |
| 1289 |
* Memory Leaks:: Tracking down non-freed memory. |
| 1290 |
* Fence-Post Overruns:: Diagnosing fence-post overwritten memory. |
| 1291 |
* Translate Return Addresses:: Convert ra return-addresses into a location. |
| 1292 |
|
| 1293 |
|
| 1294 |
File: dmalloc.info, Node: General Errors, Next: Memory Leaks, Prev: Using With a Debugger, Up: Using With a Debugger |
| 1295 |
|
| 1296 |
3.9.1 Diagnosing General Problems with a Debugger |
| 1297 |
------------------------------------------------- |
| 1298 |
|
| 1299 |
If your program stops at the `dmalloc_error()' routine then one of a |
| 1300 |
number of problems could be happening. Incorrect arguments could have |
| 1301 |
been passed to a malloc call: asking for negative number of bytes, |
| 1302 |
trying to realloc a non-heap pointer, etc.. There also could be a |
| 1303 |
problem with the system's allocations: you've run out of memory, some |
| 1304 |
other function in your program is using the heap allocation functions |
| 1305 |
`mmap' or `sbrk', etc.. However, it is most likely that some code that |
| 1306 |
has been executed was naughty. |
| 1307 |
|
| 1308 |
To get more information about the problem, first print via the |
| 1309 |
debugger the dmalloc_errno variable to get the library's internal error |
| 1310 |
code. You can suspend your debugger and run `dmalloc -e |
| 1311 |
value-returned-from-print' to get an English translation of the error. |
| 1312 |
A number of the error messages are designed to indicate specific |
| 1313 |
problems with the library administrative structures and may not be |
| 1314 |
user-friendly. |
| 1315 |
|
| 1316 |
If the problem was due to the arguments or system allocations then |
| 1317 |
the source of the problem has been found. However, if some code did |
| 1318 |
something wrong, you may have some more work to do to locate the actual |
| 1319 |
problem. The `check-heap' token should be enabled and the interval |
| 1320 |
setting disabled or set to a low value so that the library can find the |
| 1321 |
problem as close as possible to its source. The code that was execute |
| 1322 |
right before the library halted, can then be examined closely for |
| 1323 |
irregularities. *Note Debug Tokens::, *Note Dmalloc Program::. |
| 1324 |
|
| 1325 |
You may also want to put calls to `dmalloc_verify(0)' in your code |
| 1326 |
before the section which generated the error. This should locate the |
| 1327 |
problem faster by checking the library's structures at that point. |
| 1328 |
*Note Extensions::. |
| 1329 |
|
| 1330 |
|
| 1331 |
File: dmalloc.info, Node: Memory Leaks, Next: Fence-Post Overruns, Prev: General Errors, Up: Using With a Debugger |
| 1332 |
|
| 1333 |
3.9.2 Tracking Down Non-Freed Memory |
| 1334 |
------------------------------------ |
| 1335 |
|
| 1336 |
So you've run your program, examined the log-file and discovered (to |
| 1337 |
your horror) some un-freed memory. Memory leaks can become large |
| 1338 |
problems since even the smallest and most insignificant leak can starve |
| 1339 |
the program given the right circumstances. |
| 1340 |
|
| 1341 |
not freed: '0x45008' (12 bytes) from 'ra=0x1f8f4' |
| 1342 |
not freed: '0x45028' (12 bytes) from 'unknown' |
| 1343 |
not freed: '0x45048' (10 bytes) from 'argv.c:1077' |
| 1344 |
known memory not freed: 1 pointer, 10 bytes |
| 1345 |
unknown memory not freed: 2 pointers, 24 bytes |
| 1346 |
|
| 1347 |
Above you will see a sample of some non-freed memory messages from |
| 1348 |
the logfile. In the first line the `0x45008' is the pointer that was |
| 1349 |
not freed, the `12 bytes' is the size of the unfreed block, and the |
| 1350 |
`ra=0x1f8f4' or return-address shows where the allocation originated |
| 1351 |
from. *Note Translate Return Addresses::. |
| 1352 |
|
| 1353 |
The systems which cannot provide return-address information show |
| 1354 |
`unknown' instead, as in the 2nd line in the sample above. |
| 1355 |
|
| 1356 |
The `argv.c:1077' information from the 3rd line shows the file and |
| 1357 |
line number which allocated the memory which was not freed. This |
| 1358 |
information comes from the calls from C files which included |
| 1359 |
`dmalloc.h'. *Note Allocation Macros::. |
| 1360 |
|
| 1361 |
At the bottom of the sample it totals the memory for you and breaks |
| 1362 |
it down to known memory (those calls which supplied the file/line |
| 1363 |
information) and unknown (the rest). |
| 1364 |
|
| 1365 |
Often, you may allocate memory in via `strdup()' or another routine, |
| 1366 |
so the logfile listing where in the `strdup' routine the memory was |
| 1367 |
allocated does not help locate the true source of the memory leak - the |
| 1368 |
routine that called `strdup'. Without a mechanism to trace the calling |
| 1369 |
stack, there is no way for the library to see who the caller of the |
| 1370 |
caller (so to speak) was. |
| 1371 |
|
| 1372 |
However, there is a way to track down unfreed memory in this |
| 1373 |
circumstance. You need to compile the library with `STORE_SEEN_COUNT' |
| 1374 |
defined in `conf.h'. The library will then record how many times a |
| 1375 |
pointer has been allocated or freed. It will display the unfreed |
| 1376 |
memory as: |
| 1377 |
|
| 1378 |
not freed: '0x45008|s3' (12 bytes) from 'ra=0x1f8f4' |
| 1379 |
|
| 1380 |
The `STORE_SEEN_COUNT' option adds a `|s#' qualifier to the address. |
| 1381 |
This means that the address in question was seen `#' many times. In |
| 1382 |
the above example, the address `0x45008' was seen `3' times. The last |
| 1383 |
time it was allocated, it was not freed. |
| 1384 |
|
| 1385 |
How can a pointer be "seen" 3 times? Let say you `strdup' a string |
| 1386 |
of 12 characters and get address `0x45008' - this is #1 time the |
| 1387 |
pointer is seen. You then free the pointer (seen #2) but later |
| 1388 |
`strdup' another 12 character string and it gets the `0x45008' address |
| 1389 |
from the free list (seen #3). |
| 1390 |
|
| 1391 |
So to find out who is allocating this particular 12 bytes the 3rd |
| 1392 |
time, try `dmalloc -a 0x45008:3'. The library will stop the program the |
| 1393 |
third time it sees the `0x45008' address. You then enter a debugger |
| 1394 |
and put a break point at `dmalloc_error'. Run the program and when the |
| 1395 |
breakpoint is reached you can examine the stack frame to determine who |
| 1396 |
called `strdup' to allocate the pointer. |
| 1397 |
|
| 1398 |
To not bother with the `STORE_SEEN_COUNT' feature, you can also run |
| 1399 |
your program with the `never-reuse' token enabled. This token will |
| 1400 |
cause the library to never reuse memory that has been freed. Unique |
| 1401 |
addresses are always generated. This should be used with caution since |
| 1402 |
it may cause your program to run out of memory. |
| 1403 |
|
| 1404 |
|
| 1405 |
File: dmalloc.info, Node: Fence-Post Overruns, Next: Translate Return Addresses, Prev: Memory Leaks, Up: Using With a Debugger |
| 1406 |
|
| 1407 |
3.9.3 Diagnosing Fence-Post Overwritten Memory |
| 1408 |
---------------------------------------------- |
| 1409 |
|
| 1410 |
For a definition of fence-posts please see the "Features" section. |
| 1411 |
*Note Features::. |
| 1412 |
|
| 1413 |
To detect fence-post overruns, you need to enable the `check-fence' |
| 1414 |
token. *Note Debug Tokens::. This pads your allocations with some |
| 1415 |
extra bytes at the front and the end and watches the space to make sure |
| 1416 |
that they don't get overwritten. _NOTE:_ The library cannot detect if |
| 1417 |
this space gets read, only written. |
| 1418 |
|
| 1419 |
If you have encountered a fence-post memory error, the logfile |
| 1420 |
should be able to tell you the offending address. |
| 1421 |
|
| 1422 |
free: failed UNDER picket-fence magic-number checking: |
| 1423 |
pointer '0x1d008' from 'dmalloc_t.c:427' |
| 1424 |
Dump of proper fence-bottom bytes: '\e\253\300\300\e\253\300\300' |
| 1425 |
Dump of '0x1d008'-8: '\e\253\300\300WOW!\003\001pforger\023\001\123' |
| 1426 |
|
| 1427 |
The above sample shows that the pointer `0x1d008' has had its lower |
| 1428 |
fence-post area overwritten. This means that the code wrote below the |
| 1429 |
bottom of the address or above the address right below this one. In the |
| 1430 |
sample, the string that did it was `WOW!'. |
| 1431 |
|
| 1432 |
The library first shows you what the proper fence-post information |
| 1433 |
should look like, and then shows what the pointer's bad information was. |
| 1434 |
If it cannot print the character, it will display the value as `\ddd' |
| 1435 |
where ddd are three octal digits. |
| 1436 |
|
| 1437 |
By enabling the `check-heap' debugging token and assigning the |
| 1438 |
interval setting to a low number, you should be able to locate |
| 1439 |
approximately when this problem happened. *Note Debug Tokens::, *Note |
| 1440 |
Dmalloc Program::. |
| 1441 |
|
| 1442 |
|
| 1443 |
File: dmalloc.info, Node: Translate Return Addresses, Prev: Fence-Post Overruns, Up: Using With a Debugger |
| 1444 |
|
| 1445 |
3.9.4 Translating Return Addresses into Code Locations |
| 1446 |
------------------------------------------------------ |
| 1447 |
|
| 1448 |
The following gdb commands help you translate the return-addresses (ra=) |
| 1449 |
entries in the logfile into locations in your code. I've provided a |
| 1450 |
`ra_info.pl' perl script in the `contrib/' directory with the dmalloc |
| 1451 |
sources which seems to work well with gdb. But, if you need to do it |
| 1452 |
manually, here are the commands in gdb to use. |
| 1453 |
|
| 1454 |
# you may need to add the following commands to load in shared libraries |
| 1455 |
(gdb) sharedlibrary |
| 1456 |
(gdb) add-shared-symbol-files |
| 1457 |
|
| 1458 |
(gdb) x 0x10234d |
| 1459 |
0x10234d <_findbuf+132>: 0x7fffceb7 |
| 1460 |
|
| 1461 |
(gdb) info line *(0x82cc) |
| 1462 |
Line 1092 of argv.c starts at pc 0x7540 and ends at 0x7550. |
| 1463 |
|
| 1464 |
In the above example, gdb was used to find that the two non-freed |
| 1465 |
memory pointers were allocated in `_findbuf()' and in file argv.c line |
| 1466 |
1092 respectively. The `x address' (for examine) can always be used on |
| 1467 |
the return-addresses but the `info line *(address)' will only work if |
| 1468 |
that file was compiled using the `-g' option and has not been stripped. |
| 1469 |
This limitation may not be true in later versions of gdb. |
| 1470 |
|
| 1471 |
|
| 1472 |
File: dmalloc.info, Node: Using With Threads, Next: Using With Cygwin, Prev: Using With a Debugger, Up: Programming |
| 1473 |
|
| 1474 |
3.10 Using the Library with a Thread Package |
| 1475 |
============================================ |
| 1476 |
|
| 1477 |
Threads are special operating system facilities which allow your |
| 1478 |
programs to have multiple threads of execution (hence the name). In |
| 1479 |
effect your program can be doing a number of things "at the same time". |
| 1480 |
This allows you to take full advantage of modern operating system |
| 1481 |
scheduling and multi-processor hardware. If I've already lost you or |
| 1482 |
if any of the terminology below does not make sense, see manuals about |
| 1483 |
POSIX threads (pthreads) before going any further. O'Reilly publishes |
| 1484 |
a pretty good pthreads manual for example. |
| 1485 |
|
| 1486 |
To use dmalloc with your threaded program, you will first need to |
| 1487 |
make sure that you are linking with `libdmallocth.a' which is the |
| 1488 |
threaded version of the library. The support for threads in dmalloc |
| 1489 |
should be adequate for most if not all testing scenarios. It provides |
| 1490 |
support for mutex locking itself to protect against race conditions that |
| 1491 |
result in multiple simultaneous execution. One of the major problems is |
| 1492 |
that most thread libraries uses malloc themselves. Since all of |
| 1493 |
dmalloc's initialization happens when a call to malloc is made, we may |
| 1494 |
be attempting to initialize or lock the mutex while the thread library |
| 1495 |
is booting up. A very bad thing since thread libraries don't expect to |
| 1496 |
recurse. |
| 1497 |
|
| 1498 |
The solution to this problem is to have the library not initialize or |
| 1499 |
lock its mutex variable until after a certain number of allocation calls |
| 1500 |
have been completed. If the library does not wait before initializing |
| 1501 |
the locks, the thread library will probably core dump. If it waits too |
| 1502 |
long then it can't protect itself from multiple execution and it will |
| 1503 |
abort or other bad things might happen. You adjust the number of times |
| 1504 |
to wait at runtime with the `lock-on' option to the dmalloc program |
| 1505 |
(for example `dmalloc -o 20'). *Note Dmalloc Program::. Times values |
| 1506 |
between 5 and 30 are probably good although operating systems will vary |
| 1507 |
significantly. You know its too low if your program immediately core |
| 1508 |
dumps and too high if the dmalloc library says its gone recursive |
| 1509 |
although with low values, you might get either problem. |
| 1510 |
|
| 1511 |
An additional complexity is when we are initializing the lock before |
| 1512 |
mutex locking around the library. As mentioned, the initialization |
| 1513 |
itself may generate a malloc call causing the library to go recursive |
| 1514 |
and the pthread library to possibly core dump. With the THREAD_INIT_LOCK |
| 1515 |
setting defined in `settings.h', you can tune how many times before we |
| 1516 |
start locking to try and initialize the mutex lock. It defaults to 2 |
| 1517 |
which seems to work for me. If people need to have this runtime |
| 1518 |
configurable or would like to present an alternative default, please let |
| 1519 |
me know. |
| 1520 |
|
| 1521 |
So to use dmalloc with a threaded program, follow the following steps |
| 1522 |
carefully. |
| 1523 |
|
| 1524 |
1. Follow the installation instructions on how to configure, make, |
| 1525 |
and install the library but make sure to add the |
| 1526 |
`--enable-threads' argument to configure. *Note Installation::. |
| 1527 |
|
| 1528 |
2. Typing `make' should be enough to build the threaded versions of |
| 1529 |
the libraries including `libdmallocth.a'. |
| 1530 |
|
| 1531 |
3. Link the dmalloc threaded library into your program. The dmalloc |
| 1532 |
library should probably be placed at or near the end of the library |
| 1533 |
list. |
| 1534 |
|
| 1535 |
4. Enable the debugging options that you need by typing `dmalloc -l |
| 1536 |
logfile -i 100 low' (for example). `dmalloc --usage' will provide |
| 1537 |
verbose usage info for the dmalloc program. *Note Dmalloc |
| 1538 |
Program::. |
| 1539 |
|
| 1540 |
5. Enable the "lock-on" option (for example `dmalloc -o 20'). As |
| 1541 |
explained above, you may have to try different values before |
| 1542 |
getting it right. Values between 5 and 30 are probably good. |
| 1543 |
|
| 1544 |
6. If you get a dmalloc error #13 `thread locking has not been |
| 1545 |
configured' then you have not compiled you program with the |
| 1546 |
threaded version of dmalloc or there was a problem building it. |
| 1547 |
|
| 1548 |
7. If everything works, you should be able to run your program, have |
| 1549 |
it not immediately crash, and the dmalloc library should not |
| 1550 |
complain about recursion. |
| 1551 |
|
| 1552 |
|
| 1553 |
If you have any specific questions or would like addition information |
| 1554 |
posted in this section, please let me know. Experienced thread |
| 1555 |
programmers only please. |
| 1556 |
|
| 1557 |
|
| 1558 |
File: dmalloc.info, Node: Using With Cygwin, Next: Debugging A Server, Prev: Using With Threads, Up: Programming |
| 1559 |
|
| 1560 |
3.11 Using the library with Cygwin environment. |
| 1561 |
=============================================== |
| 1562 |
|
| 1563 |
The Cygwin environment is a Linux-like environment for Windows. It |
| 1564 |
provides Linux look and feel as well as a programming environment. See |
| 1565 |
URL `http://www.cygwin.com/' for more details. |
| 1566 |
|
| 1567 |
Cygwin uses the `GetEnvironmentVariableA' function to read in |
| 1568 |
environmental variables instead of `getenv'. This functions are used |
| 1569 |
to get the value of the `DMALLOC_OPTIONS' variable which sets the |
| 1570 |
debugging options. *Note Environment Variable::. |
| 1571 |
|
| 1572 |
As of right now, dmalloc is not detecting the |
| 1573 |
`GetEnvironmentVariableA' function correctly so you may need to tune |
| 1574 |
the `conf.h' file to get it to work. See the sections on |
| 1575 |
`HAVE_GETENVIRONMENTVARIABLEA' and `GETENV_SAVE' settings. Feedback is |
| 1576 |
welcome here. |
| 1577 |
|
| 1578 |
If you still have problems reading in the environmental variables, |
| 1579 |
you can work around this issue. You can add some code into the `main' |
| 1580 |
function in your program to initialize the dmalloc flags yourself. |
| 1581 |
Here is a code sample: |
| 1582 |
|
| 1583 |
main(int argc, char **argv) |
| 1584 |
{ |
| 1585 |
#ifdef DMALLOC |
| 1586 |
/* |
| 1587 |
* Get environ variable DMALLOC_OPTIONS and pass the settings string |
| 1588 |
* on to dmalloc_debug_setup to setup the dmalloc debugging flags. |
| 1589 |
*/ |
| 1590 |
dmalloc_debug_setup(getenv("DMALLOC_OPTIONS")); |
| 1591 |
#endif |
| 1592 |
|
| 1593 |
/* rest of code in main starts here */ |
| 1594 |
... |
| 1595 |
} |
| 1596 |
|
| 1597 |
The `#ifdef' is just a good idea. I means that when debugging with |
| 1598 |
dmalloc you need to compile your code with `-DDMALLOC'. When you are |
| 1599 |
done debugging you can remove the flag and the call to |
| 1600 |
`dmalloc_debug_setup' will be removed. |
| 1601 |
|
| 1602 |
Please let me know if there is a better way to do this. |
| 1603 |
|
| 1604 |
|
| 1605 |
File: dmalloc.info, Node: Debugging A Server, Next: Logfile Details, Prev: Using With Cygwin, Up: Programming |
| 1606 |
|
| 1607 |
3.12 Debugging Memory in a Server or Cgi-Bin Process |
| 1608 |
==================================================== |
| 1609 |
|
| 1610 |
There are some specified challenges when trying to debug allocations in |
| 1611 |
processes which do not startup, run, and then shutdown. Server |
| 1612 |
processes (often called daemons) are those that are started (often at |
| 1613 |
system boot time) and run perpetually. Other processes which are |
| 1614 |
difficult to debug are CGI programs which are spawned by web servers or |
| 1615 |
when you want to start debugging inside of a child process. |
| 1616 |
|
| 1617 |
1. Build your server or cgi-bin program with the dmalloc library like |
| 1618 |
any other program. *Note Getting Started::. |
| 1619 |
|
| 1620 |
2. Add code into your program to enable the library flags to perform |
| 1621 |
the memory checks that you require. Since these programs often do |
| 1622 |
not run from the command line, you cannot use the dmalloc utility |
| 1623 |
program and modify the process environment. *Note Dmalloc |
| 1624 |
Program::. The library provides a couple of functions to set the |
| 1625 |
debugging flags when a program is running. |
| 1626 |
|
| 1627 |
3. To set the memory debugging flags, use the `dmalloc_debug_setup' |
| 1628 |
function which takes a string in the same format of the |
| 1629 |
`DMALLOC_OPTIONS' environmental variable. *Note Environment |
| 1630 |
Variable::. Use the dmalloc utility with the `-n' no-changes |
| 1631 |
argument to see the appropriate settings for the `DMALLOC_OPTIONS' |
| 1632 |
environmental variable. |
| 1633 |
|
| 1634 |
> dmalloc -n -l logfile high |
| 1635 |
Outputed: |
| 1636 |
DMALLOC_OPTIONS=debug=0x4f4ed03,log=logfile |
| 1637 |
export DMALLOC_OPTIONS |
| 1638 |
|
| 1639 |
So if you want to turn on `high' debugging and log to the file |
| 1640 |
`logfile' then you would copy the above `DMALLOC_OPTIONS' value |
| 1641 |
into a call to `dmalloc_debug_setup'. Notice that I have |
| 1642 |
surrounded the dmalloc code with an `#ifdef DMALLOC' so you'll |
| 1643 |
have to compile using the `-DDMALLOC' flag. |
| 1644 |
|
| 1645 |
main() |
| 1646 |
{ |
| 1647 |
#ifdef DMALLOC |
| 1648 |
/* set the 'high' flags */ |
| 1649 |
dmalloc_debug_setup("debug=0x4f47d03,log=logfile"); |
| 1650 |
#endif |
| 1651 |
... |
| 1652 |
} |
| 1653 |
|
| 1654 |
_Please note_ that the `dmalloc_debug_setup' function does not |
| 1655 |
know about `high', `low', or other debug tokens but needs the |
| 1656 |
actual flag values. |
| 1657 |
|
| 1658 |
4. For earlier versions of the library (before 5.0.0) without |
| 1659 |
`dmalloc_debug_setup', the `dmalloc_debug' function is available |
| 1660 |
to set the flags directly, but it cannot adjust the logfile name |
| 1661 |
and the other environment settings. You can use the dmalloc |
| 1662 |
utility program to see what the numerical equivalent of the `high' |
| 1663 |
token. |
| 1664 |
|
| 1665 |
> dmalloc -n high |
| 1666 |
Outputed: |
| 1667 |
DMALLOC_OPTIONS=debug=0x4f4ed03 |
| 1668 |
export DMALLOC_OPTIONS |
| 1669 |
|
| 1670 |
You can then take the `0x4f4ed03' hexadecimal number and call |
| 1671 |
`dmalloc_debug' with that number. |
| 1672 |
|
| 1673 |
main() |
| 1674 |
{ |
| 1675 |
#ifdef DMALLOC |
| 1676 |
/* set the 'high' flags */ |
| 1677 |
dmalloc_debug(0x4f4ed03); |
| 1678 |
#endif |
| 1679 |
... |
| 1680 |
} |
| 1681 |
|
| 1682 |
5. Even with the settings enabled, you may have problems getting the |
| 1683 |
logfile to be written if your program is running as `nobody' or |
| 1684 |
another user without permissions for security reasons. This is |
| 1685 |
especially true for cgi-bin programs. In this case you should |
| 1686 |
specify a full path to your malloc logfile in a world writable |
| 1687 |
directory (ex. |
| 1688 |
`dmalloc_debug_setup("debug=0x4f47d03,log=/var/tmp/malloc");'). |
| 1689 |
Watch for programs which change into other directories and which |
| 1690 |
may cause logfiles specified as relative or local paths to be |
| 1691 |
dropped in other locations. You may always want to use a full |
| 1692 |
path logfile. |
| 1693 |
|
| 1694 |
6. Once you have your settings enabled and your log is being |
| 1695 |
generated, you may now want to check out how your process is doing |
| 1696 |
in terms of unfreed memory. Since it is not shutting down, the |
| 1697 |
automatic unfreed log entries are not being dropped to the |
| 1698 |
logfile. By using the `dmalloc_mark' and `dmalloc_log_changed' |
| 1699 |
functions, you can set a mark point at a certain place inside of |
| 1700 |
your program, and then later see whether there are any unfreed |
| 1701 |
pointers since the mark. |
| 1702 |
|
| 1703 |
main() |
| 1704 |
{ |
| 1705 |
#ifdef DMALLOC |
| 1706 |
/* set the 'high' flags */ |
| 1707 |
dmalloc_debug_setup("debug=0x4f47d03,log=logfile"); |
| 1708 |
#endif |
| 1709 |
|
| 1710 |
while (1) { |
| 1711 |
/* accept a connection from a client */ |
| 1712 |
accept_connection(); |
| 1713 |
|
| 1714 |
while (1) { |
| 1715 |
#ifdef DMALLOC |
| 1716 |
unsigned long mark; |
| 1717 |
/* get the current dmalloc position */ |
| 1718 |
mark = dmalloc_mark() ; |
| 1719 |
#endif |
| 1720 |
/* process the connection */ |
| 1721 |
if (process_connection() != PROCESS_OK) { |
| 1722 |
break; |
| 1723 |
} |
| 1724 |
#ifdef DMALLOC |
| 1725 |
/* |
| 1726 |
* log unfreed pointers that have been added to |
| 1727 |
* the heap since mark |
| 1728 |
*/ |
| 1729 |
dmalloc_log_changed(mark, |
| 1730 |
1 /* log unfreed pointers */, |
| 1731 |
0 /* do not log freed pointers */, |
| 1732 |
1 /* log each pnt otherwise summary */); |
| 1733 |
#endif |
| 1734 |
} |
| 1735 |
/* close the connection with the client */ |
| 1736 |
close_connection(); |
| 1737 |
} |
| 1738 |
... |
| 1739 |
} |
| 1740 |
|
| 1741 |
Usually you would set the mark after the initializations and before |
| 1742 |
each transaction is processed. Then for each transaction you can |
| 1743 |
use `dmalloc_log_changed' to show the unfreed memory. *Note |
| 1744 |
Extensions::. |
| 1745 |
|
| 1746 |
7. You can also use the `dmalloc_log_stats' function to dump general |
| 1747 |
information about the heap. Also, remember that you can use the |
| 1748 |
`dmalloc_message' and `dmalloc_vmessage' routines to annotate the |
| 1749 |
dmalloc logfile with details to help you debug memory problems. |
| 1750 |
*Note Extensions::. |
| 1751 |
|
| 1752 |
|
| 1753 |
|
| 1754 |
File: dmalloc.info, Node: Logfile Details, Next: Other Hints, Prev: Debugging A Server, Up: Programming |
| 1755 |
|
| 1756 |
3.13 Explanation of the Logfile Output |
| 1757 |
====================================== |
| 1758 |
|
| 1759 |
Most of time you will be using the logfile output from library as the |
| 1760 |
sole information source for diagnosing problems in and getting |
| 1761 |
statistics for your program. |
| 1762 |
|
| 1763 |
1098918225: 3: Dmalloc version 'Version 5.5.2' |
| 1764 |
1098918225: 3: flags = 0x4f4e503, logfile '/tmp/dmalloc.log' |
| 1765 |
1098918225: 3: interval = 500, addr = 0, seen # = 0, limit = 0 |
| 1766 |
1098918225: 3: starting time = 1098918225 |
| 1767 |
1098918225: 3: process pid = 32406 |
| 1768 |
1098918226: 4: WARNING: tried to free(0) from foo.c:708' |
| 1769 |
1098918228: 20: *** free: at 'unknown' pnt '0xed310080|s2': \ |
| 1770 |
size 12, alloced at 'bar.c:102' |
| 1771 |
1098918230: 50: ERROR: heap_check: free space was overwritten (err 67) |
| 1772 |
1098918230: 50: error details: checking free pointer |
| 1773 |
1098918230: 50: pointer '0x291c5' from 'unknown' prev access 'foo.c:787' |
| 1774 |
|
| 1775 |
Here is a short example of some logfile information. Each of the |
| 1776 |
lines are prefixed by the time (in epoch seconds since 1/1/1970) and |
| 1777 |
the iteration or call count which is the number of times the library |
| 1778 |
has been called from malloc, free, verify, etc.. In the above example, |
| 1779 |
the first 5 log entries where written at epoch 1098918225 or `Wed Oct |
| 1780 |
27 19:03:45 2004 EST' and they were generated by the 3rd call to the |
| 1781 |
library. See the `settings.dist' file entries to tune what elements |
| 1782 |
appear on each line: LOG_TIME_NUMBER, LOG_ITERATION, LOG_PID, etc.. |
| 1783 |
You can convert the epoch seconds to a date from the command line with |
| 1784 |
the following perl code: `perl -e 'print localtime($ARGV[0])."\n";' |
| 1785 |
epoch-seconds-number' |
| 1786 |
|
| 1787 |
The first 5 lines of the sample logfile contain header information |
| 1788 |
for all logfiles. They show the version number and URL for the library |
| 1789 |
as well as all of the settings that the library is currently using. |
| 1790 |
These settings are tuned using the dmalloc utility program. *Note |
| 1791 |
Dmalloc Program::. The 5th line of is the process-id that generated |
| 1792 |
the logfile. |
| 1793 |
|
| 1794 |
The 6th line in the above example is what causes the logfile to be |
| 1795 |
opened and the header to be written. It is a warning that tells you |
| 1796 |
that you tried to free a 0L pointer at a certain location. You can |
| 1797 |
disable these warnings by setting `ALLOW_FREE_NULL_MESSAGE' to 0 in |
| 1798 |
`settings.dist'. |
| 1799 |
|
| 1800 |
Line 7 is an example of a transaction log that you get when you |
| 1801 |
enable the `log-trans' debug token. *Note Debug Tokens::. This line |
| 1802 |
shows that a call to free was made from an unknown location. It is |
| 1803 |
unknown because the file in question did not include `dmalloc.h' to get |
| 1804 |
file/line-number information. The call to free was freeing the pointer |
| 1805 |
address `0xed310080' which we have "seen" 2 times (s2). We saw the |
| 1806 |
pointer when it was allocated and then we are seeing it again when it |
| 1807 |
was freed. Because the library is reusing pointers (reclaiming freed |
| 1808 |
memory) the seen count helps to track how many times a pointer was |
| 1809 |
used. The last part of the line shows that the pointer to be freed was |
| 1810 |
allocated by `bar.c' line 102. |
| 1811 |
|
| 1812 |
Lines 8-10 is the next problem that the library caught and this one |
| 1813 |
is an error. It happened 5 seconds from the start of the log |
| 1814 |
(1098918230) and at the 50th call into the library. It shows that an |
| 1815 |
allocation that had been freed then was overwritten. This may imply |
| 1816 |
that someone tried to use memory after it was freed or that there was a |
| 1817 |
loose pointer reference. The last two lines give more details about |
| 1818 |
when the error was discovered, the address of the offending pointer, |
| 1819 |
and when the pointer was previous accessed, in this case freed. To |
| 1820 |
discover where this problem is happening, you can use a debugger. |
| 1821 |
*Note Using With a Debugger::. |
| 1822 |
|
| 1823 |
|
| 1824 |
File: dmalloc.info, Node: Other Hints, Prev: Logfile Details, Up: Programming |
| 1825 |
|
| 1826 |
3.14 Various Other Hints That May Help |
| 1827 |
====================================== |
| 1828 |
|
| 1829 |
One of the problems that is often seen is that a program crashes in the |
| 1830 |
`libc' memory code and you suspect a heap memory problem but both |
| 1831 |
dmalloc and maybe valgrind don't show any problems. One of the big |
| 1832 |
problems with debugging is that it is very difficult to do it without |
| 1833 |
effecting how the program is run. Sometimes errors are due to subtle |
| 1834 |
race conditions that are only seen when the program is running at full |
| 1835 |
speed - not slowed down by debugging code. |
| 1836 |
|
| 1837 |
This is especially true with threaded code which is often heavily |
| 1838 |
affected when used with dmalloc and valgrind. Older versions of |
| 1839 |
valgrid (maybe current) forced all threads into a single virtual system |
| 1840 |
by design, which often masks reentrance bugs. |
| 1841 |
|
| 1842 |
One way to work through these issues is to run with the library with |
| 1843 |
very few debugging flags enabled. Many memory problems are fence-post |
| 1844 |
areas so start with dmalloc checking just the fence post and error |
| 1845 |
logging enabled: |
| 1846 |
|
| 1847 |
dmalloc -d 0 -l dmalloc.log -p log-stats -p log-non-free -p check-fence -p check-funcs |
| 1848 |
|
| 1849 |
This enabled a small number of checks and should cause your program |
| 1850 |
to run at close to full speed. The library has never been optimized for |
| 1851 |
speed so some performance penalties will be felt. |
| 1852 |
|
| 1853 |
|
| 1854 |
File: dmalloc.info, Node: Dmalloc Program, Next: Source Code, Prev: Programming, Up: Top |
| 1855 |
|
| 1856 |
4 Dmalloc Utility Program |
| 1857 |
************************* |
| 1858 |
|
| 1859 |
The dmalloc program is designed to assist in the setting of the |
| 1860 |
environment variable `DMALLOC_OPTIONS'. *Note Environment Variable::. |
| 1861 |
It is designed to print the shell commands necessary to make the |
| 1862 |
appropriate changes to the environment. Unfortunately, it cannot make |
| 1863 |
the changes on its own so the output from dmalloc should be sent |
| 1864 |
through the `eval' shell command which will do the commands. |
| 1865 |
|
| 1866 |
* Menu: |
| 1867 |
|
| 1868 |
* Shell Alias:: Using a shell alias with the utility. |
| 1869 |
* Utility Usage:: How to use the dmalloc program. |
| 1870 |
* Environment Variable:: Environment variable name and features. |
| 1871 |
* Debug Tokens:: Description of the debugging tokens. |
| 1872 |
* RC File:: Format of the runtime configuration file. |
| 1873 |
|
| 1874 |
|
| 1875 |
File: dmalloc.info, Node: Shell Alias, Next: Utility Usage, Prev: Dmalloc Program, Up: Dmalloc Program |
| 1876 |
|
| 1877 |
4.1 Using a Shell Alias with the Utility |
| 1878 |
======================================== |
| 1879 |
|
| 1880 |
The dmalloc program is designed to assist in the setting of the |
| 1881 |
environment variable `DMALLOC_OPTIONS'. *Note Environment Variable::. |
| 1882 |
It is designed to print the shell commands necessary to make the |
| 1883 |
appropriate changes to the environment. Unfortunately, it cannot make |
| 1884 |
the changes on its own so the output from dmalloc should be sent |
| 1885 |
through the `eval' shell command which will do the commands. |
| 1886 |
|
| 1887 |
With shells that have aliasing or macro capabilities: csh, bash, ksh, |
| 1888 |
tcsh, zsh, etc., setting up an alias to dmalloc to do the eval call is |
| 1889 |
recommended. Bash, ksh, and zsh users should add the following to their |
| 1890 |
`.bashrc', `.profile', or `.zshrc' file respectively (notice the `-b' |
| 1891 |
option for bourne shell output): |
| 1892 |
|
| 1893 |
function dmalloc { eval `command dmalloc -b $*`; } |
| 1894 |
|
| 1895 |
If your shell does not support the `command' function then try: |
| 1896 |
|
| 1897 |
function dmalloc { eval `\dmalloc -b $*`; } |
| 1898 |
or |
| 1899 |
function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; } |
| 1900 |
|
| 1901 |
If you are _still_ using csh or tcsh, you should add the following |
| 1902 |
to your `.cshrc' file (notice the `-C' option for c-shell output): |
| 1903 |
|
| 1904 |
alias dmalloc 'eval `\dmalloc -C \!*`' |
| 1905 |
|
| 1906 |
This allows the user to execute the dmalloc command as `dmalloc |
| 1907 |
arguments'. |
| 1908 |
|
| 1909 |
Users of versions of the Bourne shell (usually known as /bin/sh) that |
| 1910 |
don't have command functions will need to send the output to a temporary |
| 1911 |
file and the read it back in with the "." command: |
| 1912 |
|
| 1913 |
$ dmalloc -b arguments ... > /tmp/out |
| 1914 |
$ . /tmp/out |
| 1915 |
|
| 1916 |
By the way, if you are looking for a shell, I heartily recommend |
| 1917 |
trying out zsh. It is a bourne shell written from scratch with much |
| 1918 |
the same features as tcsh without the csh crap. |
| 1919 |
|
| 1920 |
_NOTE_: After you add the alias to the file you need to log out and |
| 1921 |
log back in to have it take effect, or you can execute the above |
| 1922 |
appropriate command on the command line. If you enter `dmalloc |
| 1923 |
runtime' and see any output with DMALLOC_OPTIONS in it then the alias |
| 1924 |
did not work. |
| 1925 |
|
| 1926 |
|
| 1927 |
File: dmalloc.info, Node: Utility Usage, Next: Environment Variable, Prev: Shell Alias, Up: Dmalloc Program |
| 1928 |
|
| 1929 |
4.2 How to Use the Dmalloc Program |
| 1930 |
================================== |
| 1931 |
|
| 1932 |
The most basic usage for the program is `dmalloc [-bC] tag'. The `-b' |
| 1933 |
or `-C' (either but not both flags used at a time) are for generating |
| 1934 |
Bourne or C shell type commands respectively. dmalloc will try and use |
| 1935 |
the `SHELL' environment variable to determine whether bourne or C shell |
| 1936 |
commands should be generated but you may want to explicitly specify the |
| 1937 |
correct flag. |
| 1938 |
|
| 1939 |
The `tag' argument to dmalloc should match a line from the user's |
| 1940 |
runtime configuration file or should be one of the built-in tags. |
| 1941 |
*Note RC File::. If no tag is specified and no other option-commands |
| 1942 |
used, dmalloc will display the current settings of the environment |
| 1943 |
variable. It is useful to specify one of the verbose options when doing |
| 1944 |
this. |
| 1945 |
|
| 1946 |
To find out the usage for the debug malloc program try `dmalloc |
| 1947 |
--usage-long'. The standardized usage message that will be displayed is |
| 1948 |
one of the many features of the argv library included with this package. |
| 1949 |
|
| 1950 |
It is available on the web at URL `http://256.com/sources/argv/'. |
| 1951 |
See the documentation there for more information. |
| 1952 |
|
| 1953 |
Here is a detailed list of the flags that can passed to dmalloc: |
| 1954 |
|
| 1955 |
`-a address' |
| 1956 |
Set the `addr' part of the `DMALLOC_OPTIONS' variable to address |
| 1957 |
(or alternatively address:number). |
| 1958 |
|
| 1959 |
`-b' |
| 1960 |
Output Bourne shell type commands. Usually handled automagically. |
| 1961 |
|
| 1962 |
`-C' |
| 1963 |
Output C shell type commands. Usually handled automagically. |
| 1964 |
|
| 1965 |
`-c' |
| 1966 |
Clear/unset all of the settings not specified with other |
| 1967 |
arguments. You can do this automatically when you set to a new |
| 1968 |
tag with the `-r' option. |
| 1969 |
|
| 1970 |
_NOTE_: clear will never unset the `debug' setting. Use `-d 0' or |
| 1971 |
a tag to `none' to achieve this. |
| 1972 |
|
| 1973 |
`-d bitmask' |
| 1974 |
Set the `debug' part of the `DMALLOC_OPTIONS' env variable to the |
| 1975 |
bitmask value which should be in hex. This is overridden (and |
| 1976 |
unnecessary) if a tag is specified. |
| 1977 |
|
| 1978 |
`-D' |
| 1979 |
List all of the debug-tokens. Useful for finding a token to be |
| 1980 |
used with the `-p' or `-m' options. Use with `-v' or `-V' verbose |
| 1981 |
options. |
| 1982 |
|
| 1983 |
`-e errno' |
| 1984 |
Print the dmalloc error string that corresponds to the error number |
| 1985 |
errno. |
| 1986 |
|
| 1987 |
`-f filename' |
| 1988 |
Use this configuration file instead of the RC file |
| 1989 |
`$HOME/.dmallocrc'. |
| 1990 |
|
| 1991 |
`-g' |
| 1992 |
Output gdb type commands for using inside of the gdb debugger. |
| 1993 |
|
| 1994 |
`-h (or --help)' |
| 1995 |
Output a help message for the utility. |
| 1996 |
|
| 1997 |
`-i number' |
| 1998 |
Set the checking interval to number. If the `check-heap' token is |
| 1999 |
enabled, this causes the library to only check the heap every Nth |
| 2000 |
time which can _significantly_ increase the running speed of your |
| 2001 |
program. If a problem is found, however, this limits your ability |
| 2002 |
to determine when the problem occurred. Try values of 50 or 100 |
| 2003 |
initially. |
| 2004 |
|
| 2005 |
`-k' |
| 2006 |
Do not reset all of the settings when a tag is specified. This |
| 2007 |
specifically overrides the `-r' option and is provided here to |
| 2008 |
override `-r' if it has been added to the dmalloc alias. |
| 2009 |
|
| 2010 |
`-l filename' |
| 2011 |
Write the debugging output and other log-file information to the |
| 2012 |
filename. Filename can include some of the following patterns |
| 2013 |
which get expanded into strings: |
| 2014 |
|
| 2015 |
`%h' |
| 2016 |
Gets expanded into the hostname if the `gethostname()' |
| 2017 |
function is available. |
| 2018 |
|
| 2019 |
`%i' |
| 2020 |
Gets expanded into the thread-id if the library has been |
| 2021 |
configure to be used with threads. *Note Using With |
| 2022 |
Threads::. See the end of the `settings.dist' file for |
| 2023 |
settings which return the thread-id and convert it into a |
| 2024 |
string. |
| 2025 |
|
| 2026 |
`%p' |
| 2027 |
Gets expanded into the process-id if the `getpid()' function |
| 2028 |
is available. |
| 2029 |
|
| 2030 |
`%t' |
| 2031 |
Gets expanded into the time value in seconds if the `time()' |
| 2032 |
function is available. |
| 2033 |
|
| 2034 |
`%u' |
| 2035 |
Gets expanded into the user-id number if the `getuid()' |
| 2036 |
function is available. |
| 2037 |
|
| 2038 |
|
| 2039 |
Some examples: |
| 2040 |
|
| 2041 |
# logfile produced with pid extension: |
| 2042 |
# logfile.8412 or logfile.31451 |
| 2043 |
dmalloc -l logfile.%p |
| 2044 |
|
| 2045 |
# hostname and time extensions: |
| 2046 |
# dmalloc-box1.foo.com-1055213240 |
| 2047 |
dmalloc -l dmalloc-%h-%t |
| 2048 |
|
| 2049 |
# if threads enabled, have thread-id extension: log.thread32 |
| 2050 |
dmalloc -l log.thread%i |
| 2051 |
|
| 2052 |
`-L' |
| 2053 |
Write the debug-value into the environment not in hex but by |
| 2054 |
individual debug-tokens in long form. |
| 2055 |
|
| 2056 |
`-m token(s)' |
| 2057 |
Remove (minus) the debug capabilities of token(s) from the current |
| 2058 |
debug setting or from the selected tag (or `-d' value). Multiple |
| 2059 |
`-m' options can be specified. |
| 2060 |
|
| 2061 |
`-M limit' |
| 2062 |
Set the memory allocation limit which will abort the program if the |
| 2063 |
total memory allocations exceed this number of bytes. The limit |
| 2064 |
can be a number with a k, m, or g at the end to indicate kilobyte, |
| 2065 |
megabyte, and gigabyte respectively. Ex: 100k, 200m, 1g. If the |
| 2066 |
limit is exceeded, this will generate an `ERROR_OVER_LIMIT' error. |
| 2067 |
*Note Error Codes::. |
| 2068 |
|
| 2069 |
`-n' |
| 2070 |
Without changing the environment, output the commands resulting |
| 2071 |
from the supplied options. |
| 2072 |
|
| 2073 |
`-o times' |
| 2074 |
Set the "lock-on" period which dictates to the threaded version of |
| 2075 |
the library to not initialize or lock the mutex lock around the |
| 2076 |
library until after a certain number of allocation calls have been |
| 2077 |
made. Some number between 2 and 30 is probably good. See the |
| 2078 |
"Using With Threads" section for more information about the |
| 2079 |
operation of the library with threads. *Note Using With Threads::. |
| 2080 |
|
| 2081 |
`-p token(s)' |
| 2082 |
Add (plus) the debug capabilities of token(s) to the current debug |
| 2083 |
setting or to the selected tag (or `-d' value). Multiple `-p' |
| 2084 |
options can be specified. |
| 2085 |
|
| 2086 |
`-r' |
| 2087 |
Remove (unset) all settings when using a tag. This is useful when |
| 2088 |
you are returning to a standard development tag and want the |
| 2089 |
logfile, address, and interval settings to be cleared |
| 2090 |
automatically. If you want this behavior by default, this can be |
| 2091 |
put into the dmalloc alias. |
| 2092 |
|
| 2093 |
`-R' |
| 2094 |
Output rc shell type commands. This is not for the runtime |
| 2095 |
configuration file but for the rc shell program. |
| 2096 |
|
| 2097 |
`-s file:line' |
| 2098 |
Set the `start' part of the `DMALLOC_OPTIONS' env variable to a |
| 2099 |
file-name and line-number location in the source where the library |
| 2100 |
should begin more extensive heap checking. The file and line |
| 2101 |
numbers for heap transactions must be working for this option to |
| 2102 |
be obeyed. This is used if you are trying to locate a problem and |
| 2103 |
you want the extensive checking to not happen initially because |
| 2104 |
it's too slow. |
| 2105 |
|
| 2106 |
`-S number' |
| 2107 |
Set the `start' part of the `DMALLOC_OPTIONS' env variable to an |
| 2108 |
dmalloc mark number. The library will begin more extensive heap |
| 2109 |
checking after this number of memory transactions. If you |
| 2110 |
`LOG_ITERATION' enabled in your `settings.h' file then the entries |
| 2111 |
in the log file will be prepended with the number of memory |
| 2112 |
transactions that the library has handled so far. This number can |
| 2113 |
be used to delay the start of the fine grained heap checking which |
| 2114 |
can be very slow. |
| 2115 |
|
| 2116 |
`--start-size size' |
| 2117 |
Set the `start' part of the `DMALLOC_OPTIONS' env variable to a |
| 2118 |
number of bytes. The library will begin more extensive heap |
| 2119 |
checking after this amount of memory has been allocated by the |
| 2120 |
library. This allows you to start the slow and detailed checking |
| 2121 |
of the library later in the program execution. You can use |
| 2122 |
patterns like 250m, 1g, or 102k to mean 250 megabytes, 1 gigabyte, |
| 2123 |
and 102 kilobytes respectively. |
| 2124 |
|
| 2125 |
`-t' |
| 2126 |
List all of the tags in the rc-file. Use with `-v' or `-V' |
| 2127 |
verbose options. |
| 2128 |
|
| 2129 |
`-u (or --usage)' |
| 2130 |
Output the usage information for the utility. |
| 2131 |
|
| 2132 |
`-v' |
| 2133 |
Give verbose output. Especially useful when dumping current |
| 2134 |
settings or listing all of the tags. |
| 2135 |
|
| 2136 |
`-V' |
| 2137 |
Give very verbose output for outputting even more details about |
| 2138 |
settings. |
| 2139 |
|
| 2140 |
`--version' |
| 2141 |
Output the version string for the utility. _Please note_ that the |
| 2142 |
version of the library that is installed or has been linked into |
| 2143 |
your application may be different from the utility version. |
| 2144 |
|
| 2145 |
|
| 2146 |
If no arguments are specified, dmalloc dumps out the current settings |
| 2147 |
that you have for the environment variable. For example: |
| 2148 |
|
| 2149 |
Debug-Flags '0x40005c7' (runtime) |
| 2150 |
Address 0x1f008, count = 3 |
| 2151 |
Interval 100 |
| 2152 |
Logpath 'malloc' |
| 2153 |
Start-File not-set |
| 2154 |
|
| 2155 |
With a -v option and no arguments, dmalloc dumps out the current |
| 2156 |
settings in a verbose manner. For example: |
| 2157 |
|
| 2158 |
Debug-Flags '0x40005c7' (runtime) |
| 2159 |
log-stats, log-non-free, log-bad-space, check-fence, catch-null |
| 2160 |
Address 0x1f008, count = 10 |
| 2161 |
Interval 100 |
| 2162 |
Logpath 'malloc' |
| 2163 |
Start-File not-set |
| 2164 |
|
| 2165 |
Here are some examples of dmalloc usage: |
| 2166 |
|
| 2167 |
# start tough debugging, check the heap every 100 times, |
| 2168 |
# send the log information to file 'logfile' |
| 2169 |
dmalloc high -i 100 -l logfile |
| 2170 |
|
| 2171 |
# find out what error code 20 is (from the logfile) |
| 2172 |
dmalloc -e 20 |
| 2173 |
|
| 2174 |
# cause the library to halt itself when it sees the address 0x34238 |
| 2175 |
# for the 6th time. |
| 2176 |
dmalloc -a 0x34238:6 |
| 2177 |
|
| 2178 |
# send the log information to file 'logfile' with the time in seconds |
| 2179 |
# as an extension. |
| 2180 |
dmalloc -l logfile.%t |
| 2181 |
|
| 2182 |
# return to the normal 'runtime' settings and clear out all |
| 2183 |
# other settings |
| 2184 |
dmalloc -c runtime |
| 2185 |
|
| 2186 |
# enable basic 'low' settings plus (-p) the logging of |
| 2187 |
# transactions (log-trans) to file 'logfile' |
| 2188 |
dmalloc low -p log-trans -l logfile |
| 2189 |
|
| 2190 |
# print out the current settings with Very-verbose output |
| 2191 |
dmalloc -V |
| 2192 |
|
| 2193 |
# list the available debug malloc tokens with Very-verbose output |
| 2194 |
dmalloc -DV |
| 2195 |
|
| 2196 |
# list the available tags from the rc file with verbose output |
| 2197 |
dmalloc -tv |
| 2198 |
|
| 2199 |
|
| 2200 |
File: dmalloc.info, Node: Environment Variable, Next: Debug Tokens, Prev: Utility Usage, Up: Dmalloc Program |
| 2201 |
|
| 2202 |
4.3 Environment Variable Name and Features |
| 2203 |
========================================== |
| 2204 |
|
| 2205 |
An "environment variable" is a variable that is part of the user's |
| 2206 |
working environment and is shared by all the programs. The |
| 2207 |
`DMALLOC_OPTIONS' variable is used by the dmalloc library to enable or |
| 2208 |
disable the memory debugging features, at runtime. _NOTE:_ you can |
| 2209 |
also use the `dmalloc_debug_setup' function to set the option string. |
| 2210 |
It can be set either by hand or with the help of the dmalloc program. |
| 2211 |
*Note Dmalloc Program::. |
| 2212 |
|
| 2213 |
To set it by hand, Bourne shell (sh, bash, ksh, or zsh) users should |
| 2214 |
use: |
| 2215 |
|
| 2216 |
DMALLOC_OPTIONS=value |
| 2217 |
export DMALLOC_OPTIONS |
| 2218 |
|
| 2219 |
C shell (csh or tcsh) users need to invoke: |
| 2220 |
|
| 2221 |
setenv DMALLOC_OPTIONS value |
| 2222 |
|
| 2223 |
The value in the above examples is a comma separated list of tokens |
| 2224 |
each having a corresponding value. The tokens are described below: |
| 2225 |
|
| 2226 |
`debug' |
| 2227 |
This should be set to a value in hexadecimal which corresponds to |
| 2228 |
the functionality token values added together. *Note Debug |
| 2229 |
Tokens::. For instance, if the user wanted to enable the logging |
| 2230 |
of memory transactions (value `0x008') and wanted to check |
| 2231 |
fence-post memory (value `0x400') then `debug' should be set to |
| 2232 |
`0x408' (`0x008' + `0x400'). |
| 2233 |
|
| 2234 |
_NOTE_: You don't have to worry about remembering all the hex |
| 2235 |
values of the tokens because the dmalloc program automates the |
| 2236 |
setting of this variable especially. |
| 2237 |
|
| 2238 |
_NOTE_: You can also specify the debug tokens directly, separated |
| 2239 |
by commas. *Note Debug Tokens::. If `debug' and the tokens are |
| 2240 |
both used, the token values will be added to the debug value. |
| 2241 |
|
| 2242 |
`lockon' |
| 2243 |
Set this to a number which is the "lock-on" period. This dictates |
| 2244 |
to the threaded version of the library to not initialize or lock |
| 2245 |
the mutex lock around the library until after a certain number of |
| 2246 |
allocation calls have been made. See the "Using With Threads" |
| 2247 |
section for more information about the operation of the library |
| 2248 |
with threads. *Note Using With Threads::. |
| 2249 |
|
| 2250 |
`log' |
| 2251 |
Set this to a filename so that if `debug' has logging enabled, the |
| 2252 |
library can log transactions, administration information, and/or |
| 2253 |
errors to the file so memory problems and usage can be tracked. |
| 2254 |
|
| 2255 |
To get different logfiles for different processes, you can assign |
| 2256 |
`log' to a string with `%d' in it (for instance `logfile.%d'). |
| 2257 |
This will be replaced with the pid of the running process (for |
| 2258 |
instance `logfile.2451'). |
| 2259 |
|
| 2260 |
_WARNING_: it is easy to core dump any program with dmalloc, if |
| 2261 |
you send in a format with arguments other than the one `%d'. |
| 2262 |
|
| 2263 |
`addr' |
| 2264 |
When this is set to a hex address (taken from the dmalloc log-file |
| 2265 |
for instance) dmalloc will abort when it finds itself either |
| 2266 |
allocating or freeing that address. |
| 2267 |
|
| 2268 |
The address can also have an `:number' argument. For instance, if |
| 2269 |
it was set it to `0x3e45:10', the library will kill itself the 10th |
| 2270 |
time it sees address `0x3e45'. By setting the number argument to |
| 2271 |
0, the program will never stop when it sees the address. This is |
| 2272 |
useful for logging all activity on the address and makes it easier |
| 2273 |
to track down specific addresses not being freed. |
| 2274 |
|
| 2275 |
This works well in conjunction with the `STORE_SEEN_COUNT' option. |
| 2276 |
*Note Memory Leaks::. |
| 2277 |
|
| 2278 |
_NOTE_: dmalloc will also log all activity on this address along |
| 2279 |
with a count. |
| 2280 |
|
| 2281 |
`inter' |
| 2282 |
By setting this to a number X, dmalloc will only check the heap |
| 2283 |
every X times. This means a number of debugging features can be |
| 2284 |
enabled while still running the program within a finite amount of |
| 2285 |
time. |
| 2286 |
|
| 2287 |
A setting of `100' works well with reasonably memory intensive |
| 2288 |
programs. This of course means that the library will not catch |
| 2289 |
errors exactly when they happen but possibly 100 library calls |
| 2290 |
later. |
| 2291 |
|
| 2292 |
`start' |
| 2293 |
Set this to a number X and dmalloc will begin checking the heap |
| 2294 |
after X times. This means the intensive debugging can be started |
| 2295 |
after a certain point in a program. |
| 2296 |
|
| 2297 |
`start' also has the format `file:line'. For instance, if it is |
| 2298 |
set to `dmalloc_t.c:126' dmalloc will start checking the heap |
| 2299 |
after it sees a dmalloc call from the `dmalloc_t.c' file, line |
| 2300 |
number 126. If you use `dmalloc_t.c:0', with a 0 line number, then |
| 2301 |
dmalloc will start checking the heap after it sees a call from |
| 2302 |
anywhere in the `dmalloc_t.c' file. |
| 2303 |
|
| 2304 |
This allows the intensive debugging to be started after a certain |
| 2305 |
routine or file has been reached in the program. |
| 2306 |
|
| 2307 |
Some examples are: |
| 2308 |
|
| 2309 |
# turn on transaction and stats logging and set |
| 2310 |
# 'logfile' as the log-file |
| 2311 |
setenv DMALLOC_OPTIONS log-trans,log-stats,log=logfile |
| 2312 |
|
| 2313 |
# enable debug flags 0x1f as well as heap-checking and |
| 2314 |
# set the interval to be 100 |
| 2315 |
setenv DMALLOC_OPTIONS debug=0x1f,check-heap,inter=100 |
| 2316 |
|
| 2317 |
# enable 'logfile' as the log-file, watch for |
| 2318 |
# address '0x1234', and start checking when we see |
| 2319 |
# file.c line 123 |
| 2320 |
setenv DMALLOC_OPTIONS log=logfile,addr=0x1234,start=file.c:123 |
| 2321 |
|
| 2322 |
|
| 2323 |
File: dmalloc.info, Node: Debug Tokens, Next: RC File, Prev: Environment Variable, Up: Dmalloc Program |
| 2324 |
|
| 2325 |
4.4 Description of the Debugging Tokens |
| 2326 |
======================================= |
| 2327 |
|
| 2328 |
The below tokens and their corresponding descriptions are for the |
| 2329 |
setting of the debug library setting in the environment variable. |
| 2330 |
*Note Environment Variable::. They should be specified in the user's |
| 2331 |
`.dmallocrc' file. *Note RC File::. |
| 2332 |
|
| 2333 |
Each token, when specified, enables a specific debugging feature. |
| 2334 |
For instance, if you have the `log-stats' token enabled, the library |
| 2335 |
will log general statistics to the logfile. |
| 2336 |
|
| 2337 |
To get this information on the fly, use `dmalloc -DV'. This will |
| 2338 |
print out the Debug tokens in Very-verbose mode. *Note Dmalloc |
| 2339 |
Program::. |
| 2340 |
|
| 2341 |
`none' |
| 2342 |
No debugging functionality |
| 2343 |
|
| 2344 |
`log-stats' |
| 2345 |
Log general statistics when dmalloc_shutdown or dmalloc_log_stats |
| 2346 |
is called. |
| 2347 |
|
| 2348 |
`log-non-free' |
| 2349 |
Log non-freed memory pointers when dmalloc_shutdown or |
| 2350 |
dmalloc_log_unfreed is called. |
| 2351 |
|
| 2352 |
`log-known' |
| 2353 |
Log only known memory pointers that have not been freed. Pointers |
| 2354 |
which do not have file/line or return-address information will not |
| 2355 |
be logged. |
| 2356 |
|
| 2357 |
`log-trans' |
| 2358 |
Log general memory transactions (quite verbose). |
| 2359 |
|
| 2360 |
`log-admin' |
| 2361 |
Log administrative information (quite verbose). |
| 2362 |
|
| 2363 |
`log-bad-space' |
| 2364 |
Log actual bytes in and around bad pointers. |
| 2365 |
|
| 2366 |
`log-nonfree-space' |
| 2367 |
Log actual bytes in non-freed pointers. |
| 2368 |
|
| 2369 |
`log-elapsed-time' |
| 2370 |
Log elapsed-time for allocated pointers (see `conf.h'). |
| 2371 |
|
| 2372 |
`log-current-time' |
| 2373 |
Log current-time for allocated pointers (see `conf.h'). |
| 2374 |
|
| 2375 |
`check-fence' |
| 2376 |
Check fence-post memory areas. |
| 2377 |
|
| 2378 |
`check-heap' |
| 2379 |
Verify heap administrative structure. |
| 2380 |
|
| 2381 |
`check-blank' |
| 2382 |
Check to see if space that was blanked when a pointer was |
| 2383 |
allocated or when it was freed has been overwritten. If this is |
| 2384 |
enabled then it will enable `free-blank' and `alloc-blank' |
| 2385 |
automatically. |
| 2386 |
|
| 2387 |
`check-funcs' |
| 2388 |
Check the arguments of some functions (mostly string operations) |
| 2389 |
looking for bad pointers. |
| 2390 |
|
| 2391 |
`check-shutdown' |
| 2392 |
Check all of the pointers in the heap when the program exits. |
| 2393 |
|
| 2394 |
`catch-signals' |
| 2395 |
Shutdown the library automatically on SIGHUP, SIGINT, or SIGTERM. |
| 2396 |
This will cause the library to dump its statistics (if requested) |
| 2397 |
when you press control-c on the program (for example). |
| 2398 |
|
| 2399 |
`realloc-copy' |
| 2400 |
Always copy data to a new pointer when realloc. |
| 2401 |
|
| 2402 |
`free-blank' |
| 2403 |
Write special "dmalloc-free" byte (hexadecimal `0xdf', octal |
| 2404 |
`0337', decimal `223') into space when it is freed. You can set |
| 2405 |
this to be something else in the `settings.dist' file. This |
| 2406 |
ensures that your program is not using memory after it has been |
| 2407 |
freed. You can check to see if areas have been improperly |
| 2408 |
overwritten with the `check-blank' token. If the free space has |
| 2409 |
been overwritten, then `ERROR_FREE_OVERWRITTEN' is triggered. |
| 2410 |
*Note Error Codes::. |
| 2411 |
|
| 2412 |
`error-abort' |
| 2413 |
Abort the program (and dump core) on errors. See `error-dump' |
| 2414 |
below. *Note Dumping Core::. |
| 2415 |
|
| 2416 |
`alloc-blank' |
| 2417 |
Write special "dmalloc-alloc" byte (hexadecimal `0xda', octal |
| 2418 |
`0332', decimal `218') into space when it is allocated. You can |
| 2419 |
set this to be something else in the `settings.dist' file. If you |
| 2420 |
are not using `calloc' this will overwrite the user space with the |
| 2421 |
special bytes ensuring that your program is initializing its |
| 2422 |
dynamic memory appropriately. Also, if you ask for 35 bytes and |
| 2423 |
the library has to give you a block of 64 because of rounding |
| 2424 |
issues, it will overwrite the extra memory with the special byte. |
| 2425 |
You can then check to see if the extra areas have been improperly |
| 2426 |
overwritten by enabling the `check-blank' token. |
| 2427 |
|
| 2428 |
`print-messages' |
| 2429 |
Log any errors and messages to the screen via standard-error. |
| 2430 |
|
| 2431 |
`catch-null' |
| 2432 |
Abort the program immediately if the library fails to get more heap |
| 2433 |
space from the heap allocation routine `mmap' or `sbrk'. |
| 2434 |
|
| 2435 |
`never-reuse' |
| 2436 |
Have the heap never use space that has been used before and freed. |
| 2437 |
*Note Memory Leaks::. _WARNING_: This should be used with caution |
| 2438 |
since you may run out of heap space. |
| 2439 |
|
| 2440 |
`error-dump' |
| 2441 |
Dump core on error and then continue. Later core dumps overwrite |
| 2442 |
earlier ones if the program encounters more than one error. See |
| 2443 |
`error-abort' above. *Note Dumping Core::. |
| 2444 |
|
| 2445 |
_NOTE_: This will only work if your system supports the `fork' |
| 2446 |
system call and the configuration utility was able to fork without |
| 2447 |
going recursive. |
| 2448 |
|
| 2449 |
`error-free-null' |
| 2450 |
By default the library will not generate an error when a program |
| 2451 |
tries to free a NULL pointer. By enabling this token, you can |
| 2452 |
change this behavior so an error is reported. See also the |
| 2453 |
ALLOW_FREE_NULL and ALLOW_FREE_NULL_MESSAGE settings in the |
| 2454 |
`settings.h' file to change the default behavior. |
| 2455 |
|
| 2456 |
|
| 2457 |
|
| 2458 |
File: dmalloc.info, Node: RC File, Prev: Debug Tokens, Up: Dmalloc Program |
| 2459 |
|
| 2460 |
4.5 Format of the Runtime Configuration File |
| 2461 |
============================================ |
| 2462 |
|
| 2463 |
By using a "RC File" (or runtime configuration file) you can alias tags |
| 2464 |
to combinations of debug tokens. *Note Debug Tokens::. |
| 2465 |
|
| 2466 |
_NOTE_: For beginning users, the dmalloc program has a couple of |
| 2467 |
tags built into it so it is not necessary for you to setup a RC file: |
| 2468 |
|
| 2469 |
`runtime' |
| 2470 |
Enables basic runtime tests including fence-post checking, null |
| 2471 |
handling, and logging of any errors. |
| 2472 |
|
| 2473 |
`low' |
| 2474 |
Runtime settings plus minimal checking of heap structures and |
| 2475 |
overwriting of allocated and freed space. |
| 2476 |
|
| 2477 |
`medium' |
| 2478 |
Low settings plus checking of all heap structures on each memory |
| 2479 |
call, always relocates block on realloc, and aborts on errors. |
| 2480 |
You may want to use `-i' option to the dmalloc utility. *Note |
| 2481 |
Dmalloc Program::. |
| 2482 |
|
| 2483 |
`high' |
| 2484 |
Medium settings plus checking of overwritten freed and allocated |
| 2485 |
memory and checking of arguments to a number of common functions. |
| 2486 |
You may want to use `-i' option to the dmalloc utility. *Note |
| 2487 |
Dmalloc Program::. |
| 2488 |
|
| 2489 |
|
| 2490 |
For expert users, a sample `dmallocrc' file has been provided but |
| 2491 |
you are encouraged to roll your own combinations. The name of default |
| 2492 |
rc-file is `$HOME/.dmallocrc'. The `$HOME' environment variable should |
| 2493 |
be set by the system to point to your home-directory. |
| 2494 |
|
| 2495 |
The file should contain lines in the general form of: |
| 2496 |
|
| 2497 |
tag token1, token2, ... |
| 2498 |
|
| 2499 |
`tag' is to be matched with the tag argument passed to the dmalloc |
| 2500 |
program, while `token1, token2, ...' are debug capability tokens. |
| 2501 |
*Note Dmalloc Program::, *Note Debug Tokens::. |
| 2502 |
|
| 2503 |
A line can be finished with a `\' meaning it continues onto the next |
| 2504 |
line. Lines beginning with `#' are treated as comments and are ignored |
| 2505 |
along with empty lines. |
| 2506 |
|
| 2507 |
Here is an example of a `.dmallocrc' file: |
| 2508 |
|
| 2509 |
# |
| 2510 |
# Dmalloc runtime configuration file for the debug malloc library |
| 2511 |
# |
| 2512 |
|
| 2513 |
# no debugging |
| 2514 |
none none |
| 2515 |
|
| 2516 |
# basic debugging |
| 2517 |
debug1 log-stats, log-non-free, check-fence |
| 2518 |
|
| 2519 |
# more logging and some heap checking |
| 2520 |
debug2 log-stats, log-non-free, log-trans, \ |
| 2521 |
check-fence, check-heap, error-abort |
| 2522 |
|
| 2523 |
# good utilities |
| 2524 |
debug3 log-stats, log-non-free, log-trans, \ |
| 2525 |
log-admin, check-fence, check-heap, realloc-copy, \ |
| 2526 |
free-blank, error-abort |
| 2527 |
|
| 2528 |
... |
| 2529 |
|
| 2530 |
For example, with the above file installed, you can type `dmalloc |
| 2531 |
debug1' after setting up your shell alias. *Note Dmalloc Program::. |
| 2532 |
This enables the logging of statistics, the logging of non-freed memory, |
| 2533 |
and the checking of fence-post memory areas. |
| 2534 |
|
| 2535 |
Enter `dmalloc none' to disable all memory debugging features. |
| 2536 |
|
| 2537 |
|
| 2538 |
File: dmalloc.info, Node: Source Code, Next: Troubleshooting, Prev: Dmalloc Program, Up: Top |
| 2539 |
|
| 2540 |
5 Information on the Source Code |
| 2541 |
******************************** |
| 2542 |
|
| 2543 |
* Menu: |
| 2544 |
|
| 2545 |
* Definitions:: Definition of terms and other information. |
| 2546 |
* Compatibility:: General compatibility concerns. |
| 2547 |
* Portability:: Issues important for porting the library. |
| 2548 |
|
| 2549 |
|
| 2550 |
File: dmalloc.info, Node: Definitions, Next: Compatibility, Prev: Source Code, Up: Source Code |
| 2551 |
|
| 2552 |
5.1 Definition of Terms and other Information |
| 2553 |
============================================= |
| 2554 |
|
| 2555 |
Here are a couple definitions and other information for those interested |
| 2556 |
in "picking the brain" of the library. The code is a little ugly here |
| 2557 |
and there and it conforms to the Gray-Watson handbook of coding |
| 2558 |
standards only. |
| 2559 |
|
| 2560 |
"bblock" |
| 2561 |
basic block containing 2 ^ BASIC_BLOCK bytes of info |
| 2562 |
|
| 2563 |
"bblock_adm" |
| 2564 |
administration for a set of basic blocks |
| 2565 |
|
| 2566 |
"dblock" |
| 2567 |
divided block containing some base 2 number of blocks smaller than |
| 2568 |
a basic block. |
| 2569 |
|
| 2570 |
"dblock_adm" |
| 2571 |
administration for a set of divided blocks |
| 2572 |
|
| 2573 |
"chunk" |
| 2574 |
some anonymous amount of memory |
| 2575 |
|
| 2576 |
For more information about administration structures, see the code |
| 2577 |
and comments from `chunk_loc.h'. |
| 2578 |
|
| 2579 |
|
| 2580 |
File: dmalloc.info, Node: Compatibility, Next: Portability, Prev: Definitions, Up: Source Code |
| 2581 |
|
| 2582 |
5.2 General Compatibility Concerns |
| 2583 |
================================== |
| 2584 |
|
| 2585 |
* Realloc() backwards compatibility with being able to realloc from |
| 2586 |
the last freed block is _not_ supported. The author is interested |
| 2587 |
to know who is using this (cough, cough) feature and for what |
| 2588 |
reason. |
| 2589 |
|
| 2590 |
* Realloc() of a NULL pointer is supported in which case the library |
| 2591 |
will just make a call to malloc(). This can be disabled with the |
| 2592 |
help of the `ALLOW_REALLOC_NULL' manual compilation option in the |
| 2593 |
`settings.h' file to adjust the library's default behavior. |
| 2594 |
|
| 2595 |
* Some systems allow free(0) to not be an error for some reason. |
| 2596 |
Since 0 is not a valid address returned by the malloc call, it is |
| 2597 |
debatable that this should be allowed. See `settings.h' for the |
| 2598 |
`ALLOW_FREE_NULL' manual compilation option to adjust the |
| 2599 |
library's default behavior. |
| 2600 |
|
| 2601 |
* Aside from possibly being slower than the system's memory |
| 2602 |
allocation functions, the library should be fully compatible with |
| 2603 |
the standard memory routines. If this is _not_ the case, please |
| 2604 |
bring this to my attention. |
| 2605 |
|
| 2606 |
|
| 2607 |
File: dmalloc.info, Node: Portability, Prev: Compatibility, Up: Source Code |
| 2608 |
|
| 2609 |
5.3 Issues Important for Porting the Library |
| 2610 |
============================================ |
| 2611 |
|
| 2612 |
General portability issues center around: |
| 2613 |
|
| 2614 |
* mmap, sbrk, or compatible function usages. The library does |
| 2615 |
support a preallocated memory chunk heap. See the |
| 2616 |
`INTERNAL_MEMORY_SPACE' define in the `settings.dist' file. |
| 2617 |
|
| 2618 |
* The locating of the caller's address from the dmalloc functions. |
| 2619 |
This is useful in locating problems from dmalloc functions called |
| 2620 |
from C files which did not include `dmalloc.h': C library calls for |
| 2621 |
instance. |
| 2622 |
|
| 2623 |
See `return.h' for the available architecture/compiler |
| 2624 |
combinations. You may want to examine the assembly code from gcc |
| 2625 |
(GNUs superior c-compiler) version 2+ being run on the following |
| 2626 |
code. It should give you a good start on building a hack for your |
| 2627 |
box. |
| 2628 |
|
| 2629 |
static char * x; |
| 2630 |
|
| 2631 |
a() |
| 2632 |
{ |
| 2633 |
x = __builtin_return_address(0); |
| 2634 |
} |
| 2635 |
|
| 2636 |
main() |
| 2637 |
{ |
| 2638 |
a(); |
| 2639 |
} |
| 2640 |
|
| 2641 |
|
| 2642 |
|
| 2643 |
------------------------------------------------------------------------------- |
| 2644 |
|
| 2645 |
6 Some Solutions to Common Problems |
| 2646 |
*********************************** |
| 2647 |
|
| 2648 |
This section provides some answers to some common problems and |
| 2649 |
questions. Please send me mail with any additions to this list - |
| 2650 |
either problems you are still having or tips that you would like to |
| 2651 |
pass on. |
| 2652 |
|
| 2653 |
When diagnosing a problem, if possible, always make sure you are |
| 2654 |
running the most up to date version of Dmalloc available from the home |
| 2655 |
page at URL `http://dmalloc.com/'. Problems are often fixed and a new |
| 2656 |
release can be published before people encounter them. |
| 2657 |
|
| 2658 |
`Why does my program run so slow?' |
| 2659 |
This library has never been (and maybe never will be) optimized for |
| 2660 |
space nor speed. Some of its features make it unable to use some |
| 2661 |
of the organizational methods of other more efficient heap |
| 2662 |
libraries. |
| 2663 |
|
| 2664 |
If you have the `check-heap' token enabled, your program might run |
| 2665 |
slow or seem to hang. This is because by default, the library |
| 2666 |
will run a full check of the heap with every memory allocation or |
| 2667 |
free. You can have the library check itself less frequently by |
| 2668 |
using the `-i' option to the dmalloc utility. *Note Dmalloc |
| 2669 |
Program::. If you are using the `high' token and you need your |
| 2670 |
program to run faster, try the `medium' or `low' tokens which |
| 2671 |
don't check as many heap features and so run faster although they |
| 2672 |
will not catch as many problems. *Note RC File::. |
| 2673 |
|
| 2674 |
`Why was a log-file not produced after I ran my program?' |
| 2675 |
This could be caused by a number of different problems. |
| 2676 |
|
| 2677 |
1. Are you sure you followed all of the items in the "Getting |
| 2678 |
Started" section? Please review them if there is any doubt. |
| 2679 |
*Note Getting Started::. |
| 2680 |
|
| 2681 |
2. Use the `env' or `printenv' commands to make sure that the |
| 2682 |
`DMALLOC_OPTIONS' variable is set in your exported |
| 2683 |
environment. *Note Environment Variable::. |
| 2684 |
|
| 2685 |
3. Make sure that your program has been compiled correctly with |
| 2686 |
the dmalloc library. The `ident' program should show chunk.c |
| 2687 |
and other dmalloc files compiled into your program. You can |
| 2688 |
also do `strings -a your-program | grep chunk.c' and look for |
| 2689 |
something like `$Id: chunk.c,v 1.152 1999/08/25 12:37:01 gray |
| 2690 |
Exp $' with different versions and date information. If this |
| 2691 |
doesn't show up then chances are dmalloc was not linked into |
| 2692 |
your program. |
| 2693 |
|
| 2694 |
4. If your program changes its working directory, it may write |
| 2695 |
the dmalloc log-file somewhere else in the filesystem. You |
| 2696 |
will need to check both where the program was started and to |
| 2697 |
where it might change directory. |
| 2698 |
|
| 2699 |
5. The logfile is only produced when `dmalloc_shutdown()' is |
| 2700 |
called. By default it will be called when `exit()' gets |
| 2701 |
called. If you are running your program and press |
| 2702 |
`Control-C' under Unix the program will stop immediately and |
| 2703 |
`dmalloc_shutdown()' will not get called. You can either |
| 2704 |
setup a signal handler for `SIGINTR' and call exit yourself, |
| 2705 |
or you can enable the `catch-signals' token. *Note Debug |
| 2706 |
Tokens::. |
| 2707 |
|
| 2708 |
6. If your program is segfaulting or otherwise crashing when it |
| 2709 |
exits, the `exit()' routine may not being called. You will |
| 2710 |
have to resolve these issues so the dmalloc library can |
| 2711 |
gracefully exit and write its log file. |
| 2712 |
|
| 2713 |
7. You may want to call `dmalloc_log_stats()' and |
| 2714 |
`dmalloc_log_unfreed()' (or `dmalloc_log_changed()') directly |
| 2715 |
to have the library write its log file. Some system modules |
| 2716 |
may not have shutdown if you call this before `exit()' so |
| 2717 |
extra unfreed memory may be reported. |
| 2718 |
|
| 2719 |
|
| 2720 |
`I don't see any information about my non-freed (leaked) memory?' |
| 2721 |
The library will not (by default) report on "unknown" non-freed |
| 2722 |
memory. Unknown means memory that does not have associated file |
| 2723 |
and line information. |
| 2724 |
|
| 2725 |
This will be necessary if you are _not_ including `dmalloc.h' in |
| 2726 |
all of your C files or if you are interested in tracking leaks in |
| 2727 |
system functions. |
| 2728 |
|
| 2729 |
`Dmalloc is returning the error "malloc library has gone recursive"' |
| 2730 |
This most likely indicates that you are using the Dmalloc library |
| 2731 |
within a threaded application and two threads are trying to use |
| 2732 |
the dmalloc library at once. Please see the section of the manual |
| 2733 |
about threads for more information about properly configuring the |
| 2734 |
library. *Note Using With Threads::. |
| 2735 |
|
| 2736 |
If you are not using threads, then your program could have caught a |
| 2737 |
signal while within Dmalloc, which then in turn called a memory |
| 2738 |
allocation routine. It is unwise to allocate memory on the heap |
| 2739 |
in most signal handlers. Lastly, some functions called by the |
| 2740 |
library may call memory routines that it does not anticipate. If |
| 2741 |
you think this the case, please report the problem and include a |
| 2742 |
stack trace, operating system version/type, and the version of |
| 2743 |
Dmalloc you are using. |
| 2744 |
|
| 2745 |
|
| 2746 |
|
| 2747 |
File: dmalloc.info, Node: Index of Concepts, Prev: Troubleshooting, Up: Top |
| 2748 |
|
| 2749 |
Index of Concepts |
| 2750 |
***************** |
| 2751 |
|
| 2752 |
|