ptrace(2)ptrace(2)Nameptrace - process trace
Syntax
#include <signal.h>
ptrace(request, pid, addr, data)
int request, pid, *addr, data;
Description
The system call 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 debug‐
ging. 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 for the
list. Then the traced process enters a stopped state and its parent is
notified via When the child is in the stopped state, its core image can
be examined and modified using If desired, another 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:
0 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.
1,2 The word in the child process's address space at addr is returned.
If I and D space are separated (for example, historically on a
pdp-11), request 1 indicates I space, 2 D space. The addr must be
even. The child must be stopped. The input data is ignored.
3 The word of the system's per-process data area corresponding to
addr is returned. The addr must be even and less than 512. This
space contains the registers and other information about the
process; its layout corresponds to the user structure in the sys‐
tem.
4,5 The given data is written at the word in the process's address
space corresponding to addr, which must be even. No useful value
is returned. If I and D space are separated, request 4 indicates I
space, 5 D space. Attempts to write in pure procedure fail if
another process is executing the same file.
6 The process's system data is written, as it is read with request 3.
Only a few locations can be written in this way: the general regis‐
ters, the floating point status and registers, and certain bits of
the processor status word.
7 The data argument is taken as a signal number and the child's exe‐
cution continues at location addr as if it had incurred that sig‐
nal. 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.
8 The traced process terminates.
9 Execution continues as in request 7; 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 0) can be used only when
the subject process has stopped. The call is used to determine when a
process stops; in such a case the “termination” status returned by has
the value 0177 to indicate stoppage rather than genuine termination.
To forestall possible fraud, inhibits the set-user-id and set-group-id
facilities on subsequent calls. If a traced process calls it will stop
before executing the first instruction of the new image showing signal
SIGTRAP.
On a VAX, “word” also means a 32-bit integer, but the “even” restric‐
tion does not apply.
Environment
When your program is compiled using the System V environment, requests
7 and 9 return the value of the data argument on success, errno is set
to ESRCH if the pid does not exist, EIO if the address is out of
bounds.
Return Values
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.
Restrictions
In ULTRIX, the system call will only succeed if the user owns the
binary being traced or if the user is root.
Diagnostics
[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 Alsoadb(1), sigvec(2), wait(2)
VAX ptrace(2)
