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 downloaded 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 library configuration and build process above was able to locate one of the on_exit function, atexit function, or had compiler destructor support. If one of these functions or support is available then the dmalloc library should be able to automatically shut itself down when the program exits. 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. To get the dmalloc utility to work you need to add an alias for dmalloc to your shell's runtime configuration file if supported. The idea is to have the shell capture the dmalloc program's output and adjust the environment.

   After you add the alias to the shell config file you need to log out and log back in to have it take effect, or you can execute the appropriate command below on the command line directly. After you setup the alias, if you enter dmalloc runtime and see any output with DMALLOC_OPTIONS in it then the alias did not take effect.

   Bash, ksh, and zsh (http://www.zsh.org/) 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 $*}}

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 wother includes. You may want to ifdef it as well and compile with cc -DDMALLOC …:

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

6. Another optional task is to compile all of your source with the `dmalloc.h' with the DMALLOC_FUNC_CHECK compilation flag. This willallow the library to check all of the arguments of a number of common string and utility routines. See section Checking of Function Arguments.

   cc -DDMALLOC -DDMALLOC_FUNC_CHECK file.c

7. Link the dmalloc library into your program. The dmalloc library should probably be placed at or near the end of the library list.
8. Enable the debugging features by typing dmalloc -l logfile -i 100 low (for example). You should not see any messages printed by the dmalloc utility (see NOTE below). This will:
   • Set the malloc logfile name to `logfile' (-l logfile). For programs which change directories, you may want to specify the full path to your logfile.
   • Have the library check itself every 100 iterations (-i 100). This controls how fast your program will run. Larger numbers check the heap less and so it will run faster. Lower numbers will be more likely to catch memory problems.
   • Enable a number of debug features (low). You can also try runtime for minimal checking or medium or high for more extensive heap verification.
   • By default, the low, medium, and high values enable the error-abort token which will cause the library to abort and usually dump core immediately upon seeing an error. See section Generating a Core File on Errors. You can disable this feature by entering dmalloc -m error-abort (-m for minus) to remove the error-abort token and your program will just log errors and continue.

   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.

   NOTE: The output from the dmalloc utility should be captured by your shell. If you see a bunch of stuff which includes the string DMALLOC_OPTIONS then the alias you should have created above is not working and he environmental variables are not being set. Make sure you've logged out and back in to have the alias take effect.

9. Run your program, examine the logfile that should have been created by dmalloc_shutdown, and use its information to help debug your program.

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.