1PTRACE(2) System Calls Manual PTRACE(2)
2
6 ptrace - process trace
7
9 #include <signal.h>
10 ptrace(request, pid, addr, data)
12 int *addr;
13
15 Ptrace provides a means by which a parent process may control the exe‐
16 cution of a child process, and examine and change its core image. Its
17 primary use is for the implementation of breakpoint debugging. There
18 are four arguments whose interpretation depends on a request argument.
19 Generally, pid is the process ID of the traced process, which must be a
20 child (no more distant descendant) of the tracing process. A process
21 being traced behaves normally until it encounters some signal whether
22 internally generated like `illegal instruction' or externally generated
23 like `interrupt.' See signal(2) for the list. Then the traced process
24 enters a stopped state and its parent is notified via wait(2). When
25 the child is in the stopped state, its core image can be examined and
26 modified using ptrace. If desired, another ptrace request can then
27 cause the child either to terminate or to continue, possibly ignoring
28 the signal.
29 The value of the request argument determines the precise action of the
31 call:
32 0 This request is the only one used by the child process; it declares
34 that the process is to be traced by its parent. All the other
35 arguments are ignored. Peculiar results will ensue if the parent
36 does not expect to trace the child.
37 1,2 The word in the child process's address space at addr is returned.
39 If I and D space are separated, request 1 indicates I space, 2 D
40 space. Addr must be even. The child must be stopped. The input
41 data is ignored.
42 3 The word of the system's per-process data area corresponding to
44 addr is returned. Addr must be even and less than 512. This space
45 contains the registers and other information about the process; its
46 layout corresponds to the user structure in the system.
47 4,5 The given data is written at the word in the process's address
49 space corresponding to addr, which must be even. No useful value
50 is returned. If I and D space are separated, request 4 indicates I
51 space, 5 D space. Attempts to write in pure procedure fail if
52 another process is executing the same file.
53 6 The process's system data is written, as it is read with request 3.
55 Only a few locations can be written in this way: the general regis‐
56 ters, the floating point status and registers, and certain bits of
57 the processor status word.
58 7 The data argument is taken as a signal number and the child's exe‐
60 cution continues at location addr as if it had incurred that sig‐
61 nal. Normally the signal number will be either 0 to indicate that
62 the signal that caused the stop should be ignored, or that value
63 fetched out of the process's image indicating which signal caused
64 the stop. If addr is (int *)1 then execution continues from where
65 it stopped.
66 8 The traced process terminates.
68 9 Execution continues as in request 7; however, as soon as possible
70 after execution of at least one instruction, execution stops again.
71 The signal number from the stop is SIGTRAP. (On the PDP-11 the T-
72 bit is used and just one instruction is executed; on the Interdata
73 the stop does not take place until a store instruction is exe‐
74 cuted.) This is part of the mechanism for implementing break‐
75 points.
76 As indicated, these calls (except for request 0) can be used only when
78 the subject process has stopped. The wait call is used to determine
79 when a process stops; in such a case the `termination' status returned
80 by wait has the value 0177 to indicate stoppage rather than genuine
81 termination.
82 To forestall possible fraud, ptrace inhibits the set-user-id facility
84 on subsequent exec(2) calls. If a traced process calls exec, it will
85 stop before executing the first instruction of the new image showing
86 signal SIGTRAP.
87 On the Interdata 8/32, `word' means a 32-bit word and `even' means 0
89 mod 4.
90
92 wait(2), signal(2), adb(1)
93
95 The value -1 is returned if request is invalid, pid is not a traceable
96 process, addr is out of bounds, or data specifies an illegal signal
97 number.
98
100 On the Interdata 8/32, `as soon as possible' (request 7) means `as soon
101 as a store instruction has been executed.'
102 The request 0 call should be able to specify signals which are to be
104 treated normally and not cause a stop. In this way, for example, pro‐
105 grams with simulated floating point (which use `illegal instruction'
106 signals at a very high rate) could be efficiently debugged.
107 The error indication, -1, is a legitimate function value; errno, see
108 intro(2), can be used to disambiguate.
109 It should be possible to stop a process on occurrence of a system call;
111 in this way a completely controlled environment could be provided.
112
114 (ptrace = 26.)
115 (data in r0)
116 sys ptrace; pid; addr; request
117 (value in r0)
118 PTRACE(2)