1ptrace(3C)               Standard C Library Functions               ptrace(3C)
2
3
4

NAME

6       ptrace  -  allows  a parent process to control the execution of a child
7       process
8

SYNOPSIS

10       #include <unistd.h>
11       #include <sys/types.h>
12
13       int ptrace(int request, pid_t pid, int addr, int data);
14
15

DESCRIPTION

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

ERRORS

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

USAGE

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

ATTRIBUTES

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

SEE ALSO

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)
Impressum