PTRACE(2)PTRACE(2)NAMEptrace - process trace
SYNOPSIS
#include <sys/types.h>
#include <sys/ptrace.h>
long ptrace(int req, pid_t pid, long addr, long data)
DESCRIPTION
The ptrace call provides a primitive means to trace (debug) another
process. A process can submit itself to tracing using a T_OK ptrace
request, or can be attached to by a tracer using a T_ATTACH request.
From that point on, whenever a signal is sent to the traced process,
the process will be stopped. Its tracer will be told about the signal
causing the stop, via wait(2). The tracer can then inspect the traced
process, and choose how to continue the process's execution and whether
to pass on the signal to it.
In the current model, the tracer will be notified of the signal before
any checks on ignore or block masks are made. A SIGKILL signal cannot
be intercepted by the tracer, and will always kill the traced process.
When the traced process performs a successful execve(2) call, it will
be stopped and a SIGTRAP will be generated for it. Set-uid and set-gid
bits on the new executable are ignored.
The req parameter specifies the process trace request. The interpreta‐
tion of the remaining parameters depends on the given request. For all
requests except T_OK, the pid parameter specifies process ID of the
target process. For all requests except T_OK and T_ATTACH, the process
must be stopped. The following requests are supported:
T_OK
Set the caller's parent to be its tracer. All other arguments are
ignored. This request is typically made by the child fork of a
debugger, before performing an execve(2) call.
T_GETINS, T_GETDATA
Retrieve a value from the given process's instruction and data area,
respectively, at the address given in addr.
T_SETINS, T_SETDATA
Set the value from the given process's instruction and data area,
respectively, at the address given in addr, to the value given in
data.
T_GETUSER
Retrieve the value at the zero-based offset given in addr from the
process's struct proc kernel structure, followed by, aligned on long
size boundary, its struct priv kernel structure.
T_SETUSER
Set some of the given process's registers at the beginning of its
struct proc kernel structure. The value in data will be written to
the zero-based offset given in addr from the process's struct proc
kernel structure.
T_RESUME
Resume execution of the process. A nonzero data argument will be
interpreted as a signal to pass to the process.
T_STEP
Single-step an instruction. A nonzero data argument will be inter‐
preted as a signal to pass to the process.
T_SYSCALL
Resume execution with system call tracing. When the traced process
makes a system call, a SIGTRAP signal will be generated. A subsequent
T_SYSCALL request will then cause a SIGTRAP signal to be generated
when the process leaves the system call. A nonzero data argument will
be interpreted as a signal to pass to the process.
T_EXIT
Terminate the traced process, with the exit code given in the data
argument. This call will return once the process has exited.
T_ATTACH
Attach to the given process. The process will be stopped with a
SIGSTOP signal.
T_DETACH
Detach from the given process. Any signals still pending for the
tracer are passed on directly to the process. A nonzero data argument
will be interpreted as an additional signal to pass to the process.
T_SETOPT
Set the given process's trace options to the bit combination of flags
given in the data argument.
T_GETRANGE
Get a range of values from the address space of the traced process.
The addr argument must be a pointer to a fully initialized struct
ptrace_range structure.
T_SETRANGE
Set a range of values in the address space of the traced process. The
addr argument must be a pointer to a fully initialized struct
ptrace_range structure.
The following option flags are currently supported for T_SETOPT:
TO_TRACEFORK
When the traced process performs a fork(2), automatically attach to
the new child as well. The child will be stopped with a SIGSTOP sig‐
nal right after forking.
TO_ALTEXEC
Send SIGSTOP instead of SIGTRAP upon a successful execve(2). This
allows the tracer to disambiguate between this case and other traps.
TO_NOEXEC
Do not send any signal upon a successful execve(2).
The default set of trace options when tracing is initiated with T_OK is
0. The default set of trace options after attaching with T_ATTACH is
TO_NOEXEC.
The T_GETRANGE and T_SETRANGE calls use the following structure:
struct ptrace_range {
int pr_space;
long pr_addr;
size_t pr_size;
void *pr_ptr;
};
The pr_space field specifies the address space from which to retrieve
or set the values. It must be set to either of the following values:
TS_INS Text space.
TS_DATA Data space.
The pr_addr field specifies the start address of the target area in the
traced process. The pr_size field specifies the number of bytes to
retrieve or set, and must be between 1 and LONG_MAX. The pr_ptr field
must point to a buffer in the calling process that is used to store the
retrieved values (for T_GETRANGE) or contains the values to set (for
T_SETRANGE).
All addresses specified for the T_GETINS, T_GETDATA, T_GETUSER requests
and their T_SET* counterparts must be aligned on long boundary. Simi‐
larly, only long sized values can be retrieved and set at a time.
RETURN VALUE
All but the T_GETINS, T_GETDATA, T_GETUSER requests return 0 upon suc‐
cessful completion. Otherwise, a value of -1 is returned and errno is
set to indicate the error.
The T_GETINS, T_GETDATA, T_GETUSER requests return the resulting data.
Here, -1 is a legitimate return value. To distinguish between this and
an error, clear errno before the ptrace call, and check whether it is
zero afterwards.
ERRORS
The functions will fail if any of the following errors occur:
EINVAL Invalid request, signal, space, or length given.
ESRCH The given process is not found, exiting, or not traced by the
caller.
EBUSY The given process is not stopped, or already being traced.
EFAULT The given address is invalid, inaccessible, or not properly
aligned.
EPERM Attaching is denied, because the caller equals the given
process, or the caller is not root and does not match the
given process's user or group ID, or the caller is not root
and the given process is a system process, or the caller is a
system process, or the given process may not be traced at
all.
LIMITATIONS
Signals are not ordered. Attaching to a process guarantees that a
SIGSTOP will arrive at the tracer, but it is not guaranteed that this
will be the first signal to arrive. The same goes for automatically
attached children of the traced process. Similarly, if the tracer wants
to detach from a running process, it will typically send a SIGSTOP
using kill(2) to the process to stop it, but there is no guarantee that
this will be the first signal to arrive.
Signals not caused by the process itself (e.g. those caused by kill(2))
will arrive at the tracer while the process is in stopped state, but
this does not imply that the process is in a stable state at that
point. The process may still have a system call pending, and this means
that registers and memory of the process may change almost arbitrarily
after the tracer has been told about the arrival of the current signal.
Implementers of debuggers are advised to make minimal assumptions about
the conditions of the process when an unexpected signal arrives.
It is not possible to use T_SYSCALL to get a trap upon leaving of a
system call, if T_SYSCALL was not used to get a trap upon entering that
system call. This is in fact helpful: after attaching to a process, the
first T_SYSCALL call will always cause a trap after entering the next
system call. As the only exception, T_SYSCALL on a fork(2) call of a
process with TO_TRACEFORK set, will result in two traps upon leaving:
one for the parent, and one for the child. The child's SIGSTOP signal
will always come before the SIGTRAP from its leaving the system call.
There is no way to reliably distinguish between real signals and sig‐
nals generated for the tracer.
For system stability reasons, the PM and VM servers cannot be traced.
SEE ALSOwait(2), kill(2), mdb(1)AUTHOR
Manual page written by David van Moolenbroek <dcvmoole@cs.vu.nl>
4th Berkeley Distribution September 27, 2009 PTRACE(2)
