Struct Config 

#[non_exhaustive]
pub struct Config {
    pub job_control: Option<JobControl>,
    pub ignores_sigint_sigquit: bool,
}

Configuration for subshell creation

This struct configures how a subshell is created. An instance of Config can be created with new or foreground, and modified by setting the fields. To start a subshell, call start or start_and_wait.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

job_control: Option<JobControl>

Specifies disposition of the subshell with respect to job control.

If this value is None (which is the default), the subshell runs in the same process group as the parent process. If it is Some(_), the subshell becomes a new process group leader. For Some(JobControl::Foreground), it also brings itself to the foreground.

This parameter is ignored if the shell is not controlling jobs when starting the subshell. You can tell the actual job control status of the subshell by checking the second return value of start in the parent environment and the second argument passed to the task in the subshell environment.

If the parent process is a job-controlling interactive shell, but the subshell is not job-controlled, the subshell’s signal dispositions for SIGTSTP, SIGTTIN, and SIGTTOU are set to Ignore. This is to prevent the subshell from being stopped by a job-stopping signal. Were the subshell stopped, you could never resume it since it is not job-controlled.

ignores_sigint_sigquit: bool

If true, the subshell ignores SIGINT and SIGQUIT.

This parameter is for implementing the POSIX requirement that asynchronous and-or lists ignore SIGINT and SIGQUIT if job control is disabled. The value is passed to TrapSet::enter_subshell to modify the signal dispositions for SIGINT and SIGQUIT in the subshell.

This parameter has no effect if the subshell is job-controlled (see job_control). The default value is false.

Implementations

impl Config

pub fn new() -> Self

Creates a new Config with default settings.

pub fn foreground() -> Self

Creates a new Config with foreground job control.

This is a convenient function to create a Config for a subshell that should run in the foreground if job control is active. The returned Config has job_control set to Some(JobControl::Foreground), and the other fields set to their default values.

pub async fn start<S, F>( self, env: &mut Env<S>, task: F, ) -> Result<(Pid, Option<JobControl>), Errno>

where S: BlockSignals + Close + Dup + Exit + Fork + GetPid + Open + RunBlocking + RunUnblocking + SendSignal + SetPgid + SetRlimit + SignalSystem + TcSetPgrp + 'static, F: AsyncFnOnce(&mut Env<S>, Option<JobControl>) + 'static,

Starts the subshell.

This function creates a new child process that runs the task provided as an argument.

Although this function is async, it does not wait for the child to finish, which means the parent and child processes will run concurrently. To wait for the child to change state, call Env::wait_for_subshell, Env::wait_for_subshell_to_halt, or Env::wait_for_subshell_to_finish. If job control is active, you may want to add the process ID to Env::jobs before waiting. To start the subshell and wait for it to finish at once, use start_and_wait.

If you set job_control to Some(JobControl::Foreground), this function opens Env::tty by calling Env::get_tty. The tty is used to change the foreground job to the new subshell. However, job_control is effective only when the shell is controlling jobs.

If the subshell started successfully, the return value is a pair of the child process ID and the actual job control status. Otherwise, it indicates the error.

pub async fn start_and_wait<S, F>( self, env: &mut Env<S>, task: F, ) -> Result<(Pid, ProcessResult), Errno>

where S: BlockSignals + Close + Dup + Exit + Fork + GetPid + Open + RunBlocking + RunUnblocking + SendSignal + SetPgid + SetRlimit + SignalSystem + TcSetPgrp + Wait + WaitForSignals + 'static, F: AsyncFnOnce(&mut Env<S>, Option<JobControl>) + 'static,

Starts the subshell and waits for it to finish.

This function starts self and waits for it to finish. This function returns when the subshell process exits or is killed by a signal. If the subshell is job-controlled, the function also returns when the job is suspended.

If the subshell started successfully, the return value is the process ID and the process result of the subshell. If there was an error starting the subshell, this function returns the error.

If you set job_control to JobControl::Foreground and job control is effective as per Env::controls_jobs, this function makes the shell the foreground job after the subshell terminated or suspended.

When a job-controlled subshell suspends, this function does not add it to env.jobs. You have to do it for yourself if necessary.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.