Struct yash_env::system::virtual::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 state of the system. The state is contained in Rc so that processes can share the same state. The latter is a process ID that identifies a process calling the System interface.

When you clone a virtual system, the clone will have the same process_id as the original. To simulate the fork system call, you would probably want to assign a new process ID and add a new Process to the system state.

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(&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 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.

Returns Err(Errno::EBADF) if the FD is not open.

pub fn with_open_file_description_mut<F, R>( &mut 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.

Returns Err(Errno::EBADF) if the FD is not open.

Trait Implementations

impl Clone for VirtualSystem

fn clone(&self) -> VirtualSystem

Returns a copy of the value.

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

Performs copy-assignment from source.

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 System for VirtualSystem

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

Retrieves metadata of a file.

The current implementation fills only the following values of the returned FileStat:

• st_mode
• st_size
• st_dev (always 1)
• st_ino (computed from the address of INode)

fn fstatat(&self, dir_fd: Fd, path: &CStr, flags: AtFlags) -> Result<FileStat>

Retrieves metadata of a file.

The current implementation fills only the following values of the returned FileStat:

• st_mode
• st_size
• st_dev (always 1)
• st_ino (computed from the address of INode)

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.

fn fcntl_setfl(&mut self, _fd: Fd, _flags: OFlag) -> Result<()>

Current implementation does nothing but return Ok(()).

fn now(&self) -> Instant

Returns now in SystemState.

Panics if it is None.

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

Returns times in SystemState.

fn kill( &mut self, target: Pid, signal: Option<Signal> ) -> Pin<Box<dyn Future<Output = Result<()>>>>

Sends a signal to the target process.

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 select( &mut self, readers: &mut FdSet, writers: &mut FdSet, timeout: Option<&TimeSpec>, signal_mask: Option<&SigSet> ) -> Result<c_int>

Waits for a next event.

The VirtualSystem implementation for this method does not actually block the calling thread. The method returns immediately in any case.

The timeout is ignored if this function returns because of a ready FD or a caught signal. Otherwise, the timeout is added to SystemState::now, which must not be None then.

fn setpgid(&mut 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.

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.

fn tcsetpgrp(&mut self, fd: Fd, pgid: Pid) -> Result<()>

Switches the foreground process.

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

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

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 system state. 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.

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

Waits for a child.

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

fn execve( &mut self, path: &CStr, args: &[CString], envs: &[CString] ) -> Result<Infallible>

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.

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

Changes the current working directory.

The current implementation does not canonicalize “.”, “..”, or symbolic links in the new path set to the process.

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

Returns the standard path for the system.

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

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

Whether there is a directory at the specified path.

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

Creates an unnamed pipe.

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

Duplicates a file descriptor.

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

Duplicates a file descriptor.

fn open(&mut self, path: &CStr, option: OFlag, mode: Mode) -> Result<Fd>

Opens a file descriptor.

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

Opens a file descriptor associated with an anonymous temporary file.

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

Closes a file descriptor.

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

Returns the file status flags for the open file description.

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

Returns the attributes for the file descriptor.

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

Sets attributes for the file descriptor.

fn isatty(&self, _fd: Fd) -> Result<bool>

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

fn read(&mut self, fd: Fd, buffer: &mut [u8]) -> Result<usize>

Reads from the file descriptor.

fn write(&mut self, fd: Fd, buffer: &[u8]) -> Result<usize>

Writes to the file descriptor.

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

Moves the position of the open file description.

fn fdopendir(&mut self, fd: Fd) -> Result<Box<dyn Dir>>

Opens a directory for enumerating entries.

fn opendir(&mut self, path: &CStr) -> Result<Box<dyn Dir>>

Opens a directory for enumerating entries.

fn umask(&mut self, mask: Mode) -> Mode

Gets and sets the file creation mode mask.

fn sigmask( &mut self, how: SigmaskHow, set: Option<&SigSet>, oldset: Option<&mut SigSet> ) -> Result<()>

Gets and/or sets the signal blocking mask.

fn sigaction( &mut self, signal: Signal, action: SignalHandling ) -> Result<SignalHandling>

Gets and sets the handler for a signal.

fn caught_signals(&mut self) -> Vec<Signal>

Returns signals this process has caught, if any.

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.

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

Returns the current working directory path.

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

Returns the home directory path of the given user.

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

Returns the limits for the specified resource.

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

Sets the limits for the specified resource.