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 29. 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:

 

-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:

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