2.11BSD#431 - /usr/man/cat2/ptrace.0

PTRACE(2)	    UNIX Programmer's Manual		PTRACE(2)


NAME
     ptrace - process trace

SYNOPSIS
     #include <sys/signal.h>
     #include <sys/ptrace.h>

     ptrace(request, pid, addr, data)
     int request, pid, *addr, data;

DESCRIPTION
     Ptrace provides a means by which a parent process may con-
     trol the execution of a child process, and examine and
     change its core image.  Its primary use is for the implemen-
     tation of breakpoint debugging.  There are four arguments
     whose interpretation depends on a request argument.  Gen-
     erally, 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 "inter-
     rupt".  See sigvec(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. histori-
	 cally 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


Printed 11/26/99	  May 23, 1986				1


PTRACE(2)	    UNIX Programmer's Manual		PTRACE(2)


	 system.

     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 termina-
     tion.

     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 exe-
     cuting the first instruction of the new image showing signal
     SIGTRAP.


Printed 11/26/99	  May 23, 1986				2


PTRACE(2)	    UNIX Programmer's Manual		PTRACE(2)


     On a VAX-11, "word" also means a 32-bit integer, but the
     "even" restriction does not apply.

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), sigvec(2), adb(1)

NOTES  (PDP-11)
     On the PDP-11 the PT_WRITE_U request may also write the
     child process's current overlay number in the system data
     area; the T-bit is used to single step the processor and
     just one instruction is executed for the PT_STEP request; a
     "word" means a 16-bit integer, and the "even" restriction
     does apply.

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 sig-
     nals 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.


Printed 11/26/99	  May 23, 1986				3