Struct VirtualSystem 

pub struct VirtualSystem {
    pub state: Rc<RefCell<SystemState>>,
    pub process_id: Pid,
}

Simulated system

See the module-level documentation to grasp a basic understanding of VirtualSystem.

A VirtualSystem instance has two members: state and process_id. The former is a SystemState that effectively contains the whole state of the system. The state is contained in Rc so that virtual processes can share the same state. The latter is a process ID that identifies a process calling the system interfaces.

When you clone a virtual system, the clone will have the same process_id and state as the original. To simulate the fork system call, you should call a method of the Fork trait implemented by VirtualSystem.

Fields

state: Rc<RefCell<SystemState>>

State of the system.

process_id: Pid

Process ID of the process that is interacting with the system.

Implementations

impl VirtualSystem

pub fn new() -> VirtualSystem

Creates a virtual system with an almost empty state.

The process_id of the returned VirtualSystem will be 2. (Process ID 1 has special meaning in some system calls, so we don’t use it as a default value.)

The state of the returned VirtualSystem will have a Process with process ID 2 in the process set (SystemState::processes). The file system will contain files named /dev/stdin, /dev/stdout, and /dev/stderr that are opened in the process with file descriptor 0, 1, and 2, respectively. The file system also contains an empty directory /tmp.

pub fn current_process(&self) -> Ref<'_, Process>

Finds the current process from the system state.

Panics

This function will panic if it cannot find a process having self.process_id.

pub fn current_process_mut(&self) -> RefMut<'_, Process>

Finds the current process from the system state.

Panics

This function will panic if it cannot find a process having self.process_id.

pub fn get_open_file_description( &self, fd: Fd, ) -> Result<Rc<RefCell<OpenFileDescription>>>

Returns the open file description for the given FD.

This is a helper function for obtaining the open file description for a given file descriptor in the current process. Returns Err(Errno::EBADF) if the FD is not open.

pub fn with_open_file_description<F, R>(&self, fd: Fd, f: F) -> Result<R>

where F: FnOnce(&OpenFileDescription) -> Result<R>,

Calls the given closure passing the open file description for the FD.

This is a helper function for performing an operation on the open file description for a given file descriptor in the current process. The closure is passed a reference to the open file description, and can perform any operation on it, such as checking its state. The return value of the closure is returned as the result of this function.

Returns Err(Errno::EBADF) if the FD is not open. Panics if the open file description is already mutably borrowed.

pub fn with_open_file_description_mut<F, R>(&self, fd: Fd, f: F) -> Result<R>

where F: FnOnce(&mut OpenFileDescription) -> Result<R>,

Calls the given closure passing the open file description for the FD.

This is a helper function for performing a mutable operation on the open file description for a given file descriptor in the current process. The closure is passed a mutable reference to the open file description, and can perform any operation on it, such as reading and writing. The return value of the closure is returned as the result of this function.

Returns Err(Errno::EBADF) if the FD is not open. Panics if the open file description is already borrowed.

Trait Implementations

impl CaughtSignals for VirtualSystem

fn caught_signals(&self) -> Vec<Number>

Returns signals this process has caught, if any.

impl Chdir for VirtualSystem

fn chdir(&self, path: &CStr) -> Result<()>

Changes the working directory.

impl Clock for VirtualSystem

fn now(&self) -> Instant

Returns now in SystemState.

Panics if it is None.

impl Clone for VirtualSystem

fn clone(&self) -> VirtualSystem

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Close for VirtualSystem

fn close(&self, fd: Fd) -> Result<()>

Closes a file descriptor.

impl Debug for VirtualSystem

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

Formats the value using the given formatter.

impl Default for VirtualSystem

fn default() -> Self

Returns the “default value” for a type.

impl Dup for VirtualSystem

fn dup(&self, from: Fd, to_min: Fd, flags: EnumSet<FdFlag>) -> Result<Fd>

Duplicates a file descriptor.

fn dup2(&self, from: Fd, to: Fd) -> Result<Fd>

Duplicates a file descriptor.

impl Exec for VirtualSystem

fn execve( &self, path: &CStr, args: &[CString], envs: &[CString], ) -> impl Future<Output = Result<Infallible>> + use<>

Stub for the execve system call.

The execve system call cannot be simulated in the userland. This function returns ENOSYS if the file at path is a native executable, ENOEXEC if a non-executable file, and ENOENT otherwise.

impl Exit for VirtualSystem

fn exit( &self, exit_status: ExitStatus, ) -> impl Future<Output = Infallible> + use<>

Terminates the current process.

impl Fcntl for VirtualSystem

fn ofd_access(&self, fd: Fd) -> Result<OfdAccess>

Returns the open file description access mode.

fn get_and_set_nonblocking(&self, fd: Fd, nonblocking: bool) -> Result<bool>

Gets and sets the non-blocking mode for the open file description.

fn fcntl_getfd(&self, fd: Fd) -> Result<EnumSet<FdFlag>>

Returns the attributes for the file descriptor.

fn fcntl_setfd(&self, fd: Fd, flags: EnumSet<FdFlag>) -> Result<()>

Sets attributes for the file descriptor.

impl Fork for VirtualSystem

fn new_child_process(&self) -> Result<ChildProcessStarter<Self>>

Creates a new child process.

This implementation does not create any real child process. Instead, it returns a child process starter that runs its task concurrently in the same process.

To run the concurrent task, this function needs an executor that has been set in the SystemState. If the system state does not have an executor, this function fails with Errno::ENOSYS.

The process ID of the child will be the maximum of existing process IDs plus 1. If there are no other processes, it will be 2.

impl Fstat for VirtualSystem

type Stat = Stat

Metadata type returned by fstat and fstatat

fn fstat(&self, fd: Fd) -> Result<Stat>

Retrieves metadata of a file.

fn fstatat( &self, dir_fd: Fd, path: &CStr, follow_symlinks: bool, ) -> Result<Stat>

Retrieves metadata of a file.

fn is_directory(&self, path: &CStr) -> bool

Whether there is a directory at the specified path.

fn fd_is_pipe(&self, fd: Fd) -> bool

Tests if a file descriptor is a pipe.

impl GetCwd for VirtualSystem

fn getcwd(&self) -> Result<PathBuf>

Returns the current working directory path.

impl GetPid for VirtualSystem

fn getsid(&self, pid: Pid) -> Result<Pid>

Currently, this function always returns Pid(2) if the process exists.

fn getpid(&self) -> Pid

Returns the process ID of the current process.

fn getppid(&self) -> Pid

Returns the process ID of the parent process.

fn getpgrp(&self) -> Pid

Returns the process group ID of the current process.

impl GetPw for VirtualSystem

fn getpwnam_dir(&self, name: &CStr) -> Result<Option<PathBuf>>

Returns the home directory path of the given user.

impl GetRlimit for VirtualSystem

fn getrlimit(&self, resource: Resource) -> Result<LimitPair>

Returns the limits for the specified resource.

impl GetSigaction for VirtualSystem

fn get_sigaction(&self, signal: Number) -> Result<Disposition>

Gets the disposition for a signal.

impl GetUid for VirtualSystem

fn getuid(&self) -> Uid

Returns the real user ID of the current process.

fn geteuid(&self) -> Uid

Returns the effective user ID of the current process.

fn getgid(&self) -> Gid

Returns the real group ID of the current process.

fn getegid(&self) -> Gid

Returns the effective group ID of the current process.

impl IsExecutableFile for VirtualSystem

fn is_executable_file(&self, path: &CStr) -> bool

Tests whether the specified file is executable or not.

The current implementation only checks if the file has any executable bit in the permissions. The file owner and group are not considered.

impl Isatty for VirtualSystem

fn isatty(&self, fd: Fd) -> bool

Tests if a file descriptor is associated with a terminal device.

impl Open for VirtualSystem

fn open( &self, path: &CStr, access: OfdAccess, flags: EnumSet<OpenFlag>, mode: Mode, ) -> impl Future<Output = Result<Fd>> + use<>

Opens a file and returns a new file descriptor for it.

The returned future will be pending until the file is ready to be opened. For example, if the file is a FIFO, the future will be pending until the other end of the FIFO is opened, unless OpenFlag::NonBlock is specified.

fn open_tmpfile(&self, _parent_dir: &Path) -> Result<Fd>

Opens a file descriptor associated with an anonymous temporary file.

fn fdopendir(&self, fd: Fd) -> Result<impl Dir + use<>>

Opens a directory for enumerating entries.

fn opendir(&self, path: &CStr) -> Result<impl Dir + use<>>

Opens a directory for enumerating entries.

impl Pipe for VirtualSystem

fn pipe(&self) -> Result<(Fd, Fd)>

Creates an unnamed pipe.

impl Read for VirtualSystem

fn read<'a>( &self, fd: Fd, buffer: &'a mut [u8], ) -> impl Future<Output = Result<usize>> + use<'a>

Reads data from the file descriptor into the buffer.

If a signal is caught while this method is blocking for data, it returns Errno::EINTR.

impl Seek for VirtualSystem

fn lseek(&self, fd: Fd, position: SeekFrom) -> Result<u64>

Moves the position of the open file description.

impl Select for VirtualSystem

fn select<'a>( &self, readers: &'a mut Vec<Fd>, writers: &'a mut Vec<Fd>, timeout: Option<Duration>, signal_mask: Option<&[Number]>, ) -> impl Future<Output = Result<c_int>> + use<'a>

Waits for a next event.

The VirtualSystem implementation for this method simulates the blocking behavior of select by returning a future that becomes ready when the specified FDs are ready, the timeout expires, or a signal is delivered. However, it does not actually block the calling thread. Instead, it relies on the caller to poll the returned future to determine when the event occurs. This design allows the VirtualSystem to be used in asynchronous contexts without blocking the entire thread, while still providing the expected behavior of select.

impl SendSignal for VirtualSystem

fn kill( &self, target: Pid, signal: Option<Number>, ) -> impl Future<Output = Result<()>> + use<>

Sends a signal to the target process.

The current implementation accepts any positive signal number and None (no signal) for signal. Negative signal numbers are rejected with Errno::EINVAL.

This function returns a future that enables the executor to block the calling thread until the current process is ready to proceed. If the signal is sent to the current process and it causes the process to stop, the future will be ready only when the process is resumed. Similarly, if the signal causes the current process to terminate, the future will never be ready.

fn raise(&self, signal: Number) -> impl Future<Output = Result<()>> + use<>

Sends a signal to the current process.

impl SetPgid for VirtualSystem

fn setpgid(&self, pid: Pid, pgid: Pid) -> Result<()>

Modifies the process group ID of a process.

The current implementation does not yet support the concept of sessions.

impl SetRlimit for VirtualSystem

fn setrlimit(&self, resource: Resource, limits: LimitPair) -> Result<()>

Sets the limits for the specified resource.

impl ShellPath for VirtualSystem

fn shell_path(&self) -> CString

Returns the path to the shell.

The current implementation returns “/bin/sh”.

impl Sigaction for VirtualSystem

fn sigaction( &self, signal: Number, disposition: Disposition, ) -> Result<Disposition>

Gets and sets the disposition for a signal.

impl Sigmask for VirtualSystem

fn sigmask( &self, op: Option<(SigmaskOp, &[Number])>, old_mask: Option<&mut Vec<Number>>, ) -> impl Future<Output = Result<()>> + use<>

Gets and/or sets the signal blocking mask.

impl Signals for VirtualSystem

const SIGABRT: Number = signal::SIGABRT

The signal number for SIGABRT

const SIGALRM: Number = signal::SIGALRM

The signal number for SIGALRM

const SIGBUS: Number = signal::SIGBUS

The signal number for SIGBUS

const SIGCHLD: Number = signal::SIGCHLD

The signal number for SIGCHLD

const SIGCLD: Option<Number>

The signal number for SIGCLD, if available on the system

const SIGCONT: Number = signal::SIGCONT

The signal number for SIGCONT

const SIGEMT: Option<Number>

The signal number for SIGEMT, if available on the system

const SIGFPE: Number = signal::SIGFPE

The signal number for SIGFPE

const SIGHUP: Number = signal::SIGHUP

The signal number for SIGHUP

const SIGILL: Number = signal::SIGILL

The signal number for SIGILL

const SIGINFO: Option<Number>

The signal number for SIGINFO, if available on the system

const SIGINT: Number = signal::SIGINT

The signal number for SIGINT

const SIGIO: Option<Number>

The signal number for SIGIO, if available on the system

const SIGIOT: Number = signal::SIGIOT

The signal number for SIGIOT

const SIGKILL: Number = signal::SIGKILL

The signal number for SIGKILL

const SIGLOST: Option<Number>

The signal number for SIGLOST, if available on the system

const SIGPIPE: Number = signal::SIGPIPE

The signal number for SIGPIPE

const SIGPOLL: Option<Number>

The signal number for SIGPOLL, if available on the system

const SIGPROF: Number = signal::SIGPROF

The signal number for SIGPROF

const SIGPWR: Option<Number>

The signal number for SIGPWR, if available on the system

const SIGQUIT: Number = signal::SIGQUIT

The signal number for SIGQUIT

const SIGSEGV: Number = signal::SIGSEGV

The signal number for SIGSEGV

const SIGSTKFLT: Option<Number>

The signal number for SIGSTKFLT, if available on the system

const SIGSTOP: Number = signal::SIGSTOP

The signal number for SIGSTOP

const SIGSYS: Number = signal::SIGSYS

The signal number for SIGSYS

const SIGTERM: Number = signal::SIGTERM

The signal number for SIGTERM

const SIGTHR: Option<Number>

The signal number for SIGTHR, if available on the system

const SIGTRAP: Number = signal::SIGTRAP

The signal number for SIGTRAP

const SIGTSTP: Number = signal::SIGTSTP

The signal number for SIGTSTP

const SIGTTIN: Number = signal::SIGTTIN

The signal number for SIGTTIN

const SIGTTOU: Number = signal::SIGTTOU

The signal number for SIGTTOU

const SIGURG: Number = signal::SIGURG

The signal number for SIGURG

const SIGUSR1: Number = signal::SIGUSR1

The signal number for SIGUSR1

const SIGUSR2: Number = signal::SIGUSR2

The signal number for SIGUSR2

const SIGVTALRM: Number = signal::SIGVTALRM

The signal number for SIGVTALRM

const SIGWINCH: Number = signal::SIGWINCH

The signal number for SIGWINCH

const SIGXCPU: Number = signal::SIGXCPU

The signal number for SIGXCPU

const SIGXFSZ: Number = signal::SIGXFSZ

The signal number for SIGXFSZ

fn sigrt_range(&self) -> Option<RangeInclusive<Number>>

Returns the range of real-time signals supported by the system.

const NAMED_SIGNALS: &'static [(&'static str, Option<Number>)] = _

List of all signal names and their numbers, excluding real-time signals

fn iter_sigrt(&self) -> impl DoubleEndedIterator<Item = Number> + use<Self>

Returns an iterator over all real-time signals supported by the system.

fn to_signal_number<N: Into<RawNumber>>(&self, number: N) -> Option<Number>

Tests if a signal number is valid and returns its signal number.

fn sig2str<N: Into<RawNumber>>(&self, signal: N) -> Option<Cow<'static, str>>

Converts a signal number to its string representation.

fn str2sig(&self, name: &str) -> Option<Number>

Converts a string representation of a signal to its signal number.

fn validate_signal(&self, number: RawNumber) -> Option<(Name, Number)>

Tests if a signal number is valid and returns its name and number.

fn signal_name_from_number(&self, number: Number) -> Name

Returns the signal name for the signal number.

fn signal_number_from_name(&self, name: Name) -> Option<Number>

Gets the signal number from the signal name.

impl Sysconf for VirtualSystem

fn confstr_path(&self) -> Result<UnixString>

Returns the standard path for the system.

This function returns the value of SystemState::path. If it is empty, it returns the ENOSYS error.

impl TcGetPgrp for VirtualSystem

fn tcgetpgrp(&self, fd: Fd) -> Result<Pid>

Returns the current foreground process group ID.

The current implementation does not yet support the concept of controlling terminals and sessions. It accepts any open file descriptor.

impl TcSetPgrp for VirtualSystem

fn tcsetpgrp( &self, fd: Fd, pgid: Pid, ) -> impl Future<Output = Result<()>> + use<>

Switches the foreground process.

The current implementation does not yet support the concept of controlling terminals and sessions. It accepts any open file descriptor.

impl Times for VirtualSystem

fn times(&self) -> Result<CpuTimes>

Returns times in SystemState.

impl Umask for VirtualSystem

fn umask(&self, new_mask: Mode) -> Mode

Gets and sets the file creation mode mask.

impl Wait for VirtualSystem

fn wait(&self, target: Pid) -> Result<Option<(Pid, ProcessState)>>

Waits for a child.

TODO: Currently, this function only supports target == -1 || target > 0.

impl Write for VirtualSystem

fn write<'a>( &self, fd: Fd, buffer: &'a [u8], ) -> impl Future<Output = Result<usize>> + use<'a>

Writes data from the buffer to the file descriptor.

For pipes (FIFOs) opened in blocking mode, if the write is at most PIPE_BUF bytes, this method blocks until enough room is available to write all bytes atomically. For larger writes, this method writes as many bytes as fit on each pass and loops, blocking only when the pipe is completely full, until the entire buffer has been written. The decision to loop is encapsulated in OpenFileDescription::poll_write_full; this method itself contains no file-type branching.

For non-pipe file types or non-blocking mode, this method returns after the first successful (possibly partial) write without looping.

If a signal is caught while this method is blocking, it returns Errno::EINTR if no bytes have been written yet, or the count of bytes written so far otherwise. The signal-precedence check runs at the top of each poll iteration before any further write is attempted, so when Err(Errno::EINTR) is returned no bytes have been transferred in this call.