ptrace(2)
_________________________________________________________________
ptrace System Call
Process trace.
_________________________________________________________________
SYNTAX
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
This function provides capabilities that are inherently
implementation dependent.
Ptrace lets a parent process control the execution of a child
process. Its primary use is to implement breakpoint debugging;
see sdb(1), dbx(1), or mxdb(1). The child 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 parent
is notified via wait. (A signal that is blocked does not cause
the process to stop for tracing until it is unblocked.) When the
child is stopped, its parent can examine and modify its core
image using ptrace. Also, the parent can cause the child either
to terminate or continue, with the possibility of ignoring the
signal that caused it to stop. If the parent process terminates
while tracing a child, the child will be sent a SIGKILL signal.
While a process is being traced via ptrace(2), job control stop
signals are ignored.
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
ptrace(2)
The normal sequence of events required to trace a 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.
* 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 the
wait or wait3 operation.
* The parent may now cause the child 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 parent process. For
each, <pid> is the process id of the child, and <address> is a
ring 7 address. The offset is a word address. The child 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 child is returned to the parent
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, the 32-bit word at location <address> in
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
ptrace(2)
the child's user area is returned to the parent process.
Legitimate values of <address> are listed below. The <data>
argument is ignored. This request will fail if <address> is
not a valid offset, in which case the error condition EIO is
asserted and a -1 is returned.
* Fixed and floating point accumulators.
* User Stack Registers
* User PSR
* User Extended Errno
* User Break Value
* General registers (i.e., registers 0-3).
4 or 5
With these requests, the 32-bit value given by the <data>
argument is written into the address space of the child at
location <address>. Upon successful completion, the value
is returned to the parent. 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, a few entries in the child's user area
can be written. <Data> gives the value that is to be
written and <address> is the location of the entry. The
entries are:
* Fixed and floating point accumulators.
* User Stack Registers
* General registers (i.e., registers 0-3).
7 This request causes the child to resume execution. If the
<data> argument is 0, all pending signals including the one
that caused the child to stop for tracing are cancelled
before the child resumes execution. If the <data> argument
is a valid signal number, the child 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 parent. This request will fail if
<data> is not 0 or a valid signal number, in which case the
error condition EIO is asserted and a -1 is returned.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
ptrace(2)
8 This request causes the child to terminate with the same
consequences as exit, except that the child does not stop
for tracing again as part of exiting.
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 4, 5, 6, or 8, 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> value of 7, 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:
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
ptrace(2)
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.
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)