2.4 General Features of the Library

The debugging features that are available in this debug malloc library can be divided into a couple basic classifications:

file and line number information

One of the nice things about a good debugger is its ability to provide the file and line number of an offending piece of code. This library attempts to give this functionality with the help of cpp, the C preprocessor. See section Macros Providing File and Line Information.

return-address information

To debug calls to the library from external sources (i.e. those files that could not use the allocation macros), some facilities have been provided to supply the caller's address. This address, with the help of a debugger, can help you locate the source of a problem. See section Getting Caller Address Information.

fence-post (i.e. bounds) checking

Fence-post memory is the area immediately above or below memory allocations. It is all too easy to write code that accesses above or below an allocation - especially when dealing with arrays or strings. The library can write special values in the areas around every allocation so it will notice when these areas have been overwritten. See section Diagnosing Fence-Post Overwritten Memory.

NOTE: The library cannot notice when the program reads from these areas, only when it writes values. Also, fence-post checking will increase the amount of memory the program allocates.

heap-constancy verification

The administration of the library is reasonably complex. If any of the heap-maintenance information is corrupted, the program will either crash or give unpredictable results.

By enabling heap-consistency checking, the library will run through its administrative structures to make sure all is in order. This will mean that problems will be caught faster and diagnosed better.

The drawback of this is, of course, that the library often takes quite a long time to do this. It is suitable to enable this only during development and debugging sessions.

NOTE: the heap checking routines cannot guarantee that the tests will not cause a segmentation-fault if the heap administration structures are properly (or improperly if you will) overwritten. In other words, the tests will verify that everything is okay but may not inform the user of problems in a graceful manner.

logging statistics

One of the reasons why the debug malloc library was initially developed was to track programs' memory usage - specifically to locate memory leaks which are places where allocated memory is never getting freed. See section Tracking Down Non-Freed Memory.

The library has a number of logging capabilities that can track un-freed memory pointers as well as runtime memory usage, memory transactions, administrative actions, and final statistics.

examining freed memory

Another common problem happens when a program frees a memory pointer but goes on to use it again by mistake. This can lead to mysterious crashes and unexplained problems.

To combat this, the library can write special values into a block of memory after it has been freed. This serves two purposes: it will make sure that the program will get garbage data if it trying to access the area again, and it will allow the library to verify the area later for signs of overwriting.

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.

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.