ptrace(2)




NAME

     ptrace - allows a parent process to control the execution of
     a child process


SYNOPSIS

     #include <unistd.h>
     #include <sys/types.h>

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


DESCRIPTION

     The ptrace() function allows a parent process to control the
     execution  of  a  child  process. Its primary use is for the
     implementation of breakpoint debugging.  The  child  process
     behaves   normally   until   it  encounters  a  signal  (see
     signal(3HEAD)), at which time it enters a stopped state  and
     its  parent  is  notified via the wait(2) function. When the
     child is in the stopped state, its parent  can  examine  and
     modify its "core image" using ptrace(). Also, the parent can
     cause the child either to terminate or  continue,  with  the
     possibility of ignoring the signal that caused it to stop.

     The request argument determines the action to  be  taken  by
     ptrace() and is one of the following:

     0     This request must be issued by the child process if it
           is to be traced by its parent. It turns on the child's
           trace flag that stipulates that the  child  should  be
           left  in a stopped state on receipt of a signal rather
           than the state specified by func (see signal(3C)). The
           pid,  addr,  and  data  arguments  are  ignored, and a
           return value is not defined for this request. Peculiar
           results  ensue  if the parent does not expect to trace
           the child.

     The remainder of the requests can only be used by the parent
     process.  For  each, pid is the process ID of the child. The
     child must be in a stopped state before these  requests  are
     made.

     1, 2  With these requests, the word at location addr in  the
           address  space  of the child is returned to the parent
           process. If instruction and data space are  separated,
           request  1  returns a word from instruction space, and
           request 2 returns a word from data space. If  instruc-
           tion  and data space are not separated, either request
           1 or request 2 may be used  with  equal  results.  The
           data  argument  is ignored. These two requests fail if
           addr is not the start address of a word, in which case
           -1  is returned to the parent process and the parent's
           errno is set to EIO.

     3     With this request, the word at location  addr  in  the
           child's  user  area in the system's address space (see
           <sys/user.h>) is returned to the parent  process.  The
           data  argument  is ignored. This request fails if addr
           is not the start address of a word or is  outside  the
           user  area, in which case -1 is returned to the parent
           process and the parent's errno is set to EIO.

     4, 5  With these requests, the value given by the data argu-
           ment is written into the address space of the child at
           location addr.  If  instruction  and  data  space  are
           separated,  request  4  writes a word into instruction
           space, and request 5 writes a word into data space. If
           instruction  and  data space are not separated, either
           request 4 or request 5 may be used with equal results.
           On  success,  the value written into the address space
           of the child is returned  to  the  parent.  These  two
           requests  fail  if  addr is not the start address of a
           word. On failure -1 is returned to the parent  process
           and the parent's errno is set to EIO.

     6     With this request, a few entries in the  child's  user
           area  can  be written. data gives the value that is to
           be written and addr is the location of the entry.  The
           few entries that can be written are the general regis-
           ters and the condition codes of the  Processor  Status
           Word.

     7     This request causes the child to resume execution.  If
           the  data argument is 0, all pending signals including
           the one that caused the child  to  stop  are  canceled
           before it resumes execution. If the data argument is a
           valid signal number, the child resumes execution as if
           it  had  incurred  that  signal, and any other pending
           signals are canceled. The addr argument must be  equal
           to  1 for this request. On success, the  value of data
           is returned to the parent. This request fails if  data
           is not 0 or a valid signal number, in which case -1 is
           returned to the parent process and the parent's  errno
           is set to EIO.

     8     This request causes the child to  terminate  with  the
           same consequences as exit(2).

     9     This request sets  the  trace  bit  in  the  Processor
           Status  Word  of  the child and then executes the same
           steps as listed above for request  7.  The  trace  bit
           causes  an  interrupt  on  completion  of  one machine
           instruction. This effectively allows  single  stepping
           of the child.

     To forestall possible  fraud,  ptrace()  inhibits  the  set-
     user-ID facility on subsequent calls to one of the exec fam-
     ily of functions (see exec(2)). If a  traced  process  calls
     one  of  the  exec  functions, it stops before executing the
     first instruction of the new image showing signal SIGTRAP.


ERRORS

     The ptrace() function will fail if:

     EIO   The request argument is an illegal number.

     EPERM The effective user  of  the  calling  process  is  not
           super-user.

     ESRCH The pid argument identifies  a  child  that  does  not
           exist or has not executed a ptrace() call with request
           0.


USAGE

     The /proc debugging interfaces should  be  used  instead  of
     ptrace(),  which provides quite limited debugger support and
     is itself implemented using the /proc interfaces.  There  is
     no  actual  ptrace() system call in the kernel.  See proc(4)
     for descriptions of the /proc debugging interfaces.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     exec(2), exit(2), wait(2), signal(3C), signal(3HEAD), attri-
     butes(5)


Man(1) output converted with man2html