xtrace(2)
_________________________________________________________________
xtrace System Call
Extended process trace.
_________________________________________________________________
SYNTAX
#include <sys/xtrace.h>
int xtrace (request, data)
int request;
union xtrace_u * data;
PARAMETERS
request Process trace command.
data Pointer to union used for completing the process
trace command.
DESCRIPTION
This function is a provides capabilities that are inherently
implementation dependent.
Xtrace lets a process control the execution of another process.
Its primary use is to implement breakpoint debugging; see dbx(1).
It is an extended version of ptrace which has been added to
remedy two of the major shortcomings of ptrace:
* the mandatory parent/child relationship between the
tracing-process and the process-being-traced, and
* the very small (32-bit) interface between the two processes.
Since the relationship between the two processes is no longer
mandated to be parent/child some terms defining this new
relationship are needed so that discussion of their interaction
is possible. The process controlling the tracing of another
process will be referred to as the "controlling process" or
"controller." The process being traced will be referred to as
the "target process" or "target."
There are three valid relationships between the controlling and
target processes:
* the controller is the PARENT of the target,
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
xtrace(2)
* the controller is the CHILD of the target, or
* the controller is NOT RELATED to the target (and is not the
target itself).
There are some restrictions concerning the specifics of the
tracing relationship. In general, a target can become a
controller, but a controller can not become a target. This
avoids a cycle in the controller-target relationship which could
result in a deadlock condition. A controller can trace multiple
targets, but when the controller terminates, all of its targets
are sent SIGKILL. Finally, if a controller (who is not a target)
is the child of a process being traced then job control stop
signals sent to the controller will be ignored. This restriction
is necessary because the parent process is usually responsible
for any stopped children (which is impossible in this scenario).
In all configurations, the target process behaves normally until
it encounters a signal (see signal(2) for the list) or until it
exits; it then stops for tracing and its controller is notified
via xtrace using the <request> XT_WAIT_FOR_TARGET (defined
below). (A signal that is blocked does not cause the process to
stop for tracing until the signal is unblocked. If a job control
stop signal is held because the target process has performed
vfork() but not exec() or exit(), such a signal does not cause
the process to stop for tracing until the process has performed
exec() or exit().)
When the target is stopped, its controller can examine and modify
its address space using xtrace. Also, the controller can cause
the target either to terminate or continue, with the possibility
of ignoring the signal that caused it to stop.
In the first configuration, the sequence of events required to
trace a process is as follows:
* The target process is created by fork(2) or vfork(2).
* The target process performs an xtrace operation with
<request> XT_TRACE_ME.
* The target's address space is changed by the exec(2)
operation. This causes the target to be stopped for tracing
before executing the first instruction of the new image as
if the signal SIGTRAP had occurred.
* The controlling process waits for the target to stop for
tracing using xtrace with <request> XT_WAIT_FOR_TARGET.
* The controller may now cause the target to continue
execution using xtrace with <request> XT_CONTINUE_TARGET.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
xtrace(2)
In the second configuration, the sequence of events required to
trace a process is as follows:
* The controlling process is created by fork(2) or vfork(2).
* The controlling process performs an xtrace operation with
<request> XT_TRACE_PID specifying the parent process's
process id. If the parent process is stopped due to a job
control signal (e.g., SIGSTOP) at the time XT_TRACE_PID is
issued, XT_TRACE_PID completes normally but tracing does not
actually occur until the parent process leaves the stopped
state (due to a signal that continues it or terminates it).
* The controlling process waits for the target to stop for
tracing using xtrace with <request> XT_WAIT_FOR_TARGET.
* The controller may now cause the target to continue
execution using xtrace with <request> XT_CONTINUE_TARGET.
In the third configuration, the sequence of events required to
trace a process is as follows:
* The controlling process performs an xtrace operation with
<request> XT_TRACE_PID specifying the process id of the
process to be traced. If the target is stopped due to a job
control signal (e.g., SIGSTOP) at the time XT_TRACE_PID is
issued, XT_TRACE_PID completes normally but tracing does not
actually occur until the target process leaves the stopped
state (due to a signal that continues it or terminates it).
* The controlling process waits for the target to stop using
xtrace with <request> XT_WAIT_FOR_TARGET.
* The controller may now cause the target to continue
execution using xtrace with <request> XT_CONTINUE_TARGET.
The <request> argument determines the precise action to be taken
by xtrace. For each <request> there exists a macro invocation of
xtrace that initializes the supplied xtrace_u union pointer with
the appropriate values. Each macro is of the form:
XTRACE_<"request"-less-XT-prefix>([arguments])
Users should only access xtrace through these macro invocations.
[Arguments] includes various combinations of the following:
<process-id> which is the process id of the target, <target_addr>
which is a byte address in the target process, <controlling_buf>
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
xtrace(2)
which is a byte address in the controlling process, <nchar> which
is the number of bytes to transfer between the two processes,
<signal> which is a signal to be sent when continuing a target,
<wait_ptr> which is a pointer to an integer that receives
information about the traced process. The <xtrace_union_ptr>
argument if used by a macro is the only argument from the macro
interface which is passed to xtrace. The other argument values
in the interface are placed into the union at which
<xtrace_union_ptr> points. (See the actual xtrace interface
above.) The <target_space> argument specifies the subspace of
the process's address space (Text, Data, or User Area) to which a
read/write operation is directed. (On the MV Architecture no
distinction is made between Data and Text space. Also,
read/write operations in the User Area are restricted to the
Floating Point Registers. <Target_space> can assume the
following values:
* XT_USER_SPACE, or
* XT_ADDRESS_SPACE . The requests are as follows:
* XT_TRACE_ME -
macro: XTRACE_TRACE_ME()
In the first configuration, the target process must issue
this request if it is to be traced by its controller (its
parent). This operation marks the target as being traced so
that it will be stopped for tracing upon receipt of a signal
rather than the state specified by its signal handler. A
return value of 0 is always returned with this request.
[Unexpected results may ensue if the controller (in this
case the parent) does not expect to trace the target. For
example, the controller may not cause the target to continue
after a signal. Also, the target will be terminated if the
controller terminates.]
The other requests can be used only by the controller process.
* XT_TRACE_PID -
macro: XTRACE_TRACE_PID(<process-id>,
<xtrace_union_ptr>)
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
xtrace(2)
With this request, the controlling process issues a request
to establish a tracing relationship with a target process
(specified by process id). This request will fail if:
* the effective-user-id of the controlling process does not
match the real-user-id and saved-user-id of the target
process, and the effective-group-id of the controlling
process does not match the real-group-id and saved group id
of the target process, OR
* the user id of the controlling process is not the superuser.
If the tracing relationship is successfully established, it
turns on the target's trace flag. This stipulates that the
target should stop for tracing upon receipt of a signal
rather than the state specified by its signal handler. Note
that this request does NOT cause a signal to be sent to the
target or otherwise cause the target to stop. If the
relationship cannot be established the request will fail, in
which case the error condition ESRCH is asserted. Under no
circumstances may a process trace itself!
* XT_READ_TARGET -
macro: XTRACE_READ_TARGET(<process-id>,
<target_space>
<target_addr>,
<controlling_buf>,
<nchar>,
<xtrace_union_ptr>)
With this request, the <nchar> bytes beginning at location
<target_addr> in <target_space> of the target's address
space are placed in the location <controlling_buf> in the
controller's address space. This request will fail when
either <target_addr> or <controlling_buf> is not a valid
byte address, <nchar> bytes cannot be read or <target_addr>
is not a valid address in <target_space>, in which case the
error condition EIO is asserted. The request will also fail
with EIO if the caller is not the controller of the target
or the target is not stopped for tracing, though the stop
need not have been acknowledged with XTRACE_WAIT_FOR_TARGET.
* XT_WRITE_TARGET -
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
xtrace(2)
macro: XTRACE_WRITE_TARGET(<process-id>,
<target_space>,
<target_addr>,
<controlling_buf>,
<nchar>,
<xtrace_union_ptr>)
With this request, the <nchar> bytes beginning at location
<controlling_buf> in the controller's address space are
placed in the location <target_addr> in <target_space> of
the target's address space. This request will fail when
either <target_addr> or <controlling_buf> is not a valid
byte address, <nchar> bytes cannot be written or
<target_addr> is not a valid address in <target_space>, in
which case the error condition EIO is asserted. The request
will also fail with EIO if the caller is not the controller
of the target or the target is not stopped for tracing,
though the stop need not have been acknowledged with
XTRACE_WAIT_FOR_TARGET.
* XT_WAIT_FOR_TARGET -
macro: XTRACE_WAIT_FOR_TARGET(<process-id-ptr>,
<wait_ptr>,
<options>,
<xtrace_union_ptr>)
With this request, the controlling process waits for one of
his traced processes. This request works like wait3(2)
except that it waits only for a traced process that has
received a signal (the wait3(2) WUNTRACED option is
ignored). When one of the controller's targets receives a
signal, this function returns the pid of that process and
"acknowledges" that the target has stopped so that
subsequent calls to this function will not return that same
pid until the target has been continued and it receives
another signal. If none of the targets have received a
signal, then the caller is pended unless the WNOHANG option
is specified, in which case pid 0 is returned and the caller
is not pended. EIO is returned if the caller is not the
controller for any traced process. Note: When a process
terminates or an untraced process receives one of the job
control stop signals, the status is always reported via
wait3(2) performed by the parent, never via
XTRACE_WAIT_FOR_TARGET. When a traced process stops for
tracing, the status is always reported only to the
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)
xtrace(2)
controller process. If the controller is not the parent,
then the status is only reported via XTRACE_WAIT_FOR_TARGET
and the traced state of the process will be invisible as far
as any wait3(2) calls made by the parent. If the controller
is the parent, the status is reported through either
wait3(2) or XTRACE_WAIT_FOR_TARGET, but not both. The
receipt of signal status will be reported by whichever call
is made first; but if the other call is then made the
process will already have been acknowledged and will not be
reported again.
* XT_CONTINUE_TARGET -
macro: XTRACE_CONTINUE_TARGET(<process-id>,
<signal>,
<xtrace_union_ptr>)
This request causes the target to resume execution. If the
<signal> argument is 0, all pending signals including the
one that caused the target to stop are cancelled before it
resumes execution. If the <signal> argument is a valid
signal number, the target resumes execution as if it had
incurred that signal, and any other pending signals are
cancelled. This request will fail if <signal> is not 0 or
a valid signal number, in which case the error condition EIO
is asserted. The request will also fail with EIO if the
caller is not the controller of the target or the target is
not stopped for tracing, though the stop need not have been
acknowledged with XTRACE_WAIT_FOR_TARGET.
* XT_TERMINATE_TARGET -
macro: XTRACE_TERMINATE_TARGET(<process-id>,
<xtrace_union_ptr>)
This request causes the target to terminate with the same
consequences as exit, except that the target will not stop
for tracing again as part of exit. The request will fail
with EIO if the caller is not the controller of the target
or the target is not stopped for tracing, though the stop
need not have been acknowledged with XTRACE_WAIT_FOR_TARGET.
* XT_SINGLESTEP_TARGET - This request is not supported; it
DG/UX 4.00 Page 7
Licensed material--property of copyright holder(s)
xtrace(2)
returns an error.
To forestall possible fraud, xtrace inhibits the set-user-id
facility on subsequent exec calls. If a traced process calls
exec, it will stop before executing the first instruction of the
new image showing signal SIGTRAP.
ACCESS CONTROL
None.
RETURN VALUE
0 Completed successfully.
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EIO <Request> is an illegal number.
ESRCH <Process-id> identifies a target that does not
exist.
ESRCH No tracing relationship can be established.
EINVAL One of the arguments is invalid
EFAULT One of the arguments specifies a bad address.
SEE ALSO
The related system calls: ptrace, exec, signal, wait.
DG/UX 4.00 Page 8
Licensed material--property of copyright holder(s)