4.4 Description of the Debugging Tokens

The below tokens and their corresponding descriptions are for the setting of the debug library setting in the environment variable. See section Environment Variable Name and Features. They should be specified in the user's `.dmallocrc' file. See section Format of the Runtime 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

No debugging functionality

log-stats

Log general statistics when dmalloc_shutdown or dmalloc_log_stats is called.

log-non-free

Log non-freed memory pointers when dmalloc_shutdown or dmalloc_log_unfreed is called.

log-known

Log only known memory pointers that have not been freed. Pointers which do not have file/line or return-address information will not be logged.

log-trans

Log general memory transactions (quite verbose).

log-admin

Log administrative information (quite verbose).

log-bad-space

Log actual bytes in and around bad pointers.

log-nonfree-space

Log actual bytes in non-freed pointers.

log-elapsed-time

Log elapsed-time for allocated pointers (see `conf.h').

log-current-time

Log current-time for allocated pointers (see `conf.h').

check-fence

Check fence-post memory areas.

check-heap

Verify heap administrative structure.

check-blank

Check to see if space that was blanked when a pointer was allocated or when it was freed has been overwritten. If this is enabled then it will enable free-blank and alloc-blank automatically.

check-funcs

Check the arguments of some functions (mostly string operations) looking for bad pointers.

check-shutdown

Check all of the pointers in the heap when the program exits.

catch-signals

Shutdown the library automatically on SIGHUP, SIGINT, or SIGTERM. This will cause the library to dump its statistics (if requested) when you press control-c on the program (for example).

realloc-copy

Always copy data to a new pointer when realloc.

free-blank

Write special "dmalloc-free" byte (hexadecimal 0xdf, octal 0337, decimal 223) into space when it is freed. You can set this to be something else in the `settings.dist' file. This ensures that your program is not using memory after it has been freed. You can check to see if areas have been improperly overwritten with the check-blank token. If the free space has been overwritten, then ERROR_FREE_OVERWRITTEN is triggered. See section Description of the Internal Error Codes.

error-abort

Abort the program (and dump core) on errors. See error-dump below. See section Generating a Core File on Errors.

alloc-blank

Write special "dmalloc-alloc" byte (hexadecimal 0xda, octal 0332, decimal 218) into space when it is allocated. You can set this to be something else in the `settings.dist' file. If you are not using calloc this will overwrite the user space with the special bytes ensuring that your program is initializing its dynamic memory appropriately. Also, if you ask for 35 bytes and the library has to give you a block of 64 because of rounding issues, it will overwrite the extra memory with the special byte. You can then check to see if the extra areas have been improperly overwritten by enabling the check-blank token.

print-messages

Log any errors and messages to the screen via standard-error.

catch-null

Abort the program immediately if the library fails to get more heap space from the heap allocation routine mmap or sbrk.

never-reuse

Have the heap never use space that has been used before and freed. See section Tracking Down Non-Freed Memory. WARNING: This should be used with caution since you may run out of heap space.

error-dump

Dump core on error and then continue. Later core dumps overwrite earlier ones if the program encounters more than one error. See error-abort above. See section Generating a Core File on Errors.

NOTE: This will only work if your system supports the fork system call and the configuration utility was able to fork without going recursive.

error-free-null

By default the library will not generate an error when a program tries to free a NULL pointer. By enabling this token, you can change this behavior so an error is reported. See also the ALLOW_FREE_NULL and ALLOW_FREE_NULL_MESSAGE settings in the `settings.h' file to change the default behavior.

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.