From ebe56efa6483ea26024cc671cfe204208667b2bb Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 11 Sep 2019 11:54:13 -0700 Subject: [PATCH 1/2] Create a structure for phased development. This PR takes the `witx` concept from #74 and creates a directory structure around it for enabling phased development of new APIs and changes to existing APIs. See the README.md changes for details. --- README.md | 2 + phases/README.md | 53 + .../ephemeral/docs/wasi_ephemeral_preview.md | 16 +- .../ephemeral/witx}/typenames.witx | 2 +- .../witx/wasi_ephemeral_preview.witx | 526 ++++ phases/old/docs/wasi_unstable_preview0.md | 2319 +++++++++++++++++ phases/old/witx/typenames.witx | 752 ++++++ .../old/witx}/wasi_unstable.witx | 6 +- .../unstable/docs/wasi_unstable_preview0.md | 2319 +++++++++++++++++ phases/unstable/witx/typenames.witx | 752 ++++++ .../unstable/witx/wasi_unstable_preview0.witx | 526 ++++ 11 files changed, 7265 insertions(+), 8 deletions(-) create mode 100644 phases/README.md rename design/WASI-core.md => phases/ephemeral/docs/wasi_ephemeral_preview.md (99%) rename {design/wasi_unstable => phases/ephemeral/witx}/typenames.witx (99%) create mode 100644 phases/ephemeral/witx/wasi_ephemeral_preview.witx create mode 100644 phases/old/docs/wasi_unstable_preview0.md create mode 100644 phases/old/witx/typenames.witx rename {design/wasi_unstable => phases/old/witx}/wasi_unstable.witx (98%) create mode 100644 phases/unstable/docs/wasi_unstable_preview0.md create mode 100644 phases/unstable/witx/typenames.witx create mode 100644 phases/unstable/witx/wasi_unstable_preview0.witx diff --git a/README.md b/README.md index 7fc42122..31bb340e 100644 --- a/README.md +++ b/README.md @@ -22,3 +22,5 @@ discussions. Schedules and agendas for video conference and in-person meetings are posted [here](meetings/README.md). + +API specification proposals are [here](phases/README.md). diff --git a/phases/README.md b/phases/README.md new file mode 100644 index 00000000..00d49afe --- /dev/null +++ b/phases/README.md @@ -0,0 +1,53 @@ +# WASI development process + +## WASI uses a 3-phase process: + +- [`ephemeral`](ephemeral): The development staging area. New API + proposals API-changing fixes to existing APIs should be submitted + as Pull Requests making changes to this directory. This directory + provides no API stability or versioning. APIs in this directory use + API module names starting with `wasi_ephemeral_`. + +- [`unstable`](unstable): Usable APIs. APIs in `ephemeral` will be + occasionally snapshotted and promoted into `unstable`, with approval + from the Subgroup, considering the overall suitability of the APIs + themselves, their documentation, test coverage, and availability of + polyfills when appropriate. Once merged, the API modules will be + considered stable, though they may be superseded by newer versions. + Proposals to promote specific APIs should be submitted as Pull Requests + that: + - Move any superseded files out of `unstable` into `old`. + - Optionally add polyfills for superseded APIs using `unstable` APIs. + - Move all files supporting the APIs out of `ephemeral into `unstable`. + - Rename the API modules from `wasi_ephemeral_` to `wasi_unstable_` + and append a version number. + + Pull Requests may also add additional tests, documentation, or + polyfills for existing `unstable` APIs. + +- [`old`](old): When APIs in `current` spec are replaced by new + versions, the old API modules are moved to the `old` directory. When + possible, `old` APIs may be accompanied by polyfill modules which + implement their API in terms of newer versions of the API. + +## Rationale + +### Relationship to the CG's phases + +When WASI becomes more mature, such that we have an established base +and we're adding incremental functionality to it, we may want to adopt +a process like [the CG's phases]. However, right now, everything in +WASI is undergoing changes, so we have a greater need to iterate with +flexibility. + +### Relationship to standards + +WASI should eventually become a standard at the level of WebAssembly +itself. Right now, it needs a lot of work before it's ready. The +`unstable` tree is meant to serve a practical purpose for people who +want to work with APIs today, with the understanding that everything +is still evolving. It's not meant as a replacement for proper +standardization, which will happen once the overall API is more +mature. + +[the CG's phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md diff --git a/design/WASI-core.md b/phases/ephemeral/docs/wasi_ephemeral_preview.md similarity index 99% rename from design/WASI-core.md rename to phases/ephemeral/docs/wasi_ephemeral_preview.md index c4b256ad..9db4a382 100644 --- a/design/WASI-core.md +++ b/phases/ephemeral/docs/wasi_ephemeral_preview.md @@ -34,13 +34,12 @@ This file is automatically generated. Do not edit. Source: https://github.com/NuxiNL/cloudabi --> -# WASI Core API +# The WASI Preview API -This is the API-level documentation for WASI Core. The function names +This is the API-level documentation for WASI Preview. The function names are prefixed with "\_\_wasi\_" to reflect how they are spelled in flat-namespace contexts, however at the wasm module level, they are -unprefixed, because they're inside a module namespace (currently -"wasi\_unstable"). +unprefixed, because they're inside a module namespace. Functions that start with `__wasi_fd_` operate on file descriptors, while functions that start with `__wasi_path_` operate on filesystem @@ -48,16 +47,21 @@ paths, which are relative to directory file descriptors. Much inspiration and content here is derived from [CloudABI] and [POSIX], though there are also several differences from CloudABI and POSIX. For -example, WASI Core has no concept of processes in the traditional Unix +example, WASI Preview has no concept of processes in the traditional Unix sense. While wasm linear memories have some of the aspects of processes, and it's possible to *emulate* the full semantics of processes on top of them, this can sometimes be unnatural and inefficient. The goal for -WASI Core is to be a WebAssembly-native API that exposes APIs that fit +WASI Preview is to be a WebAssembly-native API that exposes APIs that fit well into the underlying WebAssembly platform, rather than to directly emulate other platforms. This is also a work in progress, and the API here is still evolving. +Historical note: this API was originally named "WASI Core", and used the +API module name "wasi\_unstable". We've since sought to deemphasize the +"Core" name, as the goal is to split this API up into independent +modules so that embedders need not implement all of it. + [CloudABI]: https://github.com/NuxiNL/cloudabi [POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/ diff --git a/design/wasi_unstable/typenames.witx b/phases/ephemeral/witx/typenames.witx similarity index 99% rename from design/wasi_unstable/typenames.witx rename to phases/ephemeral/witx/typenames.witx index 046ed0bf..e04a188d 100644 --- a/design/wasi_unstable/typenames.witx +++ b/phases/ephemeral/witx/typenames.witx @@ -1,4 +1,4 @@ -;; Type names used by the wasi_unstable module type. +;; Type names used by low-level WASI interfaces. ;; ;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). ;; diff --git a/phases/ephemeral/witx/wasi_ephemeral_preview.witx b/phases/ephemeral/witx/wasi_ephemeral_preview.witx new file mode 100644 index 00000000..4f31fe51 --- /dev/null +++ b/phases/ephemeral/witx/wasi_ephemeral_preview.witx @@ -0,0 +1,526 @@ +;; WASI Preview. This is an evolution of the API that WASI initially +;; launched with. +;; +;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). +;; +;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md) +;; for an explanation of what that means. + +(use "typenames.witx") + +(module $wasi_ephemeral_preview + ;; Linear memory to be accessed by WASI functions that need it. + (import "memory" (memory)) + + ;; Read command-line argument data. + ;; The size of the array should match that returned by `wasi_args_sizes_get()` + (@interface func (export "args_get") + (param $argv (@witx pointer (@witx pointer u8))) + (param $argv_buf (@witx pointer u8)) + (result $error $errno_t) + ) + ;; Return command-line argument data sizes. + (@interface func (export "args_sizes_get") + (result $error $errno_t) + ;; The number of arguments. + (result $argc $size_t) + ;; The size of the argument string data. + (result $argv_buf_size $size_t) + ) + + ;; Read environment variable data. + ;; The sizes of the buffers should match that returned by `environ.sizes_get()`. + (@interface func (export "environ_get") + (param $environ (@witx pointer (@witx pointer u8))) + (param $environ_buf (@witx pointer u8)) + (result $error $errno_t) + ) + ;; Return command-line argument data sizes. + (@interface func (export "environ_sizes_get") + ;; The number of arguments. + (result $argc $size_t) + ;; The size of the argument string data. + (result $argv_buf_size $size_t) + ) + + ;; Return the resolution of a clock. + ;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` + ;; Note: This is similar to `clock_getres` in POSIX. + (@interface func (export "clock_res_get") + (result $error $errno_t) + ;; The clock for which to return the resolution. + (param $clock_id $clockid_t) + ;; The resolution of the clock. + (result $resolution $timestamp_t) + ) + ;; Return the time value of a clock. + ;; Note: This is similar to `clock_gettime` in POSIX. + (@interface func (export "clock_time_get") + ;; The clock for which to return the time. + (param $clock_id $clockid_t) + ;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. + (param $precision $timestamp_t) + (result $error $errno_t) + ;; The time value of the clock. + (result $time $timestamp_t) + ) + + ;; Provide file advisory information on a file descriptor. + ;; Note: This is similar to `posix_fadvise` in POSIX. + (@interface func (export "fd_advise") + (param $fd $fd_t) + (param $offset $filesize_t) ;; The offset within the file to which the advisory applies. + (param $len $filesize_t) ;; The length of the region to which the advisory applies. + (param $advice $advice_t) ;; The advice. + (result $error $errno_t) + ) + + ;; Force the allocation of space in a file. + ;; Note: This is similar to `posix_fallocate` in POSIX. + (@interface func (export "fd_allocate") + (param $fd $fd_t) + ;; The offset at which to start the allocation. + (param $offset $filesize_t) + ;; The length of the area that is allocated. + (param $len $filesize_t) + (result $error $errno_t) + ) + + ;; Close a file descriptor. + ;; Note: This is similar to `close` in POSIX. + (@interface func (export "fd_close") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Synchronize the data of a file to disk. + ;; Note: This is similar to `fdatasync` in POSIX. + (@interface func (export "fd_datasync") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Get the attributes of a file descriptor. + ;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. + (@interface func (export "fd_fdstat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the file descriptor's attributes are stored. + (result $stat $fdstat_t) + ) + + ;; Adjust the flags associated with a file descriptor. + ;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + (@interface func (export "fd_fdstat_set_flags") + (param $fd $fd_t) + ;; The desired values of the file descriptor flags. + (param $flags $fdflags_t) + (result $error $errno_t) + ) + + ;; Adjust the rights associated with a file descriptor. + ;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights + (@interface func (export "fd_fdstat_set_rights") + (param $fd $fd_t) + ;; The desired rights of the file descriptor. + (param $fs_rights_base $rights_t) + (param $fs_rights_inheriting $rights_t) + (result $error $errno_t) + ) + + ;; Return the attributes of an open file. + (@interface func (export "fd_filestat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the file's attributes are stored. + (result $fs_rights_base $rights_t) + ) + + ;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. + ;; Note: This is similar to `ftruncate` in POSIX. + (@interface func (export "fd_filestat_set_size") + (param $fd $fd_t) + ;; The desired file size. + (param $st_size $filesize_t) + (result $error $errno_t) + ) + + ;; Adjust the timestamps of an open file or directory. + ;; Note: This is similar to `futimens` in POSIX. + (@interface func (export "fd_filestat_set_times") + (param $fd $fd_t) + ;; The desired values of the data access timestamp. + (param $st_atim $timestamp_t) + ;; The desired values of the data modification timestamp. + (param $st_mtim $timestamp_t) + ;; A bitmask indicating which timestamps to adjust. + (param $fst_flags $fstflags_t) + (result $error $errno_t) + ) + + ;; Read from a file descriptor, without using and updating the file descriptor's offset. + ;; Note: This is similar to `preadv` in POSIX. + (@interface func (export "fd_pread") + (param $fd $fd_t) + ;; List of scatter/gather vectors in which to store data. + (param $iovs $iovec_t_array) + ;; The offset within the file at which to read. + (param $offset $filesize_t) + (result $error $errno_t) + ;; The number of bytes read. + (result $nread $size_t) + ) + + ;; Return a description of the given preopened file descriptor. + (@interface func (export "fd_prestat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the description is stored. + (result $buf $prestat_t) + ) + + ;; Return a description of the given preopened file descriptor. + (@interface func (export "fd_prestat_dir_name") + (param $fd $fd_t) + ;; A buffer into which to write the preopened directory name. + (param $path (@witx pointer u8)) + (param $path_len $size_t) + (result $error $errno_t) + ) + + ;; Write to a file descriptor, without using and updating the file descriptor's offset. + ;; Note: This is similar to `pwritev` in POSIX. + (@interface func (export "fd_pwrite") + (param $fd $fd_t) + ;; List of scatter/gather vectors from which to retrieve data. + (param $iovs $ciovec_t_array) + ;; The offset within the file at which to write. + (param $offset $filesize_t) + (result $error $errno_t) + ;; The number of bytes written. + (result $nwritten $size_t) + ) + + ;; Read from a file descriptor. + ;; Note: This is similar to `readv` in POSIX. + (@interface func (export "fd_read") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to store data. + (param $iovs $iovec_t_array) + (result $error $errno_t) + ;; The number of bytes read. + (result $nread $size_t) + ) + + ;; 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_t object, + ;; followed by dirent_t::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. + (@interface func (export "fd_readdir") + (param $fd $fd_t) + ;; The buffer where directory entries are stored + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + ;; The location within the directory to start reading + (param $cookie $dircookie_t) + (result $error $errno_t) + ;; 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. + (result $bufused $size_t) + ) + + ;; Atomically replace a file descriptor by renumbering another file descriptor. + ;; + ;; Due to the strong focus on thread safety, this environment does not provide + ;; a mechanism to duplicate or renumber a file descriptor to an arbitrary + ;; number, like `dup2()`. This would be prone to race conditions, as an actual + ;; file descriptor with the same number could be allocated by a different + ;; thread at the same time. + ;; + ;; This function provides a way to atomically renumber file descriptors, which + ;; would disappear if `dup2()` were to be removed entirely. + (@interface func (export "fd_renumber") + (param $fd $fd_t) + ;; The file descriptor to overwrite. + (param $to $fd_t) + (result $error $errno_t) + ) + + ;; Move the offset of a file descriptor. + ;; Note: This is similar to `lseek` in POSIX. + (@interface func (export "fd_seek") + (param $fd $fd_t) + ;; The number of bytes to move. + (param $offset $filedelta_t) + ;; The base from which the offset is relative. + (param $whence $whence_t) + (result $error $errno_t) + ;; The new offset of the file descriptor, relative to the start of the file. + (result $newoffset $filesize_t) + ) + + ;; Synchronize the data and metadata of a file to disk. + ;; Note: This is similar to `fsync` in POSIX. + (@interface func (export "fd_sync") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Return the current offset of a file descriptor. + ;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + (@interface func (export "fd_tell") + (param $fd $fd_t) + (result $error $errno_t) + ;; The current offset of the file descriptor, relative to the start of the file. + (result $offset $filesize_t) + ) + + ;; Write to a file descriptor. + ;; Note: This is similar to `writev` in POSIX. + (@interface func (export "fd_write") + (param $fd $fd_t) + ;; List of scatter/gather vectors from which to retrieve data. + (param $iovs $ciovec_t_array) + (result $error $errno_t) + ;; The number of bytes written. + (result $nwritten $size_t) + ) + + ;; Create a directory. + ;; Note: This is similar to `mkdirat` in POSIX. + (@interface func (export "path_create_directory") + (param $fd $fd_t) + ;; The path at which to create the directory. + (param $path string) + (result $error $errno_t) + ) + + ;; Return the attributes of a file or directory. + ;; Note: This is similar to `stat` in POSIX. + (@interface func (export "path_filestat_get") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $flags $lookupflags_t) + ;; The path of the file or directory to inspect. + (param $path string) + (result $error $errno_t) + ;; The buffer where the file's attributes are stored. + (result $buf $filestat_t) + ) + + ;; Adjust the timestamps of a file or directory. + ;; Note: This is similar to `utimensat` in POSIX. + (@interface func (export "path_filestat_set_times") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $flags $lookupflags_t) + ;; The path of the file or directory to operate on. + (param $path string) + ;; The desired values of the data access timestamp. + (param $st_atim $timestamp_t) + ;; The desired values of the data modification timestamp. + (param $st_mtim $timestamp_t) + ;; A bitmask indicating which timestamps to adjust. + (param $fst_flags $fstflags_t) + (result $error $errno_t) + ) + + ;; Create a hard link. + ;; Note: This is similar to `linkat` in POSIX. + (@interface func (export "path_link") + (param $old_fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $old_flags $lookupflags_t) + ;; The source path from which to link. + (param $old_path string) + ;; The working directory at which the resolution of the new path starts. + (param $new_fd $fd_t) + ;; The destination path at which to create the hard link. + (param $new_path string) + (result $error $errno_t) + ) + + ;; Open a file or directory. + ;; + ;; The returned file descriptor is not guaranteed to be the lowest-numbered + ;; file 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 file descriptor is + ;; guaranteed to be less than 2**31. + ;; + ;; Note: This is similar to `openat` in POSIX. + (@interface func (export "path_open") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $dirflags $lookupflags_t) + ;; The relative path of the file or directory to open, relative to the + ;; `dirfd` directory. + (param $path string) + ;; The method by which to open the file. + (param $o_flags $oflags_t) + ;; The initial rights of the newly created file descriptor. The + ;; implementation is allowed to return a file descriptor with fewer rights + ;; than specified, if and only if those rights do not apply to the type of + ;; file being opened. + ;; + ;; The base rights are rights that will apply to operations using the file + ;; descriptor itself, while the inheriting rights are rights that apply to + ;; file descriptors derived from it. + (param $fs_rights_base $rights_t) + (param $fs_rights_inherting $rights_t) + (result $error $errno_t) + ;; The file descriptor of the file that has been opened. + (result $opened_fd $fd_t) + ) + + ;; Read the contents of a symbolic link. + ;; Note: This is similar to `readlinkat` in POSIX. + (@interface func (export "path_readlink") + (param $fd $fd_t) + ;; The path of the symbolic link from which to read. + (param $path string) + ;; The buffer to which to write the contents of the symbolic link. + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + (result $error $errno_t) + ;; The number of bytes placed in the buffer. + (result $bufused $size_t) + ) + + ;; Remove a directory. + ;; Return `ENOTEMPTY` if the directory is not empty. + ;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + (@interface func (export "path_remove_directory") + (param $fd $fd_t) + ;; The path to a directory to remove. + (param $path string) + (result $error $errno_t) + ) + + ;; Rename a file or directory. + ;; Note: This is similar to `renameat` in POSIX. + (@interface func (export "path_rename") + (param $fd $fd_t) + ;; The source path of the file or directory to rename. + (param $old_path string) + ;; The working directory at which the resolution of the new path starts. + (param $new_fd $fd_t) + ;; The destination path to which to rename the file or directory. + (param $new_path string) + (result $error $errno_t) + ) + + ;; Create a symbolic link. + ;; Note: This is similar to `symlinkat` in POSIX. + (@interface func (export "path_symlink") + (param $fd $fd_t) + ;; The contents of the symbolic link. + (param $old_path string) + ;; The destination path at which to create the symbolic link. + (param $new_path string) + (result $error $errno_t) + ) + + + ;; Unlink a file. + ;; Return `EISDIR` if the path refers to a directory. + ;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + (@interface func (export "path_unlink_file") + (param $fd $fd_t) + ;; The path to a file to unlink. + (param $path string) + (result $error $errno_t) + ) + + ;; Concurrently poll for the occurrence of a set of events. + (@interface func (export "poll_oneoff") + ;; The events to which to subscribe. + (param $in (@witx const_pointer $subscription_t)) + ;; The events that have occurred. + (param $out (@witx pointer $event_t)) + ;; Both the number of subscriptions and events. + (param $nsubscriptions $size_t) + (result $error $errno_t) + ;; The number of events stored. + (result $nevents $size_t) + ) + + ;; Terminate the process normally. An exit code of 0 indicates successful + ;; termination of the program. The meanings of other values is dependent on + ;; the environment. + (@interface func (export "proc_exit") + ;; The exit code returned by the process. + (param $rval $exitcode_t) + ) + + ;; Send a signal to the process of the calling thread. + ;; Note: This is similar to `raise` in POSIX. + (@interface func (export "proc_raise") + ;; The signal condition to trigger. + (param $sig $signal_t) + (result $error $errno_t) + ) + + ;; Temporarily yield execution of the calling thread. + ;; Note: This is similar to `sched_yield` in POSIX. + (@interface func (export "proc_sched_yield") + (result $error $errno_t) + ) + + ;; Write high-quality random data into a buffer. + ;; This function blocks when the implementation is unable to immediately + ;; provide sufficient high-quality random data. + ;; This function may execute slowly, so when large mounts of random data are + ;; required, it's advisable to use this function to seed a pseudo-random + ;; number generator, rather than to provide the random data directly. + (@interface func (export "random_get") + ;; The buffer to fill with random data. + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + (result $error $errno_t) + ) + + ;; Receive a message from a socket. + ;; Note: This is similar to `recv` in POSIX, though it also supports reading + ;; the data into multiple buffers in the manner of `readv`. + (@interface func (export "sock_recv") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to store data. + (param $ri_data $iovec_t_array) + ;; Message flags. + (param $ri_flags $riflags_t) + (result $error $errno_t) + ;; Number of bytes stored in ri_data. + (result $ro_datalen $size_t) + ;; Message flags. + (result $ro_flags $roflags_t) + ) + + ;; Send a message on a socket. + ;; Note: This is similar to `send` in POSIX, though it also supports writing + ;; the data from multiple buffers in the manner of `writev`. + (@interface func (export "sock_send") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to retrieve data + (param $si_data $ciovec_t_array) + ;; Message flags. + (param $si_flags $siflags_t) + (result $error $errno_t) + ;; Number of bytes transmitted. + (result $so_datalen $size_t) + ) + + ;; Shut down socket send and receive channels. + ;; Note: This is similar to `shutdown` in POSIX. + (@interface func (export "sock_shutdown") + (param $fd $fd_t) + ;; Which channels on the socket to shut down. + (param $how $sdflags_t) + (result $error $errno_t) + ) +) diff --git a/phases/old/docs/wasi_unstable_preview0.md b/phases/old/docs/wasi_unstable_preview0.md new file mode 100644 index 00000000..9db4a382 --- /dev/null +++ b/phases/old/docs/wasi_unstable_preview0.md @@ -0,0 +1,2319 @@ + + +# The WASI Preview API + +This is the API-level documentation for WASI Preview. The function names +are prefixed with "\_\_wasi\_" to reflect how they are spelled in +flat-namespace contexts, however at the wasm module level, they are +unprefixed, because they're inside a module namespace. + +Functions that start with `__wasi_fd_` operate on file descriptors, +while functions that start with `__wasi_path_` operate on filesystem +paths, which are relative to directory file descriptors. + +Much inspiration and content here is derived from [CloudABI] and [POSIX], +though there are also several differences from CloudABI and POSIX. For +example, WASI Preview has no concept of processes in the traditional Unix +sense. While wasm linear memories have some of the aspects of processes, +and it's possible to *emulate* the full semantics of processes on top of +them, this can sometimes be unnatural and inefficient. The goal for +WASI Preview is to be a WebAssembly-native API that exposes APIs that fit +well into the underlying WebAssembly platform, rather than to directly +emulate other platforms. + +This is also a work in progress, and the API here is still evolving. + +Historical note: this API was originally named "WASI Core", and used the +API module name "wasi\_unstable". We've since sought to deemphasize the +"Core" name, as the goal is to split this API up into independent +modules so that embedders need not implement all of it. + +[CloudABI]: https://github.com/NuxiNL/cloudabi +[POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/ + +## System calls + +- [`__wasi_args_get()`](#args_get) +- [`__wasi_args_sizes_get()`](#args_sizes_get) +- [`__wasi_clock_res_get()`](#clock_res_get) +- [`__wasi_clock_time_get()`](#clock_time_get) +- [`__wasi_environ_get()`](#environ_get) +- [`__wasi_environ_sizes_get()`](#environ_sizes_get) +- [`__wasi_fd_advise()`](#fd_advise) +- [`__wasi_fd_allocate()`](#fd_allocate) +- [`__wasi_fd_close()`](#fd_close) +- [`__wasi_fd_datasync()`](#fd_datasync) +- [`__wasi_fd_fdstat_get()`](#fd_fdstat_get) +- [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags) +- [`__wasi_fd_fdstat_set_rights()`](#fd_fdstat_set_rights) +- [`__wasi_fd_filestat_get()`](#fd_filestat_get) +- [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size) +- [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times) +- [`__wasi_fd_pread()`](#fd_pread) +- [`__wasi_fd_prestat_get()`](#fd_prestat_get) +- [`__wasi_fd_prestat_dir_name()`](#fd_prestat_dir_name) +- [`__wasi_fd_pwrite()`](#fd_pwrite) +- [`__wasi_fd_read()`](#fd_read) +- [`__wasi_fd_readdir()`](#fd_readdir) +- [`__wasi_fd_renumber()`](#fd_renumber) +- [`__wasi_fd_seek()`](#fd_seek) +- [`__wasi_fd_sync()`](#fd_sync) +- [`__wasi_fd_tell()`](#fd_tell) +- [`__wasi_fd_write()`](#fd_write) +- [`__wasi_path_create_directory()`](#path_create_directory) +- [`__wasi_path_filestat_get()`](#path_filestat_get) +- [`__wasi_path_filestat_set_times()`](#path_filestat_set_times) +- [`__wasi_path_link()`](#path_link) +- [`__wasi_path_open()`](#path_open) +- [`__wasi_path_readlink()`](#path_readlink) +- [`__wasi_path_remove_directory()`](#path_remove_directory) +- [`__wasi_path_rename()`](#path_rename) +- [`__wasi_path_symlink()`](#path_symlink) +- [`__wasi_path_unlink_file()`](#path_unlink_file) +- [`__wasi_poll_oneoff()`](#poll_oneoff) +- [`__wasi_proc_exit()`](#proc_exit) +- [`__wasi_proc_raise()`](#proc_raise) +- [`__wasi_random_get()`](#random_get) +- [`__wasi_sched_yield()`](#sched_yield) +- [`__wasi_sock_recv()`](#sock_recv) +- [`__wasi_sock_send()`](#sock_send) +- [`__wasi_sock_shutdown()`](#sock_shutdown) + +### `__wasi_args_get()` + +Read command-line argument data. + +The sizes of the buffers should match that returned by [`__wasi_args_sizes_get()`](#args_sizes_get). + +Inputs: + +- char \*\*argv + + A pointer to a buffer to write the argument pointers. + +- char \*argv\_buf + + A pointer to a buffer to write the argument string data. + +### `__wasi_args_sizes_get()` + +Return command-line argument data sizes. + +Outputs: + +- size\_t \*argc + + The number of arguments. + +- size\_t \*argv\_buf\_size + + The size of the argument string data. + +### `__wasi_clock_res_get()` + +Return the resolution of a clock. + +Implementations are required to provide a non-zero value for supported clocks. +For unsupported clocks, return [`__WASI_EINVAL`](#errno.inval). + +Note: This is similar to `clock_getres` in POSIX. + +Inputs: + +- [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock for which to return the resolution. + +Outputs: + +- [\_\_wasi\_timestamp\_t](#timestamp) resolution + + The resolution of the clock. + +### `__wasi_clock_time_get()` + +Return the time value of a clock. + +Note: This is similar to `clock_gettime` in POSIX. + +Inputs: + +- [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock for which to return the time. + +- [\_\_wasi\_timestamp\_t](#timestamp) precision + + The maximum lag (exclusive) that the returned + time value may have, compared to its actual + value. + +Outputs: + +- [\_\_wasi\_timestamp\_t](#timestamp) time + + The time value of the clock. + +### `__wasi_environ_get()` + +Read environment variable data. + +The sizes of the buffers should match that returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get). + +Inputs: + +- char \*\*environ + + A pointer to a buffer to write the environment variable pointers. + +- char \*environ\_buf + + A pointer to a buffer to write the environment variable string data. + +### `__wasi_environ_sizes_get()` + +Return command-line argument data sizes. + +Outputs: + +- size\_t \*environ\_count + + The number of environment variables. + +- size\_t \*environ\_buf\_size + + The size of the environment variable string data. + +### `__wasi_fd_advise()` + +Provide file advisory information on a file descriptor. + +Note: This is similar to `posix_fadvise` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor for the file for which to provide file advisory information. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file to which the advisory applies. + +- [\_\_wasi\_filesize\_t](#filesize) len + + The length of the region to which the advisory applies. + +- [\_\_wasi\_advice\_t](#advice) advice + + The advice. + +### `__wasi_fd_allocate()` + +Force the allocation of space in a file. + +Note: This is similar to `posix_fallocate` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor for the file in which to allocate space. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset at which to start the allocation. + +- [\_\_wasi\_filesize\_t](#filesize) len + + The length of the area that is allocated. + +### `__wasi_fd_close()` + +Close a file descriptor. + +Note: This is similar to `close` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to close. + +### `__wasi_fd_datasync()` + +Synchronize the data of a file to disk. + +Note: This is similar to `fdatasync` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file to synchronize to disk. + +### `__wasi_fd_fdstat_get()` + +Get the attributes of a file descriptor. + +Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well +as additional fields. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +- [\_\_wasi\_fdstat\_t](#fdstat) \*buf + + The buffer where the file descriptor's attributes are stored. + +### `__wasi_fd_fdstat_set_flags()` + +Adjust the flags associated with a file descriptor. + +Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_fdflags\_t](#fdflags) flags + + The desired values of the file descriptor + flags. + +### `__wasi_fd_fdstat_set_rights()` + +Adjust the rights associated with a file descriptor. + +This can only be used to remove rights, and returns +[`__WASI_ENOTCAPABLE`](#errno.notcapable) if called in a way that would attempt +to add rights. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The desired rights of the file descriptor. + +### `__wasi_fd_filestat_get()` + +Return the attributes of an open file. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +- [\_\_wasi\_filestat\_t](#filestat) \*buf + + The buffer where the file's attributes are + stored. + +### `__wasi_fd_filestat_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 is similar to `ftruncate` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + A file descriptor for the file to adjust. + +- [\_\_wasi\_filesize\_t](#filesize) st\_size + + The desired file size. + +### `__wasi_fd_filestat_set_times()` + +Adjust the timestamps of an open file or directory. + +Note: This is similar to `futimens` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + The desired values of the data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + The desired values of the data modification timestamp. + +- [\_\_wasi\_fstflags\_t](#fstflags) fst\_flags + + A bitmask indicating which timestamps to adjust. + +### `__wasi_fd_pread()` + +Read from a file descriptor, without using and updating the +file descriptor's offset. + +Note: This is similar to `preadv` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor from which to read data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors in which to store data. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file at which to read. + +Outputs: + +- size\_t nread + + The number of bytes read. + +### `__wasi_fd_prestat_get()` + +Return a description of the given preopened file descriptor. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor about which to retrieve information. + +- [\_\_wasi\_prestat\_t](#prestat) \*buf + + The buffer where the description is stored. + +### `__wasi_fd_prestat_dir_name()` + +Return a description of the given preopened file descriptor. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor about which to retrieve information. + +- const char \*path and size\_t path\_len + + A buffer into which to write the preopened directory name. + +### `__wasi_fd_pwrite()` + +Write to a file descriptor, without using and updating the +file descriptor's offset. + +Note: This is similar to `pwritev` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to which to write data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors from which to retrieve data. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file at which to write. + +Outputs: + +- size\_t nwritten + + The number of bytes written. + +### `__wasi_fd_read()` + +Read from a file descriptor. + +Note: This is similar to `readv` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor from which to read data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors to which to store data. + +Outputs: + +- size\_t nread + + The number of bytes read. + +### `__wasi_fd_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 [`__wasi_dirent_t`](#dirent) object, followed by [`__wasi_dirent_t::d_namlen`](#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. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The directory from which to read the directory + entries. + +- void \*buf and size\_t buf\_len + + The buffer where directory entries are stored. + +- [\_\_wasi\_dircookie\_t](#dircookie) cookie + + The location within the directory to start + reading. + +Outputs: + +- size\_t bufused + + 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. + +### `__wasi_fd_renumber()` + +Atomically replace a file descriptor by renumbering another +file descriptor. + +Due to the strong focus on thread safety, this environment +does not provide a mechanism to duplicate or renumber a file +descriptor to an arbitrary number, like dup2(). This would be +prone to race conditions, as an actual file descriptor with the +same number could be allocated by a different thread at the same +time. + +This function provides a way to atomically renumber file +descriptors, which would disappear if dup2() were to be +removed entirely. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) from + + The file descriptor to renumber. + +- [\_\_wasi\_fd\_t](#fd) to + + The file descriptor to overwrite. + +### `__wasi_fd_seek()` + +Move the offset of a file descriptor. + +Note: This is similar to `lseek` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_filedelta\_t](#filedelta) offset + + The number of bytes to move. + +- [\_\_wasi\_whence\_t](#whence) whence + + The base from which the offset is relative. + +Outputs: + +- [\_\_wasi\_filesize\_t](#filesize) newoffset + + The new offset of the file descriptor, + relative to the start of the file. + +### `__wasi_fd_sync()` + +Synchronize the data and metadata of a file to disk. + +Note: This is similar to `fsync` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file containing the data + and metadata to synchronize to disk. + +### `__wasi_fd_tell()` + +Return the current offset of a file descriptor. + +Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +Outputs: + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The current offset of the file descriptor, relative to the start of the file. + +### `__wasi_fd_write()` + +Write to a file descriptor. + +Note: This is similar to `writev` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to which to write data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors from which to retrieve data. + +Outputs: + +- size\_t nwritten + + The number of bytes written. + +### `__wasi_path_create_directory()` + +Create a directory. + +Note: This is similar to `mkdirat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path at which to create the directory. + +### `__wasi_path_filestat_get()` + +Return the attributes of a file or directory. + +Note: This is similar to `stat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) flags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The path of the file or directory to inspect. + +- [\_\_wasi\_filestat\_t](#filestat) \*buf + + The buffer where the file's attributes are + stored. + +### `__wasi_path_filestat_set_times()` + +Adjust the timestamps of a file or directory. + +Note: This is similar to `utimensat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) flags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The path of the file or directory to operate on. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + The desired values of the data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + The desired values of the data modification timestamp. + +- [\_\_wasi\_fstflags\_t](#fstflags) fst\_flags + + A bitmask indicating which timestamps to adjust. + +### `__wasi_path_link()` + +Create a hard link. + +Note: This is similar to `linkat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) old\_fd + + The working directory at which the resolution of the old path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) old\_flags + + Flags determining the method of how the path is resolved. + +- const char \*old\_path and size\_t old\_path\_len + + The source path from which to link. + +- [\_\_wasi\_fd\_t](#fd) new\_fd + + The working directory at which the resolution of the new path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path at which to create the hard link. + +### `__wasi_path_open()` + +Open a file or directory. + +The returned file descriptor is not guaranteed to be the lowest-numbered +file 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 file +descriptor is guaranteed to be less than 231. + +Note: This is similar to `openat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) dirfd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) dirflags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The relative path of the file or directory to open, relative to + the [`dirfd`](#path_open.dirfd) directory. + +- [\_\_wasi\_oflags\_t](#oflags) o_flags + + The method by which to open the file. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The initial rights of the newly created file descriptor. The + implementation is allowed to return a file descriptor with fewer + rights than specified, if and only if those rights do not apply + to the type of file being opened. + + The *base* rights are rights that will apply to operations using + the file descriptor itself, while the *inheriting* rights are + rights that apply to file descriptors derived from it. + +- [\_\_wasi\_fdflags\_t](#fdflags) fs\_flags + + The initial flags of the file descriptor. + +Outputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file that has been + opened. + +### `__wasi_path_readlink()` + +Read the contents of a symbolic link. + +Note: This is similar to `readlinkat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path of the symbolic link from which to read. + +- char \*buf and size\_t buf\_len + + The buffer to which to write the contents of the symbolic link. + +Outputs: + +- size\_t bufused + + The number of bytes placed in the buffer. + +### `__wasi_path_remove_directory()` + +Remove a directory. + +Return [`__WASI_ENOTEMPTY`](#errno.notempty) if the directory is not empty. + +Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path to a directory to remove. + +### `__wasi_path_rename()` + +Rename a file or directory. + +Note: This is similar to `renameat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) old\_fd + + The working directory at which the resolution of the old path starts. + +- const char \*old\_path and size\_t old\_path\_len + + The source path of the file or directory to rename. + +- [\_\_wasi\_fd\_t](#fd) new\_fd + + The working directory at which the resolution of the new path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path to which to rename the file or directory. + +### `__wasi_path_symlink()` + +Create a symbolic link. + +Note: This is similar to `symlinkat` in POSIX. + +Inputs: + +- const char \*old\_path and size\_t old_path\_len + + The contents of the symbolic link. + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path at which to create the symbolic link. + +### `__wasi_path_unlink_file()` + +Unlink a file. + +Return [`__WASI_EISDIR`](#errno.isdir) if the path refers to a directory. + +Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path to a file to unlink. + +### `__wasi_poll_oneoff()` + +Concurrently poll for the occurrence of a set of events. + +Inputs: + +- const [\_\_wasi\_subscription\_t](#subscription) \*in + + The events to which to subscribe. + +- [\_\_wasi\_event\_t](#event) \*out + + The events that have occurred. + +- size\_t nsubscriptions + + Both the number of subscriptions and events. + +Outputs: + +- size\_t nevents + + The number of events stored. + +### `__wasi_proc_exit()` + +Terminate the process normally. An exit code of 0 indicates successful +termination of the program. The meanings of other values is dependent on +the environment. + +Note: This is similar to `_Exit` in POSIX. + +Inputs: + +- [\_\_wasi\_exitcode\_t](#exitcode) rval + + The exit code returned by the process. + +Does not return. + +### `__wasi_proc_raise()` + +Send a signal to the process of the calling thread. + +Note: This is similar to `raise` in POSIX. + +Inputs: + +- [\_\_wasi\_signal\_t](#signal) sig + + The signal condition to trigger. + +### `__wasi_random_get()` + +Write high-quality random data into a buffer. + +This function blocks when the implementation is unable to immediately +provide sufficient high-quality random data. + +This function may execute slowly, so when large mounts of random +data are required, it's advisable to use this function to seed a +pseudo-random number generator, rather than to provide the +random data directly. + +Inputs: + +- void \*buf and size\_t buf\_len + + The buffer to fill with random data. + +### `__wasi_sched_yield()` + +Temporarily yield execution of the calling thread. + +Note: This is similar to `sched_yield` in POSIX. + +### `__wasi_sock_recv()` + +Receive a message from a socket. + +Note: This is similar to `recv` in POSIX, though it also supports reading +the data into multiple buffers in the manner of `readv`. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to receive data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*ri\_data and size\_t ri\_data\_len + + List of scatter/gather vectors to which to store data. + +- [\_\_wasi\_riflags\_t](#riflags) ri\_flags + + Message flags. + +Outputs: + +- size\_t ro\_datalen + + Number of bytes stored in [`ri_data`](#sock_recv.ri_data). + +- [\_\_wasi\_roflags\_t](#roflags) ro\_flags + + Message flags. + +### `__wasi_sock_send()` + +Send a message on a socket. + +Note: This is similar to `send` in POSIX, though it also supports writing +the data from multiple buffers in the manner of `writev`. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to send data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*si\_data and size\_t si\_data\_len + + List of scatter/gather vectors to which to retrieve data + +- [\_\_wasi\_siflags\_t](#siflags) si\_flags + + Message flags. + +Outputs: + +- size\_t so\_datalen + + Number of bytes transmitted. + +### `__wasi_sock_shutdown()` + +Shut down socket send and receive channels. + +Note: This is similar to `shutdown` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to shutdown channels. + +- [\_\_wasi\_sdflags\_t](#sdflags) how + + Which channels on the socket to shut down. + +## Types + +### `__wasi_advice_t` (`uint8_t`) + +File or memory access pattern advisory information. + +Used by [`__wasi_fd_advise()`](#fd_advise). + +Possible values: + +- **`__WASI_ADVICE_DONTNEED`** + + The application expects that it will not access the + specified data in the near future. + +- **`__WASI_ADVICE_NOREUSE`** + + The application expects to access the specified data + once and then not reuse it thereafter. + +- **`__WASI_ADVICE_NORMAL`** + + The application has no advice to give on its behavior + with respect to the specified data. + +- **`__WASI_ADVICE_RANDOM`** + + The application expects to access the specified data + in a random order. + +- **`__WASI_ADVICE_SEQUENTIAL`** + + The application expects to access the specified data + sequentially from lower offsets to higher offsets. + +- **`__WASI_ADVICE_WILLNEED`** + + The application expects to access the specified data + in the near future. + +### `__wasi_ciovec_t` (`struct`) + +A region of memory for scatter/gather writes. + +Used by [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_write()`](#fd_write), and [`__wasi_sock_send()`](#sock_send). + +Members: + +- const void \*buf and size\_t buf\_len + + The address and length of the buffer to be written. + +### `__wasi_clockid_t` (`uint32_t`) + +Identifiers for clocks. + +Used by [`__wasi_subscription_t`](#subscription), [`__wasi_clock_res_get()`](#clock_res_get), and [`__wasi_clock_time_get()`](#clock_time_get). + +Possible values: + +- **`__WASI_CLOCK_MONOTONIC`** + + The store-wide monotonic clock, which is defined as a + clock measuring real time, whose value cannot be + adjusted and which cannot have negative clock jumps. + + The epoch of this clock is undefined. The absolute + time value of this clock therefore has no meaning. + +- **`__WASI_CLOCK_PROCESS_CPUTIME_ID`** + + The CPU-time clock associated with the current + process. + +- **`__WASI_CLOCK_REALTIME`** + + The clock measuring real time. Time value + zero corresponds with 1970-01-01T00:00:00Z. + +- **`__WASI_CLOCK_THREAD_CPUTIME_ID`** + + The CPU-time clock associated with the current thread. + +### `__wasi_device_t` (`uint64_t`) + +Identifier for a device containing a file system. Can be used +in combination with [`__wasi_inode_t`](#inode) to uniquely identify a file or +directory in the filesystem. + +Used by [`__wasi_filestat_t`](#filestat). + +### `__wasi_dircookie_t` (`uint64_t`) + +A reference to the offset of a directory entry. + +Used by [`__wasi_dirent_t`](#dirent) and [`__wasi_fd_readdir()`](#fd_readdir). + +Special values: + +- **`__WASI_DIRCOOKIE_START`** + + Permanent reference to the first directory entry + within a directory. + +### `__wasi_dirent_t` (`struct`) + +A directory entry. + +Members: + +- [\_\_wasi\_dircookie\_t](#dircookie) d\_next + + The offset of the next directory entry stored in this + directory. + +- [\_\_wasi\_inode\_t](#inode) d\_ino + + The serial number of the file referred to by this + directory entry. + +- uint32\_t d\_namlen + + The length of the name of the directory entry. + +- [\_\_wasi\_filetype\_t](#filetype) d\_type + + The type of the file referred to by this directory + entry. + +### `__wasi_errno_t` (`uint16_t`) + +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. + +Used by [`__wasi_event_t`](#event). + +Possible values: + +- **`__WASI_ESUCCESS`** + + No error occurred. System call completed successfully. + +- **`__WASI_E2BIG`** + + Argument list too long. + +- **`__WASI_EACCES`** + + Permission denied. + +- **`__WASI_EADDRINUSE`** + + Address in use. + +- **`__WASI_EADDRNOTAVAIL`** + + Address not available. + +- **`__WASI_EAFNOSUPPORT`** + + Address family not supported. + +- **`__WASI_EAGAIN`** + + Resource unavailable, or operation would block. + +- **`__WASI_EALREADY`** + + Connection already in progress. + +- **`__WASI_EBADF`** + + Bad file descriptor. + +- **`__WASI_EBADMSG`** + + Bad message. + +- **`__WASI_EBUSY`** + + Device or resource busy. + +- **`__WASI_ECANCELED`** + + Operation canceled. + +- **`__WASI_ECHILD`** + + No child processes. + +- **`__WASI_ECONNABORTED`** + + Connection aborted. + +- **`__WASI_ECONNREFUSED`** + + Connection refused. + +- **`__WASI_ECONNRESET`** + + Connection reset. + +- **`__WASI_EDEADLK`** + + Resource deadlock would occur. + +- **`__WASI_EDESTADDRREQ`** + + Destination address required. + +- **`__WASI_EDOM`** + + Mathematics argument out of domain of function. + +- **`__WASI_EDQUOT`** + + Reserved. + +- **`__WASI_EEXIST`** + + File exists. + +- **`__WASI_EFAULT`** + + Bad address. + +- **`__WASI_EFBIG`** + + File too large. + +- **`__WASI_EHOSTUNREACH`** + + Host is unreachable. + +- **`__WASI_EIDRM`** + + Identifier removed. + +- **`__WASI_EILSEQ`** + + Illegal byte sequence. + +- **`__WASI_EINPROGRESS`** + + Operation in progress. + +- **`__WASI_EINTR`** + + Interrupted function. + +- **`__WASI_EINVAL`** + + Invalid argument. + +- **`__WASI_EIO`** + + I/O error. + +- **`__WASI_EISCONN`** + + Socket is connected. + +- **`__WASI_EISDIR`** + + Is a directory. + +- **`__WASI_ELOOP`** + + Too many levels of symbolic links. + +- **`__WASI_EMFILE`** + + File descriptor value too large. + +- **`__WASI_EMLINK`** + + Too many links. + +- **`__WASI_EMSGSIZE`** + + Message too large. + +- **`__WASI_EMULTIHOP`** + + Reserved. + +- **`__WASI_ENAMETOOLONG`** + + Filename too long. + +- **`__WASI_ENETDOWN`** + + Network is down. + +- **`__WASI_ENETRESET`** + + Connection aborted by network. + +- **`__WASI_ENETUNREACH`** + + Network unreachable. + +- **`__WASI_ENFILE`** + + Too many files open in system. + +- **`__WASI_ENOBUFS`** + + No buffer space available. + +- **`__WASI_ENODEV`** + + No such device. + +- **`__WASI_ENOENT`** + + No such file or directory. + +- **`__WASI_ENOEXEC`** + + Executable file format error. + +- **`__WASI_ENOLCK`** + + No locks available. + +- **`__WASI_ENOLINK`** + + Reserved. + +- **`__WASI_ENOMEM`** + + Not enough space. + +- **`__WASI_ENOMSG`** + + No message of the desired type. + +- **`__WASI_ENOPROTOOPT`** + + Protocol not available. + +- **`__WASI_ENOSPC`** + + No space left on device. + +- **`__WASI_ENOSYS`** + + Function not supported. + +- **`__WASI_ENOTCONN`** + + The socket is not connected. + +- **`__WASI_ENOTDIR`** + + Not a directory or a symbolic link to a directory. + +- **`__WASI_ENOTEMPTY`** + + Directory not empty. + +- **`__WASI_ENOTRECOVERABLE`** + + State not recoverable. + +- **`__WASI_ENOTSOCK`** + + Not a socket. + +- **`__WASI_ENOTSUP`** + + Not supported, or operation not supported on socket. + +- **`__WASI_ENOTTY`** + + Inappropriate I/O control operation. + +- **`__WASI_ENXIO`** + + No such device or address. + +- **`__WASI_EOVERFLOW`** + + Value too large to be stored in data type. + +- **`__WASI_EOWNERDEAD`** + + Previous owner died. + +- **`__WASI_EPERM`** + + Operation not permitted. + +- **`__WASI_EPIPE`** + + Broken pipe. + +- **`__WASI_EPROTO`** + + Protocol error. + +- **`__WASI_EPROTONOSUPPORT`** + + Protocol not supported. + +- **`__WASI_EPROTOTYPE`** + + Protocol wrong type for socket. + +- **`__WASI_ERANGE`** + + Result too large. + +- **`__WASI_EROFS`** + + Read-only file system. + +- **`__WASI_ESPIPE`** + + Invalid seek. + +- **`__WASI_ESRCH`** + + No such process. + +- **`__WASI_ESTALE`** + + Reserved. + +- **`__WASI_ETIMEDOUT`** + + Connection timed out. + +- **`__WASI_ETXTBSY`** + + Text file busy. + +- **`__WASI_EXDEV`** + + Cross-device link. + +- **`__WASI_ENOTCAPABLE`** + + Extension: Capabilities insufficient. + +### `__wasi_event_t` (`struct`) + +An event that occurred. + +Used by [`__wasi_poll_oneoff()`](#poll_oneoff). + +Members: + +- [\_\_wasi\_userdata\_t](#userdata) userdata + + User-provided value that got attached to + [`__wasi_subscription_t::userdata`](#subscription.userdata). + +- [\_\_wasi\_errno\_t](#errno) error + + If non-zero, an error that occurred while processing + the subscription request. + +- [\_\_wasi\_eventtype\_t](#eventtype) type + + The type of the event that occurred. + +- When `type` is [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write): + + - **`u.fd_readwrite`** + + - [\_\_wasi\_filesize\_t](#filesize) nbytes + + The number of bytes available for reading or writing. + + - [\_\_wasi\_eventrwflags\_t](#eventrwflags) flags + + The state of the file descriptor. + +### `__wasi_eventrwflags_t` (`uint16_t` bitfield) + +The state of the file descriptor subscribed to with +[`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write). + +Used by [`__wasi_event_t`](#event). + +Possible values: + +- **`__WASI_EVENT_FD_READWRITE_HANGUP`** + + The peer of this socket has closed or disconnected. + +### `__wasi_eventtype_t` (`uint8_t`) + +Type of a subscription to an event or its occurrence. + +Used by [`__wasi_event_t`](#event) and [`__wasi_subscription_t`](#subscription). + +Possible values: + +- **`__WASI_EVENTTYPE_CLOCK`** + + The time value of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id) + has reached timestamp [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout). + +- **`__WASI_EVENTTYPE_FD_READ`** + + File descriptor [`__wasi_subscription_t::u.fd_readwrite.fd`](#subscription.u.fd_readwrite.fd) has + data available for reading. This event always triggers + for regular files. + +- **`__WASI_EVENTTYPE_FD_WRITE`** + + File descriptor [`__wasi_subscription_t::u.fd_readwrite.fd`](#subscription.u.fd_readwrite.fd) has + capacity available for writing. This event always + triggers for regular files. + +### `__wasi_exitcode_t` (`uint32_t`) + +Exit code generated by a process when exiting. + +Used by [`__wasi_proc_exit()`](#proc_exit). + +### `__wasi_fd_t` (`uint32_t`) + +A file descriptor number. + +Used by many functions in this API. + +As in POSIX, three file descriptor numbers are provided to instances +on startup -- 0, 1, and 2, (a.k.a. `STDIN_FILENO`, `STDOUT_FILENO`, +and `STDERR_FILENO`). + +Other than these, WASI implementations are not required to allocate +new file descriptors in ascending order. + +### `__wasi_fdflags_t` (`uint16_t` bitfield) + +File descriptor flags. + +Used by [`__wasi_fdstat_t`](#fdstat), [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_FDFLAG_APPEND`** + + Append mode: Data written to the file is always + appended to the file's end. + +- **`__WASI_FDFLAG_DSYNC`** + + Write according to synchronized I/O data integrity + completion. Only the data stored in the file is + synchronized. + +- **`__WASI_FDFLAG_NONBLOCK`** + + Non-blocking mode. + +- **`__WASI_FDFLAG_RSYNC`** + + Synchronized read I/O operations. + +- **`__WASI_FDFLAG_SYNC`** + + 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. + +### `__wasi_fdstat_t` (`struct`) + +File descriptor attributes. + +Used by [`__wasi_fd_fdstat_get()`](#fd_fdstat_get). + +Members: + +- [\_\_wasi\_filetype\_t](#filetype) fs\_filetype + + File type. + +- [\_\_wasi\_fdflags\_t](#fdflags) fs\_flags + + File descriptor flags. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base + + Rights that apply to this file descriptor. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + Maximum set of rights that may be installed on new + file descriptors that are created through this file + descriptor, e.g., through [`__wasi_path_open()`](#path_open). + +### `__wasi_filedelta_t` (`int64_t`) + +Relative offset within a file. + +Used by [`__wasi_fd_seek()`](#fd_seek). + +### `__wasi_filesize_t` (`uint64_t`) + +Non-negative file size or length of a region within a file. + +Used by [`__wasi_event_t`](#event), [`__wasi_filestat_t`](#filestat), [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_seek()`](#fd_seek), [`__wasi_path_tell()`](#path_tell), [`__wasi_fd_advise()`](#fd_advise), [`__wasi_fd_allocate()`](#fd_allocate), and [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size). + +### `__wasi_filestat_t` (`struct`) + +File attributes. + +Used by [`__wasi_fd_filestat_get()`](#fd_filestat_get) and [`__wasi_path_filestat_get()`](#path_filestat_get). + +Members: + +- [\_\_wasi\_device\_t](#device) st\_dev + + Device ID of device containing the file. + +- [\_\_wasi\_inode\_t](#inode) st\_ino + + File serial number. + +- [\_\_wasi\_filetype\_t](#filetype) st\_filetype + + File type. + +- [\_\_wasi\_linkcount\_t](#linkcount) st\_nlink + + Number of hard links to the file. + +- [\_\_wasi\_filesize\_t](#filesize) st\_size + + For regular files, the file size in bytes. For + symbolic links, the length in bytes of the pathname + contained in the symbolic link. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + Last data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + Last data modification timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_ctim + + Last file status change timestamp. + +### `__wasi_filetype_t` (`uint8_t`) + +The type of a file descriptor or file. + +Used by [`__wasi_dirent_t`](#dirent), [`__wasi_fdstat_t`](#fdstat), and [`__wasi_filestat_t`](#filestat). + +Possible values: + +- **`__WASI_FILETYPE_UNKNOWN`** + + The type of the file descriptor or file is unknown or + is different from any of the other types specified. + +- **`__WASI_FILETYPE_BLOCK_DEVICE`** + + The file descriptor or file refers to a block device + inode. + +- **`__WASI_FILETYPE_CHARACTER_DEVICE`** + + The file descriptor or file refers to a character + device inode. + +- **`__WASI_FILETYPE_DIRECTORY`** + + The file descriptor or file refers to a directory + inode. + +- **`__WASI_FILETYPE_REGULAR_FILE`** + + The file descriptor or file refers to a regular file + inode. + +- **`__WASI_FILETYPE_SOCKET_DGRAM`** + + The file descriptor or file refers to a datagram + socket. + +- **`__WASI_FILETYPE_SOCKET_STREAM`** + + The file descriptor or file refers to a byte-stream + socket. + +- **`__WASI_FILETYPE_SYMBOLIC_LINK`** + + The file refers to a symbolic link inode. + +### `__wasi_fstflags_t` (`uint16_t` bitfield) + +Which file time attributes to adjust. + +Used by [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times) and [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +Possible values: + +- **`__WASI_FILESTAT_SET_ATIM`** + + Adjust the last data access timestamp to the value + stored in [`__wasi_filestat_t::st_atim`](#filestat.st_atim). + +- **`__WASI_FILESTAT_SET_ATIM_NOW`** + + Adjust the last data access timestamp to the time + of clock [`__WASI_CLOCK_REALTIME`](#clockid.realtime). + +- **`__WASI_FILESTAT_SET_MTIM`** + + Adjust the last data modification timestamp to the + value stored in [`__wasi_filestat_t::st_mtim`](#filestat.st_mtim). + +- **`__WASI_FILESTAT_SET_MTIM_NOW`** + + Adjust the last data modification timestamp to the + time of clock [`__WASI_CLOCK_REALTIME`](#clockid.realtime). + +### `__wasi_inode_t` (`uint64_t`) + +File serial number that is unique within its file system. + +Used by [`__wasi_dirent_t`](#dirent) and [`__wasi_filestat_t`](#filestat). + +### `__wasi_iovec_t` (`struct`) + +A region of memory for scatter/gather reads. + +Used by [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_read()`](#fd_read), and [`__wasi_sock_recv()`](#sock_recv). + +Members: + +- void \*buf and size\_t buf\_len + + The address and length of the buffer to be filled. + +### `__wasi_linkcount_t` (`uint32_t`) + +Number of hard links to an inode. + +Used by [`__wasi_filestat_t`](#filestat). + +### `__wasi_lookupflags_t` (`uint32_t` bitfield) + +Flags determining the method of how paths are resolved. + +Used by [`__wasi_path_filestat_get()`](#path_filestat_get), [`__wasi_path_filestat_set_times()`](#path_filestat_set_times), [`__wasi_path_link()`](#path_link), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_LOOKUP_SYMLINK_FOLLOW`** + + As long as the resolved path corresponds to a symbolic + link, it is expanded. + +### `__wasi_oflags_t` (`uint16_t` bitfield) + +Open flags used by [`__wasi_path_open()`](#path_open). + +Used by [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_O_CREAT`** + + Create file if it does not exist. + +- **`__WASI_O_DIRECTORY`** + + Fail if not a directory. + +- **`__WASI_O_EXCL`** + + Fail if file already exists. + +- **`__WASI_O_TRUNC`** + + Truncate file to size 0. + +### `__wasi_riflags_t` (`uint16_t` bitfield) + +Flags provided to [`__wasi_sock_recv()`](#sock_recv). + +Used by [`__wasi_sock_recv()`](#sock_recv). + +Possible values: + +- **`__WASI_SOCK_RECV_PEEK`** + + Returns the message without removing it from the + socket's receive queue. + +- **`__WASI_SOCK_RECV_WAITALL`** + + On byte-stream sockets, block until the full amount + of data can be returned. + +### `__wasi_rights_t` (`uint64_t` bitfield) + +File descriptor rights, determining which actions may be +performed. + +Used by [`__wasi_fdstat_t`](#fdstat), [`__wasi_fd_fdstat_set_rights()`](#fd_fdstat_set_rights), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_RIGHT_FD_DATASYNC`** + + The right to invoke [`__wasi_fd_datasync()`](#fd_datasync). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_FDFLAG_DSYNC`](#fdflags.dsync). + +- **`__WASI_RIGHT_FD_READ`** + + The right to invoke [`__wasi_fd_read()`](#fd_read) and [`__wasi_sock_recv()`](#sock_recv). + + If [`__WASI_RIGHT_FD_SEEK`](#rights.fd_seek) is set, includes the right to invoke + [`__wasi_fd_pread()`](#fd_pread). + +- **`__WASI_RIGHT_FD_SEEK`** + + The right to invoke [`__wasi_fd_seek()`](#fd_seek). This flag implies + [`__WASI_RIGHT_FD_TELL`](#rights.fd_tell). + +- **`__WASI_RIGHT_FD_FDSTAT_SET_FLAGS`** + + The right to invoke [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags). + +- **`__WASI_RIGHT_FD_SYNC`** + + The right to invoke [`__wasi_fd_sync()`](#fd_sync). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_FDFLAG_RSYNC`](#fdflags.rsync) and + [`__WASI_FDFLAG_DSYNC`](#fdflags.dsync). + +- **`__WASI_RIGHT_FD_TELL`** + + The right to invoke [`__wasi_fd_seek()`](#fd_seek) in such a way that the + file offset remains unaltered (i.e., [`__WASI_WHENCE_CUR`](#whence.cur) with + offset zero), or to invoke [`__wasi_fd_tell()`](#fd_tell). + +- **`__WASI_RIGHT_FD_WRITE`** + + The right to invoke [`__wasi_fd_write()`](#fd_write) and [`__wasi_sock_send()`](#sock_send). + + If [`__WASI_RIGHT_FD_SEEK`](#rights.fd_seek) is set, includes the right to + invoke [`__wasi_fd_pwrite()`](#fd_pwrite). + +- **`__WASI_RIGHT_FD_ADVISE`** + + The right to invoke [`__wasi_fd_advise()`](#fd_advise). + +- **`__WASI_RIGHT_FD_ALLOCATE`** + + The right to invoke [`__wasi_fd_allocate()`](#fd_allocate). + +- **`__WASI_RIGHT_PATH_CREATE_DIRECTORY`** + + The right to invoke [`__wasi_path_create_directory()`](#path_create_directory). + +- **`__WASI_RIGHT_PATH_CREATE_FILE`** + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, the right to invoke + [`__wasi_path_open()`](#path_open) with [`__WASI_O_CREAT`](#oflags.creat). + +- **`__WASI_RIGHT_PATH_LINK_SOURCE`** + + The right to invoke [`__wasi_path_link()`](#path_link) with the file + descriptor as the source directory. + +- **`__WASI_RIGHT_PATH_LINK_TARGET`** + + The right to invoke [`__wasi_path_link()`](#path_link) with the file + descriptor as the target directory. + +- **`__WASI_RIGHT_PATH_OPEN`** + + The right to invoke [`__wasi_path_open()`](#path_open). + +- **`__WASI_RIGHT_FD_READDIR`** + + The right to invoke [`__wasi_fd_readdir()`](#fd_readdir). + +- **`__WASI_RIGHT_PATH_READLINK`** + + The right to invoke [`__wasi_path_readlink()`](#path_readlink). + +- **`__WASI_RIGHT_PATH_RENAME_SOURCE`** + + The right to invoke [`__wasi_path_rename()`](#path_rename) with the file + descriptor as the source directory. + +- **`__WASI_RIGHT_PATH_RENAME_TARGET`** + + The right to invoke [`__wasi_path_rename()`](#path_rename) with the file + descriptor as the target directory. + +- **`__WASI_RIGHT_PATH_FILESTAT_GET`** + + The right to invoke [`__wasi_path_filestat_get()`](#path_filestat_get). + +- **`__WASI_RIGHT_PATH_FILESTAT_SET_SIZE`** + + The right to change a file's size (there is no `__wasi_path_filestat_set_size()`). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_O_TRUNC`](#oflags.trunc). + +- **`__WASI_RIGHT_PATH_FILESTAT_SET_TIMES`** + + The right to invoke [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +- **`__WASI_RIGHT_FD_FILESTAT_GET`** + + The right to invoke [`__wasi_fd_filestat_get()`](#fd_filestat_get). + +- **`__WASI_RIGHT_FD_FILESTAT_SET_SIZE`** + + The right to invoke [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size). + +- **`__WASI_RIGHT_FD_FILESTAT_SET_TIMES`** + + The right to invoke [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times). + +- **`__WASI_RIGHT_PATH_SYMLINK`** + + The right to invoke [`__wasi_path_symlink()`](#path_symlink). + +- **`__WASI_RIGHT_PATH_UNLINK_FILE`** + + The right to invoke [`__wasi_path_unlink_file()`](#path_unlink_file). + +- **`__WASI_RIGHT_PATH_REMOVE_DIRECTORY`** + + The right to invoke [`__wasi_path_remove_directory()`](#path_remove_directory). + +- **`__WASI_RIGHT_POLL_FD_READWRITE`** + + If [`__WASI_RIGHT_FD_READ`](#rights.fd_read) is set, includes the right to + invoke [`__wasi_poll_oneoff()`](#poll_oneoff) to subscribe to [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read). + + If [`__WASI_RIGHT_FD_WRITE`](#rights.fd_write) is set, includes the right to + invoke [`__wasi_poll_oneoff()`](#poll_oneoff) to subscribe to [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write). + +- **`__WASI_RIGHT_SOCK_SHUTDOWN`** + + The right to invoke [`__wasi_sock_shutdown()`](#sock_shutdown). + +### `__wasi_roflags_t` (`uint16_t` bitfield) + +Flags returned by [`__wasi_sock_recv()`](#sock_recv). + +Used by [`__wasi_sock_recv()`](#sock_recv). + +Possible values: + +- **`__WASI_SOCK_RECV_DATA_TRUNCATED`** + + Returned by [`__wasi_sock_recv()`](#sock_recv): Message data has been + truncated. + +### `__wasi_sdflags_t` (`uint8_t` bitfield) + +Which channels on a socket to shut down. + +Used by [`__wasi_sock_shutdown()`](#sock_shutdown). + +Possible values: + +- **`__WASI_SHUT_RD`** + + Disables further receive operations. + +- **`__WASI_SHUT_WR`** + + Disables further send operations. + +### `__wasi_siflags_t` (`uint16_t` bitfield) + +Flags provided to [`__wasi_sock_send()`](#sock_send). As there are currently no flags +defined, it must be set to zero. + +Used by [`__wasi_sock_send()`](#sock_send). + +### `__wasi_signal_t` (`uint8_t`) + +Signal condition. + +Used by [`__wasi_proc_raise()`](#proc_raise). + +Possible values: + +- **`__WASI_SIGABRT`** + + Process abort signal. + + Action: Terminates the process. + +- **`__WASI_SIGALRM`** + + Alarm clock. + + Action: Terminates the process. + +- **`__WASI_SIGBUS`** + + Access to an undefined portion of a memory object. + + Action: Terminates the process. + +- **`__WASI_SIGCHLD`** + + Child process terminated, stopped, or continued. + + Action: Ignored. + +- **`__WASI_SIGCONT`** + + Continue executing, if stopped. + + Action: Continues executing, if stopped. + +- **`__WASI_SIGFPE`** + + Erroneous arithmetic operation. + + Action: Terminates the process. + +- **`__WASI_SIGHUP`** + + Hangup. + + Action: Terminates the process. + +- **`__WASI_SIGILL`** + + Illegal instruction. + + Action: Terminates the process. + +- **`__WASI_SIGINT`** + + Terminate interrupt signal. + + Action: Terminates the process. + +- **`__WASI_SIGKILL`** + + Kill. + + Action: Terminates the process. + +- **`__WASI_SIGPIPE`** + + Write on a pipe with no one to read it. + + Action: Ignored. + +- **`__WASI_SIGQUIT`** + + Terminal quit signal. + + Action: Terminates the process. + +- **`__WASI_SIGSEGV`** + + Invalid memory reference. + + Action: Terminates the process. + +- **`__WASI_SIGSTOP`** + + Stop executing. + + Action: Stops executing. + +- **`__WASI_SIGSYS`** + + Bad system call. + + Action: Terminates the process. + +- **`__WASI_SIGTERM`** + + Termination signal. + + Action: Terminates the process. + +- **`__WASI_SIGTRAP`** + + Trace/breakpoint trap. + + Action: Terminates the process. + +- **`__WASI_SIGTSTP`** + + Terminal stop signal. + + Action: Stops executing. + +- **`__WASI_SIGTTIN`** + + Background process attempting read. + + Action: Stops executing. + +- **`__WASI_SIGTTOU`** + + Background process attempting write. + + Action: Stops executing. + +- **`__WASI_SIGURG`** + + High bandwidth data is available at a socket. + + Action: Ignored. + +- **`__WASI_SIGUSR1`** + + User-defined signal 1. + + Action: Terminates the process. + +- **`__WASI_SIGUSR2`** + + User-defined signal 2. + + Action: Terminates the process. + +- **`__WASI_SIGVTALRM`** + + Virtual timer expired. + + Action: Terminates the process. + +- **`__WASI_SIGXCPU`** + + CPU time limit exceeded. + + Action: Terminates the process. + +- **`__WASI_SIGXFSZ`** + + File size limit exceeded. + + Action: Terminates the process. + +### `__wasi_subclockflags_t` (`uint16_t` bitfield) + +Flags determining how to interpret the timestamp provided in +[`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout). + +Used by [`__wasi_subscription_t`](#subscription). + +Possible values: + +- **`__WASI_SUBSCRIPTION_CLOCK_ABSTIME`** + + If set, treat the timestamp provided in + [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout) as an absolute timestamp + of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id). + + If clear, treat the timestamp provided in + [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout) relative to the current + time value of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id). + +### `__wasi_subscription_t` (`struct`) + +Subscription to an event. + +Used by [`__wasi_poll_oneoff()`](#poll_oneoff). + +Members: + +- [\_\_wasi\_userdata\_t](#userdata) userdata + + User-provided value that is attached to the subscription in the + implementation and returned through + [`__wasi_event_t::userdata`](#event.userdata). + +- [\_\_wasi\_eventtype\_t](#eventtype) type + + The type of the event to which to subscribe. + +- When `type` is [`__WASI_EVENTTYPE_CLOCK`](#eventtype.u.clock): + + - **`u.clock`** + + - [\_\_wasi\_userdata\_t](#userdata) identifier + + The user-defined unique identifier of the clock. + + - [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock against which to compare the timestamp. + + - [\_\_wasi\_timestamp\_t](#timestamp) timeout + + The absolute or relative timestamp. + + - [\_\_wasi\_timestamp\_t](#timestamp) precision + + The amount of time that the implementation may wait additionally + to coalesce with other events. + + - [\_\_wasi\_subclockflags\_t](#subclockflags) flags + + Flags specifying whether the timeout is absolute or relative. + +- When `type` is [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write): + + - **`u.fd_readwrite`** + + - [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor on which to wait for it to become ready + for reading or writing. + +### `__wasi_timestamp_t` (`uint64_t`) + +Timestamp in nanoseconds. + +Used by [`__wasi_filestat_t`](#filestat), [`__wasi_subscription_t`](#subscription), [`__wasi_clock_res_get()`](#clock_res_get), [`__wasi_clock_time_get()`](#clock_time_get), [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times), and [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +### `__wasi_userdata_t` (`uint64_t`) + +User-provided value that may be attached to objects that is +retained when extracted from the implementation. + +Used by [`__wasi_event_t`](#event) and [`__wasi_subscription_t`](#subscription). + +### `__wasi_whence_t` (`uint8_t`) + +The position relative to which to set the offset of the file descriptor. + +Used by [`__wasi_fd_seek()`](#fd_seek). + +Possible values: + +- **`__WASI_WHENCE_CUR`** + + Seek relative to current position. + +- **`__WASI_WHENCE_END`** + + Seek relative to end-of-file. + +- **`__WASI_WHENCE_SET`** + + Seek relative to start-of-file. + diff --git a/phases/old/witx/typenames.witx b/phases/old/witx/typenames.witx new file mode 100644 index 00000000..51462bd6 --- /dev/null +++ b/phases/old/witx/typenames.witx @@ -0,0 +1,752 @@ +;; Type names used by low-level WASI interfaces. +;; +;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). +;; +;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md) +;; for an explanation of what that means. + +(typename $size_t u32) + +;; Non-negative file size or length of a region within a file. +(typename $filesize_t u64) + +;; Timestamp in nanoseconds. +(typename $timestamp_t u64) + +;; Identifiers for clocks. +(typename $clockid_t + (enum u32 + ;; The store-wide monotonic clock, which is defined as a clock measuring + ;; real time, whose value cannot be adjusted and which cannot have negative + ;; clock jumps. The epoch of this clock is undefined. The absolute time + ;; value of this clock therefore has no meaning. + $CLOCK_MONOTONIC + ;; The CPU-time clock associated with the current process. + $CLOCK_PROCESS_CPUTIME_ID + ;; The clock measuring real time. Time value zero corresponds with + ;; 1970-01-01T00:00:00Z. + $CLOCK_REALTIME + ;; The CPU-time clock associated with the current thread. + $CLOCK_THREAD_CPUTIME_ID + ) +) + +;; 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. +(typename $errno_t + (enum u16 + ;; No error occurred. System call completed successfully. + $ESUCCESS + ;; Argument list too long. + $E2BIG + ;; Permission denied. + $EACCES + ;; Address in use. + $EADDRINUSE + ;; Address not available. + $EADDRNOTAVAIL + ;; Address family not supported. + $EAFNOSUPPORT + ;; Resource unavailable, or operation would block. + $EAGAIN + ;; Connection already in progress. + $EALREADY + ;; Bad file descriptor. + $EBADF + ;; Bad message. + $EBADMSG + ;; Device or resource busy. + $EBUSY + ;; Operation canceled. + $ECANCELED + ;; No child processes. + $ECHILD + ;; Connection aborted. + $ECONNABORTED + ;; Connection refused. + $ECONNREFUSED + ;; Connection reset. + $ECONNRESET + ;; Resource deadlock would occur. + $EDEADLK + ;; Destination address required. + $EDESTADDRREQ + ;; Mathematics argument out of domain of function. + $EDOM + ;; Reserved. + $EDQUOT + ;; File exists. + $EEXIST + ;; Bad address. + $EFAULT + ;; File too large. + $EFBIG + ;; Host is unreachable. + $EHOSTUNREACH + ;; Identifier removed. + $EIDRM + ;; Illegal byte sequence. + $EILSEQ + ;; Operation in progress. + $EINPROGRESS + ;; Interrupted function. + $EINTR + ;; Invalid argument. + $EINVAL + ;; I/O error. + $EIO + ;; Socket is connected. + $EISCONN + ;; Is a directory. + $EISDIR + ;; Too many levels of symbolic links. + $ELOOP + ;; File descriptor value too large. + $EMFILE + ;; Too many links. + $EMLINK + ;; Message too large. + $EMSGSIZE + ;; Reserved. + $EMULTIHOP + ;; Filename too long. + $ENAMETOOLONG + ;; Network is down. + $ENETDOWN + ;; Connection aborted by network. + $ENETRESET + ;; Network unreachable. + $ENETUNREACH + ;; Too many files open in system. + $ENFILE + ;; No buffer space available. + $ENOBUFS + ;; No such device. + $ENODEV + ;; No such file or directory. + $ENOENT + ;; Executable file format error. + $ENOEXEC + ;; No locks available. + $ENOLCK + ;; Reserved. + $ENOLINK + ;; Not enough space. + $ENOMEM + ;; No message of the desired type. + $ENOMSG + ;; Protocol not available. + $ENOPROTOOPT + ;; No space left on device. + $ENOSPC + ;; Function not supported. + $ENOSYS + ;; The socket is not connected. + $ENOTCONN + ;; Not a directory or a symbolic link to a directory. + $ENOTDIR + ;; Directory not empty. + $ENOTEMPTY + ;; State not recoverable. + $ENOTRECOVERABLE + ;; Not a socket. + $ENOTSOCK + ;; Not supported, or operation not supported on socket. + $ENOTSUP + ;; Inappropriate I/O control operation. + $ENOTTY + ;; No such device or address. + $ENXIO + ;; Value too large to be stored in data type. + $EOVERFLOW + ;; Previous owner died. + $EOWNERDEAD + ;; Operation not permitted. + $EPERM + ;; Broken pipe. + $EPIPE + ;; Protocol error. + $EPROTO + ;; Protocol not supported. + $EPROTONOSUPPORT + ;; Protocol wrong type for socket. + $EPROTOTYPE + ;; Result too large. + $ERANGE + ;; Read-only file system. + $EROFS + ;; Invalid seek. + $ESPIPE + ;; No such process. + $ESRCH + ;; Reserved. + $ESTALE + ;; Connection timed out. + $ETIMEDOUT + ;; Text file busy. + $ETXTBSY + ;; Cross-device link. + $EXDEV + ;; Extension: Capabilities insufficient. + $ENOTCAPABLE + ) +) + +;; File descriptor rights, determining which actions may be performed. +(typename $rights_t + (flags u64 + ;; The right to invoke `fd_datasync`. + ;; + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;; `path_open` with `FDFLAG_DSYNC`. + (flag $RIGHT_FD_DATASYNC) + ;; The right to invoke `fd_read` and `sock_recv`. + ;; + ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. + (flag $RIGHT_FD_READ) + ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + (flag $RIGHT_FD_SEEK) + ;; The right to invoke `fd_fdstat_set_flags`. + (flag $RIGHT_FD_FDSTAT_SET_FLAGS) + ;; The right to invoke `fd_sync`. + ;; + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. + (flag $RIGHT_FD_SYNC) + ;; The right to invoke `fd_seek` in such a way that the file offset + ;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to + ;; invoke `fd_tell`. + (flag $RIGHT_FD_TELL) + ;; The right to invoke `fd_write` and `sock_send`. + ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. + (flag $RIGHT_FD_WRITE) + ;; The right to invoke `fd_advise`. + (flag $RIGHT_FD_ADVISE) + ;; The right to invoke `fd_allocate`. + (flag $RIGHT_FD_ALLOCATE) + ;; The right to invoke `path_create_directory`. + (flag $RIGHT_PATH_CREATE_DIRECTORY) + ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + (flag $RIGHT_PATH_CREATE_FILE) + ;; The right to invoke `path_link` with the file descriptor as the + ;; source directory. + (flag $RIGHT_PATH_LINK_SOURCE) + ;; The right to invoke `path_link` with the file descriptor as the + ;; target directory. + (flag $RIGHT_PATH_LINK_TARGET) + ;; The right to invoke `path_open`. + (flag $RIGHT_PATH_OPEN) + ;; The right to invoke `fd_readdir`. + (flag $RIGHT_FD_READDIR) + ;; The right to invoke `path_readlink`. + (flag $RIGHT_PATH_READLINK) + ;; The right to invoke `path_rename` with the file descriptor as the source directory. + (flag $RIGHT_PATH_RENAME_SOURCE) + ;; The right to invoke `path_rename` with the file descriptor as the target directory. + (flag $RIGHT_PATH_RENAME_TARGET) + ;; The right to invoke `path_filestat_get`. + (flag $RIGHT_PATH_FILESTAT_GET) + ;; The right to change a file's size (there is no `path_filestat_set_size`). + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. + (flag $RIGHT_PATH_FILESTAT_SET_SIZE) + ;; The right to invoke `path_filestat_set_times`. + (flag $RIGHT_PATH_FILESTAT_SET_TIMES) + ;; The right to invoke `fd_filestat_get`. + (flag $RIGHT_FD_FILESTAT_GET) + ;; The right to invoke `fd_filestat_set_size`. + (flag $RIGHT_FD_FILESTAT_SET_SIZE) + ;; The right to invoke `fd_filestat_set_times`. + (flag $RIGHT_FD_FILESTAT_SET_TIMES) + ;; The right to invoke `path_symlink`. + (flag $RIGHT_PATH_SYMLINK) + ;; The right to invoke `path_unlink_file`. + (flag $RIGHT_PATH_UNLINK_FILE) + ;; The right to invoke `path_remove_directory`. + (flag $RIGHT_PATH_REMOVE_DIRECTORY) + ;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. + ;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. + (flag $RIGHT_POLL_FD_READWRITE) + ;; The right to invoke `sock_shutdown`. + (flag $RIGHT_SOCK_SHUTDOWN) + ) +) + +;; A file descriptor index. +(typename $fd_t u32) + +;; A region of memory for scatter/gather reads. +(typename $iovec_t + (struct + ;; The address of the buffer to be filled. + (field $buf (@witx pointer u8)) + ;; The length of the buffer to be filled. + (field $buf_len $size_t) + ) +) + +;; A region of memory for scatter/gather writes. +(typename $ciovec_t + (struct + ;; The address of the buffer to be written. + (field $buf (@witx const_pointer u8)) + ;; The length of the buffer to be written. + (field $buf_len $size_t) + ) +) + +(typename $iovec_t_array (array $iovec_t)) +(typename $ciovec_t_array (array $ciovec_t)) + +;; Relative offset within a file. +(typename $filedelta_t s64) + +;; The position relative to which to set the offset of the file descriptor. +(typename $whence_t + (enum u8 + ;; Seek relative to current position. + $WHENCE_CUR + ;; Seek relative to end-of-file. + $WHENCE_END + ;; Seek relative to start-of-file. + $WHENCE_SET + ) +) + +;; A reference to the offset of a directory entry. +(typename $dircookie_t u64) + +;; The type for the $d_namlen field of $dirent_t. +(typename $dirnamlen_t u32) + +;; File serial number that is unique within its file system. +(typename $inode_t u64) + +;; The type of a file descriptor or file. +(typename $filetype_t + (enum u8 + ;; The type of the file descriptor or file is unknown or is different from any of the other types specified. + $FILETYPE_UNKNOWN + ;; The file descriptor or file refers to a block device inode. + $FILETYPE_BLOCK_DEVICE + ;; The file descriptor or file refers to a character device inode. + $FILETYPE_CHARACTER_DEVICE + ;; The file descriptor or file refers to a directory inode. + $FILETYPE_DIRECTORY + ;; The file descriptor or file refers to a regular file inode. + $FILETYPE_REGULAR_FILE + ;; The file descriptor or file refers to a datagram socket. + $FILETYPE_SOCKET_DGRAM + ;; The file descriptor or file refers to a byte-stream socket. + $FILETYPE_SOCKET_STREAM + ;; The file refers to a symbolic link inode. + $FILETYPE_SYMBOLIC_LINK + ) +) + +;; A directory entry. +(typename $dirent_t + (struct + ;; The offset of the next directory entry stored in this directory. + (field $d_next $dircookie_t) + ;; The serial number of the file referred to by this directory entry. + (field $d_ino $inode_t) + ;; The length of the name of the directory entry. + (field $d_namlen $dirnamlen_t) + ;; The type of the file referred to by this directory entry. + (field $d_type $filetype_t) + ) +) + +;; File or memory access pattern advisory information. +(typename $advice_t + (enum u8 + ;; The application expects that it will not access the specified data in the near future. + $ADVICE_DONTNEED + ;; The application expects to access the specified data once and then not reuse it thereafter. + $ADVICE_NOREUSE + ;; The application has no advice to give on its behavior with respect to the specified data. + $ADVICE_NORMAL + ;; The application expects to access the specified data in a random order. + $ADVICE_RANDOM + ;; The application expects to access the specified data sequentially from lower offsets to higher offsets. + $ADVICE_SEQUENTIAL + ;; The application expects to access the specified data in the near future. + $ADVICE_WILLNEED + ) +) + +;; File descriptor flags. +(typename $fdflags_t + (flags u16 + ;; Append mode: Data written to the file is always appended to the file's end. + (flag $FDFLAG_APPEND) + ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + (flag $FDFLAG_DSYNC) + ;; Non-blocking mode. + (flag $FDFLAG_NONBLOCK) + ;; Synchronized read I/O operations. + (flag $FDFLAG_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. + (flag $FDFLAG_SYNC) + ) +) + +;; File descriptor attributes. +(typename $fdstat_t + (struct + ;; File type. + (field $fs_filetype $filetype_t) + ;; File descriptor flags. + (field $fs_flags $fdflags_t) + ;; Rights that apply to this file descriptor. + (field $fs_rights_base $rights_t) + ;; Maximum set of rights that may be installed on new file descriptors that + ;; are created through this file descriptor, e.g., through `path_open`. + (field $fs_rights_inheriting $rights_t) + ) +) + +;; Identifier for a device containing a file system. Can be used in combination +;; with `inode_t` to uniquely identify a file or directory in the filesystem. +(typename $device_t u64) + +;; Which file time attributes to adjust. +(typename $fstflags_t + (flags u16 + ;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. + (flag $FILESTAT_SET_ATIM) + ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + (flag $FILESTAT_SET_ATIM_NOW) + ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + (flag $FILESTAT_SET_MTIM) + ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + (flag $FILESTAT_SET_MTIM_NOW) + ) +) + +;; Flags determining the method of how paths are resolved. +(typename $lookupflags_t + (flags u32 + ;; As long as the resolved path corresponds to a symbolic link, it is expanded. + (flag $LOOKUP_SYMLINK_FOLLOW) + ) +) + +;; Open flags used by `path_open`. +(typename $oflags_t + (flags u16 + ;; Create file if it does not exist. + (flag $O_CREAT) + ;; Fail if not a directory. + (flag $O_DIRECTORY) + ;; Fail if file already exists. + (flag $O_EXCL) + ;; Truncate file to size 0. + (flag $O_TRUNC) + ) +) + +;; Number of hard links to an inode. +(typename $linkcount_t u32) + +;; File attributes. +(typename $filestat_t + (struct + ;; Device ID of device containing the file. + (field $st_dev $device_t) + ;; File serial number. + (field $st_ino $inode_t) + ;; File type. + (field $st_filetype $filetype_t) + ;; Number of hard links to the file. + (field $st_nlink $linkcount_t) + ;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. + (field $st_size $filesize_t) + ;; Last data access timestamp. + (field $st_atim $timestamp_t) + ;; Last data modification timestamp. + (field $st_mtim $timestamp_t) + ;; Last file status change timestamp. + (field $st_ctim $timestamp_t) + ) +) + +;; User-provided value that may be attached to objects that is retained when +;; extracted from the implementation. +(typename $userdata_t u64) + +;; Type of a subscription to an event or its occurrence. +(typename $eventtype_t + (flags u8 + ;; The time value of clock `subscription_t::u.clock.clock_id` has + ;; reached timestamp `subscription_t::u.clock.timeout`. + (flag $EVENTTYPE_CLOCK) + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;; available for reading. This event always triggers for regular files. + (flag $EVENTTYPE_FD_READ) + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;; available for writing. This event always triggers for regular files. + (flag $EVENTTYPE_FD_WRITE) + ) +) + +;; The state of the file descriptor subscribed to with +;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +(typename $eventrwflags_t + (flags u16 + ;; The peer of this socket has closed or disconnected. + (flag $EVENT_FD_READWRITE_HANGUP) + ) +) + +;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or +;; `EVENTTYPE_FD_WRITE`. +(typename $event_fd_readwrite_t + (struct + ;; The number of bytes available for reading or writing. + (field $nbytes $filesize_t) + ;; The state of the file descriptor. + (field $flags $eventrwflags_t) + ) +) + +;; The contents of an $event_t. +(typename $event_u + (union + ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + (field $fd_readwrite $event_fd_readwrite_t) + ) +) + +;; An event that occurred. +(typename $event_t + (struct + ;; User-provided value that got attached to `subscription_t::userdata`. + (field $userdata $userdata_t) + ;; If non-zero, an error that occurred while processing the subscription request. + (field $error $errno_t) + ;; The type of the event that occurred. + (field $type $eventtype_t) + ;; The contents of the event. + (field $u $event_u) + ) +) + +;; Flags determining how to interpret the timestamp provided in +;; `subscription_t::u.clock.timeout.` +(typename $subclockflags_t + (flags u16 + ;; If set, treat the timestamp provided in + ;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock + ;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp + ;; provided in `subscription_t::u.clock.timeout` relative to the + ;; current time value of clock `subscription_t::u.clock.clock_id.` + (flag $SUBSCRIPTION_CLOCK_ABSTIME) + ) +) + +;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +(typename $subscription_clock_t + (struct + ;; The user-defined unique identifier of the clock. + (field $identifier $userdata_t) + ;; The clock against which to compare the timestamp. + (field $clock_id $clockid_t) + ;; The absolute or relative timestamp. + (field $timeout $timestamp_t) + ;; The amount of time that the implementation may wait additionally + ;; to coalesce with other events. + ;; + ;; Flags specifying whether the timeout is absolute or relative + (field $precision $timestamp_t) + ) +) + +;; The contents of a $subscription_t when type is type is +;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +(typename $subscription_fd_readwrite_t + (struct + ;; The file descriptor on which to wait for it to become ready for reading or writing. + (field $file_descriptor $fd_t) + ) +) + +;; The contents of a $subscription_t. +(typename $subscription_u + (union + ;; When type is `EVENTTYPE_CLOCK`: + (field $clock $subscription_clock_t) + ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + (field $fd_readwrite $subscription_fd_readwrite_t) + ) +) + +;; Subscription to an event. +(typename $subscription_t + (struct + ;; User-provided value that is attached to the subscription in the + ;; implementation and returned through `event_t::userdata`. + (field $userdata $userdata_t) + ;; The type of the event to which to subscribe. + (field $type $eventtype_t) + ;; The contents of the subscription. + (field $u $subscription_u) + ) +) + +;; Exit code generated by a process when exiting. +(typename $exitcode_t u32) + +;; Signal condition. +(typename $signal_t + (enum u8 + ;; Process abort signal. + ;; Action: Terminates the process. + $SIGABRT + ;; Alarm clock. + ;; Action: Terminates the process. + $SIGALRM + ;; Access to an undefined portion of a memory object. + ;; Action: Terminates the process. + $SIGBUS + ;; Child process terminated, stopped, or continued. + ;; Action: Ignored. + $SIGCHLD + ;; Continue executing, if stopped. + ;; Action: Continues executing, if stopped. + $SIGCONT + ;; Erroneous arithmetic operation. + ;; Action: Terminates the process. + $SIGFPE + ;; Hangup. + ;; Action: Terminates the process. + $SIGHUP + ;; Illegal instruction. + ;; Action: Terminates the process. + $SIGILL + ;; Terminate interrupt signal. + ;; Action: Terminates the process. + $SIGINT + ;; Kill. + ;; Action: Terminates the process. + $SIGKILL + ;; Write on a pipe with no one to read it. + ;; Action: Ignored. + $SIGPIPE + ;; Terminal quit signal. + ;; Action: Terminates the process. + $SIGQUIT + ;; Invalid memory reference. + ;; Action: Terminates the process. + $SIGSEGV + ;; Stop executing. + ;; Action: Stops executing. + $SIGSTOP + ;; Bad system call. + ;; Action: Terminates the process. + $SIGSYS + ;; Termination signal. + ;; Action: Terminates the process. + $SIGTERM + ;; Trace/breakpoint trap. + ;; Action: Terminates the process. + $SIGTRAP + ;; Terminal stop signal. + ;; Action: Stops executing. + $SIGTSTP + ;; Background process attempting read. + ;; Action: Stops executing. + $SIGTTIN + ;; Background process attempting write. + ;; Action: Stops executing. + $SIGTTOU + ;; High bandwidth data is available at a socket. + ;; Action: Ignored. + $SIGURG + ;; User-defined signal 1. + ;; Action: Terminates the process. + $SIGUSR1 + ;; User-defined signal 2. + ;; Action: Terminates the process. + $SIGUSR2 + ;; Virtual timer expired. + ;; Action: Terminates the process. + $SIGVTALRM + ;; CPU time limit exceeded. + ;; Action: Terminates the process. + $SIGXCPU + ;; File size limit exceeded. + ;; Action: Terminates the process. + $SIGXFSZ + ) +) + +;; Flags provided to `sock_recv`. +(typename $riflags_t + (flags u16 + ;; Returns the message without removing it from the socket's receive queue. + (flag $SOCK_RECV_PEEK) + ;; On byte-stream sockets, block until the full amount of data can be returned. + (flag $SOCK_RECV_WAITALL) + ) +) + +;; Flags returned by `sock_recv`. +(typename $roflags_t + (flags u16 + ;; Returned by `sock_recv`: Message data has been truncated. + (flag $SOCK_RECV_DATA_TRUNCATED) + ) +) + +;; Flags provided to `sock_send`. As there are currently no flags +;; defined, it must be set to zero. +(typename $siflags_t u16) + +;; Which channels on a socket to shut down. +(typename $sdflags_t + (flags u8 + ;; Disables further receive operations. + (flag $SHUT_RD) + ;; Disables further send operations. + (flag $SHUT_WR) + ) +) + +;; Identifiers for preopened capabilities. +(typename preopentype_t + (enum u8 + ;; A pre-opened directory. + $PREOPENTYPE_DIR + ) +) + +;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. +(typename $prestat_dir + (struct + ;; The length of the directory name for use with `fd_prestat_dir_name`. + (field $pr_name_len $size_t) + ) +) + +;; The contents of an $prestat_t. +(typename $prestat_u + (union + ;; When type is `PREOPENTYPE_DIR`: + (field $dir $prestat_dir) + ) +) + +;; Information about a pre-opened capability. +(typename $prestat_t + (struct + ;; The type of the pre-opened capability. + (field $pr_type $preopentype_t) + ;; The contents of the information. + (field $u $prestat_u) + ) +) diff --git a/design/wasi_unstable/wasi_unstable.witx b/phases/old/witx/wasi_unstable.witx similarity index 98% rename from design/wasi_unstable/wasi_unstable.witx rename to phases/old/witx/wasi_unstable.witx index 6d4bea54..f9586ff1 100644 --- a/design/wasi_unstable/wasi_unstable.witx +++ b/phases/old/witx/wasi_unstable.witx @@ -1,4 +1,5 @@ -;; The wasi_unstable module type. +;; WASI Preview. This is an evolution of the API that WASI initially +;; launched with. ;; ;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). ;; @@ -7,6 +8,9 @@ (use "typenames.witx") +;; This API predated the convention of naming modules with a `wasi_unstable_` +;; prefix and a version number. It is preserved here for compatibility, but +;; we shouldn't follow this pattern in new APIs. (module $wasi_unstable ;; Linear memory to be accessed by WASI functions that need it. (import "memory" (memory)) diff --git a/phases/unstable/docs/wasi_unstable_preview0.md b/phases/unstable/docs/wasi_unstable_preview0.md new file mode 100644 index 00000000..9db4a382 --- /dev/null +++ b/phases/unstable/docs/wasi_unstable_preview0.md @@ -0,0 +1,2319 @@ + + +# The WASI Preview API + +This is the API-level documentation for WASI Preview. The function names +are prefixed with "\_\_wasi\_" to reflect how they are spelled in +flat-namespace contexts, however at the wasm module level, they are +unprefixed, because they're inside a module namespace. + +Functions that start with `__wasi_fd_` operate on file descriptors, +while functions that start with `__wasi_path_` operate on filesystem +paths, which are relative to directory file descriptors. + +Much inspiration and content here is derived from [CloudABI] and [POSIX], +though there are also several differences from CloudABI and POSIX. For +example, WASI Preview has no concept of processes in the traditional Unix +sense. While wasm linear memories have some of the aspects of processes, +and it's possible to *emulate* the full semantics of processes on top of +them, this can sometimes be unnatural and inefficient. The goal for +WASI Preview is to be a WebAssembly-native API that exposes APIs that fit +well into the underlying WebAssembly platform, rather than to directly +emulate other platforms. + +This is also a work in progress, and the API here is still evolving. + +Historical note: this API was originally named "WASI Core", and used the +API module name "wasi\_unstable". We've since sought to deemphasize the +"Core" name, as the goal is to split this API up into independent +modules so that embedders need not implement all of it. + +[CloudABI]: https://github.com/NuxiNL/cloudabi +[POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/ + +## System calls + +- [`__wasi_args_get()`](#args_get) +- [`__wasi_args_sizes_get()`](#args_sizes_get) +- [`__wasi_clock_res_get()`](#clock_res_get) +- [`__wasi_clock_time_get()`](#clock_time_get) +- [`__wasi_environ_get()`](#environ_get) +- [`__wasi_environ_sizes_get()`](#environ_sizes_get) +- [`__wasi_fd_advise()`](#fd_advise) +- [`__wasi_fd_allocate()`](#fd_allocate) +- [`__wasi_fd_close()`](#fd_close) +- [`__wasi_fd_datasync()`](#fd_datasync) +- [`__wasi_fd_fdstat_get()`](#fd_fdstat_get) +- [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags) +- [`__wasi_fd_fdstat_set_rights()`](#fd_fdstat_set_rights) +- [`__wasi_fd_filestat_get()`](#fd_filestat_get) +- [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size) +- [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times) +- [`__wasi_fd_pread()`](#fd_pread) +- [`__wasi_fd_prestat_get()`](#fd_prestat_get) +- [`__wasi_fd_prestat_dir_name()`](#fd_prestat_dir_name) +- [`__wasi_fd_pwrite()`](#fd_pwrite) +- [`__wasi_fd_read()`](#fd_read) +- [`__wasi_fd_readdir()`](#fd_readdir) +- [`__wasi_fd_renumber()`](#fd_renumber) +- [`__wasi_fd_seek()`](#fd_seek) +- [`__wasi_fd_sync()`](#fd_sync) +- [`__wasi_fd_tell()`](#fd_tell) +- [`__wasi_fd_write()`](#fd_write) +- [`__wasi_path_create_directory()`](#path_create_directory) +- [`__wasi_path_filestat_get()`](#path_filestat_get) +- [`__wasi_path_filestat_set_times()`](#path_filestat_set_times) +- [`__wasi_path_link()`](#path_link) +- [`__wasi_path_open()`](#path_open) +- [`__wasi_path_readlink()`](#path_readlink) +- [`__wasi_path_remove_directory()`](#path_remove_directory) +- [`__wasi_path_rename()`](#path_rename) +- [`__wasi_path_symlink()`](#path_symlink) +- [`__wasi_path_unlink_file()`](#path_unlink_file) +- [`__wasi_poll_oneoff()`](#poll_oneoff) +- [`__wasi_proc_exit()`](#proc_exit) +- [`__wasi_proc_raise()`](#proc_raise) +- [`__wasi_random_get()`](#random_get) +- [`__wasi_sched_yield()`](#sched_yield) +- [`__wasi_sock_recv()`](#sock_recv) +- [`__wasi_sock_send()`](#sock_send) +- [`__wasi_sock_shutdown()`](#sock_shutdown) + +### `__wasi_args_get()` + +Read command-line argument data. + +The sizes of the buffers should match that returned by [`__wasi_args_sizes_get()`](#args_sizes_get). + +Inputs: + +- char \*\*argv + + A pointer to a buffer to write the argument pointers. + +- char \*argv\_buf + + A pointer to a buffer to write the argument string data. + +### `__wasi_args_sizes_get()` + +Return command-line argument data sizes. + +Outputs: + +- size\_t \*argc + + The number of arguments. + +- size\_t \*argv\_buf\_size + + The size of the argument string data. + +### `__wasi_clock_res_get()` + +Return the resolution of a clock. + +Implementations are required to provide a non-zero value for supported clocks. +For unsupported clocks, return [`__WASI_EINVAL`](#errno.inval). + +Note: This is similar to `clock_getres` in POSIX. + +Inputs: + +- [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock for which to return the resolution. + +Outputs: + +- [\_\_wasi\_timestamp\_t](#timestamp) resolution + + The resolution of the clock. + +### `__wasi_clock_time_get()` + +Return the time value of a clock. + +Note: This is similar to `clock_gettime` in POSIX. + +Inputs: + +- [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock for which to return the time. + +- [\_\_wasi\_timestamp\_t](#timestamp) precision + + The maximum lag (exclusive) that the returned + time value may have, compared to its actual + value. + +Outputs: + +- [\_\_wasi\_timestamp\_t](#timestamp) time + + The time value of the clock. + +### `__wasi_environ_get()` + +Read environment variable data. + +The sizes of the buffers should match that returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get). + +Inputs: + +- char \*\*environ + + A pointer to a buffer to write the environment variable pointers. + +- char \*environ\_buf + + A pointer to a buffer to write the environment variable string data. + +### `__wasi_environ_sizes_get()` + +Return command-line argument data sizes. + +Outputs: + +- size\_t \*environ\_count + + The number of environment variables. + +- size\_t \*environ\_buf\_size + + The size of the environment variable string data. + +### `__wasi_fd_advise()` + +Provide file advisory information on a file descriptor. + +Note: This is similar to `posix_fadvise` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor for the file for which to provide file advisory information. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file to which the advisory applies. + +- [\_\_wasi\_filesize\_t](#filesize) len + + The length of the region to which the advisory applies. + +- [\_\_wasi\_advice\_t](#advice) advice + + The advice. + +### `__wasi_fd_allocate()` + +Force the allocation of space in a file. + +Note: This is similar to `posix_fallocate` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor for the file in which to allocate space. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset at which to start the allocation. + +- [\_\_wasi\_filesize\_t](#filesize) len + + The length of the area that is allocated. + +### `__wasi_fd_close()` + +Close a file descriptor. + +Note: This is similar to `close` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to close. + +### `__wasi_fd_datasync()` + +Synchronize the data of a file to disk. + +Note: This is similar to `fdatasync` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file to synchronize to disk. + +### `__wasi_fd_fdstat_get()` + +Get the attributes of a file descriptor. + +Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well +as additional fields. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +- [\_\_wasi\_fdstat\_t](#fdstat) \*buf + + The buffer where the file descriptor's attributes are stored. + +### `__wasi_fd_fdstat_set_flags()` + +Adjust the flags associated with a file descriptor. + +Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_fdflags\_t](#fdflags) flags + + The desired values of the file descriptor + flags. + +### `__wasi_fd_fdstat_set_rights()` + +Adjust the rights associated with a file descriptor. + +This can only be used to remove rights, and returns +[`__WASI_ENOTCAPABLE`](#errno.notcapable) if called in a way that would attempt +to add rights. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The desired rights of the file descriptor. + +### `__wasi_fd_filestat_get()` + +Return the attributes of an open file. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +- [\_\_wasi\_filestat\_t](#filestat) \*buf + + The buffer where the file's attributes are + stored. + +### `__wasi_fd_filestat_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 is similar to `ftruncate` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + A file descriptor for the file to adjust. + +- [\_\_wasi\_filesize\_t](#filesize) st\_size + + The desired file size. + +### `__wasi_fd_filestat_set_times()` + +Adjust the timestamps of an open file or directory. + +Note: This is similar to `futimens` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + The desired values of the data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + The desired values of the data modification timestamp. + +- [\_\_wasi\_fstflags\_t](#fstflags) fst\_flags + + A bitmask indicating which timestamps to adjust. + +### `__wasi_fd_pread()` + +Read from a file descriptor, without using and updating the +file descriptor's offset. + +Note: This is similar to `preadv` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor from which to read data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors in which to store data. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file at which to read. + +Outputs: + +- size\_t nread + + The number of bytes read. + +### `__wasi_fd_prestat_get()` + +Return a description of the given preopened file descriptor. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor about which to retrieve information. + +- [\_\_wasi\_prestat\_t](#prestat) \*buf + + The buffer where the description is stored. + +### `__wasi_fd_prestat_dir_name()` + +Return a description of the given preopened file descriptor. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor about which to retrieve information. + +- const char \*path and size\_t path\_len + + A buffer into which to write the preopened directory name. + +### `__wasi_fd_pwrite()` + +Write to a file descriptor, without using and updating the +file descriptor's offset. + +Note: This is similar to `pwritev` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to which to write data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors from which to retrieve data. + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The offset within the file at which to write. + +Outputs: + +- size\_t nwritten + + The number of bytes written. + +### `__wasi_fd_read()` + +Read from a file descriptor. + +Note: This is similar to `readv` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor from which to read data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors to which to store data. + +Outputs: + +- size\_t nread + + The number of bytes read. + +### `__wasi_fd_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 [`__wasi_dirent_t`](#dirent) object, followed by [`__wasi_dirent_t::d_namlen`](#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. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The directory from which to read the directory + entries. + +- void \*buf and size\_t buf\_len + + The buffer where directory entries are stored. + +- [\_\_wasi\_dircookie\_t](#dircookie) cookie + + The location within the directory to start + reading. + +Outputs: + +- size\_t bufused + + 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. + +### `__wasi_fd_renumber()` + +Atomically replace a file descriptor by renumbering another +file descriptor. + +Due to the strong focus on thread safety, this environment +does not provide a mechanism to duplicate or renumber a file +descriptor to an arbitrary number, like dup2(). This would be +prone to race conditions, as an actual file descriptor with the +same number could be allocated by a different thread at the same +time. + +This function provides a way to atomically renumber file +descriptors, which would disappear if dup2() were to be +removed entirely. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) from + + The file descriptor to renumber. + +- [\_\_wasi\_fd\_t](#fd) to + + The file descriptor to overwrite. + +### `__wasi_fd_seek()` + +Move the offset of a file descriptor. + +Note: This is similar to `lseek` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to operate on. + +- [\_\_wasi\_filedelta\_t](#filedelta) offset + + The number of bytes to move. + +- [\_\_wasi\_whence\_t](#whence) whence + + The base from which the offset is relative. + +Outputs: + +- [\_\_wasi\_filesize\_t](#filesize) newoffset + + The new offset of the file descriptor, + relative to the start of the file. + +### `__wasi_fd_sync()` + +Synchronize the data and metadata of a file to disk. + +Note: This is similar to `fsync` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file containing the data + and metadata to synchronize to disk. + +### `__wasi_fd_tell()` + +Return the current offset of a file descriptor. + +Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to inspect. + +Outputs: + +- [\_\_wasi\_filesize\_t](#filesize) offset + + The current offset of the file descriptor, relative to the start of the file. + +### `__wasi_fd_write()` + +Write to a file descriptor. + +Note: This is similar to `writev` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor to which to write data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*iovs and size\_t iovs\_len + + List of scatter/gather vectors from which to retrieve data. + +Outputs: + +- size\_t nwritten + + The number of bytes written. + +### `__wasi_path_create_directory()` + +Create a directory. + +Note: This is similar to `mkdirat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path at which to create the directory. + +### `__wasi_path_filestat_get()` + +Return the attributes of a file or directory. + +Note: This is similar to `stat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) flags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The path of the file or directory to inspect. + +- [\_\_wasi\_filestat\_t](#filestat) \*buf + + The buffer where the file's attributes are + stored. + +### `__wasi_path_filestat_set_times()` + +Adjust the timestamps of a file or directory. + +Note: This is similar to `utimensat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) flags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The path of the file or directory to operate on. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + The desired values of the data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + The desired values of the data modification timestamp. + +- [\_\_wasi\_fstflags\_t](#fstflags) fst\_flags + + A bitmask indicating which timestamps to adjust. + +### `__wasi_path_link()` + +Create a hard link. + +Note: This is similar to `linkat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) old\_fd + + The working directory at which the resolution of the old path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) old\_flags + + Flags determining the method of how the path is resolved. + +- const char \*old\_path and size\_t old\_path\_len + + The source path from which to link. + +- [\_\_wasi\_fd\_t](#fd) new\_fd + + The working directory at which the resolution of the new path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path at which to create the hard link. + +### `__wasi_path_open()` + +Open a file or directory. + +The returned file descriptor is not guaranteed to be the lowest-numbered +file 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 file +descriptor is guaranteed to be less than 231. + +Note: This is similar to `openat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) dirfd + + The working directory at which the resolution of the path starts. + +- [\_\_wasi\_lookupflags\_t](#lookupflags) dirflags + + Flags determining the method of how the path is resolved. + +- const char \*path and size\_t path\_len + + The relative path of the file or directory to open, relative to + the [`dirfd`](#path_open.dirfd) directory. + +- [\_\_wasi\_oflags\_t](#oflags) o_flags + + The method by which to open the file. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base and [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + The initial rights of the newly created file descriptor. The + implementation is allowed to return a file descriptor with fewer + rights than specified, if and only if those rights do not apply + to the type of file being opened. + + The *base* rights are rights that will apply to operations using + the file descriptor itself, while the *inheriting* rights are + rights that apply to file descriptors derived from it. + +- [\_\_wasi\_fdflags\_t](#fdflags) fs\_flags + + The initial flags of the file descriptor. + +Outputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor of the file that has been + opened. + +### `__wasi_path_readlink()` + +Read the contents of a symbolic link. + +Note: This is similar to `readlinkat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path of the symbolic link from which to read. + +- char \*buf and size\_t buf\_len + + The buffer to which to write the contents of the symbolic link. + +Outputs: + +- size\_t bufused + + The number of bytes placed in the buffer. + +### `__wasi_path_remove_directory()` + +Remove a directory. + +Return [`__WASI_ENOTEMPTY`](#errno.notempty) if the directory is not empty. + +Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path to a directory to remove. + +### `__wasi_path_rename()` + +Rename a file or directory. + +Note: This is similar to `renameat` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) old\_fd + + The working directory at which the resolution of the old path starts. + +- const char \*old\_path and size\_t old\_path\_len + + The source path of the file or directory to rename. + +- [\_\_wasi\_fd\_t](#fd) new\_fd + + The working directory at which the resolution of the new path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path to which to rename the file or directory. + +### `__wasi_path_symlink()` + +Create a symbolic link. + +Note: This is similar to `symlinkat` in POSIX. + +Inputs: + +- const char \*old\_path and size\_t old_path\_len + + The contents of the symbolic link. + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*new\_path and size\_t new\_path\_len + + The destination path at which to create the symbolic link. + +### `__wasi_path_unlink_file()` + +Unlink a file. + +Return [`__WASI_EISDIR`](#errno.isdir) if the path refers to a directory. + +Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) fd + + The working directory at which the resolution of the path starts. + +- const char \*path and size\_t path\_len + + The path to a file to unlink. + +### `__wasi_poll_oneoff()` + +Concurrently poll for the occurrence of a set of events. + +Inputs: + +- const [\_\_wasi\_subscription\_t](#subscription) \*in + + The events to which to subscribe. + +- [\_\_wasi\_event\_t](#event) \*out + + The events that have occurred. + +- size\_t nsubscriptions + + Both the number of subscriptions and events. + +Outputs: + +- size\_t nevents + + The number of events stored. + +### `__wasi_proc_exit()` + +Terminate the process normally. An exit code of 0 indicates successful +termination of the program. The meanings of other values is dependent on +the environment. + +Note: This is similar to `_Exit` in POSIX. + +Inputs: + +- [\_\_wasi\_exitcode\_t](#exitcode) rval + + The exit code returned by the process. + +Does not return. + +### `__wasi_proc_raise()` + +Send a signal to the process of the calling thread. + +Note: This is similar to `raise` in POSIX. + +Inputs: + +- [\_\_wasi\_signal\_t](#signal) sig + + The signal condition to trigger. + +### `__wasi_random_get()` + +Write high-quality random data into a buffer. + +This function blocks when the implementation is unable to immediately +provide sufficient high-quality random data. + +This function may execute slowly, so when large mounts of random +data are required, it's advisable to use this function to seed a +pseudo-random number generator, rather than to provide the +random data directly. + +Inputs: + +- void \*buf and size\_t buf\_len + + The buffer to fill with random data. + +### `__wasi_sched_yield()` + +Temporarily yield execution of the calling thread. + +Note: This is similar to `sched_yield` in POSIX. + +### `__wasi_sock_recv()` + +Receive a message from a socket. + +Note: This is similar to `recv` in POSIX, though it also supports reading +the data into multiple buffers in the manner of `readv`. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to receive data. + +- const [\_\_wasi\_iovec\_t](#iovec) \*ri\_data and size\_t ri\_data\_len + + List of scatter/gather vectors to which to store data. + +- [\_\_wasi\_riflags\_t](#riflags) ri\_flags + + Message flags. + +Outputs: + +- size\_t ro\_datalen + + Number of bytes stored in [`ri_data`](#sock_recv.ri_data). + +- [\_\_wasi\_roflags\_t](#roflags) ro\_flags + + Message flags. + +### `__wasi_sock_send()` + +Send a message on a socket. + +Note: This is similar to `send` in POSIX, though it also supports writing +the data from multiple buffers in the manner of `writev`. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to send data. + +- const [\_\_wasi\_ciovec\_t](#ciovec) \*si\_data and size\_t si\_data\_len + + List of scatter/gather vectors to which to retrieve data + +- [\_\_wasi\_siflags\_t](#siflags) si\_flags + + Message flags. + +Outputs: + +- size\_t so\_datalen + + Number of bytes transmitted. + +### `__wasi_sock_shutdown()` + +Shut down socket send and receive channels. + +Note: This is similar to `shutdown` in POSIX. + +Inputs: + +- [\_\_wasi\_fd\_t](#fd) sock + + The socket on which to shutdown channels. + +- [\_\_wasi\_sdflags\_t](#sdflags) how + + Which channels on the socket to shut down. + +## Types + +### `__wasi_advice_t` (`uint8_t`) + +File or memory access pattern advisory information. + +Used by [`__wasi_fd_advise()`](#fd_advise). + +Possible values: + +- **`__WASI_ADVICE_DONTNEED`** + + The application expects that it will not access the + specified data in the near future. + +- **`__WASI_ADVICE_NOREUSE`** + + The application expects to access the specified data + once and then not reuse it thereafter. + +- **`__WASI_ADVICE_NORMAL`** + + The application has no advice to give on its behavior + with respect to the specified data. + +- **`__WASI_ADVICE_RANDOM`** + + The application expects to access the specified data + in a random order. + +- **`__WASI_ADVICE_SEQUENTIAL`** + + The application expects to access the specified data + sequentially from lower offsets to higher offsets. + +- **`__WASI_ADVICE_WILLNEED`** + + The application expects to access the specified data + in the near future. + +### `__wasi_ciovec_t` (`struct`) + +A region of memory for scatter/gather writes. + +Used by [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_write()`](#fd_write), and [`__wasi_sock_send()`](#sock_send). + +Members: + +- const void \*buf and size\_t buf\_len + + The address and length of the buffer to be written. + +### `__wasi_clockid_t` (`uint32_t`) + +Identifiers for clocks. + +Used by [`__wasi_subscription_t`](#subscription), [`__wasi_clock_res_get()`](#clock_res_get), and [`__wasi_clock_time_get()`](#clock_time_get). + +Possible values: + +- **`__WASI_CLOCK_MONOTONIC`** + + The store-wide monotonic clock, which is defined as a + clock measuring real time, whose value cannot be + adjusted and which cannot have negative clock jumps. + + The epoch of this clock is undefined. The absolute + time value of this clock therefore has no meaning. + +- **`__WASI_CLOCK_PROCESS_CPUTIME_ID`** + + The CPU-time clock associated with the current + process. + +- **`__WASI_CLOCK_REALTIME`** + + The clock measuring real time. Time value + zero corresponds with 1970-01-01T00:00:00Z. + +- **`__WASI_CLOCK_THREAD_CPUTIME_ID`** + + The CPU-time clock associated with the current thread. + +### `__wasi_device_t` (`uint64_t`) + +Identifier for a device containing a file system. Can be used +in combination with [`__wasi_inode_t`](#inode) to uniquely identify a file or +directory in the filesystem. + +Used by [`__wasi_filestat_t`](#filestat). + +### `__wasi_dircookie_t` (`uint64_t`) + +A reference to the offset of a directory entry. + +Used by [`__wasi_dirent_t`](#dirent) and [`__wasi_fd_readdir()`](#fd_readdir). + +Special values: + +- **`__WASI_DIRCOOKIE_START`** + + Permanent reference to the first directory entry + within a directory. + +### `__wasi_dirent_t` (`struct`) + +A directory entry. + +Members: + +- [\_\_wasi\_dircookie\_t](#dircookie) d\_next + + The offset of the next directory entry stored in this + directory. + +- [\_\_wasi\_inode\_t](#inode) d\_ino + + The serial number of the file referred to by this + directory entry. + +- uint32\_t d\_namlen + + The length of the name of the directory entry. + +- [\_\_wasi\_filetype\_t](#filetype) d\_type + + The type of the file referred to by this directory + entry. + +### `__wasi_errno_t` (`uint16_t`) + +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. + +Used by [`__wasi_event_t`](#event). + +Possible values: + +- **`__WASI_ESUCCESS`** + + No error occurred. System call completed successfully. + +- **`__WASI_E2BIG`** + + Argument list too long. + +- **`__WASI_EACCES`** + + Permission denied. + +- **`__WASI_EADDRINUSE`** + + Address in use. + +- **`__WASI_EADDRNOTAVAIL`** + + Address not available. + +- **`__WASI_EAFNOSUPPORT`** + + Address family not supported. + +- **`__WASI_EAGAIN`** + + Resource unavailable, or operation would block. + +- **`__WASI_EALREADY`** + + Connection already in progress. + +- **`__WASI_EBADF`** + + Bad file descriptor. + +- **`__WASI_EBADMSG`** + + Bad message. + +- **`__WASI_EBUSY`** + + Device or resource busy. + +- **`__WASI_ECANCELED`** + + Operation canceled. + +- **`__WASI_ECHILD`** + + No child processes. + +- **`__WASI_ECONNABORTED`** + + Connection aborted. + +- **`__WASI_ECONNREFUSED`** + + Connection refused. + +- **`__WASI_ECONNRESET`** + + Connection reset. + +- **`__WASI_EDEADLK`** + + Resource deadlock would occur. + +- **`__WASI_EDESTADDRREQ`** + + Destination address required. + +- **`__WASI_EDOM`** + + Mathematics argument out of domain of function. + +- **`__WASI_EDQUOT`** + + Reserved. + +- **`__WASI_EEXIST`** + + File exists. + +- **`__WASI_EFAULT`** + + Bad address. + +- **`__WASI_EFBIG`** + + File too large. + +- **`__WASI_EHOSTUNREACH`** + + Host is unreachable. + +- **`__WASI_EIDRM`** + + Identifier removed. + +- **`__WASI_EILSEQ`** + + Illegal byte sequence. + +- **`__WASI_EINPROGRESS`** + + Operation in progress. + +- **`__WASI_EINTR`** + + Interrupted function. + +- **`__WASI_EINVAL`** + + Invalid argument. + +- **`__WASI_EIO`** + + I/O error. + +- **`__WASI_EISCONN`** + + Socket is connected. + +- **`__WASI_EISDIR`** + + Is a directory. + +- **`__WASI_ELOOP`** + + Too many levels of symbolic links. + +- **`__WASI_EMFILE`** + + File descriptor value too large. + +- **`__WASI_EMLINK`** + + Too many links. + +- **`__WASI_EMSGSIZE`** + + Message too large. + +- **`__WASI_EMULTIHOP`** + + Reserved. + +- **`__WASI_ENAMETOOLONG`** + + Filename too long. + +- **`__WASI_ENETDOWN`** + + Network is down. + +- **`__WASI_ENETRESET`** + + Connection aborted by network. + +- **`__WASI_ENETUNREACH`** + + Network unreachable. + +- **`__WASI_ENFILE`** + + Too many files open in system. + +- **`__WASI_ENOBUFS`** + + No buffer space available. + +- **`__WASI_ENODEV`** + + No such device. + +- **`__WASI_ENOENT`** + + No such file or directory. + +- **`__WASI_ENOEXEC`** + + Executable file format error. + +- **`__WASI_ENOLCK`** + + No locks available. + +- **`__WASI_ENOLINK`** + + Reserved. + +- **`__WASI_ENOMEM`** + + Not enough space. + +- **`__WASI_ENOMSG`** + + No message of the desired type. + +- **`__WASI_ENOPROTOOPT`** + + Protocol not available. + +- **`__WASI_ENOSPC`** + + No space left on device. + +- **`__WASI_ENOSYS`** + + Function not supported. + +- **`__WASI_ENOTCONN`** + + The socket is not connected. + +- **`__WASI_ENOTDIR`** + + Not a directory or a symbolic link to a directory. + +- **`__WASI_ENOTEMPTY`** + + Directory not empty. + +- **`__WASI_ENOTRECOVERABLE`** + + State not recoverable. + +- **`__WASI_ENOTSOCK`** + + Not a socket. + +- **`__WASI_ENOTSUP`** + + Not supported, or operation not supported on socket. + +- **`__WASI_ENOTTY`** + + Inappropriate I/O control operation. + +- **`__WASI_ENXIO`** + + No such device or address. + +- **`__WASI_EOVERFLOW`** + + Value too large to be stored in data type. + +- **`__WASI_EOWNERDEAD`** + + Previous owner died. + +- **`__WASI_EPERM`** + + Operation not permitted. + +- **`__WASI_EPIPE`** + + Broken pipe. + +- **`__WASI_EPROTO`** + + Protocol error. + +- **`__WASI_EPROTONOSUPPORT`** + + Protocol not supported. + +- **`__WASI_EPROTOTYPE`** + + Protocol wrong type for socket. + +- **`__WASI_ERANGE`** + + Result too large. + +- **`__WASI_EROFS`** + + Read-only file system. + +- **`__WASI_ESPIPE`** + + Invalid seek. + +- **`__WASI_ESRCH`** + + No such process. + +- **`__WASI_ESTALE`** + + Reserved. + +- **`__WASI_ETIMEDOUT`** + + Connection timed out. + +- **`__WASI_ETXTBSY`** + + Text file busy. + +- **`__WASI_EXDEV`** + + Cross-device link. + +- **`__WASI_ENOTCAPABLE`** + + Extension: Capabilities insufficient. + +### `__wasi_event_t` (`struct`) + +An event that occurred. + +Used by [`__wasi_poll_oneoff()`](#poll_oneoff). + +Members: + +- [\_\_wasi\_userdata\_t](#userdata) userdata + + User-provided value that got attached to + [`__wasi_subscription_t::userdata`](#subscription.userdata). + +- [\_\_wasi\_errno\_t](#errno) error + + If non-zero, an error that occurred while processing + the subscription request. + +- [\_\_wasi\_eventtype\_t](#eventtype) type + + The type of the event that occurred. + +- When `type` is [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write): + + - **`u.fd_readwrite`** + + - [\_\_wasi\_filesize\_t](#filesize) nbytes + + The number of bytes available for reading or writing. + + - [\_\_wasi\_eventrwflags\_t](#eventrwflags) flags + + The state of the file descriptor. + +### `__wasi_eventrwflags_t` (`uint16_t` bitfield) + +The state of the file descriptor subscribed to with +[`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write). + +Used by [`__wasi_event_t`](#event). + +Possible values: + +- **`__WASI_EVENT_FD_READWRITE_HANGUP`** + + The peer of this socket has closed or disconnected. + +### `__wasi_eventtype_t` (`uint8_t`) + +Type of a subscription to an event or its occurrence. + +Used by [`__wasi_event_t`](#event) and [`__wasi_subscription_t`](#subscription). + +Possible values: + +- **`__WASI_EVENTTYPE_CLOCK`** + + The time value of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id) + has reached timestamp [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout). + +- **`__WASI_EVENTTYPE_FD_READ`** + + File descriptor [`__wasi_subscription_t::u.fd_readwrite.fd`](#subscription.u.fd_readwrite.fd) has + data available for reading. This event always triggers + for regular files. + +- **`__WASI_EVENTTYPE_FD_WRITE`** + + File descriptor [`__wasi_subscription_t::u.fd_readwrite.fd`](#subscription.u.fd_readwrite.fd) has + capacity available for writing. This event always + triggers for regular files. + +### `__wasi_exitcode_t` (`uint32_t`) + +Exit code generated by a process when exiting. + +Used by [`__wasi_proc_exit()`](#proc_exit). + +### `__wasi_fd_t` (`uint32_t`) + +A file descriptor number. + +Used by many functions in this API. + +As in POSIX, three file descriptor numbers are provided to instances +on startup -- 0, 1, and 2, (a.k.a. `STDIN_FILENO`, `STDOUT_FILENO`, +and `STDERR_FILENO`). + +Other than these, WASI implementations are not required to allocate +new file descriptors in ascending order. + +### `__wasi_fdflags_t` (`uint16_t` bitfield) + +File descriptor flags. + +Used by [`__wasi_fdstat_t`](#fdstat), [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_FDFLAG_APPEND`** + + Append mode: Data written to the file is always + appended to the file's end. + +- **`__WASI_FDFLAG_DSYNC`** + + Write according to synchronized I/O data integrity + completion. Only the data stored in the file is + synchronized. + +- **`__WASI_FDFLAG_NONBLOCK`** + + Non-blocking mode. + +- **`__WASI_FDFLAG_RSYNC`** + + Synchronized read I/O operations. + +- **`__WASI_FDFLAG_SYNC`** + + 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. + +### `__wasi_fdstat_t` (`struct`) + +File descriptor attributes. + +Used by [`__wasi_fd_fdstat_get()`](#fd_fdstat_get). + +Members: + +- [\_\_wasi\_filetype\_t](#filetype) fs\_filetype + + File type. + +- [\_\_wasi\_fdflags\_t](#fdflags) fs\_flags + + File descriptor flags. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_base + + Rights that apply to this file descriptor. + +- [\_\_wasi\_rights\_t](#rights) fs\_rights\_inheriting + + Maximum set of rights that may be installed on new + file descriptors that are created through this file + descriptor, e.g., through [`__wasi_path_open()`](#path_open). + +### `__wasi_filedelta_t` (`int64_t`) + +Relative offset within a file. + +Used by [`__wasi_fd_seek()`](#fd_seek). + +### `__wasi_filesize_t` (`uint64_t`) + +Non-negative file size or length of a region within a file. + +Used by [`__wasi_event_t`](#event), [`__wasi_filestat_t`](#filestat), [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_pwrite()`](#fd_pwrite), [`__wasi_fd_seek()`](#fd_seek), [`__wasi_path_tell()`](#path_tell), [`__wasi_fd_advise()`](#fd_advise), [`__wasi_fd_allocate()`](#fd_allocate), and [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size). + +### `__wasi_filestat_t` (`struct`) + +File attributes. + +Used by [`__wasi_fd_filestat_get()`](#fd_filestat_get) and [`__wasi_path_filestat_get()`](#path_filestat_get). + +Members: + +- [\_\_wasi\_device\_t](#device) st\_dev + + Device ID of device containing the file. + +- [\_\_wasi\_inode\_t](#inode) st\_ino + + File serial number. + +- [\_\_wasi\_filetype\_t](#filetype) st\_filetype + + File type. + +- [\_\_wasi\_linkcount\_t](#linkcount) st\_nlink + + Number of hard links to the file. + +- [\_\_wasi\_filesize\_t](#filesize) st\_size + + For regular files, the file size in bytes. For + symbolic links, the length in bytes of the pathname + contained in the symbolic link. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_atim + + Last data access timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_mtim + + Last data modification timestamp. + +- [\_\_wasi\_timestamp\_t](#timestamp) st\_ctim + + Last file status change timestamp. + +### `__wasi_filetype_t` (`uint8_t`) + +The type of a file descriptor or file. + +Used by [`__wasi_dirent_t`](#dirent), [`__wasi_fdstat_t`](#fdstat), and [`__wasi_filestat_t`](#filestat). + +Possible values: + +- **`__WASI_FILETYPE_UNKNOWN`** + + The type of the file descriptor or file is unknown or + is different from any of the other types specified. + +- **`__WASI_FILETYPE_BLOCK_DEVICE`** + + The file descriptor or file refers to a block device + inode. + +- **`__WASI_FILETYPE_CHARACTER_DEVICE`** + + The file descriptor or file refers to a character + device inode. + +- **`__WASI_FILETYPE_DIRECTORY`** + + The file descriptor or file refers to a directory + inode. + +- **`__WASI_FILETYPE_REGULAR_FILE`** + + The file descriptor or file refers to a regular file + inode. + +- **`__WASI_FILETYPE_SOCKET_DGRAM`** + + The file descriptor or file refers to a datagram + socket. + +- **`__WASI_FILETYPE_SOCKET_STREAM`** + + The file descriptor or file refers to a byte-stream + socket. + +- **`__WASI_FILETYPE_SYMBOLIC_LINK`** + + The file refers to a symbolic link inode. + +### `__wasi_fstflags_t` (`uint16_t` bitfield) + +Which file time attributes to adjust. + +Used by [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times) and [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +Possible values: + +- **`__WASI_FILESTAT_SET_ATIM`** + + Adjust the last data access timestamp to the value + stored in [`__wasi_filestat_t::st_atim`](#filestat.st_atim). + +- **`__WASI_FILESTAT_SET_ATIM_NOW`** + + Adjust the last data access timestamp to the time + of clock [`__WASI_CLOCK_REALTIME`](#clockid.realtime). + +- **`__WASI_FILESTAT_SET_MTIM`** + + Adjust the last data modification timestamp to the + value stored in [`__wasi_filestat_t::st_mtim`](#filestat.st_mtim). + +- **`__WASI_FILESTAT_SET_MTIM_NOW`** + + Adjust the last data modification timestamp to the + time of clock [`__WASI_CLOCK_REALTIME`](#clockid.realtime). + +### `__wasi_inode_t` (`uint64_t`) + +File serial number that is unique within its file system. + +Used by [`__wasi_dirent_t`](#dirent) and [`__wasi_filestat_t`](#filestat). + +### `__wasi_iovec_t` (`struct`) + +A region of memory for scatter/gather reads. + +Used by [`__wasi_fd_pread()`](#fd_pread), [`__wasi_fd_read()`](#fd_read), and [`__wasi_sock_recv()`](#sock_recv). + +Members: + +- void \*buf and size\_t buf\_len + + The address and length of the buffer to be filled. + +### `__wasi_linkcount_t` (`uint32_t`) + +Number of hard links to an inode. + +Used by [`__wasi_filestat_t`](#filestat). + +### `__wasi_lookupflags_t` (`uint32_t` bitfield) + +Flags determining the method of how paths are resolved. + +Used by [`__wasi_path_filestat_get()`](#path_filestat_get), [`__wasi_path_filestat_set_times()`](#path_filestat_set_times), [`__wasi_path_link()`](#path_link), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_LOOKUP_SYMLINK_FOLLOW`** + + As long as the resolved path corresponds to a symbolic + link, it is expanded. + +### `__wasi_oflags_t` (`uint16_t` bitfield) + +Open flags used by [`__wasi_path_open()`](#path_open). + +Used by [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_O_CREAT`** + + Create file if it does not exist. + +- **`__WASI_O_DIRECTORY`** + + Fail if not a directory. + +- **`__WASI_O_EXCL`** + + Fail if file already exists. + +- **`__WASI_O_TRUNC`** + + Truncate file to size 0. + +### `__wasi_riflags_t` (`uint16_t` bitfield) + +Flags provided to [`__wasi_sock_recv()`](#sock_recv). + +Used by [`__wasi_sock_recv()`](#sock_recv). + +Possible values: + +- **`__WASI_SOCK_RECV_PEEK`** + + Returns the message without removing it from the + socket's receive queue. + +- **`__WASI_SOCK_RECV_WAITALL`** + + On byte-stream sockets, block until the full amount + of data can be returned. + +### `__wasi_rights_t` (`uint64_t` bitfield) + +File descriptor rights, determining which actions may be +performed. + +Used by [`__wasi_fdstat_t`](#fdstat), [`__wasi_fd_fdstat_set_rights()`](#fd_fdstat_set_rights), and [`__wasi_path_open()`](#path_open). + +Possible values: + +- **`__WASI_RIGHT_FD_DATASYNC`** + + The right to invoke [`__wasi_fd_datasync()`](#fd_datasync). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_FDFLAG_DSYNC`](#fdflags.dsync). + +- **`__WASI_RIGHT_FD_READ`** + + The right to invoke [`__wasi_fd_read()`](#fd_read) and [`__wasi_sock_recv()`](#sock_recv). + + If [`__WASI_RIGHT_FD_SEEK`](#rights.fd_seek) is set, includes the right to invoke + [`__wasi_fd_pread()`](#fd_pread). + +- **`__WASI_RIGHT_FD_SEEK`** + + The right to invoke [`__wasi_fd_seek()`](#fd_seek). This flag implies + [`__WASI_RIGHT_FD_TELL`](#rights.fd_tell). + +- **`__WASI_RIGHT_FD_FDSTAT_SET_FLAGS`** + + The right to invoke [`__wasi_fd_fdstat_set_flags()`](#fd_fdstat_set_flags). + +- **`__WASI_RIGHT_FD_SYNC`** + + The right to invoke [`__wasi_fd_sync()`](#fd_sync). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_FDFLAG_RSYNC`](#fdflags.rsync) and + [`__WASI_FDFLAG_DSYNC`](#fdflags.dsync). + +- **`__WASI_RIGHT_FD_TELL`** + + The right to invoke [`__wasi_fd_seek()`](#fd_seek) in such a way that the + file offset remains unaltered (i.e., [`__WASI_WHENCE_CUR`](#whence.cur) with + offset zero), or to invoke [`__wasi_fd_tell()`](#fd_tell). + +- **`__WASI_RIGHT_FD_WRITE`** + + The right to invoke [`__wasi_fd_write()`](#fd_write) and [`__wasi_sock_send()`](#sock_send). + + If [`__WASI_RIGHT_FD_SEEK`](#rights.fd_seek) is set, includes the right to + invoke [`__wasi_fd_pwrite()`](#fd_pwrite). + +- **`__WASI_RIGHT_FD_ADVISE`** + + The right to invoke [`__wasi_fd_advise()`](#fd_advise). + +- **`__WASI_RIGHT_FD_ALLOCATE`** + + The right to invoke [`__wasi_fd_allocate()`](#fd_allocate). + +- **`__WASI_RIGHT_PATH_CREATE_DIRECTORY`** + + The right to invoke [`__wasi_path_create_directory()`](#path_create_directory). + +- **`__WASI_RIGHT_PATH_CREATE_FILE`** + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, the right to invoke + [`__wasi_path_open()`](#path_open) with [`__WASI_O_CREAT`](#oflags.creat). + +- **`__WASI_RIGHT_PATH_LINK_SOURCE`** + + The right to invoke [`__wasi_path_link()`](#path_link) with the file + descriptor as the source directory. + +- **`__WASI_RIGHT_PATH_LINK_TARGET`** + + The right to invoke [`__wasi_path_link()`](#path_link) with the file + descriptor as the target directory. + +- **`__WASI_RIGHT_PATH_OPEN`** + + The right to invoke [`__wasi_path_open()`](#path_open). + +- **`__WASI_RIGHT_FD_READDIR`** + + The right to invoke [`__wasi_fd_readdir()`](#fd_readdir). + +- **`__WASI_RIGHT_PATH_READLINK`** + + The right to invoke [`__wasi_path_readlink()`](#path_readlink). + +- **`__WASI_RIGHT_PATH_RENAME_SOURCE`** + + The right to invoke [`__wasi_path_rename()`](#path_rename) with the file + descriptor as the source directory. + +- **`__WASI_RIGHT_PATH_RENAME_TARGET`** + + The right to invoke [`__wasi_path_rename()`](#path_rename) with the file + descriptor as the target directory. + +- **`__WASI_RIGHT_PATH_FILESTAT_GET`** + + The right to invoke [`__wasi_path_filestat_get()`](#path_filestat_get). + +- **`__WASI_RIGHT_PATH_FILESTAT_SET_SIZE`** + + The right to change a file's size (there is no `__wasi_path_filestat_set_size()`). + + If [`__WASI_RIGHT_PATH_OPEN`](#rights.path_open) is set, includes the right to + invoke [`__wasi_path_open()`](#path_open) with [`__WASI_O_TRUNC`](#oflags.trunc). + +- **`__WASI_RIGHT_PATH_FILESTAT_SET_TIMES`** + + The right to invoke [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +- **`__WASI_RIGHT_FD_FILESTAT_GET`** + + The right to invoke [`__wasi_fd_filestat_get()`](#fd_filestat_get). + +- **`__WASI_RIGHT_FD_FILESTAT_SET_SIZE`** + + The right to invoke [`__wasi_fd_filestat_set_size()`](#fd_filestat_set_size). + +- **`__WASI_RIGHT_FD_FILESTAT_SET_TIMES`** + + The right to invoke [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times). + +- **`__WASI_RIGHT_PATH_SYMLINK`** + + The right to invoke [`__wasi_path_symlink()`](#path_symlink). + +- **`__WASI_RIGHT_PATH_UNLINK_FILE`** + + The right to invoke [`__wasi_path_unlink_file()`](#path_unlink_file). + +- **`__WASI_RIGHT_PATH_REMOVE_DIRECTORY`** + + The right to invoke [`__wasi_path_remove_directory()`](#path_remove_directory). + +- **`__WASI_RIGHT_POLL_FD_READWRITE`** + + If [`__WASI_RIGHT_FD_READ`](#rights.fd_read) is set, includes the right to + invoke [`__wasi_poll_oneoff()`](#poll_oneoff) to subscribe to [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read). + + If [`__WASI_RIGHT_FD_WRITE`](#rights.fd_write) is set, includes the right to + invoke [`__wasi_poll_oneoff()`](#poll_oneoff) to subscribe to [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write). + +- **`__WASI_RIGHT_SOCK_SHUTDOWN`** + + The right to invoke [`__wasi_sock_shutdown()`](#sock_shutdown). + +### `__wasi_roflags_t` (`uint16_t` bitfield) + +Flags returned by [`__wasi_sock_recv()`](#sock_recv). + +Used by [`__wasi_sock_recv()`](#sock_recv). + +Possible values: + +- **`__WASI_SOCK_RECV_DATA_TRUNCATED`** + + Returned by [`__wasi_sock_recv()`](#sock_recv): Message data has been + truncated. + +### `__wasi_sdflags_t` (`uint8_t` bitfield) + +Which channels on a socket to shut down. + +Used by [`__wasi_sock_shutdown()`](#sock_shutdown). + +Possible values: + +- **`__WASI_SHUT_RD`** + + Disables further receive operations. + +- **`__WASI_SHUT_WR`** + + Disables further send operations. + +### `__wasi_siflags_t` (`uint16_t` bitfield) + +Flags provided to [`__wasi_sock_send()`](#sock_send). As there are currently no flags +defined, it must be set to zero. + +Used by [`__wasi_sock_send()`](#sock_send). + +### `__wasi_signal_t` (`uint8_t`) + +Signal condition. + +Used by [`__wasi_proc_raise()`](#proc_raise). + +Possible values: + +- **`__WASI_SIGABRT`** + + Process abort signal. + + Action: Terminates the process. + +- **`__WASI_SIGALRM`** + + Alarm clock. + + Action: Terminates the process. + +- **`__WASI_SIGBUS`** + + Access to an undefined portion of a memory object. + + Action: Terminates the process. + +- **`__WASI_SIGCHLD`** + + Child process terminated, stopped, or continued. + + Action: Ignored. + +- **`__WASI_SIGCONT`** + + Continue executing, if stopped. + + Action: Continues executing, if stopped. + +- **`__WASI_SIGFPE`** + + Erroneous arithmetic operation. + + Action: Terminates the process. + +- **`__WASI_SIGHUP`** + + Hangup. + + Action: Terminates the process. + +- **`__WASI_SIGILL`** + + Illegal instruction. + + Action: Terminates the process. + +- **`__WASI_SIGINT`** + + Terminate interrupt signal. + + Action: Terminates the process. + +- **`__WASI_SIGKILL`** + + Kill. + + Action: Terminates the process. + +- **`__WASI_SIGPIPE`** + + Write on a pipe with no one to read it. + + Action: Ignored. + +- **`__WASI_SIGQUIT`** + + Terminal quit signal. + + Action: Terminates the process. + +- **`__WASI_SIGSEGV`** + + Invalid memory reference. + + Action: Terminates the process. + +- **`__WASI_SIGSTOP`** + + Stop executing. + + Action: Stops executing. + +- **`__WASI_SIGSYS`** + + Bad system call. + + Action: Terminates the process. + +- **`__WASI_SIGTERM`** + + Termination signal. + + Action: Terminates the process. + +- **`__WASI_SIGTRAP`** + + Trace/breakpoint trap. + + Action: Terminates the process. + +- **`__WASI_SIGTSTP`** + + Terminal stop signal. + + Action: Stops executing. + +- **`__WASI_SIGTTIN`** + + Background process attempting read. + + Action: Stops executing. + +- **`__WASI_SIGTTOU`** + + Background process attempting write. + + Action: Stops executing. + +- **`__WASI_SIGURG`** + + High bandwidth data is available at a socket. + + Action: Ignored. + +- **`__WASI_SIGUSR1`** + + User-defined signal 1. + + Action: Terminates the process. + +- **`__WASI_SIGUSR2`** + + User-defined signal 2. + + Action: Terminates the process. + +- **`__WASI_SIGVTALRM`** + + Virtual timer expired. + + Action: Terminates the process. + +- **`__WASI_SIGXCPU`** + + CPU time limit exceeded. + + Action: Terminates the process. + +- **`__WASI_SIGXFSZ`** + + File size limit exceeded. + + Action: Terminates the process. + +### `__wasi_subclockflags_t` (`uint16_t` bitfield) + +Flags determining how to interpret the timestamp provided in +[`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout). + +Used by [`__wasi_subscription_t`](#subscription). + +Possible values: + +- **`__WASI_SUBSCRIPTION_CLOCK_ABSTIME`** + + If set, treat the timestamp provided in + [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout) as an absolute timestamp + of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id). + + If clear, treat the timestamp provided in + [`__wasi_subscription_t::u.clock.timeout`](#subscription.u.clock.timeout) relative to the current + time value of clock [`__wasi_subscription_t::u.clock.clock_id`](#subscription.u.clock.clock_id). + +### `__wasi_subscription_t` (`struct`) + +Subscription to an event. + +Used by [`__wasi_poll_oneoff()`](#poll_oneoff). + +Members: + +- [\_\_wasi\_userdata\_t](#userdata) userdata + + User-provided value that is attached to the subscription in the + implementation and returned through + [`__wasi_event_t::userdata`](#event.userdata). + +- [\_\_wasi\_eventtype\_t](#eventtype) type + + The type of the event to which to subscribe. + +- When `type` is [`__WASI_EVENTTYPE_CLOCK`](#eventtype.u.clock): + + - **`u.clock`** + + - [\_\_wasi\_userdata\_t](#userdata) identifier + + The user-defined unique identifier of the clock. + + - [\_\_wasi\_clockid\_t](#clockid) clock\_id + + The clock against which to compare the timestamp. + + - [\_\_wasi\_timestamp\_t](#timestamp) timeout + + The absolute or relative timestamp. + + - [\_\_wasi\_timestamp\_t](#timestamp) precision + + The amount of time that the implementation may wait additionally + to coalesce with other events. + + - [\_\_wasi\_subclockflags\_t](#subclockflags) flags + + Flags specifying whether the timeout is absolute or relative. + +- When `type` is [`__WASI_EVENTTYPE_FD_READ`](#eventtype.fd_read) or [`__WASI_EVENTTYPE_FD_WRITE`](#eventtype.fd_write): + + - **`u.fd_readwrite`** + + - [\_\_wasi\_fd\_t](#fd) fd + + The file descriptor on which to wait for it to become ready + for reading or writing. + +### `__wasi_timestamp_t` (`uint64_t`) + +Timestamp in nanoseconds. + +Used by [`__wasi_filestat_t`](#filestat), [`__wasi_subscription_t`](#subscription), [`__wasi_clock_res_get()`](#clock_res_get), [`__wasi_clock_time_get()`](#clock_time_get), [`__wasi_fd_filestat_set_times()`](#fd_filestat_set_times), and [`__wasi_path_filestat_set_times()`](#path_filestat_set_times). + +### `__wasi_userdata_t` (`uint64_t`) + +User-provided value that may be attached to objects that is +retained when extracted from the implementation. + +Used by [`__wasi_event_t`](#event) and [`__wasi_subscription_t`](#subscription). + +### `__wasi_whence_t` (`uint8_t`) + +The position relative to which to set the offset of the file descriptor. + +Used by [`__wasi_fd_seek()`](#fd_seek). + +Possible values: + +- **`__WASI_WHENCE_CUR`** + + Seek relative to current position. + +- **`__WASI_WHENCE_END`** + + Seek relative to end-of-file. + +- **`__WASI_WHENCE_SET`** + + Seek relative to start-of-file. + diff --git a/phases/unstable/witx/typenames.witx b/phases/unstable/witx/typenames.witx new file mode 100644 index 00000000..51462bd6 --- /dev/null +++ b/phases/unstable/witx/typenames.witx @@ -0,0 +1,752 @@ +;; Type names used by low-level WASI interfaces. +;; +;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). +;; +;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md) +;; for an explanation of what that means. + +(typename $size_t u32) + +;; Non-negative file size or length of a region within a file. +(typename $filesize_t u64) + +;; Timestamp in nanoseconds. +(typename $timestamp_t u64) + +;; Identifiers for clocks. +(typename $clockid_t + (enum u32 + ;; The store-wide monotonic clock, which is defined as a clock measuring + ;; real time, whose value cannot be adjusted and which cannot have negative + ;; clock jumps. The epoch of this clock is undefined. The absolute time + ;; value of this clock therefore has no meaning. + $CLOCK_MONOTONIC + ;; The CPU-time clock associated with the current process. + $CLOCK_PROCESS_CPUTIME_ID + ;; The clock measuring real time. Time value zero corresponds with + ;; 1970-01-01T00:00:00Z. + $CLOCK_REALTIME + ;; The CPU-time clock associated with the current thread. + $CLOCK_THREAD_CPUTIME_ID + ) +) + +;; 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. +(typename $errno_t + (enum u16 + ;; No error occurred. System call completed successfully. + $ESUCCESS + ;; Argument list too long. + $E2BIG + ;; Permission denied. + $EACCES + ;; Address in use. + $EADDRINUSE + ;; Address not available. + $EADDRNOTAVAIL + ;; Address family not supported. + $EAFNOSUPPORT + ;; Resource unavailable, or operation would block. + $EAGAIN + ;; Connection already in progress. + $EALREADY + ;; Bad file descriptor. + $EBADF + ;; Bad message. + $EBADMSG + ;; Device or resource busy. + $EBUSY + ;; Operation canceled. + $ECANCELED + ;; No child processes. + $ECHILD + ;; Connection aborted. + $ECONNABORTED + ;; Connection refused. + $ECONNREFUSED + ;; Connection reset. + $ECONNRESET + ;; Resource deadlock would occur. + $EDEADLK + ;; Destination address required. + $EDESTADDRREQ + ;; Mathematics argument out of domain of function. + $EDOM + ;; Reserved. + $EDQUOT + ;; File exists. + $EEXIST + ;; Bad address. + $EFAULT + ;; File too large. + $EFBIG + ;; Host is unreachable. + $EHOSTUNREACH + ;; Identifier removed. + $EIDRM + ;; Illegal byte sequence. + $EILSEQ + ;; Operation in progress. + $EINPROGRESS + ;; Interrupted function. + $EINTR + ;; Invalid argument. + $EINVAL + ;; I/O error. + $EIO + ;; Socket is connected. + $EISCONN + ;; Is a directory. + $EISDIR + ;; Too many levels of symbolic links. + $ELOOP + ;; File descriptor value too large. + $EMFILE + ;; Too many links. + $EMLINK + ;; Message too large. + $EMSGSIZE + ;; Reserved. + $EMULTIHOP + ;; Filename too long. + $ENAMETOOLONG + ;; Network is down. + $ENETDOWN + ;; Connection aborted by network. + $ENETRESET + ;; Network unreachable. + $ENETUNREACH + ;; Too many files open in system. + $ENFILE + ;; No buffer space available. + $ENOBUFS + ;; No such device. + $ENODEV + ;; No such file or directory. + $ENOENT + ;; Executable file format error. + $ENOEXEC + ;; No locks available. + $ENOLCK + ;; Reserved. + $ENOLINK + ;; Not enough space. + $ENOMEM + ;; No message of the desired type. + $ENOMSG + ;; Protocol not available. + $ENOPROTOOPT + ;; No space left on device. + $ENOSPC + ;; Function not supported. + $ENOSYS + ;; The socket is not connected. + $ENOTCONN + ;; Not a directory or a symbolic link to a directory. + $ENOTDIR + ;; Directory not empty. + $ENOTEMPTY + ;; State not recoverable. + $ENOTRECOVERABLE + ;; Not a socket. + $ENOTSOCK + ;; Not supported, or operation not supported on socket. + $ENOTSUP + ;; Inappropriate I/O control operation. + $ENOTTY + ;; No such device or address. + $ENXIO + ;; Value too large to be stored in data type. + $EOVERFLOW + ;; Previous owner died. + $EOWNERDEAD + ;; Operation not permitted. + $EPERM + ;; Broken pipe. + $EPIPE + ;; Protocol error. + $EPROTO + ;; Protocol not supported. + $EPROTONOSUPPORT + ;; Protocol wrong type for socket. + $EPROTOTYPE + ;; Result too large. + $ERANGE + ;; Read-only file system. + $EROFS + ;; Invalid seek. + $ESPIPE + ;; No such process. + $ESRCH + ;; Reserved. + $ESTALE + ;; Connection timed out. + $ETIMEDOUT + ;; Text file busy. + $ETXTBSY + ;; Cross-device link. + $EXDEV + ;; Extension: Capabilities insufficient. + $ENOTCAPABLE + ) +) + +;; File descriptor rights, determining which actions may be performed. +(typename $rights_t + (flags u64 + ;; The right to invoke `fd_datasync`. + ;; + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;; `path_open` with `FDFLAG_DSYNC`. + (flag $RIGHT_FD_DATASYNC) + ;; The right to invoke `fd_read` and `sock_recv`. + ;; + ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pread`. + (flag $RIGHT_FD_READ) + ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + (flag $RIGHT_FD_SEEK) + ;; The right to invoke `fd_fdstat_set_flags`. + (flag $RIGHT_FD_FDSTAT_SET_FLAGS) + ;; The right to invoke `fd_sync`. + ;; + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke + ;; `path_open` with `FDFLAG_RSYNC` and `FDFLAG_DSYNC`. + (flag $RIGHT_FD_SYNC) + ;; The right to invoke `fd_seek` in such a way that the file offset + ;; remains unaltered (i.e., `WHENCE_CUR` with offset zero), or to + ;; invoke `fd_tell`. + (flag $RIGHT_FD_TELL) + ;; The right to invoke `fd_write` and `sock_send`. + ;; If `RIGHT_FD_SEEK` is set, includes the right to invoke `fd_pwrite`. + (flag $RIGHT_FD_WRITE) + ;; The right to invoke `fd_advise`. + (flag $RIGHT_FD_ADVISE) + ;; The right to invoke `fd_allocate`. + (flag $RIGHT_FD_ALLOCATE) + ;; The right to invoke `path_create_directory`. + (flag $RIGHT_PATH_CREATE_DIRECTORY) + ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + (flag $RIGHT_PATH_CREATE_FILE) + ;; The right to invoke `path_link` with the file descriptor as the + ;; source directory. + (flag $RIGHT_PATH_LINK_SOURCE) + ;; The right to invoke `path_link` with the file descriptor as the + ;; target directory. + (flag $RIGHT_PATH_LINK_TARGET) + ;; The right to invoke `path_open`. + (flag $RIGHT_PATH_OPEN) + ;; The right to invoke `fd_readdir`. + (flag $RIGHT_FD_READDIR) + ;; The right to invoke `path_readlink`. + (flag $RIGHT_PATH_READLINK) + ;; The right to invoke `path_rename` with the file descriptor as the source directory. + (flag $RIGHT_PATH_RENAME_SOURCE) + ;; The right to invoke `path_rename` with the file descriptor as the target directory. + (flag $RIGHT_PATH_RENAME_TARGET) + ;; The right to invoke `path_filestat_get`. + (flag $RIGHT_PATH_FILESTAT_GET) + ;; The right to change a file's size (there is no `path_filestat_set_size`). + ;; If `RIGHT_PATH_OPEN` is set, includes the right to invoke `path_open` with `O_TRUNC`. + (flag $RIGHT_PATH_FILESTAT_SET_SIZE) + ;; The right to invoke `path_filestat_set_times`. + (flag $RIGHT_PATH_FILESTAT_SET_TIMES) + ;; The right to invoke `fd_filestat_get`. + (flag $RIGHT_FD_FILESTAT_GET) + ;; The right to invoke `fd_filestat_set_size`. + (flag $RIGHT_FD_FILESTAT_SET_SIZE) + ;; The right to invoke `fd_filestat_set_times`. + (flag $RIGHT_FD_FILESTAT_SET_TIMES) + ;; The right to invoke `path_symlink`. + (flag $RIGHT_PATH_SYMLINK) + ;; The right to invoke `path_unlink_file`. + (flag $RIGHT_PATH_UNLINK_FILE) + ;; The right to invoke `path_remove_directory`. + (flag $RIGHT_PATH_REMOVE_DIRECTORY) + ;; If `RIGHT_FD_READ` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_READ`. + ;; If `RIGHT_FD_WRITE` is set, includes the right to invoke `poll_oneoff` to subscribe to `EVENTTYPE_FD_WRITE`. + (flag $RIGHT_POLL_FD_READWRITE) + ;; The right to invoke `sock_shutdown`. + (flag $RIGHT_SOCK_SHUTDOWN) + ) +) + +;; A file descriptor index. +(typename $fd_t u32) + +;; A region of memory for scatter/gather reads. +(typename $iovec_t + (struct + ;; The address of the buffer to be filled. + (field $buf (@witx pointer u8)) + ;; The length of the buffer to be filled. + (field $buf_len $size_t) + ) +) + +;; A region of memory for scatter/gather writes. +(typename $ciovec_t + (struct + ;; The address of the buffer to be written. + (field $buf (@witx const_pointer u8)) + ;; The length of the buffer to be written. + (field $buf_len $size_t) + ) +) + +(typename $iovec_t_array (array $iovec_t)) +(typename $ciovec_t_array (array $ciovec_t)) + +;; Relative offset within a file. +(typename $filedelta_t s64) + +;; The position relative to which to set the offset of the file descriptor. +(typename $whence_t + (enum u8 + ;; Seek relative to current position. + $WHENCE_CUR + ;; Seek relative to end-of-file. + $WHENCE_END + ;; Seek relative to start-of-file. + $WHENCE_SET + ) +) + +;; A reference to the offset of a directory entry. +(typename $dircookie_t u64) + +;; The type for the $d_namlen field of $dirent_t. +(typename $dirnamlen_t u32) + +;; File serial number that is unique within its file system. +(typename $inode_t u64) + +;; The type of a file descriptor or file. +(typename $filetype_t + (enum u8 + ;; The type of the file descriptor or file is unknown or is different from any of the other types specified. + $FILETYPE_UNKNOWN + ;; The file descriptor or file refers to a block device inode. + $FILETYPE_BLOCK_DEVICE + ;; The file descriptor or file refers to a character device inode. + $FILETYPE_CHARACTER_DEVICE + ;; The file descriptor or file refers to a directory inode. + $FILETYPE_DIRECTORY + ;; The file descriptor or file refers to a regular file inode. + $FILETYPE_REGULAR_FILE + ;; The file descriptor or file refers to a datagram socket. + $FILETYPE_SOCKET_DGRAM + ;; The file descriptor or file refers to a byte-stream socket. + $FILETYPE_SOCKET_STREAM + ;; The file refers to a symbolic link inode. + $FILETYPE_SYMBOLIC_LINK + ) +) + +;; A directory entry. +(typename $dirent_t + (struct + ;; The offset of the next directory entry stored in this directory. + (field $d_next $dircookie_t) + ;; The serial number of the file referred to by this directory entry. + (field $d_ino $inode_t) + ;; The length of the name of the directory entry. + (field $d_namlen $dirnamlen_t) + ;; The type of the file referred to by this directory entry. + (field $d_type $filetype_t) + ) +) + +;; File or memory access pattern advisory information. +(typename $advice_t + (enum u8 + ;; The application expects that it will not access the specified data in the near future. + $ADVICE_DONTNEED + ;; The application expects to access the specified data once and then not reuse it thereafter. + $ADVICE_NOREUSE + ;; The application has no advice to give on its behavior with respect to the specified data. + $ADVICE_NORMAL + ;; The application expects to access the specified data in a random order. + $ADVICE_RANDOM + ;; The application expects to access the specified data sequentially from lower offsets to higher offsets. + $ADVICE_SEQUENTIAL + ;; The application expects to access the specified data in the near future. + $ADVICE_WILLNEED + ) +) + +;; File descriptor flags. +(typename $fdflags_t + (flags u16 + ;; Append mode: Data written to the file is always appended to the file's end. + (flag $FDFLAG_APPEND) + ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + (flag $FDFLAG_DSYNC) + ;; Non-blocking mode. + (flag $FDFLAG_NONBLOCK) + ;; Synchronized read I/O operations. + (flag $FDFLAG_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. + (flag $FDFLAG_SYNC) + ) +) + +;; File descriptor attributes. +(typename $fdstat_t + (struct + ;; File type. + (field $fs_filetype $filetype_t) + ;; File descriptor flags. + (field $fs_flags $fdflags_t) + ;; Rights that apply to this file descriptor. + (field $fs_rights_base $rights_t) + ;; Maximum set of rights that may be installed on new file descriptors that + ;; are created through this file descriptor, e.g., through `path_open`. + (field $fs_rights_inheriting $rights_t) + ) +) + +;; Identifier for a device containing a file system. Can be used in combination +;; with `inode_t` to uniquely identify a file or directory in the filesystem. +(typename $device_t u64) + +;; Which file time attributes to adjust. +(typename $fstflags_t + (flags u16 + ;; Adjust the last data access timestamp to the value stored in `filestat_t::st_atim`. + (flag $FILESTAT_SET_ATIM) + ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + (flag $FILESTAT_SET_ATIM_NOW) + ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + (flag $FILESTAT_SET_MTIM) + ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + (flag $FILESTAT_SET_MTIM_NOW) + ) +) + +;; Flags determining the method of how paths are resolved. +(typename $lookupflags_t + (flags u32 + ;; As long as the resolved path corresponds to a symbolic link, it is expanded. + (flag $LOOKUP_SYMLINK_FOLLOW) + ) +) + +;; Open flags used by `path_open`. +(typename $oflags_t + (flags u16 + ;; Create file if it does not exist. + (flag $O_CREAT) + ;; Fail if not a directory. + (flag $O_DIRECTORY) + ;; Fail if file already exists. + (flag $O_EXCL) + ;; Truncate file to size 0. + (flag $O_TRUNC) + ) +) + +;; Number of hard links to an inode. +(typename $linkcount_t u32) + +;; File attributes. +(typename $filestat_t + (struct + ;; Device ID of device containing the file. + (field $st_dev $device_t) + ;; File serial number. + (field $st_ino $inode_t) + ;; File type. + (field $st_filetype $filetype_t) + ;; Number of hard links to the file. + (field $st_nlink $linkcount_t) + ;; For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. + (field $st_size $filesize_t) + ;; Last data access timestamp. + (field $st_atim $timestamp_t) + ;; Last data modification timestamp. + (field $st_mtim $timestamp_t) + ;; Last file status change timestamp. + (field $st_ctim $timestamp_t) + ) +) + +;; User-provided value that may be attached to objects that is retained when +;; extracted from the implementation. +(typename $userdata_t u64) + +;; Type of a subscription to an event or its occurrence. +(typename $eventtype_t + (flags u8 + ;; The time value of clock `subscription_t::u.clock.clock_id` has + ;; reached timestamp `subscription_t::u.clock.timeout`. + (flag $EVENTTYPE_CLOCK) + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;; available for reading. This event always triggers for regular files. + (flag $EVENTTYPE_FD_READ) + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;; available for writing. This event always triggers for regular files. + (flag $EVENTTYPE_FD_WRITE) + ) +) + +;; The state of the file descriptor subscribed to with +;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +(typename $eventrwflags_t + (flags u16 + ;; The peer of this socket has closed or disconnected. + (flag $EVENT_FD_READWRITE_HANGUP) + ) +) + +;; The contents of an $event_t when type is `EVENTTYPE_FD_READ` or +;; `EVENTTYPE_FD_WRITE`. +(typename $event_fd_readwrite_t + (struct + ;; The number of bytes available for reading or writing. + (field $nbytes $filesize_t) + ;; The state of the file descriptor. + (field $flags $eventrwflags_t) + ) +) + +;; The contents of an $event_t. +(typename $event_u + (union + ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + (field $fd_readwrite $event_fd_readwrite_t) + ) +) + +;; An event that occurred. +(typename $event_t + (struct + ;; User-provided value that got attached to `subscription_t::userdata`. + (field $userdata $userdata_t) + ;; If non-zero, an error that occurred while processing the subscription request. + (field $error $errno_t) + ;; The type of the event that occurred. + (field $type $eventtype_t) + ;; The contents of the event. + (field $u $event_u) + ) +) + +;; Flags determining how to interpret the timestamp provided in +;; `subscription_t::u.clock.timeout.` +(typename $subclockflags_t + (flags u16 + ;; If set, treat the timestamp provided in + ;; `subscription_t::u.clock.timeout` as an absolute timestamp of clock + ;; `subscription_t::u.clock.clock_id.` If clear, treat the timestamp + ;; provided in `subscription_t::u.clock.timeout` relative to the + ;; current time value of clock `subscription_t::u.clock.clock_id.` + (flag $SUBSCRIPTION_CLOCK_ABSTIME) + ) +) + +;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +(typename $subscription_clock_t + (struct + ;; The user-defined unique identifier of the clock. + (field $identifier $userdata_t) + ;; The clock against which to compare the timestamp. + (field $clock_id $clockid_t) + ;; The absolute or relative timestamp. + (field $timeout $timestamp_t) + ;; The amount of time that the implementation may wait additionally + ;; to coalesce with other events. + ;; + ;; Flags specifying whether the timeout is absolute or relative + (field $precision $timestamp_t) + ) +) + +;; The contents of a $subscription_t when type is type is +;; `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`. +(typename $subscription_fd_readwrite_t + (struct + ;; The file descriptor on which to wait for it to become ready for reading or writing. + (field $file_descriptor $fd_t) + ) +) + +;; The contents of a $subscription_t. +(typename $subscription_u + (union + ;; When type is `EVENTTYPE_CLOCK`: + (field $clock $subscription_clock_t) + ;; When type is `EVENTTYPE_FD_READ` or `EVENTTYPE_FD_WRITE`: + (field $fd_readwrite $subscription_fd_readwrite_t) + ) +) + +;; Subscription to an event. +(typename $subscription_t + (struct + ;; User-provided value that is attached to the subscription in the + ;; implementation and returned through `event_t::userdata`. + (field $userdata $userdata_t) + ;; The type of the event to which to subscribe. + (field $type $eventtype_t) + ;; The contents of the subscription. + (field $u $subscription_u) + ) +) + +;; Exit code generated by a process when exiting. +(typename $exitcode_t u32) + +;; Signal condition. +(typename $signal_t + (enum u8 + ;; Process abort signal. + ;; Action: Terminates the process. + $SIGABRT + ;; Alarm clock. + ;; Action: Terminates the process. + $SIGALRM + ;; Access to an undefined portion of a memory object. + ;; Action: Terminates the process. + $SIGBUS + ;; Child process terminated, stopped, or continued. + ;; Action: Ignored. + $SIGCHLD + ;; Continue executing, if stopped. + ;; Action: Continues executing, if stopped. + $SIGCONT + ;; Erroneous arithmetic operation. + ;; Action: Terminates the process. + $SIGFPE + ;; Hangup. + ;; Action: Terminates the process. + $SIGHUP + ;; Illegal instruction. + ;; Action: Terminates the process. + $SIGILL + ;; Terminate interrupt signal. + ;; Action: Terminates the process. + $SIGINT + ;; Kill. + ;; Action: Terminates the process. + $SIGKILL + ;; Write on a pipe with no one to read it. + ;; Action: Ignored. + $SIGPIPE + ;; Terminal quit signal. + ;; Action: Terminates the process. + $SIGQUIT + ;; Invalid memory reference. + ;; Action: Terminates the process. + $SIGSEGV + ;; Stop executing. + ;; Action: Stops executing. + $SIGSTOP + ;; Bad system call. + ;; Action: Terminates the process. + $SIGSYS + ;; Termination signal. + ;; Action: Terminates the process. + $SIGTERM + ;; Trace/breakpoint trap. + ;; Action: Terminates the process. + $SIGTRAP + ;; Terminal stop signal. + ;; Action: Stops executing. + $SIGTSTP + ;; Background process attempting read. + ;; Action: Stops executing. + $SIGTTIN + ;; Background process attempting write. + ;; Action: Stops executing. + $SIGTTOU + ;; High bandwidth data is available at a socket. + ;; Action: Ignored. + $SIGURG + ;; User-defined signal 1. + ;; Action: Terminates the process. + $SIGUSR1 + ;; User-defined signal 2. + ;; Action: Terminates the process. + $SIGUSR2 + ;; Virtual timer expired. + ;; Action: Terminates the process. + $SIGVTALRM + ;; CPU time limit exceeded. + ;; Action: Terminates the process. + $SIGXCPU + ;; File size limit exceeded. + ;; Action: Terminates the process. + $SIGXFSZ + ) +) + +;; Flags provided to `sock_recv`. +(typename $riflags_t + (flags u16 + ;; Returns the message without removing it from the socket's receive queue. + (flag $SOCK_RECV_PEEK) + ;; On byte-stream sockets, block until the full amount of data can be returned. + (flag $SOCK_RECV_WAITALL) + ) +) + +;; Flags returned by `sock_recv`. +(typename $roflags_t + (flags u16 + ;; Returned by `sock_recv`: Message data has been truncated. + (flag $SOCK_RECV_DATA_TRUNCATED) + ) +) + +;; Flags provided to `sock_send`. As there are currently no flags +;; defined, it must be set to zero. +(typename $siflags_t u16) + +;; Which channels on a socket to shut down. +(typename $sdflags_t + (flags u8 + ;; Disables further receive operations. + (flag $SHUT_RD) + ;; Disables further send operations. + (flag $SHUT_WR) + ) +) + +;; Identifiers for preopened capabilities. +(typename preopentype_t + (enum u8 + ;; A pre-opened directory. + $PREOPENTYPE_DIR + ) +) + +;; The contents of a $prestat_t when type is `PREOPENTYPE_DIR`. +(typename $prestat_dir + (struct + ;; The length of the directory name for use with `fd_prestat_dir_name`. + (field $pr_name_len $size_t) + ) +) + +;; The contents of an $prestat_t. +(typename $prestat_u + (union + ;; When type is `PREOPENTYPE_DIR`: + (field $dir $prestat_dir) + ) +) + +;; Information about a pre-opened capability. +(typename $prestat_t + (struct + ;; The type of the pre-opened capability. + (field $pr_type $preopentype_t) + ;; The contents of the information. + (field $u $prestat_u) + ) +) diff --git a/phases/unstable/witx/wasi_unstable_preview0.witx b/phases/unstable/witx/wasi_unstable_preview0.witx new file mode 100644 index 00000000..08efc87f --- /dev/null +++ b/phases/unstable/witx/wasi_unstable_preview0.witx @@ -0,0 +1,526 @@ +;; WASI Preview. This is an evolution of the API that WASI initially +;; launched with. +;; +;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi). +;; +;; This is a `witx` file. See [here](https://github.com/WebAssembly/WASI/tree/master/docs/witx.md) +;; for an explanation of what that means. + +(use "typenames.witx") + +(module $wasi_unstable_preview0 + ;; Linear memory to be accessed by WASI functions that need it. + (import "memory" (memory)) + + ;; Read command-line argument data. + ;; The size of the array should match that returned by `wasi_args_sizes_get()` + (@interface func (export "args_get") + (param $argv (@witx pointer (@witx pointer u8))) + (param $argv_buf (@witx pointer u8)) + (result $error $errno_t) + ) + ;; Return command-line argument data sizes. + (@interface func (export "args_sizes_get") + (result $error $errno_t) + ;; The number of arguments. + (result $argc $size_t) + ;; The size of the argument string data. + (result $argv_buf_size $size_t) + ) + + ;; Read environment variable data. + ;; The sizes of the buffers should match that returned by `environ.sizes_get()`. + (@interface func (export "environ_get") + (param $environ (@witx pointer (@witx pointer u8))) + (param $environ_buf (@witx pointer u8)) + (result $error $errno_t) + ) + ;; Return command-line argument data sizes. + (@interface func (export "environ_sizes_get") + ;; The number of arguments. + (result $argc $size_t) + ;; The size of the argument string data. + (result $argv_buf_size $size_t) + ) + + ;; Return the resolution of a clock. + ;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return `WASI_EINVAL` + ;; Note: This is similar to `clock_getres` in POSIX. + (@interface func (export "clock_res_get") + (result $error $errno_t) + ;; The clock for which to return the resolution. + (param $clock_id $clockid_t) + ;; The resolution of the clock. + (result $resolution $timestamp_t) + ) + ;; Return the time value of a clock. + ;; Note: This is similar to `clock_gettime` in POSIX. + (@interface func (export "clock_time_get") + ;; The clock for which to return the time. + (param $clock_id $clockid_t) + ;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value. + (param $precision $timestamp_t) + (result $error $errno_t) + ;; The time value of the clock. + (result $time $timestamp_t) + ) + + ;; Provide file advisory information on a file descriptor. + ;; Note: This is similar to `posix_fadvise` in POSIX. + (@interface func (export "fd_advise") + (param $fd $fd_t) + (param $offset $filesize_t) ;; The offset within the file to which the advisory applies. + (param $len $filesize_t) ;; The length of the region to which the advisory applies. + (param $advice $advice_t) ;; The advice. + (result $error $errno_t) + ) + + ;; Force the allocation of space in a file. + ;; Note: This is similar to `posix_fallocate` in POSIX. + (@interface func (export "fd_allocate") + (param $fd $fd_t) + ;; The offset at which to start the allocation. + (param $offset $filesize_t) + ;; The length of the area that is allocated. + (param $len $filesize_t) + (result $error $errno_t) + ) + + ;; Close a file descriptor. + ;; Note: This is similar to `close` in POSIX. + (@interface func (export "fd_close") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Synchronize the data of a file to disk. + ;; Note: This is similar to `fdatasync` in POSIX. + (@interface func (export "fd_datasync") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Get the attributes of a file descriptor. + ;; Note: This returns similar flags to `fsync(fd, F_GETFL)` in POSIX, as well as additional fields. + (@interface func (export "fd_fdstat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the file descriptor's attributes are stored. + (result $stat $fdstat_t) + ) + + ;; Adjust the flags associated with a file descriptor. + ;; Note: This is similar to `fcntl(fd, F_SETFL, flags)` in POSIX. + (@interface func (export "fd_fdstat_set_flags") + (param $fd $fd_t) + ;; The desired values of the file descriptor flags. + (param $flags $fdflags_t) + (result $error $errno_t) + ) + + ;; Adjust the rights associated with a file descriptor. + ;; This can only be used to remove rights, and returns `ENOTCAPABLE` if called in a way that would attempt to add rights + (@interface func (export "fd_fdstat_set_rights") + (param $fd $fd_t) + ;; The desired rights of the file descriptor. + (param $fs_rights_base $rights_t) + (param $fs_rights_inheriting $rights_t) + (result $error $errno_t) + ) + + ;; Return the attributes of an open file. + (@interface func (export "fd_filestat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the file's attributes are stored. + (result $fs_rights_base $rights_t) + ) + + ;; Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. + ;; Note: This is similar to `ftruncate` in POSIX. + (@interface func (export "fd_filestat_set_size") + (param $fd $fd_t) + ;; The desired file size. + (param $st_size $filesize_t) + (result $error $errno_t) + ) + + ;; Adjust the timestamps of an open file or directory. + ;; Note: This is similar to `futimens` in POSIX. + (@interface func (export "fd_filestat_set_times") + (param $fd $fd_t) + ;; The desired values of the data access timestamp. + (param $st_atim $timestamp_t) + ;; The desired values of the data modification timestamp. + (param $st_mtim $timestamp_t) + ;; A bitmask indicating which timestamps to adjust. + (param $fst_flags $fstflags_t) + (result $error $errno_t) + ) + + ;; Read from a file descriptor, without using and updating the file descriptor's offset. + ;; Note: This is similar to `preadv` in POSIX. + (@interface func (export "fd_pread") + (param $fd $fd_t) + ;; List of scatter/gather vectors in which to store data. + (param $iovs $iovec_t_array) + ;; The offset within the file at which to read. + (param $offset $filesize_t) + (result $error $errno_t) + ;; The number of bytes read. + (result $nread $size_t) + ) + + ;; Return a description of the given preopened file descriptor. + (@interface func (export "fd_prestat_get") + (param $fd $fd_t) + (result $error $errno_t) + ;; The buffer where the description is stored. + (result $buf $prestat_t) + ) + + ;; Return a description of the given preopened file descriptor. + (@interface func (export "fd_prestat_dir_name") + (param $fd $fd_t) + ;; A buffer into which to write the preopened directory name. + (param $path (@witx pointer u8)) + (param $path_len $size_t) + (result $error $errno_t) + ) + + ;; Write to a file descriptor, without using and updating the file descriptor's offset. + ;; Note: This is similar to `pwritev` in POSIX. + (@interface func (export "fd_pwrite") + (param $fd $fd_t) + ;; List of scatter/gather vectors from which to retrieve data. + (param $iovs $ciovec_t_array) + ;; The offset within the file at which to write. + (param $offset $filesize_t) + (result $error $errno_t) + ;; The number of bytes written. + (result $nwritten $size_t) + ) + + ;; Read from a file descriptor. + ;; Note: This is similar to `readv` in POSIX. + (@interface func (export "fd_read") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to store data. + (param $iovs $iovec_t_array) + (result $error $errno_t) + ;; The number of bytes read. + (result $nread $size_t) + ) + + ;; 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_t object, + ;; followed by dirent_t::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. + (@interface func (export "fd_readdir") + (param $fd $fd_t) + ;; The buffer where directory entries are stored + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + ;; The location within the directory to start reading + (param $cookie $dircookie_t) + (result $error $errno_t) + ;; 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. + (result $bufused $size_t) + ) + + ;; Atomically replace a file descriptor by renumbering another file descriptor. + ;; + ;; Due to the strong focus on thread safety, this environment does not provide + ;; a mechanism to duplicate or renumber a file descriptor to an arbitrary + ;; number, like `dup2()`. This would be prone to race conditions, as an actual + ;; file descriptor with the same number could be allocated by a different + ;; thread at the same time. + ;; + ;; This function provides a way to atomically renumber file descriptors, which + ;; would disappear if `dup2()` were to be removed entirely. + (@interface func (export "fd_renumber") + (param $fd $fd_t) + ;; The file descriptor to overwrite. + (param $to $fd_t) + (result $error $errno_t) + ) + + ;; Move the offset of a file descriptor. + ;; Note: This is similar to `lseek` in POSIX. + (@interface func (export "fd_seek") + (param $fd $fd_t) + ;; The number of bytes to move. + (param $offset $filedelta_t) + ;; The base from which the offset is relative. + (param $whence $whence_t) + (result $error $errno_t) + ;; The new offset of the file descriptor, relative to the start of the file. + (result $newoffset $filesize_t) + ) + + ;; Synchronize the data and metadata of a file to disk. + ;; Note: This is similar to `fsync` in POSIX. + (@interface func (export "fd_sync") + (param $fd $fd_t) + (result $error $errno_t) + ) + + ;; Return the current offset of a file descriptor. + ;; Note: This is similar to `lseek(fd, 0, SEEK_CUR)` in POSIX. + (@interface func (export "fd_tell") + (param $fd $fd_t) + (result $error $errno_t) + ;; The current offset of the file descriptor, relative to the start of the file. + (result $offset $filesize_t) + ) + + ;; Write to a file descriptor. + ;; Note: This is similar to `writev` in POSIX. + (@interface func (export "fd_write") + (param $fd $fd_t) + ;; List of scatter/gather vectors from which to retrieve data. + (param $iovs $ciovec_t_array) + (result $error $errno_t) + ;; The number of bytes written. + (result $nwritten $size_t) + ) + + ;; Create a directory. + ;; Note: This is similar to `mkdirat` in POSIX. + (@interface func (export "path_create_directory") + (param $fd $fd_t) + ;; The path at which to create the directory. + (param $path string) + (result $error $errno_t) + ) + + ;; Return the attributes of a file or directory. + ;; Note: This is similar to `stat` in POSIX. + (@interface func (export "path_filestat_get") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $flags $lookupflags_t) + ;; The path of the file or directory to inspect. + (param $path string) + (result $error $errno_t) + ;; The buffer where the file's attributes are stored. + (result $buf $filestat_t) + ) + + ;; Adjust the timestamps of a file or directory. + ;; Note: This is similar to `utimensat` in POSIX. + (@interface func (export "path_filestat_set_times") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $flags $lookupflags_t) + ;; The path of the file or directory to operate on. + (param $path string) + ;; The desired values of the data access timestamp. + (param $st_atim $timestamp_t) + ;; The desired values of the data modification timestamp. + (param $st_mtim $timestamp_t) + ;; A bitmask indicating which timestamps to adjust. + (param $fst_flags $fstflags_t) + (result $error $errno_t) + ) + + ;; Create a hard link. + ;; Note: This is similar to `linkat` in POSIX. + (@interface func (export "path_link") + (param $old_fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $old_flags $lookupflags_t) + ;; The source path from which to link. + (param $old_path string) + ;; The working directory at which the resolution of the new path starts. + (param $new_fd $fd_t) + ;; The destination path at which to create the hard link. + (param $new_path string) + (result $error $errno_t) + ) + + ;; Open a file or directory. + ;; + ;; The returned file descriptor is not guaranteed to be the lowest-numbered + ;; file 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 file descriptor is + ;; guaranteed to be less than 2**31. + ;; + ;; Note: This is similar to `openat` in POSIX. + (@interface func (export "path_open") + (param $fd $fd_t) + ;; Flags determining the method of how the path is resolved. + (param $dirflags $lookupflags_t) + ;; The relative path of the file or directory to open, relative to the + ;; `dirfd` directory. + (param $path string) + ;; The method by which to open the file. + (param $o_flags $oflags_t) + ;; The initial rights of the newly created file descriptor. The + ;; implementation is allowed to return a file descriptor with fewer rights + ;; than specified, if and only if those rights do not apply to the type of + ;; file being opened. + ;; + ;; The base rights are rights that will apply to operations using the file + ;; descriptor itself, while the inheriting rights are rights that apply to + ;; file descriptors derived from it. + (param $fs_rights_base $rights_t) + (param $fs_rights_inherting $rights_t) + (result $error $errno_t) + ;; The file descriptor of the file that has been opened. + (result $opened_fd $fd_t) + ) + + ;; Read the contents of a symbolic link. + ;; Note: This is similar to `readlinkat` in POSIX. + (@interface func (export "path_readlink") + (param $fd $fd_t) + ;; The path of the symbolic link from which to read. + (param $path string) + ;; The buffer to which to write the contents of the symbolic link. + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + (result $error $errno_t) + ;; The number of bytes placed in the buffer. + (result $bufused $size_t) + ) + + ;; Remove a directory. + ;; Return `ENOTEMPTY` if the directory is not empty. + ;; Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + (@interface func (export "path_remove_directory") + (param $fd $fd_t) + ;; The path to a directory to remove. + (param $path string) + (result $error $errno_t) + ) + + ;; Rename a file or directory. + ;; Note: This is similar to `renameat` in POSIX. + (@interface func (export "path_rename") + (param $fd $fd_t) + ;; The source path of the file or directory to rename. + (param $old_path string) + ;; The working directory at which the resolution of the new path starts. + (param $new_fd $fd_t) + ;; The destination path to which to rename the file or directory. + (param $new_path string) + (result $error $errno_t) + ) + + ;; Create a symbolic link. + ;; Note: This is similar to `symlinkat` in POSIX. + (@interface func (export "path_symlink") + (param $fd $fd_t) + ;; The contents of the symbolic link. + (param $old_path string) + ;; The destination path at which to create the symbolic link. + (param $new_path string) + (result $error $errno_t) + ) + + + ;; Unlink a file. + ;; Return `EISDIR` if the path refers to a directory. + ;; Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + (@interface func (export "path_unlink_file") + (param $fd $fd_t) + ;; The path to a file to unlink. + (param $path string) + (result $error $errno_t) + ) + + ;; Concurrently poll for the occurrence of a set of events. + (@interface func (export "poll_oneoff") + ;; The events to which to subscribe. + (param $in (@witx const_pointer $subscription_t)) + ;; The events that have occurred. + (param $out (@witx pointer $event_t)) + ;; Both the number of subscriptions and events. + (param $nsubscriptions $size_t) + (result $error $errno_t) + ;; The number of events stored. + (result $nevents $size_t) + ) + + ;; Terminate the process normally. An exit code of 0 indicates successful + ;; termination of the program. The meanings of other values is dependent on + ;; the environment. + (@interface func (export "proc_exit") + ;; The exit code returned by the process. + (param $rval $exitcode_t) + ) + + ;; Send a signal to the process of the calling thread. + ;; Note: This is similar to `raise` in POSIX. + (@interface func (export "proc_raise") + ;; The signal condition to trigger. + (param $sig $signal_t) + (result $error $errno_t) + ) + + ;; Temporarily yield execution of the calling thread. + ;; Note: This is similar to `sched_yield` in POSIX. + (@interface func (export "proc_sched_yield") + (result $error $errno_t) + ) + + ;; Write high-quality random data into a buffer. + ;; This function blocks when the implementation is unable to immediately + ;; provide sufficient high-quality random data. + ;; This function may execute slowly, so when large mounts of random data are + ;; required, it's advisable to use this function to seed a pseudo-random + ;; number generator, rather than to provide the random data directly. + (@interface func (export "random_get") + ;; The buffer to fill with random data. + (param $buf (@witx pointer u8)) + (param $buf_len $size_t) + (result $error $errno_t) + ) + + ;; Receive a message from a socket. + ;; Note: This is similar to `recv` in POSIX, though it also supports reading + ;; the data into multiple buffers in the manner of `readv`. + (@interface func (export "sock_recv") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to store data. + (param $ri_data $iovec_t_array) + ;; Message flags. + (param $ri_flags $riflags_t) + (result $error $errno_t) + ;; Number of bytes stored in ri_data. + (result $ro_datalen $size_t) + ;; Message flags. + (result $ro_flags $roflags_t) + ) + + ;; Send a message on a socket. + ;; Note: This is similar to `send` in POSIX, though it also supports writing + ;; the data from multiple buffers in the manner of `writev`. + (@interface func (export "sock_send") + (param $fd $fd_t) + ;; List of scatter/gather vectors to which to retrieve data + (param $si_data $ciovec_t_array) + ;; Message flags. + (param $si_flags $siflags_t) + (result $error $errno_t) + ;; Number of bytes transmitted. + (result $so_datalen $size_t) + ) + + ;; Shut down socket send and receive channels. + ;; Note: This is similar to `shutdown` in POSIX. + (@interface func (export "sock_shutdown") + (param $fd $fd_t) + ;; Which channels on the socket to shut down. + (param $how $sdflags_t) + (result $error $errno_t) + ) +) From cf83f179f58f2d17e8cffea813def906c3c4719e Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Fri, 13 Sep 2019 10:29:56 -0700 Subject: [PATCH 2/2] Apply the validation fix from #90 to the new copies. --- phases/old/witx/typenames.witx | 2 +- phases/unstable/witx/typenames.witx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/phases/old/witx/typenames.witx b/phases/old/witx/typenames.witx index 51462bd6..e04a188d 100644 --- a/phases/old/witx/typenames.witx +++ b/phases/old/witx/typenames.witx @@ -718,7 +718,7 @@ ) ;; Identifiers for preopened capabilities. -(typename preopentype_t +(typename $preopentype_t (enum u8 ;; A pre-opened directory. $PREOPENTYPE_DIR diff --git a/phases/unstable/witx/typenames.witx b/phases/unstable/witx/typenames.witx index 51462bd6..e04a188d 100644 --- a/phases/unstable/witx/typenames.witx +++ b/phases/unstable/witx/typenames.witx @@ -718,7 +718,7 @@ ) ;; Identifiers for preopened capabilities. -(typename preopentype_t +(typename $preopentype_t (enum u8 ;; A pre-opened directory. $PREOPENTYPE_DIR