dattach
Brings currently executing processes under TotalView control
Format
dattach [ -g gid ] [ -r hname ]
[ -ask_attach_parallel | -no_attach_parallel ]
[ -replay | -no_replay ]
[ -go | -halt ]
[ -e] executable [ pid-list ]
[ -c core-file | recording-file ] [-rank num ]
[ -parallel_attach_subset subset-specification ]
Arguments
-g gid
Sets the control group for the processes being added to group
gid. This group must already exist. (The CLI
GROUPS variable contains a list of all groups. See
GROUPS for more information.)
-r hname
The host on which the process is running. The CLI launches a TotalView Server on the host machine if one is not already running. See the
Setting Up Parallel Debugging Sessions chapter of the
TotalView User Guide for information on the launch command used to start this server.
Setting a host sets it for all PIDs attached to in this command. If you do not name a host machine, the CLI uses the local host.
-attach_parallel
Attaches to any additional parallel processes in a parallel job.
-ask_attach_parallel
Specifies that TotalView should ask before attaching to parallel processes of a parallel job. The default is to automatically attach to processes. For additional information, see the
Parallel Configuration in the
File > Preferences Dialog Box in the
TotalView User Guide.
If none of the attach_parallel switches is specified, and there is exactly one process ID in the process list, the user's preferences are used to determine whether to perform a parallel attach.
If none of the attach_parallel switches is specified, and there is more than one process ID in the process list, the default is -no_attach_parallel.
-no_attach_parallel
Does not attach to any additional parallel processes in a parallel job. For additional information, see the Parallel Page in the File > Preferences Dialog Box in the in-product helpfor Classic TotalView.
-replay | -no_replay
Enables or disables the ReplayEngine the next time the program is restarted. To enable, the feature must be supported and licensed on the current platform.
-go | -halt
Specifies to explicitly continue or halt target execution after attaching. The default is to leave the target's run state as it was before the attach.
-rank num
Specifies the rank associated with the executable being loaded. While this can be used independently, this option is best used with core files.
-e
Tells the CLI that the next argument is an executable file name. You need to use -e if the executable name begins with a dash (-) or consists of only numeric characters. Otherwise, you can just provide the executable file name.
executable
The name of the executable. Setting an executable here sets it for all PIDs being attached to in this command. If you do not include this argument, the CLI tries to determine the executable file from the process. Some architectures do not allow this to occur.
pid-list
A list of system-level process identifiers (such as a UNIX PID) naming the processes that TotalView controls. All PIDs must reside on the same system, and they are placed in the same control group.
If you need to place the processes in different groups or attach to processes on more than one system, you must use multiple dattach commands.
-c core-file | recording-file
Loads the core file core-file or the ReplayEngine recording-file, which restores a previous ReplayEngine debugging session. If you use this option, you must also specify an executable name (executable).
-parallel_attach_subset subset_specification
Defines a list of MPI ranks to attach to when an MPI job is created or attached to. The list is space-separated; each element can have one of three forms:
rank: specifies that rank only
rank1-rank2: specifies all ranks between rank1 and rank2, inclusive
rank1-rank2:stride: specifies 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.
For example:
dattach -parallel_attach_subset {1 2 4-6 7-max:2} mpirun
attaches to ranks 1, 2, 4, 5, 6, 7, 9, 11, 13,....
Description
The dattach command attaches to one or more processes, making it possible to continue process execution under TotalView control.
This command returns the TotalView process ID (DPID) as a string. If you specify more than one process in a command, the dattach command returns a list of DPIDs instead of a single value.
TotalView places all processes to which it attaches in one dattach command in the same control group. This lets you place all processes in a multiprocess program executing on the same system in the same control group.
If a program has more than one executable, you must use a separate dattach command for each one.
If you have not loaded executable already, the CLI searches for it. The search includes all directories in the ‑EXECUTABLE_PATH CLI variable.
The process identifiers specified in the pid-list must refer to existing processes in the runtime environment. TotalView attaches to the processes, regardless of their execution states.
Command alias
Alias | Definition | Description |
|---|
at | dattach | Brings the process under TotalView control |
Examples
dattach mysys 10020
Loads debugging information for mysys and brings the process known to the runtime system as PID 10020 under TotalView control.
dattach -e 123 10020
Loads file 123 and brings the process known to the runtime system by PID 10020 under TotalView control.
dattach -g 4 -r Enterprise myfile 10020
Loads myfile that is executing on the host named Enterprise into group 4, and brings the process known to the runtime system by PID 10020 under TotalView control. If a TotalView Server (tvdsvr) is not running on Enterprise, the CLI will start it.
dattach my_file 51172 52006
Loads debugging information for my_file and brings the processes corresponding to PIDs 51172 and 52006 under TotalView control.
set new_pid [dattach -e mainprog 123]
dattach -r otherhost -g $CGROUP($new_pid) -e slave 456
Begins by attaching to mainprog running on the local host; then attaches to slave running on the otherhost host and inserts them both in the same control group.
Related Topics
