PTRACE(2) BSD PTRACE(2)
NAME
ptrace - process trace
SYNOPSIS
#include <signal.h>
#include <sys/ptrace.h>
#include <sys/wait.h>
ptrace(request, pid, addr, data, addr2, data2)
int request;
int pid;
char *addr;
int data;
char *addr2;
int data2;
DESCRIPTION
ptrace provides a means by which a parent process can control the
execution of a child process and examine and change its core image. Its
primary use is for the implementation of breakpoint debugging.
A process being traced behaves normally until it encounters some signal,
whether internally generated like "illegal instruction" or externally
generated like "interrupt" (see sigvec(2)). The traced process then
enters a stopped state and its parent is notified by way of wait(2).
When the child is in the stopped state, its core image can be examined
and modified by using ptrace. If desired, another ptrace request can
then cause the child either to terminate or to continue, possibly
ignoring the signal.
request determines the interpretation of the remaining four arguments.
It can assume the following values:
0 = PTRACE_TRACEME
Make the child process a target for debugging by the parent process.
This request is the only one issued by the child process. The
target will alert the debugger of all faults that occur and any exec
operations. None of the target's children inherit target status.
All of the remaining arguments to ptrace will be ignored. Peculiar
results will ensue if the parent does not expect to trace the child.
1 = PTRACE_PEEKTEXT, 2 = PTRACE_PEEKDATA
Return the word at location addr in the address space of the child.
Under BSD, either PTRACE_PEEKTEXT or PTRACE_PEEKDATA can be used
with identical results. If addr is not the start address of a word,
a value of -1 is returned to the parent process and the parent's
errno is set to EIO.
3 = PTRACE_PEEKUSER
Return the word at offset addr into the child's USER area in the
system's address space (see <sys/user.h>) to the parent process.
(Only 32 bits can be read.) If addr is not the start address of a
word or is outside the USER area, a value of -1 is returned to the
parent process and the parent's errno is set to EIO.
This request is obsolete and will not be supported in the future.
4 = PTRACE_POKETEXT, 5 = PTRACE_POKEDATA
Write the value given by the data argument into the address space of
the child at location addr. Upon successful completion, the value
written into the address space of the child is returned to the
parent. If addr is a location in a pure procedure space and another
process is executing in that space, or if addr is not the start
address of a word, these requests will fail, a value of -1 will be
returned to the parent process, and the parent's errno will be set
to EIO.
6 = PTRACE_POKEUSER
Write one of the following entries, where data is a 32-bit value to
be written and addr is the location of the entry in the child's USER
area:
⊕ M68XXX processor registers (A0-A7, D0-D7)
⊕ The condition codes (bits 0-7) of the Processor Status Word
This request is obsolete and will not be supported in the future.
7 = PTRACE_CONT
Continue executing the child process. If the data argument is 0,
all pending signals (including the one that caused the child to
stop) are canceled before it resumes execution. If the data
argument is a valid signal number, the child resumes execution as if
it had incurred that signal and any other pending signals are
canceled. If addr is 1, execution will be resumed where it was.
Otherwise, execution is resumed at addr. Upon successful
completion, the value of data is returned to the parent. If data
is not 0 or a valid signal number, this request will fail, a value
of -1 will be returned to the parent process, and the parent's errno
will be set to EIO.
When the signal to be delivered is SIGAPOLLO, then the status code
to be delivered is taken from data2. If data2 is 0, the status code
delivered will be the one that caused the process to stop.
8 = PTRACE_KILL
Kill the child. This request has the same consequences as _exit
(see exit(2)).
9 = PTRACE_SINGLESTEP
Set the trace bit in the Processor Status Word of the child (bit 15
on M68XXX processors). ptrace then executes the same steps as
described above for PTRACE_CONT. The trace bit causes an interrupt
upon completion of one machine instruction. This effectively allows
single stepping of the child. The trace bit is turned off after
interrupt.
10 = PTRACE_ATTACH
Make the process identified by pid a target for debugging by the
current process. If the proposed target is already the target of
another debugger, the old relationship will be severed in favor of
the requested attach. The attach request does not change the target
notification event set or the target's inheritance set (see
PTRACE_SET_OPTIONS). If this is a new target/debugger relationship,
these sets will be empty.
11 = PTRACE_DETACH
Terminate the debugger/target relationship. The former target is
continued at location addr as if the signal contained in data was
delivered.
12 = PTRACE_GETREGS
Place a copy of the machine registers into the memory pointed to by
addr2.
13 = PTRACE_SETREGS
Load the target's registers from the memory location pointed to by
addr2.
14 = PTRACE_READTEXT, 15 = PTRACE_READDATA
Copy data bytes of data from the target's address space starting at
addr to the debugger's address space at addr2.
16 = PTRACE_WRITETEXT, 17 = PTRACE_WRITEDATA
Copy data bytes of data from the debugger's address space starting
at addr2 to the target's address space at addr.
18 = PTRACE_SET_OPTIONS
Set the options that govern a target's behavior and that of its
children. addr2 points to a structure of type ptrace_set.
19 = PTRACE_INQUIRE_OPTIONS
Read the option set governing the behavior of target pid. ptrace
writes the structure into the memory referenced by addr2.
/*
* Ptrace Events.
* Can be used in ptrace_set.events as a mask.
* ex. (1<<PTRACE_FORK)|(1<<PTRACE_EXEC)
*/
#define PTRACE_SIGNAL 0
#define PTRACE_FORK 1
#define PTRACE_EXEC 2
#define PTRACE_EXIT 4
#define PTRACE_LOAD 5
#define PTRACE_STEP_OUTSIDE 6
#define PTRACE_STEP_INSIDE 7
/* Flags for ptrace_set.inherit */
/* behavior to apply when a process execs */
#define PTRACE_COPY 0x0001
#define PTRACE_MAP 0x0002
#define PTRACE_OLDEXEC 0x0004
/* behavior to apply when a process forks */
#define PTRACE_INHERIT 0x0008
struct ptrace_set {
long signals;
char *range_start;
char *range_end;
unsigned char events;
unsigned char inherit;
};
The target process will alert the debugger process of the occurrence of
an event via wait(2). The structure of wait for this is as follows:
struct wait {
unsigned short w_pad:8;
unsighed short w_Stopevent:8;
unsigned short w_Stopsig:8;
unsigned short w_Stopped:8;
};
If w_Stopped is not equal to 0177 octal, then the target process has
exited. Otherwise, w_Stopevent contains the reason for the fault. The
events are described below:
PTRACE_SIGNAL
A BSD signal was received by the target program. The w_Stopsig
field contains the signal number. If this event is caught and
PTRACE_EXEC is not caught, then exec events will be handled
conventionally and the w_Stopsig will be SIGTRAP.
PTRACE_EXEC
This occurs before the first instruction of the exec'ed program is
executed. The program counter points to the first instruction. If
w_Stopsig is 0, then this is a normal exec. If it is a 1, then an
inprocess invoke occurred.
PTRACE_FORK
This event is of little use unless PTRACE_INHERIT has been set.
This signal is raised in the parent before the fork occurs. It is
raised in the child after the fork occurs. If w_Stopsig is 0, then
this is a normal fork. If it is 1, then it is a vfork. The
debugger can then clean up the child's address space and then detach
it (with PTRACE_DETACH) or start debugging the child.
PTRACE_EXIT
This event will be raised in the exit code after the stack has been
unwound, but before the address space is returned to BSD. This is
the only exit event raised for a program that has been invoked.
PTRACE_LOAD
This event will be raised whenever the pmlib's loader has loaded an
object. This allows for extensible streams to be easily debugged.
ERRORS
[EINVAL] The request code is invalid.
[EINVAL] The specified process does not exist.
[EINVAL] The given signal number is invalid.
[EFAULT] The specified address is out of bounds.
[EPERM] The specified process cannot be traced.
SEE ALSO
wait(2), sigvec(2)
DIAGNOSTICS
A successful call returns 0. A failed call returns -1 and sets errno as
indicated under "Errors."