4.3 Environment Variable Name and Features

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. NOTE: you can also use the dmalloc_debug_setup function to set the option string. 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, Bourne shell (sh, bash, ksh, or zsh) users should use:

DMALLOC_OPTIONS=value
export DMALLOC_OPTIONS

C shell (csh or tcsh) users need to invoke:

setenv DMALLOC_OPTIONS value

The value in the above examples is a comma separated list of tokens each having a corresponding value. The tokens are described below:

debug

This should be set to a value in hexadecimal which corresponds to the functionality token values added together. See section Description of the Debugging Tokens. For instance, if the user wanted to enable the logging of memory transactions (value `0x008') and wanted to check fence-post memory (value `0x400') then `debug' should be set to `0x408' (`0x008' + `0x400').

NOTE: You don't have to worry about remembering all the hex values of the tokens because the dmalloc program automates the setting of this variable especially.

NOTE: You can also specify the debug tokens directly, separated by commas. See section Description of the Debugging Tokens. If `debug' and the tokens are both used, the token values will be added to the debug value.

lockon

Set this to a number which is the "lock-on" period. This dictates with the threaded version of the library to not initialize or lock the mutex lock around the library until after a certain number of allocation calls have been made. See the "Using With Threads" section for more information about the operation of the library with threads. See section Using the Library with a Thread Package.

log

Set this to a filename so that if `debug' has logging enabled, the library can log transactions, administration information, and/or errors to the file so memory problems and usage can be tracked.

To get different logfiles for different processes, you can assign `log' to a string with %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

When this is set to a hex address (taken from the dmalloc log-file for instance) dmalloc will abort when it finds itself either allocating or freeing that address.

The address can also have an `:number' argument. For instance, if it was set it to `0x3e45:10', the library will kill itself the 10th time it sees address `0x3e45'. By setting the number argument to 0, the program will never stop when it sees the address. This is useful for logging all activity on the address and makes it easier to track down specific addresses not being freed.

This works well in conjunction with the 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

By setting this to a number X, dmalloc will only check the heap every X times. This means a number of debugging features can be enabled while still running the program within a finite amount of time.

A setting of `100' works well with reasonably memory intensive programs. This of course means that the library will not catch errors exactly when they happen but possibly 100 library calls later.

start

Set this to a number X and dmalloc will begin checking the heap after X times. This means the intensive debugging can be started after a certain point in a program.

`start' also has the format `file:line'. For instance, if it is set to `dmalloc_t.c:126' dmalloc will start checking the heap after it sees a dmalloc call from the `dmalloc_t.c' file, line number 126. If you use `dmalloc_t.c:0', with a 0 line number, then dmalloc will start checking the heap after it sees a call from anywhere in the `dmalloc_t.c' file.

This allows the intensive debugging to be started after a certain routine or file has been reached in the program.

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

This document was generated by Gray Watson on May, 16 2007 using texi2html 1.76.

This work is licensed by Gray Watson under the Creative Commons Attribution-Share Alike 3.0 License.
This page should be W3C Valid XHTML and should work with most browsers.