tvscript Command Syntax

The syntax for the tvscript command is:

tvscript [ options ] [ filename ] [ -a program_args ]

options

TotalView and tvscript command-line options. You can use any options described in Chapter 7, “TotalView Command Syntax”. tvscript command-line options are described in the next section.

filename

The program being debugged.

-a program_args

Program arguments.

The command-line options most often used with tvscript are:

-mpi (The MPI environments supported are those listed in the Parallel tab of the File > New Program dialog box.)

-starter_args

-nodes

-np or -procs or -tasks

For more information on these command-line options, see Chapter 7, “TotalView Command Syntax”.

Blue Gene/L and
Blue Gene/P

The syntax for using tvscript with an MPI on Blue Gene/L and Blue Gene/P systems is:

tvscript [ options ] -mpi BlueGene - np number-of-instances -starter_args
          "filename [ mpi-arguments] [-args program_args]" mpirun

-np number-of-instances

The number of processes or tasks that the starter program will create.

-starter_args

Required, with the arguments following enclosed in quotes; the application executable (filename) to be debugged must be the first argument.

-mpi-arguments

The command arguments for mpirun, such as "-cwd",
"-mode", and "-partition".

-args

Command argument for mpirun that passes to the launched application on the compute node.

mpirun

Required; the executable at the end of the command line.

Blue Gene/Q with SLURM

The syntax for using tvscript with an MPI on Blue Gene/Q systems using SLURM is:

tvscript [ options ] -mpi BlueGeneQ-SLURM - np number-of-instances -starter_args
          "[srun-arguments] filename [program_args]" srun

-np number-of-instances

The number of processes or tasks that the starter program will create.

-starter_args

Required, with the arguments following enclosed in quotes; the application executable (filename) to be debugged must follow the arguments for srun.

srun-arguments

The command arguments for srun.

filename

The program being debugged.

program_args

The arguments for the program being debugged.

srun

Required; the executable at the end of the command line.

 

Blue Gene/Q for ANL's Cobalt Job Manager and IBM’s runjob

The syntax for using tvscript on Blue Gene/Q for ANL's Cobalt job manager and IBM's runjob: is:

tvscript [ options ] -mpi BlueGeneQ-Cobalt - np number-of-ranks -starter_args
          "[runjob-arguments] : filename [program_args]" runjob

-np number-of-ranks

The number of processes or tasks that the starter program will create.

-starter_args

Required, with the arguments following enclosed in quotes; the application executable (filename) to be debugged must follow the arguments for runjob and be separated by a colon (:).

runjob-arguments

The command arguments for runjob.

filename

The program being debugged.

program_args

The arguments for the program being debugged.

runjob

Required; the executable at the end of the command line.

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

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.

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 [ -level level-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 Chapter 14 “Examining Arrays” in the TotalView User Guide.

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

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.