178 lines
6.8 KiB
Groff
178 lines
6.8 KiB
Groff
|
||
|
||
PTRACE(2) Minix Programmer's Manual PTRACE(2)
|
||
|
||
|
||
NAME
|
||
ptrace - process trace
|
||
|
||
SYNOPSIS
|
||
#include <sys/types.h>
|
||
#include <sys/signal.h>
|
||
#include <sys/ptrace.h>
|
||
|
||
int ptrace(int request, pid_t pid, long addr, long data)
|
||
|
||
DESCRIPTION
|
||
Note: This manual page has no relation to Minix. Someone who knows
|
||
ptrace() has to check, or rewrite, this page. (kjb)
|
||
|
||
Ptrace provides a means by which a parent process may control the
|
||
execution of a child process, and examine and change its core image. Its
|
||
primary use is for the implementation of breakpoint debugging. There are
|
||
four arguments whose interpretation depends on a request argument.
|
||
Generally, pid is the process ID of the traced process, which must be a
|
||
child (no more distant descendant) of the tracing process. A process
|
||
being traced behaves normally until it encounters some signal whether
|
||
internally generated like "illegal instruction" or externally generated
|
||
like "interrupt". See sigaction(2) for the list. Then the traced
|
||
process enters a stopped state and its parent is notified via wait(2).
|
||
When the child is in the stopped state, its core image can be examined
|
||
and modified using ptrace. If desired, another ptrace request can then
|
||
cause the child either to terminate or to continue, possibly ignoring the
|
||
signal.
|
||
|
||
The value of the request argument determines the precise action of the
|
||
call:
|
||
|
||
PT_TRACE_ME
|
||
This request is the only one used by the child process; it declares
|
||
that the process is to be traced by its parent. All the other
|
||
arguments are ignored. Peculiar results will ensue if the parent
|
||
does not expect to trace the child.
|
||
|
||
PT_READ_I, PT_READ_D
|
||
The word in the child process's address space at addr is returned.
|
||
If I and D space are separated (e.g. historically on a pdp-11),
|
||
request PT_READ_I indicates I space, PT_READ_D D space. Addr must be
|
||
even on some machines. The child must be stopped. The input data is
|
||
ignored.
|
||
|
||
PT_READ_U
|
||
The word of the system's per-process data area corresponding to addr
|
||
is returned. Addr must be even on some machines and less than 512.
|
||
This space contains the registers and other information about the
|
||
process; its layout corresponds to the user structure in the system.
|
||
|
||
|
||
4BSD May 23, 1986 1
|
||
|
||
|
||
|
||
PTRACE(2) Minix Programmer's Manual PTRACE(2)
|
||
|
||
|
||
PT_WRITE_I, PT_WRITE_D
|
||
The given data is written at the word in the process's address space
|
||
corresponding to addr, which must be even on some machines. No
|
||
useful value is returned. If I and D space are separated, request
|
||
PT_WRITE_I indicates I space, PT_WRITE_D D space. Attempts to write
|
||
in pure procedure fail if another process is executing the same file.
|
||
|
||
PT_WRITE_U
|
||
The process's system data is written, as it is read with request
|
||
PT_READ_U. Only a few locations can be written in this way: the
|
||
general registers, the floating point status and registers, and
|
||
certain bits of the processor status word.
|
||
|
||
PT_CONTINUE
|
||
The data argument is taken as a signal number and the child's
|
||
execution continues at location addr as if it had incurred that
|
||
signal. Normally the signal number will be either 0 to indicate that
|
||
the signal that caused the stop should be ignored, or that value
|
||
fetched out of the process's image indicating which signal caused the
|
||
stop. If addr is (int *)1 then execution continues from where it
|
||
stopped.
|
||
|
||
PT_KILL
|
||
The traced process terminates.
|
||
|
||
PT_STEP
|
||
Execution continues as in request PT_CONTINUE; however, as soon as
|
||
possible after execution of at least one instruction, execution stops
|
||
again. The signal number from the stop is SIGTRAP. (On the VAX-11
|
||
the T-bit is used and just one instruction is executed.) This is
|
||
part of the mechanism for implementing breakpoints.
|
||
|
||
As indicated, these calls (except for request PT_TRACE_ME) can be used
|
||
only when the subject process has stopped. The wait call is used to
|
||
determine when a process stops; in such a case the "termination" status
|
||
returned by wait has the value 0177 to indicate stoppage rather than
|
||
genuine termination.
|
||
|
||
To forestall possible fraud, ptrace inhibits the set-user-id and set-
|
||
group-id facilities on subsequent execve(2) calls. If a traced process
|
||
calls execve, it will stop before executing the first instruction of the
|
||
new image showing signal SIGTRAP.
|
||
|
||
On a VAX-11, "word" also means a 32-bit integer, but the "even"
|
||
restriction does not apply.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
4BSD May 23, 1986 2
|
||
|
||
|
||
|
||
PTRACE(2) Minix Programmer's Manual PTRACE(2)
|
||
|
||
|
||
RETURN VALUE
|
||
A 0 value is returned if the call succeeds. If the call fails then a -1
|
||
is returned and the global variable errno is set to indicate the error.
|
||
|
||
ERRORS
|
||
|
||
[EIO] The request code is invalid.
|
||
|
||
[ESRCH] The specified process does not exist.
|
||
|
||
[EIO] The given signal number is invalid.
|
||
|
||
[EIO] The specified address is out of bounds.
|
||
|
||
[EPERM] The specified process cannot be traced.
|
||
|
||
SEE ALSO
|
||
wait(2), sigaction(2), mdb(1).
|
||
|
||
BUGS
|
||
Ptrace is unique and arcane; it should be replaced with a special file
|
||
that can be opened and read and written. The control functions could
|
||
then be implemented with ioctl(2) calls on this file. This would be
|
||
simpler to understand and have much higher performance.
|
||
|
||
The request PT_TRACE_ME call should be able to specify signals that are
|
||
to be treated normally and not cause a stop. In this way, for example,
|
||
programs with simulated floating point (which use "illegal instruction"
|
||
signals at a very high rate) could be efficiently debugged.
|
||
|
||
The error indication, -1, is a legitimate function value; errno, (see
|
||
intro(2)), can be used to disambiguate.
|
||
|
||
It should be possible to stop a process on occurrence of a system call;
|
||
in this way a completely controlled environment could be provided.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
4BSD May 23, 1986 3
|
||
|