| blob | cea611264cb77fd4e0963b77a1e64bf905a03921 |
1 .\" $NetBSD: ptrace.2,v 1.29 2007/03/06 16:07:22 drochner Exp $
2 .\"
3 .\" This file is in the public domain.
4 .Dd March 12, 2007
5 .Dt PTRACE 2
6 .Os
7 .Sh NAME
8 .Nm ptrace
9 .Nd process tracing and debugging
10 .Sh LIBRARY
11 .Lb libc
12 .Sh SYNOPSIS
13 .In sys/types.h
14 .In sys/ptrace.h
15 .Ft int
16 .Fn ptrace "int request" "pid_t pid" "void *addr" "int data"
17 .Sh DESCRIPTION
18 .Fn ptrace
19 provides tracing and debugging facilities.
20 It allows one process (the
21 .Em tracing
22 process) to control another (the
23 .Em traced
24 process).
25 Most of the time, the traced process runs normally, but when
26 it receives a signal
27 .Po
28 see
29 .Xr sigaction 2
30 .Pc ,
31 it stops.
32 The tracing process is expected to notice this via
33 .Xr wait 2
34 or the delivery of a
35 .Dv SIGCHLD
36 signal, examine the state of the stopped process, and cause it to
37 terminate or continue as appropriate.
38 .Fn ptrace
39 is the mechanism by which all this happens.
40 .Pp
41 The
42 .Fa request
43 argument specifies what operation is being performed; the meaning of
44 the rest of the arguments depends on the operation, but except for one
45 special case noted below, all
46 .Fn ptrace
47 calls are made by the tracing process, and the
48 .Fa pid
49 argument specifies the process ID of the traced process.
50 .Fa request
51 can be:
52 .Bl -tag -width 12n
53 .It Dv PT_TRACE_ME
54 This request is the only one used by the traced process; it declares
55 that the process expects to be traced by its parent.
56 All the other arguments are ignored.
57 (If the parent process does not expect to trace
58 the child, it will probably be rather confused by the results; once the
59 traced process stops, it cannot be made to continue except via
60 .Fn ptrace . )
61 When a process has used this request and calls
62 .Xr execve 2
63 or any of the routines built on it
64 .Po
65 such as
66 .Xr execv 3
67 .Pc ,
68 it will stop before executing the first instruction of the new image.
69 Also, any setuid or setgid bits on the executable being executed will
70 be ignored.
71 .It Dv PT_READ_I , Dv PT_READ_D
72 These requests read a single
73 .Li int
74 of data from the traced process' address space.
75 Traditionally,
76 .Fn ptrace
77 has allowed for machines with distinct address spaces for instruction
78 and data, which is why there are two requests: conceptually,
79 .Dv PT_READ_I
80 reads from the instruction space and
81 .Dv PT_READ_D
82 reads from the data space.
83 In the current
84 .Nx
85 implementation, these
86 two requests are completely identical.
87 The
88 .Fa addr
89 argument specifies the address (in the traced process' virtual address
90 space) at which the read is to be done.
91 This address does not have to meet any alignment constraints.
92 The value read is returned as the return value from
93 .Eo \&
94 .Fn ptrace
95 .Ec .
96 .It Dv PT_WRITE_I , Dv PT_WRITE_D
97 These requests parallel
98 .Dv PT_READ_I
99 and
100 .Dv PT_READ_D ,
101 except that they write rather than read.
102 The
103 .Fa data
104 argument supplies the value to be written.
105 .\" .It Dv PT_READ_U
106 .\" This request reads an
107 .\" .Li int
108 .\" from the traced process' user structure.
109 .\" The
110 .\" .Fa addr
111 .\" argument specifies the location of the int relative to the base of the
112 .\" user structure; it will usually be an integer value cast to
113 .\" .Li caddr_t
114 .\" either explicitly or via the presence of a prototype for
115 .\" .Eo \&
116 .\" .Fn ptrace
117 .\" .Ec .
118 .\" Unlike
119 .\" .Dv PT_READ_I
120 .\" and
121 .\" .Dv PT_READ_D ,
122 .\" .Fa addr
123 .\" must be aligned on an
124 .\" .Li int
125 .\" boundary.
126 .\" The value read is returned as the return value from
127 .\" .Eo \&
128 .\" .Fn ptrace
129 .\" .Ec .
130 .\" .It Dv PT_WRITE_U
131 .\" This request writes an
132 .\" .Li int
133 .\" into the traced process' user structure.
134 .\" .Fa addr
135 .\" specifies the offset, just as for
136 .\" .Dv PT_READ_U ,
137 .\" and
138 .\" .Fa data
139 .\" specifies the value to be written, just as for
140 .\" .Dv PT_WRITE_I
141 .\" and
142 .\" .Dv PT_WRITE_D .
143 .It Dv PT_CONTINUE
144 The traced process continues execution.
145 .Fa addr
146 is an address specifying the place where execution is to be resumed (a
147 new value for the program counter), or
148 .Li (caddr_t)1
149 to indicate that execution is to pick up where it left off.
150 .Fa data
151 provides a signal number to be delivered to the traced process as it
152 resumes execution, or 0 if no signal is to be sent.
153 .It Dv PT_KILL
154 The traced process terminates, as if
155 .Dv PT_CONTINUE
156 had been used with
157 .Dv SIGKILL
158 given as the signal to be delivered.
159 .It Dv PT_ATTACH
160 This request allows a process to gain control of an otherwise unrelated
161 process and begin tracing it.
162 It does not need any cooperation from the to-be-traced process.
163 In this case,
164 .Fa pid
165 specifies the process ID of the to-be-traced process, and the other two
166 arguments are ignored.
167 This request requires that the target process
168 must have the same real UID as the tracing process, and that it must
169 not be executing a setuid or setgid executable.
170 (If the tracing process is running as root,
171 these restrictions do not apply.)
172 The tracing process will see the newly-traced process stop and may then
173 control it as if it had been traced all along.
174 .Pp
175 Three other restrictions apply to all tracing processes, even those
176 running as root.
177 First, no process may trace a system process.
178 Second, no process may trace the process running
179 .Xr init 8 .
180 Third, if a process has its root directory set with
181 .Xr chroot 2 ,
182 it may not trace another process unless that process's root directory
183 is at or below the tracing process's root.
184 .It Dv PT_DETACH
185 This request is like PT_CONTINUE, except that after it
186 succeeds, the traced process is no longer traced and continues
187 execution normally.
188 .It Dv PT_IO
189 This request is a more general interface that can be used instead of
190 .Dv PT_READ_D ,
191 .Dv PT_WRITE_D ,
192 .Dv PT_READ_I ,
193 and
194 .Dv PT_WRITE_I .
195 The I/O request is encoded in a
196 .Dq Li "struct ptrace_io_desc"
197 defined as:
198 .Bd -literal -offset indent
199 struct ptrace_io_desc {
200 int piod_op;
201 void *piod_offs;
202 void *piod_addr;
203 size_t piod_len;
204 };
205 .Ed
206 .Pp
207 where
208 .Fa piod_offs
209 is the offset within the traced process where the I/O operation should
210 take place,
211 .Fa piod_addr
212 is the buffer in the tracing process, and
213 .Fa piod_len
214 is the length of the I/O request.
215 The
216 .Fa piod_op
217 field specifies which type of I/O operation to perform.
218 Possible
219 values are:
220 .Bl -tag -width 18n
221 .It Dv PIOD_READ_D
222 .It Dv PIOD_WRITE_D
223 .It Dv PIOD_READ_I
224 .It Dv PIOD_WRITE_I
225 .El
226 .Pp
227 See the description of
228 .Dv PT_READ_I
229 for the difference between I and D spaces.
230 A pointer to the I/O descriptor is passed in the
231 .Fa addr
232 argument to
233 .Fn ptrace .
234 On return, the
235 .Fa piod_len
236 field in the I/O descriptor will be updated with the actual number of
237 bytes transferred.
238 If the requested I/O could not be successfully performed,
239 .Fn ptrace
240 will return
241 .Li \-1
242 and set
243 .Va errno .
244 .It Dv PT_DUMPCORE
245 Makes the process specified in the
246 .Fa pid
247 pid generate a core dump.
248 The
249 .Fa addr
250 argument should contain the name of the core file to be generated
251 and the
252 .Fa data
253 argument should contain the length of the core filename.
254 This
255 .Nm
256 call currently does not stop the child process so it can generate
257 inconsistent data.
258 .It Dv PT_LWPINFO
259 Returns information about the specific thread from the process specified
260 in the
261 .Fa pid
262 argument.
263 The
264 .Fa addr
265 argument should contain a
266 .Dq Li "struct ptrace_lwpinfo"
267 defined as:
268 .Bd -literal -offset indent
269 struct ptrace_lwpinfo {
270 lwpid_t pl_lwpid;
271 int pl_event;
272 };
273 .Ed
274 .Pp
275 where
276 .Fa pl_lwpid
277 contains the thread for which to get info.
278 Upon return
279 .Fa pl_event
280 contains the event that stopped the thread.
281 Possible
282 values are:
283 .Bl -tag -width 30n
284 .It Dv PL_EVENT_NONE
285 .It Dv PL_EVENT_SIGNAL
286 .El
287 .Pp
288 The
289 .Fa data
290 argument should contain
291 .Dq Li "sizeof(struct ptrace_lwpinfo)" .
292 .It Dv PT_SYSCALL
293 Stops a process before and after executing each system call.
294 .El
295 .Pp
296 Additionally, the following requests exist but are
297 not available on all machine architectures.
298 The file
299 .Aq Pa machine/ptrace.h
300 lists which requests exist on a given machine.
301 .Bl -tag -width 12n
302 .It Dv PT_STEP
303 Execution continues as in request PT_CONTINUE; however
304 as soon as possible after execution of at least one
305 instruction, execution stops again.
306 .It Dv PT_GETREGS
307 This request reads the traced process' machine registers into the
308 .Dq Li "struct reg"
309 (defined in
310 .Aq Pa machine/reg.h )
311 pointed to by
312 .Fa addr .
313 .It Dv PT_SETREGS
314 This request is the converse of
315 .Dv PT_GETREGS ;
316 it loads the traced process' machine registers from the
317 .Dq Li "struct reg"
318 (defined in
319 .Aq Pa machine/reg.h )
320 pointed to by
321 .Fa addr .
322 .It Dv PT_GETFPREGS
323 This request reads the traced process' floating-point registers into
324 the
325 .Dq Li "struct fpreg"
326 (defined in
327 .Aq Pa machine/reg.h )
328 pointed to by
329 .Fa addr .
330 .It Dv PT_SETFPREGS
331 This request is the converse of
332 .Dv PT_GETFPREGS ;
333 it loads the traced process' floating-point registers from the
334 .Dq Li "struct fpreg"
335 (defined in
336 .Aq Pa machine/reg.h )
337 pointed to by
338 .Fa addr .
339 .\" .It Dv PT_SYSCALL
340 .\" This request is like
341 .\" .Dv PT_CONTINUE
342 .\" except that the process will stop next time it executes any system
343 .\" call. Information about the system call can be examined with
344 .\" .Dv PT_READ_U
345 .\" and potentially modified with
346 .\" .Dv PT_WRITE_U
347 .\" through the
348 .\" .Li u_kproc.kp_proc.p_md
349 .\" element of the user structure (see below). If the process is continued
350 .\" with another
351 .\" .Dv PT_SYSCALL
352 .\" request, it will stop again on exit from the syscall, at which point
353 .\" the return values can be examined and potentially changed. The
354 .\" .Li u_kproc.kp_proc.p_md
355 .\" element is of type
356 .\" .Dq Li "struct mdproc" ,
357 .\" which should be declared by including
358 .\" .Aq Pa sys/param.h ,
359 .\" .Aq Pa sys/user.h ,
360 .\" and
361 .\" .Aq Pa machine/proc.h ,
362 .\" and contains the following fields (among others):
363 .\" .Bl -item -compact -offset indent
364 .\" .It
365 .\" .Li syscall_num
366 .\" .It
367 .\" .Li syscall_nargs
368 .\" .It
369 .\" .Li syscall_args[8]
370 .\" .It
371 .\" .Li syscall_err
372 .\" .It
373 .\" .Li syscall_rv[2]
374 .\" .El
375 .\" When a process stops on entry to a syscall,
376 .\" .Li syscall_num
377 .\" holds the number of the syscall,
378 .\" .Li syscall_nargs
379 .\" holds the number of arguments it expects, and
380 .\" .Li syscall_args
381 .\" holds the arguments themselves.
382 .\" (Only the first
383 .\" .Li syscall_nargs
384 .\" elements of
385 .\" .Li syscall_args
386 .\" are guaranteed to be useful.)
387 .\" When a process stops on exit from a syscall,
388 .\" .Li syscall_num
389 .\" is
390 .\" .Eo \&
391 .\" .Li \-1
392 .\" .Ec ,
393 .\" .Li syscall_err
394 .\" holds the error number
395 .\" .Po
396 .\" see
397 .\" .Xr errno 2
398 .\" .Pc ,
399 .\" or 0 if no error occurred, and
400 .\" .Li syscall_rv
401 .\" holds the return values.
402 .\" (If the syscall returns only one value, only
403 .\" .Li syscall_rv[0]
404 .\" is useful.)
405 .\" The tracing process can modify any of these with
406 .\" .Dv PT_WRITE_U ;
407 .\" only some modifications are useful.
408 .\" .Pp
409 .\" On entry to a syscall,
410 .\" .Li syscall_num
411 .\" can be changed, and the syscall actually performed will correspond to
412 .\" the new number (it is the responsibility of the tracing process to fill
413 .\" in
414 .\" .Li syscall_args
415 .\" appropriately for the new call, but there is no need to modify
416 .\" .Eo \&
417 .\" .Li syscall_nargs
418 .\" .Ec ).
419 .\" If the new syscall number is 0, no syscall is actually performed;
420 .\" instead,
421 .\" .Li syscall_err
422 .\" and
423 .\" .Li syscall_rv
424 .\" are passed back to the traced process directly (and therefore should be
425 .\" filled in).
426 .\" If the syscall number is otherwise out of range, a dummy
427 .\" syscall which simply produces an
428 .\" .Er ENOSYS
429 .\" error is effectively performed.
430 .\" .Pp
431 .\" On exit from a syscall, only
432 .\" .Li syscall_err
433 .\" and
434 .\" .Li syscall_rv
435 .\" can usefully be changed; they are set to the values returned by the
436 .\" syscall and will be passed back to the traced process by the normal
437 .\" syscall return mechanism.
438 .It Dv PT_DUMPCORE
439 Cause the traced process to dump core.
440 If the
441 .Fa addr
442 argument is not
443 .Dv NULL
444 it is taken to be the pathname of the core file to be generated and the
445 .Fa data
446 argument should contain the length of the pathname.
447 The pathname may contain
448 .Dv %
449 patterns that are expanded as described in
450 .Xr sysctl 8 .
451 If the
452 .Fa data
453 argument is
454 .Dv NULL ,
455 the default core file path generation rules are followed.
456 .El
457 .Sh ERRORS
458 Some requests can cause
459 .Fn ptrace
460 to return
461 .Li \-1
462 as a non-error value; to disambiguate,
463 .Va errno
464 can be set to 0 before the call and checked afterwards.
465 The possible errors are:
466 .Bl -tag -width 4n
467 .It Bq Er EAGAIN
468 Process is currently exec'ing and cannot be traced.
469 .It Bq Er ESRCH
470 No process having the specified process ID exists.
471 .It Bq Er EINVAL
472 .Bl -bullet -compact
473 .It
474 A process attempted to use
475 .Dv PT_ATTACH
476 on itself.
477 .It
478 The
479 .Fa request
480 was not a legal request on this machine architecture.
481 .\" .It
482 .\" The
483 .\" .Fa addr
484 .\" to
485 .\" .Dv PT_READ_U
486 .\" or
487 .\" .Dv PT_WRITE_U
488 .\" was not
489 .\" .Li int Ns \&-aligned.
490 .It
491 The signal number (in
492 .Fa data )
493 to
494 .Dv PT_CONTINUE
495 .\" or
496 .\" .Dv PT_SYSCALL
497 was neither 0 nor a legal signal number.
498 .It
499 .Dv PT_GETREGS ,
500 .Dv PT_SETREGS ,
501 .Dv PT_GETFPREGS ,
502 or
503 .Dv PT_SETFPREGS
504 was attempted on a process with no valid register set.
505 (This is normally true only of system processes.)
506 .El
507 .It Bq Er EBUSY
508 .Bl -bullet -compact
509 .It
510 .Dv PT_ATTACH
511 was attempted on a process that was already being traced.
512 .It
513 A request attempted to manipulate a process that was being traced by
514 some process other than the one making the request.
515 .It
516 A request (other than
517 .Dv PT_ATTACH )
518 specified a process that wasn't stopped.
519 .El
520 .It Bq Er EPERM
521 .Bl -bullet -compact
522 .It
523 A request (other than
524 .Dv PT_ATTACH )
525 attempted to manipulate a process that wasn't being traced at all.
526 .It
527 An attempt was made to use
528 .Dv PT_ATTACH
529 on a process in violation of the requirements listed under
530 .Dv PT_ATTACH
531 above.
532 .El
533 .El
534 .Sh SEE ALSO
535 .Xr sigaction 2 ,
536 .Xr signal 7
537 .Sh BUGS
538 On the SPARC, the PC is set to the provided PC value for
539 .Dv PT_CONTINUE
540 and similar calls,
541 but the NPC is set willy-nilly to 4 greater than the PC value.
542 Using
543 .Dv PT_GETREGS
544 and
545 .Dv PT_SETREGS
546 to modify the PC, passing
547 .Li (caddr_t)1
548 to
549 .Eo \&
550 .Fn ptrace
551 .Ec ,
552 should be able to sidestep this.
553 .\" .Pp
554 .\" When using
555 .\" .Dv PT_SYSCALL ,
556 .\" there is no easy way to tell whether the traced process stopped because
557 .\" it made a syscall or because a signal was sent at a moment that it just
558 .\" happened to have valid-looking garbage in its
559 .\" .Dq Li "struct mdproc" .