unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (v7man)
Page:
Section:
Apropos / Subsearch:
optional field

PTRACE(2)                     System Calls Manual                    PTRACE(2)



NAME
       ptrace  -  process trace

SYNOPSIS
       #include <signal.h>

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

DESCRIPTION
       Ptrace  provides a means by which a parent process may control the exe-
       cution 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 signal(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:

       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, request 1 indicates I space, 2 D
           space.  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.  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 system.

       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 PDP-11 the T-
           bit is used and just one instruction is executed; on the  Interdata
           the  stop  does  not  take  place until a store instruction is exe-
           cuted.)  This is part of  the  mechanism  for  implementing  break-
           points.

       As  indicated, these calls (except for request 0) 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 facility
       on subsequent exec(2) calls.  If a traced process calls exec,  it  will
       stop  before  executing  the first instruction of the new image showing
       signal SIGTRAP.

       On the Interdata 8/32, `word' means a 32-bit word and  `even'  means  0
       mod 4.

SEE ALSO
       wait(2), signal(2), adb(1)

DIAGNOSTICS
       The  value -1 is returned if request is invalid, pid is not a traceable
       process, addr is out of bounds, or data  specifies  an  illegal  signal
       number.

BUGS
       On the Interdata 8/32, `as soon as possible' (request 7) means `as soon
       as a store instruction has been executed.'

       The request 0 call should be able to specify signals which  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) 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.

ASSEMBLER
       (ptrace = 26.)
       (data in r0)
       sys ptrace; pid; addr; request
       (value in r0)



                                                                     PTRACE(2)