unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

PTRACE(2)                     System Calls Manual                    PTRACE(2)



NAME
       ptrace - process trace

SYNOPSIS
       #include <&lt;signal.h>&gt;
       #include <&lt;sys/ptrace.h>&gt;
       #include <&lt;sys/wait.h>&gt;

       ptrace(request, pid, addr, data [ , addr2 ] )
       enum ptracereq request;
       int pid;
       char *addr;
       int data;
       char *addr2;

DESCRIPTION
       ptrace()  provides a means by which a process may 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 five
       arguments whose interpretation depends on the request argument.  Gener-
       ally,  pid  is  the  process ID of the traced process.  A process being
       traced behaves normally until it encounters some signal whether  inter-
       nally generated like "illegal instruction" or externally generated like
       "interrupt".  See sigvec(2) for the  list.   Then  the  traced  process
       enters  a  stopped  state  and  the  tracing  process is notified using
       wait(2V).  When the traced process is in the stopped  state,  its  core
       image can be examined and modified using ptrace().  If desired, another
       ptrace() request can then cause the traced process either to  terminate
       or to continue, possibly ignoring the signal.

       Note:  several  different  values  of  the  request  argument  can make
       ptrace() return data values -- since -1 is a possibly legitimate value,
       to  differentiate  between  -1 as a legitimate value and -1 as an error
       code, you should clear the errno  global  error  code  before  doing  a
       ptrace() call, and then check the value of errno afterwards.

       The  value of the request argument determines the precise action of the
       call:

       PTRACE_TRACEME
              This request is the only one used  by  the  traced  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.

       PTRACE_PEEKTEXT
       PTRACE_PEEKDATA
              The  word  in  the  traced  process's  address  space at addr is
              returned.  If the instruction and data spaces are separate  (for
              example,  historically  on  a  PDP-11),  request PTRACE_PEEKTEXT
              indicates instruction space while PTRACE_PEEKDATA indicates data
              space.   Otherwise,  either  request  may  be  used,  with equal
              results; addr must be a multiple of 4 on a  Sun-4  system.   The
              child must be stopped.  The input data and addr2 are ignored.

       PTRACE_PEEKUSER
              The  word of the system's per-process data area corresponding to
              addr is returned.  addr must be a valid offset within  the  ker-
              nel's per-process data pages.  This space contains the registers
              and other information about the process; its layout  corresponds
              to the user structure in the system (see <&lt;sys/user.h>&gt;).

       PTRACE_POKETEXT
       PTRACE_POKEDATA
              The  given data are written at the word in the process's address
              space corresponding to addr.  addr must be a multiple of 4 on  a
              Sun-4  system.  No useful value is returned.  If the instruction
              and data spaces are separate, request PTRACE_PEEKTEXT  indicates
              instruction  space  while  PTRACE_PEEKDATA indicates data space.
              The PTRACE_POKETEXT  request  must  be  used  to  write  into  a
              process's text space even if the instruction and data spaces are
              not separate.

       PTRACE_POKEUSER
              The process's system data  are  written,  as  it  is  read  with
              request PTRACE_PEEKUSER.  Only a few locations can be written in
              this way: the general registers, the floating point  and  status
              registers, and certain bits of the processor status word.

       PTRACE_CONT
              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.  addr must be a multiple of 4 on a Sun-4
              system.

       PTRACE_KILL
              The traced process terminates, with  the  same  consequences  as
              exit(2V).

       PTRACE_SINGLESTEP
              Execution  continues as in request PTRACE_CONT; however, as soon
              as possible after execution of at least one instruction,  execu-
              tion  stops  again.  The signal number from the stop is SIGTRAP.
              On Sun-3 and Sun386i systems, the status register T-bit is  used
              and just one instruction is executed.  This is part of the mech-
              anism for implementing breakpoints.  On a Sun-4 system this will
              return  an error since there is no hardware assist for this fea-
              ture.  Instead, the user should insert breakpoint traps  in  the
              debugged program with PTRACE_POKETEXT.

       PTRACE_ATTACH
              Attach  to  the process identified by the pid argument and begin
              tracing it.  PTRACE_ATTACH  causes  a  SIGSTOP  to  be  sent  to
              process  pid.   Process  pid  does not have to be a child of the
              requestor, but  the  requestor  must  have  permission  to  send
              process  pid a signal and the effective user IDs of the request-
              ing process and process pid must match.

       PTRACE_DETACH
              Detach the process being traced.  Process pid is no longer being
              traced  and continues its execution.  The data argument is taken
              as a signal number and the process continues at location addr as
              if it had incurred that signal.

       PTRACE_GETREGS
              The  traced  process's  registers  are  returned  in a structure
              pointed to by the addr argument.  The registers include the gen-
              eral purpose registers, the program counter and the program sta-
              tus word.  The ``regs''  structure  defined  in  <&lt;machine/reg.h>&gt;
              describes the data that are returned.

       PTRACE_SETREGS
              The  traced  process's  registers  are  written from a structure
              pointed to by the addr argument.  The registers include the gen-
              eral purpose registers, the program counter and the program sta-
              tus word.  The ``regs'' structure defined in reg.h describes the
              data that are set.

       PTRACE_GETFPREGS
              (Sun-3, Sun-4 and Sun386i systems only) The traced process's FPP
              status is returned in a structure pointed to by the  addr  argu-
              ment.   The status includes the 68881 (80387 on Sun386i systems)
              floating point registers and the control, status,  and  instruc-
              tion  address registers.  The ``fp_status'' structure defined in
              reg.  describes the data that are returned.  The fp_state struc-
              ture  defined  in  <&lt;machine/fp.h>&gt;  describes  the  data that are
              returned on a Sun386i system.

       PTRACE_SETFPREGS
              (Sun-3, Sun-4 and Sun386i systems only) The traced process's FPP
              status  is written from a structure pointed to by the addr argu-
              ment.  The status includes the FPP floating point registers  and
              the  control,  status,  and  instruction address registers.  The
              ``fp_status'' structure defined in reg.h describes the data that
              are  set.   The ``fp_state'' structure defined in fp.h describes
              the data that are returned on a Sun386i system.

       PTRACE_GETFPAREGS
              (a Sun-3 system with FPA only) The traced process's  FPA  regis-
              ters  are  returned  in a structure pointed to by the addr argu-
              ment.  The ``fpa_regs'' structure defined in reg.h describes the
              data that are returned.

       PTRACE_SETFPAREGS
              (a  Sun-3  system with FPA only) The traced process's FPA regis-
              ters are written from a structure pointed to by the  addr  argu-
              ment.   The  "fpa_regs" structure defined in reg.h describes the
              data that are set.

       PTRACE_READTEXT
       PTRACE_READDATA
              Read data from the address space of the traced process.  If  the
              instruction  and  data spaces are separate, request PTRACE_READ-
              TEXT indicates instruction space while PTRACE_READDATA indicates
              data  space.  The addr argument is the address within the traced
              process from where the data are read, the data argument  is  the
              number  of  bytes to read, and the addr2 argument is the address
              within the requesting process where the data are written.

       PTRACE_WRITETEXT
       PTRACE_WRITEDATA
              Write data into the address space of the traced process.  If the
              instruction  and  data spaces are separate, request PTRACE_READ-
              TEXT indicates instruction space while PTRACE_READDATA indicates
              data  space.  The addr argument is the address within the traced
              process where the data are written, the  data  argument  is  the
              number  of bytes to write, and the addr2 argument is the address
              within the requesting process from where the data are read.

       PTRACE_SETWRBKPT
              (Sun386i systems only) Set a write breakpoint at  location  addr
              in  the  process  being traced.  Whenever a write is directed to
              this location a breakpoint will occur and a SIGTRAP signal  will
              be sent to the process.  The data argument specifies which debug
              register should be used for the address of  the  breakpoint  and
              must  be in the range 0 through 3, inclusive. The addr2 argument
              specifies the length of the operand in bytes, and must be one of
              1, 2, or 4.

       PTRACE_SETACBKPT
              (Sun386i systems only) Set an access breakpoint at location addr
              in the process being traced.  When  location  addr  is  read  or
              written  a  breakpoint will occur and the process will be sent a
              SIGTRAP signal.  The data argument specifies which debug  regis-
              ter should be used for the address of the breakpoint and must be
              in the range 0 through 3, inclusive. The addr2  argument  speci-
              fies  the  length of the operand in bytes, and must be one of 1,
              2, or 4.

       PTRACE_CLRBKPT
              (Sun386i  systems  only)  Clears  all  break  points  set   with
              PTRACE_SETACBKPT or PTRACE_SETWRBKPT.

       PTRACE_SYSCALL
              Execution continues as in request PTRACE_CONT; until the process
              makes a system call.  The process receives a SIGTRAP signal  and
              stops.   At  this  point the arguments to the system call may be
              inspected   in   the   process   user   structure   using    the
              PTRACE_PEEKUSER request.  The system call number is available in
              place  of   the   8th   argument.    Continuing   with   another
              PTRACE_SYSCALL  will stop the process again at the completion of
              the system call.  At this point the result of  the  system  call
              and error value may be inspected in the process user structure.

       PTRACE_DUMPCORE
              Dumps a core image of the traced process to a file.  The name of
              the file is obtained from the addr argument.

       As  indicated,  these  calls  (except  for   requests   PTRACE_TRACEME,
       PTRACE_ATTACH  and  PTRACE_DETACH)  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 WSTOPPED to indicate a stop  rather  than  genuine
       termination.

       To  forestall  possible  fraud, ptrace() inhibits the setUID and setGID
       facilities on subsequent execve(2V) calls.  If a traced  process  calls
       execve(),  it  will  stop before executing the first instruction of the
       new image, showing signal SIGTRAP.

       On the Sun, "word" also means a 32-bit integer.

RETURN VALUES
       On success, the value returned by ptrace() depends on request  as  fol-
       lows:

              PTRACE_PEEKTEXT
              PTRACE_PEEKDATA          The   word   in  the  traced  process's
                                       address space at addr.

              PTRACE_PEEKUSER          The word of  the  system's  per-process
                                       data area corresponding to addr.

       On  failure,  these  requests  return  -1 and set errno to indicate the
       error.

       For all other values of request, ptrace() returns:

       0      on success.

       -1     on failure and sets errno to indicate the error.

ERRORS
       EIO            The request code is invalid.

                      The given signal number is invalid.

                      The specified address is out of bounds.

       EPERM          The specified process cannot be traced.

       ESRCH          The specified process does not exist.

                      request requires process pid to be traced by the current
                      process and stopped, and process pid is not being traced
                      by the current process.

                      request requires process pid to be traced by the current
                      process and stopped, and process pid is not stopped.

SEE ALSO
       adb(1), intro(2), ioctl(2), sigvec(2), wait(2V)

BUGS
       ptrace()  is  unique  and  arcane; it should be replaced with a special
       file which 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 requests PTRACE_TRACEME through PTRACE_SINGLESTEP are standard UNIX
       system   ptrace()   requests.    The   requests  PTRACE_ATTACH  through
       PTRACE_DUMPCORE and the fifth argument, addr2, are unique to SunOS.

       The request PTRACE_TRACEME should be able to specify signals which  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 clarify what it means.



                                21 January 1990                      PTRACE(2)