2.2 Getting Started with the Library

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:

1. Make sure you have the latest version of the library available from the home page at URL http://dmalloc.com/.
2. Follow the installation instructions on how to configure, make, and install the library (i.e. type: make install). See section How to Install the Library.
3. You need to make sure that the dmalloc building process above was able to locate one of the on_exit function, atexit function, or compiler destructor support. 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 none of the above, then you will need to call dmalloc_shutdown yourself before your program exits.
4. Add an alias for dmalloc to your shell's rc file if supported. The idea is to have the shell capture the dmalloc program's output and adjust the environment. Bash, ksh, and zsh users should add the following to their `.bashrc', `.profile', or `.zshrc' file respectively (notice the -b option for bourne shell output):

   function dmalloc { eval `command dmalloc -b $*`; }

   If your shell does not support the command function then try:

   function dmalloc { eval `\dmalloc -b $*`; }

   or

   function dmalloc { eval `/usr/local/bin/dmalloc -b $*`; }

   If you are still using csh or tcsh, you should add the following to your `.cshrc' file (notice the -C option for c-shell output):

   alias dmalloc 'eval `\dmalloc -C \!*`'

   If you are using rc shell, you should add the following to your `.rcrc' file (notice the -R option for rc-shell output):

   fn dmalloc {eval `{/usr/local/bin/dmalloc $*}}

   By the way, if you are looking for a shell, I heartily recommend trying out zsh at URL http://www.zsh.org/. It is a bourne shell written from scratch with much the same features as tcsh without the csh crap.

   NOTE: After you add the alias to the file you need to log out and log back in to have it take effect, or you can execute the above appropriate command on the command line. If you enter dmalloc runtime and see any output with DMALLOC_OPTIONS in it then the alias did not work.

5. Although not necessary, you may want to include `dmalloc.h' in your C files and recompile. This will allow the library to report the file/line numbers of calls that generate problems. See section Macros Providing File and Line Information. It should be inserted at the bottom of your include files as to not conflict with other includes. You may want to ifdef it as well and compile with cc -DDMALLOC …:

   /* other includes above ^^^ */ #ifdef DMALLOC #include "dmalloc.h" #endif

6. Link the dmalloc library into your program. The dmalloc library should probably be placed at or near the end of the library list.
7. Enable the debugging features by typing dmalloc -l logfile -i 100 low (for example). This will:
   • set the malloc log path to `logfile' (-l logfile)
   • have the library check itself every 100 iterations (-i 100)
   • enable a number of debug features (low). You can also try runtime for minimal checking or medium or high for more extensive heap verification.

   dmalloc --usage will provide verbose usage info for the dmalloc program. See section Dmalloc Utility Program.

   You may also want to install the `dmallocrc' file in your home directory as `.dmallocrc'. This allows you to add your own combination of debug tokens. See section Format of the Runtime Configuration File.

8. Run your program, examine the logfile that should have been created by dmalloc_shutdown, and use its information to help debug your program. See the next section for help with this. See section Some Solutions to Common Problems.

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.