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