The
procctl()
system call provides for control over processes.
The
idtype
and
id
arguments specify the set of processes to control.
If multiple processes match the identifier,
procctl
will make a
"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:
|
| P_PID
|
Control the process with the process ID
id.
id
zero is a shortcut for the calling process ID.
|
| P_PGID
|
| |
Control processes belonging to the process group with the ID
id.
|
|
The control request to perform is specified by the
cmd
argument.
The following commands are supported:
| PROC_ASLR_CTL
|
Controls the Address Space Layout Randomization (ASLR) in the program
images created
by
execve(2)
in the specified process or its descendants that did not changed
the control nor modified it by other means.
The
data
parameter must point to the integer variable holding one of the following
values:
|
|
| PROC_ASLR_FORCE_ENABLE
|
Request that ASLR is enabled after execution, even if it is disabled
system-wide.
The image flag and set-uid might prevent ASLR enablement still.
|
| PROC_ASLR_FORCE_DISABLE
|
| |
Request that ASLR is disabled after execution.
Same notes as for
PROC_ASLR_FORCE_ENABLE
apply.
|
| PROC_ASLR_NOFORCE
|
Use system-wide configured policy for ASLR.
|
|
| PROC_ASLR_STATUS
|
Returns the current status of ASLR enablement for the target process.
The
data
parameter must point to the integer variable, where one of the
following values is written:
|
PROC_ASLR_FORCE_ENABLE
PROC_ASLR_FORCE_DISABLE
PROC_ASLR_NOFORCE
|
| |
|
|
If the currently executed image in the process itself has ASLR enabled,
the
PROC_ASLR_ACTIVE
flag is or-ed with the value listed above.
| PROC_SPROTECT
|
Set process protection state.
This is used to mark a process as protected from being killed if the system
exhausts the available memory and swap.
The
data
parameter must point to an integer containing an operation and zero or more
optional flags.
The following operations are supported:
|
|
| PPROT_SET
|
Mark the selected processes as protected.
|
| PPROT_CLEAR
|
| |
Clear the protected state of selected processes.
|
|
The following optional flags are supported:
| PPROT_DESCEND
|
| |
Apply the requested operation to all child processes of each selected process
in addition to each selected process.
|
| PPROT_INHERIT
|
| |
When used with
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.
|
|
| PROC_REAP_ACQUIRE
|
| |
Acquires the reaper status for the current process.
Reaper status means that children orphaned by the reaper's descendants
that were forked after the acquisition of reaper status are reparented to the
reaper process.
After system initialization,
init(8)
is the default reaper.
|
| PROC_REAP_RELEASE
|
| |
Release the reaper state for the current process.
The reaper of the current process becomes the new reaper of the
current process's descendants.
|
| PROC_REAP_STATUS
|
| |
Provides information about the reaper of the specified process,
or the process itself when it is a reaper.
The
data
argument must point to a
procctl_reaper_status
structure which is filled in by the syscall on successful return.
struct procctl_reaper_status {
u_int rs_flags;
u_int rs_children;
u_int rs_descendants;
pid_t rs_reaper;
pid_t rs_pid;
};
The
rs_flags
may have the following flags returned:
|
|
| REAPER_STATUS_OWNED
|
The specified process has acquired reaper status and has not
released it.
When the flag is returned, the specified process
id,
pid, identifies the reaper, otherwise the
rs_reaper
field of the structure is set to the pid of the reaper
for the specified process id.
|
| REAPER_STATUS_REALINIT
|
| |
The specified process is the root of the reaper tree, i.e.,
init(8).
|
|
The
rs_children
field returns the number of children of the reaper among the descendants.
It is possible to have a child whose reaper is not the specified process,
since the reaper for any existing children is not reset on the
PROC_REAP_ACQUIRE
operation.
The
rs_descendants
field returns the total number of descendants of the reaper(s),
not counting descendants of the reaper in the subtree.
The
rs_reaper
field returns the reaper pid.
The
rs_pid
returns the pid of one reaper child if there are any descendants.
| PROC_REAP_GETPIDS
|
Queries the list of descendants of the reaper of the specified process.
The request takes a pointer to a
procctl_reaper_pids
structure in the
data
parameter.
struct procctl_reaper_pids {
u_int rp_count;
struct procctl_reaper_pidinfo *rp_pids;
};
When called, the
rp_pids
field must point to an array of
procctl_reaper_pidinfo
structures, to be filled in on return,
and the
rp_count
field must specify the size of the array,
into which no more than
rp_count
elements will be filled in by the kernel.
The
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.
struct procctl_reaper_pidinfo {
pid_t pi_pid;
pid_t pi_subtree;
u_int pi_flags;
};
The
pi_pid
field is the process id of the descendant.
The
pi_subtree
field provides the pid of the child of the reaper, which is the (grand-)parent
of the process.
The
pi_flags
field returns the following flags, further describing the descendant:
|
|
| REAPER_PIDINFO_VALID
|
Set to indicate that the
procctl_reaper_pidinfo
structure was filled in by the kernel.
Zero-filling the
rp_pids
array and testing the
REAPER_PIDINFO_VALID
flag allows the caller to detect the end
of the returned array.
|
| REAPER_PIDINFO_CHILD
|
The
pi_pid
field identifies the direct child of the reaper.
|
| REAPER_PIDINFO_REAPER
|
| |
The reported process is itself a reaper.
The descendants of the subordinate reaper are not reported.
|
|
| PROC_REAP_KILL
|
Request to deliver a signal to some subset of the descendants of the reaper.
The
data
parameter must point to a
procctl_reaper_kill
structure, which is used both for parameters and status return.
struct procctl_reaper_kill {
int rk_sig;
u_int rk_flags;
pid_t rk_subtree;
u_int rk_killed;
pid_t rk_fpid;
};
The
rk_sig
field specifies the signal to be delivered.
Zero is not a valid signal number, unlike for
kill(2).
The
rk_flags
field further directs the operation.
It is or-ed from the following flags:
|
|
| REAPER_KILL_CHILDREN
|
| |
Deliver the specified signal only to direct children of the reaper.
|
| REAPER_KILL_SUBTREE
|
Deliver the specified signal only to descendants that were forked by
the direct child with pid specified in the
rk_subtree
field.
|
|
If neither the
REAPER_KILL_CHILDREN
nor the
REAPER_KILL_SUBTREE
flags are specified, all current descendants of the reaper are signalled.
If a signal was delivered to any process, the return value from the request
is zero.
In this case, the
rk_killed
field identifies the number of processes signalled.
The
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
rk_fpid
field is set to -1.
| PROC_TRACE_CTL
|
Enable or disable tracing of the specified process(es), according to the
value of the integer argument.
Tracing includes attachment to the process using the
ptrace(2)
and
ktrace(2),
debugging sysctls,
hwpmc(4),
dtrace(1),
and core dumping.
Possible values for the
data
argument are:
|
|
| PROC_TRACE_CTL_ENABLE
|
Enable tracing, after it was disabled by
PROC_TRACE_CTL_DISABLE.
Only allowed for self.
|
| PROC_TRACE_CTL_DISABLE
|
Disable tracing for the specified process.
Tracing is re-enabled when the process changes the executing
program with the
execve(2)
syscall.
A child inherits the trace settings from the parent on
fork(2).
|
| PROC_TRACE_CTL_DISABLE_EXEC
|
| |
Same as
PROC_TRACE_CTL_DISABLE,
but the setting persists for the process even after
execve(2).
|
|
| PROC_TRACE_STATUS
|
Returns the current tracing status for the specified process in
the integer variable pointed to by
data.
If tracing is disabled,
data
is set to -1.
If tracing is enabled, but no debugger is attached by the
ptrace(2)
syscall,
data
is set to 0.
If a debugger is attached,
data
is set to the pid of the debugger process.
|
| PROC_TRAPCAP_CTL
|
Controls the capability mode sandbox actions for the specified
sandboxed processes,
on a return from any syscall which gives either a
ENOTCAPABLE
or
ECAPMODE
error.
If the control is enabled, such errors from the syscalls cause
delivery of the synchronous
SIGTRAP
signal to the thread immediately before returning from the syscalls.
Possible values for the
data
argument are:
|
|
| PROC_TRAPCAP_CTL_ENABLE
|
Enable the
SIGTRAP
signal delivery on capability mode access violations.
The enabled mode is inherited by the children of the process,
and is kept after
fexecve(2)
calls.
|
| PROC_TRAPCAP_CTL_DISABLE
|
| |
Disable the signal delivery on capability mode access violations.
Note that the global sysctl
kern.trap_enotcap
might still cause the signal to be delivered.
See
capsicum(4).
|
|
On signal delivery, the
si_errno
member of the
siginfo
signal handler parameter is set to the syscall error value,
and the
si_code
member is set to
TRAP_CAP.
See
capsicum(4)
for more information about the capability mode.
| PROC_TRAPCAP_STATUS
|
Return the current status of signalling capability mode access
violations for the specified process.
The integer value pointed to by the
data
argument is set to the
PROC_TRAPCAP_CTL_ENABLE
value if the process control enables signal delivery, and to
PROC_TRAPCAP_CTL_DISABLE
otherwise.
See the note about sysctl
kern.trap_enotcap
above, which gives independent global control of signal delivery.
|
| PROC_PDEATHSIG_CTL
|
Request the delivery of a signal when the parent of the calling
process exits.
idtype
must be
P_PID
and
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.
arg
must point to a value of type
int
indicating the signal
that should be delivered to the caller.
Use zero to cancel a previously requested signal delivery.
|
| PROC_PDEATHSIG_STATUS
|
Query the current signal number that will be delivered when the parent
of the calling process exits.
idtype
must be
P_PID
and
id
must be the either caller's pid or zero, with no difference in effect.
arg
must point to a memory location that can hold a value of type
int.
If signal delivery has not been requested, it will contain zero
on return.
|
| PROC_STACKGAP_CTL
|
Controls the stack gaps in the specified process.
A stack gap is the part of the growth area for a
MAP_STACK
mapped region that is reserved and never filled by memory.
Instead, the process is guaranteed to receive a
SIGSEGV
signal on accessing pages in the gap.
Gaps protect against stack overflow corrupting memory adjacent
to the stack.
The
data
argument must point to an integer variable containing flags.
The following flags are allowed:
|
|
| PROC_STACKGAP_ENABLE
|
This flag is only accepted for consistency with
PROC_STACKGAP_STATUS.
If stack gaps are enabled, the flag is ignored.
If disabled, the flag causes an
EINVAL
error to be returned.
After gaps are disabled in a process, they can only be re-enabled when an
execve(2)
is performed.
|
| PROC_STACKGAP_DISABLE
|
Disable stack gaps for the process.
For existing stacks, the gap is no longer a reserved part of the growth
area and can be filled by memory on access.
|
| PROC_STACKGAP_ENABLE_EXEC
|
Enable stack gaps for programs started after an
execve(2)
by the specified process.
|
| PROC_STACKGAP_DISABLE_EXEC
|
| |
Inherit disabled stack gaps state after
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.
|
|
The stack gap state is inherited from the parent on
fork(2).
| PROC_STACKGAP_STATUS
|
Returns the current stack gap state for the specified process.
data
must point to an integer variable, which is used to return a bitmask
consisting of the following flags:
|
| PROC_STACKGAP_ENABLE
|
Stack gaps are enabled.
|
| PROC_STACKGAP_DISABLE
|
Stack gaps are disabled.
|
| PROC_STACKGAP_ENABLE_EXEC
|
Stack gaps are enabled in the process after
execve(2).
|
| PROC_STACKGAP_DISABLE_EXEC
|
| |
Stack gaps are disabled in the process after
execve(2).
|
|
