ptrace(2)
NAME
ptrace − process trace
SYNTAX
#include <signal.h>
#include <sys/ptrace.h>
ptrace(request, pid, addr, data)
int request, pid, *addr, data;
DESCRIPTION
The system call ptrace provides a means by which a process may control the execution of another 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. A process being traced behaves normally until it encounters some signal whether internally generated like “illegal instruction” or externally generated like “interrupt”. See sigvec(.).
Upon encountering a signal the traced process enters a stopped state and its tracing process is notified via wait(.). If the the traced process stops with a SIGTRAP the process may have been stopped for a number of reasons. Two status words addressable as registers in the traced process’s uarea qualify SIGTRAPs: TRAPCAUSE, which contains the cause of the trap, and TRAPINFO, which contains extra information concerning the trap.
When the traced process is in the stopped state, its core image can be examined and modified using ptrace. If desired, another ptrace request can then cause the traced process either to terminate or to continue, possibly ignoring the signal.
The value of the request argument determines the precise action of the call:
0 This request is the only one that may be used by a child process; it may declare that it is to be traced by its parent. All other arguments are ignored. Unexpected results occur if the parent process does not expect to trace the child process.
1,2 The word in the traced process’s address space at addr is returned. If I and D space are separated (for example, historically on a PDP-11), request 1 indicates I space, 2 D space. The addr must be 4-byte aligned. The traced process must be stopped. The input data is ignored.
3 The word of the system’s per-process data area corresponding to addr is returned. The addr is a constant defined in ptrace.h. This space contains the registers and other information about the process; the constants correspond to fields in the user structure in the system.
4,5 The given data is written at the word in the process’s address space corresponding to addr, which must be 4-byte aligned. The old value at the address is returned. If I and D space are separated, request 4 indicates I space, 5 D space. Attempts to write in pure procedure fail if another process is executing the same file.
6 The process’s system data is written, as it is read with request 3. Only a few locations can be written in this way: the general registers, the floating point status and registers, and certain bits of the processor status word. The old value at the address is returned.
7 The data argument is taken as a signal number and the traced process’s execution continues at location addr as if it had incurred that signal. Normally, the signal number is 0 to indicate that the signal which caused the stop should be ignored, or the value fetched out of the process’s image indicating which signal caused the stop. If addr is (int *)1 then execution continues from where it stopped.
8 The traced process terminates.
9 Execution continues as in request 7; however, as soon as possible after execution of at least one instruction, execution stops again. The signal number from the stop is SIGTRAP. TRAPCAUSE contains CAUSESINGLE. This is part of the mechanism for implementing breakpoints.
20 This is the same as zero except it is executed by the tracing process and the pid field is non-zero. The process with that pid will stop execution, become a traced process giving control back to the tracing process rather than the parent on a signal. The tracing process must have the same uid as the traced process.
21,22
Returns MAXREG general or MAXFREG floating registers, respectively. Their values will be copied to the locations starting at the address in the tracing process specified by the addr argument.
24,25
Same as 20 and 21, but writes the registers instead of reading them.
26 Specifies a watchpoint in the data or stack segment of the traced process. If any byte address starting at the addr argument and continuing for the number of bytes specified by the data argument is accessed in an instruction, then the traced process stops execution with a SIGTRAP. TRAPCAUSE will contain CAUSEWATCH and TRAPINFO will contain the address causing the trap. This ptrace returns a wid, or watchpoint identifier. MAXWIDS specifies the maximum number of watchpoints per process.
27 The data argument specifies a wid to delete.
28 Turns off the tracing for the traced process with the specified pid.
29 Returns an open file descriptor for the file attached to pid. This is useful in accessing the symbol table of an execed process.
As indicated, these calls (except for request 0 and 20) can be used only when the subject process has stopped. The wait call is used to determine when a process stops; in such a case the “termination” status returned by wait has the value 0177 to indicate stoppage rather than genuine termination. If multiple processes are being traced, wait can be called multiple times and it returns the status for the next stopped or terminated child or traced process.
To forestall possible fraud, ptrace inhibits the set-user-id and set-group-id facilities on subsequent exec() calls. If a traced process calls execve, it stops before executing the first instruction of the new image showing signal SIGTRAP. In this case, TRAPCAUSE contains CAUSEEXEC and TRAPINFO does not contain anything interesting. If a traced process execs again, the same thing occurs.
If a traced process forks, both parent and child are traced. Breakpoints from the parent are not copied into the child. At the time of the fork, the child is stopped with a SIGTRAP. The tracing process may then terminate the trace if desired. TRAPCAUSE contains CAUSEFORK and TRAPINFO contains the pid of its parent.
RESTRICTIONS
In ULTRIX, the ptrace system call only succeeds if the user owns the binary beging traced or if the user is root.
The request 0 call should be able to specify signals which are to be treated normally and not cause a stop. In this way, for example, programs with simulated floating point (which use “illegal instruction” signals at a very high rate) could be efficiently debugged.
The error indication, −1, is a legitimate function value; errno, see intro(,), can be used to disambiguate.
It should be possible to stop a process on occurrence of a system call; in this way a completely controlled environment could be provided.
RETURN VALUE
A 0 value is returned if the call succeeds. If the call fails then a −1 is returned and the global variable errno is set to indicate the error.
DIAGNOSTICS
[EIO] The request code is invalid.
[ESRCH] The specified process does not exist.
[EIO] The given signal number is invalid.
[EIO] The specified address is out of bounds.
[EPERM] The specified process cannot be traced.
SEE ALSO
System Calls