#include <sys/types.h>
#include <sys/ptrace.h> int
ptrace (int request pid_t pid caddr_t addr int data);
DESCRIPTION
The
ptrace ();
system call
provides tracing and debugging facilities.
It allows one process
(the
tracing
process)
to control another
(the
traced
process).
The tracing process must first attach to the traced process, and then
issue a series of
ptrace ();
system calls to control the execution of the process, as well as access
process memory and register state.
For the duration of the tracing session, the traced process will be
``re-parented''
with its parent process ID (and resulting behavior)
changed to the tracing process.
It is permissible for a tracing process to attach to more than one
other process at a time.
When the tracing process has completed its work, it must detach the
traced process; if a tracing process exits without first detaching all
processes it has attached, those processes will be killed.
Most of the time, the traced process runs normally, but when it
receives a signal
(see
sigaction(2)),
it stops.
The tracing process is expected to notice this via
wait(2)
or the delivery of a
SIGCHLD
signal, examine the state of the stopped process, and cause it to
terminate or continue as appropriate.
The signal may be a normal process signal, generated as a result of
traced process behavior, or use of the
kill(2)
system call; alternatively, it may be generated by the tracing facility
as a result of attaching, system calls, or stepping by the tracing
process.
The tracing process may choose to intercept the signal, using it to
observe process behavior (such as
SIGTRAP )
or forward the signal to the process if appropriate.
The
ptrace ();
system call
is the mechanism by which all this happens.
The
Fa request
argument specifies what operation is being performed; the meaning of
the rest of the arguments depends on the operation, but except for one
special case noted below, all
ptrace ();
calls are made by the tracing process, and the
Fa pid
argument specifies the process ID of the traced process.
The
Fa request
argument
can be:
PT_TRACE_ME
This request is the only one used by the traced process; it declares
that the process expects to be traced by its parent.
All the other arguments are ignored.
(If the parent process does not expect to trace the child, it will
probably be rather confused by the results; once the traced process
stops, it cannot be made to continue except via
ptrace (. ));
When a process has used this request and calls
execve(2)
or any of the routines built on it
(such as
execv(3)),
it will stop before executing the first instruction of the new image.
Also, any setuid or setgid bits on the executable being executed will
be ignored.
PT_READ_I , PT_READ_D
These requests read a single
Vt int
of data from the traced process's address space.
Traditionally,
ptrace ();
has allowed for machines with distinct address spaces for instruction
and data, which is why there are two requests: conceptually,
PT_READ_I
reads from the instruction space and
PT_READ_D
reads from the data space.
In the current
Fx implementation, these two requests are completely identical.
The
Fa addr
argument specifies the address
(in the traced process's virtual address space)
at which the read is to be done.
This address does not have to meet any alignment constraints.
The value read is returned as the return value from
ptrace (.);
PT_WRITE_I , PT_WRITE_D
These requests parallel
PT_READ_I
and
PT_READ_D
except that they write rather than read.
The
Fa data
argument supplies the value to be written.
PT_IO
This request allows reading and writing arbitrary amounts of data in
the traced process's address space.
The
Fa addr
argument specifies a pointer to a
Vt struct ptrace_io_desc ,
which is defined as follows:
struct ptrace_io_desc {
int piod_op; /* I/O operation */
void *piod_offs; /* child offset */
void *piod_addr; /* parent offset */
size_t piod_len; /* request length */
};
/*
* Operations in piod_op.
*/
#define PIOD_READ_D 1 /* Read from D space */
#define PIOD_WRITE_D 2 /* Write to D space */
#define PIOD_READ_I 3 /* Read from I space */
#define PIOD_WRITE_I 4 /* Write to I space */
The
Fa data
argument is ignored.
The actual number of bytes read or written is stored in
piod_len
upon return.
PT_CONTINUE
The traced process continues execution.
The
Fa addr
argument
is an address specifying the place where execution is to be resumed
(a new value for the program counter),
or
Po Vt caddr_t Pc Ns 1
to indicate that execution is to pick up where it left off.
The
Fa data
argument
provides a signal number to be delivered to the traced process as it
resumes execution, or 0 if no signal is to be sent.
PT_STEP
The traced process is single stepped one instruction.
The
Fa addr
argument
should be passed
Po Vt caddr_t Pc Ns 1 .
The
Fa data
argument
provides a signal number to be delivered to the traced process as it
resumes execution, or 0 if no signal is to be sent.
PT_KILL
The traced process terminates, as if
PT_CONTINUE
had been used with
SIGKILL
given as the signal to be delivered.
PT_ATTACH
This request allows a process to gain control of an otherwise
unrelated process and begin tracing it.
It does not need any cooperation from the to-be-traced process.
In
this case,
Fa pid
specifies the process ID of the to-be-traced process, and the other
two arguments are ignored.
This request requires that the target process must have the same real
UID as the tracing process, and that it must not be executing a setuid
or setgid executable.
(If the tracing process is running as root, these restrictions do not
apply.)
The tracing process will see the newly-traced process stop and may
then control it as if it had been traced all along.
PT_DETACH
This request is like PT_CONTINUE, except that it does not allow
specifying an alternate place to continue execution, and after it
succeeds, the traced process is no longer traced and continues
execution normally.
PT_GETREGS
This request reads the traced process's machine registers into the
Do Vt struct reg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_SETREGS
This request is the converse of
PT_GETREGS
it loads the traced process's machine registers from the
Do Vt struct reg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_GETFPREGS
This request reads the traced process's floating-point registers into
the
Do Vt struct fpreg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_SETFPREGS
This request is the converse of
PT_GETFPREGS
it loads the traced process's floating-point registers from the
Do Vt struct fpreg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_GETDBREGS
This request reads the traced process's debug registers into
the
Do Vt struct dbreg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_SETDBREGS
This request is the converse of
PT_GETDBREGS
it loads the traced process's debug registers from the
Do Vt struct dbreg
Dc (defined in
In machine/reg.h )
pointed to by
Fa addr .
PT_LWPINFO
This request can be used to obtain information about the kernel thread,
also known as light-weight process, that caused the traced process to stop.
The
Fa addr
argument specifies a pointer to a
Vt struct ptrace_lwpinfo ,
which is defined as follows:
The
Fa data
argument is to be set to the size of the structure known to the caller.
This allows the structure to grow without affecting older programs.
PT_GETNUMLWPS
This request returns the number of kernel threads associated with the
traced process.
PT_GETLWPLIST
This request can be used to get the current thread list.
A pointer to an array of type
Vt lwpid_t
should be passed in
Fa addr ,
with the array size specified by
Fa data .
The return value from
ptrace ();
is the count of array entries filled in.
Additionally, machine-specific requests can exist.
RETURN VALUES
Some requests can cause
ptrace ();
to return
-1
as a non-error value; to disambiguate,
errno
can be set to 0 before the call and checked afterwards.
ERRORS
The
ptrace ();
system call may fail if:
Bq Er ESRCH
No process having the specified process ID exists.
Bq Er EINVAL
A process attempted to use
PT_ATTACH
on itself.
The
Fa request
argument
was not one of the legal requests.
The signal number
(in
Fa data )
to
PT_CONTINUE
was neither 0 nor a legal signal number.
PT_GETREGSPT_SETREGSPT_GETFPREGSPT_SETFPREGSPT_GETDBREGS
or
PT_SETDBREGS
was attempted on a process with no valid register set.
(This is normally true only of system processes.)
Bq Er EBUSY
PT_ATTACH
was attempted on a process that was already being traced.
A request attempted to manipulate a process that was being traced by
some process other than the one making the request.
A request
(other than
PT_ATTACH
specified a process that was not stopped.
Bq Er EPERM
A request
(other than
PT_ATTACH
attempted to manipulate a process that was not being traced at all.
An attempt was made to use
PT_ATTACH
on a process in violation of the requirements listed under
PT_ATTACH
above.
