| blob | efb27259c0b0ab586258360b3b837267e9bf3b88 |
1 .TH PTRACE 2 "September 27, 2009"
2 .UC 4
3 .SH NAME
4 ptrace \- process trace
5 .SH SYNOPSIS
6 .nf
7 .ft B
8 #include <sys/types.h>
9 #include <sys/ptrace.h>
11 long ptrace(int \fIreq\fP, pid_t \fIpid\fP, long \fIaddr\fP, long \fIdata\fP)
12 .ft R
13 .fi
14 .SH DESCRIPTION
15 The \fBptrace\fP call provides a primitive means to trace (debug) another
16 process. A process can submit itself to tracing using a \fBT_OK\fP ptrace
17 request, or can be attached to by a tracer using a \fBT_ATTACH\fP request.
18 From that point on, whenever a signal is sent to the traced process,
19 the process will be stopped. Its tracer will be told about the signal
20 causing the stop, via
21 .BR wait (2).
22 The tracer can then inspect the traced process, and choose how to continue the
23 process's execution and whether to pass on the signal to it.
24 .PP
25 In the current model, the tracer will be notified of the signal before any
26 checks on ignore or block masks are made. A \fBSIGKILL\fP signal cannot be
27 intercepted by the tracer, and will always kill the traced process.
28 .PP
29 When the traced process performs a successful
30 .BR execve (2)
31 call, it will be stopped and a \fBSIGTRAP\fP will be generated for it.
32 Set-uid and set-gid bits on the new executable are ignored.
33 .PP
34 The \fIreq\fP parameter specifies the process trace request. The interpretation
35 of the remaining parameters depends on the given request. For all requests
36 except \fBT_OK\fP, the \fIpid\fP parameter specifies process ID of the target
37 process. For all requests except \fBT_OK\fP and \fBT_ATTACH\fP, the process
38 must be stopped. The following requests are supported:
39 .TP 2
40 .B T_OK
41 Set the caller's parent to be its tracer. All other arguments are ignored.
42 This request is typically made by the child fork of a debugger,
43 before performing an
44 .BR execve (2)
45 call.
46 .TP
47 .B T_GETINS, T_GETDATA
48 Retrieve a value from the given process's instruction and data area,
49 respectively, at the address given in \fIaddr\fP.
50 .TP
51 .B T_SETINS, T_SETDATA
52 Set the value from the given process's instruction and data area, respectively,
53 at the address given in \fIaddr\fP, to the value given in \fIdata\fP.
54 .TP
55 .B T_GETUSER
56 Retrieve the value at the zero-based offset given in \fIaddr\fP from the
57 process's \fBstruct proc\fP kernel structure, followed by, aligned on
58 \fBlong\fP size boundary, its \fBstruct priv\fP kernel structure.
59 .TP
60 .B T_SETUSER
61 Set some of the given process's registers at the beginning of its
62 \fBstruct proc\fP kernel structure. The value in \fIdata\fP will be written to
63 the zero-based offset given in \fIaddr\fP from the process's \fBstruct proc\fP
64 kernel structure.
65 .TP
66 .B T_RESUME
67 Resume execution of the process. A nonzero \fIdata\fP argument will be
68 interpreted as a signal to pass to the process.
69 .TP
70 .B T_STEP
71 Single-step an instruction. A nonzero \fIdata\fP argument will be interpreted
72 as a signal to pass to the process.
73 .TP
74 .B T_SYSCALL
75 Resume execution with system call tracing. When the traced process makes a
76 system call, a \fBSIGTRAP\fP signal will be generated. A subsequent
77 \fBT_SYSCALL\fP request will then cause a \fBSIGTRAP\fP signal to be generated
78 when the process leaves the system call. A nonzero \fIdata\fP argument will be
79 interpreted as a signal to pass to the process.
80 .TP
81 .B T_EXIT
82 Terminate the traced process, with the exit code given in the \fIdata\fP
83 argument. This call will return once the process has exited.
84 .TP
85 .B T_ATTACH
86 Attach to the given process. The process will be stopped with a \fBSIGSTOP\fP
87 signal.
88 .TP
89 .B T_DETACH
90 Detach from the given process. Any signals still pending for the tracer are
91 passed on directly to the process. A nonzero \fIdata\fP argument will be
92 interpreted as an additional signal to pass to the process.
93 .TP
94 .B T_SETOPT
95 Set the given process's trace options to the bit combination of flags given
96 in the \fIdata\fP argument.
97 .TP
98 .B T_GETRANGE
99 Get a range of values from the address space of the traced process. The
100 \fIaddr\fP argument must be a pointer to a fully initialized
101 \fBstruct ptrace_range\fP structure.
102 .TP
103 .B T_SETRANGE
104 Set a range of values in the address space of the traced process. The
105 \fIaddr\fP argument must be a pointer to a fully initialized
106 \fBstruct ptrace_range\fP structure.
107 .PP
108 The following option flags are currently supported for \fBT_SETOPT\fP:
109 .TP 2
110 .B TO_TRACEFORK
111 When the traced process performs a
112 .BR fork (2),
113 automatically attach to the new child as well.
114 The child will be stopped with a \fBSIGSTOP\fP signal right after forking.
115 .TP
116 .B TO_ALTEXEC
117 Send \fBSIGSTOP\fP instead of \fBSIGTRAP\fP upon a successful
118 .BR execve (2).
119 This allows the tracer to disambiguate between this case and other traps.
120 .TP
121 .B TO_NOEXEC
122 Do not send any signal upon a successful
123 .BR execve (2).
124 .PP
125 The default set of trace options when tracing is initiated with \fBT_OK\fP is
126 \fB0\fP.
127 The default set of trace options after attaching with \fBT_ATTACH\fP is
128 \fBTO_NOEXEC\fP.
129 .PP
130 The \fBT_GETRANGE\fP and \fBT_SETRANGE\fP calls use the following structure:
131 .PP
132 .RS
133 .nf
134 .ft B
135 .ta +4n +8n
136 struct ptrace_range {
137 int pr_space;
138 long pr_addr;
139 size_t pr_size;
140 void *pr_ptr;
141 };
142 .ft R
143 .fi
144 .RE
145 .PP
146 The \fBpr_space\fP field specifies the address space from which to retrieve
147 or set the values. It must be set to either of the following values:
148 .PP
149 .TP 10
150 .B TS_INS
151 Text space.
152 .TP
153 .B TS_DATA
154 Data space.
155 .PP
156 The \fBpr_addr\fP field specifies the start address of the target area in the
157 traced process. The \fBpr_size\fP field specifies the number of bytes to
158 retrieve or set, and must be between 1 and LONG_MAX. The \fBpr_ptr\fP field
159 must point to a buffer in the calling process that is used to store the
160 retrieved values (for \fBT_GETRANGE\fP) or contains the values to set (for
161 \fBT_SETRANGE\fP).
162 .PP
163 All addresses specified for the \fBT_GETINS\fP, \fBT_GETDATA\fP,
164 \fBT_GETUSER\fP requests and their \fBT_SET\fP* counterparts must be
165 aligned on \fBlong\fP boundary. Similarly, only \fBlong\fP sized values can be
166 retrieved and set at a time.
167 .SH "RETURN VALUE"
168 All but the \fBT_GETINS\fP, \fBT_GETDATA\fP, \fBT_GETUSER\fP requests return 0
169 upon successful completion.
170 Otherwise, a value of -1 is returned and \fIerrno\fP is set to indicate the
171 error.
172 .PP
173 The \fBT_GETINS\fP, \fBT_GETDATA\fP, \fBT_GETUSER\fP requests return the
174 resulting data. Here, -1 is a legitimate return value.
175 To distinguish between this and an error, clear \fIerrno\fP
176 before the \fBptrace\fP call, and check whether it is zero afterwards.
177 .SH ERRORS
178 The functions will fail if any of the following errors occur:
179 .TP 10
180 .B EINVAL
181 Invalid request, signal, space, or length given.
182 .TP
183 .B ESRCH
184 The given process is not found, exiting, or not traced by the caller.
185 .TP
186 .B EBUSY
187 The given process is not stopped, or already being traced.
188 .TP
189 .B EFAULT
190 The given address is invalid, inaccessible, or not properly aligned.
191 .TP
192 .B EPERM
193 Attaching is denied, because the caller equals the given process,
194 or the caller is not root and does not match the given process's
195 user or group ID, or the caller is not root and the given process
196 is a system process, or the caller is a system process,
197 or the given process may not be traced at all.
198 .SH LIMITATIONS
199 Signals are not ordered. Attaching to a process guarantees that a \fBSIGSTOP\fP
200 will arrive at the tracer, but it is not guaranteed that this will be the first
201 signal to arrive. The same goes for automatically attached children of the
202 traced process. Similarly, if the tracer wants to detach from a running
203 process, it will typically send a \fBSIGSTOP\fP using
204 .BR kill (2)
205 to the process to stop it, but there is no guarantee that this will be the
206 first signal to arrive.
207 .PP
208 Signals not caused by the process itself (e.g. those caused by
209 .BR kill (2))
210 will arrive at the tracer while the process is in stopped state, but this does
211 not imply that the process is in a stable state at that point. The process may
212 still have a system call pending, and this means that registers and memory of
213 the process may change almost arbitrarily after the tracer has been told about
214 the arrival of the current signal. Implementers of debuggers are advised to
215 make minimal assumptions about the conditions of the process when an unexpected
216 signal arrives.
217 .PP
218 It is not possible to use \fBT_SYSCALL\fP to get a trap upon leaving of a
219 system call, if \fBT_SYSCALL\fP was not used to get a trap upon entering that
220 system call. This is in fact helpful: after attaching to a process, the first
221 \fBT_SYSCALL\fP call will always cause a trap after entering the next system
222 call. As the only exception, \fBT_SYSCALL\fP on a
223 .BR fork (2)
224 call of a process with \fBTO_TRACEFORK\fP set, will result in two traps upon
225 leaving: one for the parent, and one for the child. The child's \fBSIGSTOP\fP
226 signal will always come before the \fBSIGTRAP\fP from its leaving the system
227 call.
228 .PP
229 There is no way to reliably distinguish between real signals and signals
230 generated for the tracer.
231 .PP
232 For system stability reasons, the PM and VM servers cannot be traced.
233 .SH "SEE ALSO"
234 .BR wait (2),
235 .BR kill (2),
236 .BR mdb (1)
237 .SH AUTHOR
238 Manual page written by David van Moolenbroek <dcvmoole@cs.vu.nl>