Commit | Line | Data |
---|---|---|
b07f73bb BJ |
1 | .TH PTRACE 2 |
2 | .SH NAME | |
3 | ptrace \- process trace | |
4 | .SH SYNOPSIS | |
5 | #include <signal.h> | |
6 | .PP | |
7 | .B ptrace(request, pid, addr, data) | |
8 | .br | |
9 | .B int *addr; | |
10 | .SH DESCRIPTION | |
11 | .I Ptrace | |
12 | provides a means by which a parent process | |
13 | may control the execution of a child process, | |
14 | and examine and change its core image. | |
15 | Its primary use is for the implementation of breakpoint debugging. | |
16 | There are four arguments whose interpretation | |
17 | depends on a | |
18 | .I request | |
19 | argument. | |
20 | Generally, | |
21 | .I pid | |
22 | is the process ID of the traced process, | |
23 | which must be a child (no more distant descendant) | |
24 | of the tracing process. | |
25 | A process being traced | |
26 | behaves normally until it encounters some signal whether internally generated | |
27 | like `illegal instruction' or externally generated like `interrupt.' | |
28 | See | |
29 | .IR signal (2) | |
30 | for the list. | |
31 | Then the traced process enters a stopped state | |
32 | and its parent is notified via | |
33 | .IR wait (2). | |
34 | When the child is in the stopped state, | |
35 | its core image can be examined and modified | |
36 | using | |
37 | .IR ptrace . | |
38 | If desired, another | |
39 | .I ptrace | |
40 | request can then cause the child either to terminate | |
41 | or to continue, possibly ignoring the signal. | |
42 | .PP | |
43 | The value of the | |
44 | .I request | |
45 | argument determines the precise | |
46 | action of the call: | |
47 | .TP 4 | |
48 | 0 | |
49 | This request is the only one used by the child process; | |
50 | it declares that the process is to be traced by its parent. | |
51 | All the other arguments are ignored. | |
52 | Peculiar results will ensue | |
53 | if the parent does not expect to trace the child. | |
54 | .TP 4 | |
55 | 1,2 | |
56 | The | |
57 | word in the child process's address space | |
58 | at | |
59 | .I addr | |
60 | is returned. | |
61 | If I and D space are separated, request 1 indicates I space, | |
62 | 2 D space. | |
63 | .I Addr | |
64 | must be even. | |
65 | The child must be stopped. | |
66 | The input | |
67 | .I data | |
68 | is ignored. | |
69 | .TP 4 | |
70 | 3 | |
71 | The word | |
72 | of the system's per-process data area corresponding to | |
73 | .I addr | |
74 | is returned. | |
75 | .I Addr | |
76 | must be even and less than 512. | |
77 | This space contains the registers and other information about | |
78 | the process; | |
79 | its layout corresponds to the | |
80 | .I user | |
81 | structure in the system. | |
82 | .TP 4 | |
83 | 4,5 | |
84 | The | |
85 | given | |
86 | .I data | |
87 | is written at the word in the process's address space corresponding to | |
88 | .I addr, | |
89 | which must be even. | |
90 | No useful value is returned. | |
91 | If I and D space are separated, request 4 indicates I space, | |
92 | 5 D space. | |
93 | Attempts to write in pure procedure | |
94 | fail if another process is executing the same file. | |
95 | .TP 4 | |
96 | 6 | |
97 | The process's system data is written, | |
98 | as it is read with request 3. | |
99 | Only a few locations can be written in this way: | |
100 | the general registers, | |
101 | the floating point status and registers, | |
102 | and certain bits of the processor status word. | |
103 | .TP 4 | |
104 | 7 | |
105 | The | |
106 | .I data | |
107 | argument is taken as a signal number | |
108 | and the child's execution continues | |
109 | at location | |
110 | .I addr | |
111 | as if it had incurred that signal. | |
112 | Normally the signal number will be | |
113 | either 0 to indicate that the signal that caused the stop | |
114 | should be ignored, | |
115 | or that value fetched out of the | |
116 | process's image indicating which signal caused | |
117 | the stop. | |
118 | If | |
119 | .I addr | |
120 | is (int *)1 then execution continues from where it stopped. | |
121 | .TP 4 | |
122 | 8 | |
123 | The traced process terminates. | |
124 | .TP 4 | |
125 | 9 | |
126 | Execution continues as in request 7; | |
127 | however, as soon as possible after execution of at least one instruction, | |
128 | execution stops again. | |
129 | The signal number from the stop is | |
130 | SIGTRAP. | |
131 | (On the PDP-11 and VAX-11 the T-bit is used and just one instruction | |
132 | is executed; | |
133 | on the Interdata the stop does not take place | |
134 | until a store instruction is executed.) | |
135 | This is part of the mechanism for implementing breakpoints. | |
136 | .PP | |
137 | As indicated, | |
138 | these calls | |
139 | (except for request 0) | |
140 | can be used only when the subject process has stopped. | |
141 | The | |
142 | .I wait | |
143 | call is used to determine | |
144 | when a process stops; | |
145 | in such a case the `termination' status | |
146 | returned by | |
147 | .I wait | |
148 | has the value 0177 to indicate stoppage rather | |
149 | than genuine termination. | |
150 | .PP | |
151 | To forestall possible fraud, | |
152 | .I ptrace | |
153 | inhibits the set-user-id facility | |
154 | on subsequent | |
155 | .IR exec (2) | |
156 | calls. | |
157 | If a traced process calls | |
158 | .I exec, | |
159 | it will stop before executing the first instruction of the new image | |
160 | showing signal SIGTRAP. | |
161 | .PP | |
162 | On the Interdata 8/32, | |
163 | `word' means a 32-bit word and `even' means 0 mod 4. | |
164 | On a VAX-11, `word' also means a 32-bit integer, but the `even' restriction | |
165 | does not apply. | |
166 | .SH "SEE ALSO" | |
167 | wait(2), signal(2), adb(1) | |
168 | .SH DIAGNOSTICS | |
169 | The value \-1 is returned if | |
170 | .I request | |
171 | is invalid, | |
172 | .I pid | |
173 | is not a traceable process, | |
174 | .I addr | |
175 | is out of bounds, | |
176 | or | |
177 | .I data | |
178 | specifies an illegal signal number. | |
179 | .SH BUGS | |
180 | On the Interdata 8/32, | |
181 | `as soon as possible' (request 7) | |
182 | means `as soon as a store instruction has been executed.' | |
183 | .PP | |
184 | The request 0 call should be able to specify | |
185 | signals which are to be treated normally and not cause a stop. | |
186 | In this way, for example, | |
187 | programs with simulated floating point (which | |
188 | use `illegal instruction' signals at a very high rate) | |
189 | could be efficiently debugged. | |
190 | .br | |
191 | The error indication, \-1, is a legitimate function value; | |
192 | .I errno, | |
193 | see | |
194 | .IR intro (2), | |
195 | can be used to disambiguate. | |
196 | .PP | |
197 | It should be possible to stop a process on occurrence of a system | |
198 | call; | |
199 | in this way a completely controlled environment could | |
200 | be provided. | |
201 | .SH ASSEMBLER | |
202 | (ptrace = 26.) | |
203 | .br | |
204 | (data in r0) | |
205 | .br | |
206 | .B sys ptrace; pid; addr; request | |
207 | .br | |
208 | (value in r0) |