1ptrace(3C) Standard C Library Functions ptrace(3C)
2
3
4
6 ptrace - allows a parent process to control the execution of a child
7 process
8
10 #include <unistd.h>
11 #include <sys/types.h>
12
13 int ptrace(int request, pid_t pid, int addr, int data);
14
15
17 The ptrace() function allows a parent process to control the execution
18 of a child process. Its primary use is for the implementation of break‐
19 point debugging. The child process behaves normally until it encounters
20 a signal (see signal.h(3HEAD)), at which time it enters a stopped state
21 and its parent is notified by the wait(3C) function. When the child is
22 in the stopped state, its parent can examine and modify its "core
23 image" using ptrace(). Also, the parent can cause the child either to
24 terminate or continue, with the possibility of ignoring the signal that
25 caused it to stop.
26
27
28 The request argument determines the action to be taken by ptrace() and
29 is one of the following:
30
31 0 This request must be issued by the child process if it is to be
32 traced by its parent. It turns on the child's trace flag that
33 stipulates that the child should be left in a stopped state on
34 receipt of a signal rather than the state specified by func (see
35 signal(3C)). The pid, addr, and data arguments are ignored, and a
36 return value is not defined for this request. Peculiar results
37 ensue if the parent does not expect to trace the child.
38
39
40
41 The remainder of the requests can only be used by the parent process.
42 For each, pid is the process ID of the child. The child must be in a
43 stopped state before these requests are made.
44
45 1, 2 With these requests, the word at location addr in the address
46 space of the child is returned to the parent process. If
47 instruction and data space are separated, request 1 returns a
48 word from instruction space, and request 2 returns a word from
49 data space. If instruction and data space are not separated,
50 either request 1 or request 2 may be used with equal results.
51 The data argument is ignored. These two requests fail if addr
52 is not the start address of a word, in which case −1 is
53 returned to the parent process and the parent's errno is set to
54 EIO.
55
56
57 3 With this request, the word at location addr in the child's
58 user area in the system's address space (see <sys/user.h>) is
59 returned to the parent process. The data argument is ignored.
60 This request fails if addr is not the start address of a word
61 or is outside the user area, in which case −1 is returned to
62 the parent process and the parent's errno is set to EIO.
63
64
65 4, 5 With these requests, the value given by the data argument is
66 written into the address space of the child at location addr.
67 If instruction and data space are separated, request 4 writes a
68 word into instruction space, and request 5 writes a word into
69 data space. If instruction and data space are not separated,
70 either request 4 or request 5 may be used with equal results.
71 On success, the value written into the address space of the
72 child is returned to the parent. These two requests fail if
73 addr is not the start address of a word. On failure −1 is
74 returned to the parent process and the parent's errno is set to
75 EIO.
76
77
78 6 With this request, a few entries in the child's user area can
79 be written. data gives the value that is to be written and addr
80 is the location of the entry. The few entries that can be writ‐
81 ten are the general registers and the condition codes of the
82 Processor Status Word.
83
84
85 7 This request causes the child to resume execution. If the data
86 argument is 0, all pending signals including the one that
87 caused the child to stop are canceled before it resumes execu‐
88 tion. If the data argument is a valid signal number, the child
89 resumes execution as if it had incurred that signal, and any
90 other pending signals are canceled. The addr argument must be
91 equal to 1 for this request. On success, the value of data is
92 returned to the parent. This request fails if data is not 0 or
93 a valid signal number, in which case −1 is returned to the par‐
94 ent process and the parent's errno is set to EIO.
95
96
97 8 This request causes the child to terminate with the same conse‐
98 quences as exit(2).
99
100
101 9 This request sets the trace bit in the Processor Status Word of
102 the child and then executes the same steps as listed above for
103 request 7. The trace bit causes an interrupt on completion of
104 one machine instruction. This effectively allows single step‐
105 ping of the child.
106
107
108
109 To forestall possible fraud, ptrace() inhibits the set-user-ID facility
110 on subsequent calls to one of the exec family of functions (see
111 exec(2)). If a traced process calls one of these functions, it stops
112 before executing the first instruction of the new image showing signal
113 SIGTRAP.
114
116 The ptrace() function will fail if:
117
118 EIO The request argument is an illegal number.
119
120
121 EPERM The calling process does not have appropriate privileges to
122 control the calling process. See proc(4).
123
124
125 ESRCH The pid argument identifies a child that does not exist or has
126 not executed a ptrace() call with request 0.
127
128
130 The ptrace() function is available only with the 32-bit version of
131 libc(3LIB). It is not available with the 64-bit version of this
132 library.
133
134
135 The /proc debugging interfaces should be used instead of ptrace(),
136 which provides quite limited debugger support and is itself implemented
137 using the /proc interfaces. There is no actual ptrace() system call in
138 the kernel. See proc(4) for descriptions of the /proc debugging inter‐
139 faces.
140
142 See attributes(5) for descriptions of the following attributes:
143
144
145
146
147 ┌─────────────────────────────┬─────────────────────────────┐
148 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
149 ├─────────────────────────────┼─────────────────────────────┤
150 │Interface Stability │Standard │
151 ├─────────────────────────────┼─────────────────────────────┤
152 │MT-Level │MT-Safe │
153 └─────────────────────────────┴─────────────────────────────┘
154
156 exec(2), exit(2), libc(3LIB), signal(3C), signal.h(3HEAD), wait(3C),
157 proc(4), attributes(5)
158
159
160
161SunOS 5.11 22 Mar 2004 ptrace(3C)