Skip to content
Menu
Contents

Reading the tags

pure

Same arguments, same result; touches nothing outside.

pure if arg2 is

Pure when that argument is a pure function; otherwise as impure as it is.

impure

Reads or changes something outside the program.

WasiFile

12 types41 functions

File access for the component target, over wasi:filesystem: whole-file reads and writes, directory listings and one-level directory changes, in File's types. Contents are Bytes; readText and writeText cross to String through UTF-8.

A path is read against the directories the host grants, its preopens. An absolute path is read in the preopen whose guest path is its longest prefix, and a relative one in the relative preopen that covers the most of it — . covers every relative path. The path is normalized first, and one that climbs out of where it starts, or that no preopen covers, is OutsideSandbox without asking the host to open it. Every failure is FileErr(path, kind) with the path as the caller wrote it.

Every descriptor and stream opened here is dropped before the function returns, on a failure too.

At a glance

  • @Descriptor

    The descriptor resource of wasi:filesystem/types@0.2.3, as a handle.

  • @DirectoryEntryStream

    The directory-entry-stream resource of wasi:filesystem/types@0.2.3, as a handle.

  • ErrorCode

    The view of WIT's error-code type, from wasi:filesystem/types@0.2.3.

  • Advice

    The view of WIT's advice type, from wasi:filesystem/types@0.2.3.

  • DescriptorFlags

    The view of WIT's descriptor-flags type, from wasi:filesystem/types@0.2.3.

  • DescriptorType

    The view of WIT's descriptor-type type, from wasi:filesystem/types@0.2.3.

  • NewTimestamp

    The view of WIT's new-timestamp type, from wasi:filesystem/types@0.2.3.

  • DescriptorStat

    The view of WIT's descriptor-stat type, from wasi:filesystem/types@0.2.3.

  • PathFlags

    The view of WIT's path-flags type, from wasi:filesystem/types@0.2.3.

  • OpenFlags

    The view of WIT's open-flags type, from wasi:filesystem/types@0.2.3.

  • MetadataHashValue

    The view of WIT's metadata-hash-value type, from wasi:filesystem/types@0.2.3.

  • DirectoryEntry

    The view of WIT's directory-entry type, from wasi:filesystem/types@0.2.3.

  • read

    The whole file.

  • readText

    The whole file as text: InvalidUtf8 at the first byte that is not strict UTF-8.

  • write

    Creates the file, or truncates one that exists, and writes bytes to it.

  • writeText

    Writes text to the file as UTF-8, as write writes bytes.

  • append

    Writes bytes after the end of the file, creating it if it is missing.

  • delete

    A file, not a directory: a directory is IsDirectory.

  • list

    The entries directly inside a directory, without . and .., in the order the host lists them, which is not sorted.

  • makeDir

    One level: a missing parent is NotFound.

  • removeDir

    Only an empty directory: anything inside it is NotEmpty.

  • descriptorReadViaStream

    WIT's descriptor.read-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorWriteViaStream

    WIT's descriptor.write-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorAppendViaStream

    WIT's descriptor.append-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorAdvise

    WIT's descriptor.advise method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSyncData

    WIT's descriptor.sync-data method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorGetFlags

    WIT's descriptor.get-flags method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorGetType

    WIT's descriptor.get-type method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSetSize

    WIT's descriptor.set-size method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSetTimes

    WIT's descriptor.set-times method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorRead

    WIT's descriptor.read method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorWrite

    WIT's descriptor.write method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorReadDirectory

    WIT's descriptor.read-directory method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSync

    WIT's descriptor.sync method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorCreateDirectoryAt

    WIT's descriptor.create-directory-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorStat

    WIT's descriptor.stat method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorStatAt

    WIT's descriptor.stat-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSetTimesAt

    WIT's descriptor.set-times-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorLinkAt

    WIT's descriptor.link-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorOpenAt

    WIT's descriptor.open-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorReadlinkAt

    WIT's descriptor.readlink-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorRemoveDirectoryAt

    WIT's descriptor.remove-directory-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorRenameAt

    WIT's descriptor.rename-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorSymlinkAt

    WIT's descriptor.symlink-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorUnlinkFileAt

    WIT's descriptor.unlink-file-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorIsSameObject

    WIT's descriptor.is-same-object method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorMetadataHash

    WIT's descriptor.metadata-hash method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • descriptorMetadataHashAt

    WIT's descriptor.metadata-hash-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • directoryEntryStreamReadDirectoryEntry

    WIT's directory-entry-stream.read-directory-entry method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • filesystemErrorCode

    WIT's filesystem-error-code function, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

  • dropDescriptor

    Drops the descriptor handle, from wasi:filesystem/types@0.2.3.

  • dropDirectoryEntryStream

    Drops the directory-entry-stream handle, from wasi:filesystem/types@0.2.3.

  • getDirectories

    WIT's get-directories function, from wasi:filesystem/preopens@0.2.3, in Bert's view of its types.

Types

@Descriptor

type @Descriptor

The descriptor resource of wasi:filesystem/types@0.2.3, as a handle. It comes only from the functions here that return one. Release it with dropDescriptor.

@DirectoryEntryStream

type @DirectoryEntryStream

The directory-entry-stream resource of wasi:filesystem/types@0.2.3, as a handle. It comes only from the functions here that return one. Release it with dropDirectoryEntryStream.

ErrorCode

ErrorCode = [Access | WouldBlock | Already | BadDescriptor | Busy | Deadlock | Quota | Exist | FileTooLarge | IllegalByteSequence | InProgress | Interrupted | Invalid | Io | IsDirectory | Loop | TooManyLinks | MessageSize | NameTooLong | NoDevice | NoEntry | NoLock | InsufficientMemory | InsufficientSpace | NotDirectory | NotEmpty | NotRecoverable | Unsupported | NoTty | NoSuchDevice | Overflow | NotPermitted | Pipe | ReadOnly | InvalidSeek | TextFileBusy | CrossDevice]

The view of WIT's error-code type, from wasi:filesystem/types@0.2.3.

Advice

Advice = [Normal | Sequential | Random | WillNeed | DontNeed | NoReuse]

The view of WIT's advice type, from wasi:filesystem/types@0.2.3.

DescriptorFlags

DescriptorFlags = { read: Bool, write: Bool, fileIntegritySync: Bool, dataIntegritySync: Bool, requestedWriteSync: Bool, mutateDirectory: Bool }

The view of WIT's descriptor-flags type, from wasi:filesystem/types@0.2.3.

DescriptorType

DescriptorType = [Unknown | BlockDevice | CharacterDevice | Directory | Fifo | SymbolicLink | RegularFile | Socket]

The view of WIT's descriptor-type type, from wasi:filesystem/types@0.2.3.

NewTimestamp

NewTimestamp = [NoChange | Now | Timestamp({ seconds: Int, nanoseconds: Int })]

The view of WIT's new-timestamp type, from wasi:filesystem/types@0.2.3.

DescriptorStat

DescriptorStat = { type_: DescriptorType, linkCount: Int, size: Int, dataAccessTimestamp: [Some({ seconds: Int, nanoseconds: Int }) | None], dataModificationTimestamp: [Some({ seconds: Int, nanoseconds: Int }) | None], statusChangeTimestamp: [Some({ seconds: Int, nanoseconds: Int }) | None] }

The view of WIT's descriptor-stat type, from wasi:filesystem/types@0.2.3.

PathFlags

PathFlags = { symlinkFollow: Bool }

The view of WIT's path-flags type, from wasi:filesystem/types@0.2.3.

OpenFlags

OpenFlags = { create: Bool, directory: Bool, exclusive: Bool, truncate: Bool }

The view of WIT's open-flags type, from wasi:filesystem/types@0.2.3.

MetadataHashValue

MetadataHashValue = { lower: Int, upper: Int }

The view of WIT's metadata-hash-value type, from wasi:filesystem/types@0.2.3.

DirectoryEntry

DirectoryEntry = { type_: DescriptorType, name: String }

The view of WIT's directory-entry type, from wasi:filesystem/types@0.2.3.

Functions

read

(String) -> File.Result(Bytes.@Bytes, [FileErr(String, File.Error) | e])impure

The whole file. A directory is IsDirectory, and anything else that is not a regular file, such as a device or a fifo, is HostError("not a regular file"), since reading one may never end. A file that grows while it is read is read as long as it was when the read began.

readText

(String) -> File.Result(String, [FileErr(String, File.Error) | InvalidUtf8({ pos: Int }) | e])impure

The whole file as text: InvalidUtf8 at the first byte that is not strict UTF-8.

write

(String, Bytes.@Bytes) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

Creates the file, or truncates one that exists, and writes bytes to it.

writeText

(String, String) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

Writes text to the file as UTF-8, as write writes bytes.

append

(String, Bytes.@Bytes) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

Writes bytes after the end of the file, creating it if it is missing.

delete

(String) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

A file, not a directory: a directory is IsDirectory.

list

(String) -> File.Result(List(File.DirEntry), [FileErr(String, File.Error) | e])impure

The entries directly inside a directory, without . and .., in the order the host lists them, which is not sorted.

makeDir

(String) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

One level: a missing parent is NotFound.

removeDir

(String) -> File.Result(Unit, [FileErr(String, File.Error) | e])impure

Only an empty directory: anything inside it is NotEmpty.

descriptorReadViaStream

(@Descriptor, Int) -> [Ok(WasiIo.@InputStream) | Err(ErrorCode)]impure

WIT's descriptor.read-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorWriteViaStream

(@Descriptor, Int) -> [Ok(WasiIo.@OutputStream) | Err(ErrorCode)]impure

WIT's descriptor.write-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorAppendViaStream

WIT's descriptor.append-via-stream method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorAdvise

(@Descriptor, Int, Int, Advice) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.advise method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSyncData

(@Descriptor) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.sync-data method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorGetFlags

(@Descriptor) -> [Ok(DescriptorFlags) | Err(ErrorCode)]impure

WIT's descriptor.get-flags method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorGetType

(@Descriptor) -> [Ok(DescriptorType) | Err(ErrorCode)]impure

WIT's descriptor.get-type method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSetSize

(@Descriptor, Int) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.set-size method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSetTimes

(@Descriptor, NewTimestamp, NewTimestamp) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.set-times method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorRead

(@Descriptor, Int, Int) -> [Ok({ first: Bytes.@Bytes, second: Bool }) | Err(ErrorCode)]impure

WIT's descriptor.read method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorWrite

(@Descriptor, Bytes.@Bytes, Int) -> [Ok(Int) | Err(ErrorCode)]impure

WIT's descriptor.write method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorReadDirectory

WIT's descriptor.read-directory method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSync

(@Descriptor) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.sync method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorCreateDirectoryAt

(@Descriptor, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.create-directory-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorStat

(@Descriptor) -> [Ok(DescriptorStat) | Err(ErrorCode)]impure

WIT's descriptor.stat method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorStatAt

(@Descriptor, PathFlags, String) -> [Ok(DescriptorStat) | Err(ErrorCode)]impure

WIT's descriptor.stat-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSetTimesAt

(@Descriptor, PathFlags, String, NewTimestamp, NewTimestamp) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.set-times-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorLinkAt

(@Descriptor, PathFlags, String, @Descriptor, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.link-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorOpenAt

WIT's descriptor.open-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorReadlinkAt

(@Descriptor, String) -> [Ok(String) | Err(ErrorCode)]impure

WIT's descriptor.readlink-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorRemoveDirectoryAt

(@Descriptor, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.remove-directory-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorRenameAt

(@Descriptor, String, @Descriptor, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.rename-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorSymlinkAt

(@Descriptor, String, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.symlink-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorUnlinkFileAt

(@Descriptor, String) -> [Ok(Unit) | Err(ErrorCode)]impure

WIT's descriptor.unlink-file-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorIsSameObject

(@Descriptor, @Descriptor) -> Boolimpure

WIT's descriptor.is-same-object method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorMetadataHash

(@Descriptor) -> [Ok(MetadataHashValue) | Err(ErrorCode)]impure

WIT's descriptor.metadata-hash method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

descriptorMetadataHashAt

(@Descriptor, PathFlags, String) -> [Ok(MetadataHashValue) | Err(ErrorCode)]impure

WIT's descriptor.metadata-hash-at method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

directoryEntryStreamReadDirectoryEntry

(@DirectoryEntryStream) -> [Ok([Some(DirectoryEntry) | None]) | Err(ErrorCode)]impure

WIT's directory-entry-stream.read-directory-entry method, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

filesystemErrorCode

(WasiIo.@Error) -> [Some(ErrorCode) | None]impure

WIT's filesystem-error-code function, from wasi:filesystem/types@0.2.3, in Bert's view of its types.

dropDescriptor

(@Descriptor) -> Unitimpure

Drops the descriptor handle, from wasi:filesystem/types@0.2.3. Nothing else releases it, and the handle is not used after.

dropDirectoryEntryStream

(@DirectoryEntryStream) -> Unitimpure

Drops the directory-entry-stream handle, from wasi:filesystem/types@0.2.3. Nothing else releases it, and the handle is not used after.

getDirectories

() -> List({ first: @Descriptor, second: String })impure

WIT's get-directories function, from wasi:filesystem/preopens@0.2.3, in Bert's view of its types.

Reading the tags

pure

Same arguments, same result; touches nothing outside.

pure if arg2 is

Pure when that argument is a pure function; otherwise as impure as it is.

impure

Reads or changes something outside the program.