Commit | Line | Data |
---|---|---|
3979b9c6 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
3e664f4b | 5 | .\" @(#)ptrace.2 6.4 (Berkeley) %G% |
3979b9c6 | 6 | .\" |
504c07f6 | 7 | .TH PTRACE 2 "" |
3979b9c6 KM |
8 | .UC 4 |
9 | .SH NAME | |
10 | ptrace \- process trace | |
11 | .SH SYNOPSIS | |
12 | .nf | |
5722ea81 | 13 | .ft B |
504c07f6 KM |
14 | #include <sys/signal.h> |
15 | #include <sys/ptrace.h> | |
3979b9c6 | 16 | .PP |
5722ea81 KM |
17 | .ft B |
18 | ptrace(request, pid, addr, data) | |
19 | int request, pid, *addr, data; | |
3979b9c6 KM |
20 | .fi |
21 | .SH DESCRIPTION | |
22 | .I Ptrace | |
23 | provides a means by which a parent process | |
24 | may control the execution of a child process, | |
25 | and examine and change its core image. | |
26 | Its primary use is for the implementation of breakpoint debugging. | |
27 | There are four arguments whose interpretation | |
28 | depends on a | |
29 | .I request | |
30 | argument. | |
31 | Generally, | |
32 | .I pid | |
33 | is the process ID of the traced process, | |
34 | which must be a child (no more distant descendant) | |
35 | of the tracing process. | |
36 | A process being traced | |
5722ea81 KM |
37 | behaves normally until it encounters some signal |
38 | whether internally generated | |
39 | like \*(lqillegal instruction\*(rq or externally | |
40 | generated like \*(lqinterrupt\*(rq. | |
3979b9c6 | 41 | See |
5722ea81 | 42 | .IR sigvec (2) |
3979b9c6 KM |
43 | for the list. |
44 | Then the traced process enters a stopped state | |
45 | and its parent is notified via | |
46 | .IR wait (2). | |
47 | When the child is in the stopped state, | |
48 | its core image can be examined and modified | |
49 | using | |
50 | .IR ptrace . | |
51 | If desired, another | |
52 | .I ptrace | |
53 | request can then cause the child either to terminate | |
54 | or to continue, possibly ignoring the signal. | |
55 | .PP | |
56 | The value of the | |
57 | .I request | |
58 | argument determines the precise | |
59 | action of the call: | |
60 | .TP 4 | |
504c07f6 | 61 | PT_TRACE_ME |
3979b9c6 KM |
62 | This request is the only one used by the child process; |
63 | it declares that the process is to be traced by its parent. | |
64 | All the other arguments are ignored. | |
65 | Peculiar results will ensue | |
66 | if the parent does not expect to trace the child. | |
67 | .TP 4 | |
504c07f6 | 68 | PT_READ_I, PT_READ_D |
3979b9c6 KM |
69 | The |
70 | word in the child process's address space | |
71 | at | |
72 | .I addr | |
73 | is returned. | |
5722ea81 | 74 | If I and D space are separated (e.g. historically |
504c07f6 KM |
75 | on a pdp-11), request PT_READ_I indicates I space, |
76 | PT_READ_D D space. | |
3979b9c6 | 77 | .I Addr |
dfbb588f | 78 | must be even on some machines. |
3979b9c6 KM |
79 | The child must be stopped. |
80 | The input | |
81 | .I data | |
82 | is ignored. | |
83 | .TP 4 | |
504c07f6 | 84 | PT_READ_U |
3979b9c6 KM |
85 | The word |
86 | of the system's per-process data area corresponding to | |
87 | .I addr | |
88 | is returned. | |
89 | .I Addr | |
dfbb588f | 90 | must be even on some machines and less than 512. |
3979b9c6 KM |
91 | This space contains the registers and other information about |
92 | the process; | |
93 | its layout corresponds to the | |
94 | .I user | |
95 | structure in the system. | |
96 | .TP 4 | |
504c07f6 | 97 | PT_WRITE_I, PT_WRITE_D |
3979b9c6 KM |
98 | The |
99 | given | |
100 | .I data | |
101 | is written at the word in the process's address space corresponding to | |
102 | .I addr, | |
dfbb588f | 103 | which must be even on some machines. |
3979b9c6 | 104 | No useful value is returned. |
504c07f6 KM |
105 | If I and D space are separated, request PT_WRITE_I indicates I space, |
106 | PT_WRITE_D D space. | |
3979b9c6 KM |
107 | Attempts to write in pure procedure |
108 | fail if another process is executing the same file. | |
109 | .TP 4 | |
504c07f6 | 110 | PT_WRITE_U |
3979b9c6 | 111 | The process's system data is written, |
504c07f6 | 112 | as it is read with request PT_READ_U. |
3979b9c6 KM |
113 | Only a few locations can be written in this way: |
114 | the general registers, | |
115 | the floating point status and registers, | |
116 | and certain bits of the processor status word. | |
117 | .TP 4 | |
504c07f6 | 118 | PT_CONTINUE |
3979b9c6 KM |
119 | The |
120 | .I data | |
121 | argument is taken as a signal number | |
122 | and the child's execution continues | |
123 | at location | |
124 | .I addr | |
125 | as if it had incurred that signal. | |
126 | Normally the signal number will be | |
127 | either 0 to indicate that the signal that caused the stop | |
128 | should be ignored, | |
129 | or that value fetched out of the | |
130 | process's image indicating which signal caused | |
131 | the stop. | |
132 | If | |
133 | .I addr | |
134 | is (int *)1 then execution continues from where it stopped. | |
135 | .TP 4 | |
504c07f6 | 136 | PT_KILL |
3979b9c6 KM |
137 | The traced process terminates. |
138 | .TP 4 | |
504c07f6 KM |
139 | PT_STEP |
140 | Execution continues as in request PT_CONTINUE; | |
3979b9c6 KM |
141 | however, as soon as possible after execution of at least one instruction, |
142 | execution stops again. | |
143 | The signal number from the stop is | |
144 | SIGTRAP. | |
5722ea81 KM |
145 | (On the VAX-11 the T-bit is used and just one instruction |
146 | is executed.) | |
3979b9c6 KM |
147 | This is part of the mechanism for implementing breakpoints. |
148 | .PP | |
149 | As indicated, | |
150 | these calls | |
504c07f6 | 151 | (except for request PT_TRACE_ME) |
3979b9c6 KM |
152 | can be used only when the subject process has stopped. |
153 | The | |
154 | .I wait | |
155 | call is used to determine | |
156 | when a process stops; | |
5722ea81 | 157 | in such a case the \*(lqtermination\*(rq status |
3979b9c6 KM |
158 | returned by |
159 | .I wait | |
160 | has the value 0177 to indicate stoppage rather | |
161 | than genuine termination. | |
162 | .PP | |
163 | To forestall possible fraud, | |
164 | .I ptrace | |
5722ea81 | 165 | inhibits the set-user-id and set-group-id facilities |
3979b9c6 | 166 | on subsequent |
5722ea81 | 167 | .IR execve (2) |
3979b9c6 KM |
168 | calls. |
169 | If a traced process calls | |
5722ea81 | 170 | .IR execve , |
3979b9c6 KM |
171 | it will stop before executing the first instruction of the new image |
172 | showing signal SIGTRAP. | |
173 | .PP | |
5722ea81 KM |
174 | On a VAX-11, \*(lqword\*(rq also means a 32-bit integer, |
175 | but the \*(lqeven\*(rq | |
176 | restriction does not apply. | |
177 | .SH "RETURN VALUE | |
178 | A 0 value is returned if the call succeeds. If the call fails | |
179 | then a \-1 is returned and the global variable \fIerrno\fP is | |
180 | set to indicate the error. | |
181 | .SH "ERRORS | |
182 | .TP 15 | |
fd690c8b | 183 | [EIO] |
5722ea81 KM |
184 | The request code is invalid. |
185 | .TP 15 | |
fd690c8b | 186 | [ESRCH] |
5722ea81 KM |
187 | The specified process does not exist. |
188 | .TP 15 | |
fd690c8b | 189 | [EIO] |
5722ea81 KM |
190 | The given signal number is invalid. |
191 | .TP 15 | |
fd690c8b | 192 | [EIO] |
5722ea81 KM |
193 | The specified address is out of bounds. |
194 | .TP 15 | |
195 | [EPERM] | |
196 | The specified process cannot be traced. | |
3979b9c6 | 197 | .SH "SEE ALSO" |
5722ea81 | 198 | wait(2), sigvec(2), adb(1) |
3979b9c6 KM |
199 | .SH BUGS |
200 | .I Ptrace | |
dfbb588f | 201 | is unique and arcane; it should be replaced with a special file that |
3979b9c6 KM |
202 | can be opened and read and written. The control functions could then |
203 | be implemented with | |
204 | .IR ioctl (2) | |
205 | calls on this file. This would be simpler to understand and have much | |
206 | higher performance. | |
207 | .PP | |
504c07f6 | 208 | The request PT_TRACE_ME call should be able to specify |
dfbb588f | 209 | signals that are to be treated normally and not cause a stop. |
3979b9c6 KM |
210 | In this way, for example, |
211 | programs with simulated floating point (which | |
5722ea81 | 212 | use \*(lqillegal instruction\*(rq signals at a very high rate) |
3979b9c6 KM |
213 | could be efficiently debugged. |
214 | .PP | |
215 | The error indication, \-1, is a legitimate function value; | |
216 | .I errno, | |
3e664f4b KD |
217 | (see |
218 | .IR intro (2)), | |
3979b9c6 KM |
219 | can be used to disambiguate. |
220 | .PP | |
221 | It should be possible to stop a process on occurrence of a system | |
222 | call; | |
223 | in this way a completely controlled environment could | |
224 | be provided. |