ptrace - Trace the execution of a child process
#include <sys/signal.h> #include <sys/ptrace.h>
int ptrace(
long int request,
long int process,
ulong_t *address,
ulong_t data );
Determines the action to be taken by the ptrace() function.
Specifies the process ID. Determined by the value
of the request parameter. Determined by the value of the
request parameter.
The ptrace() function permits a parent process to control
execution of a child process. It is primarily used by
utility programs to enable breakpoint debugging.
The child process behaves normally until it receives a
signal. When a signal is delivered, the child process is
stopped, and a SIGCHLD signal is sent to its parent. The
parent process can wait for the child process to stop
using the wait() function.
When the child process is stopped, its parent process can
use the ptrace() function to examine and modify the image
memory of the child process, to either terminate the child
process or permit it to continue.
As a security measure, the ptrace() function inhibits the
set-user ID facility when any subsequent exec function is
issued by the child process. When a traced process calls
one of the exec functions, it stops before executing the
first instruction of the new image as if it had received
the SIGTRAP signal.
The request parameter is set to one of the values in the
following list. Only the PT_TRACE_ME request can be issued
by child processes; the remaining requests can only be
used by the parent process. For each request, the process
parameter is the process ID of the child process. The
child process must be in a stopped state before the following
requests are made. This request sets the child
process trace flag. It must be issued by the child process
that is to be traced by its parent process. When the trace
flag is set, the child process is left in a stopped state
on receipt of a signal, and the action specified by the
sigaction() function is ignored. The process, address, and
data parameters are ignored, and the return value is not
defined for this request. Do not issue this request when
the parent process does not expect to trace the child process.
These requests return the address space data of the
child process at the location pointed to by the address
parameter. The PT_READ_I and PT_READ_D requests produce
equal results. The data parameter is ignored. These
requests fail when the value of the address parameter is
not in the address space of the child process or, on some
machines, when the address parameter is not properly
aligned. These errors return a value of -1, and the parent
process errno is set to [EIO]. This request returns
the variable of the system's per-process data area for the
child, specified by the address parameter. This area contains
the register values and other information about the
process. On some machines, the address parameter is subject
to alignment constraints. The data parameter is
ignored. This request fails when the value of the address
parameter is outside of the system's per-process data area
for the child. On failure, a value of -1 is returned and
the parent process errno is set to [EIO]. These requests
write the value of the data parameter into the address
space variable of the child process at the location
pointed to by the address parameter. On some machines,
where necessary, the PT_WRITE_I request synchronizes any
hardware caches, if present. In all other respects, the
PT_WRITE_I and PT_WRITE_D requests can be used with equal
results. On some machines, these requests return the previous
contents of the address space variable of the child
process, while on other machines no useful value is
returned with the exception of System V behavior. System V
behavior for libsys5 returns the value written, and for
libc behavior it returns zero (0) for success.
These requests fail when the address parameter
points to a location in a pure procedure space and
a copy cannot be made. These requests also fail
when the value of the address parameter is out of
range and on some machines, when the address parameter
is not properly aligned. On failure a value of
-1 is returned and the parent process errno is set
to [EIO]. This request writes the value of the
data parameter into the variable of the system's
per-process data area for the child, specified by
the address parameter. This area contains the register
values and other information about the process.
On some machines, the address parameter is
subject to alignment constraints. Not all locations
within the system's per-process data area for the
child may be written. This request fails when the
value of the address parameter is outside of the
system's per-process data area for the child. On
failure, a value of -1 is returned and the parent
process errno is set to indicate the error. This
request permits the child process to resume execution.
When the data parameter is zero (0), the signal
that caused the child process to stop is canceled
before the child process resumes execution.
When the data parameter has a valid signal value,
the child process resumes execution as though that
signal had been received. When the address parameter
is equal to 1, execution continues from where
it stopped. When the address parameter is not 1, it
is assumed to be the address at which the process
should resume execution.
System V behavior for libsys5 returns the value
written, and for libc behavior it returns zero (0)
for success. This request fails when the data
parameter is not zero (0) or a valid signal value.
On failure, a value of -1 is returned to the parent
process and the parent process errno is set to
[EIO]. This request terminates a child process as
if the child process called the exit() function.
This request permits execution to continue in the
same manner as PT_CONTINUE. However, as soon as
possible after the execution of at least one
instruction, execution stops again as if the child
process had received the SIGTRAP signal.
Note that for the Tru64 UNIX operating system, the
PT_STEP request parameter may cause the traced program
to execute an indefinite number of instructions
if the current instruction is a branch
instruction.
If the ptrace() function fails, errno is set to one of the
following values: The location within the system's perprocess
data area could not be modified. An invalid location
was used for the system's per-process data area or
the process parameter is out of range. One of the following
conditions applies: The request parameter does not
have one of the listed values, or is not valid for the
machine type on which the process is executing. The given
signal number is invalid. The addressed used is either
out of bounds or improperly aligned. The specified process
cannot be traced. The process parameter identifies a
child process that does not exist or that has not executed
this function with the request parameter PT_TRACE_ME.
Functions: exec(2), sigaction(2), wait(2)
ptrace(2)
[ Back ] |
