1 .\" $OpenBSD: ptrace.2,v 1.3 1996/10/08 01:20:12 michaels Exp $
2 .\" $NetBSD: ptrace.2,v 1.3 1996/02/23 01:39:41 jtc Exp $
4 .\" This file is in the public domain.
10 .Nd process tracing and debugging
12 .Fd #include <sys/types.h>
13 .Fd #include <sys/ptrace.h>
15 .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data"
18 provides tracing and debugging facilities. It allows one process (the
20 process) to control another (the
22 process). Most of the time, the traced process runs normally, but when
28 it stops. The tracing process is expected to notice this via
32 signal, examine the state of the stopped process, and cause it to
33 terminate or continue as appropriate.
35 is the mechanism by which all this happens.
39 argument specifies what operation is being performed; the meaning of
40 the rest of the arguments depends on the operation, but except for one
41 special case noted below, all
43 calls are made by the tracing process, and the
45 argument specifies the process ID of the traced process.
50 This request is the only one used by the traced process; it declares
51 that the process expects to be traced by its parent. All the other
52 arguments are ignored. (If the parent process does not expect to trace
53 the child, it will probably be rather confused by the results; once the
54 traced process stops, it cannot be made to continue except via
58 When a process has used this request and calls
60 or any of the routines built on it
65 it will stop before executing the first instruction of the new image.
66 Also, any setuid or setgid bits on the executable being executed will
68 .It Dv PT_READ_I , Dv PT_READ_D
69 These requests read a single
71 of data from the traced process' address space. Traditionally,
73 has allowed for machines with distinct address spaces for instruction
74 and data, which is why there are two requests: conceptually,
76 reads from the instruction space and
78 reads from the data space. In the current OpenBSD implementation, these
79 two requests are completely identical. The
81 argument specifies the address (in the traced process' virtual address
82 space) at which the read is to be done. This address does not have to
83 meet any alignment constraints. The value read is returned as the
88 .It Dv PT_WRITE_I , Dv PT_WRITE_D
89 These requests parallel
93 except that they write rather than read. The
95 argument supplies the value to be written.
97 .\" This request reads an
99 .\" from the traced process' user structure. The
101 .\" argument specifies the location of the int relative to the base of the
102 .\" user structure; it will usually be an integer value cast to
104 .\" either explicitly or via the presence of a prototype for
113 .\" must be aligned on an
115 .\" boundary. The value read is returned as the return value from
119 .\" .It Dv PT_WRITE_U
120 .\" This request writes an
122 .\" into the traced process' user structure.
124 .\" specifies the offset, just as for
128 .\" specifies the value to be written, just as for
133 The traced process continues execution.
135 is an address specifying the place where execution is to be resumed (a
136 new value for the program counter), or
138 to indicate that execution is to pick up where it left off.
140 provides a signal number to be delivered to the traced process as it
141 resumes execution, or 0 if no signal is to be sent.
143 The traced process terminates, as if
147 given as the signal to be delivered.
149 This request allows a process to gain control of an otherwise unrelated
150 process and begin tracing it. It does not need any cooperation from
151 the to-be-traced process. In this case,
153 specifies the process ID of the to-be-traced process, and the other two
154 arguments are ignored. This request requires that the target process
155 must have the same real UID as the tracing process, and that it must
156 not be executing a setuid or setgid executable. (If the tracing
157 process is running as root, these restrictions do not apply.) The
158 tracing process will see the newly-traced process stop and may then
159 control it as if it had been traced all along.
161 This request is like PT_CONTINUE, except that it does not allow
162 specifying an alternate place to continue execution, and after it
163 succeeds, the traced process is no longer traced and continues
167 Additionally, machine-specific requests can exist. On the SPARC, these
171 This request reads the traced process' machine registers into the
174 .Aq Pa machine/reg.h )
178 This request is the converse of
180 it loads the traced process' machine registers from the
183 .Aq Pa machine/reg.h )
187 This request reads the traced process' floating-point registers into
189 .Dq Li "struct fpreg"
191 .Aq Pa machine/reg.h )
195 This request is the converse of
197 it loads the traced process' floating-point registers from the
198 .Dq Li "struct fpreg"
200 .Aq Pa machine/reg.h )
203 .\" .It Dv PT_SYSCALL
204 .\" This request is like
206 .\" except that the process will stop next time it executes any system
207 .\" call. Information about the system call can be examined with
209 .\" and potentially modified with
212 .\" .Li u_kproc.kp_proc.p_md
213 .\" element of the user structure (see below). If the process is continued
216 .\" request, it will stop again on exit from the syscall, at which point
217 .\" the return values can be examined and potentially changed. The
218 .\" .Li u_kproc.kp_proc.p_md
219 .\" element is of type
220 .\" .Dq Li "struct mdproc" ,
221 .\" which should be declared by including
222 .\" .Aq Pa sys/param.h ,
223 .\" .Aq Pa sys/user.h ,
225 .\" .Aq Pa machine/proc.h ,
226 .\" and contains the following fields (among others):
227 .\" .Bl -item -compact -offset indent
231 .\" .Li syscall_nargs
233 .\" .Li syscall_args[8]
237 .\" .Li syscall_rv[2]
239 .\" When a process stops on entry to a syscall,
241 .\" holds the number of the syscall,
242 .\" .Li syscall_nargs
243 .\" holds the number of arguments it expects, and
245 .\" holds the arguments themselves. (Only the first
246 .\" .Li syscall_nargs
249 .\" are guaranteed to be useful.) When a process stops on exit from a
257 .\" holds the error number
262 .\" or 0 if no error occurred, and
264 .\" holds the return values. (If the syscall returns only one value, only
265 .\" .Li syscall_rv[0]
266 .\" is useful.) The tracing process can modify any of these with
268 .\" only some modifications are useful.
270 .\" On entry to a syscall,
272 .\" can be changed, and the syscall actually performed will correspond to
273 .\" the new number (it is the responsibility of the tracing process to fill
276 .\" appropriately for the new call, but there is no need to modify
278 .\" .Li syscall_nargs
280 .\" If the new syscall number is 0, no syscall is actually performed;
285 .\" are passed back to the traced process directly (and therefore should be
286 .\" filled in). If the syscall number is otherwise out of range, a dummy
287 .\" syscall which simply produces an
289 .\" error is effectively performed.
291 .\" On exit from a syscall, only
295 .\" can usefully be changed; they are set to the values returned by the
296 .\" syscall and will be passed back to the traced process by the normal
297 .\" syscall return mechanism.
300 Some requests can cause
304 as a non-error value; to disambiguate,
306 can be set to 0 before the call and checked afterwards. The possible
310 No process having the specified process ID exists.
314 A process attempted to use
320 was not one of the legal requests.
329 .\" .Li int Ns \&-aligned.
331 The signal number (in
337 was neither 0 nor a legal signal number.
344 was attempted on a process with no valid register set. (This is
345 normally true only of system processes.)
351 was attempted on a process that was already being traced.
353 A request attempted to manipulate a process that was being traced by
354 some process other than the one making the request.
356 A request (other than
358 specified a process that wasn't stopped.
363 A request (other than
365 attempted to manipulate a process that wasn't being traced at all.
367 An attempt was made to use
369 on a process in violation of the requirements listed under
375 On the SPARC, the PC is set to the provided PC value for
377 and similar calls, but the NPC is set willy-nilly to 4 greater than the
382 to modify the PC, passing
388 should be able to sidestep this.
390 Single-stepping is not available.
394 .\" there is no easy way to tell whether the traced process stopped because
395 .\" it made a syscall or because a signal was sent at a moment that it just
396 .\" happened to have valid-looking garbage in its
397 .\" .Dq Li "struct mdproc" .
projects / apple / xnu.git / blob