Proposed additions to the ptrace(2) manpage, take 2

[Chuck Ebbert <76306.1226@compuserve.com>]

This is a revised set of updates to the ptrace(2) manpage.

Comments?


DESCRIPTION
       PTRACE_GETSIGINFO (since Linux 2.3.99-pre6)
              Retrieve  information  about  the  signal  that caused the stop.
              Copies a siginfo_t from the child to location data in  the  par-
              ent.  (addr is ignored)

       PTRACE_SETSIGINFO (since Linux 2.3.99-pre6)
              Set signal information.  Copies a siginfo_t from  location  data
              in  the parent to the child.  This will only affect signals that
              would normally be delivered to the child and were caught by  the
              tracer.   It  may be difficult to tell these normal signals from
              synthetic ones generated by ptrace() itself.  (addr is ignored)

       PTRACE_SETOPTIONS (since Linux 2.4.6; see BUGS for caveats)
              Sets ptrace options from data in the  parent.   data  is  inter-
              preted  as a bitmask of options, which are specified by the fol-
              lowing flags (addr is ignored.)

              PTRACE_O_TRACESYSGOOD (since Linux 2.4.6)
                     When delivering syscall traps, set bit 7  in  the  signal
                     number (i.e. deliver (SIGTRAP | 0x80)  This makes it easy
                     for the tracer to  tell  the  difference  between  normal
                     traps and those caused by a syscall.  (PTRACE_O_TRACESYS-
                     GOOD may not work on all architectures.)

              PTRACE_O_TRACEFORK (since Linux 2.5.46)
                     Stop the child at the next fork()  call  with  SIGTRAP  |
                     PTRACE_EVENT_FORK  <<  8  and automatically start tracing
                     the  newly  forked  process,  which  will  start  with  a
                     SIGSTOP.   The  pid  for the new process can be retrieved
                     with PTRACE_GETEVENTMSG.

              PTRACE_O_TRACEVFORK (since Linux 2.5.46)
                     Stop the child at the next vfork() call  with  SIGTRAP  |
                     PTRACE_EVENT_VFORK  <<  8 and automatically start tracing
                     the the newly vforked process, which will  start  with  a
                     SIGSTOP.   The  pid  for the new process can be retrieved
                     with PTRACE_GETEVENTMSG.

              PTRACE_O_TRACECLONE (since Linux 2.5.46)
                     Stop the child at the next clone() call  with  SIGTRAP  |
                     PTRACE_EVENT_CLONE  <<  8 and automatically start tracing
                     the  newly  cloned  process,  which  will  start  with  a
                     SIGSTOP.   The  pid  for the new process can be retrieved
                     with  PTRACE_GETEVENTMSG.   This  option  may  not  catch
                     clone()  calls  in all cases.  If the child calls clone()
                     with the CLONE_VFORK  flag,  PTRACE_EVENT_VFORK  will  be
                     delivered  instead  if PTRACE_O_TRACEVFORK is set; other-
                     wise if the child calls clone() with the exit signal  set
                     to   SIGCHLD,  PTRACE_EVENT_FORK  will  be  delivered  if
                     PTRACE_O_TRACEFORK is set.

              PTRACE_O_TRACEEXEC (since Linux 2.5.46)
                     Stop the child at the next exec()  call  with  SIGTRAP  |
                     PTRACE_EVENT_EXEC << 8.

              PTRACE_O_TRACEVFORKDONE (since Linux 2.5.60)
                     Stop the child at the completion of the next vfork() call
                     with SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.

              PTRACE_O_TRACEEXIT (since Linux 2.5.60)
                     Stop the child at exit with SIGTRAP  |  PTRACE_EVENT_EXIT
                     <<  8.   The  child?s  exit  status can be retrieved with
                     PTRACE_GETEVENTMSG.  This stop will be done early  during
                     process exit when registers are still available, allowing
                     the tracer to see where the exit  occurred,  whereas  the
                     normal  exit  notification  is  done after the process is
                     finished exiting.  Even though context is available,  the
                     tracer  cannot  prevent  the  exit from happening at this
                     point.

       PTRACE_GETEVENTMSG (since Linux 2.5.46)
              Retrieve a message (as an unsigned long) about the ptrace  event
              that  just  happened,  to  the location data in the parent.  For
              PTRACE_EVENT_EXIT  this  is  the   child?s   exit   code.    For
              PTRACE_EVENT_FORK,   PTRACE_EVENT_VFORK  and  PTRACE_EVENT_CLONE
              this is the pid of the new process.  (addr is ignored.)

       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (since Linux 2.6.14)
              For  PTRACE_SYSEMU,  continue  and  stop  on  entry  to the next
              syscall, which will not  be  executed.   For  PTRACE_SYSEMU_SIN-
              GLESTEP, do the same but also singlestep if not a syscall.  This
              call is used by programs like User Mode Linux who want  to  emu-
              late  all  of  the  the  child?s  syscalls.   (addr and data are
              ignored; not supported on all architectures.)

BUGS
       On  hosts with 2.6 kernel headers, PTRACE_SETOPTIONS is declared with a
       different value than the one for 2.4. This leads to  applications  com-
       piled with such headers failing when run on 2.4 host kernels.

       This   can   be   worked  around  by  redefining  PTRACE_SETOPTIONS  to
       PTRACE_OLDSETOPTIONS, if that is defined.

ERRORS
       EINVAL An attempt was made to set an invalid option.


-- 
Chuck
"Penguins don't come from next door, they come from the Antarctic!"
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/