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