Debugging Memory Problems with MemoryScape : Chapter 1 Locating Memory Problems : Batch Scripting and Using the CLI : Using the -dheap Command : dheap
dheap
The command dheap controls heap debugging
Shows MemoryScape state
dheap [ -status ]
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 MemoryScape
dheap { -enable | -disable }
Enables or disables event notification
dheap -event_filter [ subcommands ]
Writes memory information
dheap -export [ subcommands ]
Specifies which filters MemoryScape uses
dheap -filter [ 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 MemoryScape information
dheap -info [ subcommands ]
Indicates whether an address is in a deallocated block
dheap -is_dangling address
Locates memory leaks
dheap -leaks [ -[no]check_interior ]
Enables or disables MemoryScape 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 subcommand [ start_address [ end_address ] ]
Displays MemoryScape 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 if TotalView will notify you if a notifiable heap event occurs. If TotalView stops a thread because one of these events occur, it displays information about this event.
If you do not use other options to the dheap command, you can omit this option.
-enable/-disable
The option -enable tells TotalView to use the MemoryScape agent to record heap events the next time you start the program. The -disable option tells TotalView not to use the agent the next time you start your program.
If necessary, you must preload the agent (see Chapter 4, “Creating Programs for Memory Debugging,” for information) before using this option.
-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 (described later in this section).
[ -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 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 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
  -data { alloc | dealloc | hoard | leaks }
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
  -output { directory | filename }
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.
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.
[ -status ]
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.
-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. 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
-reset_notify event-list
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.
-export required_subcmds [ optional_subcmds ]
Writes information to a file.
required_subcmds
When exporting data, you must use the -data and -output options with dheap -export:
  -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 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.
  -output filename
Names the file to which TotalView writes memory information.
optional_subcmds
You can optionally use any of the following options with dheap -export:
  -[no]check_interior
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.
  -format { html| text }
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.
  -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 raw data format, MemoryScape ignores this option.
  -set_show_backtraces { on | off }
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.
  -set_show_code { on | off }
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.
  -view backtrace
Tells MemoryScape to export a backtrace view instead of a source view. If you also use the raw data format, MemoryScape ignores this option.
-filter subcommands
Use the -filter options to enable, disable, and show information about filtering.
-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 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.
-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 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.
-guard subcommands [ start_address [ end_address ] ]
Use the -guard options to enable, disable, set characteristics, and show information about guard blocks.
[ -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
Checks the guards to see if they have been violated. If it finds a violated guard, MemoryScape displays information.
-reset
Resets the guards to MemoryScape’s default value. You can create your own default 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 made and restores guard settings to what they were when you first invoked MemoryScape.
-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.
-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) indicates that MemoryScape does not 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 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.
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 type 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 type a subcommand, MemoryScape displays information about the hoarded blocks. For more information, see Memory Reuse: dheap -hoard”.
[ -status ]
Displays hoard settings. Information displayed indicates if hoarding is enabled, if 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 value.
-set_all_deallocs { on | off }
Tells MemoryScape whether to hoard deallocated blocks.
-reset_all_deallocs
Resets MemoryScape settings for hoarding of deallocated blocks to its initial value.
-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.
-info [ subcommand ] [ 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.
-show_backtrace
Displays backtrace information. This list can be very long.
-show_backtrace_id
Adds backtrace IDs to the information it displays.
-show_guard_settings
Adds information about guards settings to the information it displays.
-[no]show_allocater_id
-[no]show_owner_id
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.
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
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”.
-nocheck_interior
-check_interior
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.
-[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 type the -nonotify option, TotalView tracks heap events.
-paint [ subcommands ]
Enables and disables block painting and shows status information. (For more information on block painting, see Block Painting: dheap -paint”.)
[ -status ]
Shows the current paint settings. These are either the values you set using other painting options or their default values.
If you do not use a subcommand to the -paint option, MemoryScape shows the block painting status information.
-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 typed 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]
Enables or disables the ability to catch bounds errors and use-after-free errors retaining freed memory blocks.
Please note that the abbreviation -rz can be used for -red_zones in the CLI.
-status[-all]
Shows the current HIA Red Zones 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. -reset 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 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:
*dheap -red_zones -set_mode 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.
*dheap -red_zones -set_mode 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.
*dheap -red_zones -set_mode 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.
*dheap -red_zones -set_mode 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_pre_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 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.
-set_alignment integer
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.
-set_fence_size integer
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.
-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 ]
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.
-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 Deallocation Notification: dheap -tag_alloc”.)
When tagging memory, if you do not specify address arguments, MemoryScape either tags all allocated blocks or removes the tag from all tagged blocks.
-[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 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.
-[no]notify_dealloc
-[no]notify_realloc
Enable or disable notification when your program deallocates or reallocates a memory block.
start_address
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.
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 type 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.
[ -status ]
Displays the current verbosity setting. If you do not use other verbosity options, you can omit this option.
-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 TVHEAP_ARGS”.
-version
Displays the MemoryScape version number.
Description: 
The dheap command controls MemoryScape. MemoryScape can:
*Tell TotalView 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. For more information, see Notification When free Problems Occur”.
*Hoard freed memory so that it is not released to the heap manager. For more information, see Memory Reuse: dheap -hoard”.
*Write heap information to a file. For more information, see Writing Heap Information: dheap -export”.
*Remove unwanted information from displays. For more information, see Filtering Heap Information: dheap -filter”.
*Use guard blocks. After MemoryScape writes guard blocks, you can ask it to tell you if blocks are violated. For more information, see Guarding Memory Blocks: dheap -guards”.
*Detect leaked memory by analyzing if a memory block is reachable. For more information, see Detecting Leaks: dheap -leaks”.
*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. For more information, see Block Painting: dheap -paint”.
*Use Red Zones to detect bounds and use-after-free errors. For more information, see Red Zones Bounds Checking: dheap -red_zones”.
*Notify you when your program deallocates or reallocates a memory block. For more information, see Deallocation Notification: dheap -tag_alloc”.
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 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 exists by using the dheap -notify command.
*A block is deallocated by using the dheap -tag_alloc -notify_dealloc command.
*A block is reallocated by using the dheap -tag_alloc -notify_realloc command.
If you enable notification, TotalView stops the process when it detects one of these events. MemoryScape is always monitoring heap events, even if you turned notification off. That is, disabling notification means that TotalView does not stop a program when events occur. In addition, it does not tell you that the event 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 creates, it is the only process where TotalView 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 simply attaches to them. For more information, see Chapter 4, “Creating Programs for Memory Debugging,” .
If you do not use a dheap subcommand, the CLI displays memory status information. You 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
While some dheap options obtain information on specific memory conditions, you can use the following options throughout your session:
*dheap or dheap -status: Displays MemoryScape state information. For example:
a1.<> dheap -status
process: Enable Notify Available
1 (18868): yes yes yes
2 (18947): n/a yes yes
3 (18953): n/a yes yes
4 (18956): n/a yes yes
*dheap -version: Displays version information. You receive information for each process as processes can be compiled with different versions of MemoryScape. For example:
a1.<> dheap -version
process: Version
1 (18868): 1.001
2 (18947): 1.001
3 (18953): 1.001
4 (18956): 1.001
*dheap -backtrace: Displays information about how much of the backtrace MemoryScape displays. For example:
a1.<> dheap -backtrace
process: Depth Trim
1 (18868): 32 5
2 (18947): 32 5
3 (18953): 32 5
4 (18956): 32 5
Using arguments to this command, you can change both the depth and the trim values. Changing the depth value changes the number of stack frames that MemoryScape displays in a backtrace display. Changing the trim value eliminates the topmost stack frames.
*dheap -info: Displays information about currently allocated memory blocks. For example:
d1.<> dheap -info
process 1 (5320):
0x8049790 -- 0x804979a 0xa [ 10]
flags: 0x0 (none)
0x80497a0 -- 0x80497b4 0x14 [ 20]
flags: 0x0 (none)
0x80497b8 -- 0x80497d6 0x1e [ 30]
flags: 0x0 (none)
0x80497e0 -- 0x8049808 0x28 [ 40]
flags: 0x0 (none)