| @@ -1,731 +1,738 @@ | | | @@ -1,731 +1,738 @@ |
1 | .\" $NetBSD: ptrace.2,v 1.56 2017/01/15 22:18:11 kamil Exp $ | | 1 | .\" $NetBSD: ptrace.2,v 1.57 2017/01/25 17:12:56 kamil Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" This file is in the public domain. | | 3 | .\" This file is in the public domain. |
4 | .Dd January 14, 2016 | | 4 | .Dd January 25, 2016 |
5 | .Dt PTRACE 2 | | 5 | .Dt PTRACE 2 |
6 | .Os | | 6 | .Os |
7 | .Sh NAME | | 7 | .Sh NAME |
8 | .Nm ptrace | | 8 | .Nm ptrace |
9 | .Nd process tracing and debugging | | 9 | .Nd process tracing and debugging |
10 | .Sh LIBRARY | | 10 | .Sh LIBRARY |
11 | .Lb libc | | 11 | .Lb libc |
12 | .Sh SYNOPSIS | | 12 | .Sh SYNOPSIS |
13 | .In sys/types.h | | 13 | .In sys/types.h |
14 | .In sys/ptrace.h | | 14 | .In sys/ptrace.h |
15 | .Ft int | | 15 | .Ft int |
16 | .Fn ptrace "int request" "pid_t pid" "void *addr" "int data" | | 16 | .Fn ptrace "int request" "pid_t pid" "void *addr" "int data" |
17 | .Sh DESCRIPTION | | 17 | .Sh DESCRIPTION |
18 | .Fn ptrace | | 18 | .Fn ptrace |
19 | provides tracing and debugging facilities. | | 19 | provides tracing and debugging facilities. |
20 | It allows one process (the | | 20 | It allows one process (the |
21 | .Em tracing | | 21 | .Em tracing |
22 | process) to control another (the | | 22 | process) to control another (the |
23 | .Em traced | | 23 | .Em traced |
24 | process). | | 24 | process). |
25 | Most of the time, the traced process runs normally, but when | | 25 | Most of the time, the traced process runs normally, but when |
26 | it receives a signal | | 26 | it receives a signal |
27 | .Po | | 27 | .Po |
28 | see | | 28 | see |
29 | .Xr sigaction 2 | | 29 | .Xr sigaction 2 |
30 | .Pc , | | 30 | .Pc , |
31 | it stops. | | 31 | it stops. |
32 | The tracing process is expected to notice this via | | 32 | The tracing process is expected to notice this via |
33 | .Xr wait 2 | | 33 | .Xr wait 2 |
34 | or the delivery of a | | 34 | or the delivery of a |
35 | .Dv SIGCHLD | | 35 | .Dv SIGCHLD |
36 | signal | | 36 | signal |
37 | .Po | | 37 | .Po |
38 | see | | 38 | see |
39 | .Xr siginfo 2 | | 39 | .Xr siginfo 2 |
40 | .Pc , | | 40 | .Pc , |
41 | examine the state of the stopped process, and cause it to | | 41 | examine the state of the stopped process, and cause it to |
42 | terminate or continue as appropriate. | | 42 | terminate or continue as appropriate. |
43 | .Fn ptrace | | 43 | .Fn ptrace |
44 | is the mechanism by which all this happens. | | 44 | is the mechanism by which all this happens. |
45 | .Pp | | 45 | .Pp |
46 | When a process that is traced by a debugger requests and calls | | 46 | When a process that is traced by a debugger requests and calls |
47 | .Xr execve 2 | | 47 | .Xr execve 2 |
48 | or any of the routines built on it | | 48 | or any of the routines built on it |
49 | .Po | | 49 | .Po |
50 | such as | | 50 | such as |
51 | .Xr execv 3 | | 51 | .Xr execv 3 |
52 | .Pc , | | 52 | .Pc , |
53 | it will stop before executing the first instruction of the new image and emit | | 53 | it will stop before executing the first instruction of the new image and emit |
54 | .Dv SIGRAP | | 54 | .Dv SIGRAP |
55 | with | | 55 | with |
56 | .Dv si_code | | 56 | .Dv si_code |
57 | set to | | 57 | set to |
58 | .Dv TRAP_EXEC . | | 58 | .Dv TRAP_EXEC . |
59 | If a program is traced with the | | 59 | If a program is traced with the |
60 | .Dv PT_SYSCALL | | 60 | .Dv PT_SYSCALL |
61 | option enabled, | | 61 | option enabled, |
62 | this event notifier is disabled. | | 62 | this event notifier is disabled. |
63 | If a traced program calls | | 63 | If a traced program calls |
64 | .Xr execve 2 | | 64 | .Xr execve 2 |
65 | any setuid or setgid bits on the executable being executed will be ignored. | | 65 | any setuid or setgid bits on the executable being executed will be ignored. |
66 | .Pp | | 66 | .Pp |
67 | Program (software) breakpoints are reported with | | 67 | Program (software) breakpoints are reported with |
68 | .Dv SIGTRAP | | 68 | .Dv SIGTRAP |
69 | and the | | 69 | and the |
70 | .Dv si_code | | 70 | .Dv si_code |
71 | value set to | | 71 | value set to |
72 | .Dv TRAP_BKPT . | | 72 | .Dv TRAP_BKPT . |
73 | These breakpoints are machine specific instructions that interrput the process. | | 73 | These breakpoints are machine specific instructions that interrput the process. |
74 | In order to put a trap by a tracer into the tracee's program, | | 74 | In order to put a trap by a tracer into the tracee's program, |
75 | debugger must violate the | | 75 | debugger must violate the |
76 | .Dv PaX MPROTECT | | 76 | .Dv PaX MPROTECT |
77 | restrictions. | | 77 | restrictions. |
78 | For details check the | | 78 | For details check the |
79 | .Dv security.pax.mprotect.ptrace | | 79 | .Dv security.pax.mprotect.ptrace |
80 | option described in | | 80 | option described in |
81 | .Xr sysctl 7 . | | 81 | .Xr sysctl 7 . |
82 | When a tracee is interrputed by a trap, | | 82 | When a tracee is interrputed by a trap, |
83 | the trap is not removed by the kernel and it must be handled by a debugger. | | 83 | the trap is not removed by the kernel and it must be handled by a debugger. |
84 | .Pp | | 84 | .Pp |
85 | If a program is traced with single steps | | 85 | If a program is traced with single steps |
86 | .Dv ( PT_STEP ) | | 86 | .Dv ( PT_STEP ) |
87 | it reports each step with | | 87 | it reports each step with |
88 | .Dv SIGTRAP | | 88 | .Dv SIGTRAP |
89 | with | | 89 | with |
90 | .Dv si_code | | 90 | .Dv si_code |
91 | set to | | 91 | set to |
92 | .Dv TRAP_TRACE . | | 92 | .Dv TRAP_TRACE . |
93 | This event is always enabled and cannot be disabled. | | 93 | This event is always enabled and cannot be disabled. |
94 | .Pp | | 94 | .Pp |
95 | Child program traps are reported with | | 95 | Child program traps are reported with |
96 | .Dv SIGTRAP | | 96 | .Dv SIGTRAP |
97 | and the | | 97 | and the |
98 | .Dv si_code | | 98 | .Dv si_code |
99 | value set to | | 99 | value set to |
100 | .Dv TRAP_CHLD . | | 100 | .Dv TRAP_CHLD . |
101 | These events are by default disabled and can be configured with | | 101 | These events are by default disabled and can be configured with |
102 | .Dv PT_SET_EVENT_MASK . | | 102 | .Dv PT_SET_EVENT_MASK . |
103 | If this event occurs, | | 103 | If this event occurs, |
104 | check with | | 104 | check with |
105 | .Dv PT_GET_PROCESS_STATE | | 105 | .Dv PT_GET_PROCESS_STATE |
106 | the details of the process state associated with this event. | | 106 | the details of the process state associated with this event. |
107 | .Pp | | 107 | .Pp |
108 | A debugger might reuse a port specific symbols, | | 108 | A debugger might reuse a port specific symbols, |
109 | to help writing portable code as described in the port specific part of the | | 109 | to help writing portable code as described in the port specific part of the |
110 | .In sys/ptrace.h | | 110 | .In sys/ptrace.h |
111 | header. | | 111 | header. |
112 | Among these symbols, | | 112 | Among these symbols, |
113 | there are: | | 113 | there are: |
114 | .Bl -dash | | 114 | .Bl -dash |
115 | .It | | 115 | .It |
116 | .Dv PTRACE_REG_PC | | 116 | .Dv PTRACE_REG_PC |
117 | .It | | 117 | .It |
118 | .Dv PTRACE_REG_SET_PC | | 118 | .Dv PTRACE_REG_SET_PC |
119 | .It | | 119 | .It |
120 | .Dv PTRACE_REG_SP | | 120 | .Dv PTRACE_REG_SP |
121 | .It | | 121 | .It |
122 | .Dv PTRACE_REG_INTRV | | 122 | .Dv PTRACE_REG_INTRV |
123 | .It | | 123 | .It |
124 | .Dv PTRACE_BREAKPOINT | | 124 | .Dv PTRACE_BREAKPOINT |
125 | .It | | 125 | .It |
126 | .Dv PTRACE_BREAKPOINT_SIZE | | 126 | .Dv PTRACE_BREAKPOINT_SIZE |
127 | .It | | 127 | .It |
128 | .Dv PTRACE_BREAKPOINT_ADJ | | 128 | .Dv PTRACE_BREAKPOINT_ADJ |
129 | .El | | 129 | .El |
130 | .Pp | | 130 | .Pp |
131 | The | | 131 | The |
132 | .Fa request | | 132 | .Fa request |
133 | argument | | 133 | argument |
134 | of | | 134 | of |
135 | .Nm | | 135 | .Nm |
136 | specifies what operation is being performed; the meaning of | | 136 | specifies what operation is being performed; the meaning of |
137 | the rest of the arguments depends on the operation, but except for one | | 137 | the rest of the arguments depends on the operation, but except for one |
138 | special case noted below, all | | 138 | special case noted below, all |
139 | .Nm | | 139 | .Nm |
140 | calls are made by the tracing process, and the | | 140 | calls are made by the tracing process, and the |
141 | .Fa pid | | 141 | .Fa pid |
142 | argument specifies the process ID of the traced process. | | 142 | argument specifies the process ID of the traced process. |
143 | .Fa request | | 143 | .Fa request |
144 | can be: | | 144 | can be: |
145 | .Bl -tag -width 12n | | 145 | .Bl -tag -width 12n |
146 | .It Dv PT_TRACE_ME | | 146 | .It Dv PT_TRACE_ME |
147 | This request is the only one used by the traced process; it declares | | 147 | This request is the only one used by the traced process; it declares |
148 | that the process expects to be traced by its parent. | | 148 | that the process expects to be traced by its parent. |
149 | All the other arguments are ignored. | | 149 | All the other arguments are ignored. |
150 | If the parent process does not expect to trace | | 150 | If the parent process does not expect to trace |
151 | the child, it will probably be rather confused by the results; once the | | 151 | the child, it will probably be rather confused by the results; once the |
152 | traced process stops, it cannot be made to continue except via | | 152 | traced process stops, it cannot be made to continue except via |
153 | .Fn ptrace . | | 153 | .Fn ptrace . |
154 | .Pp | | 154 | .Pp |
155 | This call does not stop the process neither emit | | 155 | This call does not stop the process neither emit |
156 | .Dv SIGSTOP | | 156 | .Dv SIGSTOP |
157 | to parent. | | 157 | to parent. |
158 | .It Dv PT_READ_I , Dv PT_READ_D | | 158 | .It Dv PT_READ_I , Dv PT_READ_D |
159 | These requests read a single | | 159 | These requests read a single |
160 | .Li int | | 160 | .Li int |
161 | of data from the traced process' address space. | | 161 | of data from the traced process' address space. |
162 | Traditionally, | | 162 | Traditionally, |
163 | .Fn ptrace | | 163 | .Fn ptrace |
164 | has allowed for machines with distinct address spaces for instruction | | 164 | has allowed for machines with distinct address spaces for instruction |
165 | and data, which is why there are two requests: conceptually, | | 165 | and data, which is why there are two requests: conceptually, |
166 | .Dv PT_READ_I | | 166 | .Dv PT_READ_I |
167 | reads from the instruction space and | | 167 | reads from the instruction space and |
168 | .Dv PT_READ_D | | 168 | .Dv PT_READ_D |
169 | reads from the data space. | | 169 | reads from the data space. |
170 | In the current | | 170 | In the current |
171 | .Nx | | 171 | .Nx |
172 | implementation, these | | 172 | implementation, these |
173 | two requests are completely identical. | | 173 | two requests are completely identical. |
174 | The | | 174 | The |
175 | .Fa addr | | 175 | .Fa addr |
176 | argument specifies the address (in the traced process' virtual address | | 176 | argument specifies the address (in the traced process' virtual address |
177 | space) at which the read is to be done. | | 177 | space) at which the read is to be done. |
178 | This address does not have to meet any alignment constraints. | | 178 | This address does not have to meet any alignment constraints. |
179 | The value read is returned as the return value from | | 179 | The value read is returned as the return value from |
180 | .Eo \& | | 180 | .Eo \& |
181 | .Fn ptrace | | 181 | .Fn ptrace |
182 | .Ec . | | 182 | .Ec . |
183 | .It Dv PT_WRITE_I , Dv PT_WRITE_D | | 183 | .It Dv PT_WRITE_I , Dv PT_WRITE_D |
184 | These requests parallel | | 184 | These requests parallel |
185 | .Dv PT_READ_I | | 185 | .Dv PT_READ_I |
186 | and | | 186 | and |
187 | .Dv PT_READ_D , | | 187 | .Dv PT_READ_D , |
188 | except that they write rather than read. | | 188 | except that they write rather than read. |
189 | The | | 189 | The |
190 | .Fa data | | 190 | .Fa data |
191 | argument supplies the value to be written. | | 191 | argument supplies the value to be written. |
192 | .It Dv PT_CONTINUE | | 192 | .It Dv PT_CONTINUE |
193 | The traced process continues execution. | | 193 | The traced process continues execution. |
194 | .Fa addr | | 194 | .Fa addr |
195 | is an address specifying the place where execution is to be resumed (a | | 195 | is an address specifying the place where execution is to be resumed (a |
196 | new value for the program counter), or | | 196 | new value for the program counter), or |
197 | .Li (void *)1 | | 197 | .Li (void *)1 |
198 | to indicate that execution is to pick up where it left off. | | 198 | to indicate that execution is to pick up where it left off. |
199 | .Fa data | | 199 | .Fa data |
200 | provides a signal number to be delivered to the traced process as it | | 200 | provides a signal number to be delivered to the traced process as it |
201 | resumes execution, or 0 if no signal is to be sent. | | 201 | resumes execution, or 0 if no signal is to be sent. |
202 | If a negative value is supplied, that is the negative of the LWP | | 202 | If a negative value is supplied, that is the negative of the LWP |
203 | ID of the thread to be resumed, and only that thread executes. | | 203 | ID of the thread to be resumed, and only that thread executes. |
204 | .It Dv PT_KILL | | 204 | .It Dv PT_KILL |
205 | The traced process terminates, as if | | 205 | The traced process terminates, as if |
206 | .Dv PT_CONTINUE | | 206 | .Dv PT_CONTINUE |
207 | had been used with | | 207 | had been used with |
208 | .Dv SIGKILL | | 208 | .Dv SIGKILL |
209 | given as the signal to be delivered. | | 209 | given as the signal to be delivered. |
210 | .It Dv PT_ATTACH | | 210 | .It Dv PT_ATTACH |
211 | This request allows a process to gain control of an otherwise unrelated | | 211 | This request allows a process to gain control of an otherwise unrelated |
212 | process and begin tracing it. | | 212 | process and begin tracing it. |
213 | It does not need any cooperation from the to-be-traced process. | | 213 | It does not need any cooperation from the to-be-traced process. |
214 | In this case, | | 214 | In this case, |
215 | .Fa pid | | 215 | .Fa pid |
216 | specifies the process ID of the to-be-traced process, and the other two | | 216 | specifies the process ID of the to-be-traced process, and the other two |
217 | arguments are ignored. | | 217 | arguments are ignored. |
218 | This request requires that the target process | | 218 | This request requires that the target process |
219 | must have the same real UID as the tracing process, and that it must | | 219 | must have the same real UID as the tracing process, and that it must |
220 | not be executing a setuid or setgid executable. | | 220 | not be executing a setuid or setgid executable. |
221 | (If the tracing process is running as root, | | 221 | (If the tracing process is running as root, |
222 | these restrictions do not apply.) | | 222 | these restrictions do not apply.) |
223 | .Pp | | 223 | .Pp |
224 | The tracing process will see the newly-traced process stop and may then | | 224 | The tracing process will see the newly-traced process stop and may then |
225 | control it as if it had been traced all along. | | 225 | control it as if it had been traced all along. |
226 | It means that the | | 226 | It means that the |
227 | .Dv SIGSTOP | | 227 | .Dv SIGSTOP |
228 | signal is emitted to tracer. | | 228 | signal is emitted to tracer. |
229 | It is different behavior to the one from | | 229 | It is different behavior to the one from |
230 | .Dv PT_TRACE_ME . | | 230 | .Dv PT_TRACE_ME . |
231 | .Pp | | 231 | .Pp |
232 | Three other restrictions apply to all tracing processes, even those | | 232 | Three other restrictions apply to all tracing processes, even those |
233 | running as root. | | 233 | running as root. |
234 | First, no process may trace a system process. | | 234 | First, no process may trace a system process. |
235 | Second, no process may trace the process running | | 235 | Second, no process may trace the process running |
236 | .Xr init 8 . | | 236 | .Xr init 8 . |
237 | Third, if a process has its root directory set with | | 237 | Third, if a process has its root directory set with |
238 | .Xr chroot 2 , | | 238 | .Xr chroot 2 , |
239 | it may not trace another process unless that process' root directory | | 239 | it may not trace another process unless that process' root directory |
240 | is at or below the tracing process' root. | | 240 | is at or below the tracing process' root. |
241 | .It Dv PT_DETACH | | 241 | .It Dv PT_DETACH |
242 | This request is like PT_CONTINUE, except that after it | | 242 | This request is like PT_CONTINUE, except that after it |
243 | succeeds, the traced process is no longer traced and continues | | 243 | succeeds, the traced process is no longer traced and continues |
244 | execution normally. | | 244 | execution normally. |
245 | .It Dv PT_IO | | 245 | .It Dv PT_IO |
246 | This request is a more general interface that can be used instead of | | 246 | This request is a more general interface that can be used instead of |
247 | .Dv PT_READ_D , | | 247 | .Dv PT_READ_D , |
248 | .Dv PT_WRITE_D , | | 248 | .Dv PT_WRITE_D , |
249 | .Dv PT_READ_I , | | 249 | .Dv PT_READ_I , |
250 | and | | 250 | and |
251 | .Dv PT_WRITE_I . | | 251 | .Dv PT_WRITE_I . |
252 | The I/O request is encoded in a | | 252 | The I/O request is encoded in a |
253 | .Dq Li "struct ptrace_io_desc" | | 253 | .Dq Li "struct ptrace_io_desc" |
254 | defined as: | | 254 | defined as: |
255 | .Bd -literal -offset indent | | 255 | .Bd -literal -offset indent |
256 | struct ptrace_io_desc { | | 256 | struct ptrace_io_desc { |
257 | int piod_op; | | 257 | int piod_op; |
258 | void *piod_offs; | | 258 | void *piod_offs; |
259 | void *piod_addr; | | 259 | void *piod_addr; |
260 | size_t piod_len; | | 260 | size_t piod_len; |
261 | }; | | 261 | }; |
262 | .Ed | | 262 | .Ed |
263 | .Pp | | 263 | .Pp |
264 | where | | 264 | where |
265 | .Fa piod_offs | | 265 | .Fa piod_offs |
266 | is the offset within the traced process where the I/O operation should | | 266 | is the offset within the traced process where the I/O operation should |
267 | take place, | | 267 | take place, |
268 | .Fa piod_addr | | 268 | .Fa piod_addr |
269 | is the buffer in the tracing process, and | | 269 | is the buffer in the tracing process, and |
270 | .Fa piod_len | | 270 | .Fa piod_len |
271 | is the length of the I/O request. | | 271 | is the length of the I/O request. |
272 | The | | 272 | The |
273 | .Fa piod_op | | 273 | .Fa piod_op |
274 | field specifies which type of I/O operation to perform. | | 274 | field specifies which type of I/O operation to perform. |
275 | Possible values are: | | 275 | Possible values are: |
276 | .Pp | | 276 | .Pp |
277 | .Bl -tag -width 18n -offset indent -compact | | 277 | .Bl -tag -width 18n -offset indent -compact |
278 | .It Dv PIOD_READ_D | | 278 | .It Dv PIOD_READ_D |
279 | .It Dv PIOD_WRITE_D | | 279 | .It Dv PIOD_WRITE_D |
280 | .It Dv PIOD_READ_I | | 280 | .It Dv PIOD_READ_I |
281 | .It Dv PIOD_WRITE_I | | 281 | .It Dv PIOD_WRITE_I |
282 | .It Dv PIOD_READ_AUXV | | 282 | .It Dv PIOD_READ_AUXV |
283 | .El | | 283 | .El |
284 | .Pp | | 284 | .Pp |
285 | See the description of | | 285 | See the description of |
286 | .Dv PT_READ_I | | 286 | .Dv PT_READ_I |
287 | for the difference between I and D spaces. | | 287 | for the difference between I and D spaces. |
| | | 288 | .Pp |
288 | The | | 289 | The |
289 | .Dv PIOD_READ_AUXV | | 290 | .Dv PIOD_READ_AUXV |
290 | operation can be used to read from the ELF auxiliary vector. | | 291 | operation can be used to read from the ELF auxiliary vector. |
| | | 292 | The |
| | | 293 | .Fa piod_offs |
| | | 294 | argument sets offset withing the tracee's vector. |
| | | 295 | To read from the beginning of it, this value must be set to 0 and casted to |
| | | 296 | .Dv (void *) . |
| | | 297 | .Pp |
291 | A pointer to the I/O descriptor is passed in the | | 298 | A pointer to the I/O descriptor is passed in the |
292 | .Fa addr | | 299 | .Fa addr |
293 | argument to | | 300 | argument to |
294 | .Fn ptrace . | | 301 | .Fn ptrace . |
295 | On return, the | | 302 | On return, the |
296 | .Fa piod_len | | 303 | .Fa piod_len |
297 | field in the I/O descriptor will be updated with the actual number of | | 304 | field in the I/O descriptor will be updated with the actual number of |
298 | bytes transferred. | | 305 | bytes transferred. |
299 | If the requested I/O could not be successfully performed, | | 306 | If the requested I/O could not be successfully performed, |
300 | .Fn ptrace | | 307 | .Fn ptrace |
301 | will return | | 308 | will return |
302 | .Li \-1 | | 309 | .Li \-1 |
303 | and set | | 310 | and set |
304 | .Va errno . | | 311 | .Va errno . |
305 | .It Dv PT_DUMPCORE | | 312 | .It Dv PT_DUMPCORE |
306 | Makes the process specified in the | | 313 | Makes the process specified in the |
307 | .Fa pid | | 314 | .Fa pid |
308 | pid generate a core dump. | | 315 | pid generate a core dump. |
309 | The | | 316 | The |
310 | .Fa addr | | 317 | .Fa addr |
311 | argument should contain the name of the core file to be generated | | 318 | argument should contain the name of the core file to be generated |
312 | and the | | 319 | and the |
313 | .Fa data | | 320 | .Fa data |
314 | argument should contain the length of the core filename. | | 321 | argument should contain the length of the core filename. |
315 | .It Dv PT_LWPINFO | | 322 | .It Dv PT_LWPINFO |
316 | Returns information about a thread from the list of threads for the | | 323 | Returns information about a thread from the list of threads for the |
317 | process specified in the | | 324 | process specified in the |
318 | .Fa pid | | 325 | .Fa pid |
319 | argument. | | 326 | argument. |
320 | The | | 327 | The |
321 | .Fa addr | | 328 | .Fa addr |
322 | argument should contain a | | 329 | argument should contain a |
323 | .Dq Li "struct ptrace_lwpinfo" | | 330 | .Dq Li "struct ptrace_lwpinfo" |
324 | defined as: | | 331 | defined as: |
325 | .Bd -literal -offset indent | | 332 | .Bd -literal -offset indent |
326 | struct ptrace_lwpinfo { | | 333 | struct ptrace_lwpinfo { |
327 | lwpid_t pl_lwpid; | | 334 | lwpid_t pl_lwpid; |
328 | int pl_event; | | 335 | int pl_event; |
329 | }; | | 336 | }; |
330 | .Ed | | 337 | .Ed |
331 | .Pp | | 338 | .Pp |
332 | where | | 339 | where |
333 | .Fa pl_lwpid | | 340 | .Fa pl_lwpid |
334 | contains a thread LWP ID. | | 341 | contains a thread LWP ID. |
335 | Information is returned for the thread following the one with the | | 342 | Information is returned for the thread following the one with the |
336 | specified ID in the process thread list, or for the first thread | | 343 | specified ID in the process thread list, or for the first thread |
337 | if | | 344 | if |
338 | .Fa pl_lwpid | | 345 | .Fa pl_lwpid |
339 | is 0. | | 346 | is 0. |
340 | Upon return | | 347 | Upon return |
341 | .Fa pl_lwpid | | 348 | .Fa pl_lwpid |
342 | contains the LWP ID of the thread that was found, or 0 if there is | | 349 | contains the LWP ID of the thread that was found, or 0 if there is |
343 | no thread after the one whose LWP ID was supplied in the call. | | 350 | no thread after the one whose LWP ID was supplied in the call. |
344 | .Fa pl_event | | 351 | .Fa pl_event |
345 | contains the event that stopped the thread. | | 352 | contains the event that stopped the thread. |
346 | Possible values are: | | 353 | Possible values are: |
347 | .Pp | | 354 | .Pp |
348 | .Bl -tag -width 30n -offset indent -compact | | 355 | .Bl -tag -width 30n -offset indent -compact |
349 | .It Dv PL_EVENT_NONE | | 356 | .It Dv PL_EVENT_NONE |
350 | .It Dv PL_EVENT_SIGNAL | | 357 | .It Dv PL_EVENT_SIGNAL |
351 | .El | | 358 | .El |
352 | .Pp | | 359 | .Pp |
353 | The | | 360 | The |
354 | .Fa data | | 361 | .Fa data |
355 | argument should contain | | 362 | argument should contain |
356 | .Dq Li "sizeof(struct ptrace_lwpinfo)" . | | 363 | .Dq Li "sizeof(struct ptrace_lwpinfo)" . |
357 | .It Dv PT_SYSCALL | | 364 | .It Dv PT_SYSCALL |
358 | Stops a process before and after executing each system call. | | 365 | Stops a process before and after executing each system call. |
359 | .It Dv PT_SYSCALLEMU | | 366 | .It Dv PT_SYSCALLEMU |
360 | Intercept and ignore a system call before it has been executed, for use with | | 367 | Intercept and ignore a system call before it has been executed, for use with |
361 | .Dv PT_SYSCALL . | | 368 | .Dv PT_SYSCALL . |
362 | .It Dv PT_SET_EVENT_MASK | | 369 | .It Dv PT_SET_EVENT_MASK |
363 | This request can be used to specify which events in the traced process | | 370 | This request can be used to specify which events in the traced process |
364 | should be reported to the tracing process. | | 371 | should be reported to the tracing process. |
365 | These events are specified in a | | 372 | These events are specified in a |
366 | .Dq Li "struct ptrace_event" | | 373 | .Dq Li "struct ptrace_event" |
367 | defined as: | | 374 | defined as: |
368 | .Bd -literal -offset indent | | 375 | .Bd -literal -offset indent |
369 | typedef struct ptrace_event { | | 376 | typedef struct ptrace_event { |
370 | int pe_set_event; | | 377 | int pe_set_event; |
371 | } ptrace_event_t; | | 378 | } ptrace_event_t; |
372 | .Ed | | 379 | .Ed |
373 | .Pp | | 380 | .Pp |
374 | Where | | 381 | Where |
375 | .Fa pe_set_event | | 382 | .Fa pe_set_event |
376 | is the set of events to be reported. | | 383 | is the set of events to be reported. |
377 | This set is formed by OR'ing together the following values: | | 384 | This set is formed by OR'ing together the following values: |
378 | .Bl -tag -width 18n | | 385 | .Bl -tag -width 18n |
379 | .It PTRACE_FORK | | 386 | .It PTRACE_FORK |
380 | Report | | 387 | Report |
381 | .Xr fork 2 . | | 388 | .Xr fork 2 . |
382 | .It PTRACE_VFORK | | 389 | .It PTRACE_VFORK |
383 | Report | | 390 | Report |
384 | .Xr vfork 2 . | | 391 | .Xr vfork 2 . |
385 | .It PTRACE_VFORK_DONE | | 392 | .It PTRACE_VFORK_DONE |
386 | Report parent resumed after | | 393 | Report parent resumed after |
387 | .Xr vfork 2 . | | 394 | .Xr vfork 2 . |
388 | .It PTRACE_LWP_CREATE | | 395 | .It PTRACE_LWP_CREATE |
389 | Report thread birth. | | 396 | Report thread birth. |
390 | .It PTRACE_LWP_EXIT | | 397 | .It PTRACE_LWP_EXIT |
391 | Report thread termination. | | 398 | Report thread termination. |
392 | .El | | 399 | .El |
393 | .Pp | | 400 | .Pp |
394 | The | | 401 | The |
395 | .Xr fork 2 | | 402 | .Xr fork 2 |
396 | and | | 403 | and |
397 | .Xr vfork 2 | | 404 | .Xr vfork 2 |
398 | events can occur with similar operations, | | 405 | events can occur with similar operations, |
399 | like | | 406 | like |
400 | .Xr clone 2 | | 407 | .Xr clone 2 |
401 | or | | 408 | or |
402 | .Xr posix_spawn 3 . | | 409 | .Xr posix_spawn 3 . |
403 | The | | 410 | The |
404 | .Dv PTRACE_FORK | | 411 | .Dv PTRACE_FORK |
405 | value means that process gives birth to its child | | 412 | value means that process gives birth to its child |
406 | without pending on its termination or | | 413 | without pending on its termination or |
407 | .Xr execve 2 | | 414 | .Xr execve 2 |
408 | operation. | | 415 | operation. |
409 | If enabled, | | 416 | If enabled, |
410 | the child is also traced by the debugger and | | 417 | the child is also traced by the debugger and |
411 | .Dv SIGRAP | | 418 | .Dv SIGRAP |
412 | is generated twice, | | 419 | is generated twice, |
413 | first for the parent and second for the child. | | 420 | first for the parent and second for the child. |
414 | The | | 421 | The |
415 | .Dv PTRACE_VFORK | | 422 | .Dv PTRACE_VFORK |
416 | event is the same as | | 423 | event is the same as |
417 | .Dv PTRACE_FORK , | | 424 | .Dv PTRACE_FORK , |
418 | but the parent blocks after giving birth to the child. | | 425 | but the parent blocks after giving birth to the child. |
419 | The | | 426 | The |
420 | .Dv PTRACE_VFORK_DONE | | 427 | .Dv PTRACE_VFORK_DONE |
421 | event can be used to report unblocking of the parent. | | 428 | event can be used to report unblocking of the parent. |
422 | .Pp | | 429 | .Pp |
423 | A pointer to this structure is passed in | | 430 | A pointer to this structure is passed in |
424 | .Fa addr . | | 431 | .Fa addr . |
425 | The | | 432 | The |
426 | .Fa data | | 433 | .Fa data |
427 | argument should be set to | | 434 | argument should be set to |
428 | .Li sizeof(struct ptrace_event) . | | 435 | .Li sizeof(struct ptrace_event) . |
429 | .It Dv PT_GET_EVENT_MASK | | 436 | .It Dv PT_GET_EVENT_MASK |
430 | This request can be used to determine which events in the traced | | 437 | This request can be used to determine which events in the traced |
431 | process will be reported. | | 438 | process will be reported. |
432 | The information is read into the | | 439 | The information is read into the |
433 | .Dq Li struct ptrace_event | | 440 | .Dq Li struct ptrace_event |
434 | pointed to by | | 441 | pointed to by |
435 | .Fa addr . | | 442 | .Fa addr . |
436 | The | | 443 | The |
437 | .Fa data | | 444 | .Fa data |
438 | argument should be set to | | 445 | argument should be set to |
439 | .Li sizeof(struct ptrace_event) . | | 446 | .Li sizeof(struct ptrace_event) . |
440 | .It Dv PT_GET_PROCESS_STATE | | 447 | .It Dv PT_GET_PROCESS_STATE |
441 | This request reads the state information associated with the event | | 448 | This request reads the state information associated with the event |
442 | that stopped the traced process. | | 449 | that stopped the traced process. |
443 | The information is reported in a | | 450 | The information is reported in a |
444 | .Dq Li "struct ptrace_state" | | 451 | .Dq Li "struct ptrace_state" |
445 | defined as: | | 452 | defined as: |
446 | .Bd -literal -offset indent | | 453 | .Bd -literal -offset indent |
447 | typedef struct ptrace_state { | | 454 | typedef struct ptrace_state { |
448 | int pe_report_event; | | 455 | int pe_report_event; |
449 | pid_t pe_other_pid; | | 456 | pid_t pe_other_pid; |
450 | } ptrace_state_t; | | 457 | } ptrace_state_t; |
451 | .Ed | | 458 | .Ed |
452 | .Pp | | 459 | .Pp |
453 | A pointer to this structure is passed in | | 460 | A pointer to this structure is passed in |
454 | .Fa addr . | | 461 | .Fa addr . |
455 | The | | 462 | The |
456 | .Fa data | | 463 | .Fa data |
457 | argument should be set to | | 464 | argument should be set to |
458 | .Li sizeof(struct ptrace_state) . | | 465 | .Li sizeof(struct ptrace_state) . |
459 | .It Dv PT_SET_SIGINFO | | 466 | .It Dv PT_SET_SIGINFO |
460 | This request can be used to specify signal information emitted to tracee. | | 467 | This request can be used to specify signal information emitted to tracee. |
461 | This signal information is specified in | | 468 | This signal information is specified in |
462 | .Dq Li "struct ptrace_siginfo" | | 469 | .Dq Li "struct ptrace_siginfo" |
463 | defined as: | | 470 | defined as: |
464 | .Bd -literal -offset indentq | | 471 | .Bd -literal -offset indentq |
465 | typedef struct ptrace_siginfo { | | 472 | typedef struct ptrace_siginfo { |
466 | siginfo_t psi_siginfo; | | 473 | siginfo_t psi_siginfo; |
467 | lwpid_t psi_lwpid; | | 474 | lwpid_t psi_lwpid; |
468 | } ptrace_siginfo_t; | | 475 | } ptrace_siginfo_t; |
469 | .Ed | | 476 | .Ed |
470 | .Pp | | 477 | .Pp |
471 | Where | | 478 | Where |
472 | .Fa psi_siginfo | | 479 | .Fa psi_siginfo |
473 | is the set to signal information structure. | | 480 | is the set to signal information structure. |
474 | The | | 481 | The |
475 | .Fa psi_lwpid | | 482 | .Fa psi_lwpid |
476 | field describes LWP address of the signal. | | 483 | field describes LWP address of the signal. |
477 | Value | | 484 | Value |
478 | .Dv 0 | | 485 | .Dv 0 |
479 | means the whole process | | 486 | means the whole process |
480 | (route signal to all LWPs). | | 487 | (route signal to all LWPs). |
481 | .Pp | | 488 | .Pp |
482 | A pointer to this structure is passed in | | 489 | A pointer to this structure is passed in |
483 | .Fa addr . | | 490 | .Fa addr . |
484 | The | | 491 | The |
485 | .Fa data | | 492 | .Fa data |
486 | argument should be set to | | 493 | argument should be set to |
487 | .Li sizeof(struct ptrace_siginfo) . | | 494 | .Li sizeof(struct ptrace_siginfo) . |
488 | .Pp | | 495 | .Pp |
489 | In order to pass faked signal to the tracee, | | 496 | In order to pass faked signal to the tracee, |
490 | the signal type must match the signal passed to process with | | 497 | the signal type must match the signal passed to process with |
491 | .Dv PT_CONTINUE , | | 498 | .Dv PT_CONTINUE , |
492 | .Dv PT_DETACH | | 499 | .Dv PT_DETACH |
493 | or | | 500 | or |
494 | .Dv PT_STEP . | | 501 | .Dv PT_STEP . |
495 | .It Dv PT_GET_SIGINFO | | 502 | .It Dv PT_GET_SIGINFO |
496 | This request can be used to determine signal information that was received by | | 503 | This request can be used to determine signal information that was received by |
497 | a debugger | | 504 | a debugger |
498 | .Po | | 505 | .Po |
499 | see | | 506 | see |
500 | .Xr siginfo 2 | | 507 | .Xr siginfo 2 |
501 | .Pc . | | 508 | .Pc . |
502 | The information is read into the | | 509 | The information is read into the |
503 | .Dq Li struct ptrace_siginfo | | 510 | .Dq Li struct ptrace_siginfo |
504 | pointed to by | | 511 | pointed to by |
505 | .Fa addr . | | 512 | .Fa addr . |
506 | The | | 513 | The |
507 | .Fa data | | 514 | .Fa data |
508 | argument should be set to | | 515 | argument should be set to |
509 | .Li sizeof(struct ptrace_siginfo) . | | 516 | .Li sizeof(struct ptrace_siginfo) . |
510 | .El | | 517 | .El |
511 | .Pp | | 518 | .Pp |
512 | Additionally, the following requests exist but are | | 519 | Additionally, the following requests exist but are |
513 | not available on all machine architectures. | | 520 | not available on all machine architectures. |
514 | The file | | 521 | The file |
515 | .In machine/ptrace.h | | 522 | .In machine/ptrace.h |
516 | lists which requests exist on a given machine. | | 523 | lists which requests exist on a given machine. |
517 | .Bl -tag -width 12n | | 524 | .Bl -tag -width 12n |
518 | .It Dv PT_STEP | | 525 | .It Dv PT_STEP |
519 | Execution continues as in request PT_CONTINUE; however | | 526 | Execution continues as in request PT_CONTINUE; however |
520 | as soon as possible after execution of at least one | | 527 | as soon as possible after execution of at least one |
521 | instruction, execution stops again. | | 528 | instruction, execution stops again. |
522 | If the | | 529 | If the |
523 | .Fa data | | 530 | .Fa data |
524 | argument is greater than 0, it contains the LWP ID of the thread to be | | 531 | argument is greater than 0, it contains the LWP ID of the thread to be |
525 | stepped, and any other threads are continued. | | 532 | stepped, and any other threads are continued. |
526 | If the | | 533 | If the |
527 | .Fa data | | 534 | .Fa data |
528 | argument is less than zero, it contains the negative of the LWP ID of | | 535 | argument is less than zero, it contains the negative of the LWP ID of |
529 | the thread to be stepped, and only that thread executes. | | 536 | the thread to be stepped, and only that thread executes. |
530 | .It Dv PT_GETREGS | | 537 | .It Dv PT_GETREGS |
531 | This request reads the traced process' machine registers into the | | 538 | This request reads the traced process' machine registers into the |
532 | .Dq Li "struct reg" | | 539 | .Dq Li "struct reg" |
533 | (defined in | | 540 | (defined in |
534 | .In machine/reg.h ) | | 541 | .In machine/reg.h ) |
535 | pointed to by | | 542 | pointed to by |
536 | .Fa addr . | | 543 | .Fa addr . |
537 | The | | 544 | The |
538 | .Fa data | | 545 | .Fa data |
539 | argument contains the LWP ID of the thread whose registers are to | | 546 | argument contains the LWP ID of the thread whose registers are to |
540 | be read. | | 547 | be read. |
541 | If zero is supplied, the first thread of the process is read. | | 548 | If zero is supplied, the first thread of the process is read. |
542 | .It Dv PT_SETREGS | | 549 | .It Dv PT_SETREGS |
543 | This request is the converse of | | 550 | This request is the converse of |
544 | .Dv PT_GETREGS ; | | 551 | .Dv PT_GETREGS ; |
545 | it loads the traced process' machine registers from the | | 552 | it loads the traced process' machine registers from the |
546 | .Dq Li "struct reg" | | 553 | .Dq Li "struct reg" |
547 | (defined in | | 554 | (defined in |
548 | .In machine/reg.h ) | | 555 | .In machine/reg.h ) |
549 | pointed to by | | 556 | pointed to by |
550 | .Fa addr . | | 557 | .Fa addr . |
551 | The | | 558 | The |
552 | .Fa data | | 559 | .Fa data |
553 | argument contains the LWP ID of the thread whose registers are to | | 560 | argument contains the LWP ID of the thread whose registers are to |
554 | be written. | | 561 | be written. |
555 | If zero is supplied, the first thread of the process is written. | | 562 | If zero is supplied, the first thread of the process is written. |
556 | .It Dv PT_GETFPREGS | | 563 | .It Dv PT_GETFPREGS |
557 | This request reads the traced process' floating-point registers into | | 564 | This request reads the traced process' floating-point registers into |
558 | the | | 565 | the |
559 | .Dq Li "struct fpreg" | | 566 | .Dq Li "struct fpreg" |
560 | (defined in | | 567 | (defined in |
561 | .In machine/reg.h ) | | 568 | .In machine/reg.h ) |
562 | pointed to by | | 569 | pointed to by |
563 | .Fa addr . | | 570 | .Fa addr . |
564 | The | | 571 | The |
565 | .Fa data | | 572 | .Fa data |
566 | argument contains the LWP ID of the thread whose registers are to | | 573 | argument contains the LWP ID of the thread whose registers are to |
567 | be read. | | 574 | be read. |
568 | If zero is supplied, the first thread of the process is read. | | 575 | If zero is supplied, the first thread of the process is read. |
569 | .It Dv PT_SETFPREGS | | 576 | .It Dv PT_SETFPREGS |
570 | This request is the converse of | | 577 | This request is the converse of |
571 | .Dv PT_GETFPREGS ; | | 578 | .Dv PT_GETFPREGS ; |
572 | it loads the traced process' floating-point registers from the | | 579 | it loads the traced process' floating-point registers from the |
573 | .Dq Li "struct fpreg" | | 580 | .Dq Li "struct fpreg" |
574 | (defined in | | 581 | (defined in |
575 | .In machine/reg.h ) | | 582 | .In machine/reg.h ) |
576 | pointed to by | | 583 | pointed to by |
577 | .Fa addr . | | 584 | .Fa addr . |
578 | The | | 585 | The |
579 | .Fa data | | 586 | .Fa data |
580 | argument contains the LWP ID of the thread whose registers are to | | 587 | argument contains the LWP ID of the thread whose registers are to |
581 | be written. | | 588 | be written. |
582 | If zero is supplied, the first thread of the process is written. | | 589 | If zero is supplied, the first thread of the process is written. |
583 | .It Dv PT_GETXMMREGS | | 590 | .It Dv PT_GETXMMREGS |
584 | This request reads the traced process' XMM registers into | | 591 | This request reads the traced process' XMM registers into |
585 | the | | 592 | the |
586 | .Dq Li "struct xmmregs" | | 593 | .Dq Li "struct xmmregs" |
587 | (defined in | | 594 | (defined in |
588 | .In machine/reg.h ) | | 595 | .In machine/reg.h ) |
589 | pointed to by | | 596 | pointed to by |
590 | .Fa addr . | | 597 | .Fa addr . |
591 | The | | 598 | The |
592 | .Fa data | | 599 | .Fa data |
593 | argument contains the LWP ID of the thread whose registers are to | | 600 | argument contains the LWP ID of the thread whose registers are to |
594 | be read. | | 601 | be read. |
595 | If zero is supplied, the first thread of the process is read. | | 602 | If zero is supplied, the first thread of the process is read. |
596 | .It Dv PT_SETXMMREGS | | 603 | .It Dv PT_SETXMMREGS |
597 | This request is the converse of | | 604 | This request is the converse of |
598 | .Dv PT_GETXMMREGS ; | | 605 | .Dv PT_GETXMMREGS ; |
599 | it loads the traced process' XMM registers from the | | 606 | it loads the traced process' XMM registers from the |
600 | .Dq Li "struct xmmregs" | | 607 | .Dq Li "struct xmmregs" |
601 | (defined in | | 608 | (defined in |
602 | .In machine/reg.h ) | | 609 | .In machine/reg.h ) |
603 | pointed to by | | 610 | pointed to by |
604 | .Fa addr . | | 611 | .Fa addr . |
605 | The | | 612 | The |
606 | .Fa data | | 613 | .Fa data |
607 | argument contains the LWP ID of the thread whose registers are to | | 614 | argument contains the LWP ID of the thread whose registers are to |
608 | be written. | | 615 | be written. |
609 | If zero is supplied, the first thread of the process is written. | | 616 | If zero is supplied, the first thread of the process is written. |
610 | .It Dv PT_GETVECREGS | | 617 | .It Dv PT_GETVECREGS |
611 | This request reads the traced process' vector registers into | | 618 | This request reads the traced process' vector registers into |
612 | the | | 619 | the |
613 | .Dq Li "struct vreg" | | 620 | .Dq Li "struct vreg" |
614 | (defined in | | 621 | (defined in |
615 | .In machine/reg.h ) | | 622 | .In machine/reg.h ) |
616 | pointed to by | | 623 | pointed to by |
617 | .Fa addr . | | 624 | .Fa addr . |
618 | The | | 625 | The |
619 | .Fa data | | 626 | .Fa data |
620 | argument contains the LWP ID of the thread whose registers are to | | 627 | argument contains the LWP ID of the thread whose registers are to |
621 | be read. | | 628 | be read. |
622 | If zero is supplied, the first thread of the process is read. | | 629 | If zero is supplied, the first thread of the process is read. |
623 | .It Dv PT_SETVECREGS | | 630 | .It Dv PT_SETVECREGS |
624 | This request is the converse of | | 631 | This request is the converse of |
625 | .Dv PT_GETVECREGS ; | | 632 | .Dv PT_GETVECREGS ; |
626 | it loads the traced process' vector registers from the | | 633 | it loads the traced process' vector registers from the |
627 | .Dq Li "struct vreg" | | 634 | .Dq Li "struct vreg" |
628 | (defined in | | 635 | (defined in |
629 | .In machine/reg.h ) | | 636 | .In machine/reg.h ) |
630 | pointed to by | | 637 | pointed to by |
631 | .Fa addr . | | 638 | .Fa addr . |
632 | The | | 639 | The |
633 | .Fa data | | 640 | .Fa data |
634 | argument contains the LWP ID of the thread whose registers are to | | 641 | argument contains the LWP ID of the thread whose registers are to |
635 | be written. | | 642 | be written. |
636 | If zero is supplied, the first thread of the process is written. | | 643 | If zero is supplied, the first thread of the process is written. |
637 | .El | | 644 | .El |
638 | .Sh ERRORS | | 645 | .Sh ERRORS |
639 | Some requests can cause | | 646 | Some requests can cause |
640 | .Fn ptrace | | 647 | .Fn ptrace |
641 | to return | | 648 | to return |
642 | .Li \-1 | | 649 | .Li \-1 |
643 | as a non-error value; to disambiguate, | | 650 | as a non-error value; to disambiguate, |
644 | .Va errno | | 651 | .Va errno |
645 | can be set to 0 before the call and checked afterwards. | | 652 | can be set to 0 before the call and checked afterwards. |
646 | The possible errors are: | | 653 | The possible errors are: |
647 | .Bl -tag -width "[EINVAL]" | | 654 | .Bl -tag -width "[EINVAL]" |
648 | .It Bq Er EAGAIN | | 655 | .It Bq Er EAGAIN |
649 | Process is currently exec'ing and cannot be traced. | | 656 | Process is currently exec'ing and cannot be traced. |
650 | .It Bq Er EBUSY | | 657 | .It Bq Er EBUSY |
651 | .Bl -bullet -compact | | 658 | .Bl -bullet -compact |
652 | .It | | 659 | .It |
653 | .Dv PT_ATTACH | | 660 | .Dv PT_ATTACH |
654 | was attempted on a process that was already being traced. | | 661 | was attempted on a process that was already being traced. |
655 | .It | | 662 | .It |
656 | A request attempted to manipulate a process that was being traced by | | 663 | A request attempted to manipulate a process that was being traced by |
657 | some process other than the one making the request. | | 664 | some process other than the one making the request. |
658 | .It | | 665 | .It |
659 | A request (other than | | 666 | A request (other than |
660 | .Dv PT_ATTACH ) | | 667 | .Dv PT_ATTACH ) |
661 | specified a process that wasn't stopped. | | 668 | specified a process that wasn't stopped. |
662 | .El | | 669 | .El |
663 | .It Bq Er EINVAL | | 670 | .It Bq Er EINVAL |
664 | .Bl -bullet -compact | | 671 | .Bl -bullet -compact |
665 | .It | | 672 | .It |
666 | A process attempted to use | | 673 | A process attempted to use |
667 | .Dv PT_ATTACH | | 674 | .Dv PT_ATTACH |
668 | on itself. | | 675 | on itself. |
669 | .It | | 676 | .It |
670 | The | | 677 | The |
671 | .Fa request | | 678 | .Fa request |
672 | was not a legal request on this machine architecture. | | 679 | was not a legal request on this machine architecture. |
673 | .It | | 680 | .It |
674 | The signal number (in | | 681 | The signal number (in |
675 | .Fa data ) | | 682 | .Fa data ) |
676 | to | | 683 | to |
677 | .Dv PT_CONTINUE | | 684 | .Dv PT_CONTINUE |
678 | was neither 0 nor a legal signal number. | | 685 | was neither 0 nor a legal signal number. |
679 | .It | | 686 | .It |
680 | .Dv PT_GETREGS , | | 687 | .Dv PT_GETREGS , |
681 | .Dv PT_SETREGS , | | 688 | .Dv PT_SETREGS , |
682 | .Dv PT_GETFPREGS , | | 689 | .Dv PT_GETFPREGS , |
683 | or | | 690 | or |
684 | .Dv PT_SETFPREGS | | 691 | .Dv PT_SETFPREGS |
685 | was attempted on a process with no valid register set. | | 692 | was attempted on a process with no valid register set. |
686 | (This is normally true only of system processes.) | | 693 | (This is normally true only of system processes.) |
687 | .El | | 694 | .El |
688 | .It Bq Er EPERM | | 695 | .It Bq Er EPERM |
689 | .Bl -bullet -compact | | 696 | .Bl -bullet -compact |
690 | .It | | 697 | .It |
691 | A request (other than | | 698 | A request (other than |
692 | .Dv PT_ATTACH ) | | 699 | .Dv PT_ATTACH ) |
693 | attempted to manipulate a process that wasn't being traced at all. | | 700 | attempted to manipulate a process that wasn't being traced at all. |
694 | .It | | 701 | .It |
695 | An attempt was made to use | | 702 | An attempt was made to use |
696 | .Dv PT_ATTACH | | 703 | .Dv PT_ATTACH |
697 | on a process in violation of the requirements listed under | | 704 | on a process in violation of the requirements listed under |
698 | .Dv PT_ATTACH | | 705 | .Dv PT_ATTACH |
699 | above. | | 706 | above. |
700 | .El | | 707 | .El |
701 | .It Bq Er ESRCH | | 708 | .It Bq Er ESRCH |
702 | No process having the specified process ID exists. | | 709 | No process having the specified process ID exists. |
703 | .El | | 710 | .El |
704 | .Sh SEE ALSO | | 711 | .Sh SEE ALSO |
705 | .Xr sigaction 2 , | | 712 | .Xr sigaction 2 , |
706 | .Xr signal 7 | | 713 | .Xr signal 7 |
707 | .Sh HISTORY | | 714 | .Sh HISTORY |
708 | The | | 715 | The |
709 | .Fn ptrace | | 716 | .Fn ptrace |
710 | function appeared in | | 717 | function appeared in |
711 | .At v7 . | | 718 | .At v7 . |
712 | .Sh BUGS | | 719 | .Sh BUGS |
713 | On the SPARC, the PC is set to the provided PC value for | | 720 | On the SPARC, the PC is set to the provided PC value for |
714 | .Dv PT_CONTINUE | | 721 | .Dv PT_CONTINUE |
715 | and similar calls, | | 722 | and similar calls, |
716 | but the NPC is set willy-nilly to 4 greater than the PC value. | | 723 | but the NPC is set willy-nilly to 4 greater than the PC value. |
717 | Using | | 724 | Using |
718 | .Dv PT_GETREGS | | 725 | .Dv PT_GETREGS |
719 | and | | 726 | and |
720 | .Dv PT_SETREGS | | 727 | .Dv PT_SETREGS |
721 | to modify the PC, passing | | 728 | to modify the PC, passing |
722 | .Li (void *)1 | | 729 | .Li (void *)1 |
723 | to | | 730 | to |
724 | .Eo \& | | 731 | .Eo \& |
725 | .Fn ptrace | | 732 | .Fn ptrace |
726 | .Ec , | | 733 | .Ec , |
727 | should be able to sidestep this. | | 734 | should be able to sidestep this. |
728 | .Pp | | 735 | .Pp |
729 | .Dv PTRACE_VFORK | | 736 | .Dv PTRACE_VFORK |
730 | is currently unimplemented and it will return | | 737 | is currently unimplemented and it will return |
731 | .Er ENOTSUP . | | 738 | .Er ENOTSUP . |