PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
-------------------------------------------------------------------------------
ptrace
PURPOSE
Traces the execution of another process.
SYNTAX
#include <sys/ptrace.h>
int ptrace (request, pid, addr, data, buff)
int request;
pid_t pid;
int *addr, data;
char *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. ptrace does not support multiprocessor debugging. The dbx command
described in AIX Operating System Commands Reference is one such debugging
utility.
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.
If the Transparent Computing Facility is installed, the traced process must be
a process executing on the local site. This process is also forbidden to
migrate to another site.
The request parameter determines the action to be taken by the ptrace system
call and is one of the following:
PT_TRACE_ME(0)
This request must be issued by a child process that is to be traced by its
parent. This request sets the child process'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.
Processed November 7, 1990 PTRACE(2,L) 1
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
Note: The remainder of the requests can only be used by the debugging process.
For each request, the pid parameter is the process ID of the process to
be traced. The traced process must be in a stopped state before these
requests are made.
PT_READ_I(1), PT_READ_D(2)
These requests return the int value in the traced process's address space
at the location pointed to by the addr parameter. PT_READ_I specifies the
text area while PT_READ_D specifies the data area. 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 process's errno is set to EIO.
PT_READ_U(3)
This request returns the int value 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.
PT_WRITE_I(4), PT_WRITE_D(5)
These requests write the value of the data parameter into the address
space of the traced process at the int location pointed to by the addr
parameter. Request PT_WRITE_I writes into the text area and request
PT_WRITE_D writes into the data area. 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 parameter points
to a location in a pure procedure space (read-only) and a copy cannot be
made. They also fail if the value of 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.
PT_WRITE_U(6)
This request writes the value of the data parameter into the child
process's user area of the system's address space at the int location
specified by the addr parameter. The value of the addr parameter is
rounded down to the next int (word) boundary. The following values for
addr are defined in the sys/ptrace.h header file, and they identify the
only entries that can be modified.
PT_CONTINUE(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. If the addr parameter is equal to "1" for
this request, then execution continues from where it left off. Otherwise,
Processed November 7, 1990 PTRACE(2,L) 2
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
execution continues from the address specified in addr. Upon successful
completion, 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 debugging process's errno is set to EIO.
PT_KILL(8)
This request causes the traced process to terminate the same way it would
if it had received the SIGKILL signal.
PT_STEP(9)
This request puts the traced process into trace mode and then executes the
same steps as listed for request PT_CONTINUE. Trace mode causes the
traced process to stop upon completion of one machine instruction, which
allows single stepping of the traced process. The signal number from the
stop is SIGTRAP.
PT_READ_GPR(11)
This request returns the contents of one of the general purpose registers
of the traced process. The addr parameter specifies which of the
registers is to be returned. The data and buff parameters are ignored.
The registers are specified using the macro PT_REG. The argument to
PT_REG is the symbolic name found in <sys/ptrace.h>. The request fails if
the addr parameter does not specify a legitimate register. In this case,
ptrace returns the value -1 and sets the debugging process's errno to EIO.
PT_READ_FPR(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 its value should be the offset into the
trace process's saved floating point state. The format of this structure
is "struct fp87save", found in <sys/ptrace.h>. Floating point registers
are ten bytes long.
PT_WRITE_GPR(14)
This request stores the value of the data parameter 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. The
registers are specified in the same manner as used for PT_READ_GPR. This
request fails if the addr parameter does not specify a legitimate
register. In this case, ptrace returns the value -1 and sets the
debugging process's errno to EIO.
PT_WRITE_FPR(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 is specified in the same manner as with PT_READ_FPR. Floating
point registers are ten bytes long.
Processed November 7, 1990 PTRACE(2,L) 3
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
PT_READ_BLOCK(17)
This request reads a block of data from the traced process's address
space. The addr parameter 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 completion, ptrace
returns the value of the data parameter. If an error occurs, ptrace
returns -1 and sets the debugging process'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 writable location in the
debugging process's address space.
PT_WRITE_BLOCK(19)
This request writes a block of data into the traced process's address
space. The addr parameter points to the location in the traced process'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 successful completion, the value of data is returned to
the debugging process. If an error occurs, ptrace returns -1 and sets the
debugging process'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.
If the process has never accessed the vector hardware, a read will return a
buffer with all locations filled with zeros. The following describes in detail
the function of each of the 11 requests that have been added. Specific values
for the macros described can be found in Appendix A, ptrace.h.
PT_READ_VSEG_SIZ
Read the vector segment size (20)
This request returns the vector section size; Pid specifies the specific
processes that the action should be performed on. The addr, data and buff
parameters are ignored. If the cpu has no vector facility, then the
request returns the value -1 and the debugging process's errno will be set
to EINVAL. If there are no errors, a zero will be returned.
Processed November 7, 1990 PTRACE(2,L) 4
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
PT_READ_VSR
Read the vector status register (21)
This request reads the value of the vector status register and stores it
into the location pointed to by the addr parameter. The vector status
register is 8 bytes long. Pid specifies the specific process that the
action should be performed on. The data and buff parameters are ignored.
If an error occurs, ptrace returns -1 and sets the debugging process's
errno to indicate the error. The request fails when one of the following
are true:
ENODEV The cpu has no vector facility.
EFAULT A detectable memory access error has occurred during
operation.
If there are no errors, a zero will be returned.
PT_WRITE_VSR
Write to the vector status register (22)
This request stores the value pointed to by the addr parameter into the
vector status register. The vector status register is 8 bytes long. Pid
specifies the specific process that the action should be performed on.
The data and buff parameters are ignored.
If an error occurs, ptrace returns -1 and sets the debugging process's
errno to indicate the error. The request fails when one of the following
are true:
EACCES An attempt was made to alter bits 0-15 or bits 56-63 of the
status register, which are protected.
ENXIO The values given for the vector count and/or the vector
interruption index are greater than the section size.
PT_READ_VMR
Read the vector mask register (23)
This request reads the vector mask register and stores its value into the
location pointed to by the addr parameter. The vector mask register is
vector segment size number of bits long. Pid specifies the specific
process that the action should be performed on. The data and buff
parameters are ignored.
PT_WRITE_VMR
Write to the vector mask register (24)
This request stores the value pointed to by the addr parameter into the
vector mask register. The vector mask register is vector segment size
Processed November 7, 1990 PTRACE(2,L) 5
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
number of bits long. Pid specifies the specific process that the action
should be performed on. The data and buff parameters are ignored.
PT_READ_VACR
Read the vector activity register (25)
This request reads the vector activity register and stores its value into
the location pointed to by the addr parameter. The vector activity
register is 8 bytes long. Pid specifies the specific process that the
action should be performed on. The data and buff parameters are ignored.
PT_WRITE_VACR
Write the vector activity register (26)
This request stores the value pointed to by the addr parameter into the
vector activity register. The vector activity register is 8 bytes long.
Pid specifies the specific process that the action should be performed on.
The data and buff parameters are ignored.
EACCES An attempt was made to alter bits 0-8 of the vector activity
register, which are protected.
PT_READ_VFR
Read a 32-bit vector register (27)
This request reads the values of the 32-bit vector register specified by
the addr parameter and stores its values into the location specified by
the buff parameter. The length of the data is equal to 4 times the vector
segment size in bytes. Register numbers are specified in the header file
ptrace.h. Either an odd or an even number can be specified in this
request. Pid specifies the specific process that the action should be
performed on. The data parameter is ignored.
If an error occurs, ptrace returns -1 and sets the debugging process's
errno to indicate the error. The request fails when one of the following
are true:
ENODEV The cpu has no vector facility
ENXIO The register number is out of the range of numbers PT_R_V0 to
PT_R_V15.
EFAULT A detectable memory access error has occurred during
operation, (e.g, the memory area pointed to by the buff
parameter is less than 4 times the vector segment size in
bytes, and the copy of the vector would write outside of user
space.
If there are no errors, a zero will be returned.
Processed November 7, 1990 PTRACE(2,L) 6
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
PT_WRITE_VFR
Write into the 32-bit vector register (28)
This request stores the values pointed to by the buff parameter into the
32-bit vector register specified by the addr parameter. The length of the
data is equal to 4 times the vector segment size in bytes. Register
numbers are specified in the header file ptrace.h. Either an odd or an
even number can be specified in this request. Pid specifies the specific
process that the action should be performed on. The data parameter is
ignored.
PT_READ_VFR
Read the double (64-bit) vector register (29)
This request reads the even-odd pair of vector registers specified by the
addr parameter and stores its values into the location specified by the
buff parameter. The length of the data is equal to 8 times the vector
segment size in bytes. Register numbers are specified in the header file
ptrace.h. Only an even number can be specified for the vector register's
pair in the request. Pid specifies the specific process that the action
should be performed on. The data parameter is ignored.
If an error occurs, ptrace returns -1 and sets the debugging process's
errno to indicate the error. The request fails when one of the following
are true.
ENODEV The cpu has no vector facility.
ENXIO The register number is out of the range of even numbers
PT_R_V0 to PT_R_V14.
EFAULT A detectable memory access error has occurred during
operation, (e.g, the memory area pointed to by the buff
parameter is less than 8 times the vector segment size in
bytes, and the copy of the vector would write outside of user
space.
If there are no errors, a zero will be returned.
PT_WRITE_VDR
Write into the double (64-bit) vector register (30)
This request stores the values pointed to by the buff parameter into the
even-odd pair of registers specified by the addr parameter. The length of
the data is equal 8 times the vector segment size in bytes. Register
numbers are specified in the header file ptrace.h. Only an even number
can be specified for the vector register's pair in this request. Pid
specifies the specific process that the action should be performed on.
The data parameter is ignored.
Processed November 7, 1990 PTRACE(2,L) 7
PTRACE(2,L) AIX Technical Reference PTRACE(2,L)
OTHER ERRORS
In general, the ptrace system call will fail 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 has not executed a ptrace system call with request 0.
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.
ERROR CONDITIONS
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 on the
local system or that has not executed a ptrace system call with request
0.
EAGAIN The traced process was not in a stopped state before a request is made.
RELATED INFORMATION
In this book: "exec: execl, execv, execle, execve, execlp, execvp,"
"sigaction, sigvec, signal," and "wait, waitpid."
The dbx command in AIX Operating System Commands Reference.
Processed November 7, 1990 PTRACE(2,L) 8