Set or reset the depth. The depth is the maximum number of PCs that MemoryScape includes when it creates a backtrace. (The backtrace is created when your program allocates or reallocates a memory block.) The depth value starts after the trim value. That is, the number of excluded frames does not include the trimmed frames.

When you use the -reset_depth option, TotalView either restores its default setting or the setting you set using the TVHEAP_ARGS environment variable.

Sets or resets the trim. The trim describes the number of PCs from the top of the stack that MemoryScape ignores when it creates a backtrace. As the backtrace includes procedure calls from within MemoryScape, setting a trim value removes them from the backtrace. The default is to exclude MemoryScape procedures. Similarly, your program might call the heap manager from within library code. If you do not want to see call frames showing a library, you can exclude them.

When you use the -reset_trim option, TotalView either restores its default setting or the setting you set using the TVHEAP_ARGS environment variable.

Displays the stack frames associated with the backtrace identified by backtrace_id.

Names the data to be written into the exported compare file, as follows:

alloc: writes heap allocations

hoard: writes deallocations currently held in the hoard

leaks: writes leaked heap allocatons

Names the location for writing memory information. If the name ends with a slash (/), MemoryScape writes information into a directory; the filenames it uses are the MemoryScape defaults.

Changes the order in which MemoryScape makes its comparison. That is, MemoryScape normally compares the first named file to the second. This tells MemoryScape to compare the second to the first.

Specifies the format to use when it writes information to disk. If you do not use this command, MemoryScape writes the information as HTML.

Specifies if the comparison uses a process or a memory debugging export (.mdbg) file. Your choices are:

No arguments: compare the two processes in the current focus.

One argument: compare the process in the current focus with the process/filename you specify.

Two arguments: compare the two processes/filenames named as arguments.

Tells TotalView to display the current event filter settings. If you do not use other event filter options, you can omit this option.

Enables or disables event filtering. If you disable event filtering, MemoryScape displays all events. If you enable event filtering, then you can control which events MemoryScape displays.

Resets the event filter to MemoryScape’s default value. You can create your own default in a configuration file or by specifying an environment variable setting.

Enables or disables one or more events. The event names you can use are:

addr_not_at_start
alloc_not_in_heap
alloc_null
alloc_returned_bad_alignment
bad_alignment_argument
dealloc_notification
double_alloc
free_not_allocated
realloc_not_allocated
realloc_notification

Resets the event filter to MemoryScape’s default value for the filters named in the list. The names you can use are the same as those you use in the -notify option.

When exporting data, you must use the -data and -output options with dheap -export:

Specifies the data being written, as follows:

alloc: Shows all heap allocations.

alloc_leaks: Shows all heap allocations and perfrom leak detection. This differs from the alloc argument in that TotalView annotates leaked allocations.

dealloc: Shows deallocation data.

hoard: Shows deallocations currently held in the hoard.

leaks: Shows leaked heap allocations.

raw: Exports all heap informtion for the process using .mdbg format. This format’s only purpose is to be imported back into MemoryScape.

Names the file to which TotalView writes memory information.

You can optionally use any of the following options with dheap -export:

If you omit the no prefix, tells MemoryScape that a memory block should not be considered as leaked if a pointer is pointing anywhere within the block. TotalView ignores this option unless you also use the -data leaks option.

Specifies the format used to write a file. If you omit this option, MemoryScape writes an HTML-formatted document.

If you select text, the result is as expected: a text file containing the view’s information.

There are some limitations and things you need to know if you select html. The only supported browser is Firefox, running versions 1.0 or greater. In addition, you must have JavaScript turned on. (While information displays correctly in other browsers such as Internet Explorer 6.0 and Safari, isolated problems can occur.) This file can be quite large and can take a while to load.

When MemoryScape writes a file, it also creates a subdirectory with a related name containing additional information. For example, if the output file name is foo.html, MemoryScape creates a subdirectory named foo_files.

If you need to move the output file, you must also move the related subdirectory to the same directory.

If used, MemoryScape limits the information it writes to those created since the last time you created a baseline. If you also use the raw data format, MemoryScape ignores this option.

When set to on, TotalView includes backtrace information within the data being written. As on is the default, you only need to use this option with the off argument.

When set to on, TotalView includes the source code for the place where the memory was allocated with the data being written. As on is the default, you only need to use this option with the off argument.

Tells MemoryScape to export a backtrace view instead of a source view. If you also use the raw data format, MemoryScape ignores this option.

Enables filtering of dheap commands. If you do not use an argument with this option, this option is equivalent to selecting Enable Filtering in the MemoryScape Window.

Using a filter name simply defines where to locate filter information; you still need to enable filtering. For example, here is how you would enable filtering and enable the use of a filter named MyFilter:

dheap -filter -enable MyFilter
dheap -filter -enable

If you did not enter the second command, no filtering occurs.

The all argument tells MemoryScape to enable all of your filters.

Disables filtering or disables an individual filter. The way that you use this command is similar to dheap -filter -enable.

Displays a filter description and its enabled state. If you do not use a filter-name argument, the CLI displays all defined filters and their enabled states.

If you include the full argument, the information includes all of the filter’s criteria.

Enables or disables the writing of guards. If you disable this feature after it is enabled, MemoryScape does not remove existing guard blocks.

Specify a size in bytes. You can set the sizes of the pre- and post- guards independently. The actual size of a guard can differ from these settings if MemoryScape needs to adjust the size to meet alignment and allocation unit size constraints. In addition, you can set the maximum guard size. If the guard size will be greater than this maximum, MemoryScape does not create a guard.

The default sizes are 8 bytes.

Setting the maximum size to zero (0) indicates that MemoryScape does not limit guard sizes. Zero is the default value.

If you only only a start_address, MemoryScape either tags or removes the tag from the block that contains this address. The action it performs depends on the subcommand you use.

If you also specify an end_address, MemoryScape either tags all blocks beginning with the block containing the start_address and ending with the block containing the end_address or removes the tag. The action it performs depends on the subcommand you use. If end_address is 0 (zero) or you do not type an end_address, MemoryScape tags or removes the tag from all addresses beginning with start_address to the end of the heap.

Displays the contents of the hoard. You can restrict the display by specifying start_address and end_address. If you omit end_address or use a value of 0, MemoryScape displays all contents beginning at start_address and going to the end of the hoard.

The CLI displays hoarded blocks in the order in which your program deallocated them.

Enables and disables hoarding.

Resets MemoryScape settings for hoarding back to their initial value.

Tells MemoryScape whether to hoard deallocated blocks.

Resets MemoryScape settings for hoarding of deallocated blocks to its initial value.

Sets the maximum size of the hoarded information.

Sets the maximum number of hoarded blocks.

Resets a hoarding size value back to its default.

Displays backtrace information. This list can be very long.

Adds backtrace IDs to the information it displays.

Adds information about guards settings to the information it displays.

The HIA detects when an attempt is made to release a block using a Mac x-x86 malloc zone that is different from the one which allocated it.

Allocators are the low-level functions that allocated and deallocate memory.

An owner can be thought of as an instance of a heap manager interface.

If you just type a start_address, the CLI reports on all allocations beginning at and following this address. If you also type an end_address, the CLI limits the display to those allocations between the start_address and the end_address.

If you also specify an end_address, the CLI reports on all allocations between start_address and end_address. If you type 0, it’s the same as omitting this argument; that is, MemoryScape displays information from the start_address to the end of the address space.

Indicates if an address that was once allocated and not yet recycled by the heap manager is now deallocated.

Locates all memory blocks that your program allocated and which are no longer referenced. That is, using this command tells MemoryScape to locate all dangling memory. For more information, see “Detecting Leaks: dheap -leaks”.

Unless set to -nocheck_interior, MemoryScape considers a memory block as being referenced if the interior portion of the block is referenced. If you do not set this option, the default is -check_interior.

By default, MemoryScape checks to see if the starting location of an allocated memory block is referenced.

The on options enable block painting. They tell MemoryScape to paint a block when your program’s heap manager allocates, deallocates, or uses a memory function that sets memory blocks to zero.

You can only paint zero-allocated blocks if you are also painting regular allocations.

The off options disable block painting.

Sets the pattern that MemoryScape uses the next time it paints a block of memory. The maximum width of pattern can differ between operating systems. However, your pattern can be shorter.

Resets the patterns used when MemoryScape paints memory to the default values.

Enables or disables the ability to catch bounds errors and use-after-free errors retaining freed memory blocks.

Displays statistics relating to the HIA’s Red Zones allocator for the optionally specified address range. If no range is specified, the following statistics are shown for the entire address space:

Sets the HIA in one of several Red Zone modes. When a new allocation is requested, the HIA will override the actual settings for some of the individual controls, and instead use values that correspond to that mode. The settings that are affected are: pre-fence, post-fence, and end-positioning. The other settings, like use-after-free, exit value , and alignment, take their values from the actual settings of those controls.

The modes are:

Enables or disables the pre-fence control. However, the setting is ignored unless the mode is manual.

Enables or disables the post-fence control. However, the setting is ignored unless the mode is manual.

Enables or disables the use_after_free control. If enabled, any subequent allocations will be tagged such that the allocation and its fences are retained when the block is deallocated. Access to the block is disabled when it is deallocated to allow attempts to access the block to be detected.

Regulates the alignment of the start address of a block issued by the Red Zones allocator. An alignment of zero indicates that the default alignment for the platform should be used. An alignment of two ensures that any address returned by the Red Zones allocator is a multiple of two. In this case, if the length of the block is odd, the end of the block will not line up with the end of the page containing the allocation. An alignment of one is necessary for the end of the block to always correspond to the end of the page.

Adjusts the fence size used by Red Zones. A fence size of zero indicates that the default fence size of one page should be used. If necessary, the fence size is rounded up to the next multiple of the page size. In most cases it should not be necessary to adjust this control. One instance where it may be useful, however, is where it is suspected that a bounds error is a consequence of a badly coded loop, and the stride of the loop is large. In such a case, a larger fence may be helpful.

Controls whether the allocation is positioned at the end or the start of the containing page. The control in the HIA is always updated, though the actual value is ignored in overrun and underrun modes.

Adjusts the exit value used if the HIA terminates the target following detection of a Red Zones error. Generally, the application fails if it is allowed to continue after a Red Zone error has been detected. In order to allow some control over the application's exit code, the HIA will call exit when an error is detected. The value it passes to exit as a termination code can be controlled, so that if the application is run from scripts, the cause for the termination can be determined.

Enables the user to restrict the use of Red Zones to allocations of particular sizes. With size ranges are enabled, the Red Zones allocator will be used if the size of the request lies in one of the defined ranges. A value is deemed to lie in a range if start <= size <= end.

To make typing a bit easier, -size_ranges can be abbreviated to -sr.

A range having an end of 0 is interpreted as having no upper limit. Thus if the end is 0, the size matches the range if it is at least as large as the start.

This feature allows the HIA to enable Red Zones for specific allocation sizes. The Red Zones allocator will be used if the size of the request lies in any one of these ranges. The HIA does not check to see that ranges do not overlap or are otherwise consistent.

The determination of whether the Red Zones allocator should be used is made at the time of the original allocation. Thus, once an allocator has taken ownership of a block, that allocator will be used for the remainder of the block's life. In particular, all realloc operations will handled by the same allocator, irrespective of the size range settings at the time of reallocation.

There are two attributes associated with each range. The first is the “in_use” attribute. This is ignored by the HIA, and is provided for the benefit of TotalView. The motivation here is to allow TotalView to keep a state that would otherwise be lost if the target is detached, and then reattached to later.

The second attribute is the “active” attribute. This indicates if the size range is active, and therefore whether it is used by the HIA when determining whether the Red Zones allocator should be used.

-set { on | off }

Enables and disables size ranges. If size ranges are disabled, but Red Zones are enabled, the Red Zones allocator will be used for all allocations.

-reset

Unsets the TotalView setting for the enable/disable control.

-status |-all id_range|

Shows the current settings of the size ranges. The absence of an id_range is equivalent to an id_range of “0:0”. By default, only “in_use” size ranges are displayed. To display all known ranges, specify -all. id_range must be in one of the following formats:

x:y = ids from x to y
:y = ids from 1 to y
x: = id of x and higher
x = id is x

-set_range id size_range

Set a size range identified by id to a particular size range. size_range must be in one of the following formats:

x:y = allocations from x to y
:y = allocations from 1 to y
x: = allocations of x and higher
x = allocations of x

-reset_range id_range

Resets an id or range of ids. id_range must be in a format defined above.

-set_in_use { on | off} id_range

Adjusts the “in_use” attribute of all the size ranges whose ids lie within id_range.

-set_active { on | off} id_range

Adjusts the “active” attribute of all the size ranges whose ids lie within id_range.

Unsets the TotalView settings for the above controls.

Does not release tagged memory back to your program’s heap manager for reuse when it is deallocated—this is used in conjunction with hoarding. To reenable memory reuse, use the -nohoard_on_dealloc subcommand. See “Memory Reuse: dheap -hoard” for more information.

If you use this option, the memory tracker only hoards tagged blocks. In contrast, if you use the dheap -hoard -set_all_deallocs on command, MemoryScape hoards all deallocated blocks.

Enable or disable notification when your program deallocates or reallocates a memory block.

If you only type a start_address, MemoryScape either tags or removes the tag from the block that contains this address. The action it performs depends on the subcommand you use.

If you also specify an end_address, MemoryScape either tags all blocks beginning with the block containing the start_address and ending with the block containing the end_address or removes the tag. The action it performs depends on the subcommand you use. If end_address is 0 (zero) or you do not type an end_address, MemoryScape tags or removes the tag from all addresses beginning with start_address to the end of the heap.

Displays the current verbosity setting. If you do not use other verbosity options, you can omit this option.

Restores the verbosity setting to its default.

Controls how much output MemoryScape writes to its output file. By default, this is file descriptor 1. Higher verbosity values tell MemoryScape to write more information. Setting verbosity to zero (0) suppresses output.

For more information, see “TVHEAP_ARGS”.