Struct Vfs 

pub struct Vfs { /* private fields */ }

Implementations

impl Vfs

pub fn direct() -> Result<Self>

Creates a VFS that accesses the local process directly.

pub async fn new<T>(stream: T) -> Result<Self>

where T: AsyncRead + AsyncWrite + Unpin + Send + 'static,

Starts an opaque-only VFS over a bidirectional byte stream.

This transport cannot transfer native handles, so files, subprocesses, and stdio endpoints are represented by remote references and relays.

pub async fn new_split<R, W>(reader: R, writer: W) -> Result<Self>

where R: AsyncRead + Send + 'static, W: AsyncWrite + Send + 'static,

Starts an opaque-only VFS on separate reader and writer streams.

This has the same opaque-only behavior as new.

pub async fn connect(path: impl AsRef<Path>) -> Result<Self>

Available on Unix only.

Connects to an agent daemon at a Unix-domain socket path.

This transport supports native file-descriptor transfer.

pub async fn connect_with_key( path: impl AsRef<Path>, key: Option<AuthKey>, ) -> Result<Self>

Available on Unix only.

Connects to an agent daemon at a Unix-domain socket path, proving knowledge of a pre-shared key.

A socket that must be world-connectable cannot identify its peer from credentials alone, so key distinguishes the intended agent and client. Both ends must agree on the key.

pub async fn from_stream(stream: UnixStream) -> Result<Self>

Available on Unix only.

Connects using an existing Unix-domain stream.

This transport supports native file-descriptor transfer.

pub async fn from_owned_fd(value: OwnedFd) -> Result<Self>

Available on Unix only.

Starts a VFS on an already-connected Unix-domain socket file descriptor.

This transport supports native file-descriptor transfer.

pub async fn from_owned_fd_with_key( value: OwnedFd, key: Option<AuthKey>, ) -> Result<Self>

Available on Unix only.

Starts a VFS on an already-connected Unix-domain socket file descriptor, proving knowledge of a pre-shared key.

pub fn is_direct(&self) -> bool

Returns whether this VFS accesses the local process directly.

pub async fn stop(self) -> Result<()>

Stops a remote backend and ends the connection to it. Direct backends require no shutdown.

The peer finishes shutting down once its incoming transport ends, so this consumes the VFS and closes the connection itself; a bare request would leave the peer waiting on a client with nothing left to say. When the request fails the connection is aborted instead, since a peer that could not answer may never close its own output. Nested sessions stop the whole chain: the peer closes its connection to the far end as it services the request.

Clones share one session, so any that outlive this call can no longer issue requests.

pub async fn close(self)

Gracefully closes a remote backend. Direct backends require no shutdown.

This waits for the peer to close its outgoing transport and has no built-in timeout. Windows named pipes instead close the shared pipe after outgoing writes drain because they cannot half-close. Use Vfs::abort when the peer is uncooperative.

pub async fn abort(self)

Abruptly closes a remote backend. Direct backends require no shutdown.

pub async fn call_extension<T: VfsExtension>( &self, request: T::Request, ) -> Result<T::Response>

Calls a registered VFS extension, dispatching directly in-process or over RPC depending on which backend this Vfs wraps.

pub fn env(&self) -> Box<dyn Iterator<Item = (String, String)> + '_>

Iterates the target’s initial process environment.

pub fn cwd(&self) -> Path<'_>

Returns the target’s initial working directory.

pub fn current_exe(&self) -> Path<'_>

Returns the target process executable.

pub fn target(&self) -> &TargetInfo

Returns target platform information.

pub fn security(&self) -> &SecurityInfo

Returns the target’s initial security context.

pub fn session(&self) -> Uuid

Returns the identity of this target session.

Generated when the target’s context was captured, so it distinguishes this session from any other — including an earlier session against the same machine. Values that are only meaningful against one target, such as process::ProcessInfo, carry it so they cannot be quietly interpreted against a different one.

pub fn pid(&self) -> u32

Returns the process ID of the target process itself.

The process serving this VFS — the local interpreter for a direct target, the remote agent for a client — and for a chained target, the one at the far end that actually performs the work. Like any other PID from this target, it is only meaningful against session.

pub async fn processes(&self) -> Result<Processes>

Enumerates the target’s process table.

Entries are produced lazily, and a process that exits partway through is skipped rather than reported. A record carries everything the target would report about that process — the same record describe_process would produce for it.

pub async fn describe_process(&self, pid: u32) -> Result<ProcessInfo>

Describes the process that currently owns pid.

The same record processes would produce for it, without enumerating the table to reach it and without holding the process open. Nothing pins the PID, so the record describes whatever owned it at the moment it was read — for an identity that can be checked, open a handle instead.

Unlike open_process, this needs no rights over the process: on a Windows target the kernel’s own processes cannot be opened by anyone, and this is the only route to what is known about them.

pub async fn open_process_info(&self, info: &ProcessInfo) -> Result<Process>

Opens a handle to the process a snapshot describes.

Fails if the PID has been recycled since the snapshot was taken, or if the snapshot came from a different target session.

pub async fn open_process(&self, pid: u32) -> Result<Process>

Opens a handle to whatever process currently owns pid.

The escape hatch for a PID that did not come from processes — read out of a pidfile, say. Nothing here can tell whether the PID still names what the caller meant; prefer open_process_info when a snapshot is available.

pub fn extensions(&self) -> &ExtensionSet

Returns supported VFS extension protocol versions.

pub fn open_options(&self) -> OpenOptions<'_>

Creates a file-open options builder.

pub fn command(&self, program: Path<'_>) -> Command<'_>

Creates a command builder for program.

pub async fn unix_socket( &self, path: Path<'_>, key: Option<&[u8]>, ) -> Result<Vfs>

Connects to a VFS agent over a Unix-domain socket.

key is an optional pre-shared key that both ends must prove knowledge of during negotiation. It is what identifies the intended agent when the socket’s permissions cannot; the concrete client accepts the same key when connecting.

pub async fn windows_admin( &self, cwd: Path<'_>, env: HashMap<String, Option<String>>, elevate: bool, ) -> Result<Vfs>

Starts a Windows administrative VFS session.

pub async fn pipe( &self, buf_size: Option<usize>, ) -> Result<(StdioSend, StdioRecv)>

Creates a connected writable and readable pipe endpoint.

buf_size is a best-effort kernel buffer size hint. Backends that cannot honor the hint use their default buffer size.

pub async fn user_name(&self, uid: u32) -> Result<String>

Resolves a Unix user ID to a name.

pub async fn user_id(&self, name: &str) -> Result<u32>

Resolves a Unix user name to an ID.

pub async fn group_name(&self, gid: u32) -> Result<String>

Resolves a Unix group ID to a name.

pub async fn group_id(&self, name: &str) -> Result<u32>

Resolves a Unix group name to an ID.

pub async fn sid_name(&self, sid: &Sid) -> Result<SidName>

Resolves a Windows SID to its account name.

pub async fn account_name(&self, name: &str) -> Result<SidName>

Resolves a Windows account name to its SID.

pub async fn resolve_principal_id( &self, input: PrincipalId, want: PrincipalIdKind, ) -> Result<PrincipalId>

Converts a principal ID from one representation to another (e.g. a Unix uid/gid to/from a macOS principal UUID).

pub async fn read_dir(&self, path: Path<'_>) -> Result<ReadDir>

Opens a directory iterator.

pub async fn which( &self, program: Path<'_>, path: Option<&str>, cwd: Option<Path<'_>>, ) -> Result<Option<PathBuf>>

Finds an executable using a target search path.

pub async fn well_known_path( &self, key: WellKnownPath, app: Option<&str>, env: &HashMap<String, Option<String>>, ) -> Result<PathBuf>

Resolves a target-specific well-known path.

pub async fn clear_cache(&self) -> Result<()>

Clears target-side cached state.

pub async fn xattrs( &self, path: Path<'_>, namespace: XattrNamespace<'_>, follow: bool, ) -> Result<Vec<XattrEntry>>

Lists extended attributes for a path.

pub async fn streams( &self, path: Path<'_>, follow: bool, ) -> Result<Vec<StreamEntry>>

Lists alternate data streams for a path.

pub async fn xattr( &self, path: Path<'_>, name: &str, namespace: Option<&str>, follow: bool, ) -> Result<Vec<u8>>

Reads an extended attribute for a path.

pub async fn set_xattr( &self, path: Path<'_>, name: &str, namespace: Option<&str>, value: &[u8], follow: bool, ) -> Result<()>

Creates or replaces an extended attribute for a path.

pub async fn remove_xattr( &self, path: Path<'_>, name: &str, namespace: Option<&str>, follow: bool, ) -> Result<()>

Removes an extended attribute from a path.

pub async fn remove( &self, path: Path<'_>, all: bool, ignore: bool, ) -> Result<()>

Removes a file or symlink.

pub async fn metadata(&self, path: Path<'_>) -> Result<Metadata>

Returns metadata without following the final symlink.

pub async fn fs_metadata( &self, path: Path<'_>, follow: bool, ) -> Result<FsMetadata>

Returns filesystem metadata for a path.

pub async fn acl( &self, path: Path<'_>, kind: AclKind, default: bool, follow: bool, ) -> Result<Option<Acl>>

Returns the ACL of the requested kind for a path. See file::File::acl for default’s meaning.

pub async fn set_acl( &self, path: Path<'_>, kind: AclKind, acl: Option<&Acl>, default: bool, follow: bool, ) -> Result<()>

Sets or removes the ACL for a path. See file::File::set_acl for default’s meaning.

pub async fn sec_desc( &self, path: Path<'_>, mask: SecInfo, follow: bool, ) -> Result<SecDesc>

Returns the Windows security descriptor for a path.

pub async fn update_sec_desc( &self, path: Path<'_>, sec_desc: &SecDesc, follow: bool, ) -> Result<()>

Replaces the Windows security descriptor for a path.

pub async fn create_dir(&self, path: Path<'_>, all: bool) -> Result<()>

Creates a directory, optionally including missing parents.

pub async fn remove_dir( &self, path: Path<'_>, all: bool, ignore: bool, ) -> Result<()>

Removes a directory.

pub async fn copy(&self, from: Path<'_>, to: Path<'_>, all: bool) -> Result<()>

Copies a path, optionally including directory contents.

pub async fn rename( &self, from: Path<'_>, to: Path<'_>, replace: bool, ) -> Result<()>

Renames a path.

pub async fn move_(&self, from: Path<'_>, to: Path<'_>, all: bool) -> Result<()>

Moves a path, optionally including directory contents.

pub async fn symlink( &self, cwd: Path<'_>, src: Path<'_>, dst: Path<'_>, ) -> Result<()>

Creates a symbolic link using cwd to interpret relative source paths.

pub async fn hard_link(&self, src: Path<'_>, dst: Path<'_>) -> Result<()>

Creates a hard link.

pub async fn symlink_dir(&self, src: Path<'_>, dst: Path<'_>) -> Result<()>

Creates a symbolic link to a directory.

pub async fn symlink_file(&self, src: Path<'_>, dst: Path<'_>) -> Result<()>

Creates a symbolic link to a file.

pub async fn symlink_metadata(&self, path: Path<'_>) -> Result<Metadata>

Returns metadata without following the final symlink.

pub async fn update_metadata( &self, paths: &[PathBuf], patch: MetadataPatch, ) -> Result<()>

Applies a metadata patch to every path.

pub async fn canonicalize(&self, path: Path<'_>) -> Result<PathBuf>

Resolves a path to its canonical absolute form.

pub async fn read_link(&self, path: Path<'_>) -> Result<PathBuf>

Returns the destination of a symbolic link.

pub async fn access(&self, path: Path<'_>, mode: AccessFlags) -> Result<()>

Checks whether the process can access a path with the requested permissions.

pub async fn glob( &self, pattern: impl Into<String>, root: Path<'_>, follow_symlinks: bool, max_depth: Option<usize>, ) -> Result<Vec<PathBuf>>

Expands a glob pattern beneath root.

Trait Implementations

impl Clone for Vfs

fn clone(&self) -> Vfs

Returns a duplicate of the value.

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

Performs copy-assignment from source.