ptrace: add an option to not kill debuggees on debugger exit

Requested by:	markj
Reviewed by:	jhb (previous version)
Tested by:	pho
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differrential revision:	https://reviews.freebsd.org/D30351

1 files changed, 26 insertions, 1 deletions

diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2
index 0135db98dc97..504891597dab 100644
--- a/lib/libc/sys/ptrace.2
+++ b/lib/libc/sys/ptrace.2
@@ -2,7 +2,7 @@
 .\"	$NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
 .\"
 .\" This file is in the public domain.
-.Dd May 4, 2021
+.Dd May 20, 2021
 .Dt PTRACE 2
 .Os
 .Sh NAME
@@ -99,6 +99,30 @@ will report a
 signal.
 All other additional signal stops use
 .Dv SIGTRAP .
+.Sh DETACH AND TERMINATION
+.Pp
+Normally, exiting tracing process should wait for all pending
+debugging events and then detach from all alive traced processes
+before exiting using
+.Dv PT_DETACH
+request.
+If tracing process exits without detaching, for instance due to abnormal
+termination, the destiny of the traced children processes is determined
+by the
+.Dv kern.kill_on_debugger_exit
+sysctl control.
+.Pp
+If the control is set to the default value 1, such traced processes
+are terminated.
+If set to zero, kernel implicitly detaches traced processes.
+Traced processes are un-stopped if needed, and then continue the execution
+without tracing.
+Kernel drops any
+.Dv SIGTRAP
+signals queued to the traced children, which could be either generated by
+not yet consumed debug events, or sent by other means, the later should
+not be done anyway.
+.Sh TRACING EVENTS
 .Pp
 Each traced process has a tracing event mask.
 An event in the traced process only reports a
@@ -216,6 +240,7 @@ includes only
 .Dv PTRACE_EXEC
 events.
 All other event flags are disabled.
+.Sh PTRACE REQUESTS
 .Pp
 The
 .Fa request