ptrace(2) ptrace(2)
NAME
ptrace - process trace
SYNOPSIS
#include <unistd.h>
#include <sys/types.h>
long ptrace(int request, pidt pid, long addr, long data);
DESCRIPTION
ptrace() allows a parent process to control the execution of a child
process. Its primary use is for the implementation of breakpoint
debugging. The child process behaves normally until it encounters a
signal [see signal(5)], at which time it enters a stopped state and
its parent is notified via the wait(2) system call. 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 request argument determines the action to be taken by ptrace().
The possible values of request are the following:
0 The child process requests that it is traced by its parent. This
turns on the child's trace flag that stipulates that the child
should be left in a stopped state on receipt of a signal rather
than the state specified by disp [see signal(2)]. The pid, addr,
and data arguments are ignored, and a result is not defined for
this request. Peculiar results ensue if the parent does not
expect to trace the child.
The remainder of the requests can only be used by the parent pro-
cess. For each, pid is the process ID of the child. The child
must be in a stopped state before these requests are made.
1, 2 The word at location addr in the address space of the child is
returned to the parent process. If instruction and data space are
separated, request 1 returns a word from instruction space, and
request 2 returns a word from data space. If instruction and data
space are not separated, either request 1 or request 2 may be
used with equal results. The data argument is ignored. These two
requests fail if addr is not the start address of a word, in
which case a value of -1 is returned to the parent process and
the parent's errno is set to EIO.
3 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 not the start address of a word or 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.
Page 1 Reliant UNIX 5.44 Printed 11/98
ptrace(2) ptrace(2)
4, 5 The value given by the data argument is written into the address
space of the child at location addr. If instruction and data
space are separated, request 4 writes a word into instruction
space, and request 5 writes a word into data space. If instruc-
tion and data space are not separated, either request 4 or
request 5 may be used with equal results. On success, the value
written into the address space of the child is returned to the
parent. These two requests fail if addr is not the start address
of a word. On failure a value of -1 is returned to the parent
process and the parent's errno is set to EIO.
6 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 entries can be the general regis-
ters and the condition codes of the Processor Status Word.
7 The child resumes execution. If the data argument is 0, all pend-
ing 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. On suc-
cess, 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 EIO.
8 The child is terminated, with the same consequences as exit(2).
9 The trace bit in the Processor Status Word of the child is set
and then the same steps are executed as listed above for request
7. The trace bit causes an interrupt on completion of one machine
instruction. This effectively allows single stepping of the
child.
To forestall possible fraud, ptrace() inhibits the set-user-ID facil-
ity on subsequent exec(2) calls. If a traced process calls exec(2), it
stops before executing the first instruction of the new image showing
signal SIGTRAP. ptrace() in general fails if one or more of the fol-
lowing are true:
EIO request is an illegal number.
ESRCH pid identifies a child that does not exist or has not exe-
cuted a ptrace() with request 0.
EPERM The invoking subject does not have the appropriate MAC privi-
leges.
SEE ALSO
exec(2), signal(2), wait(2), unistd(4), types(5).
Page 2 Reliant UNIX 5.44 Printed 11/98