ptrace(2) DG/UX 4.30 ptrace(2)
NAME
ptrace - Process trace.
SYNOPSIS
int ptrace (request, pid, address, data)
int request;
int pid;
int address;
int data;
PARAMETERS
request Process trace command.
pid Process being traced. Used only if <request>
is 1-8.
address Optional address argument. Used only if
<request> is 1-7.
data Optional data argument. Used only if
<request> is 4-7.
DESCRIPTION
Ptrace lets a process (debugger process) control the
execution of another process (target process). Its primary
use is to implement breakpoint debugging; see sdb(1) and
dbx(1). The target process behaves normally until it
encounters a signal (see sys/signal.h for the list) or until
it exits; it then stops for tracing and its debugger process
is notified via wait. (A signal that is blocked does not
cause the process to stop for tracing until it is
unblocked.) When the target process is stopped, its
debugger process can examine and modify its core image using
ptrace. Also, the debugger process can cause the target
process either to terminate or continue, with the
possibility of ignoring the signal that caused it to stop.
If the debugger process terminates while tracing a target,
the target will be sent a SIGKILL signal. While a process
is being traced via ptrace(2), job control stop signals are
ignored.
The normal sequence of events required to trace a child
process is as follows:
* The child process is created by the fork operation.
* The child process performs a ptrace operation with
<request> set to 0.
Licensed material--property of copyright holder(s) Page 1
ptrace(2) DG/UX 4.30 ptrace(2)
* The child's address space is changed by the exec
operation. This causes the child to be stopped before
executing the first instruction of the new image as if
the signal SIGTRAP had occurred.
* The parent process waits for the child to stop using a
wait operation.
* The parent may now cause the child to continue
execution using ptrace with <request> set to 7.
The normal sequence of events required to trace a non-child
process is as follows:
* The controlling process is created by the fork
operation.
* The controlling process performs a ptrace operation
with <request> set to 128. If the target process is
stopped due to a job control signal (e.g., SIGSTOP) at
the time <request> 128 is issued, the ptrace call will
complete normally but tracing does not actually occur
until the target process leaves the stopped state (due
to a signal that continues or terminates it.
* The controlling process waits for the target process to
stop using a wait operation.
* The controlling process may now cause the target
process to continue execution using ptrace with
<request> set to 7.
The <request> argument determines the precise action to be
taken by ptrace and is one of the following:
0 The child process must issue this request if it is to
be traced by its parent. It turns on the child's trace
flag that stipulates that the child should be left in a
stopped state upon receipt of a signal rather than the
state specified by its signal handler. The <pid>,
<address>, and <data> arguments are ignored, and a
return value is not defined for this request.
[Unexpected results may ensue if the parent does not
expect to trace the child. The parent may not cause
the child to continue after a signal, and the child
will be terminated if the parent terminates.]
The other requests can be used only by the controlling
process. For each, <pid> is the process id of the target,
and <address> is a user address. The offset is a word
address. The target must have stopped for tracing before
Licensed material--property of copyright holder(s) Page 2
ptrace(2) DG/UX 4.30 ptrace(2)
these requests are made otherwise, the error condition ESRCH
is asserted.
1 or 2
With these requests, the word at location <address> in
the address space of the target is returned to the
controlling process. The <data> argument is ignored.
These two requests will fail if <address> is not a
valid word pointer, in which case the error condition
EIO is asserted and a -1 is returned.
3 With this request, information about the target process
stored in the kernel address space is made available to
the controlling process. This information is
referenced by <addr> which is interpreted as a word
offset into a synthetic ptrace_user structure (see
sys/user.h). The <data> argument is ignored. The
request will fail if <addr> is not a relative word
offset within the ptrace_user structure or if <addr> is
not a valid word * offset, in which case
the error condition EIO is asserted and a -1 is
returned.
4 or 5
With these requests, the 32-bit value given by the
<data> argument is written into the address space of
the target at location <address>. Upon successful
completion, the value is returned to the controller.
These two requests will fail if <address> is a location
in a pure procedure space and another process is
executing in that space, or if <address> is not a valid
word pointer. Upon failure the error condition EIO is
asserted and a -1 is returned. Upon successful
completion, the value written into the address space
will be returned.
6 With this request, information about the target process
stored in the kernel may be changed. This is similar
to request 3 above, but only a few entries in the
ptrace_user structure may be changed (see sys/user.h).
<Data> gives the value that is to be written and
<address> is the word offset of the entry.
7 This request causes the target to resume execution. If
the <data> argument is 0, all pending signals including
the one that caused the target to stop for tracing are
cancelled before the target resumes execution. If the
Licensed material--property of copyright holder(s) Page 3
ptrace(2) DG/UX 4.30 ptrace(2)
<data> argument is a valid signal number, the target
resumes execution as if it had incurred that signal,
and any other pending signals are cancelled. The
<address> argument must be equal to 1 for this request.
Upon successful completion, the value of <data> is
returned to the controlling process. This request will
fail if <data> is not 0 or a valid signal number, in
which case the error condition is asserted and a -1 is
returned.
8 This request causes the target to terminate with the
same consequences as exit, except that the target does
not stop for tracing again as part of exiting.
9 Single step through the instructions in the target
process.
128 The controlling process initiates a debugging session
with an existing process whose process id is <pid>.
129 The controlling process terminates a debuggins session
with a given process. If <addr> is not 1, it becomes
the new program counter of the (ex)target process.
Also, all pending signals are cleared.
130 Any forked children of the target process will inherit
their parent's debugger and trace state.
To forestall possible fraud, ptrace 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
For <request> values of 0, 6, 8, 128, 129, or 130, the
following values are returned:
0 The particular request was successful.
-1 An error occurred. Errno is set to indicate
the error.
Licensed material--property of copyright holder(s) Page 4
ptrace(2) DG/UX 4.30 ptrace(2)
For <request> values of 1, 2, or 3, the following values are
returned:
<value> The 32-bit value read from the given target
address. This value may be -1.
-1 An error occurred. Errno is set to indicate
the error.
For <request> values of 4, 5, 7, or 9, the following values
are returned:
<data> The value of <data> is returned.
-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 <pid> identifies a child that does not exist
or has not executed a ptrace with <request>
0.
SEE ALSO
The related system calls: exec, signal, wait.
Licensed material--property of copyright holder(s) Page 5