[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.4.1 Usage

To enable the memory debugger you should first of all compile in "debug" mode. It is possible to use it in "optimize" mode but you will get hexadecimal addresses instead of file name, function name, and line number information.

Next, you don't need to recompile the engine from scratch, like you used to do with the old memory debugger (that used CHK() macros). You just work as usual and if you need the memory debugger, you recompile with the `MEMDBG' variable set to 1. For example:

 
make walk mode=debug MEMDBG=1

This will just compile `memdbg.cpp' and link all other object files and libraries with this one. Linking against this file automatically enables the memory debugger.

Now you should create a map file for your executable. A map file is a text file that contains information about source files, functions and line numbers of your programs. The format of the map file is explained in the following section. See section 8.4.2 Map File Format.

The map file is created with the `CS/bin/memdbg.sh' script. You do it this way:

 
bin/memdbg.sh ./walktest [options]

This will create a file called `memdbg.map'. You also can provide some options after giving the name of executable. These options tell the memory debugger what tasks to perform. Here is a summary on each option. Note that character case is significant!

`a'
Fill memory after allocation with garbage. This is highly recommended as it is not too expensive but allows to detect cases when memory is used without being initialized first.

`f'
Fill freed memory with garbage but don't actually free it. Warning: This is quite expensive in terms of memory consumption.

`d'
Cause program to brak into debugger upon detection of serious errors. The debugger will break inside operator `new' or `delete' right before exiting back to user program. By stepping a few times you can detect the place where error occurred.

`v'
Cause memory debugger to print an informational string each time `new' or `delete' is called. It is recommended that you to redirect `stdout' when using this flag as output to console will immensely slow down your program.

`s'
Emit a summary sheet at the end of program execution. The sheet will list the summary number of memory allocations, deallocations, the peak memory consumption, and a lot of other useful information.

`l'
Emit a list of unfreed memory blocks at the end of program. The list will also contain the location where the corresponding memory block was allocated.

`b'
Detect writes past the block boundaries. This is implemented by allocating slightly bigger blocks than actually requested, and by filling those inter-block spaces with some well-known value. When block is freed, the space between blocks is checked to verify that it still contains the same well-known value.

`L'
Redirect (append) output from console to a log file called `memdbg.log'.

Default options are `aslbL'. To enable extensive checking use `aslbLf'. To enable all options use `aslbLfdv'. Thus, to disable everything except the log file and the summary, you type:

 
bin/memdbg.sh ./walktest sL

After you created the map file, just run your program as usual. If your program doesn't have a separate `stdout' stream (such as on DOS, OS/2, Windows, MacOS/9) it is recommended that you always use log file; if you didn't you can still redirect the `stdout' to a file using the `stdout' redirection, if it is possible (for intance, `./walktest > logfile').

If you will want later to change debugging options, you can load the map file into any text editor (that will handle such large files) and change the first line (that starts with a capital `O').

If you did everything correctly, you should get similar references to locations:

 
+--------+----------+- Unfreed memory blocks -------------------
|  size  |  address |location where block was allocated
+--------+----------+-------------------------------------------
|     239|   0x89970|file /home/CS/memdbg/test.cpp:28, func main

If you get such text:

 
+--------+----------+- Unfreed memory blocks--------------------
|  size  |  address |location where block was allocated
+--------+----------+-------------------------------------------
|     200|   0x32b70|unknown (0x10239)
|     239|   0x87f50|unknown (0x10189)

This means that the map file is either incorrect, or does not contain location information about the above addresses. However, this does not invalidate the usefulness of the memory debugger, it just makes reading of the log file more complex. Usually each compiler system provides a way to find out the source module and the line number that is closest to given address. For GNU set of development tools this is done with the `addr2line' tool. You also can do it with `gdb'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html