NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO
#include <sys/types.h> #include <sys/ptrace.h>int ptrace(int request, pid_t pid, char *addr, int data, char *addr2);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
ACTOR_SRCDBG
ptrace() provides tracing and debugging facilities. It allows one process (the tracing process) to control another (the traced process). It's primary use is the implementation of breakpoint debugging. The traced process behaves normally until it encounters an exception, at which time it enters a stopped state and the debugger is notified using wait(2POSIX).
The system maintains the concept of a target thread, which is the identifier of the thread that encountered the exception. Some ptrace() requests apply to the thread identified by the value of the target thread (PT_STEP, PT_SETREGS, and PT_GETREGS.) The target thread is (re)set by the system as soon as a thread causes the process to stop. It can also be reset by the debugger using a specific ptrace() request.
When the process is stopped, the debugger can examine and modify its core image using ptrace(). The debugger can also make the process terminate or continue. By using the PT_THREADSUSPEND and PT_THREADRESUME requests before making the process continue execution using PT_CONTINUE, the debugger can restart a subset of the threads within the process.
The request argument determines the precise action to be taken by ptrace(). For each request, the pid argument specifies the process ID of the traced process. If the semantics of the addr, data or addr2 arguments are not specified for a request, those arguments are ignored. Except for PT_STOP request, the debugged process must be in a stopped state before the requests can be made.
These requests read a single int
of data from the address space of the traced process. Traditionally, ptrace() has allowed for machines with distinct address spaces for
instructions and for data, which is why there are two requests. Conceptually, PT_READ_I reads from the instruction space and PT_READ_D reads from the data space.
The addr argument specifies the address (in the traced process's virtual address space) at which the read is to be done. The value read is returned as the return value from ptrace().
These two requests will fail if addr is not the start address of a word or is outside the process's address space. In this case, a value of -1 is returned and errno is set to EFAULT.
These requests parallel PT_READ_I and PT_READ_D, except that they write rather than read. The data argument supplies the value to be written.
These two requests will fail if addr is not the start address of a word or is outside the process's address space. In this case, a value of -1 is returned and errno is set to EFAULT.
This request causes the process to resume execution. The target thread resumes execution at address addr specifying the place where execution is to be resumed (a new value for the program counter), or (char*)1 to indicate that execution is to pick up where it left off.
All other threads will also resume execution, unless suspended by PT_THREADSUSPEND.
This request sets the trace bit in the Processor Status Word of the target thread. It then executes the same steps listed above for the PT_CONT request, with the exception that only the target thread will be restarted. All other threads remain in a stopped state. The trace bit causes an exception upon completion of one machine instruction, which allows single-stepping of the target thread.
This request causes the process to terminate with the same consequences as _exit(2K).
This request allows a process to gain control of an otherwise unrelated process and begin tracing it. It does not need any cooperation from the to-be-traced process. In this case, pid specifies the process ID of the to-be-traced process and the other two arguments are ignored. The tracing process will see the newly-traced process stop and may then control it as if it had been traced all along.
This request is like PT_CONTINUE, except that it does not allow specification of an alternate place to continue execution. In addition, on success, the traced process is no longer traced and continues execution normally.
PT_GETREGS
returns the registers of the target thread in the process designated by pid to a table pointed to by addr. The
registers table type is "regs
" as described in <sys/reg_f.h>.
PT_SETREGS writes the registers of the target thread in the process
designated by pid from a table pointed to by addr. The registers table type is "regs
"
as described in <sys/reg_f.h>.
The identifier of the current target thread is returned.
Set the target thread to the thread identified by the data argument.
Suspend the thread identified by data (see threadSuspend(2K)). If that thread is the thread that caused the process to stop, the thread will only be suspended at the time the debugger restarts the process using a PT_CONTINUE or PT_DETACH.
Resume the thread identified by data (see threadResume(2K)).
Get or set the symbolic name of the thread identified by data.
Some requests can cause ptrace() to return -1 as a non-error value; to disambiguate, errno can be set to 0 before the call and checked afterwards.
The ptrace() function may fail if:
PT_ATTACH was attempted on a process that was already being traced.
A request attempted to manipulate a process that was being traced by some process other than the one making the request.
A request (other than PT_ATTACH) specified a process that was not stopped.
The addr to PT_READ_I, PT_READ_D, PT_WRITE_I, or PT_WRITE_D was not the start address of a word or was outside the process's address space.
A process attempted to use PT_ATTACH on itself.
The request was not one of the legal requests.
The addr to PT_READ_U or PT_WRITE_U was not int
-aligned.
PT_GETREGS or PT_SETREGS was attempted on a process with no valid register set.
A request (other than PT_ATTACH) attempted to manipulate a process that was not being traced at all.
An attempt was made to use PT_ATTACH on a process in violation of the requirements listed under PT_ATTACH above.
No process with the specified process ID exists, or the operation is not permitted outside the context of an exception.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO