Copyright (C) 1992 - 1995 by Gray Watson.
Gray Watson makes no representations about the suitability of the software described herein for any purpose. It is provided "as is" without express or implied warranty. The name of Gray Watson cannot be used in advertising or publicity pertaining to distribution of the document or software without specific, written prior permission.
Permission to distribute this software for any purpose without fee is hereby granted, provided that the above copyright notice, all documentation files associated with the software, and this permission chapter appear in all copies.
Please see the following sections for usage permissions.
Permission to use, copy, and modify this software for any academic or non-commercial purpose without fee is hereby granted.
Although only commercial users are required to license the software, all registrations are greatly appreciated. Licensees get a registration file for the software (which cannot be distributed), a letter documenting their registered status, as well as product support and notification of free-upgrades. For more information about registration see the following section. See section Commercial License.
In order to fund maintenance and continued development of this product, the requirement has been added that commercial entities license the software for a nominal fee. There is a thirty (30) day free evaluation period but if your organization uses the software after this time period expires, please consider purchasing a registered copy. This allows me to provide better support as well as bug fixes and feature updates on a more frequent basis. Although not required, academic or non-commercial user registration is greatly appreciated.
A licensed copy of the software is available for US$35. Commercial entities should purchase one license per workstation, or one per dmalloc user, whichever is the smaller number. Licensees get a registration file for the software (which cannot be distributed), a letter documenting their registered status, as well as product support and notification of free-upgrades.
For "site" licenses (at significant discount) or any other reasonable agreements, please contact me directly. It should be noted that a "site" can be defined as anything you'd like. It can be a physical location (a room, building, etc.), an organizational grouping (a workgroups, department, etc.) or any other logical grouping ("the folks working on the widget project", etc.).
A printed and bound copy of the manual is available for US$15. A copy of the software on a Unix tar floppy is available for US$15. International shipping costs outside of the US or Canada, please add US$5 for the extra postal charges.
Please include the following registration information with your check made out to "Gray Watson". Money orders are also accepted. Purchase orders are as well, although amounts less than US$50 are discouraged.
Send it along with any other correspondence that cannot be sent via email to:
Gray Watson 826 Savannah Ave. Pittsburgh, PA 15221-3446 USA
Any program can be divided into 2 logical parts: text and data. Text is the actual program code in machine-readable format and data is the information that the text operates on when it is executing. The data, in turn, can be divided into 3 logical parts according to where it is stored: static, stack, and heap.
Static data is the information whose storage space is compiled into the program.
/* global variables are allocated as static data */
int numbers[10];
main()
{
...
}
Stack data is data allocated at run-time to hold information used inside of functions. This data is managed by the system in the space called stack space.
void foo()
{
/* this local variable is stored on the stack */
float total;
...
}
main()
{
foo();
}
Heap data is also allocated at run-time and provides a programmer with dynamic memory capabilities.
main()
{
/* the address is stored on the stack */
char * string;
...
/*
* Allocate a string of 10 bytes on the heap. Store the
* address in string which is on the stack.
*/
string = (char *)malloc(10);
...
/* de-allocate the heap memory now that we're done with it */
(void)free(string);
...
}
It is the heap data that is managed by this library.
Although the above is an example of how to use the malloc and free commands, it is not a good example of why using the heap for run-time storage is useful.
Consider this: You write a program that reads a file into memory, processes it, and displays results. You would like to handle files with arbitrary size (from 10 bytes to 1.2 megabytes and more). One problem, however, is that the entire file must be in memory at one time to do the calculations. You don't want to have to allocate 1.2 megabytes when you might only be reading in a 10 byte file because it is wasteful of system resources. Also, you are worried that your program might have to handle files of more than 1.2 megabytes.
A solution: first checkout the file's size and then, using the heap-allocation routines, get enough storage to read the entire file into memory. The program will only be using the system resources necessary for the job and you will be guaranteed that your program can handle any sized file.
All malloc libraries support 4 basic memory allocation commands. These
include malloc, calloc, realloc, and free. For
more information about their capabilities, check your system's manual
pages -- in unix, do a man 3 malloc.
Usage: pnt = (type *)malloc(size)
The malloc routine is the basic memory allocation routine. It allocates
an area of size bytes. It will return a pointer to the space
requested.
Usage: pnt = (type *)calloc(number, size)
The calloc routine allocates a certain number of items, each of
size bytes, and returns a pointer to the space. It is
appropriate to pass in a sizeof(type) value as the size argument.
Also, calloc nulls the space that it returns, assuring that the memory is all zeros.
Usage: new_pnt = (type *)realloc(old_pnt, new_size)
The realloc function expands or shrinks the memory allocation in
old_pnt to new_size number of bytes. Realloc copies as
much of the information from old_pnt as it can into the
new_pnt space it returns, up to new_size bytes.
Usage: free(pnt)
The free routine releases allocation in pnt which was returned by
malloc, calloc, or realloc back to the heap. This allows other parts of
the program to re-use memory that is not needed anymore. It guarantees
that the process does not grow too big and swallow a large portion of
the system resources.
NOTE: the returned address from the memory allocation/reallocation functions should always be cast to the appropriate pointer type for the variable being assigned.
WARNING: there is a quite common myth that all of the space that
is returned by malloc libraries has already been cleared. Only
the calloc routine will zero the memory space it returns.
The debugging features that are available in this debug malloc library can be divided into a couple basic classifications:
If any of the above debugging features detect an error, the library will try to recover. If logging is enabled then an error will be logged with as much information as possible.
The error messages that the library displays are designed to give the most information for developers. If the error message is not understood, then it is most likely just trying to indicate that a part of the heap has been corrupted.
The library can be configured to quit immediately when an error is detected and to dump a core file or memory-image. This can be examined with a debugger to determine the source of the problem. The library can either stop after dumping core or continue running.
NOTE: do not be surprised if the library catches problems with your system's routines. It took me hours to finally come to the conclusion that the localtime call, included in SunOS release 4.1, overwrites one of its fence-post markers.
To configure, compile, and install the library, follow these steps carefully.
tr '[a-z]' '[A-Z]'. Since configure uses tr
often, you may need to either get GNU's tr (in their textutils package)
or generate the `Makefile' and `conf.h' files by hand.
DMALLOC_SIZE variable gets auto-configured in
`dmalloc.h.2' but it may not generate correct settings for all
systems. You may have to alter the definitions in this file to get
things to stop complaining when you go to compile about the size
arguments to malloc routines. Comments on this please.
... to `varargs.h' and
va_alist
void * references to char *.
foo(char * var) declarations.
See the Getting Started section to get up and running with the library. See section Getting Started with the Library.
NOTE: This library has never been (and maybe never will be) optimized for space nor speed. in fact, some of its features make it unable to use some of the organizational methods of other more efficient heap libraries.
This section should give you a quick idea on how to get going. Basically, you need to do the following things to make use of the library:
on_exit or atexit
functions. If so, then the dmalloc library should be able to
automatically call dmalloc_shutdown when exit is called.
This causes the memory statistics and unfreed information to be dumped
to the log file. However, if your system has neither, you will need to
call dmalloc_shutdown yourself before your program exits.
alias dmalloc 'eval `\dmalloc -C \!*`'bash basb and zsh users should add the following to their `.bashrc' or `.zshrc' respectively file (notice the -b option for bourne shell output):
function dmalloc { eval `command dmalloc -b $*` }
By including `dmalloc.h' in your C files, your calls to calloc, free, malloc, or realloc are replaced with calls to _calloc_leap, _free_leap, _malloc_leap, and _realloc_leap. Additionally the library replaces calls to xcalloc, xfree, xmalloc, xrealloc, and xstrdup with _leap calls.
WARNING: You should be sure to have `dmalloc.h' included at the end of your include file list because dmalloc uses macros and may try to change declarations of the malloc functions if they come after it.
These leap macros use the c-preprocessor __FILE__ and
__LINE__ macros which get replaced at compilation time with the
current file and line-number of the source code in question. The leap
routines take this information and pass it on to the library making it
able to produce verbose reports on memory problems.
not freed: '0x38410' (22 bytes) from 'dmalloc_t.c:92'
This line from a log file shows that memory was not freed from file `dmalloc_t.c' line 92. See section Tracking down Non-Freed Memory.
Along with the above leap functionality, `dmalloc.h' also adds the following macros which take care of all the type-casting and make the code look much cleaner (IMHO).
Usage: long_pnt = ALLOC(long, 30). This means allocate space
for 30 longs.
Usage: char_pnt = MALLOC(1000). This is like ALLOC but for
characters only. It means allocate space for 1000 characters.
Usage: info_pnt = CALLOC(struct info_st, 100). This means
allocate space for 100 info_st structures and zero them all.
NOTE: the arguments for the CALLOC macro are sort of reversed from calloc(unsigned int count, unsigned int size).
Usage: long_pnt = REALLOC(old_pnt, long, 10). This takes
old_pnt and and changes its size to accommodate 10 longs.
NOTE: the arguments for the REALLOC macro are different from the realloc function.
Usage: char_pnt = REMALLOC(char_pnt, 100). This is like REALLOC
but for characters only. It takes char_pnt and changes its size to 100
characters.
Usage: FREE(pnt). This frees memory pointers.
Even though the allocation macros can provide file/line information for some of your code, there are still modules which either you can't include `dmalloc.h' (such as library routines) or you just don't want to. You can still get information about the routines that call dmalloc function from the return-address information. To accomplish this, you must be using this library on one of the supported architecture/compilers. See section Portability Issues.
The library attempts to use some assembly hacks to get the the return-address or the address of the line that called the dmalloc function. If you have the `log-unknown' token enabled and you run your program, you might see the following non-freed memory messages.
not freed: '0x38410' (22 bytes) from 'ra=0xdd2c' not freed: '0x38600' (10232 bytes) from 'ra=0x10234d' not freed: '0x38220' (137 bytes) from 'ra=0x82cc'
With the help of a debugger, these return-addresses (or ra) can then be identified. I've provided a `ra_info.pl' perl script in the `contrib/' directory with the dmalloc sources which seems to work well with gdb. You can also use the manual methods below for gdb.
(gdb) x 0x10234d 0x10234d <_findbuf+132>: 0x7fffceb7 (gdb) info line *(0x82cc) Line 1092 of argv.c starts at pc 0x7540 and ends at 0x7550.
In the above example, gdb was used to find that the two non-freed memory
pointers were allocated in _findbuf() and in file argv.c line
1092 respectively. The `x address' (for examine) can always be
used on the return-addresses but the `info line *(address)' will
only work if that file was compiled using the -g option and has not been
stripped. This limitation may not be true in later versions of gdb.
One potential problem with the library and its multitude of checks and
diagnoses is that they only get performed when a dmalloc function is
called. One solution this is to include `dmalloc.h' and compile
your source code with the DMALLOC_FUNC_CHECK flag defined and
enable the check-funcs token. See section Debugging Tokens.
cc -DDMALLOC_FUNC_CHECK file.c
NOTE: Once you have compiled your source with DMALLOC_FUNC_CHECK enabled, you will have to recompile with it off to disconnect the library. See section Disabling the Library.
WARNING: You should be sure to have `dmalloc.h' included at the end of your include file list because dmalloc uses macros and may try to change declarations of the checked functions if they come after it.
When this is defined dmalloc will override a number of functions and
will insert a routine which knows how to check its own arguments and
then call the real function. Dmalloc can check such functions as
bcopy, index, strcat, and strcasecmp. For
the full list see the end of `dmalloc.h'.
When you call strlen, for instance, dmalloc will make sure the
string argument's fence-post areas have not been overwritten, its file
and line number locations are good, etc. With bcopy, dmalloc
will make sure that the destination string has enough space to store the
number of bytes specified.
For all of the arguments checked, if the pointer is not in the heap then it is ignored since dmalloc does not know anything about it.
The library has a number of variables that are not a standard part of most malloc libraries:
char * dmalloc_logpath
int dmalloc_errno
dmalloc_strerror()
(see below) to get a string version of the error. It will have a value
of zero if the library has not detected any problems.
int dmalloc_address
int dmalloc_address_count
dmalloc_error().
This works well in conjunction with the STORE_SEEN_COUNT option.
See section Tracking down Non-Freed Memory.
Additionally the library provides a number of non-standard malloc routines:
This function shuts the library down and logs the final statistics and
information especially the non-freed memory pointers. The library has
code to support auto-shutdown if your system has on_exit() or
atexit() calls (see `conf.h'). If you do not have these
routines, then dmalloc_shutdown should be called right before
exit() or as the last function in main().
main()
{
...
dmalloc_shutdown();
exit(0);
}
This routine logs to the logfile (if it is enabled) a graphical representation of the current heap space.
This routine outputs the current dmalloc statistics to the log file.
This function dumps the unfreed-memory information to the log file. This is also useful to dump the currently allocated points to the log file to be diff'ed against another dump later on.
This function verifies individual memory pointers that are suspect of memory problems. To check the entire heap pass in a NULL or 0 pointer. The routine returns DMALLOC_VERIFY_ERROR or DMALLOC_VERIFY_NOERROR.
NOTE: `dmalloc_verify()' can only check the heap with the functions that have been enabled. For example, if fence-post checking is not enabled, `dmalloc_verify()' cannot check the fence-post areas in the heap.
This routine overrides the debug setting from the environment variable
and sets the library debugging features explicitly. For instance, if
debugging should never be enabled for a program, a call to
dmalloc_debug(0) as the first call in main() will disable
all the memory debugging from that point on.
One problem however is that some systems make calls to memory allocation
functions before main() is reached therefore before
dmalloc_debug() can be called meaning some debugging information
may be generated regardless.
This routine returns the current debug value from the environment variable. This allows you to save a copy of the debug dmalloc settings to be changed and then restored later.
This function returns the size of a pnt's allocation as well as the file and line or the return-address from where it was allocated. It will return NOERROR or ERROR depending on whether pnt is good or not.
NOTE: This function is certainly not provided by most if not all other malloc libraries.
This function returns the string representation of the error value in errnum (which probably should be dmalloc_errno). This allows the logging of more verbose memory error messages.
You can also display the string representation of an error value by a call to the `dmalloc' program with a `-e #' option. See section Dmalloc Utility Program.
For those people using the C++ language, some special things need to be
done to get the library to work. The problem exists with the fact that
the dynamic memory routines in C++ are new() and delete()
as opposed to malloc() and free().
The file `dmalloc.cc' is provided in the distribution which
effectively redirects new to the more familiar malloc and
delete to the more familiar free. Compile and link this
file in with the C++ program you want to debug.
NOTE: The author is not a C++ hacker so feedback in the form of other hints and ideas for C++ users would be much appreciated.
When you are finished with the development and debugging sessions, you may want to disable the dmalloc library and put in its place either the system's memory-allocation routines, gnu-malloc, or maybe your own. Attempts have been made to make this a reasonably painless process. The ease of the extraction depends heavily on how many of the library's features your made use of during your coding.
Reasonable suggestions are welcome as to how to improve this process while maintaining the effectiveness of the debugging.
DMALLOC_DISABLE. This will cause the dmalloc leap
macros to not be applied. See section Allocation Macros.
cc -g -DDMALLOC_DISABLE main.c
DMALLOC_FUNC_CHECK
defined then you must first recompile all those modules without the flag
enabled.
DMALLOC_DISABLED
defined then you need to link your program with the
`libdmalloclp.a' library.
cc main.o -L/usr/local/lib -ldmalloclp -lgmallocIf you have disabled dmalloc with the
DMALLOC_DISABLED flag or
never included `dmalloc.h' in any of your C files, then you will
not need the `libdmalloclp.a' library.
cc -g main.o -L/usr/local/lib -lgmallocIf you get unresolved references like
_malloc_leap or
_dmalloc_bcopy then something was not disabled as it should have
been.
Here are a number of possible scenarios for using the dmalloc library to track down problems with your program.
You should first enable a logfile filename (I use `dmalloc') and turn on a set of debug features. You can use dmalloc -l dmalloc low to accomplish this. If you are interested in having the error messages printed to your terminal as well, enable the `print-error' token by typing dmalloc -p print-error afterwards. See section Dmalloc Utility Program.
Now you can enter your debugger (I use the excellent GNU debugger
gdb), and put a break-point in dmalloc_error() which is the
internal error routine for the library. When your program is run, it
will stop there if a memory problem is detected.
If your program stops at the dmalloc_error() routine then one of
a number of problems could be happening. Incorrect arguments could have
been passed to a malloc call: asking for negative number of bytes,
trying to realloc a non-heap pointer, etc.. There also could be a
problem with the system's allocations: you've run out of memory, some
other function in your program is using sbrk, etc. However, it
is most likely that some code that has been executed was naughty.
To get more information about the problem, first print via the debugger the dmalloc_errno variable to get the library's internal error code. You can suspend your debugger and run `dmalloc -e value-returned-from-print' to get an english translation of the error. A number of the error messages are designed to indicate specific problems with the library administrative structures and may not be user-friendly.
If the problem was due to the arguments or system allocations then the
source of the problem has been found. However, if some code did
something wrong, you may have some more work to do to locate the actual
problem. The check-heap token should be enabled and the interval
setting disabled or set to a low value so that the library can find the
problem as close as possible to its source. The code that was execute
right before the library halted, can then be examined closely for
irregularities. See section Debugging Tokens and See section Dmalloc Utility Program.
You may also want to put calls to dmalloc_verify(0) in your code
before the section which generated the error. This should locate the
problem faster by checking the library's structures at that point.
See section Extension Routines.
So you've run your program, examined the log-file and discovered (to your horror) some un-freed memory. Memory leaks can become large problems since even the smallest and most insignificant leak can starve the program given the right circumstances.
not freed: '0x45008' (12 bytes) from 'ra=0x1f8f4' not freed: '0x45028' (12 bytes) from 'unknown' not freed: '0x45048' (10 bytes) from 'argv.c:1077' known memory not freed: 1 pointer, 10 bytes unknown memory not freed: 2 pointers, 24 bytes
Above you will see a sample of some non-freed memory messages from the logfile. In the first line the `0x45008' is the pointer that was not freed, the `12 bytes' is the size of the unfreed block, and the `ra=0x1f8f4' or return-address shows where the allocation originated from. See section Return Address Information.
The systems which cannot provide return-address information show `unknown' instead, as in the 2nd line in the sample above.
The `argv.c:1077' information from the 3rd line shows the file and line number which allocated the memory which was not freed. This information comes from the calls from C files which included `dmalloc.h'. See section Allocation Macros.
At the bottom of the sample it totals the memory for you and breaks it down to known memory (those calls which supplied the file/line information) and unknown (the rest).
Often, you may allocate memory in via strdup() or another
routine, so the logfile listing where in the strdup routine the
memory was allocated does not help locate the true source of the memory
leak -- the routine that called strdup. Without a mechanism to
trace the calling stack, there is no way for the library to see who the
caller of the caller (so to speak) was.
However, there is a way to track down unfreed memory in this
circumstance. You need to compile the library with
STORE_SEEN_COUNT defined in `conf.h'. The library will then
record how many times a pointer has been allocated or freed. It will
display the unfreed memory as:
not freed: '0x45008|s3' (12 bytes) from 'ra=0x1f8f4'
The STORE_SEEN_COUNT option adds a `|s#' qualifier to the
address. This means that the address in question was seen `#' many
times. In the above example, the address `0x45008' was seen
`3' times. The last time it was allocated, it was not freed.
How can a pointer be "seen" 3 times? Let say you strdup a
string of 12 characters and get address `0x45008' -- this is #1
time the pointer is seen. You then free the pointer (seen #2) but later
strdup another 12 character string and it gets the `0x45008'
address from the free list (seen #3).
So to find out who is allocating this particular 12 bytes the 3rd time,
try `dmalloc -a 0x45008:3'. The library will stop the program the
third time it sees the `0x45008' address. You then enter a
debugger and put a break point at dmalloc_error. Run the program
and when the breakpoint is reached you can examine the stack frame to
determine who called strdup to allocate the pointer.
To not bother with the STORE_SEEN_COUNT feature, you can also run
your program with the `never-reuse' token enabled. This token will
cause the library to never reuse memory that has been freed. Unique
addresses are always generated. This should be used with caution since
it may cause your program to run out of memory.
For a definition of fence-posts please see the Features section. See section Features of the Library.
If you have encountered a fence-post memory error, the logfile should be able to tell you the offending address.
free: failed UNDER picket-fence magic-number checking: pointer '0x1d008' from 'dmalloc_t.c:427' Dump of proper fence-bottom bytes: '\e\253\300\300\e\253\300\300' Dump of '0x1d008'-8: '\e\253\300\300WOW!\003\001pforger\023\001\123'
The above sample shows that the pointer `0x1d008' has had its lower fence-post area overwritten. This means that the code wrote below the bottom of the address or above the address right below this one. In the sample, the string that did it was `WOW!'.
The library first shows you what the proper fence-post information should look like, and then shows what the pointer's bad information was. If it cannot print the character, it will display the value as `\ddd' where ddd are three octal digits.
By enabling the check-heap debugging token and assigning the
interval setting to a low number, you should be able to locate
approximately when this problem happened. See section Debugging Tokens and
See section Dmalloc Utility Program.
An environment variable is a variable that is part of the user's working environment and is shared by all the programs. The `DMALLOC_OPTIONS' variable is used by the dmalloc library to enable or disable the memory debugging features, at runtime. It can be set either by hand or with the help of the dmalloc program. See section Dmalloc Utility Program.
To set it by hand, C shell (csh or tcsh) users need to invoke:
setenv DMALLOC_OPTIONS value
Bourne shell (sh, bash, ksh, or zsh) users should use:
DMALLOC_OPTIONS=value export DMALLOC_OPTIONS
The value in the above examples is a comma separated list of tokens each having a corresponding value. The tokens are described below:
debug
log
%d in it (for instance
`logfile.%d'). This will be replaced with the pid of the running
process (for instance `logfile.2451').
WARNING: it is easy to core dump any program with dmalloc, if
you send in a format with arguments other than the one %d.
addr
STORE_SEEN_COUNT option.
See section Tracking down Non-Freed Memory.
NOTE: dmalloc will also log all activity on this address along
with a count.
inter
start
Some examples are:
# turn on transaction and stats logging and set 'malloc' as the log-file setenv DMALLOC_OPTIONS log-trans,log-stats,log=malloc # enable debug flags 0x1f as well as heap-checking and set the interval # to be 100 setenv DMALLOC_OPTIONS debug=0x1f,check-heap,inter=100 # enable 'malloc' as the log-file, watch for address '0x1234', and start # checking when we see file.c line 123 setenv DMALLOC_OPTIONS log=malloc,addr=0x1234,start=file.c:123
The below tokens and their corresponding descriptions are for the setting of the debug library setting in the environment variable. See section Environment Variable Features. They should be specified in the user's `.dmallocrc' file. See section Run-Time Configuration File.
Each token, when specified, enables a specific debugging feature. For instance, if you have the log-stats token enabled, the library will log general statistics to the logfile.
To get this information on the fly, use `dmalloc -DV'. This will print out the Debug tokens in Very-verbose mode. See section Dmalloc Utility Program.
none
log-stats
log-non-free
log-thread-id
log-trans
log-stamp
log-admin
log-blocks
log-unknown
log-bad-space
log-nonfree-space
log-elapsed-time
log-current-time
check-fence
check-heap
check-lists
check-blank
check-funcs
realloc-copy
free-blank
error-abort
error-dump below.
alloc-blank
heap-check-map
print-error
catch-null
never-reuse
allow-nonlinear
sbrk
directly. This is now enabled by default since an increasing number of
operating system functions seem to be doing this -- one example is the
pthreads package.
WARNING: This should be used with caution since it may hide
certain heap problems.
allow-zero
error-dump
error-abort above.
NOTE: This will only work if your system supports the fork
system call.
By using a RC File (or run-time configuration file) you can alias tags to combinations of debug tokens. See section Debugging Tokens.
NOTE: For beginning users, the dmalloc program has a couple of tags built into it so it is not necessary for you to setup a RC file:
runtime
low
medium
high
all
For expert users, a sample `dmallocrc' file has been provided but you are encouraged to roll your own combinations. The name of default rc-file is `$HOME/.dmallocrc'. The `$HOME' environment variable should be set by the system to point to your home-directory.
The file should contain lines in the general form of:
tag token1, token2, ...
`tag' is to be matched with the tag argument passed to the dmalloc program, while `token1, token2, ...' are debug capability tokens. See section Dmalloc Utility Program and section Debugging Tokens.
A line can be finished with a `\' meaning it continues onto the next line. Lines beginning with `#' are treated as comments and are ignored along with empty lines.
Here is an example of a `.dmallocrc' file:
#
# Dmalloc run-time configuration file for the debug malloc library
#
# no debugging
none none
# basic debugging
debug1 log-stats, log-non-free, check-fence
# more logging and some heap checking
debug2 log-stats, log-non-free, log-trans, \
check-fence, check-heap, check-lists, error-abort
# good utilities
debug3 log-stats, log-non-free, log-trans, \
log-admin, check-fence, check-heap, check-lists, realloc-copy, \
free-blank, error-abort
...
For example, with the above file installed, you can type dmalloc
debug1 after setting up your shell alias. See section Dmalloc Utility Program.
This enables the logging of statistics, the logging of non-freed memory,
and the checking of fence-post memory areas.
Enter dmalloc none to disable all memory debugging features.
The dmalloc program is designed to assist in the setting of the
environment variable `DMALLOC_OPTIONS'. See section Environment Variable Features. It is designed to print the shell commands necessary to make
the appropriate changes to the environment. Unfortunately, it cannot
make the changes on its own so the output from dmalloc should be sent
through the eval shell command which will do the commands.
With shells that have aliasing or macro capabilities: csh, bash, ksh, tcsh, zsh, etc., setting up an alias to dmalloc to do the eval call is recommended. Csh/tcsh users (for example) should put the following in their `.cshrc' file:
alias dmalloc 'eval `\dmalloc -C \!*`'
Zsh users on the other hand should put the following in their `.zshrc' file:
dmalloc() { eval `command dmalloc -b $*` }
This allows the user to execute the dmalloc command as `dmalloc arguments'.
The most basic usage for the program is `dmalloc [-bC] tag'. The
`-b' or `-C' (either but not both flags used at a time) are
for generating Bourne or C shell type commands respectively. dmalloc
will try and use the SHELL environment variable to determine
whether bourne or C shell commands should be generated but you may want
to explicitly specify the correct flag.
The `tag' argument to dmalloc should match a line from the user's run-time configuration file or should be one of the built-in tags. See section Run-Time Configuration File. If no tag is specified and no other option-commands used, dmalloc will display the current settings of the environment variable. It is useful to specify one of the verbose options when doing this.
To find out the usage for the debug malloc program try `dmalloc --usage-long'. The standardized usage message that will be displayed is one of the many features of the argv library included with this package. It is available via ftp from `ftp.letters.com' in the `/src/argv' directory. See `argv.info' there for more information.
Here is a detailed list of the flags that can passed to dmalloc:
-a address
-b
-C
-c
-d bitmask
-D
-e errno
-f filename
-i number
-k
-l filename
-L
-m token(s)
-n
-p token(s)
-r
-s number
-S
-t
-v
If no arguments are specified, dmalloc dumps out the current settings that you have for the environment variable. For example:
Debug-Flags '0x40005c7' (runtime) Address 0x1f008, count = 3 Interval 100 Logpath 'malloc' Start-File not-set
With a -v option and no arguments, dmalloc dumps out the current settings in a verbose manner. For example:
Debug-Flags '0x40005c7' (runtime) log-stats, log-non-free, log-blocks, log-unknown, log-bad-space, check-fence, catch-null Address 0x1f008, count = 10 Interval 100 Logpath 'malloc' Start-File not-set
Here are some examples of dmalloc usage:
# start tough debugging, check the heap every 100 times, # send the log information to file 'dmalloc' dmalloc high -i 100 -l dmalloc # find out what error code 20 is (from the logfile) dmalloc -e 20 # cause the library to halt itself when it sees the address 0x34238 # for the 6th time. dmalloc -a 0x34238:6 # return to the normal 'runtime' settings and clear out all # other settings dmalloc -c runtime # enable basic 'low' settings plus (-p) the logging of # transactions (log-trans) to file 'dmalloc' dmalloc low -p log-trans -l dmalloc # print out the current settings with Very-verbose output dmalloc -V # list the available debug malloc tokens with Very-verbose output dmalloc -DV # list the available tags from the rc file with verbose output dmalloc -tv
Here are a couple definitions and other information for those interested in "picking the brain" of the library. The code is a little ugly here and there and it conforms to the Gray-Watson handbook of coding standards only.
For more information about administration structures, see the code and comments from `chunk_loc.h'.
General portability issues center around:
static char * x;
a()
{
x = __builtin_return_address(0);
}
main()
{
a();
}
The author would like to bring the following organizations to your attention. If you would like any more information about the below, please mail to the supplied addresses or drop the author a line with any questions.
This document was generated on 11 April 1997 using the texi2html translator version 1.51.