1PTRACE(2) System Calls Manual PTRACE(2)
2
6 ptrace - process trace
7
9 #include <sys/signal.h>
10 #include <sys/ptrace.h>
11 ptrace(request, pid, addr, data)
13 int request, pid, *addr, data;
14
16 Ptrace provides a means by which a parent process may control the exe‐
17 cution of a child process, and examine and change its core image. Its
18 primary use is for the implementation of breakpoint debugging. There
19 are four arguments whose interpretation depends on a request argument.
20 Generally, pid is the process ID of the traced process, which must be a
21 child (no more distant descendant) of the tracing process. A process
22 being traced behaves normally until it encounters some signal whether
23 internally generated like “illegal instruction” or externally generated
24 like “interrupt”. See sigvec(2) for the list. Then the traced process
25 enters a stopped state and its parent is notified via wait(2). When
26 the child is in the stopped state, its core image can be examined and
27 modified using ptrace. If desired, another ptrace request can then
28 cause the child either to terminate or to continue, possibly ignoring
29 the signal.
30 The value of the request argument determines the precise action of the
32 call:
33 PT_TRACE_ME
35 This request is the only one used by the child process; it declares
36 that the process is to be traced by its parent. All the other
37 arguments are ignored. Peculiar results will ensue if the parent
38 does not expect to trace the child.
39 PT_READ_I, PT_READ_D
41 The word in the child process's address space at addr is returned.
42 If I and D space are separated (e.g. historically on a pdp-11),
43 request PT_READ_I indicates I space, PT_READ_D D space. Addr must
44 be even on some machines. The child must be stopped. The input
45 data is ignored.
46 PT_READ_U
48 The word of the system's per-process data area corresponding to
49 addr is returned. Addr must be even on some machines and less than
50 512. This space contains the registers and other information about
51 the process; its layout corresponds to the user structure in the
52 system.
53 PT_WRITE_I, PT_WRITE_D
55 The given data is written at the word in the process's address
56 space corresponding to addr, which must be even on some machines.
57 No useful value is returned. If I and D space are separated,
58 request PT_WRITE_I indicates I space, PT_WRITE_D D space. Attempts
59 to write in pure procedure fail if another process is executing the
60 same file.
61 PT_WRITE_U
63 The process's system data is written, as it is read with request
64 PT_READ_U. Only a few locations can be written in this way: the
65 general registers, the floating point status and registers, and
66 certain bits of the processor status word.
67 PT_CONTINUE
69 The data argument is taken as a signal number and the child's exe‐
70 cution continues at location addr as if it had incurred that sig‐
71 nal. Normally the signal number will be either 0 to indicate that
72 the signal that caused the stop should be ignored, or that value
73 fetched out of the process's image indicating which signal caused
74 the stop. If addr is (int *)1 then execution continues from where
75 it stopped.
76 PT_KILL
78 The traced process terminates.
79 PT_STEP
81 Execution continues as in request PT_CONTINUE; however, as soon as
82 possible after execution of at least one instruction, execution
83 stops again. The signal number from the stop is SIGTRAP. (On the
84 VAX-11 the T-bit is used and just one instruction is executed.)
85 This is part of the mechanism for implementing breakpoints.
86 As indicated, these calls (except for request PT_TRACE_ME) can be used
88 only when the subject process has stopped. The wait call is used to
89 determine when a process stops; in such a case the “termination” status
90 returned by wait has the value 0177 to indicate stoppage rather than
91 genuine termination.
92 To forestall possible fraud, ptrace inhibits the set-user-id and set-
94 group-id facilities on subsequent execve(2) calls. If a traced process
95 calls execve, it will stop before executing the first instruction of
96 the new image showing signal SIGTRAP.
97 On a VAX-11, “word” also means a 32-bit integer, but the “even”
99 restriction does not apply.
100
102 A 0 value is returned if the call succeeds. If the call fails then a
103 -1 is returned and the global variable errno is set to indicate the
104 error.
105
107 [EIO] The request code is invalid.
108 [ESRCH] The specified process does not exist.
110 [EIO] The given signal number is invalid.
112 [EIO] The specified address is out of bounds.
114 [EPERM] The specified process cannot be traced.
116
118 wait(2), sigvec(2), adb(1)
119
121 On the PDP-11 the PT_WRITE_U request may also write the child process's
122 current overlay number in the system data area; the T-bit is used to
123 single step the processor and just one instruction is executed for the
124 PT_STEP request; a “word” means a 16-bit integer, and the “even”
125 restriction does apply.
126
128 Ptrace is unique and arcane; it should be replaced with a special file
129 that can be opened and read and written. The control functions could
130 then be implemented with ioctl(2) calls on this file. This would be
131 simpler to understand and have much higher performance.
132 The request PT_TRACE_ME call should be able to specify signals that are
134 to be treated normally and not cause a stop. In this way, for example,
135 programs with simulated floating point (which use “illegal instruction”
136 signals at a very high rate) could be efficiently debugged.
137 The error indication, -1, is a legitimate function value; errno, (see
139 intro(2)), can be used to disambiguate.
140 It should be possible to stop a process on occurrence of a system call;
142 in this way a completely controlled environment could be provided.
1434th Berkeley Distribution May 23, 1986 PTRACE(2)