Struct OwnedCommand 

pub struct OwnedCommand { /* private fields */ }

Implementations

impl OwnedCommand

pub fn new(program: impl AsRef<OsStr>) -> Self

pub fn from_command(command: Command) -> Self

GUI/service children are hidden on Windows by default. A wrapped Command may carry stdio, environment and raw-argument settings this crate cannot read back, so on Windows an allowlisted spawn (inherit_handles_only) from from_command requires an explicit windows_spawn_config. The crate never widens what a child inherits by default.

pub fn command_mut(&mut self) -> &mut Command

pub fn inherit_handles_only( &mut self, handles: impl IntoIterator<Item = RawHandleOrFd>, ) -> &mut Self

Inherit only these handles/fds plus configured stdio; values stay caller-owned.

pub fn inherit_fd(&mut self, fd: RawFd) -> &mut Self

Unix: keeps descriptor fd open in the child, in addition to stdio and anything listed through inherit_handles_only or other inherit_fd(s) calls. By default a spawned child inherits no descriptor above stderr: every one is marked close-on-exec between fork and exec (Orthic-Labs/rightkit#835). Listing fd clears that flag in the child only; the parent’s flags are not changed. The descriptor must be open when spawn runs, else the spawn fails with EBADF, and stays caller-owned. Use this, not a pre_exec of your own on command_mut: the sweep is registered at spawn, after every hook you added, and would close what such a hook opened. Descriptors 0 to 2 are stdio and follow the command’s stdio settings. Not available on Windows.

pub fn inherit_fds(&mut self, fds: &[RawFd]) -> &mut Self

Unix: inherit_fd for each descriptor in fds.

pub fn inherit_all_descriptors(&mut self, enabled: bool) -> &mut Self

Opts out of descriptor sanitation. Unsafe by policy: with true, a Unix child inherits every descriptor of the parent that is not itself close-on-exec, a sandboxed child included, which is exactly what a sandbox must not allow (Orthic-Labs/rightkit#835). On Windows it keeps the ordinary CreateProcess with handle inheritance on and no handle list, which hands the child every inheritable handle of the parent. Only a caller that passes descriptors it cannot name (a launcher forwarding an unknown inherited set) has a reason. Conflicts with inherit_handles_only and inherit_fd(s): the spawn fails with InvalidInput instead of guessing which wins.

pub fn env_allowlist<I, S>(&mut self, keys: I) -> &mut Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Clear environment, then copy only named variables set in this process.

pub fn env_allowlist_with_defaults<I, S>(&mut self, extra: I) -> &mut Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Self::env_allowlist over DEFAULT_ENV_ALLOWLIST plus extra (a consumer’s own variables, for instance a model-cache location). Call it once: like env_allowlist it starts from an empty environment, so a second call drops what the first kept.

pub fn env_is_cleared(&self) -> bool

True once Self::env_allowlist (or env_allowlist_with_defaults) cleared the inherited environment on this command. A Command that was cleared with env_clear directly, or wrapped by from_command after it was cleared, reads false: the state is not observable from std::process::Command.

pub fn env_strip<I, S>(&mut self, keys: I) -> &mut Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

pub fn windows_hide(&mut self) -> &mut Self

Compatibility no-op: hidden is already the default.

pub fn windows_visible(&mut self) -> &mut Self

Windows: leaves the console window visible, clearing the hidden default, for a user-facing program (an editor, a terminal at a project path) that must keep its window. Pair it with spawn_uncontained_detached for a fire-and-forget launch. Unix ignores it.

pub fn windows_allow_breakaway(&mut self, allow: bool) -> &mut Self

Windows: explicit-only breakaway (JOB_OBJECT_LIMIT_BREAKAWAY_OK). A process in the job leaves it only by asking (CREATE_BREAKAWAY_FROM_JOB); every descendant that does not ask stays contained and is terminated with the job. Dropping the owned child still terminates the helper’s tree; a grandchild that asked and broke away stays running. false restores full containment. Unix ignores it. For descendants that escape without asking, see windows_allow_silent_breakaway.

pub fn windows_allow_silent_breakaway(&mut self, allow: bool) -> &mut Self

Windows: silent breakaway (JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK plus BREAKAWAY_OK). Every process the job’s processes create is outside the job without asking, so descendants are NOT contained and survive the helper. Use only for a helper whose children must all outlive it. false restores full containment. Unix ignores it.

pub fn job_assignment_mode(&mut self, mode: JobAssignmentMode) -> &mut Self

Ignored on Unix. BestEffort reports errors on OwnedChild.

pub fn unix_containment(&mut self, mode: UnixContainment) -> &mut Self

Ignored on Windows. Session runs setsid before exec.

pub fn process_priority(&mut self, priority: ProcessPriority) -> &mut Self

Scheduling priority for the child. The default, ProcessPriority::Normal, adds nothing to the spawn. See ProcessPriority for the Windows and Unix mappings. Applies to detached spawns too.

pub fn kill_on_parent_exit(&mut self, enabled: bool) -> &mut Self

Opt-in, off by default. Linux only: the kernel sends SIGTERM to the direct child (PR_SET_PDEATHSIG) when the thread that spawned it exits, which includes this process dying without running cleanup (for example SIGKILL). The signal reaches the direct child only, never the rest of its group, it can be caught, and there is no SIGKILL escalation. It is keyed to the spawning thread, so spawn from a thread that lives as long as the child.

macOS has no PR_SET_PDEATHSIG, so the tie is a small watchdog process started right after the child (a kqueue with EVFILT_PROC/NOTE_EXIT on this process and on the child; see process_unix::arm_parent_death_watch). When this process dies, SIGKILL included, the watchdog sends SIGTERM to the child’s whole process group and SIGKILL two seconds later. Differences from Linux: the trigger is the whole process exiting, not the spawning thread; the signal goes to the group and escalates; it costs one extra helper process per tied child (it exits when the child or this process does); the child runs untied between its spawn and the moment spawn returns (a few milliseconds), and spawn kills the child and fails if the watchdog cannot be armed.

Other Unix hosts have no parent-death primitive this crate relies on: the spawn fails with ErrorKind::Unsupported before anything is started, rather than run the child untied. Windows ignores the option because kill-on-close job objects already cover parent death. Rejected (InvalidInput) for detached spawns.

pub fn partial_spawn_cleanup_timeout(&mut self, timeout: Duration) -> &mut Self

Bound failed-spawn cleanup. Timed-out children go to a background reaper.

pub fn spawn(self) -> Result<OwnedChild>

pub fn spawn_suspended(self) -> Result<OwnedChild>

Like OwnedCommand::spawn, but on Windows the child is created suspended, assigned to its Job Object, and held there: it executes no instruction until OwnedChild::resume is called. A caller can persist the child’s identity (pid and start time) first, then release it. Dropping a child that was never resumed terminates it like any owned child.

Unix has no suspended creation: this is spawn, the child runs at once, and resume is a no-op that returns Ok. A caller that needs a hold on Unix gates the child itself (for example a pipe the child blocks reading).

pub fn spawn_uncontained_detached(self) -> Result<OwnedChild>

Shared launch with no owner job or terminate-on-drop. Unix uses setsid. Stdio follows Command: dropping piped stdin can still deliver EOF.

Windows first asks to break away from the caller’s job object (CREATE_BREAKAWAY_FROM_JOB). If the caller’s job denies breakaway (ERROR_ACCESS_DENIED), the launch is retried once without it, as CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP (DETACHED_PROCESS if show_window) with the same stdio and handle allowlist (an ordinary spawn without an allowlist still inherits what std inherits). The child is then detached from the console and process group but stays inside the caller’s job, so the job’s limits (including kill-on-close) still reach it. Check OwnedChild::stayed_in_parent_job to learn which happened. A caller that must not run inside the parent’s job uses spawn_uncontained_detached_strict. Any other launch failure is returned as is, without a retry. Unix behaviour is unchanged.

pub fn spawn_uncontained_detached_strict(self) -> Result<OwnedChild>

Like spawn_uncontained_detached, but never falls back. On Windows, when the caller’s job denies breakaway the launch fails with an io::Error of kind PermissionDenied wrapping BreakawayDenied (recover it with error.get_ref().and_then(|e| e.downcast_ref::<BreakawayDenied>())), and nothing is started. On Unix this is identical to spawn_uncontained_detached.

Trait Implementations

impl Debug for OwnedCommand

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

Formats the value using the given formatter.