ptrace(2) SYSTEM CALLS ptrace(2)
NAME
ptrace - process trace
SYNOPSIS
#include <unistd.h>
#include <sys/types.h>
int ptrace(int request, pidt pid, int addr, int 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 [see sdb(1)]. The child process
behaves normally until it encounters a signal [see sig-
nal(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 and is one of the following:
0 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 on receipt of a
signal rather than the state specified by func [see
signal(2)]. 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.
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.
1, 2 With these requests, 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 instruc-
tion 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.
1
ptrace(2) SYSTEM CALLS ptrace(2)
3 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 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.
4, 5 With these requests, 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 instruction 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 few entries that can be written
are the general registers and the condition codes
of the Processor Status Word.
7 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 sig-
nal, and any other pending signals are canceled.
The addr argument must be equal to 1 for this
request. On success, 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 pro-
cess and the parent's errno is set to EIO.
8 This request causes the child to terminate with
the same consequences as exit(2).
9 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 on completion of one
machine instruction. This effectively allows
2
ptrace(2) SYSTEM CALLS ptrace(2)
single stepping of the child.
To forestall possible fraud, ptrace inhibits the set-user-ID
facility on subsequent exec(2) calls. If a traced process
calls exec(2), it stops before executing the first instruc-
tion of the new image showing signal SIGTRAP. ptrace in
general fails if one or more of the following are true:
EIO request is an illegal number.
ESRCH pid identifies a child that does not exist or
has not executed a ptrace with request 0.
SEE ALSO
sdb(1), exec(2), signal(2), wait(2).
3