Totalview® for HPC Reference Guide : PART I Using the CLI : Chapter 4 Batch Debugging Using tvscript : tvscript Command Syntax : tvscript Options
tvscript Options
-create_actionpoint "source_location_expr [=>action1[, action2]...]"
Creates an action point at a source location using an expression. (See "Action Point API"for writing expressions.) When the action point is hit, tvscript can trigger one or more actions. Add one ‑create_actionpoint command-line option for each action point.
See ‑event_action for information about actions.
-event_action "event_action_list"
Performs an action when an event occurs. Events represent an unanticipated condition, such as free_not_allocated in the Memory Debugger. You can use more than one ‑event_action command-line option when invoking tvscript.
Here is how you enter an event_action_list :
event1=action1,event2=action2
or
event1=>action1,action2,action3
 
Table 3: Supported tvscript Events
Event Type
Event
Definition
General event
any_event
A generated event occurred.
Memory debugging event
addr_not_at_start
Program attempted to free a block using an incorrect address.
alloc_not_in_heap
The memory allocator returned a block not in the heap; the heap may be corrupt.
 
alloc_null
An allocation either failed or returned NULL; this usually means that the system is out of memory.
 
alloc_returned_bad_alignment
The memory allocator returned a misaligned block; the heap may be corrupt.
 
any_memory_event
A memory event occurred.
 
bad_alignment_argument
Program supplied an invalid alignment argument to the heap manager.
 
double_alloc
The memory allocator returned a block currently being used; the heap may be corrupt.
 
double_dealloc
Program attempted to free an already freed block.
 
free_not_allocated
Program attempted to free an address that is not in the heap.
 
guard_corruption
Program overwrote the guard areas around a block.
 
hoard_low_memory_threshold
Hoard low memory threshold crossed.
 
realloc_not_allocated
Program attempted to reallocate an address that is not in the heap.
 
rz_overrun
Program attempted to access memory beyond the end of an allocated block.
 
rz_underrun
Program attempted to access memory before the start of an allocated block.
 
rz_use_after_free
Program attempted to access a block of memory after it has been deallocated.
 
rz_use_after_free_overrun
Program attempted to access memory beyond the end of a deallocated block.
 
rz_use_after_free_underrun
Program attempted to access memory before the start of a deallocated block.
 
termination_notification
The target is terminating.
Source code debugging event
actionpoint
A thread hit an action point.
 
error
An error occurred.
Reverse debugging
stopped_at_end
The program is stopped at the end of execution and is about to exit.
 
For each occurring event, define the action to perform:
Action Type
Action
Definition
Memory debugging actions
check_guard_blocks
Checks all guard blocks and write violations into the log file.
list_allocations
Writes a list of all memory allocations into the log file.
list_leaks
Writes a list of all memory leaks into the log file.
save_html_heap_status_source_view
Generates and saves an HTML version of the Heap Status Source View Report.
save_memory_debugging_file
Generates and saves a memory debugging file.
save_text_heap_status_source_view
Generates and saves a text version of the Heap Status Source View Report.
Source code debugging actions
display_backtrace
[‑levellevel-num]
[ num_levels ]
[ options]
Writes the current stack backtrace into the log file.

-level level-num sets the level at which information starts being logged.

num_levels restricts output to this number of levels in the call stack.

If you do not set a level, tvscript displays all levels in the call stack.

options is one or more of the following:
-[no]show_arguments
-[no]show_fp
-[no]show_fp_registers
-[no]show_image
-[no]show_locals
-[no]show_pc
-[no]show_registers
 
print [ ‑slice {slice_exp}]
{variable | exp}
Writes the value of a variable or an expression into the log file. If the variable is an array, the -slice option limits the amount of data defined by slice_exp. A slice expression is a way to define the slice, such as var[100:130]in C and C++. (This displays all values from var[100]to var[130].) To display every fourth value, add an additional argument; for example,var[100:130:4]. For additional information, see “Examining Arrays”.
Reverse debugging actions
enable_reverse_debugging
Turns on ReplayEngine reverse debugging and begins recording the execution of the program.
 
save_replay_recording_file
Saves a ReplayEngine recording file. The filename is of the form <ProcessName>-<PID>_<DATE>.<INDEX>.recording.
-display_specifiers "display_specifiers_list"
By default, tvscript writes all of the information in the following table to the log file. You can exclude information by using one of the following specifiers:
Type of Specifier
Specifier
Display ...
General display specifiers
noshow_fp
Does not show the frame pointer (FP)
noshow_image
Does not show the process/library in backtrace
noshow_pc
Does not show the program counter (PC)
noshow_pid
Does not show the system process ID with process information
noshow_rank
Does not show the rank of a process, which is shown only for a parallel process
noshow_tid
Does not show the thread ID with process information
Memory debugging display specifiers
noshow_allocator
Does not show the allocator for the address space
noshow_backtrace
Does not show the backtraces for memory blocks
noshow_backtrace_id
Does not show the backtrace ID for memory blocks
noshow_block_address
Does not show the memory block start and end addresses
noshow_flags
Does not show the memory block flags
noshow_guard_id
Does not show the guard ID for memory blocks
noshow_guard_settings
Does not show the guard settings for memory blocks
noshow_leak_stats
Does not show the leaked memory block statistics
noshow_owner
Does not show the owner of the allocation
noshow_red_zones_settings
Does not show the Red Zone entries for allocations (and deallocations) for the address space
-memory_debugging
Enables memory debugging and memory event notification. This option is required with any option that begins with -mem. These options are TotalView command line options, as they can be invoked directly by TotalView.
-mem_detect_leaks
Performs leak detection before generating memory information.
-mem_detect_use_after_free
Tests for use after memory is freed.
-mem_guard_blocks
Adds guard blocks to an allocated memory block.
-mem_hoard_freed_memory
Holds onto freed memory rather than returning it to the heap.
-mem_hoard_low_memory_threshold nnnn
Sets the low memory threshold amount. When memory falls below this amount, an event is fired.
-mem_paint_all
Paints memory blocks with a bit pattern when a memory is allocated or deallocated.
-mem_paint_on_alloc
Paints memory blocks with a bit pattern when a memory block is allocated.
-mem_paint_on_dealloc
Paints memory blocks with a bit pattern when a memory block is deallocated.
-mem_red_zones_overruns
Turns on testing for Red Zone overruns.
-mem_red_zones_size_ranges min:max,min:max,...
Defines the memory allocations ranges for which Red Zones are in effect. Ranges can be specified as follows:
x:y allocations from x to y
:y allocations from 1 to y
x: allocations of x and higher
x allocation of x
-mem_red_zones_underruns
Turns on testing for Red Zone underruns.
-maxruntime "hh:mm:ss"
Specifies how long the script can run.
-script_filescript_file
Names a file containing tvscript API calls and Tcl callback procedures that you create.
-script_log_filename logFilename
Overrides the name of the TVScript log file.
WARNING: Previous log files of the same name are overwritten.
-script_summary_log_filename summaryLogFilename
Overrides the name of the TVScript summary log file.
WARNING: Previous summary log files with the same name are overwritten.
-replay
Enables reverse debugging with ReplayEngine on the process through tvscript. The entire program’s execution is recorded. To turn on recording for a tvscript event, use the enable_reverse_debugging action.
tvscript Example:
The following example is similar to that shown in "Batch Debugging Using tvscript".
tvscript \
-create_actionpoint "method1=>display_backtrace -show_arguments" \
-create_actionpoint "method2#37=>display_backtrace \
-show_locals -level 1" \
-event_action "error=>display_backtrace -show_arguments \
-show_locals" \
-display_specifiers "noshow_pid,noshow_tid" \
-maxruntime "00:00:30" \
filterapp -a 20
This script performs the following actions:
Creates an action point at the beginning of method1. When tvscript reaches that breakpoint, it logs a backtrace and the method’s arguments.
Creates an action point at line 37 of method2. When tvscript reaches this line, it logs a backtrace and the local variables. The backtrace information starts at level 1.
Logs the backtrace, the current routine’s arguments, and its local variables when an error event occurs.
Excludes the process ID and thread ID from the information that tvscript logs.
Limits tvscript execution time to 30 seconds.
Names the program being debugged and passes a value of 20 to the application.
tvscript Reverse Debugging Example:
tvscript \
-create_actionpoint "main=>enable_reverse_debugging" \
-event_action "stopped_at_end=>save_replay_recording_file" \
filterapp
This script performs the following actions:
Creates an action point on method main. When the action point is hit, reverse debugging is enabled and recording of the program begins.
Specifies that the recording file is to be saved if the stopped_at_end event is raised.