NAME

     ptrace - process trace

SYNOPSIS

     #include <sys/ptrace.h>

     int ptrace(int request, int pid, int addr

DESCRIPTION

     Ptrace provides a means by which a parent process  may  con-
     trol  the  execution  of  a  child  process, and examine and
     change its core image.  Its primary use is for the implemen-
     tation of breakpoint debugging.  A traced process runs until
     a signal occurs.  Then it stops and the parent will be noti-
     fied  with  wait(2).   When  the  process  is in the stopped
     state, its memory can be read and written.  The  parent  can
     also  cause  the  child to continue execution, with optional
     ignoring the signal which caused stopping.

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

     PTRACE_TRACEME
          This process is to be traced by its parent.  The parent
          should be expecting to trace the child.

     PTRACE_PEEKTEXT, PTRACE_PEEKDATA
          Read word at location addr.

     PTRACE_PEEKUSR
          Read word at location addr in the USER area.

     PTRACE_POKETEXT, PTRACE_POKEDATA
          Write word at location addr.

     PTRACE_POKEUSR
          Write word at location addr in the USER area.

     PTRACE_SYSCALL, PTRACE_CONT
          Restart after signal.

     PTRACE_KILL
          Send the child a SIGKILL to make it exit.

     PTRACE_SINGLESTEP
          Set the trap flag for single stepping.

     PTRACE_ATTACH
          Attach to the process specified in pid.

     PTRACE_DETACH
          Detach a process that was previously attached.

NOTES

     init, the process with process ID 1, may not use this  func-
     tion.

RETURN VALUE

     On success, zero is returned.  On error, -1 is returned, and
     errno is set appropriately.

ERRORS

     EPERM   The  specified  process  (i.e.,  init),  cannot   be
             traced, or is already being traced.

     ESRCH   The specified process does not exist.

     EIO     Request is not valid.

CONFORMING TO

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

SEE ALSO

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