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