Struct SpawnOptions 

pub struct SpawnOptions {
    pub cgroup_procs: Option<Arc<CString>>,
    pub open_file_limit: Option<u64>,
    pub pids_limits: Arc<[PidsLimit]>,
    pub on_spawn: Option<Arc<dyn Fn(SpawnedProcess) + Send + Sync>>,
}

What the shell does with each external process it spawns, for an embedder that confines or tracks the processes its commands start. The default does nothing.

The options are part of the shell’s RuntimeOptions, so they reach every external command the shell runs, pipelines, background jobs and subshells included, since those copy the shell they run in.

The exec builtin applies them in the shell’s own process, with no fork, so an exec that fails leaves in place the steps that ran before the failure. The order is the cgroup join, the process counts, the shell’s other descriptors, then the open-file limit; with process counts set, the builtin refuses before any step runs.

Fields

cgroup_procs: Option<Arc<CString>>

A file each child writes 0 to after it is forked and before it runs its program. For a cgroup v2’s cgroup.procs file, the write moves the child into that cgroup, so it cannot fork a process outside it; only Linux has cgroups. When the child cannot open the file or write to it, the command fails to execute and its program never runs.

open_file_limit: Option<u64>

The soft limit on open files (RLIMIT_NOFILE) each child gets, set after it is forked and before it runs its program, for an embedder that raised its own soft limit and gives its children the one it started with. A value above the hard limit sets the hard limit, and on macOS a value it refuses is lowered to OPEN_MAX (10240). None leaves the limit the child inherits; on a platform without resource limits, setting it fails every external command.

pids_limits: Arc<[PidsLimit]>

Process counts each child checks after it joins the cgroup in cgroup_procs and before it runs its program. The kernel does not apply a cgroup’s pids.max to a process that moves into it, so the child checks the count itself and fails its spawn, without running its program, when a count is above its limit or cannot be read: the command then fails to execute, with status 126, and on_spawn is not called. The exec builtin refuses to replace the shell while the list is non-empty, because in the shell’s own process a count would include every thread of the shell; a subshell’s exec forks and is checked as usual. Empty, the default, checks nothing; on a platform without this check, a non-empty list fails every external command.

on_spawn: Option<Arc<dyn Fn(SpawnedProcess) + Send + Sync>>

Called with each child once it has started, before the shell waits for it. It runs on the shell’s task, so it should return quickly.

Trait Implementations

impl Clone for SpawnOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpawnOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SpawnOptions

fn default() -> Self

Returns the “default value” for a type.