Struct Subshell 

pub struct Subshell<F> { /* private fields */ }

Subshell builder

See the module documentation for details.

Implementations

impl<F> Subshell<F>

where F: for<'a> FnOnce(&'a mut Env, Option<JobControl>) -> Pin<Box<dyn Future<Output = ()> + 'a>> + 'static,

pub fn new(task: F) -> Self

Creates a new subshell builder with a task.

The task will run in a subshell after it is started. The task takes two arguments:

1. The environment in which the subshell runs, and
2. Job control status for the subshell.

If the task returns an Err(Divert::...), it is handled as follows:

• Interrupt and Exit with Some(exit_status) override the exit status in Env.
• Other Divert values are ignored.

pub fn job_control<J: Into<Option<JobControl>>>(self, job_control: J) -> Self

Specifies disposition of the subshell with respect to job control.

If the argument 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. For 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 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.

pub fn ignore_sigint_sigquit(self, ignore: bool) -> Self

Makes the subshell ignore SIGINT and SIGQUIT.

If ignore is true and the subshell is not job-controlled, the subshell sets its signal dispositions for SIGINT and SIGQUIT to Ignore.

The default is false.

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

Starts the subshell.

This function creates a new child process that runs the task contained in this builder.

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 finish, you need to call Env::wait_for_subshell 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.

If you set job_control to 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. Otherwise, it indicates the error.

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

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<F> Debug for Subshell<F>

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

Formats the value using the given formatter.