Trait System 

pub trait System: Debug {
    // Required methods
    fn fstat(&self, fd: Fd) -> Result<Stat>;
    fn fstatat(
        &self,
        dir_fd: Fd,
        path: &CStr,
        follow_symlinks: bool,
    ) -> Result<Stat>;
    fn is_executable_file(&self, path: &CStr) -> bool;
    fn is_directory(&self, path: &CStr) -> bool;
    fn pipe(&mut self) -> Result<(Fd, Fd)>;
    fn dup(
        &mut self,
        from: Fd,
        to_min: Fd,
        flags: EnumSet<FdFlag>,
    ) -> Result<Fd>;
    fn dup2(&mut self, from: Fd, to: Fd) -> Result<Fd>;
    fn open(
        &mut self,
        path: &CStr,
        access: OfdAccess,
        flags: EnumSet<OpenFlag>,
        mode: Mode,
    ) -> Result<Fd>;
    fn open_tmpfile(&mut self, parent_dir: &Path) -> Result<Fd>;
    fn close(&mut self, fd: Fd) -> Result<()>;
    fn ofd_access(&self, fd: Fd) -> Result<OfdAccess>;
    fn get_and_set_nonblocking(
        &mut self,
        fd: Fd,
        nonblocking: bool,
    ) -> Result<bool>;
    fn fcntl_getfd(&self, fd: Fd) -> Result<EnumSet<FdFlag>>;
    fn fcntl_setfd(&mut self, fd: Fd, flags: EnumSet<FdFlag>) -> Result<()>;
    fn isatty(&self, fd: Fd) -> bool;
    fn read(&mut self, fd: Fd, buffer: &mut [u8]) -> Result<usize>;
    fn write(&mut self, fd: Fd, buffer: &[u8]) -> Result<usize>;
    fn lseek(&mut self, fd: Fd, position: SeekFrom) -> Result<u64>;
    fn fdopendir(&mut self, fd: Fd) -> Result<Box<dyn Dir>>;
    fn opendir(&mut self, path: &CStr) -> Result<Box<dyn Dir>>;
    fn umask(&mut self, new_mask: Mode) -> Mode;
    fn now(&self) -> Instant;
    fn times(&self) -> Result<Times>;
    fn validate_signal(&self, number: RawNumber) -> Option<(Name, Number)>;
    fn signal_number_from_name(&self, name: Name) -> Option<Number>;
    fn sigmask(
        &mut self,
        op: Option<(SigmaskOp, &[Number])>,
        old_mask: Option<&mut Vec<Number>>,
    ) -> Result<()>;
    fn get_sigaction(&self, signal: Number) -> Result<Disposition>;
    fn sigaction(
        &mut self,
        signal: Number,
        action: Disposition,
    ) -> Result<Disposition>;
    fn caught_signals(&mut self) -> Vec<Number>;
    fn kill(
        &mut self,
        target: Pid,
        signal: Option<Number>,
    ) -> FlexFuture<Result<()>> ;
    fn raise(&mut self, signal: Number) -> FlexFuture<Result<()>> ;
    fn select(
        &mut self,
        readers: &mut Vec<Fd>,
        writers: &mut Vec<Fd>,
        timeout: Option<Duration>,
        signal_mask: Option<&[Number]>,
    ) -> Result<c_int>;
    fn getsid(&self, pid: Pid) -> Result<Pid>;
    fn getpid(&self) -> Pid;
    fn getppid(&self) -> Pid;
    fn getpgrp(&self) -> Pid;
    fn setpgid(&mut self, pid: Pid, pgid: Pid) -> Result<()>;
    fn tcgetpgrp(&self, fd: Fd) -> Result<Pid>;
    fn tcsetpgrp(&mut self, fd: Fd, pgid: Pid) -> Result<()>;
    fn new_child_process(&mut self) -> Result<ChildProcessStarter>;
    fn wait(&mut self, target: Pid) -> Result<Option<(Pid, ProcessState)>>;
    fn execve(
        &mut self,
        path: &CStr,
        args: &[CString],
        envs: &[CString],
    ) -> FlexFuture<Result<Infallible>> ;
    fn exit(&mut self, exit_status: ExitStatus) -> FlexFuture<Infallible> ;
    fn getcwd(&self) -> Result<PathBuf>;
    fn chdir(&mut self, path: &CStr) -> Result<()>;
    fn getuid(&self) -> Uid;
    fn geteuid(&self) -> Uid;
    fn getgid(&self) -> Gid;
    fn getegid(&self) -> Gid;
    fn getpwnam_dir(&self, name: &CStr) -> Result<Option<PathBuf>>;
    fn confstr_path(&self) -> Result<UnixString>;
    fn shell_path(&self) -> CString;
    fn getrlimit(&self, resource: Resource) -> Result<LimitPair>;
    fn setrlimit(&mut self, resource: Resource, limits: LimitPair) -> Result<()>;
}

API to the system-managed parts of the environment.

The System trait defines a collection of methods to access the underlying operating system from the shell as an application program. There are two substantial implementors for this trait: RealSystem and VirtualSystem. Another implementor is SharedSystem, which wraps a System instance to extend the interface with asynchronous methods.

Required Methods

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_executable_file(&self, path: &CStr) -> bool

Whether there is an executable file at the specified path.

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.

This is a thin wrapper around the pipe system call. If successful, returns the reading and writing ends of the pipe.

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

Duplicates a file descriptor.

This is a thin wrapper around the fcntl system call that opens a new FD that shares the open file description with from. The new FD will be the minimum unused FD not less than to_min. The flags are set to the new FD.

If successful, returns Ok(new_fd). On error, returns Err(_).

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

Duplicates a file descriptor.

This is a thin wrapper around the dup2 system call. If successful, returns Ok(to). On error, returns Err(_).

fn open( &mut self, path: &CStr, access: OfdAccess, flags: EnumSet<OpenFlag>, mode: Mode, ) -> Result<Fd>

Opens a file descriptor.

This is a thin wrapper around the open system call.

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

Opens a file descriptor associated with an anonymous temporary file.

This function works similarly to the O_TMPFILE flag specified to the open function.

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

Closes a file descriptor.

This is a thin wrapper around the close system call.

This function returns Ok(()) when the FD is already closed.

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

Returns the open file description access mode.

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

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

This is a wrapper around the fcntl system call. This function sets the non-blocking mode to the given value and returns the previous mode.

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

Returns the attributes for the file descriptor.

This is a thin wrapper around the fcntl system call.

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

Sets attributes for the file descriptor.

This is a thin wrapper around the fcntl system call.

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

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

On error, this function simply returns false and no detailed error information is provided because POSIX does not require the isatty function to set errno.

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

Reads from the file descriptor.

This is a thin wrapper around the read system call. If successful, returns the number of bytes read.

This function may perform blocking I/O, especially if the O_NONBLOCK flag is not set for the FD. Use SharedSystem::read_async to support concurrent I/O in an async function context.

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

Writes to the file descriptor.

This is a thin wrapper around the write system call. If successful, returns the number of bytes written.

This function may write only part of the buffer and block if the O_NONBLOCK flag is not set for the FD. Use SharedSystem::write_all to support concurrent I/O in an async function context and ensure the whole buffer is written.

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, new_mask: Mode) -> Mode

Gets and sets the file creation mode mask.

This is a thin wrapper around the umask system call. It sets the mask to the given value and returns the previous mask.

You cannot tell the current mask without setting a new one. If you only want to get the current mask, you need to set it back to the original value after getting it.

fn now(&self) -> Instant

Returns the current time.

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

Returns consumed CPU times.

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

Tests if a signal number is valid.

This function returns Some((name, number)) if the signal number refers to a valid signal supported by the system. Otherwise, it returns None.

Note that one signal number can have multiple names, in which case this function returns the name that is considered the most common.

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

Gets the signal number from the signal name.

This function returns the signal number corresponding to the signal name in the system. If the signal name is not supported, it returns None.

fn sigmask( &mut self, op: Option<(SigmaskOp, &[Number])>, old_mask: Option<&mut Vec<Number>>, ) -> Result<()>

Gets and/or sets the signal blocking mask.

This is a low-level function used internally by SharedSystem::set_disposition. You should not call this function directly, or you will disrupt the behavior of SharedSystem. The description below applies if you want to do everything yourself without depending on SharedSystem.

This is a thin wrapper around the sigprocmask system call. If op is Some, this function updates the signal blocking mask by applying the given SigmaskOp and signal set to the current mask. If op is None, this function does not change the mask. If old_mask is Some, this function sets the previous mask to it.

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

Gets the disposition for a signal.

This is a low-level function used internally by SharedSystem::get_disposition. You should not call this function directly, or you will leave the SharedSystem instance in an inconsistent state. The description below applies if you want to do everything yourself without depending on SharedSystem.

This is an abstract wrapper around the sigaction system call. This function returns the current disposition if successful.

To change the disposition, use sigaction.

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

Gets and sets the disposition for a signal.

This is a low-level function used internally by SharedSystem::set_disposition. You should not call this function directly, or you will leave the SharedSystem instance in an inconsistent state. The description below applies if you want to do everything yourself without depending on SharedSystem.

This is an abstract wrapper around the sigaction system call. This function returns the previous disposition if successful.

When you set the disposition to Disposition::Catch, signals sent to this process are accumulated in the System instance and made available from caught_signals.

To get the current disposition without changing it, use get_sigaction.

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

Returns signals this process has caught, if any.

This is a low-level function used internally by SharedSystem::select. You should not call this function directly, or you will disrupt the behavior of SharedSystem. The description below applies if you want to do everything yourself without depending on SharedSystem.

To catch a signal, you must firstly install a signal handler by calling sigaction with Disposition::Catch. Once the handler is ready, signals sent to the process are accumulated in the System. You call caught_signals to obtain a list of caught signals thus far.

This function clears the internal list of caught signals, so a next call will return an empty list unless another signal is caught since the first call. Because the list size is limited, you should call this function periodically before the list gets full, in which case further caught signals are silently ignored.

Note that signals become pending if sent while blocked by sigmask. They must be unblocked so that they are caught and made available from this function.

fn kill( &mut self, target: Pid, signal: Option<Number>, ) -> FlexFuture<Result<()>>

Sends a signal.

This is a thin wrapper around the kill system call. If signal is None, permission to send a signal is checked, but no signal is sent.

The virtual system version of this function blocks the calling thread if the signal stops or terminates the current process, hence returning a future. See VirtualSystem::kill for details.

fn raise(&mut self, signal: Number) -> FlexFuture<Result<()>>

Sends a signal to the current process.

This is a thin wrapper around the raise system call.

The virtual system version of this function blocks the calling thread if the signal stops or terminates the current process, hence returning a future. See VirtualSystem::kill for details.

fn select( &mut self, readers: &mut Vec<Fd>, writers: &mut Vec<Fd>, timeout: Option<Duration>, signal_mask: Option<&[Number]>, ) -> Result<c_int>

Waits for a next event.

This is a low-level function used internally by SharedSystem::select. You should not call this function directly, or you will disrupt the behavior of SharedSystem. The description below applies if you want to do everything yourself without depending on SharedSystem.

This function blocks the calling thread until one of the following condition is met:

• An FD in readers becomes ready for reading.
• An FD in writers becomes ready for writing.
• The specified timeout duration has passed.
• A signal handler catches a signal.

When this function returns an Ok, FDs that are not ready for reading and writing are removed from readers and writers, respectively. The return value will be the number of FDs left in readers and writers.

If readers and writers contain an FD that is not open for reading and writing, respectively, this function will fail with EBADF. In this case, you should remove the FD from readers and writers and try again.

If signal_mask is Some list of signals, it is used as the signal blocking mask while waiting and restored when the function returns.

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

Returns the session ID of the specified process.

If pid is Pid(0), this function returns the session ID of the current process.

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 setpgid(&mut self, pid: Pid, pgid: Pid) -> Result<()>

Modifies the process group ID of a process.

This is a thin wrapper around the setpgid system call.

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

Returns the current foreground process group ID.

This is a thin wrapper around the tcgetpgrp system call.

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

Switches the foreground process group.

This is a thin wrapper around the tcsetpgrp system call.

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

Creates a new child process.

This is a thin wrapper around the fork system call. Users of Env should not call it directly. Instead, use Subshell so that the environment can condition the state of the child process before it starts running.

Because we need the parent environment to create the child environment, this method cannot initiate the child task directly. Instead, it returns a ChildProcessStarter function that takes the parent environment and the child task. The caller must call the starter to make sure the parent and child processes perform correctly after forking.

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

Reports updated status of a child process.

This is a low-level function used internally by Env::wait_for_subshell. You should not call this function directly, or you will disrupt the behavior of Env. The description below applies if you want to do everything yourself without depending on Env.

This function performs waitpid(target, ..., WUNTRACED | WCONTINUED | WNOHANG). Despite the name, this function does not block: it returns the result immediately.

This function returns a pair of the process ID and the process state if a process matching target is found and its state has changed. If all the processes matching target have not changed their states, this function returns Ok(None). If an error occurs, this function returns Err(_).

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

Replaces the current process with an external utility.

This is a thin wrapper around the execve system call.

fn exit(&mut self, exit_status: ExitStatus) -> FlexFuture<Infallible>

Terminates the current process.

This function is a thin wrapper around the _exit system call.

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

Returns the current working directory path.

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

Changes the working directory.

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.

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

Returns the home directory path of the given user.

Returns Ok(None) if the user is not found.

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

Returns the standard $PATH value where all standard utilities are expected to be found.

This is a thin wrapper around the confstr(_CS_PATH, …).

fn shell_path(&self) -> CString

Returns the path to the shell executable.

If possible, this function should return the path to the current shell executable. Otherwise, it should return the path to the default POSIX shell.

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

Returns the limits for the specified resource.

This function returns a pair of the soft and hard limits for the given resource. The soft limit is the current limit, and the hard limit is the maximum value that the soft limit can be set to.

When no limit is set, the limit value is INFINITY.

This is a thin wrapper around the getrlimit system call.

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

Sets the limits for the specified resource.

Specify INFINITY as the limit value to remove the limit.

This is a thin wrapper around the setrlimit system call.

Implementors

impl System for &SharedSystem

Delegates System methods to the contained system instance.

This implementation only requires a non-mutable reference to the shared system because it uses RefCell to access the contained system instance.

impl System for RealSystem

impl System for SharedSystem

Delegates System methods to the contained system instance.

impl System for VirtualSystem