| blob | 44fc1eafe13eee4a36a1c658c8466c94b8b24c4e |
1 .\" $FreeBSD$
2 .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
3 .\"
4 .\" This file is in the public domain.
5 .Dd April 9, 2007
6 .Dt PTRACE 2
7 .Os
8 .Sh NAME
9 .Nm ptrace
10 .Nd process tracing and debugging
11 .Sh LIBRARY
12 .Lb libc
13 .Sh SYNOPSIS
14 .In sys/types.h
15 .In sys/ptrace.h
16 .Ft int
17 .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data"
18 .Sh DESCRIPTION
19 The
20 .Fn ptrace
21 system call
22 provides tracing and debugging facilities.
23 It allows one process
24 (the
25 .Em tracing
26 process)
27 to control another
28 (the
29 .Em traced
30 process).
31 The tracing process must first attach to the traced process, and then
32 issue a series of
33 .Fn ptrace
34 system calls to control the execution of the process, as well as access
35 process memory and register state.
36 For the duration of the tracing session, the traced process will be
37 .Dq re-parented ,
38 with its parent process ID (and resulting behavior)
39 changed to the tracing process.
40 It is permissible for a tracing process to attach to more than one
41 other process at a time.
42 When the tracing process has completed its work, it must detach the
43 traced process; if a tracing process exits without first detaching all
44 processes it has attached, those processes will be killed.
45 .Pp
46 Most of the time, the traced process runs normally, but when it
47 receives a signal
48 (see
49 .Xr sigaction 2 ) ,
50 it stops.
51 The tracing process is expected to notice this via
52 .Xr wait 2
53 or the delivery of a
54 .Dv SIGCHLD
55 signal, examine the state of the stopped process, and cause it to
56 terminate or continue as appropriate.
57 The signal may be a normal process signal, generated as a result of
58 traced process behavior, or use of the
59 .Xr kill 2
60 system call; alternatively, it may be generated by the tracing facility
61 as a result of attaching, system calls, or stepping by the tracing
62 process.
63 The tracing process may choose to intercept the signal, using it to
64 observe process behavior (such as
65 .Dv SIGTRAP ) ,
66 or forward the signal to the process if appropriate.
67 The
68 .Fn ptrace
69 system call
70 is the mechanism by which all this happens.
71 .Pp
72 The
73 .Fa request
74 argument specifies what operation is being performed; the meaning of
75 the rest of the arguments depends on the operation, but except for one
76 special case noted below, all
77 .Fn ptrace
78 calls are made by the tracing process, and the
79 .Fa pid
80 argument specifies the process ID of the traced process.
81 The
82 .Fa request
83 argument
84 can be:
85 .Bl -tag -width 12n
86 .It Dv PT_TRACE_ME
87 This request is the only one used by the traced process; it declares
88 that the process expects to be traced by its parent.
89 All the other arguments are ignored.
90 (If the parent process does not expect to trace the child, it will
91 probably be rather confused by the results; once the traced process
92 stops, it cannot be made to continue except via
93 .Fn ptrace . )
94 When a process has used this request and calls
95 .Xr execve 2
96 or any of the routines built on it
97 (such as
98 .Xr execv 3 ) ,
99 it will stop before executing the first instruction of the new image.
100 Also, any setuid or setgid bits on the executable being executed will
101 be ignored.
102 .It Dv PT_READ_I , Dv PT_READ_D
103 These requests read a single
104 .Vt int
105 of data from the traced process's address space.
106 Traditionally,
107 .Fn ptrace
108 has allowed for machines with distinct address spaces for instruction
109 and data, which is why there are two requests: conceptually,
110 .Dv PT_READ_I
111 reads from the instruction space and
112 .Dv PT_READ_D
113 reads from the data space.
114 In the current
115 .Fx
116 implementation, these two requests are completely identical.
117 The
118 .Fa addr
119 argument specifies the address
120 (in the traced process's virtual address space)
121 at which the read is to be done.
122 This address does not have to meet any alignment constraints.
123 The value read is returned as the return value from
124 .Fn ptrace .
125 .It Dv PT_WRITE_I , Dv PT_WRITE_D
126 These requests parallel
127 .Dv PT_READ_I
128 and
129 .Dv PT_READ_D ,
130 except that they write rather than read.
131 The
132 .Fa data
133 argument supplies the value to be written.
134 .It Dv PT_IO
135 This request allows reading and writing arbitrary amounts of data in
136 the traced process's address space.
137 The
138 .Fa addr
139 argument specifies a pointer to a
140 .Vt "struct ptrace_io_desc" ,
141 which is defined as follows:
142 .Bd -literal
143 struct ptrace_io_desc {
144 int piod_op; /* I/O operation */
145 void *piod_offs; /* child offset */
146 void *piod_addr; /* parent offset */
147 size_t piod_len; /* request length */
148 };
150 /*
151 * Operations in piod_op.
152 */
153 #define PIOD_READ_D 1 /* Read from D space */
154 #define PIOD_WRITE_D 2 /* Write to D space */
155 #define PIOD_READ_I 3 /* Read from I space */
156 #define PIOD_WRITE_I 4 /* Write to I space */
157 .Ed
158 .Pp
159 The
160 .Fa data
161 argument is ignored.
162 The actual number of bytes read or written is stored in
163 .Va piod_len
164 upon return.
165 .It Dv PT_CONTINUE
166 The traced process continues execution.
167 The
168 .Fa addr
169 argument
170 is an address specifying the place where execution is to be resumed
171 (a new value for the program counter),
172 or
173 .Po Vt caddr_t Pc Ns 1
174 to indicate that execution is to pick up where it left off.
175 The
176 .Fa data
177 argument
178 provides a signal number to be delivered to the traced process as it
179 resumes execution, or 0 if no signal is to be sent.
180 .It Dv PT_STEP
181 The traced process is single stepped one instruction.
182 The
183 .Fa addr
184 argument
185 should be passed
186 .Po Vt caddr_t Pc Ns 1 .
187 The
188 .Fa data
189 argument
190 provides a signal number to be delivered to the traced process as it
191 resumes execution, or 0 if no signal is to be sent.
192 .It Dv PT_KILL
193 The traced process terminates, as if
194 .Dv PT_CONTINUE
195 had been used with
196 .Dv SIGKILL
197 given as the signal to be delivered.
198 .It Dv PT_ATTACH
199 This request allows a process to gain control of an otherwise
200 unrelated process and begin tracing it.
201 It does not need any cooperation from the to-be-traced process.
202 In
203 this case,
204 .Fa pid
205 specifies the process ID of the to-be-traced process, and the other
206 two arguments are ignored.
207 This request requires that the target process must have the same real
208 UID as the tracing process, and that it must not be executing a setuid
209 or setgid executable.
210 (If the tracing process is running as root, these restrictions do not
211 apply.)
212 The tracing process will see the newly-traced process stop and may
213 then control it as if it had been traced all along.
214 .It Dv PT_DETACH
215 This request is like PT_CONTINUE, except that it does not allow
216 specifying an alternate place to continue execution, and after it
217 succeeds, the traced process is no longer traced and continues
218 execution normally.
219 .It Dv PT_GETREGS
220 This request reads the traced process's machine registers into the
221 .Do
222 .Vt "struct reg"
223 .Dc
224 (defined in
225 .In machine/reg.h )
226 pointed to by
227 .Fa addr .
228 .It Dv PT_SETREGS
229 This request is the converse of
230 .Dv PT_GETREGS ;
231 it loads the traced process's machine registers from the
232 .Do
233 .Vt "struct reg"
234 .Dc
235 (defined in
236 .In machine/reg.h )
237 pointed to by
238 .Fa addr .
239 .It Dv PT_GETFPREGS
240 This request reads the traced process's floating-point registers into
241 the
242 .Do
243 .Vt "struct fpreg"
244 .Dc
245 (defined in
246 .In machine/reg.h )
247 pointed to by
248 .Fa addr .
249 .It Dv PT_SETFPREGS
250 This request is the converse of
251 .Dv PT_GETFPREGS ;
252 it loads the traced process's floating-point registers from the
253 .Do
254 .Vt "struct fpreg"
255 .Dc
256 (defined in
257 .In machine/reg.h )
258 pointed to by
259 .Fa addr .
260 .It Dv PT_GETDBREGS
261 This request reads the traced process's debug registers into
262 the
263 .Do
264 .Vt "struct dbreg"
265 .Dc
266 (defined in
267 .In machine/reg.h )
268 pointed to by
269 .Fa addr .
270 .It Dv PT_SETDBREGS
271 This request is the converse of
272 .Dv PT_GETDBREGS ;
273 it loads the traced process's debug registers from the
274 .Do
275 .Vt "struct dbreg"
276 .Dc
277 (defined in
278 .In machine/reg.h )
279 pointed to by
280 .Fa addr .
281 .It Dv PT_LWPINFO
282 This request can be used to obtain information about the kernel thread,
283 also known as light-weight process, that caused the traced process to stop.
284 The
285 .Fa addr
286 argument specifies a pointer to a
287 .Vt "struct ptrace_lwpinfo" ,
288 which is defined as follows:
289 .Bd -literal
290 struct ptrace_lwpinfo {
291 lwpid_t pl_lwpid; /* LWP described. */
292 int pl_event; /* Event received. */
293 };
294 .Ed
295 .Pp
296 The
297 .Fa data
298 argument is to be set to the size of the structure known to the caller.
299 This allows the structure to grow without affecting older programs.
300 .It PT_GETNUMLWPS
301 This request returns the number of kernel threads associated with the
302 traced process.
303 .It PT_GETLWPLIST
304 This request can be used to get the current thread list.
305 A pointer to an array of type
306 .Vt lwpid_t
307 should be passed in
308 .Fa addr ,
309 with the array size specified by
310 .Fa data .
311 The return value from
312 .Fn ptrace
313 is the count of array entries filled in.
314 .El
315 .Pp
316 Additionally, machine-specific requests can exist.
317 .Sh RETURN VALUES
318 Some requests can cause
319 .Fn ptrace
320 to return
321 \-1
322 as a non-error value; to disambiguate,
323 .Va errno
324 can be set to 0 before the call and checked afterwards.
325 .Sh ERRORS
326 The
327 .Fn ptrace
328 system call may fail if:
329 .Bl -tag -width Er
330 .It Bq Er ESRCH
331 .Bl -bullet -compact
332 .It
333 No process having the specified process ID exists.
334 .El
335 .It Bq Er EINVAL
336 .Bl -bullet -compact
337 .It
338 A process attempted to use
339 .Dv PT_ATTACH
340 on itself.
341 .It
342 The
343 .Fa request
344 argument
345 was not one of the legal requests.
346 .It
347 The signal number
348 (in
349 .Fa data )
350 to
351 .Dv PT_CONTINUE
352 was neither 0 nor a legal signal number.
353 .It
354 .Dv PT_GETREGS ,
355 .Dv PT_SETREGS ,
356 .Dv PT_GETFPREGS ,
357 .Dv PT_SETFPREGS ,
358 .Dv PT_GETDBREGS ,
359 or
360 .Dv PT_SETDBREGS
361 was attempted on a process with no valid register set.
362 (This is normally true only of system processes.)
363 .El
364 .It Bq Er EBUSY
365 .Bl -bullet -compact
366 .It
367 .Dv PT_ATTACH
368 was attempted on a process that was already being traced.
369 .It
370 A request attempted to manipulate a process that was being traced by
371 some process other than the one making the request.
372 .It
373 A request
374 (other than
375 .Dv PT_ATTACH )
376 specified a process that was not stopped.
377 .El
378 .It Bq Er EPERM
379 .Bl -bullet -compact
380 .It
381 A request
382 (other than
383 .Dv PT_ATTACH )
384 attempted to manipulate a process that was not being traced at all.
385 .It
386 An attempt was made to use
387 .Dv PT_ATTACH
388 on a process in violation of the requirements listed under
389 .Dv PT_ATTACH
390 above.
391 .El
392 .El
393 .Sh SEE ALSO
394 .Xr execve 2 ,
395 .Xr sigaction 2 ,
396 .Xr wait 2 ,
397 .Xr execv 3 ,
398 .Xr i386_clr_watch 3 ,
399 .Xr i386_set_watch 3
400 .Sh HISTORY
401 The
402 .Fn ptrace
403 function appeared in
404 .At v7 .