879 lines
21 KiB
Groff
879 lines
21 KiB
Groff
.\" $NetBSD: ptrace.2,v 1.67 2017/06/03 19:41:14 abhinav Exp $
|
|
.\"
|
|
.\" This file is in the public domain.
|
|
.Dd April 7, 2017
|
|
.Dt PTRACE 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ptrace
|
|
.Nd process tracing and debugging
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/ptrace.h
|
|
.Ft int
|
|
.Fn ptrace "int request" "pid_t pid" "void *addr" "int data"
|
|
.Sh DESCRIPTION
|
|
.Fn ptrace
|
|
provides tracing and debugging facilities.
|
|
It allows one process (the
|
|
.Em tracing
|
|
process) to control another (the
|
|
.Em traced
|
|
process).
|
|
Most of the time, the traced process runs normally, but when
|
|
it receives a signal
|
|
.Po
|
|
see
|
|
.Xr sigaction 2
|
|
.Pc ,
|
|
it stops.
|
|
The tracing process is expected to notice this via
|
|
.Xr wait 2
|
|
or the delivery of a
|
|
.Dv SIGCHLD
|
|
signal
|
|
.Po
|
|
see
|
|
.Xr siginfo 2
|
|
.Pc ,
|
|
examine the state of the stopped process, and cause it to
|
|
terminate or continue as appropriate.
|
|
.Fn ptrace
|
|
is the mechanism by which all this happens.
|
|
.Pp
|
|
When a process that is traced by a debugger requests and calls
|
|
.Xr execve 2
|
|
or any of the routines built on it
|
|
.Po
|
|
such as
|
|
.Xr execv 3
|
|
.Pc ,
|
|
it will stop before executing the first instruction of the new image and emit
|
|
.Dv SIGTRAP
|
|
with
|
|
.Dv si_code
|
|
set to
|
|
.Dv TRAP_EXEC .
|
|
If a program is traced with the
|
|
.Dv PT_SYSCALL
|
|
option enabled,
|
|
this event notifier is disabled.
|
|
If a traced program calls
|
|
.Xr execve 2
|
|
any setuid or setgid bits on the executable being executed will be ignored.
|
|
.Pp
|
|
Program (software) breakpoints are reported with
|
|
.Dv SIGTRAP
|
|
and the
|
|
.Dv si_code
|
|
value set to
|
|
.Dv TRAP_BKPT .
|
|
These breakpoints are machine specific instructions that interrupt the process.
|
|
In order to put a trap by a tracer into the tracee's program,
|
|
debugger must violate the
|
|
.Dv PaX MPROTECT
|
|
restrictions.
|
|
For details check the
|
|
.Dv security.pax.mprotect.ptrace
|
|
option described in
|
|
.Xr sysctl 7 .
|
|
When a tracee is interrupted by a trap,
|
|
the trap is not removed by the kernel and it must be handled by a debugger.
|
|
.Pp
|
|
If a program is traced with single steps
|
|
.Dv ( PT_STEP )
|
|
it reports each step with
|
|
.Dv SIGTRAP
|
|
with
|
|
.Dv si_code
|
|
set to
|
|
.Dv TRAP_TRACE .
|
|
This event is not maskable
|
|
.Dv PT_SET_EVENT_MASK .
|
|
.Pp
|
|
Child program traps are reported with
|
|
.Dv SIGTRAP
|
|
and the
|
|
.Dv si_code
|
|
value set to
|
|
.Dv TRAP_CHLD .
|
|
These events are by default disabled and can be configured with
|
|
.Dv PT_SET_EVENT_MASK .
|
|
If this event occurs,
|
|
check with
|
|
.Dv PT_GET_PROCESS_STATE
|
|
the details of the process state associated with this event.
|
|
.Pp
|
|
Design choices for Debug Register accessors
|
|
.Bl -dash
|
|
.It
|
|
.Fn exec
|
|
.Dv ( TRAP_EXEC
|
|
event) must remove debug registers from LWP
|
|
.It
|
|
debug registers are only per-LWP, not per-process globally
|
|
.It
|
|
debug registers must not be inherited after (v)forking a process
|
|
.It
|
|
debug registers must not be inherited after forking a thread
|
|
.It
|
|
a debugger is responsible to set global watchpoints/breakpoints with the
|
|
debug registers,
|
|
to achieve this
|
|
.Dv PTRACE_LWP_CREATE
|
|
/
|
|
.Dv PTRACE_LWP_EXIT
|
|
event monitoring function is designed to be used
|
|
.It
|
|
debug register traps must generate
|
|
.Dv SIGTRAP with
|
|
.Dv si_code
|
|
.Dv TRAP_DBREG
|
|
.It
|
|
debugger is responsible to retrieve debug register state to distinguish
|
|
the exact debug register trap
|
|
.It
|
|
kernel must not remove debug register traps after triggering a trap event;
|
|
a debugger is responsible to detach this trap with appropriate
|
|
.Dv PT_SETDBREGS
|
|
call
|
|
.It
|
|
debug registers must not be exposed in mcontext
|
|
.It
|
|
userland must not be allowed to set a trap on the kernel
|
|
.El
|
|
.Pp
|
|
A debugger might reuse port specific symbols,
|
|
to help writing portable code as described in the port specific part of the
|
|
.In sys/ptrace.h
|
|
header.
|
|
Among these symbols,
|
|
there are:
|
|
.Bl -dash
|
|
.It
|
|
.Dv PTRACE_REG_PC
|
|
.It
|
|
.Dv PTRACE_REG_SET_PC
|
|
.It
|
|
.Dv PTRACE_REG_SP
|
|
.It
|
|
.Dv PTRACE_REG_INTRV
|
|
.It
|
|
.Dv PTRACE_BREAKPOINT
|
|
.It
|
|
.Dv PTRACE_BREAKPOINT_SIZE
|
|
.It
|
|
.Dv PTRACE_BREAKPOINT_ADJ
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa request
|
|
argument
|
|
of
|
|
.Nm
|
|
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
|
|
.Nm
|
|
calls are made by the tracing process, and the
|
|
.Fa pid
|
|
argument specifies the process ID of the traced process.
|
|
.Fa request
|
|
can be:
|
|
.Bl -tag -width 12n
|
|
.It Dv 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
|
|
.Fn ptrace .
|
|
.Pp
|
|
This call does not stop the process neither emit
|
|
.Dv SIGSTOP
|
|
to parent.
|
|
.It Dv PT_READ_I , Dv PT_READ_D
|
|
These requests read a single
|
|
.Li int
|
|
of data from the traced process' address space.
|
|
Traditionally,
|
|
.Fn ptrace
|
|
has allowed for machines with distinct address spaces for instruction
|
|
and data, which is why there are two requests: conceptually,
|
|
.Dv PT_READ_I
|
|
reads from the instruction space and
|
|
.Dv PT_READ_D
|
|
reads from the data space.
|
|
In the current
|
|
.Nx
|
|
implementation, these
|
|
two requests are completely identical.
|
|
The
|
|
.Fa addr
|
|
argument specifies the address (in the traced process' 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
|
|
.Eo \&
|
|
.Fn ptrace
|
|
.Ec .
|
|
.It Dv PT_WRITE_I , Dv PT_WRITE_D
|
|
These requests parallel
|
|
.Dv PT_READ_I
|
|
and
|
|
.Dv PT_READ_D ,
|
|
except that they write rather than read.
|
|
The
|
|
.Fa data
|
|
argument supplies the value to be written.
|
|
.It Dv PT_CONTINUE
|
|
The traced process continues execution.
|
|
.Fa addr
|
|
is an address specifying the place where execution is to be resumed (a
|
|
new value for the program counter), or
|
|
.Li (void *)1
|
|
to indicate that execution is to pick up where it left off.
|
|
.Fa data
|
|
provides a signal number to be delivered to the traced process as it
|
|
resumes execution, or 0 if no signal is to be sent.
|
|
If a negative value is supplied, that is the negative of the LWP
|
|
ID of the thread to be resumed, and only that thread executes.
|
|
.It Dv PT_KILL
|
|
The traced process terminates, as if
|
|
.Dv PT_CONTINUE
|
|
had been used with
|
|
.Dv SIGKILL
|
|
given as the signal to be delivered.
|
|
.It Dv 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.)
|
|
.Pp
|
|
The tracing process will see the newly-traced process stop and may then
|
|
control it as if it had been traced all along.
|
|
It means that the
|
|
.Dv SIGSTOP
|
|
signal is emitted to tracer.
|
|
It is different behavior to the one from
|
|
.Dv PT_TRACE_ME .
|
|
.Pp
|
|
Three other restrictions apply to all tracing processes, even those
|
|
running as root.
|
|
First, no process may trace a system process.
|
|
Second, no process may trace the process running
|
|
.Xr init 8 .
|
|
Third, if a process has its root directory set with
|
|
.Xr chroot 2 ,
|
|
it may not trace another process unless that process' root directory
|
|
is at or below the tracing process' root.
|
|
.It Dv PT_DETACH
|
|
This request is like PT_CONTINUE, except that after it
|
|
succeeds, the traced process is no longer traced and continues
|
|
execution normally.
|
|
.It Dv PT_IO
|
|
This request is a more general interface that can be used instead of
|
|
.Dv PT_READ_D ,
|
|
.Dv PT_WRITE_D ,
|
|
.Dv PT_READ_I ,
|
|
and
|
|
.Dv PT_WRITE_I .
|
|
The I/O request is encoded in a
|
|
.Dq Li "struct ptrace_io_desc"
|
|
defined as:
|
|
.Bd -literal -offset indent
|
|
struct ptrace_io_desc {
|
|
int piod_op;
|
|
void *piod_offs;
|
|
void *piod_addr;
|
|
size_t piod_len;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Fa piod_offs
|
|
is the offset within the traced process where the I/O operation should
|
|
take place,
|
|
.Fa piod_addr
|
|
is the buffer in the tracing process, and
|
|
.Fa piod_len
|
|
is the length of the I/O request.
|
|
The
|
|
.Fa piod_op
|
|
field specifies which type of I/O operation to perform.
|
|
Possible values are:
|
|
.Pp
|
|
.Bl -tag -width 18n -offset indent -compact
|
|
.It Dv PIOD_READ_D
|
|
.It Dv PIOD_WRITE_D
|
|
.It Dv PIOD_READ_I
|
|
.It Dv PIOD_WRITE_I
|
|
.It Dv PIOD_READ_AUXV
|
|
.El
|
|
.Pp
|
|
See the description of
|
|
.Dv PT_READ_I
|
|
for the difference between I and D spaces.
|
|
.Pp
|
|
The
|
|
.Dv PIOD_READ_AUXV
|
|
operation can be used to read from the ELF auxiliary vector.
|
|
The
|
|
.Fa piod_offs
|
|
argument sets the offset within the tracee's vector.
|
|
To read from the beginning of it, this value must be set to 0 and cast to
|
|
.Dv (void *) .
|
|
.Pp
|
|
A pointer to the I/O descriptor is passed in the
|
|
.Fa addr
|
|
argument to
|
|
.Fn ptrace .
|
|
On return, the
|
|
.Fa piod_len
|
|
field in the I/O descriptor will be updated with the actual number of
|
|
bytes transferred.
|
|
If the requested I/O could not be successfully performed,
|
|
.Fn ptrace
|
|
will return
|
|
.Li \-1
|
|
and set
|
|
.Va errno .
|
|
.It Dv PT_DUMPCORE
|
|
Makes the process specified in the
|
|
.Fa pid
|
|
pid generate a core dump.
|
|
The
|
|
.Fa addr
|
|
argument should contain the name of the core file to be generated
|
|
and the
|
|
.Fa data
|
|
argument should contain the length of the core filename.
|
|
.It Dv PT_LWPINFO
|
|
Returns information about a thread from the list of threads for the
|
|
process specified in the
|
|
.Fa pid
|
|
argument.
|
|
The
|
|
.Fa addr
|
|
argument should contain a
|
|
.Dq Li "struct ptrace_lwpinfo"
|
|
defined as:
|
|
.Bd -literal -offset indent
|
|
struct ptrace_lwpinfo {
|
|
lwpid_t pl_lwpid;
|
|
int pl_event;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Fa pl_lwpid
|
|
contains a thread LWP ID.
|
|
Information is returned for the thread following the one with the
|
|
specified ID in the process thread list, or for the first thread
|
|
if
|
|
.Fa pl_lwpid
|
|
is 0.
|
|
Upon return
|
|
.Fa pl_lwpid
|
|
contains the LWP ID of the thread that was found, or 0 if there is
|
|
no thread after the one whose LWP ID was supplied in the call.
|
|
.Fa pl_event
|
|
contains the event that stopped the thread.
|
|
Possible values are:
|
|
.Pp
|
|
.Bl -tag -width 30n -offset indent -compact
|
|
.It Dv PL_EVENT_NONE
|
|
.It Dv PL_EVENT_SIGNAL
|
|
.It Dv PL_EVENT_SUSPENDED
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa data
|
|
argument should contain
|
|
.Dq Li "sizeof(struct ptrace_lwpinfo)" .
|
|
.It Dv PT_SYSCALL
|
|
Stops a process before and after executing each system call.
|
|
Otherwise this operation is the same as
|
|
.Dv PT_CONTINUE .
|
|
.It Dv PT_SYSCALLEMU
|
|
Intercept and ignore a system call before it has been executed, for use with
|
|
.Dv PT_SYSCALL .
|
|
This operation shall be called for syscall entry trap from
|
|
.Dv PT_SYSCALL .
|
|
To resume execution after intercepting the system call,
|
|
another
|
|
.Dv PT_SYSCALL
|
|
shall be used.
|
|
.It Dv PT_SET_EVENT_MASK
|
|
This request can be used to specify which events in the traced process
|
|
should be reported to the tracing process.
|
|
These events are specified in a
|
|
.Dq Li "struct ptrace_event"
|
|
defined as:
|
|
.Bd -literal -offset indent
|
|
typedef struct ptrace_event {
|
|
int pe_set_event;
|
|
} ptrace_event_t;
|
|
.Ed
|
|
.Pp
|
|
.Fa pe_set_event
|
|
is the set of events to be reported.
|
|
This set is formed by OR'ing together the following values:
|
|
.Bl -tag -width 18n
|
|
.It PTRACE_FORK
|
|
Report
|
|
.Xr fork 2 .
|
|
.It PTRACE_VFORK
|
|
Report
|
|
.Xr vfork 2 .
|
|
.It PTRACE_VFORK_DONE
|
|
Report parent resumed after
|
|
.Xr vfork 2 .
|
|
.It PTRACE_LWP_CREATE
|
|
Report thread birth.
|
|
.It PTRACE_LWP_EXIT
|
|
Report thread termination.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Xr fork 2
|
|
and
|
|
.Xr vfork 2
|
|
events can occur with similar operations,
|
|
like
|
|
.Xr clone 2
|
|
or
|
|
.Xr posix_spawn 3 .
|
|
The
|
|
.Dv PTRACE_FORK
|
|
value means that process gives birth to its child
|
|
without pending on its termination or
|
|
.Xr execve 2
|
|
operation.
|
|
If enabled,
|
|
the child is also traced by the debugger and
|
|
.Dv SIGRAP
|
|
is generated twice,
|
|
first for the parent and second for the child.
|
|
The
|
|
.Dv PTRACE_VFORK
|
|
event is the same as
|
|
.Dv PTRACE_FORK ,
|
|
but the parent blocks after giving birth to the child.
|
|
The
|
|
.Dv PTRACE_VFORK_DONE
|
|
event can be used to report unblocking of the parent.
|
|
.Pp
|
|
A pointer to this structure is passed in
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument should be set to
|
|
.Li sizeof(struct ptrace_event) .
|
|
.It Dv PT_GET_EVENT_MASK
|
|
This request can be used to determine which events in the traced
|
|
process will be reported.
|
|
The information is read into the
|
|
.Dq Li struct ptrace_event
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument should be set to
|
|
.Li sizeof(struct ptrace_event) .
|
|
.It Dv PT_GET_PROCESS_STATE
|
|
This request reads the state information associated with the event
|
|
that stopped the traced process.
|
|
The information is reported in a
|
|
.Dq Li "struct ptrace_state"
|
|
defined as:
|
|
.Bd -literal -offset indent
|
|
typedef struct ptrace_state {
|
|
int pe_report_event;
|
|
pid_t pe_other_pid;
|
|
} ptrace_state_t;
|
|
.Ed
|
|
.Pp
|
|
A pointer to this structure is passed in
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument should be set to
|
|
.Li sizeof(struct ptrace_state) .
|
|
.It Dv PT_SET_SIGINFO
|
|
This request can be used to specify signal information emitted to tracee.
|
|
This signal information is specified in
|
|
.Dq Li "struct ptrace_siginfo"
|
|
defined as:
|
|
.Bd -literal -offset indentq
|
|
typedef struct ptrace_siginfo {
|
|
siginfo_t psi_siginfo;
|
|
lwpid_t psi_lwpid;
|
|
} ptrace_siginfo_t;
|
|
.Ed
|
|
.Pp
|
|
Where
|
|
.Fa psi_siginfo
|
|
is the set to signal information structure.
|
|
The
|
|
.Fa psi_lwpid
|
|
field describes LWP address of the signal.
|
|
Value
|
|
.Dv 0
|
|
means the whole process
|
|
(route signal to all LWPs).
|
|
.Pp
|
|
A pointer to this structure is passed in
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument should be set to
|
|
.Li sizeof(struct ptrace_siginfo) .
|
|
.Pp
|
|
In order to pass faked signal to the tracee,
|
|
the signal type must match the signal passed to the process with
|
|
.Dv PT_CONTINUE
|
|
or
|
|
.Dv PT_SYSCALL .
|
|
.It Dv PT_GET_SIGINFO
|
|
This request can be used to determine signal information that was received by
|
|
a debugger
|
|
.Po
|
|
see
|
|
.Xr siginfo 2
|
|
.Pc .
|
|
The information is read into the
|
|
.Dq Li struct ptrace_siginfo
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument should be set to
|
|
.Li sizeof(struct ptrace_siginfo) .
|
|
.It Dv PT_SET_SIGMASK
|
|
This request loads the traced process' signal mask from
|
|
.Dq Li "sigset_t"
|
|
(defined in
|
|
.In sys/sigtypes.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.It Dv PT_GET_SIGMASK
|
|
This request is the converse of
|
|
.Dv PT_SET_SIGMASK ;
|
|
it reads the traced process' signal mask into
|
|
.Dq Li "sigset_t"
|
|
(defined in
|
|
.In sys/sigtypes.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose mask is to be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_RESUME
|
|
Allow execution of a specified thread,
|
|
change its state from suspended to continued.
|
|
The
|
|
.Fa addr
|
|
argument is unused.
|
|
The
|
|
.Fa data
|
|
argument specifies the LWP ID.
|
|
.Pp
|
|
This call is equivalent to
|
|
.Xr _lwp_continue 2
|
|
called by a traced process.
|
|
This call does not change the general process state from stopped to continued.
|
|
.It Dv PT_SUSPEND
|
|
Prevent execution of a specified thread,
|
|
change its state from continued to suspended.
|
|
The
|
|
.Fa addr
|
|
argument is unused.
|
|
The
|
|
.Fa data
|
|
argument specifies the requested LWP ID.
|
|
.Pp
|
|
This call is equivalent to
|
|
.Xr _lwp_suspend 2
|
|
called by a traced process.
|
|
This call does not change the general process state from continued to stopped.
|
|
.El
|
|
.Pp
|
|
Additionally, the following requests exist but are
|
|
not available on all machine architectures.
|
|
The file
|
|
.In machine/ptrace.h
|
|
lists which requests exist on a given machine.
|
|
.Bl -tag -width 12n
|
|
.It Dv PT_STEP
|
|
Execution continues as in request PT_CONTINUE; however
|
|
as soon as possible after execution of at least one
|
|
instruction, execution stops again.
|
|
If the
|
|
.Fa data
|
|
argument is greater than 0, it contains the LWP ID of the thread to be
|
|
stepped, and any other threads are continued.
|
|
If the
|
|
.Fa data
|
|
argument is less than zero, it contains the negative of the LWP ID of
|
|
the thread to be stepped, and only that thread executes.
|
|
.It Dv PT_SETSTEP
|
|
This request will turn on single stepping of the specified process.
|
|
.It Dv PT_CLEARSTEP
|
|
This request will turn off single stepping of the specified process.
|
|
.It Dv PT_GETREGS
|
|
This request reads the traced process' machine registers into the
|
|
.Dq Li "struct reg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_SETREGS
|
|
This request is the converse of
|
|
.Dv PT_GETREGS ;
|
|
it loads the traced process' machine registers from the
|
|
.Dq Li "struct reg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.It Dv PT_GETFPREGS
|
|
This request reads the traced process' floating-point registers into
|
|
the
|
|
.Dq Li "struct fpreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_SETFPREGS
|
|
This request is the converse of
|
|
.Dv PT_GETFPREGS ;
|
|
it loads the traced process' floating-point registers from the
|
|
.Dq Li "struct fpreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.It Dv PT_GETDBREGS
|
|
This request reads the traced process' debug registers into
|
|
the
|
|
.Dq Li "struct dbreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_SETDBREGS
|
|
This request is the converse of
|
|
.Dv PT_GETDBREGS ;
|
|
it loads the traced process' debug registers from the
|
|
.Dq Li "struct dbreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.It Dv PT_GETXMMREGS
|
|
This request reads the traced process' XMM registers into
|
|
the
|
|
.Dq Li "struct xmmregs"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_SETXMMREGS
|
|
This request is the converse of
|
|
.Dv PT_GETXMMREGS ;
|
|
it loads the traced process' XMM registers from the
|
|
.Dq Li "struct xmmregs"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.It Dv PT_GETVECREGS
|
|
This request reads the traced process' vector registers into
|
|
the
|
|
.Dq Li "struct vreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be read.
|
|
If zero is supplied, the first thread of the process is read.
|
|
.It Dv PT_SETVECREGS
|
|
This request is the converse of
|
|
.Dv PT_GETVECREGS ;
|
|
it loads the traced process' vector registers from the
|
|
.Dq Li "struct vreg"
|
|
(defined in
|
|
.In machine/reg.h )
|
|
pointed to by
|
|
.Fa addr .
|
|
The
|
|
.Fa data
|
|
argument contains the LWP ID of the thread whose registers are to
|
|
be written.
|
|
If zero is supplied, the first thread of the process is written.
|
|
.El
|
|
.Sh ERRORS
|
|
Some requests can cause
|
|
.Fn ptrace
|
|
to return
|
|
.Li \-1
|
|
as a non-error value; to disambiguate,
|
|
.Va errno
|
|
can be set to 0 before the call and checked afterwards.
|
|
The possible errors are:
|
|
.Bl -tag -width "[EINVAL]"
|
|
.It Bq Er EAGAIN
|
|
Process is currently exec'ing and cannot be traced.
|
|
.It Bq Er EBUSY
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Dv PT_ATTACH
|
|
was attempted on a process that was already being traced.
|
|
.It
|
|
A request attempted to manipulate a process that was being traced by
|
|
some process other than the one making the request.
|
|
.It
|
|
A request (other than
|
|
.Dv PT_ATTACH )
|
|
specified a process that wasn't stopped.
|
|
.El
|
|
.It Bq Er EDEADLK
|
|
An attempt to unstop a process with locked threads.
|
|
.It Bq Er EINVAL
|
|
.Bl -bullet -compact
|
|
.It
|
|
A process attempted to use
|
|
.Dv PT_ATTACH
|
|
on itself.
|
|
.It
|
|
The
|
|
.Fa request
|
|
was not a legal request on this machine architecture.
|
|
.It
|
|
The signal number (in
|
|
.Fa data )
|
|
to
|
|
.Dv PT_CONTINUE
|
|
was neither 0 nor a legal signal number.
|
|
.It
|
|
.Dv PT_GETREGS ,
|
|
.Dv PT_SETREGS ,
|
|
.Dv PT_GETFPREGS ,
|
|
or
|
|
.Dv PT_SETFPREGS
|
|
was attempted on a process with no valid register set.
|
|
(This is normally true only of system processes.)
|
|
.El
|
|
.It Bq Er EPERM
|
|
.Bl -bullet -compact
|
|
.It
|
|
A request (other than
|
|
.Dv PT_ATTACH )
|
|
attempted to manipulate a process that wasn't being traced at all.
|
|
.It
|
|
An attempt was made to use
|
|
.Dv PT_ATTACH
|
|
on a process in violation of the requirements listed under
|
|
.Dv PT_ATTACH
|
|
above.
|
|
.El
|
|
.It Bq Er ESRCH
|
|
No process having the specified process ID exists.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr sigaction 2 ,
|
|
.Xr signal 7
|
|
.Sh HISTORY
|
|
The
|
|
.Fn ptrace
|
|
function appeared in
|
|
.At v7 .
|
|
.Sh BUGS
|
|
On the SPARC, the PC is set to the provided PC value for
|
|
.Dv PT_CONTINUE
|
|
and similar calls,
|
|
but the NPC is set willy-nilly to 4 greater than the PC value.
|
|
Using
|
|
.Dv PT_GETREGS
|
|
and
|
|
.Dv PT_SETREGS
|
|
to modify the PC, passing
|
|
.Li (void *)1
|
|
to
|
|
.Eo \&
|
|
.Fn ptrace
|
|
.Ec ,
|
|
should be able to sidestep this.
|
|
.Pp
|
|
.Dv PTRACE_VFORK
|
|
is currently unimplemented and it will return
|
|
.Er ENOTSUP .
|
|
.Pp
|
|
.Dv PT_SET_SIGINFO ,
|
|
.Dv PT_RESUME
|
|
and
|
|
.Dv PT_SUSPEND
|
|
can change the image of process returned by
|
|
.Dv PT_LWPINFO .
|