p_candebug(9): cr_bsd_visible() impacts, misc fixes

Mention cr_bsd_visible(9).  Remove references to cr_canseeothergids(9)
and cr_canseeotheruids(9), as well as indirect references not
immediately useful.

Fix description of credentials checks to match reality.

Re-order errors to match code's check order.

Reviewed by:            bcr, pauamma_gundo.com
Sponsored by:           Kumacom SAS
Differential Revision:  https://reviews.freebsd.org/D40638

(cherry picked from commit eb94f24fab4b44f13ca045370d9fcf12ca8835f2)

Approved by:    markj (mentor)

1 files changed, 56 insertions, 47 deletions

diff --git a/share/man/man9/p_candebug.9 b/share/man/man9/p_candebug.9
index e80d313de55c..c824db974154 100644
--- a/share/man/man9/p_candebug.9
+++ b/share/man/man9/p_candebug.9
@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 2003 Joseph Koshy <jkoshy@FreeBSD.org>
+.\" Copyright (c) 2023 Olivier Certner <olce.freebsd@certner.fr>
 .\"
 .\" All rights reserved.
 .\"
@@ -25,7 +26,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 19, 2006
+.Dd August 18, 2023
 .Dt P_CANDEBUG 9
 .Os
 .Sh NAME
@@ -37,24 +38,27 @@
 .Ft int
 .Fn p_candebug "struct thread *td" "struct proc *p"
 .Sh DESCRIPTION
-This function can be used to determine if a given process
+This function determines if a given process
 .Fa p
-is debuggable by the thread
+is debuggable by some thread
 .Fa td .
-.Sh SYSCTL VARIABLES
+.Pp
 The following
 .Xr sysctl 8
 variables directly influence the behaviour of
 .Fn p_candebug :
 .Bl -tag -width indent
+.It Va security.bsd.unprivileged_proc_debug
+Must be set to a non-zero value to allow unprivileged processes
+access to the kernel's debug facilities.
 .It Va kern.securelevel
 Debugging of the init process is not allowed if this variable is
 .Li 1
 or greater.
-.It Va security.bsd.unprivileged_proc_debug
-Must be set to a non-zero value to allow unprivileged processes
-access to the kernel's debug facilities.
 .El
+.Pp
+Other such variables indirectly influence it; see
+.Xr cr_bsd_visible 9 .
 .Sh RETURN VALUES
 The
 .Fn p_candebug
@@ -68,35 +72,45 @@ is debuggable by thread
 or a non-zero error return value otherwise.
 .Sh ERRORS
 .Bl -tag -width Er
-.It Bq Er EACCESS
-The MAC subsystem denied debuggability.
-.It Bq Er EAGAIN
-Process
-.Fa p
-is in the process of being
-.Fn exec Ns 'ed.
 .It Bq Er EPERM
+An unprivileged process attempted to debug another process but the system is
+configured to deny it
+.Po
+see
+.Xr sysctl 8
+variable
+.Va security.bsd.unprivileged_proc_debug
+above
+.Pc .
+.It Bq Er ESRCH
 Thread
 .Fa td
-lacks super-user credentials and process
-.Fa p
-is executing a set-user-ID or set-group-ID executable.
+has been jailed and the process to debug does not belong to the same jail or one
+of its sub-jails, as determined by
+.Xr prison_check 9 .
+.It Bq Er ESRCH
+.Xr cr_bsd_visible 9
+denied visibility according to the BSD security policies in force.
 .It Bq Er EPERM
 Thread
 .Fa td
-lacks super-user credentials and process
+lacks superuser credentials and its (effective) group set is not a superset of
+process
 .Fa p Ns 's
-group set is not a subset of
-.Fa td Ns 's
-effective group set.
+whole group set
+.Pq "including real, effective and saved group IDs" .
 .It Bq Er EPERM
 Thread
 .Fa td
-lacks super-user credentials and process
-.Fa p Ns 's
-user IDs do not match thread
-.Fa td Ns 's
-effective user ID.
+lacks superuser credentials and its (effective) user ID does not match all user
+IDs of process
+.Fa p .
+.It Bq Er EPERM
+Thread
+.Fa td
+lacks superuser credentials and process
+.Fa p
+is executing a set-user-ID or set-group-ID executable.
 .It Bq Er EPERM
 Process
 .Fa p
@@ -107,30 +121,25 @@ and the
 variable
 .Va kern.securelevel
 is greater than zero.
-.It Bq Er ESRCH
+.It Bq Er EBUSY
 Process
 .Fa p
-is not visible to thread
-.Fa td
-as determined by
-.Xr cr_canseeotheruids 9
-or
-.Xr cr_canseeothergids 9 .
-.It Bq Er ESRCH
-Thread
-.Fa td
-has been jailed and process
+is in the process of being
+.Fn exec Ns 'ed.
+.It Bq Er EPERM
+Process
 .Fa p
-does not belong to the same jail as
-.Fa td .
-.It Bq Er ESRCH
-The MAC subsystem denied debuggability.
+denied debuggability
+.Po
+see
+.Xr procctl 2 ,
+command
+.Dv PROC_TRACE_CTL
+.Pc .
 .El
 .Sh SEE ALSO
-.Xr jail 2 ,
-.Xr sysctl 8 ,
-.Xr cr_canseeothergids 9 ,
-.Xr cr_canseeotheruids 9 ,
+.Xr prison_check 9 ,
 .Xr mac 9 ,
-.Xr p_cansee 9 ,
-.Xr prison_check 9
+.Xr cr_bsd_visible 9 ,
+.Xr procctl 2 ,
+.Xr p_cansee 9