From 8d70aa89eacde10ff19549553751948d2fdf0b73 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 12:50:34 -0800 Subject: [PATCH 1/7] archive: contents of `old` moved underneath `snapshot_0` The contents of `old` are identical to the current `unstable/wasi_unstable_preview0` in every sense except the name of the module and file. So, for this snapshotting, rather than move the contents of the current "unstable" (which will be renamed "snapshot" as part of this PR) under a new directory under phases/old, we're just moving the current contents under a directory, so that future snapshots can be archived without changing these paths. --- phases/old/{ => snapshot_0}/docs/wasi_unstable.md | 0 phases/old/{ => snapshot_0}/witx/typenames.witx | 0 phases/old/{ => snapshot_0}/witx/wasi_unstable.witx | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename phases/old/{ => snapshot_0}/docs/wasi_unstable.md (100%) rename phases/old/{ => snapshot_0}/witx/typenames.witx (100%) rename phases/old/{ => snapshot_0}/witx/wasi_unstable.witx (100%) diff --git a/phases/old/docs/wasi_unstable.md b/phases/old/snapshot_0/docs/wasi_unstable.md similarity index 100% rename from phases/old/docs/wasi_unstable.md rename to phases/old/snapshot_0/docs/wasi_unstable.md diff --git a/phases/old/witx/typenames.witx b/phases/old/snapshot_0/witx/typenames.witx similarity index 100% rename from phases/old/witx/typenames.witx rename to phases/old/snapshot_0/witx/typenames.witx diff --git a/phases/old/witx/wasi_unstable.witx b/phases/old/snapshot_0/witx/wasi_unstable.witx similarity index 100% rename from phases/old/witx/wasi_unstable.witx rename to phases/old/snapshot_0/witx/wasi_unstable.witx From 420cab367be26700861f9be32bdce4cbf27218c9 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 12:56:29 -0800 Subject: [PATCH 2/7] delete current unstable (snapshot), rather than move it under old. Special case of this first-time snapshotting process. --- .../unstable/docs/wasi_unstable_preview0.md | 2343 ----------------- phases/unstable/witx/typenames.witx | 767 ------ .../unstable/witx/wasi_unstable_preview0.witx | 528 ---- 3 files changed, 3638 deletions(-) delete mode 100644 phases/unstable/docs/wasi_unstable_preview0.md delete mode 100644 phases/unstable/witx/typenames.witx delete mode 100644 phases/unstable/witx/wasi_unstable_preview0.witx diff --git a/phases/unstable/docs/wasi_unstable_preview0.md b/phases/unstable/docs/wasi_unstable_preview0.md deleted file mode 100644 index 2464f2342..000000000 --- a/phases/unstable/docs/wasi_unstable_preview0.md +++ /dev/null @@ -1,2343 +0,0 @@ - - -# 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_NORMAL`** - - The application has no advice to give on its behavior - with respect to the specified data. - -- **`__WASI_ADVICE_SEQUENTIAL`** - - The application expects to access the specified data - sequentially from lower offsets to higher offsets. - -- **`__WASI_ADVICE_RANDOM`** - - The application expects to access the specified data - in a random order. - -- **`__WASI_ADVICE_WILLNEED`** - - The application expects to access the specified data - in the near future. - -- **`__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_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_REALTIME`** - - The clock measuring real time. Time value - zero corresponds with 1970-01-01T00:00:00Z. - -- **`__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_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_REMOVE_DIRECTORY`** - - The right to invoke [`__wasi_path_remove_directory()`](#path_remove_directory). - -- **`__WASI_RIGHT_PATH_UNLINK_FILE`** - - The right to invoke [`__wasi_path_unlink_file()`](#path_unlink_file). - -- **`__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_SIGHUP`** - - Hangup. - - Action: Terminates the process. - -- **`__WASI_SIGINT`** - - Terminate interrupt signal. - - Action: Terminates the process. - -- **`__WASI_SIGQUIT`** - - Terminal quit signal. - - Action: Terminates the process. - -- **`__WASI_SIGILL`** - - Illegal instruction. - - Action: Terminates the process. - -- **`__WASI_SIGTRAP`** - - Trace/breakpoint trap. - - Action: Terminates the process. - -- **`__WASI_SIGABRT`** - - Process abort signal. - - Action: Terminates the process. - -- **`__WASI_SIGBUS`** - - Access to an undefined portion of a memory object. - - Action: Terminates the process. - -- **`__WASI_SIGFPE`** - - Erroneous arithmetic operation. - - Action: Terminates the process. - -- **`__WASI_SIGKILL`** - - Kill. - - Action: Terminates the process. - -- **`__WASI_SIGUSR1`** - - User-defined signal 1. - - Action: Terminates the process. - -- **`__WASI_SIGSEGV`** - - Invalid memory reference. - - Action: Terminates the process. - -- **`__WASI_SIGUSR2`** - - User-defined signal 2. - - Action: Terminates the process. - -- **`__WASI_SIGPIPE`** - - Write on a pipe with no one to read it. - - Action: Ignored. - -- **`__WASI_SIGALRM`** - - Alarm clock. - - Action: Terminates the process. - -- **`__WASI_SIGTERM`** - - Termination signal. - - 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_SIGSTOP`** - - Stop executing. - - Action: Stops executing. - -- **`__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_SIGXCPU`** - - CPU time limit exceeded. - - Action: Terminates the process. - -- **`__WASI_SIGXFSZ`** - - File size limit exceeded. - - Action: Terminates the process. - -- **`__WASI_SIGVTALRM`** - - Virtual timer expired. - - Action: Terminates the process. - -- **`__WASI_SIGPROF`** - - Profiling timer expired. - - Action: Terminates the process. - -- **`__WASI_SIGWINCH`** - - Window changed. - - Action: Ignored. - -- **`__WASI_SIGPOLL`** - - I/O possible. - - Action: Terminates the process. - -- **`__WASI_SIGPWR`** - - Power failure. - - Action: Terminates the process. - -- **`__WASI_SIGSYS`** - - Bad system call. - - 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 deleted file mode 100644 index 15b53af51..000000000 --- a/phases/unstable/witx/typenames.witx +++ /dev/null @@ -1,767 +0,0 @@ -;; 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 clock measuring real time. Time value zero corresponds with - ;; 1970-01-01T00:00:00Z. - $CLOCK_REALTIME - ;; 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 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`. - $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`. - $RIGHT_FD_READ - ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. - $RIGHT_FD_SEEK - ;; The right to invoke `fd_fdstat_set_flags`. - $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`. - $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`. - $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`. - $RIGHT_FD_WRITE - ;; The right to invoke `fd_advise`. - $RIGHT_FD_ADVISE - ;; The right to invoke `fd_allocate`. - $RIGHT_FD_ALLOCATE - ;; The right to invoke `path_create_directory`. - $RIGHT_PATH_CREATE_DIRECTORY - ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. - $RIGHT_PATH_CREATE_FILE - ;; The right to invoke `path_link` with the file descriptor as the - ;; source directory. - $RIGHT_PATH_LINK_SOURCE - ;; The right to invoke `path_link` with the file descriptor as the - ;; target directory. - $RIGHT_PATH_LINK_TARGET - ;; The right to invoke `path_open`. - $RIGHT_PATH_OPEN - ;; The right to invoke `fd_readdir`. - $RIGHT_FD_READDIR - ;; The right to invoke `path_readlink`. - $RIGHT_PATH_READLINK - ;; The right to invoke `path_rename` with the file descriptor as the source directory. - $RIGHT_PATH_RENAME_SOURCE - ;; The right to invoke `path_rename` with the file descriptor as the target directory. - $RIGHT_PATH_RENAME_TARGET - ;; The right to invoke `path_filestat_get`. - $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`. - $RIGHT_PATH_FILESTAT_SET_SIZE - ;; The right to invoke `path_filestat_set_times`. - $RIGHT_PATH_FILESTAT_SET_TIMES - ;; The right to invoke `fd_filestat_get`. - $RIGHT_FD_FILESTAT_GET - ;; The right to invoke `fd_filestat_set_size`. - $RIGHT_FD_FILESTAT_SET_SIZE - ;; The right to invoke `fd_filestat_set_times`. - $RIGHT_FD_FILESTAT_SET_TIMES - ;; The right to invoke `path_symlink`. - $RIGHT_PATH_SYMLINK - ;; The right to invoke `path_remove_directory`. - $RIGHT_PATH_REMOVE_DIRECTORY - ;; The right to invoke `path_unlink_file`. - $RIGHT_PATH_UNLINK_FILE - ;; 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`. - $RIGHT_POLL_FD_READWRITE - ;; The right to invoke `sock_shutdown`. - $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 has no advice to give on its behavior with respect to the specified data. - $ADVICE_NORMAL - ;; 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 a random order. - $ADVICE_RANDOM - ;; The application expects to access the specified data in the near future. - $ADVICE_WILLNEED - ;; 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 - ) -) - -;; File descriptor flags. -(typename $fdflags_t - (flags u16 - ;; Append mode: Data written to the file is always appended to the file's end. - $FDFLAG_APPEND - ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. - $FDFLAG_DSYNC - ;; Non-blocking mode. - $FDFLAG_NONBLOCK - ;; Synchronized read I/O operations. - $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. - $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`. - $FILESTAT_SET_ATIM - ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. - $FILESTAT_SET_ATIM_NOW - ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. - $FILESTAT_SET_MTIM - ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. - $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. - $LOOKUP_SYMLINK_FOLLOW - ) -) - -;; Open flags used by `path_open`. -(typename $oflags_t - (flags u16 - ;; Create file if it does not exist. - $O_CREAT - ;; Fail if not a directory. - $O_DIRECTORY - ;; Fail if file already exists. - $O_EXCL - ;; Truncate file to size 0. - $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 - (enum u8 - ;; The time value of clock `subscription_t::u.clock.clock_id` has - ;; reached timestamp `subscription_t::u.clock.timeout`. - $EVENTTYPE_CLOCK - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data - ;; available for reading. This event always triggers for regular files. - $EVENTTYPE_FD_READ - ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity - ;; available for writing. This event always triggers for regular files. - $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. - $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.` - $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. - (field $precision $timestamp_t) - ;; Flags specifying whether the timeout is absolute or relative - (field $flags $subclockflags_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 - ;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, - ;; so this value is reserved. - $SIGNONE - ;; Hangup. - ;; Action: Terminates the process. - $SIGHUP - ;; Terminate interrupt signal. - ;; Action: Terminates the process. - $SIGINT - ;; Terminal quit signal. - ;; Action: Terminates the process. - $SIGQUIT - ;; Illegal instruction. - ;; Action: Terminates the process. - $SIGILL - ;; Trace/breakpoint trap. - ;; Action: Terminates the process. - $SIGTRAP - ;; Process abort signal. - ;; Action: Terminates the process. - $SIGABRT - ;; Access to an undefined portion of a memory object. - ;; Action: Terminates the process. - $SIGBUS - ;; Erroneous arithmetic operation. - ;; Action: Terminates the process. - $SIGFPE - ;; Kill. - ;; Action: Terminates the process. - $SIGKILL - ;; User-defined signal 1. - ;; Action: Terminates the process. - $SIGUSR1 - ;; Invalid memory reference. - ;; Action: Terminates the process. - $SIGSEGV - ;; User-defined signal 2. - ;; Action: Terminates the process. - $SIGUSR2 - ;; Write on a pipe with no one to read it. - ;; Action: Ignored. - $SIGPIPE - ;; Alarm clock. - ;; Action: Terminates the process. - $SIGALRM - ;; Termination signal. - ;; Action: Terminates the process. - $SIGTERM - ;; Child process terminated, stopped, or continued. - ;; Action: Ignored. - $SIGCHLD - ;; Continue executing, if stopped. - ;; Action: Continues executing, if stopped. - $SIGCONT - ;; Stop executing. - ;; Action: Stops executing. - $SIGSTOP - ;; 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 - ;; CPU time limit exceeded. - ;; Action: Terminates the process. - $SIGXCPU - ;; File size limit exceeded. - ;; Action: Terminates the process. - $SIGXFSZ - ;; Virtual timer expired. - ;; Action: Terminates the process. - $SIGVTALRM - ;; Profiling timer expired. - ;; Action: Terminates the process. - $SIGPROF - ;; Window changed. - ;; Action: Ignored. - $SIGWINCH - ;; I/O possible. - ;; Action: Terminates the process. - $SIGPOLL - ;; Power failure. - ;; Action: Terminates the process. - $SIGPWR - ;; Bad system call. - ;; Action: Terminates the process. - $SIGSYS - ) -) - -;; Flags provided to `sock_recv`. -(typename $riflags_t - (flags u16 - ;; Returns the message without removing it from the socket's receive queue. - $SOCK_RECV_PEEK - ;; On byte-stream sockets, block until the full amount of data can be returned. - $SOCK_RECV_WAITALL - ) -) - -;; Flags returned by `sock_recv`. -(typename $roflags_t - (flags u16 - ;; Returned by `sock_recv`: Message data has been truncated. - $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. - $SHUT_RD - ;; Disables further send operations. - $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 deleted file mode 100644 index d5686dabb..000000000 --- a/phases/unstable/witx/wasi_unstable_preview0.witx +++ /dev/null @@ -1,528 +0,0 @@ -;; 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") - (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) - ) - - ;; 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 $buf $filestat_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) - (param $flags $fdflags_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") - ;; The contents of the symbolic link. - (param $old_path string) - (param $fd $fd_t) - ;; 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 "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 2302a0e1a97b461d556a765dd49663075d1c511a Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 12:57:29 -0800 Subject: [PATCH 3/7] copy phases/ephemeral/* into phases/snapshot/ --- .../snapshot/docs/wasi_ephemeral_preview.md | 2351 +++++++++++++++++ phases/snapshot/witx/typenames.witx | 767 ++++++ .../snapshot/witx/wasi_ephemeral_preview.witx | 528 ++++ 3 files changed, 3646 insertions(+) create mode 100644 phases/snapshot/docs/wasi_ephemeral_preview.md create mode 100644 phases/snapshot/witx/typenames.witx create mode 100644 phases/snapshot/witx/wasi_ephemeral_preview.witx diff --git a/phases/snapshot/docs/wasi_ephemeral_preview.md b/phases/snapshot/docs/wasi_ephemeral_preview.md new file mode 100644 index 000000000..6de15f1d2 --- /dev/null +++ b/phases/snapshot/docs/wasi_ephemeral_preview.md @@ -0,0 +1,2351 @@ + + +# 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. + +Inputs: + +- char \*\*argv + + A pointer to a buffer to write the argument pointers. + + The count of elements for the buffer should be at least the value of `argc` returned by [`__wasi_args_sizes_get()`](#args_sizes_get). + + The caller of `__wasi_args_get()` is responsible for allocating an additional element for a terminating NULL pointer, if necessary. + +- char \*argv\_buf + + A pointer to a buffer to write the argument string data. + + The size of this buffer should be the value of `argv_buf_size` returned by [`__wasi_args_sizes_get()`](#args_sizes_get). + +### `__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. + +Inputs: + +- char \*\*environ + + A pointer to a buffer to write the environment variable pointers. + + The count of elements for the buffer should be at least the value of `environ_count` returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get). + + The caller of `__wasi_environ_get()` is responsible for allocating an additional element for a terminating NULL pointer, if necessary. + +- char \*environ\_buf + + A pointer to a buffer to write the environment variable string data. + + The size of this buffer should be the value of `environ_buf_size` returned by [`__wasi_environ_sizes_get()`](#environ_sizes_get). + +### `__wasi_environ_sizes_get()` + +Return enviroment variable 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_NORMAL`** + + The application has no advice to give on its behavior + with respect to the specified data. + +- **`__WASI_ADVICE_SEQUENTIAL`** + + The application expects to access the specified data + sequentially from lower offsets to higher offsets. + +- **`__WASI_ADVICE_RANDOM`** + + The application expects to access the specified data + in a random order. + +- **`__WASI_ADVICE_WILLNEED`** + + The application expects to access the specified data + in the near future. + +- **`__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_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_REALTIME`** + + The clock measuring real time. Time value + zero corresponds with 1970-01-01T00:00:00Z. + +- **`__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_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` (`uint64_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_REMOVE_DIRECTORY`** + + The right to invoke [`__wasi_path_remove_directory()`](#path_remove_directory). + +- **`__WASI_RIGHT_PATH_UNLINK_FILE`** + + The right to invoke [`__wasi_path_unlink_file()`](#path_unlink_file). + +- **`__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_SIGHUP`** + + Hangup. + + Action: Terminates the process. + +- **`__WASI_SIGINT`** + + Terminate interrupt signal. + + Action: Terminates the process. + +- **`__WASI_SIGQUIT`** + + Terminal quit signal. + + Action: Terminates the process. + +- **`__WASI_SIGILL`** + + Illegal instruction. + + Action: Terminates the process. + +- **`__WASI_SIGTRAP`** + + Trace/breakpoint trap. + + Action: Terminates the process. + +- **`__WASI_SIGABRT`** + + Process abort signal. + + Action: Terminates the process. + +- **`__WASI_SIGBUS`** + + Access to an undefined portion of a memory object. + + Action: Terminates the process. + +- **`__WASI_SIGFPE`** + + Erroneous arithmetic operation. + + Action: Terminates the process. + +- **`__WASI_SIGKILL`** + + Kill. + + Action: Terminates the process. + +- **`__WASI_SIGUSR1`** + + User-defined signal 1. + + Action: Terminates the process. + +- **`__WASI_SIGSEGV`** + + Invalid memory reference. + + Action: Terminates the process. + +- **`__WASI_SIGUSR2`** + + User-defined signal 2. + + Action: Terminates the process. + +- **`__WASI_SIGPIPE`** + + Write on a pipe with no one to read it. + + Action: Ignored. + +- **`__WASI_SIGALRM`** + + Alarm clock. + + Action: Terminates the process. + +- **`__WASI_SIGTERM`** + + Termination signal. + + 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_SIGSTOP`** + + Stop executing. + + Action: Stops executing. + +- **`__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_SIGXCPU`** + + CPU time limit exceeded. + + Action: Terminates the process. + +- **`__WASI_SIGXFSZ`** + + File size limit exceeded. + + Action: Terminates the process. + +- **`__WASI_SIGVTALRM`** + + Virtual timer expired. + + Action: Terminates the process. + +- **`__WASI_SIGPROF`** + + Profiling timer expired. + + Action: Terminates the process. + +- **`__WASI_SIGWINCH`** + + Window changed. + + Action: Ignored. + +- **`__WASI_SIGPOLL`** + + I/O possible. + + Action: Terminates the process. + +- **`__WASI_SIGPWR`** + + Power failure. + + Action: Terminates the process. + +- **`__WASI_SIGSYS`** + + Bad system call. + + 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_SET`** + + Seek relative to start-of-file. + +- **`__WASI_WHENCE_CUR`** + + Seek relative to current position. + +- **`__WASI_WHENCE_END`** + + Seek relative to end-of-file. + diff --git a/phases/snapshot/witx/typenames.witx b/phases/snapshot/witx/typenames.witx new file mode 100644 index 000000000..1a45be1fd --- /dev/null +++ b/phases/snapshot/witx/typenames.witx @@ -0,0 +1,767 @@ +;; 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 clock measuring real time. Time value zero corresponds with + ;; 1970-01-01T00:00:00Z. + $CLOCK_REALTIME + ;; 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 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`. + $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`. + $RIGHT_FD_READ + ;; The right to invoke `fd_seek`. This flag implies `RIGHT_FD_TELL`. + $RIGHT_FD_SEEK + ;; The right to invoke `fd_fdstat_set_flags`. + $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`. + $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`. + $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`. + $RIGHT_FD_WRITE + ;; The right to invoke `fd_advise`. + $RIGHT_FD_ADVISE + ;; The right to invoke `fd_allocate`. + $RIGHT_FD_ALLOCATE + ;; The right to invoke `path_create_directory`. + $RIGHT_PATH_CREATE_DIRECTORY + ;; If `RIGHT_PATH_OPEN` is set, the right to invoke `path_open` with `O_CREAT`. + $RIGHT_PATH_CREATE_FILE + ;; The right to invoke `path_link` with the file descriptor as the + ;; source directory. + $RIGHT_PATH_LINK_SOURCE + ;; The right to invoke `path_link` with the file descriptor as the + ;; target directory. + $RIGHT_PATH_LINK_TARGET + ;; The right to invoke `path_open`. + $RIGHT_PATH_OPEN + ;; The right to invoke `fd_readdir`. + $RIGHT_FD_READDIR + ;; The right to invoke `path_readlink`. + $RIGHT_PATH_READLINK + ;; The right to invoke `path_rename` with the file descriptor as the source directory. + $RIGHT_PATH_RENAME_SOURCE + ;; The right to invoke `path_rename` with the file descriptor as the target directory. + $RIGHT_PATH_RENAME_TARGET + ;; The right to invoke `path_filestat_get`. + $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`. + $RIGHT_PATH_FILESTAT_SET_SIZE + ;; The right to invoke `path_filestat_set_times`. + $RIGHT_PATH_FILESTAT_SET_TIMES + ;; The right to invoke `fd_filestat_get`. + $RIGHT_FD_FILESTAT_GET + ;; The right to invoke `fd_filestat_set_size`. + $RIGHT_FD_FILESTAT_SET_SIZE + ;; The right to invoke `fd_filestat_set_times`. + $RIGHT_FD_FILESTAT_SET_TIMES + ;; The right to invoke `path_symlink`. + $RIGHT_PATH_SYMLINK + ;; The right to invoke `path_remove_directory`. + $RIGHT_PATH_REMOVE_DIRECTORY + ;; The right to invoke `path_unlink_file`. + $RIGHT_PATH_UNLINK_FILE + ;; 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`. + $RIGHT_POLL_FD_READWRITE + ;; The right to invoke `sock_shutdown`. + $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 start-of-file. + $WHENCE_SET + ;; Seek relative to current position. + $WHENCE_CUR + ;; Seek relative to end-of-file. + $WHENCE_END + ) +) + +;; A reference to the offset of a directory entry. +;; +;; The value 0 signifies the start of the directory. +(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 has no advice to give on its behavior with respect to the specified data. + $ADVICE_NORMAL + ;; 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 a random order. + $ADVICE_RANDOM + ;; The application expects to access the specified data in the near future. + $ADVICE_WILLNEED + ;; 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 + ) +) + +;; File descriptor flags. +(typename $fdflags_t + (flags u16 + ;; Append mode: Data written to the file is always appended to the file's end. + $FDFLAG_APPEND + ;; Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized. + $FDFLAG_DSYNC + ;; Non-blocking mode. + $FDFLAG_NONBLOCK + ;; Synchronized read I/O operations. + $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. + $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`. + $FILESTAT_SET_ATIM + ;; Adjust the last data access timestamp to the time of clock `CLOCK_REALTIME`. + $FILESTAT_SET_ATIM_NOW + ;; Adjust the last data modification timestamp to the value stored in `filestat_t::st_mtim`. + $FILESTAT_SET_MTIM + ;; Adjust the last data modification timestamp to the time of clock `CLOCK_REALTIME`. + $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. + $LOOKUP_SYMLINK_FOLLOW + ) +) + +;; Open flags used by `path_open`. +(typename $oflags_t + (flags u16 + ;; Create file if it does not exist. + $O_CREAT + ;; Fail if not a directory. + $O_DIRECTORY + ;; Fail if file already exists. + $O_EXCL + ;; Truncate file to size 0. + $O_TRUNC + ) +) + +;; Number of hard links to an inode. +(typename $linkcount_t u64) + +;; 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 + (enum u8 + ;; The time value of clock `subscription_t::u.clock.clock_id` has + ;; reached timestamp `subscription_t::u.clock.timeout`. + $EVENTTYPE_CLOCK + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has data + ;; available for reading. This event always triggers for regular files. + $EVENTTYPE_FD_READ + ;; File descriptor `subscription_t::u.fd_readwrite.fd` has capacity + ;; available for writing. This event always triggers for regular files. + $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. + $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.` + $SUBSCRIPTION_CLOCK_ABSTIME + ) +) + +;; The contents of a $subscription_t when type is `EVENTTYPE_CLOCK`. +(typename $subscription_clock_t + (struct + ;; 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. + (field $precision $timestamp_t) + ;; Flags specifying whether the timeout is absolute or relative + (field $flags $subclockflags_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 + ;; No signal. Note that POSIX has special semantics for `kill(pid, 0)`, + ;; so this value is reserved. + $SIGNONE + ;; Hangup. + ;; Action: Terminates the process. + $SIGHUP + ;; Terminate interrupt signal. + ;; Action: Terminates the process. + $SIGINT + ;; Terminal quit signal. + ;; Action: Terminates the process. + $SIGQUIT + ;; Illegal instruction. + ;; Action: Terminates the process. + $SIGILL + ;; Trace/breakpoint trap. + ;; Action: Terminates the process. + $SIGTRAP + ;; Process abort signal. + ;; Action: Terminates the process. + $SIGABRT + ;; Access to an undefined portion of a memory object. + ;; Action: Terminates the process. + $SIGBUS + ;; Erroneous arithmetic operation. + ;; Action: Terminates the process. + $SIGFPE + ;; Kill. + ;; Action: Terminates the process. + $SIGKILL + ;; User-defined signal 1. + ;; Action: Terminates the process. + $SIGUSR1 + ;; Invalid memory reference. + ;; Action: Terminates the process. + $SIGSEGV + ;; User-defined signal 2. + ;; Action: Terminates the process. + $SIGUSR2 + ;; Write on a pipe with no one to read it. + ;; Action: Ignored. + $SIGPIPE + ;; Alarm clock. + ;; Action: Terminates the process. + $SIGALRM + ;; Termination signal. + ;; Action: Terminates the process. + $SIGTERM + ;; Child process terminated, stopped, or continued. + ;; Action: Ignored. + $SIGCHLD + ;; Continue executing, if stopped. + ;; Action: Continues executing, if stopped. + $SIGCONT + ;; Stop executing. + ;; Action: Stops executing. + $SIGSTOP + ;; 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 + ;; CPU time limit exceeded. + ;; Action: Terminates the process. + $SIGXCPU + ;; File size limit exceeded. + ;; Action: Terminates the process. + $SIGXFSZ + ;; Virtual timer expired. + ;; Action: Terminates the process. + $SIGVTALRM + ;; Profiling timer expired. + ;; Action: Terminates the process. + $SIGPROF + ;; Window changed. + ;; Action: Ignored. + $SIGWINCH + ;; I/O possible. + ;; Action: Terminates the process. + $SIGPOLL + ;; Power failure. + ;; Action: Terminates the process. + $SIGPWR + ;; Bad system call. + ;; Action: Terminates the process. + $SIGSYS + ) +) + +;; Flags provided to `sock_recv`. +(typename $riflags_t + (flags u16 + ;; Returns the message without removing it from the socket's receive queue. + $SOCK_RECV_PEEK + ;; On byte-stream sockets, block until the full amount of data can be returned. + $SOCK_RECV_WAITALL + ) +) + +;; Flags returned by `sock_recv`. +(typename $roflags_t + (flags u16 + ;; Returned by `sock_recv`: Message data has been truncated. + $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. + $SHUT_RD + ;; Disables further send operations. + $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/snapshot/witx/wasi_ephemeral_preview.witx b/phases/snapshot/witx/wasi_ephemeral_preview.witx new file mode 100644 index 000000000..f98ff129b --- /dev/null +++ b/phases/snapshot/witx/wasi_ephemeral_preview.witx @@ -0,0 +1,528 @@ +;; 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") + (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) + ) + + ;; 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 $buf $filestat_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) + (param $flags $fdflags_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") + ;; The contents of the symbolic link. + (param $old_path string) + (param $fd $fd_t) + ;; 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 "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 3dffd94b825b4c9d4a9639620a50ecb55f18d7e1 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 13:01:46 -0800 Subject: [PATCH 4/7] rename files in snapshot to snapshot_preview1 --- .../{wasi_ephemeral_preview.md => wasi_unstable_preview1.md} | 0 ...{wasi_ephemeral_preview.witx => wasi_snapshot_preview1.witx} | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename phases/snapshot/docs/{wasi_ephemeral_preview.md => wasi_unstable_preview1.md} (100%) rename phases/snapshot/witx/{wasi_ephemeral_preview.witx => wasi_snapshot_preview1.witx} (99%) diff --git a/phases/snapshot/docs/wasi_ephemeral_preview.md b/phases/snapshot/docs/wasi_unstable_preview1.md similarity index 100% rename from phases/snapshot/docs/wasi_ephemeral_preview.md rename to phases/snapshot/docs/wasi_unstable_preview1.md diff --git a/phases/snapshot/witx/wasi_ephemeral_preview.witx b/phases/snapshot/witx/wasi_snapshot_preview1.witx similarity index 99% rename from phases/snapshot/witx/wasi_ephemeral_preview.witx rename to phases/snapshot/witx/wasi_snapshot_preview1.witx index f98ff129b..630537416 100644 --- a/phases/snapshot/witx/wasi_ephemeral_preview.witx +++ b/phases/snapshot/witx/wasi_snapshot_preview1.witx @@ -8,7 +8,7 @@ (use "typenames.witx") -(module $wasi_ephemeral_preview +(module $wasi_snapshot_preview1 ;; Linear memory to be accessed by WASI functions that need it. (import "memory" (memory)) From 39ba594657d8e85ccaef4aef5bc2755ac7d199ef Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 13:08:20 -0800 Subject: [PATCH 5/7] update phases/README to rename `unstable` to `snapshot` Per https://github.com/WebAssembly/WASI/issues/138 and discussion on 07nov19 wasi video call. Updates the steps for PR based on what I did for this first snapshot. --- phases/README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/phases/README.md b/phases/README.md index 53cb649bb..4fbbd888a 100644 --- a/phases/README.md +++ b/phases/README.md @@ -8,22 +8,30 @@ 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 +- [`snapshot`](snapshot): Usable APIs. APIs in `ephemeral` will be + occasionally snapshotted and promoted into `snapshot`, 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. + 1. `git mv` contents of `phases/snapshot/` to + `phases/old/snapshot_{old_snapshot_number}`. + 2. `cp -R` contents of `phases/ephemeral/` into `phases/snapshot/`. + 3. Rename files copied into `phases/snapshot/` to substitute `ephemeral` + for `snapshot` in file names. Append the new snapshot number to each + name. + 4. Update module names given in `.witx` files according to the previous + step. + 5. Update tests in `tools/witx/tests/wasi.rs` to point at new snapshot, and + add a test pointing at the just-archived snapshot under `old`. + 6. Optionally, under `phases/old/snapshot_{old_snapshot_number}, add + polyfills for suberseded APIs using the new APIs. + Pull Requests may also add additional tests, documentation, or - polyfills for existing `unstable` APIs. + polyfills for existing `snapshot` APIs. - [`old`](old): When APIs in `current` spec are replaced by new versions, the old API modules are moved to the `old` directory. When @@ -44,7 +52,7 @@ flexibility. 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 +`snapshot` 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 From c89c82b44a984f8d0d848574ccffbf17a01e17f2 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Fri, 8 Nov 2019 13:15:48 -0800 Subject: [PATCH 6/7] witx: tests point at newly snapshotted and archived witx specs and the test file gets renamed to just regular wasi.rs --- tools/witx/tests/{wasi_unstable.rs => wasi.rs} | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) rename tools/witx/tests/{wasi_unstable.rs => wasi.rs} (65%) diff --git a/tools/witx/tests/wasi_unstable.rs b/tools/witx/tests/wasi.rs similarity index 65% rename from tools/witx/tests/wasi_unstable.rs rename to tools/witx/tests/wasi.rs index 68e65186a..2b2566997 100644 --- a/tools/witx/tests/wasi_unstable.rs +++ b/tools/witx/tests/wasi.rs @@ -2,15 +2,15 @@ use std::path::Path; use witx; #[test] -fn validate_wasi_unstable_preview0() { +fn validate_wasi_snapshot() { witx::load(Path::new( - "../../phases/unstable/witx/wasi_unstable_preview0.witx", + "../../phases/snapshot/witx/wasi_snapshot_preview1.witx", )) .unwrap_or_else(|e| panic!("failed to parse: {}", e)); } #[test] -fn validate_wasi_ephemeral_preview() { +fn validate_wasi_ephemeral() { witx::load(Path::new( "../../phases/ephemeral/witx/wasi_ephemeral_preview.witx", )) @@ -18,15 +18,17 @@ fn validate_wasi_ephemeral_preview() { } #[test] -fn validate_wasi_old_preview0() { - witx::load(Path::new("../../phases/old/witx/wasi_unstable.witx")) - .unwrap_or_else(|e| panic!("failed to parse: {}", e)); +fn validate_wasi_old_snapshot_0() { + witx::load(Path::new( + "../../phases/old/snapshot_0/witx/wasi_unstable.witx", + )) + .unwrap_or_else(|e| panic!("failed to parse: {}", e)); } #[test] fn render_roundtrip() { let doc = witx::load(Path::new( - "../../phases/unstable/witx/wasi_unstable_preview0.witx", + "../../phases/snapshot/witx/wasi_snapshot_preview1.witx", )) .unwrap_or_else(|e| panic!("failed to parse: {}", e)); From c5b51c4c31592e4d7a919a18d89da4c808511548 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Mon, 11 Nov 2019 16:01:14 -0800 Subject: [PATCH 7/7] fixes in phases readme per dan's code review --- phases/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/phases/README.md b/phases/README.md index 4fbbd888a..86f5fb4ba 100644 --- a/phases/README.md +++ b/phases/README.md @@ -27,13 +27,13 @@ 5. Update tests in `tools/witx/tests/wasi.rs` to point at new snapshot, and add a test pointing at the just-archived snapshot under `old`. 6. Optionally, under `phases/old/snapshot_{old_snapshot_number}, add - polyfills for suberseded APIs using the new APIs. + polyfills for superceded APIs using the new APIs. Pull Requests may also add additional tests, documentation, or polyfills for existing `snapshot` APIs. -- [`old`](old): When APIs in `current` spec are replaced by new +- [`old`](old): When APIs in `snapshot` 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.