ptrace(2)ptrace(2)NAMEptrace - Trace the execution of a child process
SYNOPSIS
#include <sys/signal.h> #include <sys/ptrace.h>
int ptrace(
long int request,
long int process,
ulong_t *address,
ulong_t data );
PARAMETERS
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.
DESCRIPTION
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 con‐
tinue.
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 parame‐
ters 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 parame‐
ter. 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 align‐
ment 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 vari‐
able 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 loca‐
tion 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 sys‐
tem'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, execu‐
tion stops again as if the child process had received the SIG‐
TRAP 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.
ERRORS
If the ptrace() function fails, errno is set to one of the following
values: The location within the system's per-process 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 func‐
tion with the request parameter PT_TRACE_ME.
SEE ALSO
Functions: exec(2), sigaction(2), wait(2)ptrace(2)