4.2 How to Use the Dmalloc Program

The most basic usage for the program is `dmalloc [-bC] tag'. The `-b' or `-C' (either but not both flags used at a time) are for generating Bourne or C shell type commands respectively. dmalloc will try and use the SHELL environment variable to determine whether bourne or C shell commands should be generated but you may want to explicitly specify the correct flag.

The `tag' argument to dmalloc should match a line from the user's runtime configuration file or should be one of the built-in tags. See section Format of the Runtime Configuration File. If no tag is specified and no other option-commands used, dmalloc will display the current settings of the environment variable. It is useful to specify one of the verbose options when doing this.

To find out the usage for the debug malloc program try `dmalloc --usage-long'. The standardized usage message that will be displayed is one of the many features of the argv library included with this package.

It is available on the web at URL http://256.com/sources/argv/. See the documentation there for more information.

Here is a detailed list of the flags that can passed to dmalloc:

-a address

Set the `addr' part of the `DMALLOC_OPTIONS' variable to address (or alternatively address:number).

-b

Output Bourne shell type commands. Usually handled automagically.

-C

Output C shell type commands. Usually handled automagically.

-c

Clear/unset all of the settings not specified with other arguments. You can do this automatically when you set to a new tag with the -r option.

NOTE: clear will never unset the `debug' setting. Use -d 0 or a tag to `none' to achieve this.

-d bitmask

Set the `debug' part of the `DMALLOC_OPTIONS' env variable to the bitmask value which should be in hex. This is overridden (and unnecessary) if a tag is specified.

-D

List all of the debug-tokens. Useful for finding a token to be used with the -p or -m options. Use with -v or -V verbose options.

-e errno

Print the dmalloc error string that corresponds to the error number errno.

-f filename

Use this configuration file instead of the RC file `$HOME/.dmallocrc'.

-g

Output gdb type commands for using inside of the gdb debugger.

-h (or --help)

Output a help message for the utility.

-i number

Set the checking interval to number. If the check-heap token is enabled, this causes the library to only check the heap every Nth time which can significantly increase the running speed of your program. If a problem is found, however, this limits your ability to determine when the problem occurred. Try values of 50 or 100 initially.

-k

Do not reset all of the settings when a tag is specified. This specifically overrides the -r option and is provided here to override -r if it has been added to the dmalloc alias.

-l filename

Write the debugging output and other log-file information to the filename. Filename can include some of the following patterns which get expanded into strings:

%h

Gets expanded into the hostname if the gethostname() function is available.

%i

Gets expanded into the thread-id if the library has been configure to be used with threads. See section Using the Library with a Thread Package. See the end of the `settings.dist' file for settings which return the thread-id and convert it into a string.

%p

Gets expanded into the process-id if the getpid() function is available.

%t

Gets expanded into the time value in seconds if the time() function is available.

%u

Gets expanded into the user-id number if the getuid() function is available.

Some examples:

# logfile produced with pid extension: # logfile.8412 or logfile.31451 dmalloc -l logfile.%p # hostname and time extensions: # dmalloc-box1.foo.com-1055213240 dmalloc -l dmalloc-%h-%t # if threads enabled, have thread-id extension: log.thread32 dmalloc -l log.thread%i

-L

Write the debug-value into the environment not in hex but by individual debug-tokens in long form.

-m token(s)

Remove (minus) the debug capabilities of token(s) from the current debug setting or from the selected tag (or -d value). Multiple -m options can be specified.

-M limit

Set the memory allocation limit which will abort the program if the total memory allocations exceed this number of bytes. The limit can be a number with a k, m, or g at the end to indicate kilobyte, megabyte, and gigabyte respectively. Ex: 100k, 200m, 1g. If the limit is exceeded, this will generate an ERROR_OVER_LIMIT error. See section Description of the Internal Error Codes.

-n

Without changing the environment, output the commands resulting from the supplied options.

-o times

Set the "lock-on" period which dictates to the threaded version of the library to not initialize or lock the mutex lock around the library until after a certain number of allocation calls have been made. Some number between 2 and 30 is probably good. See the "Using With Threads" section for more information about the operation of the library with threads. See section Using the Library with a Thread Package.

-p token(s)

Add (plus) the debug capabilities of token(s) to the current debug setting or to the selected tag (or -d value). Multiple -p options can be specified.

-r

Remove (unset) all settings when using a tag. This is useful when you are returning to a standard development tag and want the logfile, address, and interval settings to be cleared automatically. If you want this behavior by default, this can be put into the dmalloc alias.

-R

Output rc shell type commands. This is not for the runtime configuration file but for the rc shell program.

-s file:line

Set the `start' part of the `DMALLOC_OPTIONS' env variable to a file-name and line-number location in the source where the library should begin more extensive heap checking. The file and line numbers for heap transactions must be working for this option to be obeyed. This is used if you are trying to locate a problem and you want the extensive checking to not happen initially because it's too slow.

-S number

Set the `start' part of the `DMALLOC_OPTIONS' env variable to an dmalloc mark number. The library will begin more extensive heap checking after this number of memory transactions. If you LOG_ITERATION enabled in your `settings.h' file then the entries in the log file will be prepended with the number of memory transactions that the library has handled so far. This number can be used to delay the start of the fine grained heap checking which can be very slow.

--start-size size

Set the `start' part of the `DMALLOC_OPTIONS' env variable to a number of bytes. The library will begin more extensive heap checking after this amount of memory has been allocated by the library. This allows you to start the slow and detailed checking of the library later in the program execution. You can use patterns like 250m, 1g, or 102k to mean 250 megabytes, 1 gigabyte, and 102 kilobytes respectively.

-t

List all of the tags in the rc-file. Use with -v or -V verbose options.

-u (or --usage)

Output the usage information for the utility.

-v

Give verbose output. Especially useful when dumping current settings or listing all of the tags.

-V

Give very verbose output for outputting even more details about settings.

--version

Output the version string for the utility. Please note that the version of the library that is installed or has been linked into your application may be different from the utility version.

If no arguments are specified, dmalloc dumps out the current settings that you have for the environment variable. For example:

Debug-Flags  '0x40005c7' (runtime)
Address      0x1f008, count = 3
Interval     100
Logpath      'malloc'
Start-File   not-set

With a -v option and no arguments, dmalloc dumps out the current settings in a verbose manner. For example:

Debug-Flags  '0x40005c7' (runtime)
   log-stats, log-non-free, log-bad-space, check-fence, catch-null
Address      0x1f008, count = 10
Interval     100
Logpath      'malloc'
Start-File   not-set

Here are some examples of dmalloc usage:

# start tough debugging, check the heap every 100 times,
# send the log information to file 'logfile'
dmalloc high -i 100 -l logfile

# find out what error code 20 is (from the logfile)
dmalloc -e 20

# cause the library to halt itself when it sees the address 0x34238
# for the 6th time.
dmalloc -a 0x34238:6

# send the log information to file 'logfile' with the time in seconds
# as an extension.
dmalloc -l logfile.%t

# return to the normal 'runtime' settings and clear out all
# other settings
dmalloc -c runtime

# enable basic 'low' settings plus (-p) the logging of
# transactions (log-trans) to file 'logfile'
dmalloc low -p log-trans -l logfile

# print out the current settings with Very-verbose output
dmalloc -V

# list the available debug malloc tokens with Very-verbose output
dmalloc -DV

# list the available tags from the rc file with verbose output
dmalloc -tv

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.