cc . . . -lc
# include <unistd.h>
int ptrace(int request, pid_t pid, int addr, int data);
The ptrace system call provides a means by which
a parent process may control the execution of a child
process. Its primary use is for the implementation of
breakpoint debugging (see
The child process behaves normally until it encounters a
for the list), at which time it enters a stopped state and
its parent is notified via
When the child is in the stopped state, its parent can
examine and modify its ``core image'' using
ptrace. Also, the parent can cause the child
either to terminate or continue, with the possibility of
ignoring the signal that caused it to stop. The data type
of the argument addr depends upon the particular
request given to ptrace.
The request argument determines the precise
action to be taken by ptrace and is one of the
The remainder of the requests can only be used by the
parent process. For each, pid is the process
ID of the child. The child must be in a stopped
state before these requests are made.
This request must be issued by the child process if it is
to be traced by its parent. It turns on the child's trace
flag that stipulates that the child should be left in a
stopped state upon receipt of a signal rather than the
state specified by func. See
The pid, addr, and data
arguments are ignored, and a return value is not defined
for this request. Peculiar results ensue if the parent
does not expect to trace the child.
To forestall possible fraud, ptrace inhibits the
set-user-ID facility on subsequent
calls. If a traced process calls exec, it stops
before executing the first instruction of the new image
showing signal SIGTRAP.
With these requests, the word at location addr in
the address space of the child is returned to the parent
process. If I and D space are separated, request
1 returns a word from I space, and request
2 returns a word from D space. If I and D space
are not separated, either request 1 or request
2 may be used with equal results. The
data argument is ignored.
With this request, the word at location addr in
the child's USER area in the system's address
space (see <sys/user.h>) is returned to the
parent process. The data argument is ignored.
This request fails if addr is outside the
USER area, in which case a value of -1 is
returned to the parent process and the parent's
errno is set to EIO.
With these requests, the value given by the data
argument is written into the address space of the child at
location addr. If I and D space are separated,
request 4 writes a word into I space, and request
5 writes a word into D space. If I and D space
are not separated, either request 4 or request
5 may be used with equal results. Upon
successful completion, the value written into the address
space of the child is returned to the parent.
With this request, a few entries in the child's
USER area can be written.
data gives the value that is to be written and
addr is the location of the entry.
The few entries that can be written are all registers.
On the 80386, the ptrace system call can be used
to modify the debug registers.
The 80386 debug registers are used to specify an address to
monitor in a user process. Any access to this location by
the user process delivers a SIGTRAP (see
to the user process and possibly restart the parent
The 80386 debug registers can be accessed by using the 3 or
6 options of the ptrace system call to read or
write a traced-process's u-area. The file
<sys/debugreg.h> should be included in the parent
process that wants to control the debug registers. This
header file defines bit masks that describe the
debug-registers in the
u_debugreg array in the
The debug registers numbered
[DR_FIRSTADDR] (%dr0) to
contain process addresses which are monitored according to
the instructions provided in
u.u_debugreg[DR_CONTROL] (%dr7). Only
the DR_LOCAL_ENABLE_MASK and the various
read/write and length bits in
u.u_debugreg[DR_CONTROL] can be set.
Setting DR_LOCAL_SLOWDOWN to slow down processing
is also highly recommended. The setting of all other bits
is undefined and should be set to zero to ensure
compatibility with future Intel processors.
In the process being debugged, these registers are
automatically loaded before entering user-mode (privilege
level 3) and cleared before entering the system for any
reason. In System V Release 3.2, if the location specified
by a debug-register is accessed during a system call,
core-dump, or interrupt service, no trap ensues.
This request causes the child to resume execution. If the
data argument is 0, all pending signals including
the one that caused the child to stop are canceled before
it resumes execution. If the data argument is a
valid signal number, the child resumes execution as if it
had incurred that signal, and any other pending signals are
canceled. The addr argument must be equal to 1
for this request. Upon successful completion, the value of
data is returned to the parent. This request
fails if data is not 0 or a valid signal number,
in which case a value of -1 is returned to the parent
process and the parent's errno is set to
This request causes the child to terminate with the same
This request sets the trace bit in the Processor Status
Word of the child and then executes the same steps as
listed above for request 7. The trace bit causes
an interrupt upon completion of one machine instruction.
This effectively allows single stepping of the child.
Attach to the process pid, and begin tracing it.
Process pid must have the same uid as the current
process, and it must not have executed a suid or sgid
program, nor may it be executing a file for which the
current process' UID did not have read permission
at the time of the exec. Process pid need not be
a child of the current process. Root may attach to any
Detach the process being traced. Process pid is
no longer traced, and continues executing. The same steps
as listed above for request 7 are performed.
The STRCFRK flag for the process pid is
set. This causes any child processes resulting from a
by the process pid to be controlled by the
current process. The child processes stops before
executing the return from the fork call. On a
multiprocessor it is possible for another process to
successfully ATTACH before the child is set up to
be traced by the parent's controller. In this case, the
other process remains the child's controller, and the
STRCFRK bit is ignored.
The process with process ID equal to
data is given control of the process
pid. The process with a process ID
equal to data must have the same UID as
the current process. The current process no longer
controls the process pid. The process with
process ID equal to data is sent a
The ptrace system call generally fails if the
child process is running under i286emul(CP) or
one or more of the following is true:
request is an illegal number.
For request 10, the process is already being traced. For request
0, the parent of the current process has a process ID
of 1, or the process is already traced, or, on a multiprocessor,
the parent process is exiting.
For request 10, the process has a different UID, the
process's GID is not in the group list of the current
process, the process is executing a setuid/setgid
program, or the process is executing a file for which it does not
have read permission. For request 13, the process data
has a different UID than the current process.
pid identifies a process that does not exist
or is not controlled by the current process,
or is in the process of terminating (on a multiprocessor).
ptrace is conformant with:
AT&T SVID Issue 2
\, but has been withdrawn from XPG3.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003