1 files changed, 24 insertions, 0 deletions

diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2
index 807f907fa737..8b61df3a2571 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