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 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 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 DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP 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.