Totalview® for HPC Reference Guide : PART II Running TotalView : Chapter 7 TotalView Command Syntax : Command-Line Options
Command-Line Options
-a args
Pass all subsequent arguments (specified by args) to the program specified by filename. This option must be the last one on the command line.
-aix_use_fast_ccw
Defined only on AIX, a synonym for the platform-independent -use_fast_wp, for TotalView script backward compatibility . See -use_fast_wp for more information.You must set this option on the command line; you cannot set it interactively using the CLI.
-aix_use_fast_trap
Defined only on AIX, a synonym for the platform-independent -use_fast_trap, for TotalView script backward compatibility. See -use_fast_trap for more information. You must set this option on the command line; you cannot set it interactively using the CLI.
-args filename [args]
Specifies filename as the executable to debug, with args as optional arguments to pass to your program. This option must be listed last on the command line. You can also use --args instead of -args, for compatibility with other debuggers.
-background color
Sets the general background color to color.
-bg color
Same as -background.
Default: light blue
-bluegene_q_user_threads
Enables handling of user-level (M:N) thread packages on BlueGene/Q systems.
-no_bluegene_q_user_threads
(Default) Disables handling of user-level (M:N) thread packages, improving startup performance at high scale. There is usually a 1:1 correspondence between user-level threads and kernel-level threads on BlueGene/Q systems.
-compiler_vars
(Alpha, HP, and SGI only.) Shows variables created by the Fortran compiler, as well as those in the user’s program.
Some Fortran compilers (HP f90/f77, HP f90, SGI 7.2 compilers) output debugging information that describes variables the compiler itself has invented for purposes such as passing the length of character*(*) variables. By default, TotalView suppresses the display of these compiler-generated variables.
However, you can specify the -compiler_vars option to display these variables. This is useful when you are looking for a corruption of a run-time descriptor or are writing a -compiler.
-no_compiler_vars
(Default) Tells TotalView that it should not show variables created by the Fortran compiler.
-control_c_quick_shutdown-ccq
(Default) Tells TotalView to kills attached processes and exits.
-no_control_c_quick_shutdown -nccq
Invokes code that sometimes allows TotalView to better manage the way it kills parallel jobs when it works with management systems. This has only been tested with SLURM. It may not work with other systems.
-cuda
(Default) Enables CUDA debugging with TotalView.
-no_cuda
Disables CUDA debugging. Any CUDA kernels launched on a GPU device are not seen by the debugger, so the debugger can only debug the host code. -nocuda is the identical command.
-dbfork
(Default) Catches the fork(), vfork(), and execve() system calls if your executable is linked with the dbfork library.
-no_dbfork
Tells TotalView that it should not catch fork(), vfork(), and execve() system calls even if your executable is linked with the dbfork library.
-debug_file console_outputfile
Redirects TotalView console output to a file named console_outputfile.
If consoleoutputfile is the string UNIQUE, the filename tv_dump.hostname.pid is used. If console_outputfile contains the string '$$' (note the escaping single quotes), hostname.pid is substituted. UNIQUE and '$$' are useful for separating the console output when running multiple tvdsvr processes.
All TotalView console output is written to stderr.
-default_parallel_attach_subset subset_specification
Specifies a set of MPI ranks to be attached to when an MPI job is created or attached to. The subset_specification is a space-separated list, the elements of which can be in one of these forms:
rank: that rank only
rank1-ranks2: all ranks between rank1 and rank2 inclusive
rank1-rank2:stride: every strideth rank between rank1 and rank2
A rank must be either a positive decimal integer or max (the last rank in the MPI job).
A subset_specification that is the empty string ("") is equivalent to 0-max.
The default_parallel_attach_subset is used to initialize the -parallel_attach_subset property of an MPI starter process, which can be get or set in the CLI using:
TV::process get dpid parallel_attach_subset
TV::process set dpid parallel_attach_subset -subset_specification
The CLI dattach and dload -parallel_attach_subset -subset_specification overrides the default_parallel_attach_subset and sets the parallel_attach_subset property of the process being attached or loaded.
-demangler=compiler
Overrides the demangler and mangler TotalView uses by default. The following indicate override options.
-demangler=compaq HP cxx on Linux (alpha)
-demangler=gnu GNU C++ on Linux Alpha
-demangler=gnu_dot GNU C++ on Linux x86
-demangler=gnu_v3 GNU C++ Linux x86
-demangler=kai KAI C++
-demangler=kai3_n KAI C++ version 3.n
-demangler=kai_4_0 KAI C++
-demangler=spro SunPro C++ 4.0 or 4.2
-demangler=spro5 SunPro C++ 5.0 or later
-demangler=sun Sun CFRONT C++
-demangler=xlc IBM XLC/VAC++ compilers
-display displayname
Set the name of the X Windows display to displayname. For example, -display vinnie:0.0 will display TotalView on the machine named “vinnie.”
Default: The value of your DISPLAY environment variable.
-dll_ignore_prefix list
The colon-separated argument to this option tells TotalView that it should ignore files having this prefix when making a decision to ask about stopping the process when it dlopens a dynamic library. If the DLL being opened has any of the entries on this list as a prefix, the question is not asked.
-dll_stop_suffix list
The colon-separated argument to this option tells TotalView that if the library being opened has any of the entries on this list as a suffix, it should ask if it should open the library.
-dlopen_always_recalculate
(Default). Reevaluates breakpoint specifications on every dlopen call.
-no_dlopen_always_recalculate
Enables dlopen event filtering, deferring the reevaluation of breakpoint specifications until after the dlopen event. The point at which the breakpoint specifications are reevaluated depends on the value of the TV::dlopen_recalculate_on_match variable (see dlopen_recalculate_on_match glob-list).
This setting impacts scalability in HPC computing environments. For details, see "Filtering dlopen Events".
dlopen_recalculate_on_match glob-list
Default: "" (the empty string)
This option’s argument is a colon-separated list of simple glob patterns used to compare and match the dlopened library. A simple glob pattern is a string, optionally ending with asterisk character ('*'). For information on the semantics of glob pattern matching, see TV::dlopen_recalculate_on_match.
Used with ‑no_dlopen_always_recalculate, when a dlopen event occurs, the name of the dlopened library is matched against the list of glob patterns; if the glob-list is empty (the default) or the name of the dlopened library does not match the glob-list, then breakpoint reevaluation is deferred until the process stops for some other reason (e.g., the process hits a breakpoint, the user stops the process, the process encounters a signal, etc.).
If the library name matches a pattern, the breakpoints are reevaluated immediately.
-dlopen_read_libraries_in_parallel
Enables dlopen events to be handled in parallel, reducing client/server communication overhead by using MRNet to fetch the library information.
-no_dlopen_read_libraries_in_parallel
(Default). Disables handling dlopened events in parallel.
This setting impacts scalability in HPC computing environments. For details, see "Handling dlopen Events in Parallel".
-dump_core
Allows TotalView to dump a core file of itself when an internal error occurs. This is used to help Rogue Wave Software debug problems.
-e commands
Tells TotalView to immediately execute the CLI commands named within this argument. All information you enter here is sent directly to the CLI’s Tcl interpreter. For example, the following writes a string to stdout:
cli -e 'puts hello'
You can have more than one -e option on a command line.
-ent
Tells TotalView that it should only use an Enterprise license.
-no_ent
Tells TotalView that it should not use an Enterprise license. You may combine this with -no_team or --‑noteamplus.
-env variable=value
Tells TotalView to add an environment variable to the environment variables passed to your program by the shell. If the variable already exists, it effectively replaces the previous value. You need to use this command for each variable being added; that is, you cannot add more than one variable with an env command.
-foreground color
Sets the general foreground color (that is, the text color) to color.
-fg color
Same as -foreground.
Default: black
-f9x_demangler=compiler
Overrides the Fortran demangler and mangler TotalView uses by default. The following indicate override options.
-demangler=spro_f9x_4 SunPro Fortran, 4.0 or later
-demangler=xlf IBM Fortran
-global_types
(Default) Lets TotalView assume that type names are globally unique within a program and that all type definitions with the same name are identical. The C++ standard asserts that this must be true for standard-conforming code.
If this option is set, TotalView will attempt to replace an opaque type (struct foo *p;) declared in one module, with an identically named defined type in a different module.
If TotalView has read the symbols for the module containing the non-opaque type definition, then when displaying variables declared with the opaque type, TotalView will automatically display the variable by using the non-opaque type definition.
-no_global_types
Specifies that TotalView cannot assume that type names are globally unique in a program. You should specify this option if your code has multiple different definitions of the same named type, since otherwise TotalView can use the wrong definition for an opaque type.
-gnu_debuglink
Tells TotalView that if a program or library has a .gnu_debug_link section, it should look for a gnu_debug_link file. If found, TotalView reads the debugging information from this file.
-no_gnu_debuglink
Do not load information from a gnu_debug_link file even if the file has a .gnu_debug_link section.
-gnu_debuglink_checksum
Tells TotalView that it should validate the gnu_debug_link file’s checksum against the checksum contained in the process’s .gnu_debuglink section.
-no_gnu_debuglink_checksum
Do not compare checksums. Only do this if you are absolutely certain that the debug file matches.
-ipv6_support
Directs TotalView to support IPv6 addresses.
-no_ipv6_support
(Default) Do not support IPv6 addresses.
-kcc_classes
(Default) Converts structure definitions output by the KCC compiler into classes that show base classes and virtual base classes in the same way as other C++ compilers. See the description of the TV::kcc_classes variable for a description of the conversions that TotalView performs.
-no_kcc_classes
Specifies that TotalView will not convert structure definitions output by the KCC compiler into classes. Virtual bases will show up as pointers, rather than as data.
-lb
(Default) Loads action points automatically from the filename.TVD.v3breakpoints file, providing the file exists.
-nlb
Tells TotalView that it should not automatically load action points from an action points file.
-load_session session_name
Loads into TotalView the session named in session_name. If the preference “Show Startup Parameters when TotalView starts” is set, this option launches the Session Manager’s Program Session screen where you can edit the session’s properties and then launch the session; otherwise, the option immediately loads the session into TotalView, launching the Root and Process windows. Session names with spaces must be enclosed in quotes, for example, "my debug session". Sessions that attach to an existing process cannot be loaded using this option; rather, use the -pid option instead.
-local_interface string
Sets the interface name that the server uses when it makes a callback. For example, on an IBM PS2 machine, you would set this to css0. However, you can use any legal inet interface name. (You can obtain a list of the interfaces if you use the netstat -i command.)
-memory_debugging
Enables memory debugging. By adding the following suboptions, you enable that particular feature using its the feature’s default configuration. In most cases, you will want to use one or more of the following sub-options.
-mem_detect_use_after_free
Tests for memory use after memory is freed.
-mem_detect_use_after_free
Tests for memory use after memory is freed.
-mem_guard_blocks
Surrounds allocated memory blocks with guard blocks.
-mem_hoard_freed_memory
Tells the Memory Debugger to hoard memory blocks instead of releasing them when a free() routine is called.
-mem_hoard_low_memory_threshold nnnn
Sets the low memory threshold amount. When memory falls below this amount an event will be fired.
-mem_notify_events
Turns on memory event notification.
-no_mem_notify_events turns event notification off.
-mem_paint_all
Paint both allocated and deallocated blocks with a bit pattern.
-mem_paint_on_alloc
Paint memory blocks with a bit pattern when they are allocated.
-mem_paint_on_dealloc
Paint memory blocks with a bit pattern when they are freed.
-mem_red_zones_overruns
Turn on testing for Red Zones 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
Turn on testing for Red Zones underruns.
-message_queue
(Default) Enables the display of MPI message queues when debugging an MPI program.
-mqd
Same as -message_queue.
-mqd
Same as -message_queue.
-no_message_queue
Disables the display of MPI message queues when you are debugging an MPI program. This might be useful if something is overwriting the message queues and causing TotalView to become confused.
-no_mqd
Same as -no_message_queue.
-mpi starter
Names the MPI that your program requires. The list of starter names that you enter are those that appear in the Parallel system pull down list contained within the New Program’s Parallel tab. If the starter name has more than one word (for example, Open MPI), enclose the name in quotes. For example:
-mpi "Open MPI"
-newUI
Launches the NextGen TotalView for HPC UI rather than TotalView’s traditional interface.
-nodes
Specifies the number of nodes upon which the MPI job will run.
-no_startup_scripts
Tells TotalView not to reference any initialization files during startup. Note that this negates all settings in all initialization files. Aliases are -nostartupscripts and -nss.
-nohand_cursor
By default, the cursor in the source pane of the process window turns into a hand cursor when hovering over an element you can dive on (a red box is also drawn around the applicable code). Specify this option to override this behavior and retain the usual arrow cursor.
-np
Specifies how many tasks that TotalView should launch for the job. This argument usually follows a -mpi command-line option.
-nptl_threads
Tells TotalView that your application is using NPTL threads. You only need use this option if default cannot determine that you are using this threads package.
-no_nptl_threads
Tells TotalView that you are not using the NPTL threads package. Use this option if TotalView thinks your application is using it and it isn’t.
-oldroot
Displays the Root Window used in versions prior to TotalView 8.15.0. Using ‑-oldroot or -‑newroot overrides the TV::GUI::old_root_window value.
-newroot
(Default) Displays the new Root Window. This is useful when TV::GUI::-old_root_window is set to true in the .tvdrc file and you wish to use the new Root Window.
-parallel
(Default) Enables handling of parallel program run-time libraries such as MPI, PE, and UPC.
-no_parallel
Disables handling of parallel program run-time libraries such as MPI, PE, and UPC. This is useful for debugging parallel programs as if they were single-process programs.
-parallel_attach option
Sets the action that TotalView takes when starting a parallel program. Possible options are:
yes (default) Attaches to all processes in a parallel program, unless the process being launched or attached to has a non-empty parallel_attach_subset property. In this case, only the subset of processes specified in the parallel_attach_subset are attached.
no Attaches to no processes in a parallel program.
ask Asks which processes to attach to by posting the subset attach dialog box if the debugger GUI is open.
This option works in concert with the parallel_attach_subset property (see -default_parallel_attach_subset) of an MPI starter process, which specifies a set of MPI tasks to attach to when the debugger launches or attaches to an MPI job.
Modifying this setting does not affect the parallel_attach_subset property itself.
-patch_area_base address
Allocates the patch space dynamically at address. See “Allocating Patch Space for Compiled Expressions” in the TotalView for HPC User Guide.
-patch_area_length length
Sets the length of the dynamically allocated patch space to this length. See “Allocating Patch Space for Compiled Expressions” in the TotalView for HPC User Guide.
-pid pid filename
Attaches to process pid for executable filename when TotalView starts executing.
-procs
Specifies how many tasks that TotalView should launch for the job. This argument usually follows a -mpi command-line option.
-processgrid
Displays the Processes/Ranks Tab in the Process Window. Note that enabling this tab can significantly affect performance, particularly for large, massively parallel applications.
-noprocessgrid (default)
Does not display the Processes/Ranks Tab in the Process Window. This command qualifier is helpful when you wish to disable the Processes/Ranks Tab for a debug session and you have TV::GUI::process_grid_wanted set to true in your .tvdrc file.
-remote hostname[:portnumber]
Debugs an executable that is not running on the same machine as TotalView. For hostname, you can specify a TCP/IP host name (such as vinnie) or a TCP/IP address (such as 128.89.0.16). Optionally, you can specify a TCP/IP port number for portnumber, such as :4174. When you specify a port number, you disable the autolaunch feature. For more information on the autolaunch feature, see “Setting Single Process Server Launch” in the TotalView for HPC User Guide.
-r hostname[:portnumber]
Same as -remote.
-replay
Enables the ReplayEngine when TotalView begins. This command-line option is ignored if you do not have a license for ReplayEngine.
-s pathname
Specifies the path name of a startup file that will be loaded and executed. This path name can be either an absolute or relative name.
You can add more than one -s option on a command line.
-serial device[:options]
Debugs an executable that is not running on the same machine as TotalView. For device, specify the device name of a serial line, such as /dev/com1. Currently, the only option you are allowed to specify is the baud rate, which defaults to 38400. For more information on debugging over a serial line, see “Debugging Over a Serial Line” in the TotalView for HPC Users Guide.
-search_path pathlist
Specify a colon-separated list of directories that TotalView will search when it looks for source files. For example:
totalview -search_path proj/bin:proj/util
-signal_handling_mode "action_list"
Modifies the way in which TotalView handles signals. You must enclose the action_list string in quotation marks to protect it from the shell.
An action_list consists of a list of signal_action descriptions separated by spaces:
signal_action[ signal_action] ...
A signal action description consists of an action, an equal sign (=), and a list of signals:
action=signal_list
An actioncan be one of the following: Error, Stop, Resend, or Discard, For more information on the meaning of each action, see Chapter 3 of the TotalView for HPC User Guide.
A signal_specifier can be a signal name (such as SIGSEGV), a signal number (such as 11), or a star (*), which specifies all signals. We recommend that you use the signal name rather than the number because number assignments vary across UNIX sessions.
The following rules apply when you are specifying an action_list:
(1) If you specify an action for a signal in an action_list, TotalView changes the default action for that signal.
(2) If you do not specify a signal in the action_list, TotalView does not change its default action for the signal.
(3) If you specify a signal that does not exist for the platform, TotalView ignores it.
(4) If you specify an action for a signal more than once, TotalView uses the last action specified.
If you need to revert the settings for signal handling to built-in defaults, use the Defaults button in the File > Signals dialog box.
For example, here’s how to set the default action for the SIGTERM signal to resend:
"Resend=SIGTERM"
Here’s how to set the action for SIGSEGV and SIGBUS to error, the action for SIGHUP to resend, and all remaining signals to stop:
"Stop=* Error=SIGSEGV,SIGBUS Resend=SIGHUP"
-shm "action_list"
Same as -signal_handling_mode.
-starter_args "arguments"
Tells TotalView to pass arguments to the starter program. You can omit the quotation marks if arguments is just one string without any embedded spaces.
-stderr pathname
Names the file to which TotalView writes the target program’s stderr information while executing within TotalView. If the file exists, TotalView overwrites it. If the file does not exist, TotalView creates it.
-stderr_append
Tells TotalView to append the target program’s stderr information to the file named in the -stderr command, specified in the GUI, or in the TotalView TV::default_stderr_filename variable. If the file does not exist, TotalView creates it.
-stderr_is_stdout
Tells TotalView to redirect the target program’s stderr to stdout.
-stdin pathname
Names the file from which the target program reads information while executing within TotalView.
-stdout pathname
Names the file to which TotalView writes the target program’s stdout information while executing within TotalView. If the file exists, TotalView overwrites it. If the file does not exist, TotalView creates it.
-stdout_append
Tells TotalView to append the target program’s stdout information to the file named in the -stdout command, specified in the GUI, or in the TotalView TV::default_stdout_filename variable. If the file does not exist, TotalView creates it.
-tasks
Specifies how many tasks that TotalView should launch for the job. This argument usually follows a -mpi command-line option.
-team
Tells TotalView that it should only use a Team license.
-no_team
Tells TotalView that it should not use an Enterprise license. You may combine this with -no_ent or -noteamplus.
-teamplus
Tells TotalView that it should only use a Team Plus license.
-no_teamplus
Tells TotalView that it should not use a Team PLus license. You may combine this with -no_ent or -noteam.
-tvhome pathname
The directory from which TotalView reads preferences and other related information and the directory to which it writes this information.
-use_fast_trap
Controls TotalView’s use of the target operating system’s support of the fast trap mechanism for compiled conditional breakpoints, also known as EVAL points. As of TotalView 8.7, when this was introduced, only AIX supported the fast trap mechanism for breakpoints, but we anticipate other operating systems adding support. You must set this option on the command line; you cannot set it interactively using the CLI.
Your operating system may not be configured correctly to support this option. See the TotalView for HPC Release Notes on our web site for more information.
-use_fast_wp
Controls TotalView’s use of the target operating system’s support of the fast trap mechanism for compiled conditional watchpoints, also known as CDWP points. As of TotalView 8.7, when this was introduced, only AIX supported the fast trap mechanism for watchpoints, but we anticipate other operating systems adding support. You must set this option on the command line; you cannot set it interactively using the CLI.
Your operating system may not be configured correctly to support this option. See the TotalView for HPC Release Notes on our web site for more information.
-user_threads
(Default) Enables handling of user-level (M:N) thread packages on systems where two-level (kernel and user) thread scheduling is supported. (Note: This option does not apply to -BlueGene/Q systems; instead, see -bluegene_q_user_threads.)
-no_user_threads
Disables handling of user-level (M:N) thread packages. This option may be useful in situations where you need to debug kernel-level threads, but in most cases, this option is of little use on systems where two-level thread scheduling is used.
-verbosity level
Sets the verbosity level of TotalView messages to level, which may be one of silent, error, warning, or info.
Default: info
-xterm_name pathname
Sets the name of the program used when TotalView needs to create a the CLI. If you do not use this command or have not set the TV::xterm_name variable, TotalView will attempt to create an xterm window.