yash_env/

lib.rs

// This file is part of yash, an extended POSIX shell.
// Copyright (C) 2021 WATANABE Yuki
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! This crate defines the shell execution environment.
//!
//! A shell execution environment, [`Env`], is a collection of data that may
//! affect or be affected by the execution of commands. The environment consists
//! of application-managed parts and system-managed parts. Application-managed
//! parts are implemented in pure Rust in this crate. Many application-managed
//! parts like [function]s and [variable]s can be manipulated independently of
//! interactions with the underlying system. System-managed parts, on the other
//! hand, reside in the underlying system. Attributes like the working directory
//! and umask are managed by the system to be accessed only by interaction with
//! the system interface.
//!
//! Traits declared in the [`system`] module define the interface to the
//! system-managed parts of the environment.
//! [`RealSystem`] provides an implementation that interacts with the actual
//! underlying system. [`VirtualSystem`] simulates a system in memory for
//! testing purposes. [`Concurrent`] is a wrapper that adds support for
//! concurrent execution of multiple tasks on top of any system that implements
//! the required traits.
//!
//! We assume that the shell process is single-threaded. This means that the
//! shell process itself must not create threads, and all interactions with the
//! system must be performed in the main thread. Using any items in this crate
//! in a multi-threaded context is not supported and may cause undefined
//! behavior. This prerequisite still applies even when a [`VirtualSystem`]
//! simulates concurrent execution of multiple processes, which run as
//! asynchronous tasks.

use self::alias::AliasSet;
use self::any::DataSet;
use self::builtin::Builtin;
use self::fork::ForkEnvState;
use self::function::FunctionSet;
use self::io::Fd;
use self::job::JobList;
use self::job::Pid;
use self::job::ProcessResult;
use self::job::ProcessState;
use self::job::RunBlocking;
use self::job::RunUnblocking;
use self::option::On;
use self::option::OptionSet;
use self::option::{AllExport, ErrExit, Interactive, Monitor};
use self::semantics::Divert;
use self::semantics::ExitStatus;
use self::stack::Frame;
use self::stack::Stack;
use self::system::Close;
use self::system::Concurrent;
use self::system::Dup;
use self::system::Errno;
use self::system::Fork;
use self::system::Fstat;
use self::system::GetCwd;
use self::system::GetPid;
use self::system::Isatty;
use self::system::Mode;
use self::system::OfdAccess;
use self::system::Open;
use self::system::OpenFlag;
use self::system::SignalList;
#[allow(deprecated, reason = "for backward compatible API")]
pub use self::system::System;
use self::system::TcSetPgrp;
use self::system::Wait;
use self::system::concurrency::Select;
use self::system::concurrency::WaitForSignals;
#[cfg(unix)]
pub use self::system::real::RealSystem;
pub use self::system::r#virtual::VirtualSystem;
use self::trap::SignalSystem;
use self::trap::TrapSet;
use self::variable::PPID;
use self::variable::Scope;
use self::variable::VariableRefMut;
use self::variable::VariableSet;
use std::collections::HashMap;
use std::fmt::Debug;
use std::ops::ControlFlow::{self, Break, Continue};
use std::pin::pin;
use std::rc::Rc;
use std::task::Context;
use std::task::Poll;
use std::task::Waker;
pub use unix_path as path;
pub use unix_str as str;

/// Whole shell execution environment.
///
/// See the [module-level documentation](self) for details.
///
/// This struct is typically instantiated as `Env<Rc<Concurrent<RealSystem>>>`
/// in the actual shell, but it can be used with other system types for testing
/// or other purposes. For example, `Env<VirtualSystem>` can be used for testing
/// without concurrency, and `Env<Rc<Concurrent<VirtualSystem>>>` can be used
/// for testing with concurrency.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Env<S> {
    /// Aliases defined in the environment
    pub aliases: AliasSet,

    /// Name of the current shell executable or shell script
    ///
    /// Special parameter `0` expands to this value.
    pub arg0: String,

    /// Built-in utilities available in the environment
    pub builtins: HashMap<&'static str, Builtin<S>>,

    /// Exit status of the last executed command
    pub exit_status: ExitStatus,

    /// Functions defined in the environment
    pub functions: FunctionSet<S>,

    /// Jobs managed in the environment
    pub jobs: JobList,

    /// Process group ID of the main shell process
    pub main_pgid: Pid,

    /// Process ID of the main shell process
    ///
    /// This PID represents the value of the `$` special parameter.
    pub main_pid: Pid,

    /// Shell option settings
    pub options: OptionSet,

    /// Runtime execution context stack
    pub stack: Stack,

    /// Traps defined in the environment
    pub traps: TrapSet,

    /// File descriptor to the controlling terminal
    ///
    /// [`get_tty`](Self::get_tty) saves a file descriptor in this variable, so
    /// you don't have to prepare it yourself.
    pub tty: Option<Fd>,

    /// Variables and positional parameters defined in the environment
    pub variables: VariableSet,

    /// Abstract container that can store any type-erased data
    pub any: DataSet,

    /// Interface to the system-managed parts of the environment
    pub system: S,
}

impl<S> Env<S> {
    /// Creates a new environment with the given system.
    ///
    /// Members of the new environments are default-constructed except that:
    /// - `main_pgid` is initialized as `system.getpgrp()`
    /// - `main_pid` is initialized as `system.getpid()`
    /// - `system` is initialized as the provided `system` instance
    #[must_use]
    pub fn with_system(system: S) -> Self
    where
        S: GetPid,
    {
        Env {
            aliases: Default::default(),
            arg0: Default::default(),
            builtins: Default::default(),
            exit_status: Default::default(),
            functions: Default::default(),
            jobs: Default::default(),
            main_pgid: system.getpgrp(),
            main_pid: system.getpid(),
            options: Default::default(),
            stack: Default::default(),
            traps: Default::default(),
            tty: Default::default(),
            variables: Default::default(),
            any: Default::default(),
            system,
        }
    }

    /// Clones this environment.
    ///
    /// The application-managed parts of the environment are cloned normally.
    /// The system-managed parts are replaced with the provided `System`
    /// instance.
    #[must_use]
    pub fn clone_with_system(&self, system: S) -> Self {
        Env {
            aliases: self.aliases.clone(),
            arg0: self.arg0.clone(),
            builtins: self.builtins.clone(),
            exit_status: self.exit_status,
            functions: self.functions.clone(),
            jobs: self.jobs.clone(),
            main_pgid: self.main_pgid,
            main_pid: self.main_pid,
            options: self.options,
            stack: self.stack.clone(),
            traps: self.traps.clone(),
            tty: self.tty,
            variables: self.variables.clone(),
            any: self.any.clone(),
            system,
        }
    }
}

impl<S> Default for Env<S>
where
    S: Default + GetPid,
{
    /// Creates a new environment with a default-constructed system.
    ///
    /// This is equivalent to `Env::with_system(S::default())`.
    fn default() -> Self {
        Self::with_system(S::default())
    }
}

impl Env<Rc<Concurrent<VirtualSystem>>> {
    /// Creates a new environment with a default-constructed [`VirtualSystem`]
    /// wrapped in [`Concurrent`].
    ///
    /// This is equivalent to `Env::<Rc<Concurrent<VirtualSystem>>>::default()`,
    /// but more explicit about the type of the system.
    #[must_use]
    pub fn new_virtual() -> Self {
        Self::default()
    }
}

impl<S> Env<S> {
    /// 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 fn init_variables(&mut self)
    where
        S: Fstat + GetCwd + GetPid,
    {
        self.variables.init();

        self.variables
            .get_or_new(PPID, Scope::Global)
            .assign(self.system.getppid().to_string(), None)
            .ok();

        self.prepare_pwd().ok();
    }

    /// Waits for some signals to be caught in the current process.
    ///
    /// Returns an array of signals caught.
    ///
    /// This function is a wrapper for [`WaitForSignals::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_signals(&mut self) -> Rc<SignalList>
    where
        S: WaitForSignals,
    {
        let result = self.system.wait_for_signals().await;
        for signal in result.iter().copied() {
            self.traps.catch_signal(signal);
        }
        result
    }

    /// Waits for a specific signal to be caught in the current process.
    ///
    /// This function calls [`wait_for_signals`](Self::wait_for_signals)
    /// repeatedly until it returns results containing the specified `signal`.
    pub async fn wait_for_signal(&mut self, signal: signal::Number)
    where
        S: WaitForSignals,
    {
        while !self.wait_for_signals().await.contains(&signal) {}
    }

    /// Returns signals that have been caught.
    ///
    /// This function is similar to
    /// [`wait_for_signals`](Self::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 system. If no signals have been
    /// caught, it returns `None`.
    ///
    /// 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 fn poll_signals(&mut self) -> Option<Rc<SignalList>>
    where
        S: WaitForSignals + Select,
    {
        fn poll<S: WaitForSignals + Select>(system: &S) -> Option<Rc<SignalList>> {
            let mut future = pin!(system.wait_for_signals());
            let mut context = Context::from_waker(Waker::noop());

            // Check if the result is ready before peeking the system
            if let Poll::Ready(signals) = future.as_mut().poll(&mut context) {
                return Some(signals);
            }

            // Peek to handle any pending signals
            system.peek();

            // Check again if the result is ready after peeking
            if let Poll::Ready(signals) = future.poll(&mut context) {
                return Some(signals);
            }

            None
        }

        let signals = poll(&self.system);
        if let Some(signals) = &signals {
            for signal in signals.iter().copied() {
                self.traps.catch_signal(signal);
            }
        }
        signals
    }

    /// Whether error messages should be printed in color
    ///
    /// This function decides whether messages printed to the standard error
    /// should contain ANSI color escape sequences. The result is true only if
    /// the standard error is a terminal.
    ///
    /// The current implementation simply checks if the standard error is a
    /// terminal. This will be changed in the future to support user
    /// configuration.
    #[must_use]
    fn should_print_error_in_color(&self) -> bool
    where
        S: Isatty,
    {
        // TODO Enable color depending on user config (force/auto/never)
        // TODO Check if the terminal really supports color (needs terminfo)
        self.system.isatty(Fd::STDERR)
    }

    /// 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 async fn get_tty(&mut self) -> Result<Fd, Errno>
    where
        S: Open + Dup + Close,
    {
        if let Some(fd) = self.tty {
            return Ok(fd);
        }

        let first_fd = {
            // POSIX.1-2024 Job control specifications are written in the
            // assumption that a job-control shell may not have a control
            // terminal. The shell should not make an arbitrary terminal its
            // control terminal, so we open /dev/tty with NoCtty.
            let mut result = self
                .system
                .open(
                    c"/dev/tty",
                    OfdAccess::ReadWrite,
                    OpenFlag::CloseOnExec | OpenFlag::NoCtty,
                    Mode::empty(),
                )
                .await;
            if result == Err(Errno::EINVAL) {
                // However, some systems do not support NoCtty. In that case,
                // we open /dev/tty without NoCtty.
                result = self
                    .system
                    .open(
                        c"/dev/tty",
                        OfdAccess::ReadWrite,
                        OpenFlag::CloseOnExec.into(),
                        Mode::empty(),
                    )
                    .await;
            }
            result?
        };

        let final_fd = io::move_fd_internal(&self.system, first_fd);
        self.tty = final_fd.ok();
        final_fd
    }

    /// 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 [`job::tcsetpgrp_with_block`]. Otherwise, this function
    /// suspends the process until it is resumed in the foreground by another
    /// job-controlling process (see [`job::tcsetpgrp_without_block`]).
    ///
    /// This function returns an error if the process does not have a controlling
    /// terminal, that is, [`get_tty`](Self::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 async fn ensure_foreground(&mut self) -> Result<(), Errno>
    where
        S: Open + Dup + Close + GetPid + RunBlocking + RunUnblocking + TcSetPgrp,
    {
        let fd = self.get_tty().await?;

        if self.system.getsid(Pid(0)) == Ok(self.main_pgid) {
            job::tcsetpgrp_with_block(&self.system, fd, self.main_pgid).await
        } else {
            job::tcsetpgrp_without_block(&self.system, fd, self.main_pgid).await
        }
    }

    /// Runs a task in a new child process.
    ///
    /// This function creates a new child process and runs the given
    /// `child_task` in it. The `shared_data` is passed to the child task as an
    /// argument and also returned to the caller. The signature of this method
    /// is analogous to [`Fork::run_in_child_process`] but the child task
    /// receives a clone of the current `Env` instead of the inner `Concurrent`
    /// instance.
    ///
    /// You should generally use [`Subshell`](crate::subshell::Subshell) instead
    /// of this method to create a subshell, so that the environment can
    /// condition the state of the child process before it starts running.
    pub fn run_in_child_process<D, F>(
        &mut self,
        shared_data: D,
        child_task: F,
    ) -> (Result<Pid, Errno>, D)
    where
        S: Fork + 'static,
        D: Clone + 'static,
        F: AsyncFnOnce(Self, D) + 'static,
    {
        let state = ForkEnvState::extract_from_env(self);

        let (pid_or_error, (state, shared_data)) = self.system.run_in_child_process(
            (state, shared_data),
            |child_system, (state, shared_data): (ForkEnvState<S>, D)| async move {
                let child_env = state.into_env_with_system(child_system);
                child_task(child_env, shared_data).await
            },
        );

        state.restore_into_env(self);

        (pid_or_error, shared_data)
    }

    /// 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`](Wait::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`](Self::wait_for_subshell_to_finish)
    /// instead.
    pub async fn wait_for_subshell(&mut self, target: Pid) -> Result<(Pid, ProcessState), Errno>
    where
        S: SignalSystem + WaitForSignals + Wait,
    {
        // We need to set the internal disposition before calling `wait` so we don't
        // miss any `SIGCHLD` that may arrive between `wait` and `wait_for_signal`.
        self.traps
            .enable_internal_disposition_for_sigchld(&self.system)
            .await?;

        loop {
            if let Some((pid, state)) = self.system.wait(target)? {
                self.jobs.update_status(pid, state);
                return Ok((pid, state));
            }
            self.wait_for_signal(S::SIGCHLD).await;
        }
    }

    /// Wait for a subshell to terminate or suspend.
    ///
    /// This function is similar to
    /// [`wait_for_subshell`](Self::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_halt(
        &mut self,
        target: Pid,
    ) -> Result<(Pid, ProcessResult), Errno>
    where
        S: SignalSystem + WaitForSignals + Wait,
    {
        loop {
            let (pid, state) = self.wait_for_subshell(target).await?;
            if let ProcessState::Halted(result) = state {
                return Ok((pid, result));
            }
        }
    }

    /// Wait for a subshell to terminate.
    ///
    /// This function is similar to
    /// [`wait_for_subshell`](Self::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 async fn wait_for_subshell_to_finish(
        &mut self,
        target: Pid,
    ) -> Result<(Pid, ExitStatus), Errno>
    where
        S: SignalSystem + WaitForSignals + Wait,
    {
        loop {
            let (pid, result) = self.wait_for_subshell_to_halt(target).await?;
            if !result.is_stopped() {
                return Ok((pid, result.into()));
            }
        }
    }

    /// Applies all job status updates to jobs in `self.jobs`.
    ///
    /// This function calls [`self.system.wait`](Wait::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 update_all_subshell_statuses(&mut self)
    where
        S: Wait,
    {
        while let Ok(Some((pid, state))) = self.system.wait(Pid::ALL) {
            self.jobs.update_status(pid, state);
        }
    }

    /// 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`).
    #[must_use]
    pub fn is_interactive(&self) -> bool {
        self.options.get(Interactive) == On && !self.stack.contains(&Frame::Subshell)
    }

    /// 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`).
    #[must_use]
    pub fn controls_jobs(&self) -> bool {
        self.options.get(Monitor) == On && !self.stack.contains(&Frame::Subshell)
    }

    /// 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](VariableRefMut::export) 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 get_or_create_variable<N>(&mut self, name: N, scope: Scope) -> VariableRefMut<'_>
    where
        N: Into<String>,
    {
        let mut variable = self.variables.get_or_new(name, scope);
        if self.options.get(AllExport) == On {
            variable.export(true);
        }
        variable
    }

    /// 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.
    ///
    /// [`Condition`]: Frame::Condition
    pub fn errexit_is_applicable(&self) -> bool {
        self.options.get(ErrExit) == On && !self.stack.contains(&Frame::Condition)
    }

    /// 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](Self::errexit_is_applicable) and the current
    /// `self.exit_status` is non-zero. Otherwise, it returns `Continue(())`.
    pub fn apply_errexit(&self) -> ControlFlow<Divert> {
        if !self.exit_status.is_successful() && self.errexit_is_applicable() {
            Break(Divert::Exit(None))
        } else {
            Continue(())
        }
    }

    /// 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 apply_result(&mut self, result: crate::semantics::Result) {
        match result {
            Continue(_) => {}
            Break(divert) => {
                if let Some(exit_status) = divert.exit_status() {
                    self.exit_status = exit_status;
                }
            }
        }
    }
}

pub mod alias;
pub mod any;
pub mod builtin;
pub mod decl_util;
pub mod function;
pub mod input;
pub mod io;
pub mod job;
pub mod option;
pub mod parser;
pub mod prompt;
pub mod pwd;
pub mod semantics;
pub mod signal;
pub mod source;
pub mod stack;
pub mod subshell;
pub mod system;
pub mod trap;
pub mod variable;
pub mod waker;

mod fork;

#[cfg(any(test, feature = "yash-executor"))]
mod executor_helper;
#[cfg(any(test, feature = "test-helper"))]
pub mod test_helper;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::io::MIN_INTERNAL_FD;
    use crate::job::Job;
    use crate::source::Location;
    use crate::subshell::Config;
    use crate::system::Exit as _;
    use crate::system::Sigset as _;
    use crate::system::r#virtual::Inode;
    use crate::system::r#virtual::SIGCHLD;
    use crate::test_helper::in_virtual_system;
    use crate::trap::Action;
    use futures_executor::LocalPool;
    use futures_util::FutureExt as _;
    use std::cell::Cell;
    use std::cell::RefCell;

    #[test]
    fn wait_for_signal_remembers_signal_in_trap_set() {
        in_virtual_system(|mut env, state| async move {
            env.traps
                .set_action(
                    &env.system,
                    SIGCHLD,
                    Action::Command("".into()),
                    Location::dummy(""),
                    false,
                )
                .await
                .unwrap();
            {
                let mut state = state.borrow_mut();
                let process = state.processes.get_mut(&env.main_pid).unwrap();
                assert_eq!(process.blocked_signals().contains(SIGCHLD), Ok(true));
                let _ = process.raise_signal(SIGCHLD);
            }
            env.wait_for_signal(SIGCHLD).await;

            let trap_state = env.traps.get_state(SIGCHLD).0.unwrap();
            assert!(trap_state.pending);
        })
    }

    fn poll_signals_env() -> (Env<Rc<Concurrent<VirtualSystem>>>, VirtualSystem) {
        let system = VirtualSystem::new();
        let mut env = Env::with_system(Rc::new(Concurrent::new(system.clone())));
        env.traps
            .set_action(
                &env.system,
                SIGCHLD,
                Action::Command("".into()),
                Location::dummy(""),
                false,
            )
            .now_or_never()
            .unwrap()
            .unwrap();
        (env, system)
    }

    #[test]
    fn poll_signals_none() {
        let mut env = poll_signals_env().0;
        let result = env.poll_signals();
        assert_eq!(result, None);
    }

    #[test]
    fn poll_signals_some() {
        let (mut env, system) = poll_signals_env();
        {
            let mut state = system.state.borrow_mut();
            let process = state.processes.get_mut(&system.process_id).unwrap();
            assert_eq!(process.blocked_signals().contains(SIGCHLD), Ok(true));
            let _ = process.raise_signal(SIGCHLD);
        }

        let result = env.poll_signals().unwrap();
        assert_eq!(result.as_slice(), [SIGCHLD]);
    }

    #[test]
    fn get_tty_opens_tty() {
        let system = VirtualSystem::new();
        let tty = Rc::new(RefCell::new(Inode::new([])));
        system
            .state
            .borrow_mut()
            .file_system
            .save("/dev/tty", Rc::clone(&tty))
            .unwrap();
        let mut env = Env::with_system(system.clone());

        let fd = env.get_tty().now_or_never().unwrap().unwrap();
        assert!(
            fd >= MIN_INTERNAL_FD,
            "get_tty returned {fd}, which should be >= {MIN_INTERNAL_FD}"
        );
        system
            .with_open_file_description(fd, |ofd| {
                assert!(Rc::ptr_eq(ofd.inode(), &tty));
                Ok(())
            })
            .unwrap();

        system.state.borrow_mut().file_system = Default::default();

        // get_tty returns cached FD
        let fd = env.get_tty().now_or_never().unwrap().unwrap();
        system
            .with_open_file_description(fd, |ofd| {
                assert!(Rc::ptr_eq(ofd.inode(), &tty));
                Ok(())
            })
            .unwrap();
    }

    #[test]
    fn run_in_child_process_runs_child_and_returns_shared_data() {
        in_virtual_system(|mut env, _state| async move {
            let parent_pid = env.system.getpid();
            let child_seen_pid = Rc::new(Cell::new(None));
            let child_seen_ppid = Rc::new(Cell::new(None));
            let child_seen_pid_2 = Rc::clone(&child_seen_pid);
            let child_seen_ppid_2 = Rc::clone(&child_seen_ppid);

            let (result, shared_data) = env.run_in_child_process(
                42_u32,
                |child_env: Env<Rc<Concurrent<VirtualSystem>>>, data| async move {
                    assert_eq!(data, 42);
                    child_seen_pid_2.set(Some(child_env.system.getpid()));
                    child_seen_ppid_2.set(Some(child_env.system.getppid()));
                    child_env.system.exit(ExitStatus(13)).await;
                },
            );

            assert_eq!(shared_data, 42);
            let child_pid = result.unwrap();
            assert_ne!(child_pid, parent_pid);
            assert_eq!(
                env.wait_for_subshell(child_pid).await,
                Ok((child_pid, ProcessState::exited(13)))
            );
            assert_eq!(child_seen_pid.get(), Some(child_pid));
            assert_eq!(child_seen_ppid.get(), Some(parent_pid));
        });
    }

    #[test]
    fn run_in_child_process_passes_clone_of_parent_env_to_child() {
        in_virtual_system(|mut env, _state| async move {
            env.arg0 = "parent-shell".to_string();
            env.exit_status = ExitStatus(5);
            env.variables
                .get_or_new("PARENT", Scope::Global)
                .assign("before", None)
                .unwrap();

            let (result, ()) = env.run_in_child_process(
                (),
                |child_env: Env<Rc<Concurrent<VirtualSystem>>>, ()| async move {
                    assert_eq!(child_env.arg0, "parent-shell");
                    assert_eq!(child_env.exit_status, ExitStatus(5));
                    assert_eq!(child_env.variables.get_scalar("PARENT"), Some("before"));
                    child_env.system.exit(ExitStatus(0)).await;
                },
            );

            let child_pid = result.unwrap();
            _ = env.wait_for_subshell(child_pid).await;
        })
    }

    #[test]
    fn run_in_child_process_restores_parent_environment() {
        in_virtual_system(|mut env, _state| async move {
            env.arg0 = "parent-shell".to_string();
            env.exit_status = ExitStatus(5);
            env.variables
                .get_or_new("PARENT", Scope::Global)
                .assign("before", None)
                .unwrap();

            let (result, ()) = env.run_in_child_process(
                (),
                |mut child_env: Env<Rc<Concurrent<VirtualSystem>>>, ()| async move {
                    child_env
                        .variables
                        .get_or_new("PARENT", Scope::Global)
                        .assign("after", None)
                        .unwrap();
                    child_env.system.exit(ExitStatus(0)).await;
                },
            );

            let child_pid = result.unwrap();
            assert_eq!(
                env.wait_for_subshell(child_pid).await,
                Ok((child_pid, ProcessState::exited(0)))
            );
            assert_eq!(env.arg0, "parent-shell");
            assert_eq!(env.exit_status, ExitStatus(5));
            assert_eq!(env.variables.get_scalar("PARENT"), Some("before"));
        });
    }

    #[test]
    fn start_and_wait_for_subshell() {
        in_virtual_system(|mut env, _state| async move {
            let (pid, _) = Config::new()
                .start(&mut env, async |env, _job_control| {
                    env.exit_status = ExitStatus(42)
                })
                .await
                .unwrap();
            let result = env.wait_for_subshell(pid).await;
            assert_eq!(result, Ok((pid, ProcessState::exited(42))));
        });
    }

    #[test]
    fn start_and_wait_for_subshell_with_job_list() {
        in_virtual_system(|mut env, _state| async move {
            let (pid, _) = Config::new()
                .start(&mut env, async |env, _job_control| {
                    env.exit_status = ExitStatus(42)
                })
                .await
                .unwrap();
            let mut job = Job::new(pid);
            job.name = "my job".to_string();
            let job_index = env.jobs.add(job.clone());
            let result = env.wait_for_subshell(pid).await;
            assert_eq!(result, Ok((pid, ProcessState::exited(42))));
            job.state = ProcessState::exited(42);
            assert_eq!(env.jobs[job_index], job);
        });
    }

    #[test]
    fn wait_for_subshell_no_subshell() {
        let system = VirtualSystem::new();
        let mut executor = LocalPool::new();
        system.state.borrow_mut().executor = Some(Rc::new(executor.spawner()));
        let mut env = Env::with_system(Rc::new(Concurrent::new(system)));
        executor.run_until(async move {
            let result = env.wait_for_subshell(Pid::ALL).await;
            assert_eq!(result, Err(Errno::ECHILD));
        });
    }

    #[test]
    fn update_all_subshell_statuses_without_subshells() {
        let mut env = Env::new_virtual();
        env.update_all_subshell_statuses();
    }

    #[test]
    fn update_all_subshell_statuses_with_subshells() {
        let system = VirtualSystem::new();
        let mut executor = futures_executor::LocalPool::new();
        system.state.borrow_mut().executor = Some(Rc::new(executor.spawner()));

        let mut env = Env::with_system(Rc::new(Concurrent::new(system)));

        let [job_1, job_2, job_3] = executor.run_until(async {
            // Run a subshell.
            let (pid_1, _) = Config::new()
                .start(&mut env, async |env, _job_control| {
                    env.exit_status = ExitStatus(12)
                })
                .await
                .unwrap();

            // Run another subshell.
            let (pid_2, _) = Config::new()
                .start(&mut env, async |env, _job_control| {
                    env.exit_status = ExitStatus(35)
                })
                .await
                .unwrap();

            // This one will never finish.
            let (pid_3, _) = Config::new()
                .start(&mut env, async |_env, _job_control| {
                    futures_util::future::pending().await
                })
                .await
                .unwrap();

            // Yet another subshell. We don't make this into a job.
            let (_pid_4, _) = Config::new()
                .start(&mut env, async |env, _job_control| {
                    env.exit_status = ExitStatus(100)
                })
                .await
                .unwrap();

            // Create jobs.
            let job_1 = env.jobs.add(Job::new(pid_1));
            let job_2 = env.jobs.add(Job::new(pid_2));
            let job_3 = env.jobs.add(Job::new(pid_3));
            [job_1, job_2, job_3]
        });

        // Let the jobs (except job_3) finish.
        executor.run_until_stalled();

        // We're not yet updated.
        assert_eq!(env.jobs[job_1].state, ProcessState::Running);
        assert_eq!(env.jobs[job_2].state, ProcessState::Running);
        assert_eq!(env.jobs[job_3].state, ProcessState::Running);

        env.update_all_subshell_statuses();

        // Now we have the results.
        // TODO assert_eq!(env.jobs[job_1].state, ProcessState::Exited(ExitStatus(12)));
        // TODO assert_eq!(env.jobs[job_2].state, ProcessState::Exited(ExitStatus(35)));
        assert_eq!(env.jobs[job_3].state, ProcessState::Running);
    }

    #[test]
    fn get_or_create_variable_with_all_export_off() {
        let mut env = Env::new_virtual();
        let mut a = env.get_or_create_variable("a", Scope::Global);
        assert!(!a.is_exported);
        a.export(true);
        let a = env.get_or_create_variable("a", Scope::Global);
        assert!(a.is_exported);
    }

    #[test]
    fn get_or_create_variable_with_all_export_on() {
        let mut env = Env::new_virtual();
        env.options.set(AllExport, On);
        let mut a = env.get_or_create_variable("a", Scope::Global);
        assert!(a.is_exported);
        a.export(false);
        let a = env.get_or_create_variable("a", Scope::Global);
        assert!(a.is_exported);
    }

    #[test]
    fn errexit_on() {
        let mut env = Env::new_virtual();
        env.exit_status = ExitStatus::FAILURE;
        env.options.set(ErrExit, On);
        assert_eq!(env.apply_errexit(), Break(Divert::Exit(None)));
    }

    #[test]
    fn errexit_with_zero_exit_status() {
        let mut env = Env::new_virtual();
        env.options.set(ErrExit, On);
        assert_eq!(env.apply_errexit(), Continue(()));
    }

    #[test]
    fn errexit_in_condition() {
        let mut env = Env::new_virtual();
        env.exit_status = ExitStatus::FAILURE;
        env.options.set(ErrExit, On);
        let env = env.push_frame(Frame::Condition);
        assert_eq!(env.apply_errexit(), Continue(()));
    }

    #[test]
    fn errexit_off() {
        let mut env = Env::new_virtual();
        env.exit_status = ExitStatus::FAILURE;
        assert_eq!(env.apply_errexit(), Continue(()));
    }

    #[test]
    fn apply_result_with_continue() {
        let mut env = Env::new_virtual();
        env.apply_result(Continue(()));
        assert_eq!(env.exit_status, ExitStatus::default());
    }

    #[test]
    fn apply_result_with_divert_without_exit_status() {
        let mut env = Env::new_virtual();
        env.apply_result(Break(Divert::Exit(None)));
        assert_eq!(env.exit_status, ExitStatus::default());
    }

    #[test]
    fn apply_result_with_divert_with_exit_status() {
        let mut env = Env::new_virtual();
        env.apply_result(Break(Divert::Exit(Some(ExitStatus(67)))));
        assert_eq!(env.exit_status, ExitStatus(67));
    }
}