ptrace(2)							System Calls Manual							 ptrace(2)

Name
       ptrace - process trace

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

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

Description
       The  system  call  provides a means by which a process can control the execution of another 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.  A process being traced behaves normally until it encounters some sig-
       nal, whether internally generated, like "illegal instruction," or externally generated, like "interrupt."  For more information, see

       Upon encountering a signal, the traced process enters a stopped state and its tracing process is notified by means of If the traced process
       stops with a SIGTRAP, the process might have been stopped for a number of reasons.  Two status words addressable as registers in the traced
       process's uarea qualify SIGTRAPs: TRAPCAUSE, which contains the cause of the trap, and TRAPINFO, which contains extra information  concern-
       ing the trap.

       When  the  traced  process  is in the stopped state, its core image can be examined and modified using If desired, another request can then
       cause the traced process 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 that can be used by a child process.  The child process can declare that it is to be traced by its parent.
	   All other arguments are ignored.  Unexpected results occur if the parent process does not expect to trace the child process.

       1,2 The	word  in  the  traced 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, request 2 indicates D space.  The addr must be  4-byte  aligned.   The  traced  process  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 is a constant defined in ptrace.h.  This
	   space contains the registers and other information about the process; the constants correspond to fields in the user structure  in  the
	   system.

       4,5 The	given  data  is  written  at the word in the process's address space corresponding to addr, which must be 4-byte aligned.  The old
	   value at the address is returned.  If I and D space are separated, request 4 indicates I space, request 5 indicates 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 reg-
	   isters, the floating point status and registers, and certain bits of the processor status word.   The  old  value  at  the  address	is
	   returned.

       7   The	data argument is taken as a signal number and the traced process's execution continues at location addr as if it had incurred that
	   signal.  Normally, the signal number is 0 to indicate that the signal causing the stop should be ignored. The signal  number  might	be
	   the value fetched out of the process's image, which identifies the signal that caused the stop.  If addr is (int *)1, execution contin-
	   ues 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.  TRAPCAUSE contains CAUSESINGLE.  This is part of the mechanism for implementing break-
	   points.

       20  This is the same as zero, except it is executed by the tracing process and the pid field is nonzero.  The process with that	pid  stops
	   and	becomes  a  traced  process.  On a signal, the traced process returns control to the tracing process, rather than the parent.  The
	   tracing process must have the same uid as the traced process.

       21,22
	   Returns MAXREG general or MAXFREG floating registers, respectively.	Their values are copied to the locations starting at  the  address
	   in the tracing process specified by the addr argument.

       24,25
	   Same as 20 and 21, but writes the registers instead of reading them.

       26  Specifies  a watchpoint in the data or stack segment of the traced process.	If any byte address starting at the addr argument and con-
	   tinuing for the number of bytes specified by the data argument is accessed in an instruction, the traced process stops execution with a
	   SIGTRAP.   TRAPCAUSE contains CAUSEWATCH, and TRAPINFO contains the address causing the trap.  This ptrace returns a watchpoint identi-
	   fier (wid).	MAXWIDS specifies the maximum number of watchpoints for each process.

       27  The data argument specifies a wid to delete.

       28  Turns off the tracing for the traced process with the specified pid.

       29  Returns an open file descriptor for the file attached to pid.  This request is useful in accessing the symbol table of a  process  cre-
	   ated with the call.

       As  indicated,  these  calls (except for request 0 and 20) 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. This value indicates that the
       process has stopped, rather than terminated.  If multiple processes are being traced, can be called multiple times, and it returns the sta-
       tus for the next stopped or terminated child or traced process.

       To forestall possible fraud, inhibits the set-user-id and set-group-id facilities on subsequent calls.  If a traced process calls it  stops
       before  executing  the  first instruction of the new image showing signal SIGTRAP.  In this case, TRAPCAUSE contains CAUSEEXEC and TRAPINFO
       does not contain anything interesting.  If a traced process calls again, the same thing occurs.

       If a traced process forks, both parent and child are traced.  Breakpoints from the parent are not copied into the child.  At  the  time	of
       the  fork,  the child is stopped with a SIGTRAP. The tracing process can then terminate the trace if desired.  TRAPCAUSE contains CAUSEFORK
       and TRAPINFO contains the pid of its parent.

Restrictions
       On an ULTRIX system, the system call succeeds only if the user owns the binary being traced or if the user is root.

       The request 0 call should be able to specify signals that are to be treated normally and not cause a stop.  In this way, for example,  pro-
       grams with simulated floating point, which use "illegal instruction" signals at a very high rate, can be efficiently debugged.

       The  error  indication,	-1,  is a legitimate function value; when an error occurs, the errno variable is set to explain the condition that
       caused the error.

       It should be possible to stop a process on occurrence of a system call; in this way, a completely controlled environment could be provided.

Return Values
       A 0 value is returned if the call succeeds.  If the call fails, a -1 is returned, and the global variable errno	is  set  to  indicate  the
       error.

Diagnostics
       The call fails under the following conditions:

       [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
       dbx(1), wait(2), sigvec(2)

								       RISC								 ptrace(2)