ptrace
Purpose
Traces the execution of another process.
Syntax
#include <sys/reg.h>
int ptrace (request, pid, addr, data, buff)
int request, pid, *addr, data, *buff;
Description
The ptrace system call allows one process to control the
execution of another process. ptrace is primarily used
by utility programs to implement breakpoint debugging.
The sdb and dbx commands described in AIX Operating
System Commands Reference are two such debugging utili-
ties.
The traced process behaves normally until it encounters a
signal, at which time it enters a stopped state and its
debugging process is notified with the wait system call.
When the traced process is in the stopped state, its
debugging process can examine and modify its memory image
using the ptrace system call. Also, the debugging
process can cause the traced process to either terminate
or continue, with the possibility of ignoring the signal
that caused it to stop.
The request parameter determines the action to be taken
by the ptrace system call and is one of the following:
0 This request must be issued by a child process
that is to be traced by its parent. This request
sets the child's trace flag that causes the child
to be left in a stopped state upon receipt of a
signal, rather than the state specified by the
func parameter of the signal system call. The
pid, addr, and data parameters are ignored, and a
return value is not defined for this request. Do
not issue this request if the parent does not
expect to trace the child.
Note: The remainder of the requests can only be used by
the debugging process. For each request, the pid param-
eter is the process ID of the process to be traced. The
traced process must be in a stopped state before these
requests are made.
1, 2 These requests return the int in the traced proc-
ess's address space at the location pointed to by
the addr parameter. Either request 1 or request
2 can be used with equal results. The data
parameter is ignored. These requests fail if the
value of the addr parameter is not in the address
space of the traced process, in which case a
value of -1 is returned, and the debugging proc-
ess's errno is set to EIO.
3 This request returns the int from the traced
process's user area of the system's address space
that is located at the offset given by the addr
parameter. (For information about the user area,
see the sys/user.h header file.) The value of
the addr parameter must be in the range 0 to
ctob(USIZE), and it is rounded down to the next
int (word) boundary. (ctob and USIZE are defined
by including the sys/param.h header file.) The
data parameter is ignored. This request fails if
the addr parameter is outside the user area, in
which case a value of -1 is returned to the
debugging process, whose errno is then set to
EIO.
4, 5 These requests write the value of the data param-
eter into the address space of the traced process
at the int pointed to by the addr parameter.
Either request 4 or request 5 can be used with
equal results. Upon successful completion, the
value written into the address space of the
traced process is returned to the debugging
process. These requests fail if the addr param-
eter points to a location in a pure procedure
space and a copy cannot be made. They also fail
if the addr is out of range. Upon failure, a
value of -1 is returned to the debugging process
and the debugging process's errno is set to EIO.
6 This request writes the value of the data param-
eter into the traced process's user area of the
system's address space at the int specified by
the addr parameter. The value of the addr param-
eter is rounded down to the the next int (word)
boundary. The following values for addr are
defined in the sys/reg.h header file, and they
identify the only entries that can be modified:
R0--R15 General Purpose Registers 0--15
IAR Instruction Address Register
MQ Multiply/Quotient Register
CS Condition Status Register.
7 This request causes the traced process to resume
execution. If the data parameter is "0", all
pending signals, including the one that caused
the traced process to stop, are canceled before
the traced process resumes execution. If the
data parameter is a valid signal number, the
traced process resumes execution as if it had
received that signal. Any other pending signals
are canceled. The addr parameter must be equal
to "1" for this request. Upon successful com-
pletion, the value of the data parameter is
returned to the debugging process. This request
fails if the data parameter is not 0 or a valid
signal number, in which case a value of -1 is
returned to the debugging process and the debug-
ging process's errno is set to EIO.
8 This request causes the traced process to termi-
nate the same way it would if it had received a
resume execution with the SIGKILL signal.
11 This request returns the contents of one of the
general purpose registers of the traced process.
The addr parameter specifies which of the sixteen
32-bit registers is to be returned. The data and
buff parameters are ignored. This request fails
if the value of the addr parameter is not between
0 and 15 inclusive. In this case, ptrace returns
the value -1 and sets the debugging process's
errno to EIO.
12 This request stores the value of a floating-point
register into the location pointed to by the addr
parameter. The data parameter specifies which
floating-point register, and it must be a value
in the range from 0 to 7, excluding 6. Registers
0 through 5 are eight bytes long, and the status
register (register 7) is four bytes long.
14 This request stores the value of the data param-
eter in one of the traced process's general
purpose registers. The addr parameter specifies
the register to be modified. The buff parameter
is ignored. Upon successful completion, the
value of data is returned to the debugging
process. This request fails if the value of the
addr parameter is not between 0 and 15 inclusive.
In this case, ptrace returns the value -1 and
sets the deubgging process's errno to EIO.
15 This request sets the floating-point register
specified by the data parameter to the value
pointed to by the addr parameter. The data
parameter must be a value in the range from 0 to
7, excluding 6. Registers 0 through 5 are eight
bytes long, and the status register (register 7)
is four bytes long.
17 This request reads a block of data from the
traced process's address space. The addr param-
eter points to the block of data in the traced
process's address space and the data parameter
gives its length in bytes. The value of the data
parameter must not be greater than 1024. The
buff parameter points to the location in the
debugging process's address space into which the
data is to be copied. Upon successful com-
pletion, ptrace returns the value of the data
parameter. If an error occurs, ptrace returns -1
and sets the debugging process's errno to indi-
cate the error. This request fails when one or
more of the following are true:
EINVAL The data parameter is less than 1 or
greater than 1024.
EIO The addr parameter is not a valid
pointer into the traced process's
address space.
EFAULT The buff parameter does not point to a
writable location in the debugging
process's address space.
19 This request writes a block of data into the
traced process's address space. The addr param-
eter points to the location in the traced proc-
ess's address space to be written into. The data
parameter gives the length of the block in bytes,
and it must not be greater than 1024. The buff
parameter points to the data in the debugging
process's address space to be copied. Upon suc-
cessful completion, the value of data is returned
to the deubgging process. If an error occurs,
ptrace returns -1 and sets the debugging proc-
ess's errno to indicate the error. This request
fails when one or more of the following are true:
EINVAL The data parameter is less than 1 or
greater than 1024.
EIO The addr parameter is not a valid
pointer into the traced process's
address space.
EFAULT The buff parameter does not point to a
readable location in the debugging
process's address space.
30 This request allows a debugging process to attach
a process that is already running and place it
into trace mode for debugging. This request
cannot be used if the target process is already
being traced.
To debug another process, at least one of the
following must be true:
o Either the real or the effective user ID of
the debugging process matches the real or
effective user ID of the process to be
traced.
o The effective user ID of the debugging
process is superuser.
This request fails if the calling process does
not meet these permission requirements, returning
an error code of EPERM.
31 This request allows a debugged process, specified
by the pid parameter, to exit trace mode. The
process then continues running, as if it had
received the signal whose number is contained in
the data parameter. The process is no longer
traced and does not process any further ptrace
calls.
32 This request writes the contents of all 16
general purpose registers to the area pointed to
by the addr parameter. This area should be at
least 64 bytes. The request fails if the addr
parameter &pointsout., and returns a value of -1,
setting the value of errno to EINVAL.
33 This request allows a new debugger, with the
proper permissions, to trace a process that was
already traced by another debugger. This request
fails if the calling process does not meet the
permission requirements, returning an error code
of EPERM.
34 This request returns the inumber and device
number of the process being traced in the area
pointed to by the addr parameter. This informa-
tion allows the calling process to determine the
full pathname of the traced process. The request
fails if the addr parameter &pointsout., and
returns a value of -1, setting the value of errno
to EINVAL.
35 This request turns on and off multi-process
debugging mode, to allow debugging to continue
across fork and exec system calls. A "0" value
for the data parameter turns multi-process debug-
ging mode off, while all other values turn it on.
When multi-process debugging mode is in effect,
any fork system call causes both the traced
process and its newly created child process to
trap on the next instruction.
Also, when multi-process debugging mode is
enabled, the following new values will be
returned from a wait system call:
125 Process stopped during exec.
126 Process stopped during fork.
As a security measure, the ptrace system call inhibits
the set-user-ID facility on subsequent exec system calls.
If a traced process initiates an exec system call, it
stops before executing the first instruction of the new
image and shows the signal SIGTRAP.
Diagnostics
In general, the ptrace system call fails if one or more
of the following are true:
EIO The request parameter is not one of the values
listed.
ESRCH The pid parameter identifies a child process
that does not exist or that has not executed a
ptrace system call with request 0.
Related Information
In this book: "exec: execl, execv, execle, execve,
execlp, execvp," "signal," and "wait."
The sdb and dbx commands in AIX Operating System Commands
Reference.