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