Struct Env 

#[non_exhaustive]
pub struct Env {

    pub aliases: AliasSet,
    pub arg0: String,
    pub builtins: HashMap<&'static str, Builtin>,
    pub exit_status: ExitStatus,
    pub functions: FunctionSet,
    pub jobs: JobList,
    pub main_pgid: Pid,
    pub main_pid: Pid,
    pub options: OptionSet,
    pub stack: Stack,
    pub traps: TrapSet,
    pub tty: Option<Fd>,
    pub variables: VariableSet,
    pub any: DataSet,
    pub system: SharedSystem,
}

Whole shell execution environment.

The shell execution environment consists of application-managed parts and system-managed parts. Application-managed parts are directly implemented in the Env instance. System-managed parts are managed by a SharedSystem that contains an instance of System.

Cloning

Env::clone effectively clones the application-managed parts of the environment. Since SharedSystem is reference-counted, you will not get a deep copy of the system-managed parts. See also clone_with_system.

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.

aliases: AliasSet

Aliases defined in the environment

arg0: String

Name of the current shell executable or shell script

Special parameter 0 expands to this value.

builtins: HashMap<&'static str, Builtin>

Built-in utilities available in the environment

exit_status: ExitStatus

Exit status of the last executed command

functions: FunctionSet

Functions defined in the environment

jobs: JobList

Jobs managed in the environment

main_pgid: Pid

Process group ID of the main shell process

main_pid: Pid

Process ID of the main shell process

This PID represents the value of the $ special parameter.

options: OptionSet

Shell option settings

stack: Stack

Runtime execution context stack

traps: TrapSet

Traps defined in the environment

tty: Option<Fd>

File descriptor to the controlling terminal

get_tty saves a file descriptor in this variable, so you don’t have to prepare it yourself.

variables: VariableSet

Variables and positional parameters defined in the environment

any: DataSet

Abstract container that can store any type-erased data

system: SharedSystem

Interface to the system-managed parts of the environment

Implementations

impl Env

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.

impl Env

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 pop_frame(guard: EnvFrameGuard<'_>) -> Frame

Pops the topmost frame from the runtime execution context stack.

impl 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.

pub fn pop_context(guard: EnvContextGuard<'_>)

Pops the topmost context from the variable set.

impl Env

pub fn with_system(system: Box<dyn System>) -> Env

Creates a new environment with the given system.

Members of the new environments are default-constructed except that:

• main_pid is initialized as system.getpid()
• system is initialized as SharedSystem::new(system)

pub fn new_virtual() -> Env

Creates a new environment with a default-constructed VirtualSystem.

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: Result)

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.

Trait Implementations

impl Clone for Env

fn clone(&self) -> Env

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Env

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

Formats the value using the given formatter.

impl Glossary for Env

Allows to look up aliases in the environment.

This implementation delegates to self.aliases.

fn look_up(&self, name: &str) -> Option<Rc<Alias>>

Looks up an alias by name.

fn is_empty(&self) -> bool

Returns whether the glossary is empty.

impl Glossary for Env

Determines whether a command name is a declaration utility.

This implementation looks up the command name in self.builtins and returns the value of is_declaration_utility if the built-in is found. Otherwise, the command is not a declaration utility.

fn is_declaration_utility(&self, name: &str) -> Option<bool>

Returns whether the given command name is a declaration utility.