Struct RedirGuard 

pub struct RedirGuard<'e> { /* private fields */ }

Env wrapper for performing redirections.

This is an RAII-style wrapper of Env in which redirections are performed. A RedirGuard keeps track of file descriptors affected by redirections so that we can restore the file descriptors to the state before performing the redirections.

There are two ways to clear file descriptors saved in the RedirGuard. One is undo_redirs, which restores the file descriptors to the original state, and the other is preserve_redirs, which removes the saved file descriptors without restoring the state and thus makes the effect of the redirections permanent.

When an instance of RedirGuard is dropped, undo_redirs is implicitly called. That means you need to call preserve_redirs explicitly to preserve the redirections’ effect.

Implementations

impl<'e> RedirGuard<'e>

pub fn new(env: &'e mut Env) -> Self

Creates a new RedirGuard.

pub async fn perform_redir( &mut self, redir: &Redir, xtrace: Option<&mut XTrace>, ) -> Result<Option<ExitStatus>, Error>

Performs a redirection.

If successful, this function saves internally a backing copy of the file descriptor affected by the redirection, and returns the exit status of the last command substitution performed during the redirection, if any.

If xtrace is Some instance of XTrace, the redirection operators and the expanded operands are written to it.

pub async fn perform_redirs<'a, I>( &mut self, redirs: I, xtrace: Option<&mut XTrace>, ) -> Result<Option<ExitStatus>, Error>

where I: IntoIterator<Item = &'a Redir>,

Performs redirections.

This is a convenience function for performing redirection for each iterator item.

If the redirection fails for an item, the remainders are ignored, but the effects of the preceding items are not canceled.

If xtrace is Some instance of XTrace, the redirection operators and the expanded operands are written to it.

pub fn undo_redirs(&mut self)

Undoes the effect of the redirections.

This function restores the file descriptors affected by redirections to the original state and closes internal backing file descriptors, which were used for restoration and are no longer needed.

pub fn preserve_redirs(&mut self)

Makes the redirections permanent.

This function closes internal backing file descriptors without restoring the original file descriptor state.

Methods from Deref<Target = Env>

pub fn clone_with_system(&self, system: Box<dyn System>) -> Env

Clones this environment.

The application-managed parts of the environment are cloned normally. The system-managed parts are replaced with the provided System instance.

pub fn init_variables(&mut self)

Initializes default variables.

This function assigns the following variables to self:

• IFS=' \t\n'
• OPTIND=1
• PS1='$ '
• PS2='> '
• PS4='+ '
• PPID=(parent process ID)
• PWD=(current working directory) (See Env::prepare_pwd)

This function ignores any errors that may occur.

TODO: PS1 should be set to "# " for root users.

pub async fn wait_for_signals(&mut self) -> Rc<[Number]>

Waits for some signals to be caught in the current process.

Returns an array of signals caught.

This function is a wrapper for SharedSystem::wait_for_signals. Before the function returns, it passes the results to TrapSet::catch_signal so the trap set can remember the signals caught to be handled later.

pub async fn wait_for_signal(&mut self, signal: Number)

Waits for a specific signal to be caught in the current process.

This function calls wait_for_signals repeatedly until it returns results containing the specified signal.

pub fn poll_signals(&mut self) -> Option<Rc<[Number]>>

Returns signals that have been caught.

This function is similar to wait_for_signals but does not wait for signals to be caught. Instead, it only checks if any signals have been caught but not yet consumed in the SharedSystem.

pub fn get_tty(&mut self) -> Result<Fd, Errno>

Returns a file descriptor to the controlling terminal.

This function returns self.tty if it is Some FD. Otherwise, it opens /dev/tty and saves the new FD to self.tty before returning it.

pub fn ensure_foreground(&mut self) -> Result<(), Errno>

Ensures the shell is in the foreground.

If the current process belongs to the same process group as the session leader, this function forces the current process to be in the foreground by calling SystemEx::tcsetpgrp_with_block. Otherwise, this function suspends the process until it is resumed in the foreground by another job-controlling process (see SystemEx::tcsetpgrp_without_block).

This function returns an error if the process does not have a controlling terminal, that is, get_tty returns Err(_).

Note on POSIX conformance

This function implements part of the initialization of the job-control shell. POSIX says that the shell should bring itself into the foreground only if it is started as the controlling process (that is, the session leader) for the terminal session. However, this function also brings the shell into the foreground if the shell is in the same process group as the session leader because it is unlikely that there is another job-controlling process that can bring the shell into the foreground.

pub fn is_interactive(&self) -> bool

Tests whether the current environment is an interactive shell.

This function returns true if and only if:

• the Interactive option is On in self.options, and
• the current context is not in a subshell (no Frame::Subshell in self.stack).

pub fn controls_jobs(&self) -> bool

Tests whether the shell is performing job control.

This function returns true if and only if:

• the Monitor option is On in self.options, and
• the current context is not in a subshell (no Frame::Subshell in self.stack).

pub async fn wait_for_subshell( &mut self, target: Pid, ) -> Result<(Pid, ProcessState), Errno>

Waits for a subshell to terminate, suspend, or resume.

This function waits for a subshell to change its execution state. The target parameter specifies which child to wait for:

• -1: any child
• 0: any child in the same process group as the current process
• pid: the child whose process ID is pid
• -pgid: any child in the process group whose process group ID is pgid

When self.system.wait returned a new state of the target, it is sent to self.jobs (JobList::update_status) before being returned from this function.

If there is no matching target, this function returns Err(Errno::ECHILD).

If the target subshell is not job-controlled, you may want to use wait_for_subshell_to_finish instead.

pub async fn wait_for_subshell_to_halt( &mut self, target: Pid, ) -> Result<(Pid, ProcessResult), Errno>

Wait for a subshell to terminate or suspend.

This function is similar to wait_for_subshell, but returns only when the target is finished (either exited or killed by a signal) or suspended.

pub async fn wait_for_subshell_to_finish( &mut self, target: Pid, ) -> Result<(Pid, ExitStatus), Errno>

Wait for a subshell to terminate.

This function is similar to wait_for_subshell, but returns only when the target is finished (either exited or killed by a signal).

Returns the process ID of the awaited process and its exit status.

pub fn update_all_subshell_statuses(&mut self)

Applies all job status updates to jobs in self.jobs.

This function calls self.system.wait repeatedly until all status updates available are applied to self.jobs (JobList::update_status).

Note that updates of subshells that are not managed in self.jobs are lost when you call this function.

pub fn get_or_create_variable<S>( &mut self, name: S, scope: Scope, ) -> VariableRefMut<'_>

where S: Into<String>,

Get an existing variable or create a new one.

This method is a thin wrapper around VariableSet::get_or_new. If the AllExport option is on, the variable is exported before being returned from the method.

You should prefer using this method over VariableSet::get_or_new to make sure that the AllExport option is applied.

pub fn errexit_is_applicable(&self) -> bool

Tests whether the ErrExit option is applicable in the current context.

This function returns true if and only if:

• the ErrExit option is on, and
• the current stack has no Condition frame.

pub fn apply_errexit(&self) -> ControlFlow<Divert>

Returns a Divert if the shell should exit because of the ErrExit shell option.

The function returns Break(Divert::Exit(None)) if the errexit option is applicable and the current self.exit_status is non-zero. Otherwise, it returns Continue(()).

pub fn apply_result(&mut self, result: ControlFlow<Divert>)

Updates the exit status from the given result.

If result is a Break(divert) where divert.exit_status() is Some exit status, this function sets self.exit_status to that exit status.

pub fn get_pwd_if_correct(&self) -> Option<&str>

Returns the value of the $PWD variable if it is correct.

The variable is correct if:

• it is a scalar variable,
• its value is a pathname of the current working directory (possibly including symbolic link components), and
• there is no dot (.) or dot-dot (..) component in the pathname.

pub fn prepare_pwd(&mut self) -> Result<(), PreparePwdError>

Updates the $PWD variable with the current working directory.

If the value of $PWD is correct, this function does not modify it. Otherwise, this function sets the value to self.system.getcwd().

This function is meant for initializing the $PWD variable when the shell starts.

pub fn push_frame(&mut self, frame: Frame) -> EnvFrameGuard<'_>

Pushes a new frame to the runtime execution context stack.

This function is equivalent to self.stack.push(frame), but returns an EnvFrameGuard that allows re-borrowing the Env.

pub fn push_context(&mut self, context: Context) -> EnvContextGuard<'_>

Pushes a new context to the variable set.

This function is equivalent to self.variables.push_context(context_type), but returns an EnvContextGuard that allows re-borrowing the Env.

Trait Implementations

impl<'e> Debug for RedirGuard<'e>

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

Formats the value using the given formatter.

impl Deref for RedirGuard<'_>

type Target = Env

The resulting type after dereferencing.

fn deref(&self) -> &Env

Dereferences the value.

impl DerefMut for RedirGuard<'_>

fn deref_mut(&mut self) -> &mut Env

Mutably dereferences the value.

impl Drop for RedirGuard<'_>

fn drop(&mut self)

Executes the destructor for this type.