ptrace(2) CLIX ptrace(2)
NAME
ptrace - Process trace
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
int ptrace(
int request ,
int pid ,
int addr ,
int data );
PARAMETERS
request Specifies the precise action requested.
pid Specifies the process ID of the child process which is the
target of the request.
addr For certain requests, specifies an address in the child's user
or system address space.
data Specifies request-specific data.
DESCRIPTION
The ptrace() function 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 sdb function.) The
child process runs normally until it encounters a signal (see the signal()
function for the list), at which time it enters a stopped state and its
parent is notified with wait(). 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 parameter determines the precise 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, indicating that
the child should be left in a stopped state upon receipt of a signal
rather than the state specified by func. (See signal().) The pid,
addr,and data parameters are ignored, and a return value is not
defined for this request. Peculiar results will ensue if the parent
does not expect to trace the child.
2/94 - Intergraph Corporation 1
ptrace(2) CLIX ptrace(2)
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 (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 parameter is ignored. These two requests
fail if addr does not specify the start address of a word. In this
case, a value of -1 is returned to the parent process and the
parent's errno is set to EIO.
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 parameter is ignored. This request
fails if addr does not specify the start address of a word, or if
the address were outside the USER area. In this 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 parameter 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. These two
requests fail if addr is not the start address of a word. Upon
failure a value of -1 is returned to the parent process and the
parent's errno is set to EIO.
6 With this request, certain entries in the child's USER area can be
written. The data parameter 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
⊕ The condition codes of the Processor Status Word
7 This request causes the child to resume execution. If the data
parameter is 0, all pending signals including the one that caused
the child to stop are canceled before the child resumes execution.
If the data parameter 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 parameter 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
2 Intergraph Corporation - 2/94
ptrace(2) CLIX ptrace(2)
parent process and the parent's errno is set to EIO.
8 This request causes the child to terminate with the same
consequences as exit().
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 upon completion of one machine
instruction. This effectively allows single stepping of the child.
To forestall possible fraud, ptrace() restricts the set-user-ID facility
on subsequent exec() calls. If a traced process calls exec(), it will
stop before executing the first instruction of the new image showing
signal SIGTRAP.
EXAMPLES
1. For a child to indicate that it can be traced:
ptrace(0,0,0,0);
2. To write a value into location 0x3000 in a traced child's address
space:
if (ptrace(5, child_pid, 0x3000, value) == -1)
perror("ptrace store failed");
3. To cause a traced child to resume execution, ignoring any currently
outstanding signals:
if (ptrace(7, child_pid, 0, 1) == -1)
perror("ptrace resume failed");
NOTES
Much of the functionality provided by ptrace() is also available using the
/proc file system.
RETURN VALUES
Return values for ptrace() are request-specific.
ERRORS
The ptrace() function will in general fail if one or more of the following
are true:
[EIO] The request parameter is an illegal number.
2/94 - Intergraph Corporation 3
ptrace(2) CLIX ptrace(2)
[ESRCH] The pid identifies a child that does not exist or has not
executed a ptrace() with request 0.
RELATED INFORMATION
Commands: sdb(1)
Functions: exec(2), signal(2), wait(2)
Files: proc(7)
4 Intergraph Corporation - 2/94