componentized/directory

wasi:filesystem

interface dependency

WASI filesystem interfaces

interface preopens wasi:filesystem/preopens@0.3.0 since 0.3.0

Types

use resource descriptorsince 0.3.0

from wasi:filesystem/types@0.3.0

A descriptor is a reference to a filesystem object, which may be a file, directory, named pipe, special file, or other object on which filesystem calls may be made.

  • read-via-stream: func( offset: filesize, ) -> tuple<stream<u8>, future<result<_, error-code>>>since 0.3.0

    Return a stream for reading from a file.

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

    This function returns a stream which provides the data received from the file, and a future providing additional error information in case an error is encountered.

    If no error is encountered, stream.read on the stream will return read-status::closed with no error-context and the future resolves to the value ok. If an error is encountered, stream.read on the stream returns read-status::closed with an error-context and the future resolves to err with an error-code.

    Note: This is similar to pread in POSIX.

  • write-via-stream: func( data: stream<u8>, offset: filesize, ) -> future<result<_, error-code>>since 0.3.0

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

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

    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.

    This function returns once either full contents of the stream are written or an error is encountered.

    Note: This is similar to pwrite in POSIX.

  • append-via-stream: func( data: stream<u8>, ) -> future<result<_, error-code>>since 0.3.0

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

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

    This function returns once either full contents of the stream are written or an error is encountered.

    Note: This is similar to write with O_APPEND in POSIX.

  • advise: async func( offset: filesize, length: filesize, advice: advice, ) -> result<_, error-code>since 0.3.0

    Provide file advisory information on a descriptor.

    This is similar to posix_fadvise in POSIX.

  • sync-data: async func() -> result<_, error-code>since 0.3.0

    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.

  • get-flags: async func() -> result<descriptor-flags, error-code>since 0.3.0

    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.

  • get-type: async func() -> result<descriptor-type, error-code>since 0.3.0

    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.

  • set-size: async func(size: filesize) -> result<_, error-code>since 0.3.0

    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.

  • set-times: async func( data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp, ) -> result<_, error-code>since 0.3.0

    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.

  • read-directory: func() -> tuple<stream<directory-entry>, future<result<_, error-code>>>since 0.3.0

    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.

    This function returns a future, which will resolve to an error code if reading full contents of the directory fails.

  • sync: async func() -> result<_, error-code>since 0.3.0

    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.

  • create-directory-at: async func(path: string) -> result<_, error-code>since 0.3.0

    Create a directory.

    Note: This is similar to mkdirat in POSIX.

  • stat: async func() -> result<descriptor-stat, error-code>since 0.3.0

    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.

  • stat-at: async func( path-flags: path-flags, path: string, ) -> result<descriptor-stat, error-code>since 0.3.0

    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.

  • set-times-at: async func( path-flags: path-flags, path: string, data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp, ) -> result<_, error-code>since 0.3.0

    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.

  • open-at: async func( path-flags: path-flags, path: string, open-flags: open-flags, flags: descriptor-flags, ) -> result<descriptor, error-code>since 0.3.0

    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.

  • remove-directory-at: async func(path: string) -> result<_, error-code>since 0.3.0

    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.

  • rename-at: async func( old-path: string, new-descriptor: borrow<descriptor>, new-path: string, ) -> result<_, error-code>since 0.3.0

    Rename a filesystem object.

    Note: This is similar to renameat in POSIX.

  • is-same-object: async func(other: borrow<descriptor>) -> boolsince 0.3.0

    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.

  • metadata-hash: async func() -> result<metadata-hash-value, error-code>since 0.3.0

    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.

  • metadata-hash-at: async func( path-flags: path-flags, path: string, ) -> result<metadata-hash-value, error-code>since 0.3.0

    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.

Functions

get-directories: func() -> list<tuple<descriptor, string>>since 0.3.0

Return the set of preopened directories, and their paths.

WIT

@since(version = 0.3.0)
interface preopens {
  @since(version = 0.3.0)
  use types.{descriptor};

  /// Return the set of preopened directories, and their paths.
  @since(version = 0.3.0)
  get-directories: func() -> list<tuple<descriptor, string>>;
}