| blob | 7548e92bdaeef196465f977bf16673e79d6d0272 |
1 .\" $NetBSD: ptrace.2,v 1.35 2011/08/31 23:04:33 jmcneill Exp $
2 .\"
3 .\" This file is in the public domain.
4 .Dd August 31, 2011
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 If a negative value is supplied, that is the negative of the LWP
154 ID of the thread to be resumed, and only that thread executes.
155 .It Dv PT_KILL
156 The traced process terminates, as if
157 .Dv PT_CONTINUE
158 had been used with
159 .Dv SIGKILL
160 given as the signal to be delivered.
161 .It Dv PT_ATTACH
162 This request allows a process to gain control of an otherwise unrelated
163 process and begin tracing it.
164 It does not need any cooperation from the to-be-traced process.
165 In this case,
166 .Fa pid
167 specifies the process ID of the to-be-traced process, and the other two
168 arguments are ignored.
169 This request requires that the target process
170 must have the same real UID as the tracing process, and that it must
171 not be executing a setuid or setgid executable.
172 (If the tracing process is running as root,
173 these restrictions do not apply.)
174 The tracing process will see the newly-traced process stop and may then
175 control it as if it had been traced all along.
176 .Pp
177 Three other restrictions apply to all tracing processes, even those
178 running as root.
179 First, no process may trace a system process.
180 Second, no process may trace the process running
181 .Xr init 8 .
182 Third, if a process has its root directory set with
183 .Xr chroot 2 ,
184 it may not trace another process unless that process's root directory
185 is at or below the tracing process's root.
186 .It Dv PT_DETACH
187 This request is like PT_CONTINUE, except that after it
188 succeeds, the traced process is no longer traced and continues
189 execution normally.
190 .It Dv PT_IO
191 This request is a more general interface that can be used instead of
192 .Dv PT_READ_D ,
193 .Dv PT_WRITE_D ,
194 .Dv PT_READ_I ,
195 and
196 .Dv PT_WRITE_I .
197 The I/O request is encoded in a
198 .Dq Li "struct ptrace_io_desc"
199 defined as:
200 .Bd -literal -offset indent
201 struct ptrace_io_desc {
202 int piod_op;
203 void *piod_offs;
204 void *piod_addr;
205 size_t piod_len;
206 };
207 .Ed
208 .Pp
209 where
210 .Fa piod_offs
211 is the offset within the traced process where the I/O operation should
212 take place,
213 .Fa piod_addr
214 is the buffer in the tracing process, and
215 .Fa piod_len
216 is the length of the I/O request.
217 The
218 .Fa piod_op
219 field specifies which type of I/O operation to perform.
220 Possible values are:
221 .Pp
222 .Bl -tag -width 18n -offset indent -compact
223 .It Dv PIOD_READ_D
224 .It Dv PIOD_WRITE_D
225 .It Dv PIOD_READ_I
226 .It Dv PIOD_WRITE_I
227 .El
228 .Pp
229 See the description of
230 .Dv PT_READ_I
231 for the difference between I and D spaces.
232 A pointer to the I/O descriptor is passed in the
233 .Fa addr
234 argument to
235 .Fn ptrace .
236 On return, the
237 .Fa piod_len
238 field in the I/O descriptor will be updated with the actual number of
239 bytes transferred.
240 If the requested I/O could not be successfully performed,
241 .Fn ptrace
242 will return
243 .Li \-1
244 and set
245 .Va errno .
246 .It Dv PT_DUMPCORE
247 Makes the process specified in the
248 .Fa pid
249 pid generate a core dump.
250 The
251 .Fa addr
252 argument should contain the name of the core file to be generated
253 and the
254 .Fa data
255 argument should contain the length of the core filename.
256 This
257 .Nm
258 call currently does not stop the child process so it can generate
259 inconsistent data.
260 .It Dv PT_LWPINFO
261 Returns information about a thread from the list of threads for the
262 process specified in the
263 .Fa pid
264 argument.
265 The
266 .Fa addr
267 argument should contain a
268 .Dq Li "struct ptrace_lwpinfo"
269 defined as:
270 .Bd -literal -offset indent
271 struct ptrace_lwpinfo {
272 lwpid_t pl_lwpid;
273 int pl_event;
274 };
275 .Ed
276 .Pp
277 where
278 .Fa pl_lwpid
279 contains a thread LWP ID.
280 Information is returned for the thread following the one with the
281 specified ID in the process thread list, or for the first thread
282 if
283 .Fa pl_lwpid
284 is 0.
285 Upon return
286 .Fa pl_lwpid
287 contains the LWP ID of the thread that was found, or 0 if there is
288 no thread after the one whose LWP ID was supplied in the call.
289 .Fa pl_event
290 contains the event that stopped the thread.
291 Possible values are:
292 .Pp
293 .Bl -tag -width 30n -offset indent -compact
294 .It Dv PL_EVENT_NONE
295 .It Dv PL_EVENT_SIGNAL
296 .El
297 .Pp
298 The
299 .Fa data
300 argument should contain
301 .Dq Li "sizeof(struct ptrace_lwpinfo)" .
302 .It Dv PT_SYSCALL
303 Stops a process before and after executing each system call.
304 .It Dv PT_SYSCALLEMU
305 Intercept and ignore a system call before it has been executed, for use with
306 .Dv PT_SYSCALL .
307 .El
308 .Pp
309 Additionally, the following requests exist but are
310 not available on all machine architectures.
311 The file
312 .In machine/ptrace.h
313 lists which requests exist on a given machine.
314 .Bl -tag -width 12n
315 .It Dv PT_STEP
316 Execution continues as in request PT_CONTINUE; however
317 as soon as possible after execution of at least one
318 instruction, execution stops again.
319 If the
320 .Fa data
321 argument is greater than 0, it contains the LWP ID of the thread to be
322 stepped, and any other threads are continued.
323 If the
324 .Fa data
325 argument is less than zero, it contains the negative of the LWP ID of
326 the thread to be stepped, and only that thread executes.
327 .It Dv PT_GETREGS
328 This request reads the traced process' machine registers into the
329 .Dq Li "struct reg"
330 (defined in
331 .In machine/reg.h )
332 pointed to by
333 .Fa addr .
334 The
335 .Fa data
336 argument contains the LWP ID of the thread whose registers are to
337 be read.
338 If zero is supplied, the first thread of the process is read.
339 .It Dv PT_SETREGS
340 This request is the converse of
341 .Dv PT_GETREGS ;
342 it loads the traced process' machine registers from the
343 .Dq Li "struct reg"
344 (defined in
345 .In machine/reg.h )
346 pointed to by
347 .Fa addr .
348 The
349 .Fa data
350 argument contains the LWP ID of the thread whose registers are to
351 be written.
352 If zero is supplied, the first thread of the process is written.
353 .It Dv PT_GETFPREGS
354 This request reads the traced process' floating-point registers into
355 the
356 .Dq Li "struct fpreg"
357 (defined in
358 .In machine/reg.h )
359 pointed to by
360 .Fa addr .
361 The
362 .Fa data
363 argument contains the LWP ID of the thread whose registers are to
364 be read.
365 If zero is supplied, the first thread of the process is read.
366 .It Dv PT_SETFPREGS
367 This request is the converse of
368 .Dv PT_GETFPREGS ;
369 it loads the traced process' floating-point registers from the
370 .Dq Li "struct fpreg"
371 (defined in
372 .In machine/reg.h )
373 pointed to by
374 .Fa addr .
375 The
376 .Fa data
377 argument contains the LWP ID of the thread whose registers are to
378 be written.
379 If zero is supplied, the first thread of the process is written.
380 .\" .It Dv PT_SYSCALL
381 .\" This request is like
382 .\" .Dv PT_CONTINUE
383 .\" except that the process will stop next time it executes any system
384 .\" call.
385 .\" Information about the system call can be examined with
386 .\" .Dv PT_READ_U
387 .\" and potentially modified with
388 .\" .Dv PT_WRITE_U
389 .\" through the
390 .\" .Li u_kproc.kp_proc.p_md
391 .\" element of the user structure (see below).
392 .\" If the process is continued
393 .\" with another
394 .\" .Dv PT_SYSCALL
395 .\" request, it will stop again on exit from the syscall, at which point
396 .\" the return values can be examined and potentially changed.
397 .\" The
398 .\" .Li u_kproc.kp_proc.p_md
399 .\" element is of type
400 .\" .Dq Li "struct mdproc" ,
401 .\" which should be declared by including
402 .\" .In sys/param.h ,
403 .\" .In sys/user.h ,
404 .\" and
405 .\" .In machine/proc.h ,
406 .\" and contains the following fields (among others):
407 .\" .Bl -item -compact -offset indent
408 .\" .It
409 .\" .Li syscall_num
410 .\" .It
411 .\" .Li syscall_nargs
412 .\" .It
413 .\" .Li syscall_args[8]
414 .\" .It
415 .\" .Li syscall_err
416 .\" .It
417 .\" .Li syscall_rv[2]
418 .\" .El
419 .\" When a process stops on entry to a syscall,
420 .\" .Li syscall_num
421 .\" holds the number of the syscall,
422 .\" .Li syscall_nargs
423 .\" holds the number of arguments it expects, and
424 .\" .Li syscall_args
425 .\" holds the arguments themselves.
426 .\" (Only the first
427 .\" .Li syscall_nargs
428 .\" elements of
429 .\" .Li syscall_args
430 .\" are guaranteed to be useful.)
431 .\" When a process stops on exit from a syscall,
432 .\" .Li syscall_num
433 .\" is
434 .\" .Eo \&
435 .\" .Li \-1
436 .\" .Ec ,
437 .\" .Li syscall_err
438 .\" holds the error number
439 .\" .Po
440 .\" see
441 .\" .Xr errno 2
442 .\" .Pc ,
443 .\" or 0 if no error occurred, and
444 .\" .Li syscall_rv
445 .\" holds the return values.
446 .\" (If the syscall returns only one value, only
447 .\" .Li syscall_rv[0]
448 .\" is useful.)
449 .\" The tracing process can modify any of these with
450 .\" .Dv PT_WRITE_U ;
451 .\" only some modifications are useful.
452 .\" .Pp
453 .\" On entry to a syscall,
454 .\" .Li syscall_num
455 .\" can be changed, and the syscall actually performed will correspond to
456 .\" the new number (it is the responsibility of the tracing process to fill
457 .\" in
458 .\" .Li syscall_args
459 .\" appropriately for the new call, but there is no need to modify
460 .\" .Eo \&
461 .\" .Li syscall_nargs
462 .\" .Ec ).
463 .\" If the new syscall number is 0, no syscall is actually performed;
464 .\" instead,
465 .\" .Li syscall_err
466 .\" and
467 .\" .Li syscall_rv
468 .\" are passed back to the traced process directly (and therefore should be
469 .\" filled in).
470 .\" If the syscall number is otherwise out of range, a dummy
471 .\" syscall which simply produces an
472 .\" .Er ENOSYS
473 .\" error is effectively performed.
474 .\" .Pp
475 .\" On exit from a syscall, only
476 .\" .Li syscall_err
477 .\" and
478 .\" .Li syscall_rv
479 .\" can usefully be changed; they are set to the values returned by the
480 .\" syscall and will be passed back to the traced process by the normal
481 .\" syscall return mechanism.
482 .It Dv PT_DUMPCORE
483 Cause the traced process to dump core.
484 If the
485 .Fa addr
486 argument is not
487 .Dv NULL
488 it is taken to be the pathname of the core file to be generated and the
489 .Fa data
490 argument should contain the length of the pathname.
491 The pathname may contain
492 .Dv %
493 patterns that are expanded as described in
494 .Xr sysctl 8 .
495 If the
496 .Fa data
497 argument is
498 .Dv NULL ,
499 the default core file path generation rules are followed.
500 .El
501 .Sh ERRORS
502 Some requests can cause
503 .Fn ptrace
504 to return
505 .Li \-1
506 as a non-error value; to disambiguate,
507 .Va errno
508 can be set to 0 before the call and checked afterwards.
509 The possible errors are:
510 .Bl -tag -width "[EINVAL]"
511 .It Bq Er EAGAIN
512 Process is currently exec'ing and cannot be traced.
513 .It Bq Er EBUSY
514 .Bl -bullet -compact
515 .It
516 .Dv PT_ATTACH
517 was attempted on a process that was already being traced.
518 .It
519 A request attempted to manipulate a process that was being traced by
520 some process other than the one making the request.
521 .It
522 A request (other than
523 .Dv PT_ATTACH )
524 specified a process that wasn't stopped.
525 .El
526 .It Bq Er EINVAL
527 .Bl -bullet -compact
528 .It
529 A process attempted to use
530 .Dv PT_ATTACH
531 on itself.
532 .It
533 The
534 .Fa request
535 was not a legal request on this machine architecture.
536 .\" .It
537 .\" The
538 .\" .Fa addr
539 .\" to
540 .\" .Dv PT_READ_U
541 .\" or
542 .\" .Dv PT_WRITE_U
543 .\" was not
544 .\" .Li int Ns \&-aligned.
545 .It
546 The signal number (in
547 .Fa data )
548 to
549 .Dv PT_CONTINUE
550 .\" or
551 .\" .Dv PT_SYSCALL
552 was neither 0 nor a legal signal number.
553 .It
554 .Dv PT_GETREGS ,
555 .Dv PT_SETREGS ,
556 .Dv PT_GETFPREGS ,
557 or
558 .Dv PT_SETFPREGS
559 was attempted on a process with no valid register set.
560 (This is normally true only of system processes.)
561 .El
562 .It Bq Er EPERM
563 .Bl -bullet -compact
564 .It
565 A request (other than
566 .Dv PT_ATTACH )
567 attempted to manipulate a process that wasn't being traced at all.
568 .It
569 An attempt was made to use
570 .Dv PT_ATTACH
571 on a process in violation of the requirements listed under
572 .Dv PT_ATTACH
573 above.
574 .El
575 .It Bq Er ESRCH
576 No process having the specified process ID exists.
577 .El
578 .Sh SEE ALSO
579 .Xr sigaction 2 ,
580 .Xr signal 7
581 .Sh BUGS
582 On the SPARC, the PC is set to the provided PC value for
583 .Dv PT_CONTINUE
584 and similar calls,
585 but the NPC is set willy-nilly to 4 greater than the PC value.
586 Using
587 .Dv PT_GETREGS
588 and
589 .Dv PT_SETREGS
590 to modify the PC, passing
591 .Li (caddr_t)1
592 to
593 .Eo \&
594 .Fn ptrace
595 .Ec ,
596 should be able to sidestep this.
597 .\" .Pp
598 .\" When using
599 .\" .Dv PT_SYSCALL ,
600 .\" there is no easy way to tell whether the traced process stopped because
601 .\" it made a syscall or because a signal was sent at a moment that it just
602 .\" happened to have valid-looking garbage in its
603 .\" .Dq Li "struct mdproc" .