.\" Copyright (c) 2013 Hudson River Trading LLC
.\" Written by: John H. Baldwin <jhb@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Copyright (c) 2014 The FreeBSD Foundation
.\" Portions of this documentation were written by Konstantin Belousov
.\" under sponsorship from the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (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 December 4, 2024
.Dt PROCCTL 2
.Os
.Sh NAME
.Nm procctl
.Nd control processes
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/procctl.h
.Ft int
.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data"
.Sh DESCRIPTION
The
.Fn procctl
system call provides for control over processes.
The
.Fa idtype
and
.Fa id
arguments specify the set of processes to control.
If multiple processes match the identifier,
.Nm
will make a
.Dq best effort
to control as many of the selected processes as possible.
An error is only returned if no selected processes successfully complete
the request.
The following identifier types are supported:
.Bl -tag -width P_PGID
.It Dv P_PID
Control the process with the process ID
.Fa id .
.Fa id
zero is a shortcut for the calling process ID.
.It Dv P_PGID
Control processes belonging to the process group with the ID
.Fa id .
.El
.Pp
The control request to perform is specified by the
.Fa cmd
argument.
.Pp
All status changing requests
.Pq Dv *_CTL
require the caller to have the right to debug the target.
All status query requests
.Pq Dv *_STATUS
require the caller to have the right to observe the target.
.Pp
The following commands are supported:
.Bl -tag -width PROC_TRAPCAP_STATUS
.It Dv PROC_ASLR_CTL
Controls Address Space Layout Randomization (ASLR) in program
images created
by
.Xr execve 2
in the specified process or its descendants that do not either change
the control or modify it by other means.
The
.Fa data
parameter must point to an integer variable holding one of the following
values:
.Bl -tag -width Ds
.It Dv PROC_ASLR_FORCE_ENABLE
Request that ASLR is enabled after execution, even if it is disabled
system-wide.
.It Dv PROC_ASLR_FORCE_DISABLE
Request that ASLR is disabled after execution, even if it is enabled
system-wide.
.It Dv PROC_ASLR_NOFORCE
Use the system-wide configured policy for ASLR.
.El
.Pp
Note that the
.Xr elfctl 1
.Dq noaslr
flag takes precedence over this control.
Executing a binary with this flag set will never use ASLR.
Similarly, executing a set-user-ID or set-group-ID binary ignores this
control and only honors the
.Xr elfctl 1
flag and system-wide policy.
.It Dv PROC_ASLR_STATUS
Returns the current status of ASLR enablement for the target process.
The
.Fa data
parameter must point to an integer variable, where one of the
following values is written:
.Bl -tag -width Ds
.It Dv PROC_ASLR_FORCE_ENABLE
.It Dv PROC_ASLR_FORCE_DISABLE
.It Dv PROC_ASLR_NOFORCE
.El
.Pp
If the currently executed image in the process itself has ASLR enabled,
the
.Dv PROC_ASLR_ACTIVE
flag is or-ed with the value listed above.
.It Dv PROC_PROTMAX_CTL
Controls the maximum protection used for
.Xr mmap 2
requests in the target process that do not specify
an explicit maximum protection in the
.Fa prot
argument via
.Dv PROT_MAX .
The maximum protection limits the permissions a mapping can be assigned by
.Xr mprotect 2 .
If an explicit maximum protection is not provided,
the maximum protection for a new mapping is set to either
.Dv PROT_READ | PROT_WRITE | PROT_EXEC
.Pq RWX
or the protection specified in
.Fa prot .
Mappings created with
.Fa prot
set to
.Dv PROT_NONE
always use RWX maximum protection.
.Pp
The
.Fa data
parameter must point to an integer variable holding one of the following
values:
.Bl -tag -width Ds
.It Dv PROC_PROTMAX_FORCE_ENABLE
Use the permissions in
.Fa prot
as the implicit maximum protection,
even if RWX permissions are requested by the sysctl
.Va vm.imply_prot_max .
.It Dv PROC_PROTMAX_FORCE_DISABLE
Use RWX as the implicit maximum protection,
even if constrained permissions are requested by the sysctl
.Va vm.imply_prot_max .
.It Dv PROC_PROTMAX_NOFORCE
Use the system-wide configured policy for the implicit PROT_MAX control.
.El
.Pp
Note that the
.Xr elfctl 1
.Dq noprotmax
flag takes precedence over this control.
Executing a binary with this flag set will always use RWX as the implicit
maximum protection.
.It Dv PROC_PROTMAX_STATUS
Returns the current status of the implicit PROT_MAX control for the
target process.
The
.Fa data
parameter must point to an integer variable, where one of the
following values is written:
.Bl -tag -width Ds
.It Dv PROC_PROTMAX_FORCE_ENABLE
.It Dv PROC_PROTMAX_FORCE_DISABLE
.It Dv PROC_PROTMAX_NOFORCE
.El
.Pp
If the currently executed image in the process itself has the implicit PROT_MAX
control enabled, the
.Dv PROC_PROTMAX_ACTIVE
flag is or-ed with the value listed above.
.It Dv PROC_SPROTECT
Set process protection state.
This is used to mark a process as protected from being killed if the system
exhausts available memory and swap.
The
.Fa data
parameter must point to an integer containing an operation and zero or more
optional flags.
The following operations are supported:
.Bl -tag -width Ds
.It Dv PPROT_SET
Mark the selected processes as protected.
.It Dv PPROT_CLEAR
Clear the protected state of selected processes.
.El
.Pp
The following optional flags are supported:
.Bl -tag -width Ds
.It Dv PPROT_DESCEND
Apply the requested operation to all child processes of each selected process
in addition to each selected process.
.It Dv PPROT_INHERIT
When used with
.Dv PPROT_SET ,
mark all future child processes of each selected process as protected.
Future child processes will also mark all of their future child processes.
.El
.It Dv PROC_REAP_ACQUIRE
Enable orphaned process reaping for future children of the current process.
.Pp
If a parent process exits before one or more of its children processes,
the remaining children processes are orphaned.
When an orphaned process exits,
it is reparented to a reaper process that is responsible for harvesting
the terminated process via
.Xr wait 2 .
When this control is enabled,
the current process becomes the reaper process for future children and their
descendants.
Existing child processes continue to use the reaper assigned when the child
was created via
.Xr fork 2 .
If a reaper process exits,
all of the processes for whom it was the reaper are reassigned to the reaper
process's reaper.
.Pp
After system initialization,
.Xr init 8
is the default reaper.
.It Dv PROC_REAP_RELEASE
Disable orphaned process reaping for the current process.
.Pp
Any processes for whom the current process was the reaper are reassigned to
the current process's reaper.
.It Dv PROC_REAP_STATUS
Provides a consistent snapshot of information about the reaper
of the specified process,
or the process itself if it is a reaper.
The
.Fa data
argument must point to a
.Vt procctl_reaper_status
structure which is filled in by the system call on successful return.
.Bd -literal
struct procctl_reaper_status {
	u_int	rs_flags;
	u_int	rs_children;
	u_int	rs_descendants;
	pid_t	rs_reaper;
	pid_t	rs_pid;
};
.Ed
.Pp
The
.Fa rs_flags
may have the following flags returned:
.Bl -tag -width Ds
.It Dv REAPER_STATUS_OWNED
The specified process is a reaper.
When this flag is returned, the specified process
.Fa id ,
pid, identifies a reaper, otherwise the
.Fa rs_reaper
field of the structure is set to the pid of the reaper
for the specified process id.
.It Dv REAPER_STATUS_REALINIT
The specified process is the root of the reaper tree, i.e.,
.Xr init 8 .
.El
.Pp
The
.Fa rs_children
field returns the number of processes that can be reaped by the reaper that
are also children of the reaper.
It is possible to have a child whose reaper is not the specified process,
since the reaper for existing children is not changed by
.Dv PROC_REAP_ACQUIRE .
The
.Fa rs_descendants
field returns the total number of processes that can be reaped by the reaper.
The
.Fa rs_reaper
field returns the reaper's pid.
The
.Fa rs_pid
returns the pid of one reaper child if there are any processes that can be
reapead;
otherwise, it is set to \-1.
.It Dv PROC_REAP_GETPIDS
Queries the list of processes that can be reaped
by the reaper of the specified process.
The request takes a pointer to a
.Vt procctl_reaper_pids
structure in the
.Fa data
parameter.
.Bd -literal
struct procctl_reaper_pids {
	u_int	rp_count;
	struct procctl_reaper_pidinfo *rp_pids;
};
.Ed
.Pp
When called, the
.Fa rp_pids
field must point to an array of
.Fa rp_count
.Vt procctl_reaper_pidinfo
structures.
The kernel will populate these structures with information about the
reaper's descendants.
.Pp
The
.Vt "struct procctl_reaper_pidinfo"
structure provides some information about one of the reaper's descendants.
Note that for a descendant that is not a child, it may be incorrectly
identified because of a race in which the original child process exited
and the exited process's pid was reused for an unrelated process.
.Bd -literal
struct procctl_reaper_pidinfo {
	pid_t	pi_pid;
	pid_t	pi_subtree;
	u_int	pi_flags;
};
.Ed
.Pp
The
.Fa pi_pid
field is the process id of the descendant.
The
.Fa pi_subtree
field provides the pid of the direct child of the reaper which is
the (grand-)parent of the descendant process.
The
.Fa pi_flags
field returns the following flags, further describing the descendant:
.Bl -tag -width Ds
.It Dv REAPER_PIDINFO_VALID
Set to indicate that the
.Vt procctl_reaper_pidinfo
structure was filled in by the kernel.
Zero-filling the
.Fa rp_pids
array and testing the
.Dv REAPER_PIDINFO_VALID
flag allows the caller to detect the end
of the returned array.
.It Dv REAPER_PIDINFO_CHILD
The
.Fa pi_pid
field identifies a direct child of the reaper.
.It Dv REAPER_PIDINFO_REAPER
The reported process is itself a reaper.
The descendants of the subordinate reaper are not reported.
.It Dv REAPER_PIDINFO_ZOMBIE
The reported process is in the zombie state, ready to be reaped.
.It Dv REAPER_PIDINFO_STOPPED
The reported process is stopped by a SIGSTOP/SIGTSTP signal.
.It Dv REAPER_PIDINFO_EXITING
The reported process is in the process of exiting (but not yet a zombie).
.El
.It Dv PROC_REAP_KILL
Request to deliver a signal to some subset of the descendants of the reaper.
The
.Fa data
parameter must point to a
.Vt procctl_reaper_kill
structure, which is used both for parameters and status return.
.Bd -literal
struct procctl_reaper_kill {
	int	rk_sig;
	u_int	rk_flags;
	pid_t	rk_subtree;
	u_int	rk_killed;
	pid_t	rk_fpid;
};
.Ed
.Pp
The
.Fa rk_sig
field specifies the signal to be delivered.
Zero is not a valid signal number, unlike for
.Xr kill 2 .
The
.Fa rk_flags
field further directs the operation.
It is or-ed from the following flags:
.Bl -tag -width Ds
.It Dv REAPER_KILL_CHILDREN
Deliver the specified signal only to direct children of the reaper.
.It Dv REAPER_KILL_SUBTREE
Deliver the specified signal only to descendants that were forked by
the direct child with pid specified in the
.Fa rk_subtree
field.
.El
.Pp
If neither the
.Dv REAPER_KILL_CHILDREN
nor the
.Dv REAPER_KILL_SUBTREE
flags are specified, all current descendants of the reaper are signalled.
.Pp
If a signal was delivered to any process, the return value from the request
is zero.
In this case, the
.Fa rk_killed
field identifies the number of processes signalled.
The
.Fa rk_fpid
field is set to the pid of the first process for which signal
delivery failed, e.g., due to permission problems.
If no such process exists, the
.Fa rk_fpid
field is set to \-1.
.It Dv PROC_TRACE_CTL
Enable or disable tracing of the specified process(es), according to the
value of the integer argument.
Tracing includes inspecting the process via
.Xr ptrace 2 ,
.Xr ktrace 2 ,
debugging sysctls,
.Xr hwpmc 4 ,
or
.Xr dtrace 1
as well as dumping core.
Possible values for the
.Fa data
argument are:
.Bl -tag -width Ds
.It Dv PROC_TRACE_CTL_ENABLE
Enable tracing, after it was disabled by
.Dv PROC_TRACE_CTL_DISABLE .
Only allowed for self.
.It Dv PROC_TRACE_CTL_DISABLE
Disable tracing for the specified process.
Tracing is re-enabled when the process changes the executing
program with the
.Xr execve 2
system call.
A child inherits the trace settings from the parent on
.Xr fork 2 .
.It Dv PROC_TRACE_CTL_DISABLE_EXEC
Same as
.Dv PROC_TRACE_CTL_DISABLE ,
but the setting persists for the process even after
.Xr execve 2 .
.El
.It Dv PROC_TRACE_STATUS
Returns the current tracing status for the specified process in
the integer variable pointed to by
.Fa data .
If tracing is disabled,
.Fa data
is set to \-1.
If tracing is enabled, but no debugger is attached by the
.Xr ptrace 2
system call,
.Fa data
is set to 0.
If a debugger is attached,
.Fa data
is set to the pid of the debugger process.
.It Dv PROC_TRAPCAP_CTL
Controls the capability mode sandbox actions for the specified
sandboxed processes
on a return from any system call which fails with either an
.Er ENOTCAPABLE
or
.Er ECAPMODE
error.
If this control is enabled and a system call fails with one of these errors,
a synchronous
.Dv SIGTRAP
signal is delivered to the thread immediately before returning from the
system call.
.Pp
Possible values for the
.Fa data
argument are:
.Bl -tag -width Ds
.It Dv PROC_TRAPCAP_CTL_ENABLE
Enable
.Dv SIGTRAP
signal delivery on capability mode access violations.
The enabled mode is inherited by the children of the process,
and is kept after
.Xr fexecve 2
calls.
.It Dv PROC_TRAPCAP_CTL_DISABLE
Disable
.Dv SIGTRAP
signal delivery on capability mode access violations.
Note that the global sysctl
.Dv kern.trap_enotcap
might still cause the signal to be delivered.
See
.Xr capsicum 4 .
.El
.Pp
On signal delivery, the
.Va si_errno
member of the
.Fa siginfo
signal handler parameter is set to the system call error value,
and the
.Va si_code
member is set to
.Dv TRAP_CAP .
The system call number is stored in the
.Va si_syscall
field of the
.Fa siginfo
signal handler parameter.
The other system call parameters can be read from the
.Fa ucontext_t
but the system call number is typically stored in the register
that also contains the return value and so is unavailable in the
signal handler.
.Pp
See
.Xr capsicum 4
for more information about capability mode.
.It Dv PROC_TRAPCAP_STATUS
Return the current status of raising
.Dv SIGTRAP
for capability mode access violations by the specified process.
The integer value pointed to by the
.Fa data
argument is set to the
.Dv PROC_TRAPCAP_CTL_ENABLE
value if
.Dv SIGTRAP
delivery is enabled, and to
.Dv PROC_TRAPCAP_CTL_DISABLE
otherwise.
.Pp
See the note about sysctl
.Dv kern.trap_enotcap
above, which gives independent global control of signal delivery.
.It Dv PROC_PDEATHSIG_CTL
Request the delivery of a signal when the parent of the calling
process exits.
.Fa idtype
must be
.Dv P_PID
and
.Fa id
must be the either caller's pid or zero, with no difference in effect.
The value is cleared for child processes
and when executing set-user-ID or set-group-ID binaries.
.Fa data
must point to a value of type
.Vt int
indicating the signal
that should be delivered to the caller.
Use zero to cancel a previously requested signal delivery.
.It Dv PROC_PDEATHSIG_STATUS
Query the current signal number that will be delivered when the parent
of the calling process exits.
.Fa idtype
must be
.Dv P_PID
and
.Fa id
must be the either caller's pid or zero, with no difference in effect.
.Fa data
must point to a memory location that can hold a value of type
.Vt int .
If signal delivery has not been requested, it will contain zero
on return.
.It Dv PROC_STACKGAP_CTL
Controls stack gaps in the specified process.
A stack gap is one or more virtual memory pages at the end of the
growth area for a
.Dv MAP_STACK
mapping that is reserved and never backed by memory.
Instead, the process is guaranteed to receive a synchronous
.Dv SIGSEGV
signal for each access to pages in the gap.
The number of pages reserved for each stack is set by the sysctl
.Va security.bsd.stack_guard_page .
.Pp
Gaps protect against stack overflows by preventing them from corrupting memory
adjacent to the stack.
.Pp
The
.Fa data
argument must point to an integer variable containing flags.
The following flags are allowed:
.Bl -tag -width Ds
.It Dv PROC_STACKGAP_ENABLE
This flag is only accepted for consistency with
.Dv PROC_STACKGAP_STATUS .
If stack gaps are enabled, the flag is ignored.
If stack gaps are disabled, the request fails with
.Ev EINVAL .
After gaps are disabled in a process, they can only be re-enabled when an
.Xr execve 2
is performed.
.It Dv PROC_STACKGAP_DISABLE
Disable stack gaps for the process.
For existing stacks, the gap is no longer reserved
and can be filled by memory on access.
.It Dv PROC_STACKGAP_ENABLE_EXEC
Enable stack gaps for the new address space constructed by any future
.Xr execve 2
in the specified process.
.It Dv PROC_STACKGAP_DISABLE_EXEC
Inherit disabled stack gaps state after
.Xr execve 2 .
In other words, if the currently executing program has stack gaps disabled,
they are kept disabled on exec.
If gaps were enabled, they are kept enabled after exec.
.El
.Pp
The stack gap state is inherited from the parent on
.Xr fork 2 .
.It Dv PROC_STACKGAP_STATUS
Returns the current stack gap state for the specified process.
.Fa data
must point to an integer variable, which is used to return a bitmask
consisting of the following flags:
.Bl -tag -width Ds
.It Dv PROC_STACKGAP_ENABLE
Stack gaps are enabled.
.It Dv PROC_STACKGAP_DISABLE
Stack gaps are disabled.
.It Dv PROC_STACKGAP_ENABLE_EXEC
Stack gaps are enabled in the process after
.Xr execve 2 .
.It Dv PROC_STACKGAP_DISABLE_EXEC
Stack gaps are disabled in the process after
.Xr execve 2 .
.El
.Pp
Note that the
.Xr elfctl 1
.Dq nostackgap
flag takes precedence over this setting for individual process address spaces.
Executing a binary with this flag set will never use stack gaps in the address
space constructed by
.Xr execve 2 .
However, the controls value can still be inherited by child processes, and
executing a binary without this flag set will revert to the behavior specified
by the control.
.It Dv PROC_NO_NEW_PRIVS_CTL
Allows one to ignore the set-user-ID and set-group-ID bits on the program
images activated by
.Xr execve 2
in the specified process and its future descendants.
The
.Fa data
parameter must point to an integer variable holding the following
value:
.Bl -tag -width Ds
.It Dv PROC_NO_NEW_PRIVS_ENABLE
Request set-user-ID and set-group-ID bits to be ignored.
.El
.Pp
It is not possible to disable this control once it has been enabled.
.It Dv PROC_NO_NEW_PRIVS_STATUS
Returns the current status of set-ID bits enablement for the target process.
The
.Fa data
parameter must point to an integer variable, where one of the
following values is written:
.Bl -tag -width Ds
.It Dv PROC_NO_NEW_PRIVS_ENABLE
.It Dv PROC_NO_NEW_PRIVS_DISABLE
.El
.It Dv PROC_WXMAP_CTL
Controls the creation of mappings with both write and execute permissions
in a process's address space.
The
.Fa data
parameter must point to an integer variable holding one of the
following values:
.Bl -tag -width Ds
.It Dv PROC_WX_MAPPINGS_PERMIT
Enable creation of mappings that have both write and execute
permissions in the specified process' current and future address spaces.
.It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
In a new address space created by a future call to
.Xr execve 2 ,
disallow creation of mappings that have both write and execute
permissions.
.El
.Pp
If both flags are set,
.Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
takes precedence during
.Xr execve 2 .
If neither flag is set,
mappings with write and execute permissions are only permitted if the
.Dv kern.elf{32/64}.allow_wx
sysctl is non-zero or the
.Xr elfctl 1
.Dq wxneeded
flag is set in the ELF control note.
.Pp
Once creation of writeable and executable mappings is enabled for a process,
it is impossible (and pointless) to disable it.
The only way to ensure the absence of such mappings after they
were enabled in a given process is to set the
.Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
flag and
.Xr execve 2
an image.
.It Dv PROC_WXMAP_STATUS
Returns the current status of the controls over creation of mappings with
both write and execute permissions for the specified process.
The
.Dv data
parameter must point to an integer variable, where one of the
following values is written:
.Bl -tag -width Ds
.It Dv PROC_WX_MAPPINGS_PERMIT
Creation of simultaneously writable and executable mappings are permitted;
otherwise, the process cannot create such mappings.
.It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
After
.Xr execve 2 ,
the new address space will not permit creation of simultaneously
writable and executable mappings.
.El
.Pp
Additionally, if the address space of the process does not permit
creation of simultaneously writable and executable mappings and
it is guaranteed that no such mapping was created since address space
creation, the
.Dv PROC_WXORX_ENFORCE
flag is set in the returned value.
.El
.Sh x86 MACHINE-SPECIFIC REQUESTS
.Bl -tag -width PROC_KPTI_STATUS
.It Dv PROC_KPTI_CTL
AMD64 only.
Controls the Kernel Page Table Isolation (KPTI) option for the children
of the specified process.
This control is only meaningful if KPTI has been enabled globally by the
.Va vm.pmap.kpti
tunable.
It is not possible to change the KPTI setting for a running process,
only for new address spaces constructed by a future
.Xr execve 2 .
.Pp
The
.Fa data
parameter must point to an integer variable containing one of the
following commands:
.Bl -tag -width Ds
.It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
Enable KPTI after
.Xr execve 2 .
.It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
Disable KPTI after
.Xr execve 2 .
Only root or a process having the
.Va PRIV_IO
privilege can use this option.
.El
.It Dv PROC_KPTI_STATUS
Returns the current KPTI status for the specified process.
.Fa data
must point to an integer variable, where one of the
following values is written:
.Bl -tag -width Ds
.It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
.It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
.El
.Pp
The status is or-ed with
.Va PROC_KPTI_STATUS_ACTIVE
if KPTI is active for the current address space of the process.
.El
.Sh NOTES
Disabling tracing on a process should not be considered a security
feature, as it is bypassable both by the kernel and privileged processes
and via other system mechanisms.
As such, it should not be utilized to reliably protect cryptographic
keying material or other confidential data.
.Pp
Note that processes can trivially bypass the 'no simultaneously
writable and executable mappings' policy by first marking some mapping
as writeable, writing code to it, then removing write and adding
execute permission.
This may be legitimately required by some programs such as JIT compilers.
.Sh RETURN VALUES
If an error occurs, a value of \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn procctl
system call
will fail if:
.Bl -tag -width Er
.It Bq Er EFAULT
The
.Fa data
parameter points outside the process's allocated address space.
.It Bq Er EINVAL
The
.Fa cmd
argument specifies an unsupported command.
.Pp
The
.Fa idtype
argument specifies an unsupported identifier type.
.It Bq Er EPERM
The calling process does not have permission to perform the requested
operation on any of the selected processes.
.It Bq Er ESRCH
No processes matched the requested
.Fa idtype
and
.Fa id .
.It Bq Er ESRCH
No descendant processes can be found matching criteria specified in the
.Dv PROC_REAP_KILL
request.
.It Bq Er EINVAL
An invalid operation or flag was passed in
.Fa data
for a
.Dv PROC_SPROTECT
command.
.It Bq Er EPERM
The
.Fa idtype
argument is not equal to
.Dv P_PID ,
or
.Fa id
is not equal to the pid of the calling process, for
.Dv PROC_REAP_ACQUIRE
or
.Dv PROC_REAP_RELEASE
requests.
.It Bq Er EINVAL
Invalid or undefined flags were passed to a
.Dv PROC_REAP_KILL
request.
.It Bq Er EINVAL
An invalid or zero signal number was requested for a
.Dv PROC_REAP_KILL
request.
.It Bq Er EINVAL
A
.Dv PROC_REAP_RELEASE
request was issued by the
.Xr init 8
process.
.It Bq Er EBUSY
A
.Dv PROC_REAP_ACQUIRE
request was issued by a process that is already a reaper process.
.It Bq Er EBUSY
A
.Dv PROC_TRACE_CTL
request was issued for a process being traced.
.It Bq Er EPERM
A
.Dv PROC_TRACE_CTL
request to re-enable tracing of the process
.Po Dv PROC_TRACE_CTL_ENABLE Pc ,
or to disable persistence of
.Dv PROC_TRACE_CTL_DISABLE
on
.Xr execve 2
specified a target process other than the calling process.
.It Bq Er EINVAL
The value of the integer
.Fa data
parameter for the
.Dv PROC_TRACE_CTL
or
.Dv PROC_TRAPCAP_CTL
request is invalid.
.It Bq Er EINVAL
The
.Dv PROC_PDEATHSIG_CTL
or
.Dv PROC_PDEATHSIG_STATUS
request referenced an unsupported
.Fa id ,
.Fa idtype
or invalid signal number.
.El
.Sh SEE ALSO
.Xr dtrace 1 ,
.Xr elfctl 1 ,
.Xr proccontrol 1 ,
.Xr protect 1 ,
.Xr cap_enter 2 ,
.Xr kill 2 ,
.Xr ktrace 2 ,
.Xr mmap 2 ,
.Xr mprotect 2 ,
.Xr ptrace 2 ,
.Xr wait 2 ,
.Xr capsicum 4 ,
.Xr hwpmc 4 ,
.Xr init 8
.Sh HISTORY
The
.Fn procctl
function appeared in
.Fx 9.3 .
.Pp
The reaper facility is based on a similar feature in Linux and
DragonflyBSD, and first appeared in
.Fx 10.2 .
.Pp
The
.Dv PROC_PDEATHSIG_CTL
facility is based on the
.Ql prctl(PR_SET_PDEATHSIG, ...)
feature in Linux,
and first appeared in
.Fx 11.2 .
.Pp
ASLR support was added for checklist compliance in
.Fx 13.0 .