Maybe make WASI API docs less sh*tty?

wasi-preview1-api.md

Modules

wasi_snapshot_preview1

Imports

Memory

Functions

# args_get

args_get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) → Result<(), errno>

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.

Params

• argv: Pointer<Pointer<u8>>

• argv_buf: Pointer<u8>

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# args_sizes_get

args_sizes_get() → Result<(size, size), errno>

Return command-line argument data sizes.

Params

None

Results

• error: Result<(size, size), errno>
  Returns the number of arguments and the size of the argument string data, or an error.

Variants

• size: 12; align: 4; tag_size: 4
• Cases:

  • ok: (size, size)

  • (Offset=0) 0: size

  • (Offset=4) 1: size

  • err: errno

# environ_get

environ_get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) → Result<(), 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 \0s.

Params

• environ: Pointer<Pointer<u8>>

• environ_buf: Pointer<u8>

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# environ_sizes_get

environ_sizes_get() → Result<(size, size), errno>

Return environment variable data sizes.

Params

None

Results

• error: Result<(size, size), errno>
  Returns the number of environment variable arguments and the size of the environment variable data.

Variants

• size: 12; align: 4; tag_size: 4
• Cases:

  • ok: (size, size)

  • (Offset=0) 0: size

  • (Offset=4) 1: size

  • err: errno

# clock_res_get

clock_res_get(id: clockid) → Result<timestamp, 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.

Params

• id: clockid
  The clock for which to return the resolution.

Results

• error: Result<timestamp, errno>
  The resolution of the clock, or an error if one happened.

Variants

• size: 16; align: 8; tag_size: 4
• Cases:

  • ok: timestamp

  • err: errno

# clock_time_get

clock_time_get(id: clockid, precision: timestamp) → Result<timestamp, errno>

Return the time value of a clock. Note: This is similar to clock_gettime in POSIX.

Params

• id: clockid
  The clock for which to return the time.

• precision: timestamp
  The maximum lag (exclusive) that the returned time value may have, compared to its actual value.

Results

• error: Result<timestamp, errno>
  The time value of the clock.

Variants

• size: 16; align: 8; tag_size: 4
• Cases:

  • ok: timestamp

  • err: errno

# fd_advise

fd_advise(fd: fd, offset: filesize, len: filesize, advice: advice) → Result<(), errno>

Provide file advisory information on a file descriptor. Note: This is similar to posix_fadvise in POSIX.

Params

• fd: fd

• offset: filesize
  The offset within the file to which the advisory applies.

• len: filesize
  The length of the region to which the advisory applies.

• advice: advice
  The advice.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_allocate

fd_allocate(fd: fd, offset: filesize, len: filesize) → Result<(), errno>

Force the allocation of space in a file. Note: This is similar to posix_fallocate in POSIX.

Params

• fd: fd

• offset: filesize
  The offset at which to start the allocation.

• len: filesize
  The length of the area that is allocated.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_close

fd_close(fd: fd) → Result<(), errno>

Close a file descriptor. Note: This is similar to close in POSIX.

Params

• fd: fd

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_datasync

fd_datasync(fd: fd) → Result<(), errno>

Synchronize the data of a file to disk. Note: This is similar to fdatasync in POSIX.

Params

• fd: fd

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_fdstat_get

fd_fdstat_get(fd: fd) → Result<fdstat, 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.

Params

• fd: fd

Results

• error: Result<fdstat, errno>
  The buffer where the file descriptor's attributes are stored.

Variants

• size: 32; align: 8; tag_size: 4
• Cases:

  • ok: fdstat

  • err: errno

# fd_fdstat_set_flags

fd_fdstat_set_flags(fd: fd, flags: fdflags) → Result<(), errno>

Adjust the flags associated with a file descriptor. Note: This is similar to fcntl(fd, F_SETFL, flags) in POSIX.

Params

• fd: fd

• flags: fdflags
  The desired values of the file descriptor flags.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_fdstat_set_rights

fd_fdstat_set_rights(fd: fd, fs_rights_base: rights, fs_rights_inheriting: rights) → Result<(), 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

Params

• fd: fd

• fs_rights_base: rights
  The desired rights of the file descriptor.

• fs_rights_inheriting: rights

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_filestat_get

fd_filestat_get(fd: fd) → Result<filestat, errno>

Return the attributes of an open file.

Params

• fd: fd

Results

• error: Result<filestat, errno>
  The buffer where the file's attributes are stored.

Variants

• size: 72; align: 8; tag_size: 4
• Cases:

  • ok: filestat

  • err: errno

# fd_filestat_set_size

fd_filestat_set_size(fd: fd, size: filesize) → Result<(), 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.

Params

• fd: fd

• size: filesize
  The desired file size.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_filestat_set_times

fd_filestat_set_times(fd: fd, atim: timestamp, mtim: timestamp, fst_flags: fstflags) → Result<(), errno>

Adjust the timestamps of an open file or directory. Note: This is similar to futimens in POSIX.

Params

• fd: fd

• atim: timestamp
  The desired values of the data access timestamp.

• mtim: timestamp
  The desired values of the data modification timestamp.

• fst_flags: fstflags
  A bitmask indicating which timestamps to adjust.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_pread

fd_pread(fd: fd, iovs: iovec_array, offset: filesize) → Result<size, 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).

Params

• fd: fd

• iovs: iovec_array
  List of scatter/gather vectors in which to store data.

• offset: filesize
  The offset within the file at which to read.

Results

• error: Result<size, errno>
  The number of bytes read.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# fd_prestat_get

fd_prestat_get(fd: fd) → Result<prestat, errno>

Return a description of the given preopened file descriptor.

Params

• fd: fd

Results

• error: Result<prestat, errno>
  The buffer where the description is stored.

Variants

• size: 12; align: 4; tag_size: 4
• Cases:

  • ok: prestat

  • err: errno

# fd_prestat_dir_name

fd_prestat_dir_name(fd: fd, path: Pointer<u8>, path_len: size) → Result<(), errno>

Return a description of the given preopened file descriptor.

Params

• fd: fd

• path: Pointer<u8>
  A buffer into which to write the preopened directory name.

• path_len: size

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_pwrite

fd_pwrite(fd: fd, iovs: ciovec_array, offset: filesize) → Result<size, 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.

Params

• fd: fd

• iovs: ciovec_array
  List of scatter/gather vectors from which to retrieve data.

• offset: filesize
  The offset within the file at which to write.

Results

• error: Result<size, errno>
  The number of bytes written.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# fd_read

fd_read(fd: fd, iovs: iovec_array) → Result<size, errno>

Read from a file descriptor. Note: This is similar to readv in POSIX.

Params

• fd: fd

• iovs: iovec_array
  List of scatter/gather vectors to which to store data.

Results

• error: Result<size, errno>
  The number of bytes read.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# fd_readdir

fd_readdir(fd: fd, buf: Pointer<u8>, buf_len: size, cookie: dircookie) → Result<size, 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.

Params

• fd: fd

• buf: Pointer<u8>
  The buffer where directory entries are stored

• buf_len: size

• cookie: dircookie
  The location within the directory to start reading

Results

• error: Result<size, errno>
  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.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# fd_renumber

fd_renumber(fd: fd, to: fd) → Result<(), 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.

Params

• fd: fd

• to: fd
  The file descriptor to overwrite.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_seek

fd_seek(fd: fd, offset: filedelta, whence: whence) → Result<filesize, errno>

Move the offset of a file descriptor. Note: This is similar to lseek in POSIX.

Params

• fd: fd

• offset: filedelta
  The number of bytes to move.

• whence: whence
  The base from which the offset is relative.

Results

• error: Result<filesize, errno>
  The new offset of the file descriptor, relative to the start of the file.

Variants

• size: 16; align: 8; tag_size: 4
• Cases:

  • ok: filesize

  • err: errno

# fd_sync

fd_sync(fd: fd) → Result<(), errno>

Synchronize the data and metadata of a file to disk. Note: This is similar to fsync in POSIX.

Params

• fd: fd

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# fd_tell

fd_tell(fd: fd) → Result<filesize, errno>

Return the current offset of a file descriptor. Note: This is similar to lseek(fd, 0, SEEK_CUR) in POSIX.

Params

• fd: fd

Results

• error: Result<filesize, errno>
  The current offset of the file descriptor, relative to the start of the file.

Variants

• size: 16; align: 8; tag_size: 4
• Cases:

  • ok: filesize

  • err: errno

# fd_write

fd_write(fd: fd, iovs: ciovec_array) → Result<size, 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.

Params

• fd: fd

• iovs: ciovec_array
  List of scatter/gather vectors from which to retrieve data.

Results

• error: Result<size, errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# path_create_directory

path_create_directory(fd: fd, path: string) → Result<(), errno>

Create a directory. Note: This is similar to mkdirat in POSIX.

Params

• fd: fd

• path: string
  The path at which to create the directory.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_filestat_get

path_filestat_get(fd: fd, flags: lookupflags, path: string) → Result<filestat, errno>

Return the attributes of a file or directory. Note: This is similar to stat in POSIX.

Params

• fd: fd

• flags: lookupflags
  Flags determining the method of how the path is resolved.

• path: string
  The path of the file or directory to inspect.

Results

• error: Result<filestat, errno>
  The buffer where the file's attributes are stored.

Variants

• size: 72; align: 8; tag_size: 4
• Cases:

  • ok: filestat

  • err: errno

# path_filestat_set_times

path_filestat_set_times(fd: fd, flags: lookupflags, path: string, atim: timestamp, mtim: timestamp, fst_flags: fstflags) → Result<(), errno>

Adjust the timestamps of a file or directory. Note: This is similar to utimensat in POSIX.

Params

• fd: fd

• flags: lookupflags
  Flags determining the method of how the path is resolved.

• path: string
  The path of the file or directory to operate on.

• atim: timestamp
  The desired values of the data access timestamp.

• mtim: timestamp
  The desired values of the data modification timestamp.

• fst_flags: fstflags
  A bitmask indicating which timestamps to adjust.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_link

path_link(old_fd: fd, old_flags: lookupflags, old_path: string, new_fd: fd, new_path: string) → Result<(), errno>

Create a hard link. Note: This is similar to linkat in POSIX.

Params

• old_fd: fd

• old_flags: lookupflags
  Flags determining the method of how the path is resolved.

• old_path: string
  The source path from which to link.

• new_fd: fd
  The working directory at which the resolution of the new path starts.

• new_path: string
  The destination path at which to create the hard link.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_open

path_open(fd: fd, dirflags: lookupflags, path: string, oflags: oflags, fs_rights_base: rights, fs_rights_inheriting: rights, fdflags: fdflags) → Result<fd, 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.

Params

• fd: fd

• dirflags: lookupflags
  Flags determining the method of how the path is resolved.

• path: string
  The relative path of the file or directory to open, relative to the path_open::fd directory.

• oflags: oflags
  The method by which to open the file.

• fs_rights_base: rights
  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.

• fs_rights_inheriting: rights

• fdflags: fdflags

Results

• error: Result<fd, errno>
  The file descriptor of the file that has been opened.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: fd

  • err: errno

# path_readlink

path_readlink(fd: fd, path: string, buf: Pointer<u8>, buf_len: size) → Result<size, 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.

Params

• fd: fd

• path: string
  The path of the symbolic link from which to read.

• buf: Pointer<u8>
  The buffer to which to write the contents of the symbolic link.

• buf_len: size

Results

• error: Result<size, errno>
  The number of bytes placed in the buffer.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# path_remove_directory

path_remove_directory(fd: fd, path: string) → Result<(), 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.

Params

• fd: fd

• path: string
  The path to a directory to remove.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_rename

path_rename(fd: fd, old_path: string, new_fd: fd, new_path: string) → Result<(), errno>

Rename a file or directory. Note: This is similar to renameat in POSIX.

Params

• fd: fd

• old_path: string
  The source path of the file or directory to rename.

• new_fd: fd
  The working directory at which the resolution of the new path starts.

• new_path: string
  The destination path to which to rename the file or directory.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_symlink

path_symlink(old_path: string, fd: fd, new_path: string) → Result<(), errno>

Create a symbolic link. Note: This is similar to symlinkat in POSIX.

Params

• old_path: string
  The contents of the symbolic link.

• fd: fd

• new_path: string
  The destination path at which to create the symbolic link.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# path_unlink_file

path_unlink_file(fd: fd, path: string) → Result<(), 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.

Params

• fd: fd

• path: string
  The path to a file to unlink.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# poll_oneoff

poll_oneoff(in: ConstPointer<subscription>, out: Pointer<event>, nsubscriptions: size) → Result<size, errno>

Concurrently poll for the occurrence of a set of events.

If nsubscriptions is 0, returns errno::inval.

Params

• in: ConstPointer<subscription>
  The events to which to subscribe.

• out: Pointer<event>
  The events that have occurred.

• nsubscriptions: size
  Both the number of subscriptions and events.

Results

• error: Result<size, errno>
  The number of events stored.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# proc_exit

proc_exit(rval: exitcode)

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.

Params

• rval: exitcode
  The exit code returned by the process.

Results

# proc_raise

proc_raise(sig: signal) → Result<(), errno>

Send a signal to the process of the calling thread. Note: This is similar to raise in POSIX.

Params

• sig: signal
  The signal condition to trigger.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# sched_yield

sched_yield() → Result<(), errno>

Temporarily yield execution of the calling thread. Note: This is similar to sched_yield in POSIX.

Params

None

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# random_get

random_get(buf: Pointer<u8>, buf_len: size) → Result<(), 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.

Params

• buf: Pointer<u8>
  The buffer to fill with random data.

• buf_len: size

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

# sock_accept

sock_accept(fd: fd, flags: fdflags) → Result<fd, errno>

Accept a new incoming connection. Note: This is similar to accept in POSIX.

Params

• fd: fd
  The listening socket.

• flags: fdflags
  The desired values of the file descriptor flags.

Results

• error: Result<fd, errno>
  New socket connection

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: fd

  • err: errno

# sock_recv

sock_recv(fd: fd, ri_data: iovec_array, ri_flags: riflags) → Result<(size, roflags), 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.

Params

• fd: fd

• ri_data: iovec_array
  List of scatter/gather vectors to which to store data.

• ri_flags: riflags
  Message flags.

Results

• error: Result<(size, roflags), errno>
  Number of bytes stored in ri_data and message flags.

Variants

• size: 12; align: 4; tag_size: 4
• Cases:

  • ok: (size, roflags)

  • (Offset=0) 0: size

  • (Offset=4) 1: roflags

  • err: errno

# sock_send

sock_send(fd: fd, si_data: ciovec_array, si_flags: siflags) → Result<size, 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.

Params

• fd: fd

• si_data: ciovec_array
  List of scatter/gather vectors to which to retrieve data

• si_flags: siflags
  Message flags.

Results

• error: Result<size, errno>
  Number of bytes transmitted.

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok: size

  • err: errno

# sock_shutdown

sock_shutdown(fd: fd, how: sdflags) → Result<(), errno>

Shut down socket send and receive channels. Note: This is similar to shutdown in POSIX.

Params

• fd: fd

• how: sdflags
  Which channels on the socket to shut down.

Results

• error: Result<(), errno>

Variants

• size: 8; align: 4; tag_size: 4
• Cases:

  • ok

  • err: errno

Types

size: u32

• Size: 4
• Alignment: 4

filesize: u64

Non-negative file size or length of a region within a file.

• Size: 8
• Alignment: 8

timestamp: u64

Timestamp in nanoseconds.

• Size: 8
• Alignment: 8

clockid: Variant

Identifiers for clocks.

• Size: 4

• Alignment: 4

• Cases:

  • realtime
    The clock measuring real time. Time value zero corresponds with 1970-01-01T00:00:00Z.

  • 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.

  • process_cputime_id
    The CPU-time clock associated with the current process.

  • thread_cputime_id
    The CPU-time clock associated with the current thread.

errno: Variant

Error codes returned by functions. Not all of these error codes are returned by the functions provided by this API; some are used in higher-level library layers, and others are provided merely for alignment with POSIX.

• Size: 2

• Alignment: 2

• Cases:

  • success
    No error occurred. System call completed successfully.

  • 2big
    Argument list too long.

  • acces
    Permission denied.

  • addrinuse
    Address in use.

  • addrnotavail
    Address not available.

  • afnosupport
    Address family not supported.

  • again
    Resource unavailable, or operation would block.

  • already
    Connection already in progress.

  • badf
    Bad file descriptor.

  • badmsg
    Bad message.

  • busy
    Device or resource busy.

  • canceled
    Operation canceled.

  • child
    No child processes.

  • connaborted
    Connection aborted.

  • connrefused
    Connection refused.

  • connreset
    Connection reset.

  • deadlk
    Resource deadlock would occur.

  • destaddrreq
    Destination address required.

  • dom
    Mathematics argument out of domain of function.

  • dquot
    Reserved.

  • exist
    File exists.

  • fault
    Bad address.

  • fbig
    File too large.

  • hostunreach
    Host is unreachable.

  • idrm
    Identifier removed.

  • ilseq
    Illegal byte sequence.

  • inprogress
    Operation in progress.

  • intr
    Interrupted function.

  • inval
    Invalid argument.

  • io
    I/O error.

  • isconn
    Socket is connected.

  • isdir
    Is a directory.

  • loop
    Too many levels of symbolic links.

  • mfile
    File descriptor value too large.

  • mlink
    Too many links.

  • msgsize
    Message too large.

  • multihop
    Reserved.

  • nametoolong
    Filename too long.

  • netdown
    Network is down.

  • netreset
    Connection aborted by network.

  • netunreach
    Network unreachable.

  • nfile
    Too many files open in system.

  • nobufs
    No buffer space available.

  • nodev
    No such device.

  • noent
    No such file or directory.

  • noexec
    Executable file format error.

  • nolck
    No locks available.

  • nolink
    Reserved.

  • nomem
    Not enough space.

  • nomsg
    No message of the desired type.

  • noprotoopt
    Protocol not available.

  • nospc
    No space left on device.

  • nosys
    Function not supported.

  • notconn
    The socket is not connected.

  • notdir
    Not a directory or a symbolic link to a directory.

  • notempty
    Directory not empty.

  • notrecoverable
    State not recoverable.

  • notsock
    Not a socket.

  • notsup
    Not supported, or operation not supported on socket.

  • notty
    Inappropriate I/O control operation.

  • nxio
    No such device or address.

  • overflow
    Value too large to be stored in data type.

  • ownerdead
    Previous owner died.

  • perm
    Operation not permitted.

  • pipe
    Broken pipe.

  • proto
    Protocol error.

  • protonosupport
    Protocol not supported.

  • prototype
    Protocol wrong type for socket.

  • range
    Result too large.

  • rofs
    Read-only file system.

  • spipe
    Invalid seek.

  • srch
    No such process.

  • stale
    Reserved.

  • timedout
    Connection timed out.

  • txtbsy
    Text file busy.

  • xdev
    Cross-device link.

  • notcapable
    Extension: Capabilities insufficient.

rights: Record

File descriptor rights, determining which actions may be performed.

• Size: 8

• Alignment: 8

  • (Bit=0) fd_datasync: bool
    The right to invoke fd_datasync. If path_open is set, includes the right to invoke path_open with fdflags::dsync.

  • (Bit=1) fd_read: bool
    The right to invoke fd_read and sock_recv. If rights::fd_seek is set, includes the right to invoke fd_pread.

  • (Bit=2) fd_seek: bool
    The right to invoke fd_seek. This flag implies rights::fd_tell.

  • (Bit=3) fd_fdstat_set_flags: bool
    The right to invoke fd_fdstat_set_flags.

  • (Bit=4) fd_sync: bool
    The right to invoke fd_sync. If path_open is set, includes the right to invoke path_open with fdflags::rsync and fdflags::dsync.

  • (Bit=5) fd_tell: bool
    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.

  • (Bit=6) fd_write: bool
    The right to invoke fd_write and sock_send. If rights::fd_seek is set, includes the right to invoke fd_pwrite.

  • (Bit=7) fd_advise: bool
    The right to invoke fd_advise.

  • (Bit=8) fd_allocate: bool
    The right to invoke fd_allocate.

  • (Bit=9) path_create_directory: bool
    The right to invoke path_create_directory.

  • (Bit=10) path_create_file: bool
    If path_open is set, the right to invoke path_open with oflags::creat.

  • (Bit=11) path_link_source: bool
    The right to invoke path_link with the file descriptor as the source directory.

  • (Bit=12) path_link_target: bool
    The right to invoke path_link with the file descriptor as the target directory.

  • (Bit=13) path_open: bool
    The right to invoke path_open.

  • (Bit=14) fd_readdir: bool
    The right to invoke fd_readdir.

  • (Bit=15) path_readlink: bool
    The right to invoke path_readlink.

  • (Bit=16) path_rename_source: bool
    The right to invoke path_rename with the file descriptor as the source directory.

  • (Bit=17) path_rename_target: bool
    The right to invoke path_rename with the file descriptor as the target directory.

  • (Bit=18) path_filestat_get: bool
    The right to invoke path_filestat_get.

  • (Bit=19) path_filestat_set_size: bool
    The right to change a file's size. If path_open is set, includes the right to invoke path_open with oflags::trunc. Note: there is no function named path_filestat_set_size. This follows POSIX design, which only has ftruncate and does not provide ftruncateat. While such function would be desirable from the API design perspective, there are virtually no use cases for it since no code written for POSIX systems would use it. Moreover, implementing it would require multiple syscalls, leading to inferior performance.

  • (Bit=20) path_filestat_set_times: bool
    The right to invoke path_filestat_set_times.

  • (Bit=21) fd_filestat_get: bool
    The right to invoke fd_filestat_get.

  • (Bit=22) fd_filestat_set_size: bool
    The right to invoke fd_filestat_set_size.

  • (Bit=23) fd_filestat_set_times: bool
    The right to invoke fd_filestat_set_times.

  • (Bit=24) path_symlink: bool
    The right to invoke path_symlink.

  • (Bit=25) path_remove_directory: bool
    The right to invoke path_remove_directory.

  • (Bit=26) path_unlink_file: bool
    The right to invoke path_unlink_file.

  • (Bit=27) poll_fd_readwrite: bool
    If rights::fd_read is set, includes the right to invoke poll_oneoff to subscribe to eventtype::fd_read. If rights::fd_write is set, includes the right to invoke poll_oneoff to subscribe to eventtype::fd_write.

  • (Bit=28) sock_shutdown: bool
    The right to invoke sock_shutdown.

  • (Bit=29) sock_accept: bool
    The right to invoke sock_accept.

fd: Handle

A file descriptor handle.

• Size: 4
• Alignment: 4

Supertypes

iovec: Record

A region of memory for scatter/gather reads.

• Size: 8

• Alignment: 4

  • (Offset=0) buf: Pointer<u8>
    The address of the buffer to be filled.

  • (Offset=4) buf_len: size
    The length of the buffer to be filled.

ciovec: Record

A region of memory for scatter/gather writes.

• Size: 8

• Alignment: 4

  • (Offset=0) buf: ConstPointer<u8>
    The address of the buffer to be written.

  • (Offset=4) buf_len: size
    The length of the buffer to be written.

iovec_array: List<iovec>

• Size: 8
• Alignment: 4

ciovec_array: List<ciovec>

• Size: 8
• Alignment: 4

filedelta: s64

Relative offset within a file.

• Size: 8
• Alignment: 8

whence: Variant

The position relative to which to set the offset of the file descriptor.

• Size: 1

• Alignment: 1

• Cases:

  • set
    Seek relative to start-of-file.

  • cur
    Seek relative to current position.

  • end
    Seek relative to end-of-file.

dircookie: u64

A reference to the offset of a directory entry.

The value 0 signifies the start of the directory.

• Size: 8
• Alignment: 8

dirnamlen: u32

The type for the dirent::d_namlen field of dirent struct.

• Size: 4
• Alignment: 4

inode: u64

File serial number that is unique within its file system.

• Size: 8
• Alignment: 8

filetype: Variant

The type of a file descriptor or file.

• Size: 1

• Alignment: 1

• Cases:

  • unknown
    The type of the file descriptor or file is unknown or is different from any of the other types specified.

  • block_device
    The file descriptor or file refers to a block device inode.

  • character_device
    The file descriptor or file refers to a character device inode.

  • directory
    The file descriptor or file refers to a directory inode.

  • regular_file
    The file descriptor or file refers to a regular file inode.

  • socket_dgram
    The file descriptor or file refers to a datagram socket.

  • socket_stream
    The file descriptor or file refers to a byte-stream socket.

  • symbolic_link
    The file refers to a symbolic link inode.

dirent: Record

A directory entry.

• Size: 24

• Alignment: 8

  • (Offset=0) d_next: dircookie
    The offset of the next directory entry stored in this directory.

  • (Offset=8) d_ino: inode
    The serial number of the file referred to by this directory entry.

  • (Offset=16) d_namlen: dirnamlen
    The length of the name of the directory entry.

  • (Offset=20) d_type: filetype
    The type of the file referred to by this directory entry.

advice: Variant

File or memory access pattern advisory information.

• Size: 1

• Alignment: 1

• Cases:

  • normal
    The application has no advice to give on its behavior with respect to the specified data.

  • sequential
    The application expects to access the specified data sequentially from lower offsets to higher offsets.

  • random
    The application expects to access the specified data in a random order.

  • willneed
    The application expects to access the specified data in the near future.

  • dontneed
    The application expects that it will not access the specified data in the near future.

  • noreuse
    The application expects to access the specified data once and then not reuse it thereafter.

fdflags: Record

File descriptor flags.

• Size: 2

• Alignment: 2

  • (Bit=0) append: bool
    Append mode: Data written to the file is always appended to the file's end.

  • (Bit=1) dsync: bool
    Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.

  • (Bit=2) nonblock: bool
    Non-blocking mode.

  • (Bit=3) rsync: bool
    Synchronized read I/O operations.

  • (Bit=4) sync: bool
    Write according to synchronized I/O file integrity completion. In addition to synchronizing the data stored in the file, the implementation may also synchronously update the file's metadata.

fdstat: Record

File descriptor attributes.

• Size: 24

• Alignment: 8

  • (Offset=0) fs_filetype: filetype
    File type.

  • (Offset=2) fs_flags: fdflags
    File descriptor flags.

  • (Offset=8) fs_rights_base: rights
    Rights that apply to this file descriptor.

  • (Offset=16) fs_rights_inheriting: rights
    Maximum set of rights that may be installed on new file descriptors that are created through this file descriptor, e.g., through path_open.

device: u64

Identifier for a device containing a file system. Can be used in combination with inode to uniquely identify a file or directory in the filesystem.

• Size: 8
• Alignment: 8

fstflags: Record

Which file time attributes to adjust.

• Size: 2

• Alignment: 2

  • (Bit=0) atim: bool
    Adjust the last data access timestamp to the value stored in filestat::atim.

  • (Bit=1) atim_now: bool
    Adjust the last data access timestamp to the time of clock clockid::realtime.

  • (Bit=2) mtim: bool
    Adjust the last data modification timestamp to the value stored in filestat::mtim.

  • (Bit=3) mtim_now: bool
    Adjust the last data modification timestamp to the time of clock clockid::realtime.

lookupflags: Record

Flags determining the method of how paths are resolved.

• Size: 4

• Alignment: 4

  • (Bit=0) symlink_follow: bool
    As long as the resolved path corresponds to a symbolic link, it is expanded.

oflags: Record

Open flags used by path_open.

• Size: 2

• Alignment: 2

  • (Bit=0) creat: bool
    Create file if it does not exist.

  • (Bit=1) directory: bool
    Fail if not a directory.

  • (Bit=2) excl: bool
    Fail if file already exists.

  • (Bit=3) trunc: bool
    Truncate file to size 0.

linkcount: u64

Number of hard links to an inode.

• Size: 8
• Alignment: 8

filestat: Record

File attributes.

• Size: 64

• Alignment: 8

  • (Offset=0) dev: device
    Device ID of device containing the file.

  • (Offset=8) ino: inode
    File serial number.

  • (Offset=16) filetype: filetype
    File type.

  • (Offset=24) nlink: linkcount
    Number of hard links to the file.

  • (Offset=32) size: filesize
    For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link.

  • (Offset=40) atim: timestamp
    Last data access timestamp. This can be 0 if the underlying platform doesn't provide suitable timestamp for this file.

  • (Offset=48) mtim: timestamp
    Last data modification timestamp. This can be 0 if the underlying platform doesn't provide suitable timestamp for this file.

  • (Offset=56) ctim: timestamp
    Last file status change timestamp. This can be 0 if the underlying platform doesn't provide suitable timestamp for this file.

userdata: u64

User-provided value that may be attached to objects that is retained when extracted from the implementation.

• Size: 8
• Alignment: 8

eventtype: Variant

Type of a subscription to an event or its occurrence.

• Size: 1

• Alignment: 1

• Cases:

  • clock
    The time value of clock subscription_clock::id has reached timestamp subscription_clock::timeout.

  • fd_read
    File descriptor subscription_fd_readwrite::file_descriptor has data available for reading. This event always triggers for regular files.

  • fd_write
    File descriptor subscription_fd_readwrite::file_descriptor has capacity available for writing. This event always triggers for regular files.

eventrwflags: Record

The state of the file descriptor subscribed to with eventtype::fd_read or eventtype::fd_write.

• Size: 2

• Alignment: 2

  • (Bit=0) fd_readwrite_hangup: bool
    The peer of this socket has closed or disconnected.

event_fd_readwrite: Record

The contents of an event when type is eventtype::fd_read or eventtype::fd_write.

• Size: 16

• Alignment: 8

  • (Offset=0) nbytes: filesize
    The number of bytes available for reading or writing.

  • (Offset=8) flags: eventrwflags
    The state of the file descriptor.

event: Record

An event that occurred.

• Size: 32

• Alignment: 8

  • (Offset=0) userdata: userdata
    User-provided value that got attached to subscription::userdata.

  • (Offset=8) error: errno
    If non-zero, an error that occurred while processing the subscription request.

  • (Offset=10) type: eventtype
    The type of event that occured

  • (Offset=16) fd_readwrite: event_fd_readwrite
    The contents of the event, if it is an eventtype::fd_read or eventtype::fd_write. eventtype::clock events ignore this field.

subclockflags: Record

Flags determining how to interpret the timestamp provided in subscription_clock::timeout.

• Size: 2

• Alignment: 2

  • (Bit=0) subscription_clock_abstime: bool
    If set, treat the timestamp provided in subscription_clock::timeout as an absolute timestamp of clock subscription_clock::id. If clear, treat the timestamp provided in subscription_clock::timeout relative to the current time value of clock subscription_clock::id.

subscription_clock: Record

The contents of a subscription when type is eventtype::clock.

• Size: 32

• Alignment: 8

  • (Offset=0) id: clockid
    The clock against which to compare the timestamp.

  • (Offset=8) timeout: timestamp
    The absolute or relative timestamp.

  • (Offset=16) precision: timestamp
    The amount of time that the implementation may wait additionally to coalesce with other events.

  • (Offset=24) flags: subclockflags
    Flags specifying whether the timeout is absolute or relative

subscription_fd_readwrite: Record

The contents of a subscription when type is type is eventtype::fd_read or eventtype::fd_write.

• Size: 4

• Alignment: 4

  • (Offset=0) file_descriptor: fd
    The file descriptor on which to wait for it to become ready for reading or writing.

subscription_u: Variant

The contents of a subscription.

• Size: 40
• Alignment: 8

Variants

• size: 40; align: 8; tag_size: 1
• Cases:

  • clock: subscription_clock

  • fd_read: subscription_fd_readwrite

  • fd_write: subscription_fd_readwrite

subscription: Record

Subscription to an event.

• Size: 48

• Alignment: 8

  • (Offset=0) userdata: userdata
    User-provided value that is attached to the subscription in the implementation and returned through event::userdata.

  • (Offset=8) u: subscription_u
    The type of the event to which to subscribe, and its contents

exitcode: u32

Exit code generated by a process when exiting.

• Size: 4
• Alignment: 4

signal: Variant

Signal condition.

• Size: 1

• Alignment: 1

• Cases:

  • none
    No signal. Note that POSIX has special semantics for kill(pid, 0), so this value is reserved.

  • hup
    Hangup. Action: Terminates the process.

  • int
    Terminate interrupt signal. Action: Terminates the process.

  • quit
    Terminal quit signal. Action: Terminates the process.

  • ill
    Illegal instruction. Action: Terminates the process.

  • trap
    Trace/breakpoint trap. Action: Terminates the process.

  • abrt
    Process abort signal. Action: Terminates the process.

  • bus
    Access to an undefined portion of a memory object. Action: Terminates the process.

  • fpe
    Erroneous arithmetic operation. Action: Terminates the process.

  • kill
    Kill. Action: Terminates the process.

  • usr1
    User-defined signal 1. Action: Terminates the process.

  • segv
    Invalid memory reference. Action: Terminates the process.

  • usr2
    User-defined signal 2. Action: Terminates the process.

  • pipe
    Write on a pipe with no one to read it. Action: Ignored.

  • alrm
    Alarm clock. Action: Terminates the process.

  • term
    Termination signal. Action: Terminates the process.

  • chld
    Child process terminated, stopped, or continued. Action: Ignored.

  • cont
    Continue executing, if stopped. Action: Continues executing, if stopped.

  • stop
    Stop executing. Action: Stops executing.

  • tstp
    Terminal stop signal. Action: Stops executing.

  • ttin
    Background process attempting read. Action: Stops executing.

  • ttou
    Background process attempting write. Action: Stops executing.

  • urg
    High bandwidth data is available at a socket. Action: Ignored.

  • xcpu
    CPU time limit exceeded. Action: Terminates the process.

  • xfsz
    File size limit exceeded. Action: Terminates the process.

  • vtalrm
    Virtual timer expired. Action: Terminates the process.

  • prof
    Profiling timer expired. Action: Terminates the process.

  • winch
    Window changed. Action: Ignored.

  • poll
    I/O possible. Action: Terminates the process.

  • pwr
    Power failure. Action: Terminates the process.

  • sys
    Bad system call. Action: Terminates the process.

riflags: Record

Flags provided to sock_recv.

• Size: 2

• Alignment: 2

  • (Bit=0) recv_peek: bool
    Returns the message without removing it from the socket's receive queue.

  • (Bit=1) recv_waitall: bool
    On byte-stream sockets, block until the full amount of data can be returned.

roflags: Record

Flags returned by sock_recv.

• Size: 2

• Alignment: 2

  • (Bit=0) recv_data_truncated: bool
    Returned by sock_recv: Message data has been truncated.

siflags: u16

Flags provided to sock_send. As there are currently no flags defined, it must be set to zero.

• Size: 2
• Alignment: 2

sdflags: Record

Which channels on a socket to shut down.

• Size: 1

• Alignment: 1

  • (Bit=0) rd: bool
    Disables further receive operations.

  • (Bit=1) wr: bool
    Disables further send operations.

preopentype: Variant

Identifiers for preopened capabilities.

• Size: 1

• Alignment: 1

• Cases:

  • dir
    A pre-opened directory.

prestat_dir: Record

The contents of a prestat when type is preopentype::dir.

• Size: 4

• Alignment: 4

  • (Offset=0) pr_name_len: size
    The length of the directory name for use with fd_prestat_dir_name.

prestat: Variant

Information about a pre-opened capability.

• Size: 8
• Alignment: 4

Variants

• size: 8; align: 4; tag_size: 1
• Cases:
  • dir: prestat_dir