From 54203dec4e88fc249ee82b8fa5d798fb7b20fe51 Mon Sep 17 00:00:00 2001
From: Dan Gohman <dev@sunfishcode.online>
Date: Mon, 22 Nov 2021 13:32:41 -0800
Subject: [PATCH] Port the wasi-filesystem API to the new wai format. #35

This makes a number of changes, to make use of interface-types features such
as expected, variant types, and resources. The change to use resources in
particular means that filesystem functions are now methods of the descriptor
resource. Since this means renaming everything, take this opportunity to
introduce a new naming conventions, with _at being used for functions that
take dirfd+path arguments.

This also eliminates the rights concept what was present in earlier versions
of WASI, has has discussed in #31. This required adding new flags to open_at,
so while here, this also adds basic chmod-like support, as discussed in #33.

And, this removes support for readdir seeking (seekdir/telldir), as discussed
in #7.

And it adds a fifo file type and a more general socket type, as discussed in #4.
---
 README.md              |  110 ++++
 test/README.md         |   11 +
 wasi-filesystem.abi.md | 1121 ++++++++++++++++++++++++++++++++++++++++
 wasi-filesystem.wai.md |  815 +++++++++++++++++++++++++++++
 4 files changed, 2057 insertions(+)
 create mode 100644 README.md
 create mode 100644 test/README.md
 create mode 100644 wasi-filesystem.abi.md
 create mode 100644 wasi-filesystem.wai.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fa56877
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# [Example WASI proposal]
+
+This template can be used to start a new proposal, which can then be proposed in the WASI Subgroup meetings.
+
+The sections below are recommended. However, every proposal is different, and the community can help you flesh out the proposal, so don't block on having something filled in for each one of them.
+
+Thank you to the W3C Privacy CG for the [inspiration](https://github.com/privacycg/template)!
+
+# [Title]
+
+A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
+
+### Current Phase
+
+[Fill in the current phase, e.g. Phase 1]
+
+### Champions
+
+- [Champion 1]
+- [Champion 2]
+- [etc.]
+
+### Phase 4 Advancement Criteria
+
+TODO before entering Phase 2.
+
+## Table of Contents [if the explainer is longer than one printed page]
+
+- [Introduction](#introduction)
+- [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios)
+- [Non-goals](#non-goals)
+- [API walk-through](#api-walk-through)
+  - [Use case 1](#use-case-1)
+  - [Use case 2](#use-case-2)
+- [Detailed design discussion](#detailed-design-discussion)
+  - [[Tricky design choice 1]](#tricky-design-choice-1)
+  - [[Tricky design choice 2]](#tricky-design-choice-2)
+- [Considered alternatives](#considered-alternatives)
+  - [[Alternative 1]](#alternative-1)
+  - [[Alternative 2]](#alternative-2)
+- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback)
+- [References & acknowledgements](#references--acknowledgements)
+
+### Introduction
+
+[The "executive summary" or "abstract". Explain in a few sentences what the goals of the project are, and a brief overview of how the solution works. This should be no more than 1-2 paragraphs.]
+
+### Goals [or Motivating Use Cases, or Scenarios]
+
+[What is the end-user need which this project aims to address?]
+
+### Non-goals
+
+[If there are "adjacent" goals which may appear to be in scope but aren't, enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]
+
+### API walk-through
+
+[Walk through of how someone would use this API.]
+
+#### [Use case 1]
+
+[Provide example code snippets and diagrams explaining how the API would be used to solve the given problem]
+
+#### [Use case 2]
+
+[etc.]
+
+### Detailed design discussion
+
+[This section should mostly refer to the .wai.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.]
+
+#### [Tricky design choice #1]
+
+[Talk through the tradeoffs in coming to the specific design point you want to make.]
+
+```
+// Illustrated with example code.
+```
+
+[This may be an open question, in which case you should link to any active discussion threads.]
+
+#### [Tricky design choice 2]
+
+[etc.]
+
+### Considered alternatives
+
+[This section is not required if you already covered considered alternatives in the design discussion above.]
+
+#### [Alternative 1]
+
+[Describe an alternative which was considered, and why you decided against it.]
+
+#### [Alternative 2]
+
+[etc.]
+
+### Stakeholder Interest & Feedback
+
+TODO before entering Phase 3.
+
+[This should include a list of implementers who have expressed interest in implementing the proposal]
+
+### References & acknowledgements
+
+Many thanks for valuable feedback and advice from:
+
+- [Person 1]
+- [Person 2]
+- [etc.]
diff --git a/test/README.md b/test/README.md
new file mode 100644
index 0000000..c274acd
--- /dev/null
+++ b/test/README.md
@@ -0,0 +1,11 @@
+# Testing guidelines
+
+TK fill in testing guidelines
+
+## Installing the tools
+
+TK fill in instructions
+
+## Running the tests
+
+TK fill in instructions
diff --git a/wasi-filesystem.abi.md b/wasi-filesystem.abi.md
new file mode 100644
index 0000000..80a6f38
--- /dev/null
+++ b/wasi-filesystem.abi.md
@@ -0,0 +1,1121 @@
+# Types
+
+## <a href="#size" name="size"></a> `size`: `u32`
+
+  Size of a range of bytes in memory.
+
+Size: 4, Alignment: 4
+
+## <a href="#filesize" name="filesize"></a> `filesize`: `u64`
+
+  Non-negative file size or length of a region within a file.
+
+Size: 8, Alignment: 8
+
+## <a href="#filedelta" name="filedelta"></a> `filedelta`: `s64`
+
+  Relative offset within a file.
+
+Size: 8, Alignment: 8
+
+## <a href="#timestamp" name="timestamp"></a> `timestamp`: `u64`
+
+  Timestamp in nanoseconds.
+  
+  TODO: wasi-clocks is moving to seconds+nanoseconds.
+
+Size: 8, Alignment: 8
+
+## <a href="#info" name="info"></a> `info`: record
+
+  Information associated with a descriptor.
+  
+  Note: This was called `fdstat` in earlier versions of WASI.
+
+Size: 2, Alignment: 1
+
+### Record Fields
+
+- <a href="info.type" name="info.type"></a> [`type`](#info.type): [`type`](#type)
+
+  The type of filesystem object referenced by a descriptor.
+
+- <a href="info.flags" name="info.flags"></a> [`flags`](#info.flags): [`flags`](#flags)
+
+  Flags associated with a descriptor.
+
+## <a href="#type" name="type"></a> `type`: variant
+
+  The type of a filesystem object referenced by a descriptor.
+  
+  Note: This was called `filetype` in earlier versions of WASI.
+
+Size: 1, Alignment: 1
+
+### Variant Cases
+
+- <a href="type.unknown" name="type.unknown"></a> [`unknown`](#type.unknown)
+
+  The type of the descriptor or file is unknown or is different from
+  any of the other types specified.
+
+- <a href="type.block_device" name="type.block_device"></a> [`block_device`](#type.block_device)
+
+  The descriptor refers to a block device inode.
+
+- <a href="type.character_device" name="type.character_device"></a> [`character_device`](#type.character_device)
+
+  The descriptor refers to a character device inode.
+
+- <a href="type.directory" name="type.directory"></a> [`directory`](#type.directory)
+
+  The descriptor refers to a directory inode.
+
+- <a href="type.fifo" name="type.fifo"></a> [`fifo`](#type.fifo)
+
+  The descriptor refers to a named pipe.
+
+- <a href="type.symbolic_link" name="type.symbolic_link"></a> [`symbolic_link`](#type.symbolic_link)
+
+  The file refers to a symbolic link inode.
+
+- <a href="type.regular_file" name="type.regular_file"></a> [`regular_file`](#type.regular_file)
+
+  The descriptor refers to a regular file inode.
+
+- <a href="type.socket" name="type.socket"></a> [`socket`](#type.socket)
+
+  The descriptor refers to a socket.
+
+## <a href="#flags" name="flags"></a> `flags`: record
+
+  Descriptor flags.
+  
+  Note: This was called `fdflags` in earlier versions of WASI.
+
+Size: 1, Alignment: 1
+
+### Record Fields
+
+- <a href="flags.read" name="flags.read"></a> [`read`](#flags.read): `bool`
+
+  Read mode: Data can be read.
+Bit: 0
+
+- <a href="flags.write" name="flags.write"></a> [`write`](#flags.write): `bool`
+
+  Write mode: Data can be written to.
+Bit: 1
+
+- <a href="flags.append" name="flags.append"></a> [`append`](#flags.append): `bool`
+
+  Append mode: Data written to the file is always appended to the file's
+  end.
+Bit: 2
+
+- <a href="flags.dsync" name="flags.dsync"></a> [`dsync`](#flags.dsync): `bool`
+
+  Write according to synchronized I/O data integrity completion. Only the
+  data stored in the file is synchronized.
+Bit: 3
+
+- <a href="flags.nonblock" name="flags.nonblock"></a> [`nonblock`](#flags.nonblock): `bool`
+
+  Non-blocking mode.
+Bit: 4
+
+- <a href="flags.rsync" name="flags.rsync"></a> [`rsync`](#flags.rsync): `bool`
+
+  Synchronized read I/O operations.
+Bit: 5
+
+- <a href="flags.sync" name="flags.sync"></a> [`sync`](#flags.sync): `bool`
+
+  Write according to synchronized I/O file integrity completion. In
+  addition to synchronizing the data stored in the file, the
+  implementation may also synchronously update the file's metadata.
+Bit: 6
+
+## <a href="#stat" name="stat"></a> `stat`: record
+
+  File attributes.
+  
+  Note: This was called `filestat` in earlier versions of WASI.
+
+Size: 64, Alignment: 8
+
+### Record Fields
+
+- <a href="stat.dev" name="stat.dev"></a> [`dev`](#stat.dev): [`device`](#device)
+
+  Device ID of device containing the file.
+
+- <a href="stat.ino" name="stat.ino"></a> [`ino`](#stat.ino): [`inode`](#inode)
+
+  File serial number.
+
+- <a href="stat.type" name="stat.type"></a> [`type`](#stat.type): [`type`](#type)
+
+  File type.
+
+- <a href="stat.nlink" name="stat.nlink"></a> [`nlink`](#stat.nlink): [`linkcount`](#linkcount)
+
+  Number of hard links to the file.
+
+- <a href="stat.size" name="stat.size"></a> [`size`](#stat.size): [`filesize`](#filesize)
+
+  For regular files, the file size in bytes. For symbolic links, the length
+  in bytes of the pathname contained in the symbolic link.
+
+- <a href="stat.atim" name="stat.atim"></a> [`atim`](#stat.atim): [`timestamp`](#timestamp)
+
+  Last data access timestamp.
+
+- <a href="stat.mtim" name="stat.mtim"></a> [`mtim`](#stat.mtim): [`timestamp`](#timestamp)
+
+  Last data modification timestamp.
+
+- <a href="stat.ctim" name="stat.ctim"></a> [`ctim`](#stat.ctim): [`timestamp`](#timestamp)
+
+  Last file status change timestamp.
+
+## <a href="#lookupflags" name="lookupflags"></a> `lookupflags`: record
+
+  Flags determining the method of how paths are resolved.
+
+Size: 1, Alignment: 1
+
+### Record Fields
+
+- <a href="lookupflags.symlink_follow" name="lookupflags.symlink_follow"></a> [`symlink_follow`](#lookupflags.symlink_follow): `bool`
+
+  As long as the resolved path corresponds to a symbolic link, it is expanded.
+Bit: 0
+
+## <a href="#oflags" name="oflags"></a> `oflags`: record
+
+  Open flags used by `open_at`.
+
+Size: 1, Alignment: 1
+
+### Record Fields
+
+- <a href="oflags.nofollow" name="oflags.nofollow"></a> [`nofollow`](#oflags.nofollow): `bool`
+
+  Fail if path names an existing symbolic link.
+Bit: 0
+
+- <a href="oflags.creat" name="oflags.creat"></a> [`creat`](#oflags.creat): `bool`
+
+  Create file if it does not exist.
+Bit: 1
+
+- <a href="oflags.directory" name="oflags.directory"></a> [`directory`](#oflags.directory): `bool`
+
+  Fail if not a directory.
+Bit: 2
+
+- <a href="oflags.excl" name="oflags.excl"></a> [`excl`](#oflags.excl): `bool`
+
+  Fail if file already exists.
+Bit: 3
+
+- <a href="oflags.trunc" name="oflags.trunc"></a> [`trunc`](#oflags.trunc): `bool`
+
+  Truncate file to size 0.
+Bit: 4
+
+## <a href="#mode" name="mode"></a> `mode`: record
+
+  Permissions mode used by `open_at`, `change_permissions_at`, and similar.
+
+Size: 1, Alignment: 1
+
+### Record Fields
+
+- <a href="mode.readable" name="mode.readable"></a> [`readable`](#mode.readable): `bool`
+
+  True if the resource is considered readable by the containing
+  filesystem.
+Bit: 0
+
+- <a href="mode.writeable" name="mode.writeable"></a> [`writeable`](#mode.writeable): `bool`
+
+  True if the resource is considered writeable by the containing
+  filesystem.
+Bit: 1
+
+- <a href="mode.executable" name="mode.executable"></a> [`executable`](#mode.executable): `bool`
+
+  True if the resource is considered executable by the containing
+  filesystem. This does not apply to directories.
+Bit: 2
+
+## <a href="#linkcount" name="linkcount"></a> `linkcount`: `u64`
+
+  Number of hard links to an inode.
+
+Size: 8, Alignment: 8
+
+## <a href="#device" name="device"></a> `device`: `u64`
+
+  Identifier for a device containing a file system. Can be used in combination
+  with `inode` to uniquely identify a file or directory in the filesystem.
+
+Size: 8, Alignment: 8
+
+## <a href="#inode" name="inode"></a> `inode`: `u64`
+
+
+Size: 8, Alignment: 8
+
+## <a href="#new_timestamp" name="new_timestamp"></a> `new_timestamp`: variant
+
+  When setting a timestamp, this gives the value to set it to.
+
+Size: 16, Alignment: 8
+
+### Variant Cases
+
+- <a href="new_timestamp.no_change" name="new_timestamp.no_change"></a> [`no_change`](#new_timestamp.no_change)
+
+  Leave the timestamp set to its previous value.
+
+- <a href="new_timestamp.now" name="new_timestamp.now"></a> [`now`](#new_timestamp.now)
+
+  Set the timestamp to the current time of the system clock associated
+  with the filesystem.
+
+- <a href="new_timestamp.timestamp" name="new_timestamp.timestamp"></a> [`timestamp`](#new_timestamp.timestamp): [`timestamp`](#timestamp)
+
+  Set the timestamp to the given value.
+
+## <a href="#dirent" name="dirent"></a> `dirent`: record
+
+  A directory entry.
+
+Size: 16, Alignment: 8
+
+### Record Fields
+
+- <a href="dirent.ino" name="dirent.ino"></a> [`ino`](#dirent.ino): [`inode`](#inode)
+
+  The serial number of the file referred to by this directory entry.
+
+- <a href="dirent.namelen" name="dirent.namelen"></a> [`namelen`](#dirent.namelen): [`size`](#size)
+
+  The length of the name of the directory entry.
+
+- <a href="dirent.type" name="dirent.type"></a> [`type`](#dirent.type): [`type`](#type)
+
+  The type of the file referred to by this directory entry.
+
+## <a href="#errno" name="errno"></a> `errno`: variant
+
+  Error codes returned by functions.
+  Not all of these error codes are returned by the functions provided by this
+  API; some are used in higher-level library layers, and others are provided
+  merely for alignment with POSIX.
+
+Size: 1, Alignment: 1
+
+### Variant Cases
+
+- <a href="errno.success" name="errno.success"></a> [`success`](#errno.success)
+
+  No error occurred. System call completed successfully.
+
+- <a href="errno.toobig" name="errno.toobig"></a> [`toobig`](#errno.toobig)
+
+  Argument list too long. This is similar to `E2BIG` in POSIX.
+
+- <a href="errno.access" name="errno.access"></a> [`access`](#errno.access)
+
+  Permission denied.
+
+- <a href="errno.addrinuse" name="errno.addrinuse"></a> [`addrinuse`](#errno.addrinuse)
+
+  Address in use.
+
+- <a href="errno.addrnotavail" name="errno.addrnotavail"></a> [`addrnotavail`](#errno.addrnotavail)
+
+  Address not available.
+
+- <a href="errno.afnosupport" name="errno.afnosupport"></a> [`afnosupport`](#errno.afnosupport)
+
+  Address family not supported.
+
+- <a href="errno.again" name="errno.again"></a> [`again`](#errno.again)
+
+  Resource unavailable, or operation would block.
+
+- <a href="errno.already" name="errno.already"></a> [`already`](#errno.already)
+
+  Connection already in progress.
+
+- <a href="errno.badmsg" name="errno.badmsg"></a> [`badmsg`](#errno.badmsg)
+
+  Bad message.
+
+- <a href="errno.busy" name="errno.busy"></a> [`busy`](#errno.busy)
+
+  Device or resource busy.
+
+- <a href="errno.canceled" name="errno.canceled"></a> [`canceled`](#errno.canceled)
+
+  Operation canceled.
+
+- <a href="errno.child" name="errno.child"></a> [`child`](#errno.child)
+
+  No child processes.
+
+- <a href="errno.connaborted" name="errno.connaborted"></a> [`connaborted`](#errno.connaborted)
+
+  Connection aborted.
+
+- <a href="errno.connrefused" name="errno.connrefused"></a> [`connrefused`](#errno.connrefused)
+
+  Connection refused.
+
+- <a href="errno.connreset" name="errno.connreset"></a> [`connreset`](#errno.connreset)
+
+  Connection reset.
+
+- <a href="errno.deadlk" name="errno.deadlk"></a> [`deadlk`](#errno.deadlk)
+
+  Resource deadlock would occur.
+
+- <a href="errno.destaddrreq" name="errno.destaddrreq"></a> [`destaddrreq`](#errno.destaddrreq)
+
+  Destination address required.
+
+- <a href="errno.dom" name="errno.dom"></a> [`dom`](#errno.dom)
+
+  Mathematics argument out of domain of function.
+
+- <a href="errno.dquot" name="errno.dquot"></a> [`dquot`](#errno.dquot)
+
+  Reserved.
+
+- <a href="errno.exist" name="errno.exist"></a> [`exist`](#errno.exist)
+
+  File exists.
+
+- <a href="errno.fault" name="errno.fault"></a> [`fault`](#errno.fault)
+
+  Bad address.
+
+- <a href="errno.fbig" name="errno.fbig"></a> [`fbig`](#errno.fbig)
+
+  File too large.
+
+- <a href="errno.hostunreach" name="errno.hostunreach"></a> [`hostunreach`](#errno.hostunreach)
+
+  Host is unreachable.
+
+- <a href="errno.idrm" name="errno.idrm"></a> [`idrm`](#errno.idrm)
+
+  Identifier removed.
+
+- <a href="errno.ilseq" name="errno.ilseq"></a> [`ilseq`](#errno.ilseq)
+
+  Illegal byte sequence.
+
+- <a href="errno.inprogress" name="errno.inprogress"></a> [`inprogress`](#errno.inprogress)
+
+  Operation in progress.
+
+- <a href="errno.intr" name="errno.intr"></a> [`intr`](#errno.intr)
+
+  Interrupted function.
+
+- <a href="errno.inval" name="errno.inval"></a> [`inval`](#errno.inval)
+
+  Invalid argument.
+
+- <a href="errno.io" name="errno.io"></a> [`io`](#errno.io)
+
+  I/O error.
+
+- <a href="errno.isconn" name="errno.isconn"></a> [`isconn`](#errno.isconn)
+
+  Socket is connected.
+
+- <a href="errno.isdir" name="errno.isdir"></a> [`isdir`](#errno.isdir)
+
+  Is a directory.
+
+- <a href="errno.loop" name="errno.loop"></a> [`loop`](#errno.loop)
+
+  Too many levels of symbolic links.
+
+- <a href="errno.mfile" name="errno.mfile"></a> [`mfile`](#errno.mfile)
+
+  File descriptor value too large.
+
+- <a href="errno.mlink" name="errno.mlink"></a> [`mlink`](#errno.mlink)
+
+  Too many links.
+
+- <a href="errno.msgsize" name="errno.msgsize"></a> [`msgsize`](#errno.msgsize)
+
+  Message too large.
+
+- <a href="errno.multihop" name="errno.multihop"></a> [`multihop`](#errno.multihop)
+
+  Reserved.
+
+- <a href="errno.nametoolong" name="errno.nametoolong"></a> [`nametoolong`](#errno.nametoolong)
+
+  Filename too long.
+
+- <a href="errno.netdown" name="errno.netdown"></a> [`netdown`](#errno.netdown)
+
+  Network is down.
+
+- <a href="errno.netreset" name="errno.netreset"></a> [`netreset`](#errno.netreset)
+
+  Connection aborted by network.
+
+- <a href="errno.netunreach" name="errno.netunreach"></a> [`netunreach`](#errno.netunreach)
+
+  Network unreachable.
+
+- <a href="errno.nfile" name="errno.nfile"></a> [`nfile`](#errno.nfile)
+
+  Too many files open in system.
+
+- <a href="errno.nobufs" name="errno.nobufs"></a> [`nobufs`](#errno.nobufs)
+
+  No buffer space available.
+
+- <a href="errno.nodev" name="errno.nodev"></a> [`nodev`](#errno.nodev)
+
+  No such device.
+
+- <a href="errno.noent" name="errno.noent"></a> [`noent`](#errno.noent)
+
+  No such file or directory.
+
+- <a href="errno.noexec" name="errno.noexec"></a> [`noexec`](#errno.noexec)
+
+  Executable file format error.
+
+- <a href="errno.nolck" name="errno.nolck"></a> [`nolck`](#errno.nolck)
+
+  No locks available.
+
+- <a href="errno.nolink" name="errno.nolink"></a> [`nolink`](#errno.nolink)
+
+  Reserved.
+
+- <a href="errno.nomem" name="errno.nomem"></a> [`nomem`](#errno.nomem)
+
+  Not enough space.
+
+- <a href="errno.nomsg" name="errno.nomsg"></a> [`nomsg`](#errno.nomsg)
+
+  No message of the desired type.
+
+- <a href="errno.noprotoopt" name="errno.noprotoopt"></a> [`noprotoopt`](#errno.noprotoopt)
+
+  Protocol not available.
+
+- <a href="errno.nospc" name="errno.nospc"></a> [`nospc`](#errno.nospc)
+
+  No space left on device.
+
+- <a href="errno.nosys" name="errno.nosys"></a> [`nosys`](#errno.nosys)
+
+  Function not supported.
+
+- <a href="errno.notconn" name="errno.notconn"></a> [`notconn`](#errno.notconn)
+
+  The socket is not connected.
+
+- <a href="errno.notdir" name="errno.notdir"></a> [`notdir`](#errno.notdir)
+
+  Not a directory or a symbolic link to a directory.
+
+- <a href="errno.notempty" name="errno.notempty"></a> [`notempty`](#errno.notempty)
+
+  Directory not empty.
+
+- <a href="errno.notrecoverable" name="errno.notrecoverable"></a> [`notrecoverable`](#errno.notrecoverable)
+
+  State not recoverable.
+
+- <a href="errno.notsock" name="errno.notsock"></a> [`notsock`](#errno.notsock)
+
+  Not a socket.
+
+- <a href="errno.notsup" name="errno.notsup"></a> [`notsup`](#errno.notsup)
+
+  Not supported, or operation not supported on socket.
+
+- <a href="errno.notty" name="errno.notty"></a> [`notty`](#errno.notty)
+
+  Inappropriate I/O control operation.
+
+- <a href="errno.nxio" name="errno.nxio"></a> [`nxio`](#errno.nxio)
+
+  No such device or address.
+
+- <a href="errno.overflow" name="errno.overflow"></a> [`overflow`](#errno.overflow)
+
+  Value too large to be stored in data type.
+
+- <a href="errno.ownerdead" name="errno.ownerdead"></a> [`ownerdead`](#errno.ownerdead)
+
+  Previous owner died.
+
+- <a href="errno.perm" name="errno.perm"></a> [`perm`](#errno.perm)
+
+  Operation not permitted.
+
+- <a href="errno.pipe" name="errno.pipe"></a> [`pipe`](#errno.pipe)
+
+  Broken pipe.
+
+- <a href="errno.proto" name="errno.proto"></a> [`proto`](#errno.proto)
+
+  Protocol error.
+
+- <a href="errno.protonosupport" name="errno.protonosupport"></a> [`protonosupport`](#errno.protonosupport)
+
+  Protocol not supported.
+
+- <a href="errno.prototype" name="errno.prototype"></a> [`prototype`](#errno.prototype)
+
+  Protocol wrong type for socket.
+
+- <a href="errno.range" name="errno.range"></a> [`range`](#errno.range)
+
+  Result too large.
+
+- <a href="errno.rofs" name="errno.rofs"></a> [`rofs`](#errno.rofs)
+
+  Read-only file system.
+
+- <a href="errno.spipe" name="errno.spipe"></a> [`spipe`](#errno.spipe)
+
+  Invalid seek.
+
+- <a href="errno.srch" name="errno.srch"></a> [`srch`](#errno.srch)
+
+  No such process.
+
+- <a href="errno.stale" name="errno.stale"></a> [`stale`](#errno.stale)
+
+  Reserved.
+
+- <a href="errno.timedout" name="errno.timedout"></a> [`timedout`](#errno.timedout)
+
+  Connection timed out.
+
+- <a href="errno.txtbsy" name="errno.txtbsy"></a> [`txtbsy`](#errno.txtbsy)
+
+  Text file busy.
+
+- <a href="errno.xdev" name="errno.xdev"></a> [`xdev`](#errno.xdev)
+
+  Cross-device link.
+
+- <a href="errno.notcapable" name="errno.notcapable"></a> [`notcapable`](#errno.notcapable)
+
+  Extension: Capabilities insufficient.
+
+## <a href="#advice" name="advice"></a> `advice`: variant
+
+  File or memory access pattern advisory information.
+
+Size: 1, Alignment: 1
+
+### Variant Cases
+
+- <a href="advice.normal" name="advice.normal"></a> [`normal`](#advice.normal)
+
+  The application has no advice to give on its behavior with respect to the specified data.
+
+- <a href="advice.sequential" name="advice.sequential"></a> [`sequential`](#advice.sequential)
+
+  The application expects to access the specified data sequentially from lower offsets to higher offsets.
+
+- <a href="advice.random" name="advice.random"></a> [`random`](#advice.random)
+
+  The application expects to access the specified data in a random order.
+
+- <a href="advice.willneed" name="advice.willneed"></a> [`willneed`](#advice.willneed)
+
+  The application expects to access the specified data in the near future.
+
+- <a href="advice.dontneed" name="advice.dontneed"></a> [`dontneed`](#advice.dontneed)
+
+  The application expects that it will not access the specified data in the near future.
+
+- <a href="advice.noreuse" name="advice.noreuse"></a> [`noreuse`](#advice.noreuse)
+
+  The application expects to access the specified data once and then not reuse it thereafter.
+
+## <a href="#seek_from" name="seek_from"></a> `seek_from`: variant
+
+  The position relative to which to set the offset of the descriptor.
+
+Size: 16, Alignment: 8
+
+### Variant Cases
+
+- <a href="seek_from.set" name="seek_from.set"></a> [`set`](#seek_from.set): [`filesize`](#filesize)
+
+  Seek relative to start-of-file.
+
+- <a href="seek_from.cur" name="seek_from.cur"></a> [`cur`](#seek_from.cur): [`filedelta`](#filedelta)
+
+  Seek relative to current position.
+
+- <a href="seek_from.end" name="seek_from.end"></a> [`end`](#seek_from.end): [`filesize`](#filesize)
+
+  Seek relative to end-of-file.
+
+# Functions
+
+----
+
+#### <a href="#descriptor_fadvise" name="descriptor_fadvise"></a> `descriptor::fadvise` 
+
+  Provide file advisory information on a descriptor.
+  
+  This is similar to `posix_fadvise` in POSIX.
+##### Params
+
+- <a href="#descriptor_fadvise.self" name="descriptor_fadvise.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_fadvise.offset" name="descriptor_fadvise.offset"></a> `offset`: `u64`
+- <a href="#descriptor_fadvise.len" name="descriptor_fadvise.len"></a> `len`: `u64`
+- <a href="#descriptor_fadvise.advice" name="descriptor_fadvise.advice"></a> `advice`: [`advice`](#advice)
+##### Results
+
+- <a href="#descriptor_fadvise." name="descriptor_fadvise."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_fallocate" name="descriptor_fallocate"></a> `descriptor::fallocate` 
+
+  Force the allocation of space in a file.
+  
+  Note: This is similar to `posix_fallocate` in POSIX.
+##### Params
+
+- <a href="#descriptor_fallocate.self" name="descriptor_fallocate.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_fallocate.offset" name="descriptor_fallocate.offset"></a> `offset`: [`filesize`](#filesize)
+- <a href="#descriptor_fallocate.len" name="descriptor_fallocate.len"></a> `len`: [`filesize`](#filesize)
+##### Results
+
+- <a href="#descriptor_fallocate." name="descriptor_fallocate."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_datasync" name="descriptor_datasync"></a> `descriptor::datasync` 
+
+  Synchronize the data of a file to disk.
+  
+  Note: This is similar to `fdatasync` in POSIX.
+##### Params
+
+- <a href="#descriptor_datasync.self" name="descriptor_datasync.self"></a> `self`: handle<descriptor>
+##### Results
+
+- <a href="#descriptor_datasync." name="descriptor_datasync."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_info" name="descriptor_info"></a> `descriptor::info` 
+
+  Get information associated with a descriptor.
+  
+  Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well
+  as additional fields.
+  
+  Note: This was called `fdstat_get` in earlier versions of WASI.
+##### Params
+
+- <a href="#descriptor_info.self" name="descriptor_info.self"></a> `self`: handle<descriptor>
+##### Results
+
+- <a href="#descriptor_info." name="descriptor_info."></a> ``: expected<[`info`](#info), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_set_size" name="descriptor_set_size"></a> `descriptor::set_size` 
+
+  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.
+##### Params
+
+- <a href="#descriptor_set_size.self" name="descriptor_set_size.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_set_size.size" name="descriptor_set_size.size"></a> `size`: [`filesize`](#filesize)
+##### Results
+
+- <a href="#descriptor_set_size." name="descriptor_set_size."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_set_times" name="descriptor_set_times"></a> `descriptor::set_times` 
+
+  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.
+##### Params
+
+- <a href="#descriptor_set_times.self" name="descriptor_set_times.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_set_times.atim" name="descriptor_set_times.atim"></a> `atim`: [`new_timestamp`](#new_timestamp)
+- <a href="#descriptor_set_times.mtim" name="descriptor_set_times.mtim"></a> `mtim`: [`new_timestamp`](#new_timestamp)
+##### Results
+
+- <a href="#descriptor_set_times." name="descriptor_set_times."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_pread" name="descriptor_pread"></a> `descriptor::pread` 
+
+  Read from a descriptor, without using and updating the descriptor's offset.
+  
+  Note: This is similar to `pread` in POSIX.
+##### Params
+
+- <a href="#descriptor_pread.self" name="descriptor_pread.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_pread.buf" name="descriptor_pread.buf"></a> `buf`: push-buffer<`u8`>
+- <a href="#descriptor_pread.offset" name="descriptor_pread.offset"></a> `offset`: [`filesize`](#filesize)
+##### Results
+
+- <a href="#descriptor_pread." name="descriptor_pread."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_pwrite" name="descriptor_pwrite"></a> `descriptor::pwrite` 
+
+  Write to a descriptor, without using and updating the descriptor's offset.
+  
+  Note: This is similar to `pwrite` in POSIX.
+##### Params
+
+- <a href="#descriptor_pwrite.self" name="descriptor_pwrite.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_pwrite.buf" name="descriptor_pwrite.buf"></a> `buf`: pull-buffer<`u8`>
+- <a href="#descriptor_pwrite.offset" name="descriptor_pwrite.offset"></a> `offset`: [`filesize`](#filesize)
+##### Results
+
+- <a href="#descriptor_pwrite." name="descriptor_pwrite."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_read" name="descriptor_read"></a> `descriptor::read` 
+
+  Read from a descriptor.
+  
+  The meaning of `read` on a directory is unspecified.
+  
+  Note: This is similar to `read` in POSIX.
+##### Params
+
+- <a href="#descriptor_read.self" name="descriptor_read.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_read.buf" name="descriptor_read.buf"></a> `buf`: push-buffer<`u8`>
+##### Results
+
+- <a href="#descriptor_read." name="descriptor_read."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_readdir" name="descriptor_readdir"></a> `descriptor::readdir` 
+
+  Read directory entries from a directory.
+  
+  When successful, the contents of the output buffer consist of a sequence of
+  directory entries. Each directory entry consists of a `dirent` object,
+  followed by `dirent::d_namlen` bytes holding the name of the directory
+  entry.
+  
+  This function fills the output buffer as much as possible, potentially
+  truncating the last directory entry. This allows the caller to grow its
+  read buffer size in case it's too small to fit a single large directory
+  entry, or skip the oversized directory entry.
+##### Params
+
+- <a href="#descriptor_readdir.self" name="descriptor_readdir.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_readdir.buf" name="descriptor_readdir.buf"></a> `buf`: push-buffer<`u8`>
+- <a href="#descriptor_readdir.rewind" name="descriptor_readdir.rewind"></a> `rewind`: `bool`
+##### Results
+
+- <a href="#descriptor_readdir." name="descriptor_readdir."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_seek" name="descriptor_seek"></a> `descriptor::seek` 
+
+  Move the offset of a descriptor.
+  
+  The meaning of `seek` on a directory is unspecified.
+  
+  Note: This is similar to `lseek` in POSIX.
+##### Params
+
+- <a href="#descriptor_seek.self" name="descriptor_seek.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_seek.from" name="descriptor_seek.from"></a> `from`: [`seek_from`](#seek_from)
+##### Results
+
+- <a href="#descriptor_seek." name="descriptor_seek."></a> ``: expected<[`filesize`](#filesize), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_sync" name="descriptor_sync"></a> `descriptor::sync` 
+
+  Synchronize the data and metadata of a file to disk.
+  
+  Note: This is similar to `fsync` in POSIX.
+##### Params
+
+- <a href="#descriptor_sync.self" name="descriptor_sync.self"></a> `self`: handle<descriptor>
+##### Results
+
+- <a href="#descriptor_sync." name="descriptor_sync."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_tell" name="descriptor_tell"></a> `descriptor::tell` 
+
+  Return the current offset of a descriptor.
+  
+  Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX.
+##### Params
+
+- <a href="#descriptor_tell.self" name="descriptor_tell.self"></a> `self`: handle<descriptor>
+##### Results
+
+- <a href="#descriptor_tell." name="descriptor_tell."></a> ``: expected<[`filesize`](#filesize), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_write" name="descriptor_write"></a> `descriptor::write` 
+
+  Write to a descriptor.
+  
+  Note: This is similar to `write` in POSIX.
+##### Params
+
+- <a href="#descriptor_write.self" name="descriptor_write.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_write.buf" name="descriptor_write.buf"></a> `buf`: pull-buffer<`u8`>
+##### Results
+
+- <a href="#descriptor_write." name="descriptor_write."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_create_directory_at" name="descriptor_create_directory_at"></a> `descriptor::create_directory_at` 
+
+  Create a directory.
+  
+  Note: This is similar to `mkdirat` in POSIX.
+##### Params
+
+- <a href="#descriptor_create_directory_at.self" name="descriptor_create_directory_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_create_directory_at.path" name="descriptor_create_directory_at.path"></a> `path`: `string`
+##### Results
+
+- <a href="#descriptor_create_directory_at." name="descriptor_create_directory_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_stat_at" name="descriptor_stat_at"></a> `descriptor::stat_at` 
+
+  Return the attributes of a file or directory.
+  
+  Note: This is similar to `fstatat` in POSIX.
+  
+  Note: This was called `fd_filestat_get` in earlier versions of WASI.
+##### Params
+
+- <a href="#descriptor_stat_at.self" name="descriptor_stat_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_stat_at.lookupflags" name="descriptor_stat_at.lookupflags"></a> `lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_stat_at.path" name="descriptor_stat_at.path"></a> `path`: `string`
+##### Results
+
+- <a href="#descriptor_stat_at." name="descriptor_stat_at."></a> ``: expected<[`stat`](#stat), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_set_times_at" name="descriptor_set_times_at"></a> `descriptor::set_times_at` 
+
+  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.
+##### Params
+
+- <a href="#descriptor_set_times_at.self" name="descriptor_set_times_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_set_times_at.lookupflags" name="descriptor_set_times_at.lookupflags"></a> `lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_set_times_at.path" name="descriptor_set_times_at.path"></a> `path`: `string`
+- <a href="#descriptor_set_times_at.atim" name="descriptor_set_times_at.atim"></a> `atim`: [`new_timestamp`](#new_timestamp)
+- <a href="#descriptor_set_times_at.mtim" name="descriptor_set_times_at.mtim"></a> `mtim`: [`new_timestamp`](#new_timestamp)
+##### Results
+
+- <a href="#descriptor_set_times_at." name="descriptor_set_times_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_link_at" name="descriptor_link_at"></a> `descriptor::link_at` 
+
+  Create a hard link.
+  
+  Note: This is similar to `linkat` in POSIX.
+##### Params
+
+- <a href="#descriptor_link_at.self" name="descriptor_link_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_link_at.old_lookupflags" name="descriptor_link_at.old_lookupflags"></a> `old_lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_link_at.old_path" name="descriptor_link_at.old_path"></a> `old_path`: `string`
+- <a href="#descriptor_link_at.new_descriptor" name="descriptor_link_at.new_descriptor"></a> `new_descriptor`: handle<descriptor>
+- <a href="#descriptor_link_at.new_path" name="descriptor_link_at.new_path"></a> `new_path`: `string`
+##### Results
+
+- <a href="#descriptor_link_at." name="descriptor_link_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_open_at" name="descriptor_open_at"></a> `descriptor::open_at` 
+
+  Open a file or directory.
+  
+  The returned descriptor is not guaranteed to be the lowest-numbered
+  descriptor not currently open/ it is randomized to prevent applications
+  from depending on making assumptions about indexes, since this is
+  error-prone in multi-threaded contexts. The returned descriptor is
+  guaranteed to be less than 2**31.
+  
+  Note: This is similar to `openat` in POSIX.
+  
+  TODO: Re-evaluate `direflags` here.
+  TODO: Add a permissions mode.
+##### Params
+
+- <a href="#descriptor_open_at.self" name="descriptor_open_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_open_at.lookupflags" name="descriptor_open_at.lookupflags"></a> `lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_open_at.path" name="descriptor_open_at.path"></a> `path`: `string`
+- <a href="#descriptor_open_at.oflags" name="descriptor_open_at.oflags"></a> `oflags`: [`oflags`](#oflags)
+- <a href="#descriptor_open_at.fdflags" name="descriptor_open_at.fdflags"></a> `fdflags`: [`flags`](#flags)
+- <a href="#descriptor_open_at.mode" name="descriptor_open_at.mode"></a> `mode`: [`mode`](#mode)
+##### Results
+
+- <a href="#descriptor_open_at." name="descriptor_open_at."></a> ``: expected<handle<descriptor>, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_readlink_at" name="descriptor_readlink_at"></a> `descriptor::readlink_at` 
+
+  Read the contents of a symbolic link.
+  
+  Note: This is similar to `readlinkat` in POSIX.
+##### Params
+
+- <a href="#descriptor_readlink_at.self" name="descriptor_readlink_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_readlink_at.path" name="descriptor_readlink_at.path"></a> `path`: `string`
+- <a href="#descriptor_readlink_at.buf" name="descriptor_readlink_at.buf"></a> `buf`: push-buffer<`u8`>
+##### Results
+
+- <a href="#descriptor_readlink_at." name="descriptor_readlink_at."></a> ``: expected<[`size`](#size), [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_remove_directory_at" name="descriptor_remove_directory_at"></a> `descriptor::remove_directory_at` 
+
+  Remove a directory.
+  
+  Return `errno::notempty` if the directory is not empty.
+  
+  Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
+##### Params
+
+- <a href="#descriptor_remove_directory_at.self" name="descriptor_remove_directory_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_remove_directory_at.path" name="descriptor_remove_directory_at.path"></a> `path`: `string`
+##### Results
+
+- <a href="#descriptor_remove_directory_at." name="descriptor_remove_directory_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_rename_at" name="descriptor_rename_at"></a> `descriptor::rename_at` 
+
+  Rename a filesystem object.
+  
+  Note: This is similar to `renameat` in POSIX.
+##### Params
+
+- <a href="#descriptor_rename_at.self" name="descriptor_rename_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_rename_at.old_path" name="descriptor_rename_at.old_path"></a> `old_path`: `string`
+- <a href="#descriptor_rename_at.new_descriptor" name="descriptor_rename_at.new_descriptor"></a> `new_descriptor`: handle<descriptor>
+- <a href="#descriptor_rename_at.new_path" name="descriptor_rename_at.new_path"></a> `new_path`: `string`
+##### Results
+
+- <a href="#descriptor_rename_at." name="descriptor_rename_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_symlink_at" name="descriptor_symlink_at"></a> `descriptor::symlink_at` 
+
+  Create a symbolic link.
+  
+  Note: This is similar to `symlinkat` in POSIX.
+##### Params
+
+- <a href="#descriptor_symlink_at.self" name="descriptor_symlink_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_symlink_at.old_path" name="descriptor_symlink_at.old_path"></a> `old_path`: `string`
+- <a href="#descriptor_symlink_at.new_path" name="descriptor_symlink_at.new_path"></a> `new_path`: `string`
+##### Results
+
+- <a href="#descriptor_symlink_at." name="descriptor_symlink_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_unlink_file_at" name="descriptor_unlink_file_at"></a> `descriptor::unlink_file_at` 
+
+  Unlink a filesystem object that is not a directory.
+  
+  Return `errno::isdir` if the path refers to a directory.
+  Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
+##### Params
+
+- <a href="#descriptor_unlink_file_at.self" name="descriptor_unlink_file_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_unlink_file_at.path" name="descriptor_unlink_file_at.path"></a> `path`: `string`
+##### Results
+
+- <a href="#descriptor_unlink_file_at." name="descriptor_unlink_file_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_change_file_permissions_at" name="descriptor_change_file_permissions_at"></a> `descriptor::change_file_permissions_at` 
+
+##### Params
+
+- <a href="#descriptor_change_file_permissions_at.self" name="descriptor_change_file_permissions_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_change_file_permissions_at.lookupflags" name="descriptor_change_file_permissions_at.lookupflags"></a> `lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_change_file_permissions_at.path" name="descriptor_change_file_permissions_at.path"></a> `path`: `string`
+- <a href="#descriptor_change_file_permissions_at.mode" name="descriptor_change_file_permissions_at.mode"></a> `mode`: [`mode`](#mode)
+##### Results
+
+- <a href="#descriptor_change_file_permissions_at." name="descriptor_change_file_permissions_at."></a> ``: expected<_, [`errno`](#errno)>
+
+----
+
+#### <a href="#descriptor_change_directory_permissions_at" name="descriptor_change_directory_permissions_at"></a> `descriptor::change_directory_permissions_at` 
+
+##### Params
+
+- <a href="#descriptor_change_directory_permissions_at.self" name="descriptor_change_directory_permissions_at.self"></a> `self`: handle<descriptor>
+- <a href="#descriptor_change_directory_permissions_at.lookupflags" name="descriptor_change_directory_permissions_at.lookupflags"></a> `lookupflags`: [`lookupflags`](#lookupflags)
+- <a href="#descriptor_change_directory_permissions_at.path" name="descriptor_change_directory_permissions_at.path"></a> `path`: `string`
+- <a href="#descriptor_change_directory_permissions_at.mode" name="descriptor_change_directory_permissions_at.mode"></a> `mode`: [`mode`](#mode)
+##### Results
+
+- <a href="#descriptor_change_directory_permissions_at." name="descriptor_change_directory_permissions_at."></a> ``: expected<_, [`errno`](#errno)>
+
diff --git a/wasi-filesystem.wai.md b/wasi-filesystem.wai.md
new file mode 100644
index 0000000..5ce49a4
--- /dev/null
+++ b/wasi-filesystem.wai.md
@@ -0,0 +1,815 @@
+# WASI Filesystem API
+
+WASI filesystem is a filesystem API primarily intended to let users run WASI
+programs that access their files on their existing filesystems, without
+significant overhead.
+
+It is intended to be roughly portable between Unix-family platforms and
+Windows, though it does not hide many of the major differences.
+
+Paths are passed as interface-type `string`s, meaning they must consist of
+a sequence of Unicode Scalar Values (USVs). Some filesystems may contain paths
+which are not accessible by this API.
+
+Some of the content and ideas here are derived from
+[CloudABI](https://github.com/NuxiNL/cloudabi).
+
+## `size`
+```wai
+/// Size of a range of bytes in memory.
+type size = u32
+```
+
+## `filesize`
+```wai
+/// Non-negative file size or length of a region within a file.
+type filesize = u64
+```
+
+## `filedelta`
+```wai
+/// Relative offset within a file.
+type filedelta = s64
+```
+
+## `timestamp`
+```wai
+/// Timestamp in nanoseconds.
+///
+/// TODO: wasi-clocks is moving to seconds+nanoseconds.
+type timestamp = u64
+```
+
+## `info`
+```wai
+/// Information associated with a descriptor.
+///
+/// Note: This was called `fdstat` in earlier versions of WASI.
+record info {
+    /// The type of filesystem object referenced by a descriptor.
+    "type": "type",
+    /// Flags associated with a descriptor.
+    "flags": "flags",
+}
+```
+
+## `type`
+```wai
+/// The type of a filesystem object referenced by a descriptor.
+///
+/// Note: This was called `filetype` in earlier versions of WASI.
+enum "type" {
+    /// The type of the descriptor or file is unknown or is different from
+    /// any of the other types specified.
+    unknown,
+    /// The descriptor refers to a block device inode.
+    block_device,
+    /// The descriptor refers to a character device inode.
+    character_device,
+    /// The descriptor refers to a directory inode.
+    directory,
+    /// The descriptor refers to a named pipe.
+    fifo,
+    /// The file refers to a symbolic link inode.
+    symbolic_link,
+    /// The descriptor refers to a regular file inode.
+    regular_file,
+    /// The descriptor refers to a socket.
+    socket,
+}
+```
+
+## `flags`
+```wai
+/// Descriptor flags.
+///
+/// Note: This was called `fdflags` in earlier versions of WASI.
+flags "flags" {
+    /// Read mode: Data can be read.
+    read,
+    /// Write mode: Data can be written to.
+    write,
+    /// Append mode: Data written to the file is always appended to the file's
+    /// end.
+    append,
+    /// Write according to synchronized I/O data integrity completion. Only the
+    /// data stored in the file is synchronized.
+    dsync,
+    /// Non-blocking mode.
+    nonblock,
+    /// Synchronized read I/O operations.
+    rsync,
+    /// Write according to synchronized I/O file integrity completion. In
+    /// addition to synchronizing the data stored in the file, the
+    /// implementation may also synchronously update the file's metadata.
+    sync,
+}
+```
+
+## `stat`
+```wai
+/// File attributes.
+/// 
+/// Note: This was called `filestat` in earlier versions of WASI.
+record stat {
+    /// Device ID of device containing the file.
+    dev: device,
+    /// File serial number.
+    ino: inode,
+    /// File type.
+    "type": "type",
+    /// Number of hard links to the file.
+    nlink: linkcount,
+    /// For regular files, the file size in bytes. For symbolic links, the length
+    /// in bytes of the pathname contained in the symbolic link.
+    size: filesize,
+    /// Last data access timestamp.
+    atim: timestamp,
+    /// Last data modification timestamp.
+    mtim: timestamp,
+    /// Last file status change timestamp.
+    ctim: timestamp,
+}
+```
+
+## `lookupflags`
+```wai
+/// Flags determining the method of how paths are resolved.
+flags lookupflags {
+    /// As long as the resolved path corresponds to a symbolic link, it is expanded.
+    symlink_follow,
+}
+```
+
+## `oflags`
+```wai
+/// Open flags used by `open_at`.
+flags oflags {
+    /// Fail if path names an existing symbolic link.
+    nofollow,
+    /// Create file if it does not exist.
+    creat,
+    /// Fail if not a directory.
+    directory,
+    /// Fail if file already exists.
+    excl,
+    /// Truncate file to size 0.
+    trunc,
+}
+```
+
+## `mode`
+```wai
+/// Permissions mode used by `open_at`, `change_permissions_at`, and similar.
+flags mode {
+    /// True if the resource is considered readable by the containing
+    /// filesystem.
+    readable,
+    /// True if the resource is considered writeable by the containing
+    /// filesystem.
+    writeable,
+    /// True if the resource is considered executable by the containing
+    /// filesystem. This does not apply to directories.
+    executable,
+}
+```
+
+## `linkcount`
+```wai
+/// Number of hard links to an inode.
+type linkcount = u64
+```
+
+## `device`
+```wai
+/// Identifier for a device containing a file system. Can be used in combination
+/// with `inode` to uniquely identify a file or directory in the filesystem.
+type device = u64
+```
+
+## `inode`
+/// Filesystem object serial number that is unique within its file system.
+```wai
+type inode = u64
+```
+
+## `new_timestamp`
+```wai
+/// When setting a timestamp, this gives the value to set it to.
+variant new_timestamp {
+    /// Leave the timestamp set to its previous value.
+    no_change,
+    /// Set the timestamp to the current time of the system clock associated
+    /// with the filesystem.
+    now,
+    /// Set the timestamp to the given value.
+    timestamp(timestamp),
+}
+```
+
+## `dirent`
+```wai
+/// A directory entry. 
+record dirent {
+    /// The serial number of the file referred to by this directory entry.
+    ino: inode,
+    /// The length of the name of the directory entry.
+    namelen: size,
+    /// The type of the file referred to by this directory entry.
+    "type": "type",
+}
+```
+
+## `errno`
+```wai
+/// Error codes returned by functions.
+/// Not all of these error codes are returned by the functions provided by this
+/// API; some are used in higher-level library layers, and others are provided
+/// merely for alignment with POSIX.
+enum errno {
+    /// No error occurred. System call completed successfully.
+    success,
+    /// Argument list too long. This is similar to `E2BIG` in POSIX.
+    toobig,
+    /// Permission denied.
+    access,
+    /// Address in use.
+    addrinuse,
+    /// Address not available.
+    addrnotavail,
+    /// Address family not supported.
+    afnosupport,
+    /// Resource unavailable, or operation would block.
+    again,
+    /// Connection already in progress.
+    already,
+    /// Bad message.
+    badmsg,
+    /// Device or resource busy.
+    busy,
+    /// Operation canceled.
+    canceled,
+    /// No child processes.
+    child,
+    /// Connection aborted.
+    connaborted,
+    /// Connection refused.
+    connrefused,
+    /// Connection reset.
+    connreset,
+    /// Resource deadlock would occur.
+    deadlk,
+    /// Destination address required.
+    destaddrreq,
+    /// Mathematics argument out of domain of function.
+    dom,
+    /// Reserved.
+    dquot,
+    /// File exists.
+    exist,
+    /// Bad address.
+    fault,
+    /// File too large.
+    fbig,
+    /// Host is unreachable.
+    hostunreach,
+    /// Identifier removed.
+    idrm,
+    /// Illegal byte sequence.
+    ilseq,
+    /// Operation in progress.
+    inprogress,
+    /// Interrupted function.
+    intr,
+    /// Invalid argument.
+    inval,
+    /// I/O error.
+    io,
+    /// Socket is connected.
+    isconn,
+    /// Is a directory.
+    isdir,
+    /// Too many levels of symbolic links.
+    loop,
+    /// File descriptor value too large.
+    mfile,
+    /// Too many links.
+    mlink,
+    /// Message too large.
+    msgsize,
+    /// Reserved.
+    multihop,
+    /// Filename too long.
+    nametoolong,
+    /// Network is down.
+    netdown,
+    /// Connection aborted by network.
+    netreset,
+    /// Network unreachable.
+    netunreach,
+    /// Too many files open in system.
+    nfile,
+    /// No buffer space available.
+    nobufs,
+    /// No such device.
+    nodev,
+    /// No such file or directory.
+    noent,
+    /// Executable file format error.
+    noexec,
+    /// No locks available.
+    nolck,
+    /// Reserved.
+    nolink,
+    /// Not enough space.
+    nomem,
+    /// No message of the desired type.
+    nomsg,
+    /// Protocol not available.
+    noprotoopt,
+    /// No space left on device.
+    nospc,
+    /// Function not supported.
+    nosys,
+    /// The socket is not connected.
+    notconn,
+    /// Not a directory or a symbolic link to a directory.
+    notdir,
+    /// Directory not empty.
+    notempty,
+    /// State not recoverable.
+    notrecoverable,
+    /// Not a socket.
+    notsock,
+    /// Not supported, or operation not supported on socket.
+    notsup,
+    /// Inappropriate I/O control operation.
+    notty,
+    /// No such device or address.
+    nxio,
+    /// Value too large to be stored in data type.
+    overflow,
+    /// Previous owner died.
+    ownerdead,
+    /// Operation not permitted.
+    perm,
+    /// Broken pipe.
+    pipe,
+    /// Protocol error.
+    proto,
+    /// Protocol not supported.
+    protonosupport,
+    /// Protocol wrong type for socket.
+    prototype,
+    /// Result too large.
+    range,
+    /// Read-only file system.
+    rofs,
+    /// Invalid seek.
+    spipe,
+    /// No such process.
+    srch,
+    /// Reserved.
+    stale,
+    /// Connection timed out.
+    timedout,
+    /// Text file busy.
+    txtbsy,
+    /// Cross-device link.
+    xdev,
+    /// Extension: Capabilities insufficient.
+    notcapable,
+}
+```
+
+## `advice`
+```wai
+/// File or memory access pattern advisory information.
+enum advice {
+    /// The application has no advice to give on its behavior with respect to the specified data.
+    normal,
+    /// The application expects to access the specified data sequentially from lower offsets to higher offsets.
+    sequential,
+    /// The application expects to access the specified data in a random order.
+    random,
+    /// The application expects to access the specified data in the near future.
+    willneed,
+    /// The application expects that it will not access the specified data in the near future.
+    dontneed,
+    /// The application expects to access the specified data once and then not reuse it thereafter.
+    noreuse,
+}
+```
+
+## `seek_from`
+```wai
+/// The position relative to which to set the offset of the descriptor.
+variant seek_from {
+    /// Seek relative to start-of-file.
+    set(filesize),
+    /// Seek relative to current position.
+    cur(filedelta),
+    /// Seek relative to end-of-file.
+    end(filesize),
+}
+```
+
+## `descriptor`
+```wai
+/// 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.
+resource descriptor {
+```
+
+## `fadvise`
+```wai
+/// Provide file advisory information on a descriptor.
+///
+/// This is similar to `posix_fadvise` in POSIX.
+fadvise: function(
+    /// The offset within the file to which the advisory applies.
+    offset: u64,
+    /// The length of the region to which the advisory applies.
+    len: u64,
+    /// The advice.
+    advice: advice
+) -> expected<_, errno>
+```
+
+## `fallocate`
+```wai
+/// Force the allocation of space in a file.
+///
+/// Note: This is similar to `posix_fallocate` in POSIX.
+fallocate: function(
+    /// The offset at which to start the allocation.
+    offset: filesize,
+    /// The length of the area that is allocated.
+    len: filesize
+) -> expected<_, errno>
+```
+
+## `fdatasync`
+```wai
+/// Synchronize the data of a file to disk.
+///
+/// Note: This is similar to `fdatasync` in POSIX.
+datasync: function() -> expected<_, errno>
+```
+
+## `info`
+```wai
+/// Get information associated with a descriptor.
+///
+/// Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well
+/// as additional fields.
+///
+/// Note: This was called `fdstat_get` in earlier versions of WASI.
+info: function() -> expected<info, errno>
+```
+
+## `set_size`
+```wai
+/// 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_size: function(size: filesize) -> expected<_, errno>
+```
+
+## `set_times`
+```wai
+/// 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.
+set_times: function(
+    /// The desired values of the data access timestamp.
+    atim: new_timestamp,
+    /// The desired values of the data modification timestamp.
+    mtim: new_timestamp,
+) -> expected<_, errno>
+```
+
+## `pread`
+```wai
+/// Read from a descriptor, without using and updating the descriptor's offset.
+///
+/// Note: This is similar to `pread` in POSIX.
+pread: function(
+    /// Buffer to read into
+    buf: push-buffer<u8>,
+    /// The offset within the file at which to read.
+    offset: filesize,
+) -> expected<size, errno>
+```
+
+## `pwrite`
+```wai
+/// Write to a descriptor, without using and updating the descriptor's offset.
+///
+/// Note: This is similar to `pwrite` in POSIX.
+pwrite: function(
+    /// Data to write
+    buf: pull-buffer<u8>,
+    /// The offset within the file at which to write.
+    offset: filesize,
+) -> expected<size, errno>
+```
+
+## `read`
+```wai
+/// Read from a descriptor.
+///
+/// The meaning of `read` on a directory is unspecified.
+///
+/// Note: This is similar to `read` in POSIX.
+read: function(
+    /// Where to read into
+    buf: push-buffer<u8>,
+) -> expected<size, errno>
+```
+
+## `readdir`
+```wai
+/// Read directory entries from a directory.
+///
+/// When successful, the contents of the output buffer consist of a sequence of
+/// directory entries. Each directory entry consists of a `dirent` object,
+/// followed by `dirent::d_namlen` bytes holding the name of the directory
+/// entry.
+//
+/// This function fills the output buffer as much as possible, potentially
+/// truncating the last directory entry. This allows the caller to grow its
+/// read buffer size in case it's too small to fit a single large directory
+/// entry, or skip the oversized directory entry.
+readdir: function(
+    /// The buffer where directory entries are stored
+    ///
+    /// TODO: Ideally we should return directory entries as typed records.
+    buf: push-buffer<u8>,
+    /// If true, rewind the current position to the beginning before reading.
+    rewind: bool,
+) -> (
+    /// The number of bytes stored in the read buffer. If less than the size of
+    /// the read buffer, the end of the directory has been reached.
+    expected<size, errno>
+)
+```
+
+## `seek`
+```wai
+/// Move the offset of a descriptor.
+///
+/// The meaning of `seek` on a directory is unspecified.
+///
+/// Note: This is similar to `lseek` in POSIX.
+seek: function(
+    /// The method to compute the new offset.
+    "from": seek_from,
+) -> (
+    /// The new offset of the descriptor, relative to the start of the file.
+    expected<filesize, errno>
+)
+```
+
+## `sync`
+```wai
+/// Synchronize the data and metadata of a file to disk.
+///
+/// Note: This is similar to `fsync` in POSIX.
+sync: function() -> expected<_, errno>
+```
+
+## `tell`
+```wai
+/// Return the current offset of a descriptor.
+///
+/// Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX.
+tell: function() -> (
+    /// The current offset of the descriptor, relative to the start of the file.
+    expected<filesize, errno>
+)
+```
+
+## `write`
+```wai
+/// Write to a descriptor.
+///
+/// Note: This is similar to `write` in POSIX.
+write: function(
+    /// Data to write
+    buf: pull-buffer<u8>,
+) -> expected<size, errno>
+```
+
+## `create_directory_at`
+```wai
+/// Create a directory.
+///
+/// Note: This is similar to `mkdirat` in POSIX.
+create_directory_at: function(
+    /// The relative path at which to create the directory.
+    path: string,
+) -> expected<_, errno>
+```
+
+## `stat_at`
+```wai
+/// Return the attributes of a file or directory.
+///
+/// Note: This is similar to `fstatat` in POSIX.
+///
+/// Note: This was called `fd_filestat_get` in earlier versions of WASI.
+stat_at: function(
+    /// Flags determining the method of how the path is resolved.
+    lookupflags: lookupflags,
+    /// The relative path of the file or directory to inspect.
+    path: string,
+) -> (
+    /// The buffer where the file's attributes are stored.
+    expected<stat, errno>
+)
+```
+
+## `set_times_at`
+```wai
+/// 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.
+set_times_at: function(
+    /// Flags determining the method of how the path is resolved.
+    lookupflags: lookupflags,
+    /// The relative path of the file or directory to operate on.
+    path: string,
+    /// The desired values of the data access timestamp.
+    atim: new_timestamp,
+    /// The desired values of the data modification timestamp.
+    mtim: new_timestamp,
+) -> expected<_, errno>
+```
+
+## `link_at`
+```wai
+/// Create a hard link.
+///
+/// Note: This is similar to `linkat` in POSIX.
+link_at: function(
+    /// Flags determining the method of how the path is resolved.
+    old_lookupflags: lookupflags,
+    /// The relative source path from which to link.
+    old_path: string,
+    /// The base directory for `new_path`.
+    new_descriptor: handle descriptor,
+    /// The relative destination path at which to create the hard link.
+    new_path: string,
+) -> expected<_, errno>
+```
+
+## `open_at`
+```wai
+/// Open a file or directory.
+///
+/// The returned descriptor is not guaranteed to be the lowest-numbered
+/// descriptor not currently open/ it is randomized to prevent applications
+/// from depending on making assumptions about indexes, since this is
+/// error-prone in multi-threaded contexts. The returned descriptor is
+/// guaranteed to be less than 2**31.
+///
+/// Note: This is similar to `openat` in POSIX.
+///
+/// TODO: Re-evaluate `direflags` here.
+/// TODO: Add a permissions mode.
+open_at: function(
+    /// Flags determining the method of how the path is resolved.
+    lookupflags: lookupflags,
+    /// The relative path of the object to open.
+    path: string,
+    /// The method by which to open the file.
+    oflags: oflags,
+    /// Flags to use for the resulting descriptor.
+    fdflags: "flags",
+    /// Permissions to use when creating a new file.
+    mode: mode
+) -> (
+    /// The descriptor of the file that has been opened.
+    expected<descriptor, errno>
+)
+```
+
+## `readlink_at`
+```wai
+/// Read the contents of a symbolic link.
+///
+/// Note: This is similar to `readlinkat` in POSIX.
+readlink_at: function(
+    /// The relative path of the symbolic link from which to read.
+    path: string,
+    /// The buffer to which to write the contents of the symbolic link.
+    buf: push-buffer<u8>,
+) -> (
+    /// The number of bytes placed in the buffer.
+    expected<size, errno>
+)
+```
+
+## `remove_directory_at`
+```wai
+/// Remove a directory.
+///
+/// Return `errno::notempty` if the directory is not empty.
+///
+/// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
+remove_directory_at: function(
+    /// The relative path to a directory to remove.
+    path: string,
+) -> expected<_, errno>
+```
+
+## `rename_at`
+```wai
+/// Rename a filesystem object.
+///
+/// Note: This is similar to `renameat` in POSIX.
+rename_at: function(
+    /// The relative source path of the file or directory to rename.
+    old_path: string,
+    /// The base directory for `new_path`.
+    new_descriptor: handle descriptor,
+    /// The relative destination path to which to rename the file or directory.
+    new_path: string,
+) -> expected<_, errno>
+```
+
+## `symlink_at`
+```wai
+/// Create a symbolic link.
+///
+/// Note: This is similar to `symlinkat` in POSIX.
+symlink_at: function(
+    /// The contents of the symbolic link.
+    old_path: string,
+    /// The relative destination path at which to create the symbolic link.
+    new_path: string,
+) -> expected<_, errno>
+```
+
+## `unlink_file_at`
+```wai
+/// Unlink a filesystem object that is not a directory.
+///
+/// Return `errno::isdir` if the path refers to a directory.
+/// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
+unlink_file_at: function(
+    /// The relative path to a file to unlink.
+    path: string,
+) -> expected<_, errno>
+```
+
+## `change_file_permissions_at`
+/// Change the permissions of a filesystem object that is not a directory.
+///
+/// Note that the ultimate meanings of these permissions is
+/// filesystem-specific.
+///
+/// Note: This is similar to `fchmodat` in POSIX.
+```wai
+change_file_permissions_at: function(
+    /// Flags determining the method of how the path is resolved.
+    lookupflags: lookupflags,
+    /// The relative path to operate on.
+    path: string,
+    /// The new permissions for the filesystem object.
+    mode: mode,
+) -> expected<_, errno>
+```
+
+## `change_dir_permissions_at`
+/// Change the permissions of a directory.
+///
+/// Note that the ultimate meanings of these permissions is
+/// filesystem-specific.
+///
+/// Unlike in POSIX, the `executable` flag is not reinterpreted as a "search"
+/// flag. `read` on a directory implies readability and searchability, and
+/// `execute` is not valid for directories.
+///
+/// Note: This is similar to `fchmodat` in POSIX.
+```wai
+change_directory_permissions_at: function(
+    /// Flags determining the method of how the path is resolved.
+    lookupflags: lookupflags,
+    /// The relative path to operate on.
+    path: string,
+    /// The new permissions for the directory.
+    mode: mode,
+) -> expected<_, errno>
+```
+
+```wai
+}
+```