.TH PTRACE 2 .SH NAMEptrace  \-  process trace.SH SYNOPSIS#include <signal.h>.PP.B ptrace(request, pid, addr, data).br.B int *addr;.SH DESCRIPTION.I Ptraceprovides a means by which a parent processmay 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 interpretationdepends on a.I requestargument.Generally,.I pidis the process ID of the traced process,which must be a child (no more distant descendant)of the tracing process.A process being tracedbehaves normally until it encounters some signal whether internally generatedlike `illegal instruction' or externally generated like `interrupt.'See.IR signal (2)for the list.Then the traced process enters a stopped stateand its parent is notified via.IR  wait (2).When the child is in the stopped state,its core image can be examined and modifiedusing.IR ptrace .If desired, another.I ptracerequest can then cause the child either to terminateor to continue, possibly ignoring the signal..PPThe value of the.I requestargument determines the preciseaction of the call:.TP 40This 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 ensueif the parent does not expect to trace the child..TP 41,2Theword in the child process's address spaceat.I addris returned.If I and D space are separated, request 1 indicates I space,2 D space..I Addrmust be even.The child must be stopped.The input.I datais ignored..TP 43The wordof the system's per-process data area corresponding to.I addris returned..I Addrmust be even and less than 512.This space contains the registers and other information aboutthe process;its layout corresponds to the.I userstructure in the system..TP 44,5Thegiven.I datais written at the word in the process's address space corresponding to.I 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 procedurefail if another process is executing the same file..TP 46The 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 registers,the floating point status and registers,and certain bits of the processor status word..TP 47The.I dataargument is taken as a signal numberand the child's execution continuesat location.I addras if it had incurred that signal.Normally the signal number will beeither 0 to indicate that the signal that caused the stopshould be ignored,or that value fetched out of theprocess's image indicating which signal causedthe stop.If.I addris (int *)1 then execution continues from where it stopped..TP 48The traced process terminates..TP 49Execution 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 isSIGTRAP.(On the PDP-11 the T-bit is used and just one instructionis executed;on the Interdata the stop does not take placeuntil a store instruction is executed.)This is part of the mechanism for implementing breakpoints..PPAs indicated,these calls(except for request 0)can be used only when the subject process has stopped.The.I waitcall is used to determinewhen a process stops;in such a case the `termination' statusreturned by.I waithas the value 0177 to indicate stoppage ratherthan genuine termination..PPTo forestall possible fraud,.I ptraceinhibits the set-user-id facilityon subsequent.IR  exec (2)calls.If a traced process calls.I exec,it will stop before executing the first instruction of the new imageshowing signal SIGTRAP..PPOn the Interdata 8/32,`word' means a 32-bit word and `even' means 0 mod 4..SH "SEE ALSO"wait(2), signal(2), adb(1).SH DIAGNOSTICSThe value \-1 is returned if.I request is invalid,.I pidis not a traceable process,.I addris out of bounds,or.I dataspecifies an illegal signal number..SH BUGSOn the Interdata 8/32,`as soon as possible' (request 7)means `as soon as a store instruction has been executed.'.PPThe request 0 call should be able to specifysignals which are to be treated normally and not cause a stop.In this way, for example,programs with simulated floating point (whichuse `illegal instruction' signals at a very high rate)could be efficiently debugged..brThe error indication, \-1, is a legitimate function value;.I errno,see.IR intro (2),can be used to disambiguate..PPIt should be possible to stop a process on occurrence of a systemcall;in this way a completely controlled environment couldbe provided..SH ASSEMBLER(ptrace = 26.).br(data in r0).br.B sys ptrace; pid; addr; request.br(value in r0)