ptrace - process trace


SYNOPSIS

       #include <sys/ptrace.h>

       long  int ptrace(enum __ptrace_request request, pid_t pid,
       void * addr, void * data)


DESCRIPTION

       The ptrace system call provides a means by which a  parent
       process  may  observe and control the execution of another
       process, and examine and change its core image and  regis­
       ters.  It is primarily used to implement breakpoint debug­
       ging and system call tracing.

       The parent can initiate a trace  by  calling  fork(2)  and
       having  the  resulting child do a PTRACE_TRACEME, followed
       (typically) by an exec(2).  Alternatively, the parent  may
       commence trace of an existing process using PTRACE_ATTACH.

       While being traced, the child will stop each time a signal
       is  delivered,  even if the signal is being ignored.  (The
       exception is SIGKILL, which has its  usual  effect.)   The
       parent  will  be  notified  at  its  next  wait(2) and may
       inspect and modify the child process while it is  stopped.
       The  parent  then causes the child to continue, optionally
       ignoring the delivered signal (or even delivering  a  dif­
       ferent signal instead).

       When  the parent is finished tracing, it can terminate the
       child with PTRACE_KILL or cause it to  continue  executing
       in a normal, untraced mode via PTRACE_DETACH.

       The  value  of  request  determines  the action to be per­
       formed:

       PTRACE_TRACEME
              Indicates that this process is to be traced by  its
              parent.   Any  signal (except SIGKILL) delivered to
              this process will cause it to stop and  its  parent
              to  be  notified  via  wait.   Also, all subsequent
              calls to exec by this process will cause a  SIGTRAP
              to  be  sent  to  it, giving the parent a chance to
              gain control before the new program  begins  execu­
              tion.   A  process  probably  shouldn't  make  this
              request if its parent isn't expecting to trace  it.
              (pid, addr, and data are ignored.)

       The  above  request is used only by the child process; the
       rest are used  only  by  the  parent.   In  the  following
       requests,  pid specifies the child process to be acted on.
       For requests other than  PTRACE_KILL,  the  child  process
              Reads  a  word  at the location addr in the child's
              memory, returning the word as  the  result  of  the
              ptrace call.  Linux does not have separate text and
              data address spaces, so the two requests  are  cur­
              rently equivalent.  (data is ignored.)

       PTRACE_PEEKUSER
              Reads  a  word  at  offset addr in the child's USER
              area, which holds the registers and other  informa­
              tion  about  the  process  (see  <linux/user.h> and
              <sys/user.h>).  The word is returned as the  result
              of  the  ptrace call.  Typically the offset must be
              word-aligned, though this might vary  by  architec­
              ture.  (data is ignored.)

       PTRACE_POKETEXT, PTRACE_POKEDATA
              Copies  a  word  from location data in the parent's
              memory to location addr in the child's memory.   As
              above, the two requests are currently equivalent.

       PTRACE_POKEUSER
              Copies  a  word  from location data in the parent's
              memory to offset addr in the child's USER area.  As
              above,  the  offset must typically be word-aligned.
              In order to maintain the integrity of  the  kernel,
              some modifications to the USER area are disallowed.

       PTRACE_GETREGS, PTRACE_GETFPREGS
              Copies the child's  general  purpose  or  floating-
              point  registers, respectively, to location data in
              the parent.  See <linux/user.h> for information  on
              the format of this data.  (addr is ignored.)

       PTRACE_SETREGS, PTRACE_SETFPREGS
              Copies  the  child's  general  purpose or floating-
              point registers, respectively, from  location  data
              in  the  parent.  As for PTRACE_POKEUSER, some gen­
              eral purpose register modifications may  be  disal­
              lowed.  (addr is ignored.)

       PTRACE_CONT
              Restarts  the  stopped  child  process.  If data is
              non-zero and not SIGSTOP, it is  interpreted  as  a
              signal  to be delivered to the child; otherwise, no
              signal is delivered.  Thus, for example, the parent
              can  control  whether a signal sent to the child is
              delivered or not.  (addr is ignored.)

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
              Restarts the stopped child as for PTRACE_CONT,  but
              arranges  for  the  child to be stopped at the next
              entry to or exit from a system call, or after  exe­
              of  a  signal.)  From the parent's perspective, the
              child will appear to have been stopped  by  receipt
              of a SIGTRAP.  So, for PTRACE_SYSCALL, for example,
              the idea is to inspect the arguments to the  system
              call   at   the   first   stop,   then  do  another
              PTRACE_SYSCALL and inspect the return value of  the
              system call at the second stop.  (addr is ignored.)

       PTRACE_KILL
              Sends the child a SIGKILL to terminate  it.   (addr
              and data are ignored.)

       PTRACE_ATTACH
              Attaches to the process specified in pid, making it
              a traced "child" of the current process; the behav­
              ior   of   the  child  is  as  if  it  had  done  a
              PTRACE_TRACEME.   The  current   process   actually
              becomes  the  parent  of the child process for most
              purposes (e.g., it  will  receive  notification  of
              child  events  and  appears  in ps(1) output as the
              child's parent), but a getpid(2) by the child  will
              still  return  the pid of the original parent.  The
              child is sent a SIGSTOP, but will  not  necessarily
              have  stopped  by  the completion of this call; use
              wait to wait for the child to stop.  (addr and data
              are ignored.)

       PTRACE_DETACH
              Restarts  the stopped child as for PTRACE_CONT, but
              first detaches from the process, undoing the repar­
              enting  effect of PTRACE_ATTACH, and the effects of
              PTRACE_TRACEME.   Although  perhaps  not  intended,
              under  Linux a traced child can be detached in this
              way regardless of which method was used to initiate
              tracing.  (addr is ignored.)


NOTES

       Although  arguments to ptrace are interpreted according to
       the prototype given, GNU libc currently declares ptrace as
       a  variadic function with only the request argument fixed.
       This means that unneeded trailing arguments may  be  omit­
       ted,  though  doing  so  makes  use of undocumented gcc(1)
       behavior.

       init(8), the process with pid 1, may not be traced.

       The layout of the contents of memory and the USER area are
       quite OS- and architecture-specific.

       The  size  of  a  "word"  is  determined by the OS variant
       (e.g., for 32-bit Linux it's 32 bits, etc.).

       attached to with PTRACE_ATTACH, its original parent can no
       longer  receive  notification  via wait when it stops, and
       there is no way for the new parent to effectively simulate
       this notification.

       This  page  documents  the  way the ptrace call works cur­
       rently in Linux.  Its behavior differs noticeably on other
       flavors of Unix.  In any case, use of ptrace is highly OS-
       and architecture-specific.

       The  SunOS  man  page  describes  ptrace  as  "unique  and
       arcane",  which it is.  The proc-based debugging interface
       present in Solaris 2 implements a superset of ptrace func­
       tionality in a more powerful and uniform way.


RETURN VALUE

       On  success,  PTRACE_PEEK*  requests  return the requested
       data, while other requests return  zero.   On  error,  all
       requests  return  -1,  and  errno(3) is set appropriately.
       Since the value  returned  by  a  successful  PTRACE_PEEK*
       request  may be -1, the caller must check errno after such
       requests to determine whether or not an error occurred.


ERRORS

       EPERM  The specified process cannot be traced.  This could
              be  because the parent has insufficient privileges;
              non-root processes cannot trace processes that they
              cannot send signals to or those running setuid/set­
              gid programs, for obvious reasons.   Alternatively,
              the process may already be being traced, or be init
              (pid 1).

       ESRCH  The specified process does not  exist,  or  is  not
              currently  being  traced  by  the caller, or is not
              stopped (for requests that require that).

       EIO    request is invalid, or an attempt was made to  read
              from or write to an invalid area in the parent's or
              child's memory, or there was a word-alignment  vio­
              lation, or an invalid signal was specified during a
              restart request.

       EFAULT There was an attempt to read from or  write  to  an
              invalid  area  in  the  parent's or child's memory,
              probably because the area wasn't mapped or accessi­
              ble.   Unfortunately, under Linux, different varia­
              tions of this fault will return EIO or EFAULT  more
              or less arbitrarily.


CONFORMING TO

       SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3

       exec(3), wait(2), signal(2), fork(2), gdb(1), strace(1)