Creating or Loading a Session
totalview -load_session session_name
Creates a process based on the session values. Sessions that attach to an existing process cannot be loaded this way; use the -pid command line option instead
CLI: totalviewcli dsession -load session_name |
Debugging a Program
totalview executable
Starts TotalView and loads the executable program.
CLI: totalviewcli executable |
If you installed TotalView on a Macintosh using the application bundle, you can drag your program’s executable to the TotalView icon on your desktop.
If you type an executable name, TotalView remembers that name and many of its arguments.
Debugging a Core File
totalview executable corefiles
Starts TotalView and loads the executable program and one or more associated core-files.
CLI: dattach -c core-files -e executable |
The core-files argument represents one or more core files associated with this executable. You can use wild cards in the core file names.
Debugging with a Replay Recording File
totalview executable recording-file
Starts TotalView and loads the executable program and an associated recording-file. The recording file was saved in a previous debugging session that used the Replay feature, and restores the state of that debugging session, including all Replay information.
CLI: dattach -c recording-file -e executable |
Passing Arguments to the Program Being Debugged
totalview executable -a args
Starts TotalView and passes all the arguments following the -a option to the executable program. When using the -a option, it must be the last TotalView option on the command line.
CLI: totalviewcli executable -a args |
If you don’t use the -a option and you want to add arguments after TotalView loads your program, add them either using either the File > Debug New Program dialog box or use the Process > Startup command.
CLI: dset ARGS_DEFAULT {value} |
totalview -args executable args
Similar to above, but uses the command line option -args to specify that the executable program and arguments follow.
CLI: totalviewcli -args executable args |
Debugging a Program Running on Another Computer
totalview executable -remote hostname_or_address[:port]
Starts TotalView on your local host and the tvdsvr command (which implements and controls debugging on remote machines) on a remote host. After TotalView begins executing, it loads the program specified by executable for remote debugging. You can specify a host name or a TCP/IP address. If you need to, you can also enter the TCP/IP port number.
CLI: totalviewcli executable
-r hostname_or_address[:port] |
If TotalView fails to automatically load a remote executable, you may need to disable
autolaunching for this connection and manually start the
tvdsvr. (
Autolaunching is the process of automatically launching
tvdsvr processes.) To disable autolaunching, add the
hostname:portnumber suffix to the name entered in the
Debug on Host field of the
File > Debug New Program dialog box. As always, the
portnumber is the TCP/IP port number on which TotalView server is communicating with TotalView. See
Starting the TotalView Server Manually for more information.
NOTE: TotalView Individual does not allow remote debugging.
Debugging an MPI Program
The exact details for starting the debugger on an MPI program vary greatly from system to system, so consult with your local system documentation for details. The following are generic examples that may or may not work on your specific system.
totalview
Method 1: In many cases, you can start an MPI program in much the same way as you would start any other program. However, you need to select A New Parallel program from the Start a Debugging Session dialog box, and enter the MPI version and other information on the parallel program to debug.
totalview -args mpirun mpirun-args
Method 2: Invokes TotalView on the MPI starter program mpirun. The mpirun-args are the arguments to pass to the MPI starter program, such as the number of processes, number of nodes, the name of the MPI application program to debug, and arguments for the application. For example:
totalview -args mpirun -np 4 ./myMPIprog myDataFile
mpirun -np count -tv executable
Method 3: The MPI mpirun command starts the TotalView executable pointed to by the TOTALVIEW environment variable. TotalView then starts your program. This program runs using count processes.
Starting TotalView on a Script
It is sometimes convenient to start TotalView on a shell script. For example, a typical use case might be a script that calls into a shared library, and you need to debug the shared library code; another case is a shell script that sets environment variables, then execs the application to debug.
Anywhere in the examples above that an executable can be specified, an interpreter script can be specified instead. The underlying interpreter, which must be a valid executable object file for the platform, is debugged, not the script itself.
On Unix, an interpreter script starts with a line that is similar to the following:
#! interpreter [ interpreter-arg ]
Where:
#! are the first two characters in the file.
interpreter is the path to an executable object file or some other interpreter script.
interpreter-arg is an optional argument to pass to the interpreter.
When the interpreter script is executed, the interpreter is invoked by the system as follows:
interpreter [ interpreter-arg ] script [ script-args ]
Here's a simple example:
% cat myscript.sh
#! /bin/sh -x
echo "$@"
% ./myscript.sh a b c
+ echo a b c
a b c
%
In the example above, the following command was executed:
/bin/sh -x ./myscript.sh a b c
Whenever TotalView is processing an executable file, it first checks to see if the file is an interpreter script. If the file starts with #!, it is treated as an interpreter script. The path to the interpreter is extracted from the script and used as the executable object file to debug. If the interpreter file is itself an interpreter script, TotalView repeats the procedure (up to 40 times) until it encounters an interpreter file that is not an interpreter script. If the procedure fails to find a valid executable object file for the platform, loading the script into the debugger will fail.
In most cases, the interpreter for the script does not directly contain the code you want to debug, and instead dynamically loads or executes the code to debug. TotalView contains several configuration settings that make it easier to plant breakpoints and stop in your code, as described by the Related Topics below. There are three common cases, where the interpreter script:
— Dynamically loads a shared library and calls into the code to debug (see the entries below regarding dynamic library handling and creating pending breakpoints)
— Execs the program containing the code to debug (relevant to exec handling)
— Runs the program containing the code to debug (relevant to fork handling)
.
