ptrace(2)
NAME
ptrace − process trace
SYNTAX
#include <signal.h>
int ptrace(request, pid, addr, data)
int request, pid, *addr, data;
DESCRIPTION
The ptrace system call allows a parent process either to control the execution of, examine, or change the core image its child process. Its primary use is for the implementation of breakpoint debugging. There are four arguments whose interpretation depends on request. 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 (for example, an illegal instruction) or externally generated (for example, an interrupt). For further information, see signal(2). The traced process then enters a stopped state, and its parent is notified by a wait call. When the child is in the stopped state, its core image can be examined and modified using a ptrace call. If desired, another ptrace call then can cause the child either to terminate or to continue, possibly ignoring the signal.
The value of request determines the precise action of the call:
0 This request is the only one used by the child process. It declares that the process is to be traced by its parent. All the other arguments are ignored. Peculiar results will ensue if the parent does not expect to trace the child.
1,2 The word in the child process’s address space at addr is returned. If I and D space are separated, request 1 indicates I space, 2 D space. The addr must be even. The child must be stopped. The input data is ignored.
3 The word corresponding to addr is returned for each data area of the system. The addr must be even and less than 512. This space contains the registers and other information about the process. Its layout corresponds to 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 even. No useful value is returned. If I and D space are separated, request 4 indicates I space, 5 D space. Attempts to write in pure procedure will fail if another process is executing the same file.
6 The process’s system data is written similar to a read (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.
7 The data argument is taken as a signal number, and the child’s execution continues at location addr as if it had incurred that signal. Normally, the signal number will be either 0 to indicate that the signal that caused the stop should be ignored, or that 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 executing at least one instruction, execution stops again. The signal number from the stop is SIGTRAP. (On the PDP-11 the T-bit is used and just one instruction is executed.) This is part of the mechanism for implementing breakpoints.
As indicated, these requests (except 0) 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 call has the value 0177 to indicate stoppage rather than genuine termination.
To forestall possible fraud, ptrace inhibits the set-user-ID facility on subsequent exec calls. If a traced process calls exec, it will stop before executing the first instruction of the new image showing signal SIGTRAP.
RESTRICTIONS
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.
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
If unsuccessful, returns a −1, and the global variable errno indicates the error code.
DIAGNOSTICS
The ptrace call will fail if:
[EFAULT] The specified address is out of bounds.
[EIO] The request is an illegal number.
[EPERM] The specified process cannot be traced.
[ESRCH] The specified process does not exist.
ASSEMBLER
(ptrace = 26.)
(data in r0)
sys ptrace; pid; addr; request
(value in r0)