NAME

ptrace − process trace

SYNOPSIS

#include <sys/ptrace.h>
int ptrace (request, pid, addr, data);
int request, pid, addr, data;

DESCRIPTION

ptrace provides a means by which a process may control the execution of another process.  The controlling process is known as the debugging process, or debugger.  The process being controlled is known as the debuggee process, or debuggee.  Its primary use is for the implementation of breakpoint debugging.  The debuggee process behaves normally until it encounters a signal (see signal(2) for the list), at which time it enters a stopped state and the debugging process is notified via wait(2), wait3(2) or waitpid(2).  When the debuggee is in the stopped state, the debugger can examine and modify its ”core image” using ptrace.  Also, the debugger can cause the debuggee either to terminate or continue, with the possibility of ignoring the signal that caused it to stop. 

The request argument determines the precise action to be taken by ptrace and is one of the following:

PT_TRACE_ME
This request must be issued by a child process 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 func; see signal(2).  The pid, addr, and data arguments are ignored, and a return value is not defined for this request.  Peculiar results will ensue if the parent does not expect to trace the child. 

The remainder of the requests can only be used by the debugger process.  For each, pid is the process ID of the child.  The child must be in a stopped state before these requests are made. 

PT_READ_I, PT_READ_D
With these requests, the word at location addr in the address space of the child is returned to the parent process.  Either request PT_READ_I or request PT_READ_D may be used with equal results.  The data argument is ignored.  These two requests will fail if addr is not the start address of a word, in which case a value of −1 is returned to the parent process and the parent’s errno is set to ­EIO. 

PT_READ_U
With this request, information about the debuggee stored in the kernel address space is made available to the debugging process.  This information is referenced by addr . 
 
addr is interpreted as a word offset into a synthetic structure struct ptrace_user which is defined in <sys/ptrace.h>.  The request will fail if addr is not a relative word offset within struct ptrace_user.  Upon failure, a value of -1 is returned to the debugger process and the debugger’s errno is set to [EIO]. 

PT_WRITE_I, PT_WRITE_D
With these requests, the value given by the data argument is written into the address space of the child at location addr. Either request PT_WRITE_I or request PT_WRITE_D may be used with equal results. Upon successful completion, the value written into the address space of the child is returned to the parent. These two requests will fail if addr is a location in a pure procedure space and another process is executing in that space, or addr is not the start address of a word.  Upon failure a value of −1 is returned to the parent process and the parent’s errno is set to EIO. 

PT_WRITE_U
With this request, information about the debuggee stored in the kernel can be changed.  This is similar to the request PT_READ_U above, but only the entries of the ptrace_user structure in the following list can be changed; if other structure members are changed, the ptrace() call shall fail and return -1 with errno set to [EIO]. 
 

pt_r0-pt_r31General purpose registers
pt_psrProcessor status register.
Only the byte order, carry, misaligned
access, and serialize bits may be changed.
pt_fpsrFloating point user status register
pt_sigtblSignal table entries.
pt_sigframeSignal Interface Data Structure

PT_CONTINUE
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 are canceled before it 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 canceled.  The addr 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 a value of −1 is returned to the parent process and the parent’s errno is set to EIO. 

PT_KILL
This request causes the child to terminate with the same consequences as exit(2). 

PT_STEP
This request sets the trace bit in the Processor Status Word of the child and then executes the same steps as listed above for request PT_CONTINUE.  The trace bit causes an interrupt upon completion of one machine instruction.  This effectively allows single stepping of the child. 

PT_TRACE_CHILD
A child process which is forked by a debuggee inherits the debuggee’s debugging process, address space, and trace state, including the current set of breakpoints. The pid argument is the process ID of the debuggee.  The inheritance state is not automatically passed to succeeding generations of child processes. 

PT_TRACE_PROC
The debugger initiates a debugging session with an existing process whose process ID is specified in pid.  The original parent of the existing process shall remain its parent process. When the debuggee encounters a signal, the debugger, not the parent, is notified via wait(2), wait3(2) or waitpid(2).  Either the debugger must run as superuser, or have the ACC_PTATTACH access vector, or its effective user ID must match the real and saved user ID of the debugee and its effective group ID must match the real and saved group ID of the debuggee. The controlling tty of either process is not changed.  If the debugger’s effective user ID is not super user, or it does not have the ACC_MAC_EXP bit set in its access vector, the debugger’s current security label must be identical to the debuggee’s security label. A debugger must not attach to a process which is currently a debuggee. The debugger must not become the debugger of its debugger (either directly or through a process chain). The debugger may initiate a debugging session with an existing debugging process. A debugger must not attach to a process which is connected to a user level interrupt.

PT_RELEASE_PROC
The debugger terminates a debugging session with the process whose process ID is specified in pid.  This request causes the process to resume execution.  If addr is not 1, then addr will get truncated to a multiple of 4, SNIP shall be set to addr and SFIP will be set to addr +4. In both the SNIP and the SFIP the valid bits will be set and the exception bits cleared.  This modification of the instruction pointers shall be done before any signal is delivered to the debuggee.  Pending signals are not discarded.

If request PT_TRACE_CHILD is used, the wait(2), wait3(2) or waitpid(2) call can be used to notify the debugging process that the debuggee is in the stopped or terminated state. 

To forestall possible fraud, ptrace inhibits the set-user-id facility on subsequent exec(2) calls.  If a traced process calls exec, it will stop before executing the first instruction of the new image showing signal SIGTRAP. 

GENERAL ERRORS

ptrace will in general fail if one or more of the following are true:

[EIO] Request is an illegal number. 

[ESRCH] Pid identifies a process that does not exist or is not being traced. 

[EEXIST] Pid identifies a process which is being traced, but is not stopped. 

[EPERM] Request is PT_TRACE_PROC and the debugger is not superuser, or its effective user ID does not match the real and saved user ID of the debuggee and its effective group ID does not match the real and saved group ID of the debuggee, or it does not have the ACC_PTATTACH access vector. (IF access vectors are configured)

[EPERM] Request is PT_TRACE_PROC and the debugger’s current security label is not identical to the debuggee’s security label, and the debuggers effective user id is not super user or it does not have the ACC_MAC_EXP bit in its access vector. (If access vectors are configured) (B1 only)

[EACCESS] Request is PT_TRACE_PROC and debugger is trying to attach to a process which is connected to a user level interrupt. 

[EINVAL] Request is PT_TRACE_PROC and the debugger tried to attach to a process which is currently a debugee, or the debugger would become the debugger of its debugger. 

SEE ALSO

exec(2), signal(2), wait(2), wait3(2), waitpid(2). 
iconnect(2) in the CX/UX User’s Reference Manual. 

CX/UX Programmer’s Reference Manual