ptrace

NAME

       ptrace - process trace

SYNOPSIS

       #include <sys/ptrace.h>

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

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 imple-
       mentation of breakpoint debugging.  A traced process  runs
       until  a signal occurs.  Then it stops and the parent will
       be notified 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
       function.

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

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

SEE ALSO

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