PTRACE(2)
NAME
ptrace − process trace
USAGE
#include <signal.h>
ptrace(request, pid, addr, data) int request, pid, *addr, data;
DESCRIPTION
Ptrace provides a means by which a parent process may control the execution of a child process and examine and change its core image. Its primary use is for the implementation of breakpoint debugging. There are four arguments whose interpretation depends on a request argument. Generally, pid is the process ID of the traced process, which must be a child (no more distant descendant) of the tracing process. A process being traced behaves normally until it encounters some signal whether internally generated like “illegal instruction” or externally generated like “interrupt”. See sigvec(2) for the list. Then the traced process enters a stopped state and its parent is notified via wait(2). When the child is in the stopped state, its core image can be examined and modified using ptrace. If desired, another ptrace request can then cause the child either to terminate or to continue, possibly ignoring the signal.
The value of the request argument determines the precise action of the call:
Note: Where two numbers are associated with a request (an artifact of implementations with separate instruction and data space), either number may be used.
Request zero can only be used in the child. Non-zero requests can only be used by the parent. For each non-zero request, pid is the process ID of the child. The child must be in a stopped state before these requests are made.
0 Child trace flag. This is the only request that can be issued by the child. It stipulates that the child should be left in a stopped state upon receipt of a signal rather than the state specified by any func; argument associated with a signal(2) call in the child. 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.
1, 2 return the word at location addr in the address space of the child. On DOMAIN Systems, either request 1 or request 2 may be used with identical results. If addr is not the start address of a word, a value of −1 is returned to the parent process and the parent’s errno is set to EIO.
3 return the word at offset addr into the child’s USER area in the system’s address space (see <sys/user.h>) to the parent process. (Only 16 bits can be read.) If addr is not the start address of a word or is outside the USER area, a value of -1 is returned to the parent process and the parent’s errno is set to EIO.
4, 5 write the value given by the data argument into the address space of the child at location addr. Upon successful completion, the value written into the address space of the child is returned to the parent. If addr is a location in a pure procedure space and another process is executing in that space, or if addr is not the start address of a word, these requests will fail, a value of −1 will be returned to the parent process, and the parent’s errno will be set to EIO.
6 write one of the following entries, where data is a 16-bit value to be written and addr is the location of the entry in the child’s USER area:
M68xxx processor registers (A0-A7, D0-D7).
The condition codes (bits 0-7) of the Processor Status Word
7 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. If data is not 0 or a valid signal number, this request will fail, a value of −1 will be returned to the parent process, and the parent’s errno will be set to EIO.
8 This request causes the child to terminate with the same consequences as _exit(2).
9 This request sets the trace bit in the Processor Status Word of the child (bit 15 on M68xxx processors) and then executes the same steps as listed above for request 7. The trace bit causes an interrupt upon completion of one machine instruction. This effectively allows single stepping of the child. The trace bit is turned off after interrupt.
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.
NOTES
The error indication, -1, can be is a legitimate function value. Errno, see intro(2), can be used to disambiguate.
RETURN VALUE
A successful call returns zero. A failed call returns -1 and sets errno as indicated below.
ERRORS
[EINVAL] The request code is invalid.
[EINVAL] The specified process does not exist.
[EINVAL] The given signal number is invalid.
[EFAULT] The specified address is out of bounds.
[EPERM] The specified process cannot be traced.