Clarify the behavior of ptrace(2) a little bit: the tracing process

must first attach to the traced process.  If the tracing process
exits without detaching, the traced process will be killed rather
than continued.  For the duration of the tracing session, the traced
process is reparented to the tracing process (with resulting expected
behaviors).  It is permissible to trace more than one other process
at a time.  When using waitpid() to monitor the behavior of the traced
process, signals are intercepted: they may optionally then be
forwarded using ptrace().  Signals are generated normally by and for
the process, but also by the tracing facility (SIGTRAP).

Product of:	Suffering
Sponsored by:	DARPA, AFRL

1 files changed, 24 insertions, 0 deletions

diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2
index 807f907..8b61df3 100644
--- a/lib/libc/sys/ptrace.2
+++ b/lib/libc/sys/ptrace.2
@@ -28,6 +28,20 @@ to control another
 (the
 .Em traced
 process).
+The tracing process must first attach to the traced process, and then
+issue a series of
+.Fn ptrace
+system calls to control the execution of the process, as well as access
+process memory and register state.
+For the duration of the tracing session, the traced process will be
+"re-parented", with its parent process id (and resulting behavior)
+changed to the tracing process.
+It is permissible for a tracing process to attach to more than one
+other process at a time.
+When the tracing process has completed its work, it must detach the
+traced process; if a tracing process exits without first detaching all
+processes it has attached, those processes will be killed.
+.Pp
 Most of the time, the traced process runs normally, but when it
 receives a signal
 (see
@@ -39,6 +53,16 @@ or the delivery of a
 .Dv SIGCHLD
 signal, examine the state of the stopped process, and cause it to
 terminate or continue as appropriate.
+The signal may be a normal process signal, generated as a result of
+traced process behavior, or use of the
+.Xr kill 2
+system call; alternatively, it may be generated by the tracing facility
+as a result of attaching, system calls, or stepping by the tracing
+process.
+The tracing process may choose to intercept the signal, using it to
+observe process behavior (such as
+.Dv SIGTRAP ),
+or forward the signal to the process if appropriate.
 The
 .Fn ptrace
 system call