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