Skip to content

Latest commit

 

History

History
2062 lines (1358 loc) · 68.7 KB

docs.md

File metadata and controls

2062 lines (1358 loc) · 68.7 KB

Types

size: usize

An array size.

Note: This is similar to size_t in POSIX.

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: Enum(u32)

Identifiers for clocks.

Size: 4

Alignment: 4

Variants

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

errno: Enum(u16)

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

Variants

  • success No error occurred. System call completed successfully.

  • 2big Argument list too long.

  • access 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: Flags(u64)

File descriptor rights, determining which actions may be performed.

Size: 8

Alignment: 8

Flags

  • fd_datasync The right to invoke fd_datasync. If path_open is set, includes the right to invoke path_open with fdflags::dsync.

  • fd_read The right to invoke fd_read and sock_recv. If rights::fd_seek is set, includes the right to invoke fd_pread.

  • fd_seek The right to invoke fd_seek. This flag implies rights::fd_tell.

  • fd_fdstat_set_flags The right to invoke fd_fdstat_set_flags.

  • fd_sync The right to invoke fd_sync. If path_open is set, includes the right to invoke path_open with fdflags::rsync and fdflags::dsync.

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

  • fd_write The right to invoke fd_write and sock_send. If rights::fd_seek is set, includes the right to invoke fd_pwrite.

  • fd_advise The right to invoke fd_advise.

  • fd_allocate The right to invoke fd_allocate.

  • path_create_directory The right to invoke path_create_directory.

  • path_create_file If path_open is set, the right to invoke path_open with oflags::create.

  • path_link_source The right to invoke path_link with the file descriptor as the source directory.

  • path_link_target The right to invoke path_link with the file descriptor as the target directory.

  • path_open The right to invoke path_open.

  • fd_readdir The right to invoke fd_readdir.

  • path_readlink The right to invoke path_readlink.

  • path_rename_source The right to invoke path_rename with the file descriptor as the source directory.

  • path_rename_target The right to invoke path_rename with the file descriptor as the target directory.

  • path_filestat_get The right to invoke path_filestat_get.

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

  • path_filestat_set_times The right to invoke path_filestat_set_times.

  • path_permissions_set The right to invoke path_permissions_set.

  • fd_filestat_get The right to invoke fd_filestat_get.

  • fd_filestat_set_size The right to invoke fd_filestat_set_size.

  • fd_filestat_set_times The right to invoke fd_filestat_set_times.

  • fd_permissions_set The right to invoke fd_permissions_set.

  • path_symlink The right to invoke path_symlink.

  • path_remove_directory The right to invoke path_remove_directory.

  • path_unlink_file The right to invoke path_unlink_file.

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

  • sock_shutdown The right to invoke sock_shutdown.

fd

A file descriptor handle.

Size: 4

Alignment: 4

Supertypes

iovec: Struct

A region of memory for scatter/gather reads.

Size: 8

Alignment: 4

Struct members

  • buf: Pointer<u8> The address of the buffer to be filled.

Offset: 0

  • buf_len: size The length of the buffer to be filled.

Offset: 4

ciovec: Struct

A region of memory for scatter/gather writes.

Size: 8

Alignment: 4

Struct members

  • buf: ConstPointer<u8> The address of the buffer to be written.

Offset: 0

  • buf_len: size The length of the buffer to be written.

Offset: 4

iovec_array: Array<iovec>

Size: 8

Alignment: 4

ciovec_array: Array<ciovec>

Size: 8

Alignment: 4

filedelta: s64

Relative offset within a file.

Size: 8

Alignment: 8

whence: Enum(u8)

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

Size: 1

Alignment: 1

Variants

  • set Seek relative to start-of-file.

  • cur Seek relative to current position.

  • end Seek relative to end-of-file.

dircookie: Int(u64)

A reference to the offset of a directory entry.

Size: 8

Alignment: 8

Consts

  • start In an fd_readdir call, this value signifies the start of the directory.

dirnamlen: u32

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

Size: 4

Alignment: 4

inode: u64

File serial number that is unique within its file system.

Size: 8

Alignment: 8

filetype: Enum(u8)

The type of a file descriptor or file.

Size: 1

Alignment: 1

Variants

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

  • fifo The file descriptor or file refers to a FIFO.

dirent: Struct

A directory entry.

Size: 24

Alignment: 8

Struct members

  • d_next: dircookie The offset of the next directory entry stored in this directory.

Offset: 0

  • d_ino: inode The serial number of the file referred to by this directory entry.

Offset: 8

  • d_type: filetype The type 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

advice: Enum(u8)

File or memory access pattern advisory information.

Size: 1

Alignment: 1

Variants

  • 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: Flags(u16)

File descriptor flags.

Size: 2

Alignment: 2

Flags

  • append Append mode: Data written to the file is always appended to the file's end.

  • dsync Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.

  • nonblock Non-blocking mode.

  • rsync Synchronized read I/O operations.

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

fdstat: Struct

File descriptor attributes.

Size: 24

Alignment: 8

Struct members

Offset: 0

  • fs_flags: fdflags File descriptor flags.

Offset: 2

  • fs_rights_base: rights Rights that apply to this file descriptor.

Offset: 8

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

Offset: 16

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: Flags(u16)

Which file time attributes to adjust.

Size: 2

Alignment: 2

Flags

  • atim Adjust the last data access timestamp to the value stored in filestat::atim.

  • atim_now Adjust the last data access timestamp to the time of clock clockid::realtime.

  • mtim Adjust the last data modification timestamp to the value stored in filestat::mtim.

  • mtim_now Adjust the last data modification timestamp to the time of clock clockid::realtime.

lookupflags: Flags(u32)

Flags determining the method of how paths are resolved.

Size: 4

Alignment: 4

Flags

  • symlink_follow As long as the resolved path corresponds to a symbolic link, it is expanded.

oflags: Flags(u16)

Open flags used by path_open.

Size: 2

Alignment: 2

Flags

  • create Create file if it does not exist.

  • directory Fail if not a directory.

  • excl Fail if file already exists.

  • trunc Truncate file to size 0.

linkcount: u64

Number of hard links to an inode.

Size: 8

Alignment: 8

permissions: Flags(u8)

File permissions. This represents the permissions associated with a file in a filesystem, and don't fully reflect all the conditions which determine whether a given WASI program can access the file.

Size: 1

Alignment: 1

Flags

  • read For files, permission to read the file. For directories, permission to do readdir and access files within the directory.

Note: This is similar to the read bit being set on files, and the read and execute bits being set on directories, in POSIX.

  • write For files, permission to mutate the file. For directories, permission to create, remove, and rename items within the directory.

  • execute For files, permission to "execute" the file, using whatever concept of "executing" the host filesystem has. This flag is not valid for directories.

  • private For filesystems which have a concept of multiple "users", this flag indicates that the file is only accessible by the effective "user" that the WASI store uses to access the filesystem, and inaccessible to other "users".

filestat: Struct

File attributes.

Size: 64

Alignment: 8

Struct members

  • dev: device Device ID of device containing the file.

Offset: 0

  • ino: inode File serial number.

Offset: 8

Offset: 16

Offset: 17

  • nlink: linkcount Number of hard links to the file.

Offset: 24

  • 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: 32

  • atim: timestamp Last data access timestamp.

Offset: 40

  • mtim: timestamp Last data modification timestamp.

Offset: 48

  • ctim: timestamp Last file status change timestamp.

Offset: 56

userdata: u64

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

Size: 8

Alignment: 8

eventtype: Enum(u8)

Type of a subscription to an event or its occurrence.

Size: 1

Alignment: 1

Variants

eventrwflags: Flags(u16)

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

Size: 2

Alignment: 2

Flags

  • fd_readwrite_hangup The peer of this socket has closed or disconnected.

event_fd_readwrite: Struct

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

Size: 16

Alignment: 8

Struct members

  • nbytes: filesize The number of bytes available for reading or writing.

Offset: 0

Offset: 8

event_u: Union

The contents of an event.

Size: 24

Alignment: 8

Union Layout

  • tag_size: 1
  • tag_align: 1
  • contents_offset: 8
  • contents_size: 16
  • contents_align: 8

Union variants

event: Struct

An event that occurred.

Size: 40

Alignment: 8

Struct members

Offset: 0

  • error: errno If non-zero, an error that occurred while processing the subscription request.

Offset: 8

  • u: event_u The type of the event that occurred, and the contents of the event

Offset: 16

subclockflags: Flags(u16)

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

Size: 2

Alignment: 2

Flags

subscription_clock: Struct

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

Size: 32

Alignment: 8

Struct members

  • id: clockid The clock against which to compare the timestamp.

Offset: 0

  • timeout: timestamp The absolute or relative timestamp.

Offset: 8

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

Offset: 16

  • flags: subclockflags Flags specifying whether the timeout is absolute or relative

Offset: 24

subscription_fd_readwrite: Struct

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

Size: 4

Alignment: 4

Struct members

  • fd: fd The file descriptor on which to wait for it to become ready for reading or writing.

Offset: 0

subscription_u: Union

The contents of a subscription.

Size: 40

Alignment: 8

Union Layout

  • tag_size: 1
  • tag_align: 1
  • contents_offset: 8
  • contents_size: 32
  • contents_align: 8

Union variants

subscription: Struct

Subscription to an event.

Size: 48

Alignment: 8

Struct members

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

Offset: 0

  • u: subscription_u The type of the event to which to subscribe, and the contents of the subscription.

Offset: 8

exitcode: u32

Exit code generated by a process when exiting.

Size: 4

Alignment: 4

riflags: Flags(u16)

Flags provided to sock_recv.

Size: 2

Alignment: 2

Flags

  • recv_peek Returns the message without removing it from the socket's receive queue.

  • recv_waitall On byte-stream sockets, block until the full amount of data can be returned.

roflags: Flags(u16)

Flags returned by sock_recv.

Size: 2

Alignment: 2

Flags

  • recv_data_truncated 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: Flags(u8)

Which channels on a socket to shut down.

Size: 1

Alignment: 1

Flags

  • rd Disables further receive operations.

  • wr Disables further send operations.

preopentype: Enum(u8)

Identifiers for preopened capabilities.

Size: 1

Alignment: 1

Variants

  • dir A pre-opened directory.

prestat_dir: Struct

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

Size: 4

Alignment: 4

Struct members

  • pr_name_len: size The length of the directory name for use with fd_prestat_dir_name.

Offset: 0

prestat: Union

Information about a pre-opened capability.

Size: 8

Alignment: 4

Union Layout

  • tag_size: 1
  • tag_align: 1
  • contents_offset: 4
  • contents_size: 4
  • contents_align: 4

Union variants

Modules

wasi_ephemeral_args

Imports

Memory

Functions

get(argv: Pointer<Pointer<char8>>, argv_buf: Pointer<char8>) -> errno

Read command-line argument data. The size of the array should match that returned by sizes_get

Params

  • argv: Pointer<Pointer<char8>>

  • argv_buf: Pointer<char8>

Results

sizes_get() -> (errno, size, size)

Return command-line argument data sizes.

Params
Results

  • error: errno

  • argc: size The number of arguments.

  • argv_buf_size: size The size of the argument string data.

wasi_ephemeral_clock

Imports

Memory

Functions

res_get(id: clockid) -> (errno, timestamp)

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

time_get(id: clockid, precision: timestamp) -> (errno, timestamp)

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

wasi_ephemeral_environ

Imports

Memory

Functions

get(environ: Pointer<Pointer<char8>>, environ_buf: Pointer<char8>) -> errno

Read environment variable data. The sizes of the buffers should match that returned by sizes_get.

Params

  • environ: Pointer<Pointer<char8>>

  • environ_buf: Pointer<char8>

Results

sizes_get() -> (errno, size, size)

Return environment variable data sizes.

Params
Results

  • error: errno

  • environc: size The number of environment variable arguments.

  • environ_buf_size: size The size of the environment variable data.

wasi_ephemeral_fd

Imports

Memory

Functions

advise(fd: fd, offset: filesize, len: filesize, advice: advice) -> 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

allocate(fd: fd, offset: filesize, len: filesize) -> 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

close(fd: fd) -> errno

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

Params
Results

datasync(fd: fd) -> errno

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

Params
Results

fdstat_get(fd: fd) -> (errno, fdstat)

Get the attributes of a file descriptor. Note: This returns similar flags to fsync(fd, F_GETFL) in POSIX, as well as additional fields.

Params
Results

  • error: errno

  • stat: fdstat The buffer where the file descriptor's attributes are stored.

fdstat_set_flags(fd: fd, flags: fdflags) -> 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

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

filestat_get(fd: fd) -> (errno, filestat)

Return the attributes of an open file.

Params
Results

  • error: errno

  • buf: filestat The buffer where the file's attributes are stored.

filestat_set_size(fd: fd, size: filesize) -> 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
Results

filestat_set_times(fd: fd, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> 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

permissions_set(fd: fd, permissions: permissions) -> errno

Set the permissions of a file or directory.

This sets the permissions associated with a file or directory in a filesystem at the time it is called. The ability to actually access a file or directory may depend on additional permissions not reflected here.

Note: This is similar fchmod in POSIX.

Unlike POSIX, this doesn't expose a user/group/other distinction; implementations in POSIX environments are suggested to consult the umask to determine which of the user/group/other flags to modify.

Params

  • fd: fd

  • permissions: permissions The permissions associated with the file.

Results

pread(fd: fd, iovs: iovec_array, offset: filesize) -> (errno, size)

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: errno

  • nread: size The number of bytes read.

prestat_get(fd: fd) -> (errno, prestat)

Return a description of the given preopened file descriptor.

Params
Results

  • error: errno

  • buf: prestat The buffer where the description is stored.

prestat_dir_name(fd: fd, path: Pointer<char8>, path_len: size) -> errno

Return a description of the given preopened file descriptor.

Params

  • fd: fd

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

  • path_len: size

Results

pwrite(fd: fd, iovs: ciovec_array, offset: filesize) -> (errno, size)

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: errno

  • nwritten: size The number of bytes written.

read(fd: fd, iovs: iovec_array) -> (errno, size)

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: errno

  • nread: size The number of bytes read.

readdir(fd: fd, buf: Pointer<u8>, buf_len: size, cookie: dircookie) -> (errno, size)

Read directory entries from a directory. When successful, the contents of the output buffer consist of a sequence of directory entries. Each directory entry consists of a dirent object, followed by dirent::d_namlen bytes holding the name of the directory entry. This function fills the output buffer as much as possible, potentially truncating the last directory entry. This allows the caller to grow its read buffer size in case it's too small to fit a single large directory entry, or skip the oversized directory entry.

Params

  • 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: errno

  • bufused: size 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.

renumber(fd: fd, to: fd) -> 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

seek(fd: fd, offset: filedelta, whence: whence) -> (errno, filesize)

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: errno

  • newoffset: filesize The new offset of the file descriptor, relative to the start of the file.

sync(fd: fd) -> errno

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

Params
Results

tell(fd: fd) -> (errno, filesize)

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

Params
Results

  • error: errno

  • offset: filesize The current offset of the file descriptor, relative to the start of the file.

write(fd: fd, iovs: ciovec_array) -> (errno, size)

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: errno

  • nwritten: size The number of bytes written.

wasi_ephemeral_path

Imports

Memory

Functions

create_directory(fd: fd, path: string) -> 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

filestat_get(fd: fd, flags: lookupflags, path: string) -> (errno, filestat)

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: errno

  • buf: filestat The buffer where the file's attributes are stored.

filestat_set_times(fd: fd, flags: lookupflags, path: string, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> 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

permissions_set(fd: fd, flags: lookupflags, path: string, permissions: permissions) -> errno

Set the permissions of a file or directory.

This sets the permissions associated with a file or directory in a filesystem at the time it is called. The ability to actually access a file or directory may depend on additional permissions not reflected here.

Note: This is similar to fchmodat in POSIX.

Unlike POSIX, this doesn't expose a user/group/other distinction; implementations in POSIX environments are suggested to consult the umask to determine which of the user/group/other flags to modify.

Params

  • fd: fd

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

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

  • permissions: permissions The permissions to associate with the file.

Results

link(old_fd: fd, old_flags: lookupflags, old_path: string, new_fd: fd, new_path: string) -> 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

open(fd: fd, dirflags: lookupflags, path: string, oflags: oflags, fs_rights_base: rights, fs_rights_inheriting: rights, fdflags: fdflags, permissions: permissions) -> (errno, fd)

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

  • permissions: permissions If a file is created, the filesystem permissions to associate with it.

Results

  • error: errno

  • opened_fd: fd The file descriptor of the file that has been opened.

readlink(fd: fd, path: string, buf: Pointer<char8>, buf_len: size) -> (errno, size)

Read the contents of a symbolic link. Note: This is similar to readlinkat in POSIX.

Params

  • fd: fd

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

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

  • buf_len: size

Results

  • error: errno

  • bufused: size The number of bytes placed in the buffer.

remove_directory(fd: fd, path: string) -> 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

rename(fd: fd, old_path: string, new_fd: fd, new_path: string) -> 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

symlink(old_path: string, fd: fd, new_path: string) -> 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

unlink_file(fd: fd, path: string) -> 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

wasi_ephemeral_poll

Imports

Memory

Functions

oneoff(in: ConstPointer<subscription>, out: Pointer<event>, nsubscriptions: size) -> (errno, size)

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: errno

  • nevents: size The number of events stored.

wasi_ephemeral_proc

Imports

Functions

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

wasi_ephemeral_random

Imports

Memory

Functions

get(buf: Pointer<u8>, buf_len: size) -> 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

wasi_ephemeral_sched

Imports

Functions

yield() -> errno

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

Params
Results

wasi_ephemeral_sock

Imports

Memory

Functions

recv(fd: fd, ri_data: iovec_array, ri_flags: riflags) -> (errno, size, roflags)

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: errno

  • ro_datalen: size Number of bytes stored in ri_data.

  • ro_flags: roflags Message flags.

send(fd: fd, si_data: ciovec_array, si_flags: siflags) -> (errno, size)

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: errno

  • so_datalen: size Number of bytes transmitted.

shutdown(fd: fd, how: sdflags) -> 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