Traces the execution of another process.
Standard C Library (libc.a)
#include <sys/reg.h>
#include <sys/ptrace.h>
#include <sys/ldr.h>
int ptrace ( Request, Identifier, Address, Data, Buffer)
int Request;
int Identifier;
int *Address;
int Data;
int *Buffer;
int ptracex ( request, identifier, addr, data, buff)
int request;
int identifier;
long long addr;
int data;
int *buff;
int ptrace64 ( request, identifier, addr, data, buff)
int request;
long long identifier;
long long addr;
int data;
int *buff;
The ptrace subroutine allows a 32-bit process to trace the execution of another process. The ptrace subroutine is used to implement breakpoint debugging.
A debugged process runs normally until it encounters a signal. Then it enters a stopped state and its debugging process is notified with the wait subroutine.
Exception: If the process encounters the SIGTRAP signal, a signal handler for SIGTRAP exists, and fast traps (Fast Trap Instructions) have been enabled for the process, then the signal handler is called and the debugger is not notified. This exception only applies to AIX® 4.3.3 and later releases.
While the process is in the stopped state, the debugger examines and modifies the memory image of the process being debugged by using the ptrace subroutine. For multi-threaded processes, the getthrds (getthrds Subroutine) subroutine identifies each kernel thread in the debugged process. Also, the debugging process can cause the debugged process to terminate or continue, with the possibility of ignoring the signal that caused it to stop.
As a security measure, the ptrace subroutine inhibits the set-user-ID facility on subsequent exec subroutines.
(This paragraph only applies to AIX 4.3.2 and later releases.) When a process running under ptrace control calls load or unload, the debugger is notified and the W_SLWTED flag is set in the status returned by wait. (A 32-bit process calling loadbind is stopped as well.) If the process being debugged has added modules in the shared library to its address space, the modules are added to the process's private copy of the shared library segments. If shared library modules are removed from a process's address space, the modules are deleted from the process's private copy of the library text segment by freeing the pages that contain the module. No other changes to the segment are made, and existing breakpoints do not have to be reinserted.
To allow a debugger to generate code more easily (in order to handle fast trap instructions, for example), memory from the end of the main program up to the next segment boundary can be modified. That memory is read-only to the process but can be modified by the debugger.
When a process being traced forks, the child process is initialized with the unmodified main program and shared library segment, effectively removing breakpoints in these segments in the child process. If multiprocess debugging is enabled, new copies of the main program and shared library segments are made. Modifications to privately loaded modules, however, are not affected by a fork. These breakpoints will remain in the child process, and if these breakpoints are run, a SIGTRAP signal is generated and delivered to the process.
If a traced process initiates an exec subroutine, the process stops before executing the first instruction of the new image and returns the SIGTRAP signal.
Fast Trap Instructions
Sometimes, allowing the process being debugged to handle certain trap instructions is useful, instead of causing the process to stop and notify the debugger. You can use this capability to patch running programs or programs whose source codes are not available. For a process to use this capability, you must enable fast traps, which requires you to make a ptrace call from a debugger on behalf of the process.
To let a process handle fast traps, a debugger uses the ptrace (PT_SET, pid, 0, PTFLAG_FAST_TRAP, 0) subroutine call. Cancel this capability with the ptrace (PT_CLEAR, pid, 0, PTFLAG_FAST_TRAP, 0) subroutine call. If a process is able to handle fast traps when the debugger detaches, the fast trap capability remains in effect. Consequently, when another debugger attaches to that process, fast trap processing is still enabled. When no debugger is attached to a process, SIGTRAP signals are handled in the same manner, regardless of whether fast traps are enabled.
A fast trap instruction is an unconditional trap immediate instruction in the form twi 14,r13,0xNXXX. This instruction has the binary form 0x0ddfNXXX, where N is a hex digit >=8 and XXX are any three hex digits. By using different values of 0xNXXX, a debugger can generate different fast trap instructions, allowing a signal handler to quickly determine how to handle the signal. (The fast trap instruction is defined by the macro _PTRACE_FASTTRAP. The _PTRACE_FASTTRAP_MASK macro can be used to check whether a trap is a fast trap.)
Usually, a fast trap instruction is treated like any other trap instruction. However, if a process has a signal handler for SIGTRAP, the signal is not blocked, and the fast trap capability is enabled, then the signal handler is called and the debugger is not notified.
A signal handler can logically AND the trap instruction with _PTRACE_FASTTRAP_NUM (0x7FFF) to obtain an integer identifying which trap instruction was run.
Fast data watchpoint
In AIX 5.3 ML5 and later, ptrace supports the ability to enable fast watchpoint trap handling. This is similar to fast trap instruction handling in that when it is enabled. Processes that have a signal handler for SIGTRAP will have the handler called when a watchpoint trap is encountered. In the SIGTRAP signal handler, the traced process can detect a fast watchpoint trap by checking the SI_FAST_WATCH in the _si_flags of the siginfo_t that is passed to the handler. The fast watchpoint handling employs trap-after semantics, which means that the store to the watched location is completed before calling the trap handler, so the instruction address pointer in the signal context that is passed to the handler will point to the instruction following the instruction that caused the trap.
Thread-level tracing
In AIX 5.3 ML5 and later, ptrace supports setting breakpoints and watchpoints per-thread for system scope (1:1) threads. With these, the tracing process (debugger) is only notified when the specific thread of interest has encountered a trap. This provides an efficient means for debuggers to trace individual threads of interest since it doesn’t have to filter “false hit” notifications. See the PTT_WATCH, PTT_SET_TRAP, and PTT_CLEAR_TRAP request types below for the usage description.
The ptrace programming model remains unchanged with thread-level breakpoints and watchpoints in that the attachment is still done at the process level, and the target process stops and notifies the tracing process upon encountering a trap. The tracing process can detect that the traced process has stopped for a thread-level trap by checking the TTHRDTRAP flag (in ti_flag2) of the stopping thread (the thread with TTRCSIG set in ti_flag). These flags can be checked by calling getthrds64 on the target process.
Other behaviors that are specific to thread-level tracing:
For the 64-bit Process
Use ptracex where the debuggee is a 64-bit process and the operation requested uses the third (Address) parameter to reference the debuggee's address space or is sensitive to register size. Note that ptracex and ptrace64 will also support 32-bit debugees.
If returning or passing an int doesn't work for a 64-bit debuggee (for example, PT_READ_GPR), the buffer parameter takes the address for the result. Thus, with the ptracex subroutine, PT_READ_GPR and PT_WRITE_GPR take a pointer to an 8 byte area representing the register value.
In general, ptracex supports all the calls that ptrace does when they are modified for any that are extended for 64-bit addresses (for example, GPRs, LR, CTR, IAR, and MSR). Anything whose size increases for 64-bit processes must be allowed for in the obvious way (for example, PT_REGSET must be an array of long longs for a 64-bit debuggee).
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to one the following codes:
The Identifier parameter specifies the process ID of the traced process. The Address parameter, Buffer parameter, and the unused bits in the Data parameter are reserved for future use and should be set to 0.
The Identifier parameter is a valid kernel thread ID in the target process (-1 for all). The Address parameter is the address of the breakpoint. The Data parameter must be 0. The Buffer parameter must be NULL.
If the request is unsuccessful, -1 is returned and the errno global variable is set to one of the following:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
The Address parameter specifies where to resume execution:
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 maximum 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:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
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 first element of the list corresponds to the main executable module. The ld_info structures are defined in the /usr/include/sys/ldr.h file. The linked list is implemented so that the ldinfo_next field of each element gives the offset of the next element from this element. The ldinfo_next field of the last element has the value 0.
Each object module reported is opened on behalf of the debugger process. The file descriptor for an object module is saved in the ldinfo_fd field of the corresponding ld_info structure. The debugger process is responsible for managing the files opened by the ptrace subroutine.
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
This request is similar to the PT_LDINFO request. A linked list of ld_xinfo structures is returned instead of a list of ld_info structures. The first element of the list corresponds to the main executable module. The ld_xinfo structures are defined in the /usr/include/sys/ldr.h file. The linked list is implemented so that the ldinfo_next field of each element gives the offset of the next element from this element. The ldinfo_next field of the last element has the value 0.
Each object module reported is opened on behalf of the debugger process. The file descriptor for an object module is saved in the ldinfo_fd field of the corresponding ld_xinfo structure. The debugger process is responsible for managing the files opened by the ptrace subroutine.
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
Also, when multiprocess debugging mode is enabled, the following values are returned from the wait subroutine:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to one of the following codes:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to one the following codes:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
The Identifier parameter specifies the process ID of the traced process. The Address parameter, Buffer parameter, and the unused bits in the Data parameter are reserved for future use and should be set to 0.
The Identifier parameter is a valid kernel ID in the target process. The Address parameter is the address in the target process for the breakpoint. The Data parameter is the length of data in Buffer, it must be 4. The Buffer parameter is a pointer to trap instruction to be written.
The system call will not evaluate the contents of the buffer for this request, but by convention, it should contain a single trap instruction.
If the request is unsuccessful, a value of -1 is returned and the errno global variable is set to one of the following:
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) If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored. The Address parameter specifies beginning of the memory region to be watched. To clear the watchpoint the Address parameter must be NULL. The Data parameter specifies the size of the memory region.
Watchpoints are supported only on the hardware POWER6®30, POWER5 and POWER6. Currently the size of the memory region, that is, the parameter Data must be 8 because only 8 byte watchpoint is supported at the hardware level.
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
The Identifier parameter is a valid kernel thread ID in the target process ( -1 for all). The Address parameter is the double-worded aligned address to watch. A value of 0 clears the watchpoint. The Data parameter must be 0 (clear) or 8 (set). The Buffer parameter must be NULL.
If the request is unsuccessful, a value of -1 is returned and the errno global variable is set to one of the following:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to one of the following codes:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
If this request is unsuccessful, a value of -1 is returned and the errno global variable is set to the following code:
The ptrace subroutine is unsuccessful when one of the following is true:
| Item | Description |
|---|---|
| EFAULT | The Buffer parameter points to a location outside the debugging process address space. |
| EINVAL | The debugger and the traced process are the same; or the Identifier parameter does not identify the thread that caused the exception. |
| EIO | The Request parameter is not one of the values listed, or the Request parameter is not valid for the machine type on which the process is run. |
| 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. |
| ENXIO | The target thread has not referenced the VMX unit and is not currently a VMX thread. |
| EPERM | The Identifier parameter corresponds to a kernel thread which is stopped in kernel mode and whose computational state cannot be read or written. |
| ESRCH | The Identifier parameter identifies a process or thread that does not exist, that has not run a ptrace call with the PT_TRACE_ME request, or that is not stopped. |
For ptrace: If the debuggee is a 64-bit process, the options that refer to GPRs or SPRs fail with errno = EIO, and the options that specify addresses are limited to 32-bits.
For ptracex or ptrace64: If the debuggee is a 32-bit process, the options that refer to GPRs or SPRs fail with errno = EIO, and the options that specify addresses in the debuggee's address space that are larger than 2**32 - 1 fail with errno set to EIO.
Also, the options PT_READ_U and PT_WRITE_U are not supported if the debuggee is a 64-bit program (errno = ENOTSUP).