Totalview® for HPC Reference Guide : PART I Using the CLI : Chapter 2 CLI Commands : dheap
dheap
Controls MemoryScape with TotalView heap debugging behavior
Format 
Shows Memory Debugger state
dheap [ -status ]
Enables or disables the Memory Debugger
dheap { -enable | -disable }
Applies a saved configuration file
dheap -apply_config { default| filename }
Shows information about a backtrace
dheap -backtrace [ subcommands ]
Compares memory states
dheap -compare subcommands [ optional_subcommands ]
[ process | filename [ process | filename ] ]
Enables or disables event notification
dheap -event_filtersubcommands
Writes memory information
dheap -exportsubcommands
Specifies the filters the Memory Debugger uses
dheap -filtersubcommands
Displays or increments the generation number given to memory allocations
dheap -generation [ subcommands ]
Writes guard blocks (memory before and after an allocation)
dheap -guard [ subcommands ]
Enables or disables the retaining (hoarding) of freed memory blocks
dheap -hoard[ subcommands ]
Displays Memory Debugger information
dheap -info [ subcommands ]
Indicates whether an address is in a deallocated block
dheap -is_dangling address
Locates memory leaks
dheap -leaks [ -check_interior ]
Enables or disables Memory Debugger event notification
dheap -[no]notify
Paints memory with a distinct pattern
dheap -paint [ subcommands ]
Enables or disables the ability to catch bounds errors and use-after-free errors retaining freed memory blocks
dheap -red_zones [ subcommands ]
Enables or disables allocation and reallocation notification
dheap -tag_alloc subcommands [ start_address [ end_address ] ]
Displays or specifies the verbosity level for HIA output
dheap -verbosity [ subcommands ]
Displays the Memory Debugger version number
dheap -version
Arguments 
-status
Displays the current state of MemoryScape. This tells you if a process is capable of having its heap operations traced, and whether TotalView for HPC will notify you if a notifiable heap event occurs. If TotalView for HPC stops a thread because one of these events occur, it displays information about this event.
Entering dheap with no arguments is the same as using this option.
-enable / -disable
The option -enable tells TotalView for HPC to use the MemoryScape agent to record heap events the next time you start the program. The -disable option tells TotalView for HPC not to use the agent the next time you start your program.
-apply_config { default | filename }
Applies configuration settings in a file to MemoryScape. If you type default, MemoryScape looks first in the current directory and then in your .totalview/hia/ directory for a file named default.hiarc. Otherwise, it uses the name of the file entered here. If you do not specify an extension, MemoryScape assumes that the extension is .hiarc. That is, while you can specify a file named foo.foobar, you cannot specify a file foo as MemoryScape would then assume that the file is actually named foo.hiarc.
-backtrace subcommands
Shows the current settings for the backtraces associated with a memory allocation. This information includes the depth and the trim, a s described below.
Subcommands
-status
Displays backtrace information. If you do not use other backtrace options, you can omit this option.
-set_depth depth / -reset_depth
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.
-set_trim trim / -reset_trim
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.
-display backtrace_id
Displays the stack frames associated with the backtrace identified by backtrace_id.
-compare required_subcommands [ optional_subcommands ]
[ process | filename [ process | filename ] ]
Required_Subcommands (both are required)
-data { alloc | dealloc | hoard | leaks }
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
-output { directory | filename }
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.
Optional_Subcommands
-reverse_diff
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.
-format { html | txt }
Specifies the format to use when it writes information to disk. If you do not use this command, MemoryScape writes the information as HTML.
process | filename [ process | filename ]
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.
-event_filter subcommands
The subcommands to this option let you control which agent events cause MemoryScape to stop program execution.
Subcommands
-status (optional)
Tells TotalView to display the current event filter settings. If you do not use other event filter options, you can omit this option.
-set { on | off }
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.
-show_supported
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.
-reset
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.
-[no]notify event-list
Enables or disables one or more events. Use the -show_supported command to list the events supported by the HIA in use.
-reset_notify event-list
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.
-export required_subcommands [ optional_subcommands ]
Writes information to a file.
Required_Subcommands
-data { alloc | alloc_leaks | dealloc | hoard | leaks | raw }
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.
-output filename
Names the file to which TotalView for HPC writes memory information.
Optional_Subcommands
You can optionally use any of the following options with dheap -export:
-[no]check_interior
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.
-format { html| text }
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.
-relative_to_baseline
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.
-set_show_backtraces { on | off }
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.
-set_show_code { on | off }
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.
-view backtrace
Tells MemoryScape to export a backtrace view instead of a source view. If you also use the -data raw option, MemoryScape ignores this option.
-filter subcommands
Use the -filter options to enable, disable, and show information about filtering.
Subcommands
-enable [ filter-name-list | all ]
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:
dheap -filter -enable MyFilter
dheap -filter -enable
If you did not enter the second command, no filtering would occur.
-disable [ filter-name-list | all ]
Disables filtering or disables an individual filter. The way that you use this command is similar to dheap -filter -enable.
-list [ [ -full ] filter-name-list ]
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.
-generation [ -status | -increment ]
The HIA gives each allocation a generation number. The -status option displays the current value of the generation number. This is the default option.
The -increment option increments the generation number in the HIA.
-guard subcommands [ start_address [ end_address ] ]
Use the-guard options to enable, disable, set characteristics, and show information about guard blocks.
Subcommands
-status
Displays guard settings. If you do not use other guard options, you can omit the -status option when you want to see status information.
-check [ subcommands ]
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.
-set { on | off }
Enables or disables the writing of guards. If you disable this feature after it is enabled, MemoryScape does not remove existing guard blocks.
-reset
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.
-reset_max_size / -reset_post_pattern / -reset_pre_pattern / -reset_post_size / -reset_pre_size
Removes all changes you have made and restores guard settings to what they were when you first invoked MemoryScape.
-set_max_size size / -set_post_size size / -set_pre_size size
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.
-set_post_pattern pattern / -set_pre_pattern pattern
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.
start_address
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.
end_address
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.
-hoard [ subcommands ]
Tells MemoryScape not to surrender allocated blocks back to your program’s heap manager. If you do not specify a subcommand, MemoryScape displays information about the hoarded blocks. For more information, see “Memory Reuse: dheap -hoard” in the Debugging Memory Problems with MemoryScape.
Subcommands
-status
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.
-display [ start_address [ end_address ] ]
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.
-set { on | off }
Enables and disables hoarding.
-reset
Resets MemoryScape settings for hoarding back to their initial values.
-set_all_deallocs { on | off }
Tells MemoryScape whether to hoard deallocated blocks.
-reset_all_deallocs
Resets MemoryScape settings for hoarding of deallocated blocks to their initial values.
-set_max_kb num_kb
Sets the maximum size of the hoarded information.
-set_max_blocks num_blocks
Sets the maximum number of hoarded blocks.
-reset_max_kb / -reset_max_blocks
Resets a hoarding size value back to its default.
-autoshrink [ subcommands ]
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.
-info [ subcommands ] [ -generation x:y ] [ start_address [ end_address ] ]
Displays information about the heap or regions of the heap within a range of addresses. If you do not use the address arguments, the CLI displays information about all heap allocations.
The information that MemoryScape displays includes the start address, a block’s length, and other information such as flags or attributes.
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) information about generation IDs.
-[no]show_guard_settings
Displays (or not) information about guards settings.
-generation x:y
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:
Specifier Condition
x:y x <= id <= y
x x <= id
x: x <= id
x:0 x <= id
:y 1 <= id <= y
where id identifies the HIA generation of the heap region, and x and y are positive integers.
start_address
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.
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.
-is_dangling address
Indicates if an address that was once allocated and not yet recycled by the heap manager is now deallocated.
-leaks [ subcommands ]
Locates all memory blocks that your program has allocated and that are no longer referenced. That is, using this command tells MemoryScape to locate all dangling memory.
If neither of the subcommands -check_interior and -no_check_interior are specified, the default behavior is based on the TotalView variable TV::GUI::leak_check_interior_pointers, whose default value is true.
A leak report is generated as a result of the command. The report shows the total number of leaks and total bytes leaked for the processes. It also consolidates leaks occurring at the same lines and reports the total number of leaks and total bytes leaked. Some additional statistics such as the smallest, largest and average leak size are also displayed.
For more information, see the section “Detecting Leaks: dheap -leaks” in Debugging Memory Problems with MemoryScape.
Subcommands
-check_interior
MemoryScape considers a memory block as being referenced if the beginning or an interior portion of the block is referenced.
-no_check_interior
MemoryScape considers a memory block as being referenced only if a reference points to the beginning of the allocated block.
-generation x:y
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:
Specifier Condition
x:y x <= id <= y
x x <= id
x: x <= id
x:0 x <= id
:y 1 <= id <= y
where id identifies the HIA generation of the heap region, and x and y are positive integers.
-[no]notify
Using the-notify option tells TotalView to stop your program’s execution when MemoryScape detects a notifiable event, and then print a message (or display a dialog box if you are also using the GUI) that explains what just occurred. MemoryScape can notify you when heap memory errors occur or when your program deallocates or reallocates tagged blocks.Using the -nonotify option tells TotalView not to stop execution. Even if you specify the -nonotify option, TotalView tracks heap events.
-paint [ subcommands ]
The painting feature allows the HIA to be instructed to fill, or paint, blocks as they are allocated and deallocated. The pattern used to fill the blocks may be specified, and different patterns may be used for allocations and deallocations.
Painting is useful in cases where it is suspected that the application is not initializing memory it acquires from the heap manager before using it. The allocation pattern can be set to something easily recognizable, and to something that may provoke an error if the memory is used before it is initialized. For example, if the memory is being used for floating point numbers, the pattern could be set to something that is not a legal floating point number. Should an element in the block be used in a floating point operation without being initialized, a floating point error should be raised. Similarly, certain “use-after-free” errors can be found by using a deallocation pattern.
Subcommands
-status
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.
-set_alloc {on | off } / -set_dealloc { on | off } / -set_zalloc { on | off }
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.
-reset_alloc / -reset_dealloc / -reset_zalloc
Resets MemoryScape settings for block painting to their initial values or to values specified in a startup file.
-set_alloc_pattern pattern / -set_dealloc_pattern pattern
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.
-reset_alloc_pattern / -reset_dealloc_pattern
Resets the patterns used when MemoryScape paints memory to the default values.
-red_zones [ subcommands ]
The Red Zones feature help catch bounds errors and use-after-free errors. The basic idea is that each allocation is placed in its own page. An allocation is positioned so that if an overrun, that is, an access beyond the end of the allocation, is to be detected, the end of allocation corresponds to the end of the page.
The page following that in which the allocation lies is also allocated, though access to this page is disabled. This page is termed the fence. Should the application attempt to access a location beyond the end of the allocation, that is, in the fence, the operating system sends the target a segment violation signal. This is caught by a signal handler installed by the HIA. The HIA examines the address that caused the violation. If it lies in the fence, then the HIA raises an overrun bounds error using the normal event mechanism.
If, however, the address does not lie in any region the HIA `owns', then the HIA attempts to replicate what would have happened if the HIA’s signal handler were not in place. If the application had installed a signal handler, then this handler is called. Otherwise, the HIA attempts to perform the default action for the signal. It should be clear from this that the HIA needs to interpose the signals API to ensure that it always remains the installed handler as far as the operating system is concerned. At the same time, it needs to present the application with what it expects.
Underruns, or errors where the application attempts to read before the start of an allocation are handled in a similar way. Here, though, the allocation is positioned so that its start lies at the start of the page, and fence is positioned to precede the allocation.
One complication that arises concerns overrun detection. The architecture or definition of the allocation routines may require that certain addresses conform to alignment constraints. As a consequence, there may be a conflict between ensuring that the allocation's start address has the correct alignment, and ensuring that the allocation ends at the end of the page.
Use-after-free errors can also be detected. In this case, when the block is deallocated, the pages are not returned to the operating system. Instead, the HIA changes the state of the allocation's table entry to indicate that it's now in the deallocated state, and then disables access to the page in which the allocation lies. This time, should the application attempt to access the block now that it's been deallocated, a signal will be raised. Again, the HIA examines the faulting address to see what it knows about the address, and then either raises an appropriate event for TV, or forwards the signal on.
The key features that distinguishes Red Zones is that it can be engaged and disengaged at will during the course of the target's execution. The settings can be adjusted, so that new allocations have different properties from existing allocations. Red Zones can be turned on or off, so that some of the application's requests are satisfied by the Red Zones allocator, and others by the standard heap manager. The HIA keeps track of which allocator is responsible for, or owns, each block.
Note that -rz is an alias for -red_zones.
For more information on red zones, see the section “Red Zones: dheap-red_zones” in Debugging Memory Problems with MemoryScape.
Subcommands
-status [ -all ]
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.
-stats [ start_addr [ end_addr ] ]
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.
-info [ start_addr [ end_addr ] ]
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.
-set { on | off } / -reset
Enables or disables Red Zones. The -reset option allows the HIA to determine its setting using the usual rules.
-set_mode { overrun | underrun | unfenced | manual }
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.
-set_pre_fence { on | off }
Enables or disables the pre-fence control. However, the setting is ignored unless the mode is manual.
-set_post_fence { on | off }
Enables or disables the post-fence control. However, the setting is ignored unless the mode is manual.
-set_use_after_free { on | off }
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.
-set_alignment integer
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.
-set_fence_size integer
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.
-set_end_aligned { on | off }
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.
-set_exit_value integer
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.
-size_ranges [ subcommands ]
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.
Subcommands
-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.
-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: = 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.
-reset_mode / -reset_pre_fence / -reset_post_fence / -reset_use_after_free / -reset_alignment / -reset_fence_size / -reset_exit_value / -reset_end_aligned
Unsets the TotalView settings for the above controls.
-tag_alloc subcommand [ start_address [ end_address ] ]
Marks a block so that it can notify you when your program deallocates or reallocates a memory block. For more information, see the section “Deallocation Notification: dheap -tag_alloc” in Debugging Memory Problems with MemoryScape.
When tagging memory, if you do not specify address arguments, MemoryScape either tags all allocated blocks or removes the tag from all tagged blocks.
Subcommands
-[no]hoard_on_dealloc
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.
-[no]notify_dealloc / -[no]notify_realloc
Enable or disable notification when your program deallocates or reallocates a memory block.
start_address
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.
end_address
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.
-verbosity [ subcommands ]
The subcommands to this option let you control how much information MemoryScape displays as it executes.
Subcommands
-status
Displays the current verbosity setting. This is the default if no arguments are specified.
-reset
Restores the verbosity setting to its default.
-set verbosity
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.
-version
Displays the version number of the HIA. If it is available, the distribution number of the version of TotalView for HPC with which the HIA was released is also shown.
Description 
The dheap command controls the MemoryScape product from the command line. You must have the MemoryScape product installed and a valid license. For full information on using MemoryScape, see the document Debugging Memory Problems with MemoryScape.
Here are some of the things you can do with MemoryScape:
Tell TotalView for HPC to use the MemoryScape agent to track memory errors.
Stop execution when a free() error occurs, and display information you need to analyze the error.
Hoard freed memory so that it is not released to the heap manager.
Write heap information to a file.
Control how much information is written to displays.
Use guard blocks. After MemoryScape writes guard blocks, you can ask it to tell you if blocks are violated.
Detect leaked memory by analyzing whether a memory block is reachable.
Compare memory states. You can compare the current state against a saved state or compare two saved states.
Paint memory with a bit pattern when your program allocate and deallocates it.
Use Red Zones to detect bounds and use-after-free errors.
Receive notification when your program deallocates or reallocates a memory block.
The first step when debugging memory problems is to type the dheap -enable command. This command activates MemoryScape. You must do this before your program begins executing. If you try to do this after execution starts, TotalView for HPC tells you that it will enable MemoryScape when you restart your program. For example:
 
d1.<> n
64 > int num_reds = 15;
d1.<> dheap -enable
process 1 (30100): This will only take effect on restart
You can tell MemoryScape to stop execution if:
A free() problem occurs (dheap -notify)
A block is deallocated (dheap -tag_alloc -notify_dealloc)
A block is reallocated (dheap -tag_alloc -notify_realloc)
If you enable notification, TotalView for HPC stops the process when it detects one of these events. MemoryScape is always monitoring heap events even if you turned notification off, but TotalView for HPC does not stop the program when events occur or tell you that the events occurred.
While you can separately enable and disable notification in any group, process, or thread, you probably want to activate notification only on the control group’s master process. Because this is the only process that TotalView for HPC creates, it is the only process where TotalView for HPC can control MemoryScape’s environment variable. For example, slave processes are normally created by an MPI starter process or as a result of using the fork() and exec() functions. In these cases, TotalView for HPC simply attaches to them. For more information, see Chapter 4, “Creating Programs for Memory Debugging”, in Debugging Memory Problems with MemoryScape.
If you do not use a dheap subcommand, the CLI displays memory status information. You need to use the ‑status option only when you want the CLI to display status information in addition to doing something else.
The information that the dheap command displays can contain a flag containing additional information about the memory location. The following table describes these flags:
 
Flag Value
Meaning
0x0001
Operation in progress
0x0002
notify_dealloc: you will be notified if the block is deallocated
0x0004
notify_realloc: you will be notified if the block is reallocated
0x0008
paint_on_dealloc: MemoryScape will paint the block when it is deallocated
0x0010
dont_free_on_dealloc: MemoryScape will not free the tagged block when it is deallocated
0x0020
hoarded: MemoryScape is hoarding the block
 
Examples 
The following example shows a scenario of finding and debugging a memory problem with dheap.
d1.<> dheap
process: Enable Notify Available
1 (18993): yes yes yes
1.1 realloc: Address does not match any allocated block.: 0xbfffd87c
 
d1.<> dheap -info -backtrace
process 1 (18993):
0x8049e88 -- 0x8049e98 0x10 [ 16]
flags: 0x0 (none)
: realloc PC=0x400217e5 [/.../malloc_wrappers_dlopen.c]
: argz_append PC=0x401ae025 [/lib/i686/libc.so.6]
: __newlocale PC=0x4014b3c7 [/lib/i686/libc.so.6]
:
...
.../malloc_wrappers_dlopen.c]
: main PC=0x080487c4 [../realloc_prob.c]
: __libc_start_main PC=0x40140647 [/lib/i686/libc.so.6]
: _start PC=0x08048621 [/.../realloc_prob]
 
 
0x8049f18 -- 0x8049f3a 0x22 [ 34]
flags: 0x0 (none)
: realloc PC=0x400217e5 [/.../malloc_wrappers_dlopen.c]
: main PC=0x0804883e [../realloc_prob.c]
: __libc_start_main PC=0x40140647 [/lib/i686/libc.so.6]
: _start PC=0x08048621 [/.../realloc_prob]
Here is an example of a reported free error:
d1.<> dheap
process: Enable Notify Available
1 (30420): yes yes yes
1.1 free: Address is not the start of any allocated block.:
free: existing allocated block:
free: start=0x08049b00 length=(17 [0x11])
free: flags: 0x0 (none)
free: malloc PC=0x40021739 [/.../malloc_wrappers_dlopen.c]
free: main PC=0x0804871b [../free_prob.c]
free: __libc_start_main PC=0x40140647 [/lib/i686/libc.so.6]
free: _start PC=0x080485e1 [/.../free_prob]
 
free: address passed to heap manager: 0x08049b08