1.\" 2.\" Copyright (c) 2003 Joseph Koshy <jkoshy@FreeBSD.org> 3.\" Copyright (c) 2023 Olivier Certner <olce.freebsd@certner.fr> 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd August 18, 2023 30.Dt P_CANDEBUG 9 31.Os 32.Sh NAME 33.Nm p_candebug 34.Nd determine debuggability of a process 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/proc.h 38.Ft int 39.Fn p_candebug "struct thread *td" "struct proc *p" 40.Sh DESCRIPTION 41This function determines if a given process 42.Fa p 43is debuggable by some thread 44.Fa td . 45.Pp 46The following 47.Xr sysctl 8 48variables directly influence the behaviour of 49.Fn p_candebug : 50.Bl -tag -width indent 51.It Va security.bsd.unprivileged_proc_debug 52Must be set to a non-zero value to allow unprivileged processes 53access to the kernel's debug facilities. 54.It Va kern.securelevel 55Debugging of the init process is not allowed if this variable is 56.Li 1 57or greater. 58.El 59.Pp 60Other such variables indirectly influence it; see 61.Xr cr_bsd_visible 9 . 62.Sh RETURN VALUES 63The 64.Fn p_candebug 65function 66returns 67.Li 0 68if the process denoted by 69.Fa p 70is debuggable by thread 71.Fa td , 72or a non-zero error return value otherwise. 73.Sh ERRORS 74.Bl -tag -width Er 75.It Bq Er EPERM 76An unprivileged process attempted to debug another process but the system is 77configured to deny it 78.Po 79see 80.Xr sysctl 8 81variable 82.Va security.bsd.unprivileged_proc_debug 83above 84.Pc . 85.It Bq Er ESRCH 86Thread 87.Fa td 88has been jailed and the process to debug does not belong to the same jail or one 89of its sub-jails, as determined by 90.Xr prison_check 9 . 91.It Bq Er ESRCH 92.Xr cr_bsd_visible 9 93denied visibility according to the BSD security policies in force. 94.It Bq Er EPERM 95Thread 96.Fa td 97lacks superuser credentials and its (effective) group set is not a superset of 98process 99.Fa p Ns 's 100whole group set 101.Pq "including real, effective and saved group IDs" . 102.It Bq Er EPERM 103Thread 104.Fa td 105lacks superuser credentials and its (effective) user ID does not match all user 106IDs of process 107.Fa p . 108.It Bq Er EPERM 109Thread 110.Fa td 111lacks superuser credentials and process 112.Fa p 113is executing a set-user-ID or set-group-ID executable. 114.It Bq Er EPERM 115Process 116.Fa p 117denotes the initial process 118.Fn initproc 119and the 120.Xr sysctl 8 121variable 122.Va kern.securelevel 123is greater than zero. 124.It Bq Er EBUSY 125Process 126.Fa p 127is in the process of being 128.Fn exec Ns 'ed. 129.It Bq Er EPERM 130Process 131.Fa p 132denied debuggability 133.Po 134see 135.Xr procctl 2 , 136command 137.Dv PROC_TRACE_CTL 138.Pc . 139.El 140.Sh SEE ALSO 141.Xr prison_check 9 , 142.Xr mac 9 , 143.Xr cr_bsd_visible 9 , 144.Xr procctl 2 , 145.Xr p_cansee 9 146