wasmtime_wasi::bindings::filesystem::types

Trait HostDescriptor

Source
pub trait HostDescriptor: Send {
Show 28 methods // Required methods fn read_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<InputStream>, FsError>; fn write_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<OutputStream>, FsError>; fn append_via_stream( &mut self, self_: Resource<Descriptor>, ) -> Result<Resource<OutputStream>, FsError>; fn advise( &mut self, self_: Resource<Descriptor>, offset: Filesize, length: Filesize, advice: Advice, ) -> impl Future<Output = Result<(), FsError>> + Send; fn sync_data( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<(), FsError>> + Send; fn get_flags( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorFlags, FsError>> + Send; fn get_type( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorType, FsError>> + Send; fn set_size( &mut self, self_: Resource<Descriptor>, size: Filesize, ) -> impl Future<Output = Result<(), FsError>> + Send; fn set_times( &mut self, self_: Resource<Descriptor>, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> impl Future<Output = Result<(), FsError>> + Send; fn read( &mut self, self_: Resource<Descriptor>, length: Filesize, offset: Filesize, ) -> impl Future<Output = Result<(Vec<u8>, bool), FsError>> + Send; fn write( &mut self, self_: Resource<Descriptor>, buffer: Vec<u8>, offset: Filesize, ) -> impl Future<Output = Result<Filesize, FsError>> + Send; fn read_directory( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<Resource<DirectoryEntryStream>, FsError>> + Send; fn sync( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<(), FsError>> + Send; fn create_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn stat( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorStat, FsError>> + Send; fn stat_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> impl Future<Output = Result<DescriptorStat, FsError>> + Send; fn set_times_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> impl Future<Output = Result<(), FsError>> + Send; fn link_at( &mut self, self_: Resource<Descriptor>, old_path_flags: PathFlags, old_path: String, new_descriptor: Resource<Descriptor>, new_path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn open_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, open_flags: OpenFlags, flags: DescriptorFlags, ) -> impl Future<Output = Result<Resource<Descriptor>, FsError>> + Send; fn readlink_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<String, FsError>> + Send; fn remove_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn rename_at( &mut self, self_: Resource<Descriptor>, old_path: String, new_descriptor: Resource<Descriptor>, new_path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn symlink_at( &mut self, self_: Resource<Descriptor>, old_path: String, new_path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn unlink_file_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<(), FsError>> + Send; fn is_same_object( &mut self, self_: Resource<Descriptor>, other: Resource<Descriptor>, ) -> impl Future<Output = Result<bool>> + Send; fn metadata_hash( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<MetadataHashValue, FsError>> + Send; fn metadata_hash_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> impl Future<Output = Result<MetadataHashValue, FsError>> + Send; fn drop(&mut self, rep: Resource<Descriptor>) -> Result<()>;
}

Required Methods§

Source

fn read_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<InputStream>, FsError>

Return a stream for reading from a file, if available.

May fail with an error-code describing why the file cannot be read.

Multiple read, write, and append streams may be active on the same open file and they do not interfere with each other.

Note: This allows using read-stream, which is similar to read in POSIX.

Source

fn write_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<OutputStream>, FsError>

Return a stream for writing to a file, if available.

May fail with an error-code describing why the file cannot be written.

Note: This allows using write-stream, which is similar to write in POSIX.

Source

fn append_via_stream( &mut self, self_: Resource<Descriptor>, ) -> Result<Resource<OutputStream>, FsError>

Return a stream for appending to a file, if available.

May fail with an error-code describing why the file cannot be appended.

Note: This allows using write-stream, which is similar to write with O_APPEND in POSIX.

Source

fn advise( &mut self, self_: Resource<Descriptor>, offset: Filesize, length: Filesize, advice: Advice, ) -> impl Future<Output = Result<(), FsError>> + Send

Provide file advisory information on a descriptor.

This is similar to posix_fadvise in POSIX.

Source

fn sync_data( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<(), FsError>> + Send

Synchronize the data of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fdatasync in POSIX.

Source

fn get_flags( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorFlags, FsError>> + Send

Get flags associated with a descriptor.

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

Note: This returns the value that was the fs_flags value returned from fdstat_get in earlier versions of WASI.

Source

fn get_type( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorType, FsError>> + Send

Get the dynamic type of a descriptor.

Note: This returns the same value as the type field of the fd-stat returned by stat, stat-at and similar.

Note: This returns similar flags to the st_mode & S_IFMT value provided by fstat in POSIX.

Note: This returns the value that was the fs_filetype value returned from fdstat_get in earlier versions of WASI.

Source

fn set_size( &mut self, self_: Resource<Descriptor>, size: Filesize, ) -> impl Future<Output = Result<(), FsError>> + Send

Adjust the size of an open file. If this increases the file’s size, the extra bytes are filled with zeros.

Note: This was called fd_filestat_set_size in earlier versions of WASI.

Source

fn set_times( &mut self, self_: Resource<Descriptor>, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> impl Future<Output = Result<(), FsError>> + Send

Adjust the timestamps of an open file or directory.

Note: This is similar to futimens in POSIX.

Note: This was called fd_filestat_set_times in earlier versions of WASI.

Source

fn read( &mut self, self_: Resource<Descriptor>, length: Filesize, offset: Filesize, ) -> impl Future<Output = Result<(Vec<u8>, bool), FsError>> + Send

Read from a descriptor, without using and updating the descriptor’s offset.

This function returns a list of bytes containing the data that was read, along with a bool which, when true, indicates that the end of the file was reached. The returned list will contain up to length bytes; it may return fewer than requested, if the end of the file is reached or if the I/O operation is interrupted.

In the future, this may change to return a stream<u8, error-code>.

Note: This is similar to pread in POSIX.

Source

fn write( &mut self, self_: Resource<Descriptor>, buffer: Vec<u8>, offset: Filesize, ) -> impl Future<Output = Result<Filesize, FsError>> + Send

Write to a descriptor, without using and updating the descriptor’s offset.

It is valid to write past the end of a file; the file is extended to the extent of the write, with bytes between the previous end and the start of the write set to zero.

In the future, this may change to take a stream<u8, error-code>.

Note: This is similar to pwrite in POSIX.

Source

fn read_directory( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<Resource<DirectoryEntryStream>, FsError>> + Send

Read directory entries from a directory.

On filesystems where directories contain entries referring to themselves and their parents, often named . and .. respectively, these entries are omitted.

This always returns a new stream which starts at the beginning of the directory. Multiple streams may be active on the same directory, and they do not interfere with each other.

Source

fn sync( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<(), FsError>> + Send

Synchronize the data and metadata of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fsync in POSIX.

Source

fn create_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<(), FsError>> + Send

Create a directory.

Note: This is similar to mkdirat in POSIX.

Source

fn stat( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<DescriptorStat, FsError>> + Send

Return the attributes of an open file or directory.

Note: This is similar to fstat in POSIX, except that it does not return device and inode information. For testing whether two descriptors refer to the same underlying filesystem object, use is-same-object. To obtain additional data that can be used do determine whether a file has been modified, use metadata-hash.

Note: This was called fd_filestat_get in earlier versions of WASI.

Source

fn stat_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> impl Future<Output = Result<DescriptorStat, FsError>> + Send

Return the attributes of a file or directory.

Note: This is similar to fstatat in POSIX, except that it does not return device and inode information. See the stat description for a discussion of alternatives.

Note: This was called path_filestat_get in earlier versions of WASI.

Source

fn set_times_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> impl Future<Output = Result<(), FsError>> + Send

Adjust the timestamps of a file or directory.

Note: This is similar to utimensat in POSIX.

Note: This was called path_filestat_set_times in earlier versions of WASI.

Create a hard link.

Note: This is similar to linkat in POSIX.

Source

fn open_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, open_flags: OpenFlags, flags: DescriptorFlags, ) -> impl Future<Output = Result<Resource<Descriptor>, FsError>> + Send

Open a file or directory.

If flags contains descriptor-flags::mutate-directory, and the base descriptor doesn’t have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

If flags contains write or mutate-directory, or open-flags contains truncate or create, and the base descriptor doesn’t have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

Note: This is similar to openat in POSIX.

Read the contents of a symbolic link.

If the contents contain an absolute or rooted path in the underlying filesystem, this function fails with error-code::not-permitted.

Note: This is similar to readlinkat in POSIX.

Source

fn remove_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> impl Future<Output = Result<(), FsError>> + Send

Remove a directory.

Return error-code::not-empty if the directory is not empty.

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

Source

fn rename_at( &mut self, self_: Resource<Descriptor>, old_path: String, new_descriptor: Resource<Descriptor>, new_path: String, ) -> impl Future<Output = Result<(), FsError>> + Send

Rename a filesystem object.

Note: This is similar to renameat in POSIX.

Create a symbolic link (also known as a “symlink”).

If old-path starts with /, the function fails with error-code::not-permitted.

Note: This is similar to symlinkat in POSIX.

Unlink a filesystem object that is not a directory.

Return error-code::is-directory if the path refers to a directory. Note: This is similar to unlinkat(fd, path, 0) in POSIX.

Source

fn is_same_object( &mut self, self_: Resource<Descriptor>, other: Resource<Descriptor>, ) -> impl Future<Output = Result<bool>> + Send

Test whether two descriptors refer to the same filesystem object.

In POSIX, this corresponds to testing whether the two descriptors have the same device (st_dev) and inode (st_ino or d_ino) numbers. wasi-filesystem does not expose device and inode numbers, so this function may be used instead.

Source

fn metadata_hash( &mut self, self_: Resource<Descriptor>, ) -> impl Future<Output = Result<MetadataHashValue, FsError>> + Send

Return a hash of the metadata associated with a filesystem object referred to by a descriptor.

This returns a hash of the last-modification timestamp and file size, and may also include the inode number, device number, birth timestamp, and other metadata fields that may change when the file is modified or replaced. It may also include a secret value chosen by the implementation and not otherwise exposed.

Implementations are encouraged to provide the following properties:

  • If the file is not modified or replaced, the computed hash value should usually not change.
  • If the object is modified or replaced, the computed hash value should usually change.
  • The inputs to the hash should not be easily computable from the computed hash.

However, none of these is required.

Source

fn metadata_hash_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> impl Future<Output = Result<MetadataHashValue, FsError>> + Send

Return a hash of the metadata associated with a filesystem object referred to by a directory descriptor and a relative path.

This performs the same hash computation as metadata-hash.

Source

fn drop(&mut self, rep: Resource<Descriptor>) -> Result<()>

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source§

impl<_T: HostDescriptor + ?Sized + Send> HostDescriptor for &mut _T

Source§

fn read_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<InputStream>, FsError>

Return a stream for reading from a file, if available.

May fail with an error-code describing why the file cannot be read.

Multiple read, write, and append streams may be active on the same open file and they do not interfere with each other.

Note: This allows using read-stream, which is similar to read in POSIX.

Source§

fn write_via_stream( &mut self, self_: Resource<Descriptor>, offset: Filesize, ) -> Result<Resource<OutputStream>, FsError>

Return a stream for writing to a file, if available.

May fail with an error-code describing why the file cannot be written.

Note: This allows using write-stream, which is similar to write in POSIX.

Source§

fn append_via_stream( &mut self, self_: Resource<Descriptor>, ) -> Result<Resource<OutputStream>, FsError>

Return a stream for appending to a file, if available.

May fail with an error-code describing why the file cannot be appended.

Note: This allows using write-stream, which is similar to write with O_APPEND in POSIX.

Source§

async fn advise( &mut self, self_: Resource<Descriptor>, offset: Filesize, length: Filesize, advice: Advice, ) -> Result<(), FsError>

Provide file advisory information on a descriptor.

This is similar to posix_fadvise in POSIX.

Source§

async fn sync_data( &mut self, self_: Resource<Descriptor>, ) -> Result<(), FsError>

Synchronize the data of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fdatasync in POSIX.

Source§

async fn get_flags( &mut self, self_: Resource<Descriptor>, ) -> Result<DescriptorFlags, FsError>

Get flags associated with a descriptor.

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

Note: This returns the value that was the fs_flags value returned from fdstat_get in earlier versions of WASI.

Source§

async fn get_type( &mut self, self_: Resource<Descriptor>, ) -> Result<DescriptorType, FsError>

Get the dynamic type of a descriptor.

Note: This returns the same value as the type field of the fd-stat returned by stat, stat-at and similar.

Note: This returns similar flags to the st_mode & S_IFMT value provided by fstat in POSIX.

Note: This returns the value that was the fs_filetype value returned from fdstat_get in earlier versions of WASI.

Source§

async fn set_size( &mut self, self_: Resource<Descriptor>, size: Filesize, ) -> Result<(), FsError>

Adjust the size of an open file. If this increases the file’s size, the extra bytes are filled with zeros.

Note: This was called fd_filestat_set_size in earlier versions of WASI.

Source§

async fn set_times( &mut self, self_: Resource<Descriptor>, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> Result<(), FsError>

Adjust the timestamps of an open file or directory.

Note: This is similar to futimens in POSIX.

Note: This was called fd_filestat_set_times in earlier versions of WASI.

Source§

async fn read( &mut self, self_: Resource<Descriptor>, length: Filesize, offset: Filesize, ) -> Result<(Vec<u8>, bool), FsError>

Read from a descriptor, without using and updating the descriptor’s offset.

This function returns a list of bytes containing the data that was read, along with a bool which, when true, indicates that the end of the file was reached. The returned list will contain up to length bytes; it may return fewer than requested, if the end of the file is reached or if the I/O operation is interrupted.

In the future, this may change to return a stream<u8, error-code>.

Note: This is similar to pread in POSIX.

Source§

async fn write( &mut self, self_: Resource<Descriptor>, buffer: Vec<u8>, offset: Filesize, ) -> Result<Filesize, FsError>

Write to a descriptor, without using and updating the descriptor’s offset.

It is valid to write past the end of a file; the file is extended to the extent of the write, with bytes between the previous end and the start of the write set to zero.

In the future, this may change to take a stream<u8, error-code>.

Note: This is similar to pwrite in POSIX.

Source§

async fn read_directory( &mut self, self_: Resource<Descriptor>, ) -> Result<Resource<DirectoryEntryStream>, FsError>

Read directory entries from a directory.

On filesystems where directories contain entries referring to themselves and their parents, often named . and .. respectively, these entries are omitted.

This always returns a new stream which starts at the beginning of the directory. Multiple streams may be active on the same directory, and they do not interfere with each other.

Source§

async fn sync(&mut self, self_: Resource<Descriptor>) -> Result<(), FsError>

Synchronize the data and metadata of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fsync in POSIX.

Source§

async fn create_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> Result<(), FsError>

Create a directory.

Note: This is similar to mkdirat in POSIX.

Source§

async fn stat( &mut self, self_: Resource<Descriptor>, ) -> Result<DescriptorStat, FsError>

Return the attributes of an open file or directory.

Note: This is similar to fstat in POSIX, except that it does not return device and inode information. For testing whether two descriptors refer to the same underlying filesystem object, use is-same-object. To obtain additional data that can be used do determine whether a file has been modified, use metadata-hash.

Note: This was called fd_filestat_get in earlier versions of WASI.

Source§

async fn stat_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> Result<DescriptorStat, FsError>

Return the attributes of a file or directory.

Note: This is similar to fstatat in POSIX, except that it does not return device and inode information. See the stat description for a discussion of alternatives.

Note: This was called path_filestat_get in earlier versions of WASI.

Source§

async fn set_times_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, data_access_timestamp: NewTimestamp, data_modification_timestamp: NewTimestamp, ) -> Result<(), FsError>

Adjust the timestamps of a file or directory.

Note: This is similar to utimensat in POSIX.

Note: This was called path_filestat_set_times in earlier versions of WASI.

Create a hard link.

Note: This is similar to linkat in POSIX.

Source§

async fn open_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, open_flags: OpenFlags, flags: DescriptorFlags, ) -> Result<Resource<Descriptor>, FsError>

Open a file or directory.

If flags contains descriptor-flags::mutate-directory, and the base descriptor doesn’t have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

If flags contains write or mutate-directory, or open-flags contains truncate or create, and the base descriptor doesn’t have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

Note: This is similar to openat in POSIX.

Read the contents of a symbolic link.

If the contents contain an absolute or rooted path in the underlying filesystem, this function fails with error-code::not-permitted.

Note: This is similar to readlinkat in POSIX.

Source§

async fn remove_directory_at( &mut self, self_: Resource<Descriptor>, path: String, ) -> Result<(), FsError>

Remove a directory.

Return error-code::not-empty if the directory is not empty.

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

Source§

async fn rename_at( &mut self, self_: Resource<Descriptor>, old_path: String, new_descriptor: Resource<Descriptor>, new_path: String, ) -> Result<(), FsError>

Rename a filesystem object.

Note: This is similar to renameat in POSIX.

Create a symbolic link (also known as a “symlink”).

If old-path starts with /, the function fails with error-code::not-permitted.

Note: This is similar to symlinkat in POSIX.

Unlink a filesystem object that is not a directory.

Return error-code::is-directory if the path refers to a directory. Note: This is similar to unlinkat(fd, path, 0) in POSIX.

Source§

async fn is_same_object( &mut self, self_: Resource<Descriptor>, other: Resource<Descriptor>, ) -> Result<bool>

Test whether two descriptors refer to the same filesystem object.

In POSIX, this corresponds to testing whether the two descriptors have the same device (st_dev) and inode (st_ino or d_ino) numbers. wasi-filesystem does not expose device and inode numbers, so this function may be used instead.

Source§

async fn metadata_hash( &mut self, self_: Resource<Descriptor>, ) -> Result<MetadataHashValue, FsError>

Return a hash of the metadata associated with a filesystem object referred to by a descriptor.

This returns a hash of the last-modification timestamp and file size, and may also include the inode number, device number, birth timestamp, and other metadata fields that may change when the file is modified or replaced. It may also include a secret value chosen by the implementation and not otherwise exposed.

Implementations are encouraged to provide the following properties:

  • If the file is not modified or replaced, the computed hash value should usually not change.
  • If the object is modified or replaced, the computed hash value should usually change.
  • The inputs to the hash should not be easily computable from the computed hash.

However, none of these is required.

Source§

async fn metadata_hash_at( &mut self, self_: Resource<Descriptor>, path_flags: PathFlags, path: String, ) -> Result<MetadataHashValue, FsError>

Return a hash of the metadata associated with a filesystem object referred to by a directory descriptor and a relative path.

This performs the same hash computation as metadata-hash.

Source§

fn drop(&mut self, rep: Resource<Descriptor>) -> Result<()>

Implementors§

Source§

impl<T> HostDescriptor for WasiImpl<T>
where T: WasiView,