Displays backtrace information. If you do not use other backtrace options, you can omit this option.

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 for HPC 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 for HPC 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: heap allocations

dealloc: heap deallocations

hoard: deallocations currently held in the hoard

leaks: leaked heap allocations

Names the location for writing memory information. If the name ends with a slash (/), MemoryScape writes information into a directory, with the filenames being 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.

Lists the set of events that is supported by the HIA in use. Any of these events can be specified in a space-delimited list as the argument to the -notify, -nonotify, and -reset_notify options.

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. Use the -show_supported command to list the events supported by the HIA in use.

Resets the event filter to MemoryScape’s default value for the filters named in the list. Use the -show_supported command to list the events supported by the HIA in use.

Specifies the data being written, as follows:

alloc: Shows all heap allocations.

alloc_leaks: Shows all heap allocations and perform 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 information for the process using .mdbg format. This format’s only purpose is to be imported back into MemoryScape.

Names the file to which TotalView for HPC writes memory information.

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

Specifies the format used to write a view’s data to a file. The default is html.

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 an HTML 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 -data raw option, MemoryScape ignores this option.

When set to on, TotalView for HPC 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 for HPC 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 -data raw option, 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 GUI.

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:

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

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-list 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.

Displays guard settings. If you do not use other guard options, you can omit the -status option when you want to see status information.

Checks the guards to see if they have been violated. If it finds a violated guard, MemoryScape displays information. The information displayed can be modified through the following subcommands:

-[no]show_backtrace: Displays (or not) backtrace information. This list can be very long.

-[no]show_backtrace_id: Displays (or not) backtrace IDs.

-[no]show_generation_id: Displays (or not) generation IDs.

-[no]show_guard_settings: Displays (or not) information about guards settings.

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

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

Removes all changes you have made and restores guard settings to what they were when you first invoked MemoryScape.

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) tells MemoryScape not to limit guard sizes. Zero is the default value.

Defines the pattern MemoryScape uses when it writes guard blocks.The default pre-allocation pattern is 0x77777777 and the default post-allocation pattern is 0x99999999.

If you only specify 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 specify an end_address, MemoryScape tags or removes the tag from all addresses beginning with start_address to the end of the heap.

Displays hoard settings. Information displayed indicates whether hoarding is enabled, whether deallocated blocks are added to the hoard (or only those that are tagged), the maximum size of the hoard, and the hoard’s current size.If you do not use other hoarding options, you can omit the -status option when you want to see status information.

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 values.

Tells MemoryScape whether to hoard deallocated blocks.

Resets MemoryScape settings for hoarding of deallocated blocks to their initial values.

Sets the maximum size of the hoarded information.

Sets the maximum number of hoarded blocks.

Resets a hoarding size value back to its default.

The autoshrink feature attemps to avoid the failure of memory allocations because memory is running short by reducing the size of the hoard to free enough memory for the allocation. If hoarding is enabled and this feature is turned on, blocks are removed from the hoard until either there is sufficient memory for the allocation, or the hoard is exhausted. If the hoard is exhausted and the allocation still fails, the normal “allocation operation returned null” event is raised.

There are subcommands to control this feature, as follows:

-status: Displays information about the current status of autoshrinking.

-set { on | off }: Turns the feature on and off.

-reset: Resets autoshrinking to its default values, obtained from the TVHEAP_ARGS environment variable, the HIA configuration file, or the TotalView default values.

-set_threshold_kb integer | -reset_threshold_kb: Defines a size in kilobytes for the hoard such that if autoshrinking causes the hoard to fall below this value, you are notified. This can be a useful way to know when memory is running short. Use the reset option to return this setting to its default value.

-set_threshold_trigger integer | -reset_threshold_trigger: If you set a threshold, it can happen that the size of the hoard starts crossing over and under the threshold size again and again, resulting in continuous notifications. This option sets a limit to the number of notifications by decrementing the specified number each time a notification occurs until the number reaches zero, at which time notifications stop. To start them again, use this option to set a new number. The reset option resets the default value, which normally is 1, meaning you receive just a single notification and then no more.

Displays (or not) backtrace information. This list can be very long.

Displays (or not) backtrace IDs.

Displays (or not) information about generation IDs.

Displays (or not) information about guards settings.

Limits the reporting to leaked heap regions with a HIA generation ID satisfying the range condition x:y. The range condition is specified as follows:

where id identifies the HIA generation of the heap region, and x and y are positive integers.

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.

MemoryScape considers a memory block as being referenced if the beginning or an interior portion of the block is referenced.

MemoryScape considers a memory block as being referenced only if a reference points to the beginning of the allocated block.

Limits the reporting to leaked heap regions with a HIA generation ID satisfying the range condition x:y. The range condition is specified as follows:

where id identifies the HIA generation of the heap region, and x and y are positive integers.

Shows the current paint settings. These are either the values you set using other painting options or their default values. This is the default behavior if -paint is entered without arguments.

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.

Resets MemoryScape settings for block painting to their initial values or to values specified in a startup file.

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.

Shows the current HIA red zone settings. By default, dheap -red_zones displays only those settings that can vary in the current mode, so that, for example, in overrun mode the settings for fences and end positioning are not shown. The dheap -red_zones -status -all command causes all settings to be shown, including those that are overridden for the current mode.

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:

Number of allocated blocks.

Sum of the space requests received by the Red Zones allocator for allocated blocks.

Sum of the space used for fences for allocated blocks.

Overall space used for allocated blocks.

The same set of statistics are also shown for deallocated blocks. In addition, the space used for each category is shown as a percentage of the overall space used for Red Zones.

Displays the Red Zone entries for allocations (and deallocations) lying in the optionally specified range. If no range is specified, the entries for the entire address space are displayed.

Enables or disables Red Zones. The -reset option allows the HIA to determine its setting using the usual rules.

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 will 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:

overrun: The settings used are those that allow overruns to be detected. These are: no for pre-fence, yes for post-fence, and yes for end-positioned.

underrun: The settings used are those that allow underruns to be detected. These are: yes for pre-fence, no for post-fence, and no for end-positioned.

unfenced: The settings used are those that allow use_after_frees to be detected. These are: no for pre-fence, no for post-fence. End-positioned is determined from the control's setting.

manual: All settings are determined from their actual values.

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 subsequent 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 0 indicates that the default alignment for the platform should be used. An alignment of 2 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 1 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 0 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.

Restricts the use of Red Zones to allocations of particular sizes. With size ranges enabled, the Red Zones allocator is 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.Note that -sr is an alias to -size_ranges.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 be 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 is used for all allocations.

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: = IDs of x and higher
x = ID is x

-set_range id size_range

Sets 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 = allocation is x

-reset_range id_range

Resets an id or range of ids. For id_range formats, see -status above.

-set_in_use { on | off } id_range

Adjusts the “in_use” attribute of all the size ranges whose IDs lie within id_range. For id_range formats, see -status above.

-set_active { on | off } id_range

Adjusts the “active” attribute of all the size ranges whose ids lie within id_range. For id_range formats, see -status above.

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 re-enable memory reuse, use the -no‑hoard_on_dealloc subcommand. For more information, see the section “Memory Reuse: dheap -hoard” in Debugging Memory Problems with MemoryScape.

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 specify 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 specify 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. This is the default if no arguments are specified.

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 the section “TVHEAP_ARGS” in Debugging Memory Problems with MemoryScape.