ptrace(2) DG/UX R4.11MU05 ptrace(2)
NAME
ptrace - process trace
SYNOPSIS
#include <unistd.h>
#include <sys/types.h>
int ptrace (request, pid, address, data)
int request;
pidt pid;
int address;
int data;
where:
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 mxdb(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:
1. The child process is created by the fork operation.
2. The child process performs a ptrace operation with request set
to 0.
3. 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.
4. The parent process waits for the child to stop using a wait
operation.
5. 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:
1. The controlling process is created by the fork operation.
2. 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).
3. The controlling process waits for the target process to stop
using a wait operation.
4. 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 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
ptraceuser structure (see sys/user.h). The data argument is
ignored. The request will fail if addr is not a relative word
offset within the ptraceuser 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 ptraceuser 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 a valid signal number, the target resumes
execution as if it had incurred that signal, and any other
pending signals are canceled. 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 debugging session with a
given process. If addr is not 1, it becomes the new program
counter of the (ex)target process.
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.
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.
DIAGNOSTICS
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
exec(2), signal(2), wait(2).
Licensed material--property of copyright holder(s)