![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ptrace.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to ptrace.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 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: .\"
5: .\" @(#)ptrace.2 6.4 (Berkeley) 5/23/86
6: .\"
7: .TH PTRACE 2 "May 23, 1986"
8: .UC 4
9: .SH NAME
10: ptrace \- process trace
11: .SH SYNOPSIS
12: .nf
13: .ft B
14: #include <sys/signal.h>
15: #include <sys/ptrace.h>
16: .PP
17: .ft B
18: ptrace(request, pid, addr, data)
19: int request, pid, *addr, data;
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
37: behaves normally until it encounters some signal
38: whether internally generated
39: like \*(lqillegal instruction\*(rq or externally
40: generated like \*(lqinterrupt\*(rq.
41: See
42: .IR sigvec (2)
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
61: PT_TRACE_ME
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
68: PT_READ_I, PT_READ_D
69: The
70: word in the child process's address space
71: at
72: .I addr
73: is returned.
74: If I and D space are separated (e.g. historically
75: on a pdp-11), request PT_READ_I indicates I space,
76: PT_READ_D D space.
77: .I Addr
78: must be even on some machines.
79: The child must be stopped.
80: The input
81: .I data
82: is ignored.
83: .TP 4
84: PT_READ_U
85: The word
86: of the system's per-process data area corresponding to
87: .I addr
88: is returned.
89: .I Addr
90: must be even on some machines and less than 512.
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
97: PT_WRITE_I, PT_WRITE_D
98: The
99: given
100: .I data
101: is written at the word in the process's address space corresponding to
102: .I addr,
103: which must be even on some machines.
104: No useful value is returned.
105: If I and D space are separated, request PT_WRITE_I indicates I space,
106: PT_WRITE_D D space.
107: Attempts to write in pure procedure
108: fail if another process is executing the same file.
109: .TP 4
110: PT_WRITE_U
111: The process's system data is written,
112: as it is read with request PT_READ_U.
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
118: PT_CONTINUE
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
136: PT_KILL
137: The traced process terminates.
138: .TP 4
139: PT_STEP
140: Execution continues as in request PT_CONTINUE;
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.
145: (On the VAX-11 the T-bit is used and just one instruction
146: is executed.)
147: This is part of the mechanism for implementing breakpoints.
148: .PP
149: As indicated,
150: these calls
151: (except for request PT_TRACE_ME)
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;
157: in such a case the \*(lqtermination\*(rq status
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
165: inhibits the set-user-id and set-group-id facilities
166: on subsequent
167: .IR execve (2)
168: calls.
169: If a traced process calls
170: .IR execve ,
171: it will stop before executing the first instruction of the new image
172: showing signal SIGTRAP.
173: .PP
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
183: [EIO]
184: The request code is invalid.
185: .TP 15
186: [ESRCH]
187: The specified process does not exist.
188: .TP 15
189: [EIO]
190: The given signal number is invalid.
191: .TP 15
192: [EIO]
193: The specified address is out of bounds.
194: .TP 15
195: [EPERM]
196: The specified process cannot be traced.
197: .SH "SEE ALSO"
198: wait(2), sigvec(2), adb(1)
199: .SH BUGS
200: .I Ptrace
201: is unique and arcane; it should be replaced with a special file that
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
208: The request PT_TRACE_ME call should be able to specify
209: signals that are to be treated normally and not cause a stop.
210: In this way, for example,
211: programs with simulated floating point (which
212: use \*(lqillegal instruction\*(rq signals at a very high rate)
213: could be efficiently debugged.
214: .PP
215: The error indication, \-1, is a legitimate function value;
216: .I errno,
217: (see
218: .IR intro (2)),
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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.