Request |
Determines the action to be taken by the ptrace subroutine and
has one of the following values:
- PT_ATTACH
- This request allows a debugging process to attach a current process and
place it into trace mode for debugging. This request cannot be used if the target
process is already being traced.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Address, Data, and Buffer parameters are ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to one the following codes:
- ESRCH
- Process ID is not valid; the traced process is a kernel process;
the process is currently being traced; or, the debugger or traced process already
exists.
- EPERM
- Real or effective user ID of the debugger does not match that of the
traced process, or the debugger does not have root authority.
- EINVAL
- The debugger and the traced process are the same.
- PT_CONTINUE
- This request allows the process to resume execution. If the Data
parameter is 0, all pending signals, including the one that caused the process to
stop, are concealed before the process resumes execution. If the data parameter is
a valid signal number, the process resumes execution as if it had received that
signal. If the Address parameter equals 1, the execution continues from
where it stopped. If the Address parameter is not 1, it is assumed to be the
address at which the process should resume execution. Upon successful completion,
the value of the Data parameter is returned to the debugging process.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The signal to be sent to the traced process is not a valid signal
number.
-
PTT_CONTINUE
- This request asks the scheduler to resume execution of the kernel thread
specified by Identifier. This kernel thread must be the one that caused the
exception. The Data parameter specifies how to handle
signals:
- If the Data parameter is zero, the kernel
thread which caused the exception will be resumed as if the signal never
occurred.
- If the Data parameter is a valid signal
number, the kernel thread which caused the exception will be resumed as if it had
received that signal.
The Address parameter specifies where to resume execution:
- If the Address parameter is one, execution
resumes from the address where it stopped.
- If the Address parameter contains an
address value other than one, execution resumes from that address.
The Buffer parameter should point to a PTTHREADS
structure,
which contains a list of kernel thread identifiers to be started. This list should
be NULL terminated if it is smaller than the maxiumum allowed.
On successful completion, the value of the Data parameter is returned to
the debugging process. On unsuccessful completion, the value -1 is returned, and
the errno global variable is set as follows:
- EINVAL
- The Identifier parameter names the wrong kernel thread.
- EIO
- The signal to be sent to the traced kernel thread is not a valid signal number.
- ESRCH
- The Buffer parameter names an invalid kernel thread. Each kernel
thread in the list must be stopped and belong to the same process as the kernel
thread named by the Identifier parameter.
- PT_DETACH
- This request allows a debugged process, specified by the
Identifier
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. The
Address and Buffer parameters are ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- Signal to be sent to the traced process is not a valid signal
number.
- PT_KILL
- This request allows the process to terminate the same way it would with
an exit subroutine.
- PT_LDINFO
- This request retrieves a description of the object modules that were
loaded by the debugged process.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored. The Address parameter specifies the
location where the loader information is copied. The Data parameter
specifies the size of this area. The loader information is retrieved as a linked
list of ld_info structures. The ld_info structures are defined in the
/usr/include/sys/ldr.h file. The linked list is implemented so that the
ldinfo_nxt
field of each element gives the offset of the next element
from this element. The ldinfo_nxt
field of the last element has the
value 0.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- ENOMEM
- Either the area is not large enough to accommodate the loader
information, or there is not enough memory to allocate an equivalent buffer in the
kernel.
- PT_MULTI
- This request turns multiprocess debugging mode on and off, to allow
debugging to continue across fork and exec subroutines. A 0 value for
the data parameter turns multiprocess debugging mode off, while all other values
turn it on. When multiprocess debugging mode is in effect, any fork subroutine allows both the traced process and its newly created process to trap
on the next instruction. If a traced process initiated an exec subroutine,
the process stops before executing the first instruction of the new image and
returns the SIGTRAP signal.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Address and Buffer parameters are ignored.
Also, when multiprocess debugging mode is enabled, the following values are
returned from the wait subroutine:
- W_SEWTED
- Process stopped during execution of the exec subroutine.
- W_SFWTED
- Process stopped during execution of the fork subroutine.
- PT_READ_BLOCK
- This request reads a block of data from the debugged process address
space. The Address parameter points to the block of data in the process
address space, and the Data parameter gives its length in bytes. The value
of the Data parameter must not be greater than 1024.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter points to the location in the debugging process address
space where the data is copied. Upon successful completion, the ptrace
subroutine returns the value of the data parameter.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to one of the following codes:
- EIO
- The Data parameter is less than 1 or greater than 1024.
- EIO
- The Address parameter is not a valid pointer into the debugged
process address space.
- EFAULT
- The Buffer parameter does not point to a writable location in the
debugging process address space.
- PT_READ_FPR
- This request stores the value of a floating-point register into the
location pointed to by the Address parameter. The Data parameter
specifies the floating-point register, defined in the sys/reg.h file for the
machine type on which the process is executed.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Data parameter is not a valid floating-point register. The
Data parameter must be in the range 256-287.
- PTT_READ_FPRS
- This request writes the contents of the 32 floating point registers to the
area specified by the Address parameter. This area must be at least 256
bytes long. The Identifier parameter specifies the traced kernel thread. The
Data and Buffer parameters are ignored.
- PT_READ_GPR
- This request returns the contents of one of the general-purpose or
special-purpose registers of the debugged process. The Address parameter
specifies register returns. The value of the Address parameter is defined in
the sys/reg.h file for the machine type on which the process is executed.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Data and Buffer parameters are ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Address is not a valid general-purpose or special-purpose
register. The Address parameter must be in the range 0-31 or 128-136.
- PTT_READ_GPRS
- This request writes the contents of the 32 general purpose registers to the
area specified by the Address parameter. This area must be at least 128
bytes long. The Identifier parameter specifies the traced kernel thread. The
Data and Buffer parameters are ignored.
- PT_READ_I
or PT_READ_D
- These requests return the word-aligned address in the debugged process
address space specified by the Address parameter.
On all machines currently supported by the Version
4 operating system, the PT_READ_I and PT_READ_D instruction and data
requests can be used with equal results.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Data parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Address is not word-aligned, or the Address is not
valid. User blocks, kernel segments, and kernel extension segments are not
considered as valid addresses.
-
PTT_READ_SPRS
- This request writes the contents of the special purpose registers to the area
specified by the Address parameter, which points to a ptsprs
structure. The Identifier parameter specifies the traced kernel thread. The
Data and Buffer parameters are ignored.
- PT_REATT
- This request allows a new debugger, with the proper permissions, to
trace a process that was already traced by another debugger.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Address, Data, and Buffer parameters are ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to one the following codes:
- ESRCH
- The
Identifier is not valid; or the traced process is a kernel process.
- EPERM
- Real or effective user ID of the debugger does not match that of the
traced process, or the debugger does not have root authority.
- EINVAL
- The debugger and the traced process are the same.
- PT_REGSET
- This request writes the contents of all 32 general purpose registers to
the area specified by the Address parameter. This area must be at least 128
bytes.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Data and Buffer parameters are ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Address parameter points to a location outside of the
allocated address space of the process.
- PT_TRACE_ME
- This request must be issued by the debugged process to be traced. Upon
receipt of a signal, this request sets the process trace flag, placing the process
in a stopped state, rather than the action specified by the sigaction
subroutine. The
Identifier, Address, Data, and Buffer parameters are
ignored. Do not issue this request if the parent process does not expect to trace
the debugged process.
As a security measure, the ptrace subroutine inhibits the set-user-ID
facility on subsequent exec subroutines, as shown in the following example:
if((childpid = fork()) == 0)
{ /* child process */
ptrace(PT_TRACE_ME,0,0,0,0);
execlp( )/* your favorite exec*/
}
else
{ /* parent */
/* wait for child to stop */
rc = wait(status)
Note: This is the only request that
should be performed by the child. The parent should perform all other requests when the child is in a stopped state.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- ESRCH
- Process is debugged by a process that is not its parent.
- PT_WRITE_BLOCK
- This request writes a block of data into the debugged process address
space. The Address parameter points to the location in the process address
space to be written into. The Data parameter gives the length of the block
in bytes, and must not be greater than 1024.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter points to the location in the debugging process address
space where the data is copied. Upon successful completion, the value of the
Data parameter is returned to the debugging process.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to one of the following codes:
- EIO
- The Data parameter is less than 1 or greater than 1024.
- EIO
- The Address parameter is not a valid pointer into the debugged
process address space.
- EFAULT
- The Buffer parameter does not point to a readable location in the
debugging process address space.
- PT_WRITE_FPR
- This request sets the floating-point register specified by the
Data parameter to the value specified by the Address parameter.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Data parameter is not a valid floating-point register. The
Data parameter must be in the range 256-287.
- PTT_WRITE_FPRS
- This request updates the contents of the 32 floating point registers with the
values specified in the area designated by the Address parameter. This area
must be at least 256 bytes long. The Identifier parameter specifies the
traced kernel thread. The Data and Buffer parameters are
ignored.
- PT_WRITE_GPR
- This request stores the value of the Data parameter in one of the
process general-purpose or special-purpose registers. The Address parameter
specifies the register to be modified. Upon successful completion, the value of the
Data parameter is returned to the debugging process.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Address is not a valid general-purpose or special-special
purpose register. The Address parameter must be in the range 0-31 or
128-136.
-
PTT_WRITE_GPRS
- This request updates the contents of the 32 general purpose registers with
the values specified in the area designated by the Address parameter. This
area must be at least 128 bytes long. The Identifier parameter specifies the
traced kernel thread. The Data and Buffer parameters are
ignored.
- PT_WRITE_I
or PT_WRITE_D
- These requests write the value of the data parameter into the address
space of the debugged process at the word-aligned address specified by the
Address parameter.
On all machines currently supported by the Version 4 operating system, instruction
and data address spaces are not separated.
The PT_WRITE_I and PT_WRITE_D instruction and data requests can be
used with equal results. Upon successful completion, the value written into the
address space of the debugged process is returned to the debugging process.
The Identifier parameter is interpreted as the process ID of the traced
process.
The Buffer parameter is ignored.
If this request is unsuccessful, -1 is returned and the errno global
variable is set to the following code:
- EIO
- The Address parameter points to a location in a pure procedure
space and a copy cannot be made; the Address is not word-aligned; or, the
Address is not valid. User blocks, kernel segments, and kernel extension
segments are not considered valid addresses.
-
PTT_WRITE_SPRS
- This request updates the special purpose registers with the values in the
area specified by the Address parameter, which points to a ptsprs
structure. The Identifier parameter specifies the traced kernel thread. The
Data and Buffer parameters are ignored.
|