wasi_snapshot_preview1.witx

;; 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/blob/main/legacy/tools/witx-docs.md)
;; for an explanation of what that means.

(use "typenames.witx")

(module $wasi_snapshot_preview1
  ;;; 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 `args_sizes_get`.
  ;;;
  ;;; Each argument is expected to be `\0` terminated.
  ;;;
  ;;; The first argument should be a string containing the "name" of the
  ;;; program. This need not be a usable filesystem path or even file name,
  ;;; and may even be a fixed string. Subsequent arguments are the arguments
  ;;; passed to the program by the user.
  (@interface func (export "args_get")
    (param $argv (@witx pointer (@witx pointer u8)))
    (param $argv_buf (@witx pointer u8))
    (result $error (expected (error $errno)))
  )
  ;;; Return command-line argument data sizes.
  (@interface func (export "args_sizes_get")
    ;;; Returns the number of arguments and the size of the argument string
    ;;; data, or an error.
    (result $error (expected (tuple $size $size) (error $errno)))
  )

  ;;; Read environment variable data.
  ;;; The sizes of the buffers should match that returned by `environ_sizes_get`.
  ;;; Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
  (@interface func (export "environ_get")
    (param $environ (@witx pointer (@witx pointer u8)))
    (param $environ_buf (@witx pointer u8))
    (result $error (expected (error $errno)))
  )
  ;;; Return environment variable data sizes.
  (@interface func (export "environ_sizes_get")
    ;;; Returns the number of environment variable arguments and the size of the
    ;;; environment variable data.
    (result $error (expected (tuple $size $size) (error $errno)))
  )

  ;;; Return the resolution of a clock.
  ;;; Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks,
  ;;; return `errno::inval`.
  ;;; Note: This is similar to `clock_getres` in POSIX.
  (@interface func (export "clock_res_get")
    ;;; The clock for which to return the resolution.
    (param $id $clockid)
    ;;; The resolution of the clock, or an error if one happened.
    (result $error (expected $timestamp (error $errno)))
  )
  ;;; 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 $id $clockid)
    ;;; The maximum lag (exclusive) that the returned time value may have, compared to its actual value.
    (param $precision $timestamp)
    ;;; The time value of the clock.
    (result $error (expected $timestamp (error $errno)))
  )

  ;;; 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)
    ;;; The offset within the file to which the advisory applies.
    (param $offset $filesize)
    ;;; The length of the region to which the advisory applies.
    (param $len $filesize)
    ;;; The advice.
    (param $advice $advice)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; The offset at which to start the allocation.
    (param $offset $filesize)
    ;;; The length of the area that is allocated.
    (param $len $filesize)
    (result $error (expected (error $errno)))
  )

  ;;; Close a file descriptor.
  ;;; Note: This is similar to `close` in POSIX.
  (@interface func (export "fd_close")
    (param $fd $fd)
    (result $error (expected (error $errno)))
  )

  ;;; Synchronize the data of a file to disk.
  ;;; Note: This is similar to `fdatasync` in POSIX.
  (@interface func (export "fd_datasync")
    (param $fd $fd)
    (result $error (expected (error $errno)))
  )

  ;;; Get the attributes of a file descriptor.
  ;;; Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX, as well as additional fields.
  (@interface func (export "fd_fdstat_get")
    (param $fd $fd)
    ;;; The buffer where the file descriptor's attributes are stored.
    (result $error (expected $fdstat (error $errno)))
  )

  ;;; 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)
    ;;; The desired values of the file descriptor flags.
    (param $flags $fdflags)
    (result $error (expected (error $errno)))
  )

  ;;; Adjust the rights associated with a file descriptor.
  ;;; This can only be used to remove rights, and returns `errno::notcapable` if called in a way that would attempt to add rights
  (@interface func (export "fd_fdstat_set_rights")
    (param $fd $fd)
    ;;; The desired rights of the file descriptor.
    (param $fs_rights_base $rights)
    (param $fs_rights_inheriting $rights)
    (result $error (expected (error $errno)))
  )

  ;;; Return the attributes of an open file.
  (@interface func (export "fd_filestat_get")
    (param $fd $fd)
    ;;; The buffer where the file's attributes are stored.
    (result $error (expected $filestat (error $errno)))
  )

  ;;; 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)
    ;;; The desired file size.
    (param $size $filesize)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; The desired values of the data access timestamp.
    (param $atim $timestamp)
    ;;; The desired values of the data modification timestamp.
    (param $mtim $timestamp)
    ;;; A bitmask indicating which timestamps to adjust.
    (param $fst_flags $fstflags)
    (result $error (expected (error $errno)))
  )

  ;;; Read from a file descriptor, without using and updating the file descriptor's offset.
  ;;; Note: This is similar to `preadv` in Linux (and other Unix-es).
  (@interface func (export "fd_pread")
    (param $fd $fd)
    ;;; List of scatter/gather vectors in which to store data.
    (param $iovs $iovec_array)
    ;;; The offset within the file at which to read.
    (param $offset $filesize)
    ;;; The number of bytes read.
    (result $error (expected $size (error $errno)))
  )

  ;;; Return a description of the given preopened file descriptor.
  (@interface func (export "fd_prestat_get")
    (param $fd $fd)
    ;;; The buffer where the description is stored.
    (result $error (expected $prestat (error $errno)))
  )

  ;;; Return a description of the given preopened file descriptor.
  (@interface func (export "fd_prestat_dir_name")
    (param $fd $fd)
    ;;; A buffer into which to write the preopened directory name.
    (param $path (@witx pointer u8))
    (param $path_len $size)
    (result $error (expected (error $errno)))
  )

  ;;; Write to a file descriptor, without using and updating the file descriptor's offset.
  ;;; Note: This is similar to `pwritev` in Linux (and other Unix-es).
  ;;;
  ;;; Like Linux (and other Unix-es), any calls of `pwrite` (and other
  ;;; functions to read or write) for a regular file by other threads in the
  ;;; WASI process should not be interleaved while `pwrite` is executed.
  (@interface func (export "fd_pwrite")
    (param $fd $fd)
    ;;; List of scatter/gather vectors from which to retrieve data.
    (param $iovs $ciovec_array)
    ;;; The offset within the file at which to write.
    (param $offset $filesize)
    ;;; The number of bytes written.
    (result $error (expected $size (error $errno)))
  )

  ;;; Read from a file descriptor.
  ;;; Note: This is similar to `readv` in POSIX.
  (@interface func (export "fd_read")
    (param $fd $fd)
    ;;; List of scatter/gather vectors to which to store data.
    (param $iovs $iovec_array)
    ;;; The number of bytes read.
    (result $error (expected $size (error $errno)))
  )

  ;;; Read directory entries from a directory.
  ;;; When successful, the contents of the output buffer consist of a sequence of
  ;;; directory entries. Each directory entry consists of a `dirent` object,
  ;;; followed by `dirent::d_namlen` bytes holding the name of the directory
  ;;; entry.
  ;;
  ;;; This function fills the output buffer as much as possible, potentially
  ;;; truncating the last directory entry. This allows the caller to grow its
  ;;; read buffer size in case it's too small to fit a single large directory
  ;;; entry, or skip the oversized directory entry.
  ;;;
  ;;; Entries for the special `.` and `..` directory entries are included in the
  ;;; sequence.
  (@interface func (export "fd_readdir")
    (param $fd $fd)
    ;;; The buffer where directory entries are stored
    (param $buf (@witx pointer u8))
    (param $buf_len $size)
    ;;; The location within the directory to start reading
    (param $cookie $dircookie)
    ;;; 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 $error (expected $size (error $errno)))
  )

  ;;; 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)
    ;;; The file descriptor to overwrite.
    (param $to $fd)
    (result $error (expected (error $errno)))
  )

  ;;; Move the offset of a file descriptor.
  ;;; Note: This is similar to `lseek` in POSIX.
  (@interface func (export "fd_seek")
    (param $fd $fd)
    ;;; The number of bytes to move.
    (param $offset $filedelta)
    ;;; The base from which the offset is relative.
    (param $whence $whence)
    ;;; The new offset of the file descriptor, relative to the start of the file.
    (result $error (expected $filesize (error $errno)))
  )

  ;;; 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)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; The current offset of the file descriptor, relative to the start of the file.
    (result $error (expected $filesize (error $errno)))
  )

  ;;; Write to a file descriptor.
  ;;; Note: This is similar to `writev` in POSIX.
  ;;;
  ;;; Like POSIX, any calls of `write` (and other functions to read or write)
  ;;; for a regular file by other threads in the WASI process should not be
  ;;; interleaved while `write` is executed.
  (@interface func (export "fd_write")
    (param $fd $fd)
    ;;; List of scatter/gather vectors from which to retrieve data.
    (param $iovs $ciovec_array)
    (result $error (expected $size (error $errno)))
  )

  ;;; Create a directory.
  ;;; Note: This is similar to `mkdirat` in POSIX.
  (@interface func (export "path_create_directory")
    (param $fd $fd)
    ;;; The path at which to create the directory.
    (param $path string)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; Flags determining the method of how the path is resolved.
    (param $flags $lookupflags)
    ;;; The path of the file or directory to inspect.
    (param $path string)
    ;;; The buffer where the file's attributes are stored.
    (result $error (expected $filestat (error $errno)))
  )

  ;;; 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)
    ;;; Flags determining the method of how the path is resolved.
    (param $flags $lookupflags)
    ;;; The path of the file or directory to operate on.
    (param $path string)
    ;;; The desired values of the data access timestamp.
    (param $atim $timestamp)
    ;;; The desired values of the data modification timestamp.
    (param $mtim $timestamp)
    ;;; A bitmask indicating which timestamps to adjust.
    (param $fst_flags $fstflags)
    (result $error (expected (error $errno)))
  )

  ;;; Create a hard link.
  ;;; Note: This is similar to `linkat` in POSIX.
  (@interface func (export "path_link")
    (param $old_fd $fd)
    ;;; Flags determining the method of how the path is resolved.
    (param $old_flags $lookupflags)
    ;;; 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)
    ;;; The destination path at which to create the hard link.
    (param $new_path string)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; Flags determining the method of how the path is resolved.
    (param $dirflags $lookupflags)
    ;;; The relative path of the file or directory to open, relative to the
    ;;; `path_open::fd` directory.
    (param $path string)
    ;;; The method by which to open the file.
    (param $oflags $oflags)
    ;;; 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)
    (param $fs_rights_inheriting $rights)
    (param $fdflags $fdflags)
    ;;; The file descriptor of the file that has been opened.
    (result $error (expected $fd (error $errno)))
  )

  ;;; Read the contents of a symbolic link.
  ;;; Note: This is similar to `readlinkat` in POSIX. If `buf` is not large
  ;;; enough to contain the contents of the link, the first `buf_len` bytes will be
  ;;; be written to `buf`.
  (@interface func (export "path_readlink")
    (param $fd $fd)
    ;;; 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)
    ;;; The number of bytes placed in the buffer.
    (result $error (expected $size (error $errno)))
  )

  ;;; Remove a directory.
  ;;; Return `errno::notempty` 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)
    ;;; The path to a directory to remove.
    (param $path string)
    (result $error (expected (error $errno)))
  )

  ;;; Rename a file or directory.
  ;;; Note: This is similar to `renameat` in POSIX.
  (@interface func (export "path_rename")
    (param $fd $fd)
    ;;; 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)
    ;;; The destination path to which to rename the file or directory.
    (param $new_path string)
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    ;;; The destination path at which to create the symbolic link.
    (param $new_path string)
    (result $error (expected (error $errno)))
  )


  ;;; Unlink a file.
  ;;; Return `errno::isdir` 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)
    ;;; The path to a file to unlink.
    (param $path string)
    (result $error (expected (error $errno)))
  )

  ;;; Concurrently poll for the occurrence of a set of events.
  ;;;
  ;;; If `nsubscriptions` is 0, returns `errno::inval`.
  (@interface func (export "poll_oneoff")
    ;;; The events to which to subscribe.
    (param $in (@witx const_pointer $subscription))
    ;;; The events that have occurred.
    (param $out (@witx pointer $event))
    ;;; Both the number of subscriptions and events.
    (param $nsubscriptions $size)
    ;;; The number of events stored.
    (result $error (expected $size (error $errno)))
  )

  ;;; 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)
    (@witx noreturn)
  )

  ;;; 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)
    (result $error (expected (error $errno)))
  )

  ;;; Temporarily yield execution of the calling thread.
  ;;; Note: This is similar to `sched_yield` in POSIX.
  (@interface func (export "sched_yield")
    (result $error (expected (error $errno)))
  )

  ;;; 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)
    (result $error (expected (error $errno)))
  )

  ;;; Accept a new incoming connection.
  ;;; Note: This is similar to `accept` in POSIX.
  (@interface func (export "sock_accept")
    ;;; The listening socket.
    (param $fd $fd)
    ;;; The desired values of the file descriptor flags.
    (param $flags $fdflags)
    ;;; New socket connection
    (result $error (expected $fd (error $errno)))
  )

  ;;; 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)
    ;;; List of scatter/gather vectors to which to store data.
    (param $ri_data $iovec_array)
    ;;; Message flags.
    (param $ri_flags $riflags)
    ;;; Number of bytes stored in ri_data and message flags.
    (result $error (expected (tuple $size $roflags) (error $errno)))
  )

  ;;; 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)
    ;;; List of scatter/gather vectors to which to retrieve data
    (param $si_data $ciovec_array)
    ;;; Message flags.
    (param $si_flags $siflags)
    ;;; Number of bytes transmitted.
    (result $error (expected $size (error $errno)))
  )

  ;;; Shut down socket send and receive channels.
  ;;; Note: This is similar to `shutdown` in POSIX.
  (@interface func (export "sock_shutdown")
    (param $fd $fd)
    ;;; Which channels on the socket to shut down.
    (param $how $sdflags)
    (result $error (expected (error $errno)))
  )
)