tvscript Options
-create_actionpoint "source_location_expr [=>action1[, action2]...]"
Creates an action point at a source location using an expression. (See Action Point APIfor 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
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.
