[][src]Crate wasi

Raw API bindings to the WebAssembly System Interface (WASI)

This crate provides Rust API bindings to WASI APIs. All WASI APIs are exported from this crate and provided with the appropriate type signatures. This crate is entirely procedurally generated from the *.witx files that describe the WASI API.

WASI API Version

The WASI API is evolving over time. It is both gaining new features as well as tweaking the ABI of existing features. As a result it's important to understand what version of this crate you're using and how it relates to the WASI version of the spec.

The WASI specification is organized into phases where there is a snapshot at any one point in time describing the current state of the specification. This crate implements a particular snapshot. You can find the snapshot version implemented in this crate in the build metadata of the crate version number. For example something like 0.9.0+wasi-snapshot-preview1 means that this crate's own personal version is 0.9.0 and it implements the wasi-snapshot-preview1 snapshot. A major release of this crate (i.e. bumping the "0.9.0") is expected whenever the generated code changes or a new WASI snapshot is used.

Crate Features

This crate supports one feature, std, which implements the standard Error trait for the exported Error type in this crate. This is enabled by default but can be disabled to make the library no_std compatible.

Modules

wasi_snapshot_preview1

Structs

Ciovec
Dirent
Error

A raw error returned by wasi APIs, internally containing a 16-bit error code.

Event
EventFdReadwrite
Fdstat
Filestat
Iovec
Prestat
PrestatDir
Subscription
SubscriptionClock
SubscriptionFdReadwrite

Constants

ADVICE_DONTNEED

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

ADVICE_NOREUSE

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

ADVICE_NORMAL

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

ADVICE_RANDOM

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

ADVICE_SEQUENTIAL

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

ADVICE_WILLNEED

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

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

CLOCKID_PROCESS_CPUTIME_ID

The CPU-time clock associated with the current process.

CLOCKID_REALTIME

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

CLOCKID_THREAD_CPUTIME_ID

The CPU-time clock associated with the current thread.

ERRNO_2BIG

Argument list too long.

ERRNO_ACCES

Permission denied.

ERRNO_ADDRINUSE

Address in use.

ERRNO_ADDRNOTAVAIL

Address not available.

ERRNO_AFNOSUPPORT

Address family not supported.

ERRNO_AGAIN

Resource unavailable, or operation would block.

ERRNO_ALREADY

Connection already in progress.

ERRNO_BADF

Bad file descriptor.

ERRNO_BADMSG

Bad message.

ERRNO_BUSY

Device or resource busy.

ERRNO_CANCELED

Operation canceled.

ERRNO_CHILD

No child processes.

ERRNO_CONNABORTED

Connection aborted.

ERRNO_CONNREFUSED

Connection refused.

ERRNO_CONNRESET

Connection reset.

ERRNO_DEADLK

Resource deadlock would occur.

ERRNO_DESTADDRREQ

Destination address required.

ERRNO_DOM

Mathematics argument out of domain of function.

ERRNO_DQUOT

Reserved.

ERRNO_EXIST

File exists.

ERRNO_FAULT

Bad address.

ERRNO_FBIG

File too large.

ERRNO_HOSTUNREACH

Host is unreachable.

ERRNO_IDRM

Identifier removed.

ERRNO_ILSEQ

Illegal byte sequence.

ERRNO_INPROGRESS

Operation in progress.

ERRNO_INTR

Interrupted function.

ERRNO_INVAL

Invalid argument.

ERRNO_IO

I/O error.

ERRNO_ISCONN

Socket is connected.

ERRNO_ISDIR

Is a directory.

ERRNO_LOOP

Too many levels of symbolic links.

ERRNO_MFILE

File descriptor value too large.

ERRNO_MLINK

Too many links.

ERRNO_MSGSIZE

Message too large.

ERRNO_MULTIHOP

Reserved.

ERRNO_NAMETOOLONG

Filename too long.

ERRNO_NETDOWN

Network is down.

ERRNO_NETRESET

Connection aborted by network.

ERRNO_NETUNREACH

Network unreachable.

ERRNO_NFILE

Too many files open in system.

ERRNO_NOBUFS

No buffer space available.

ERRNO_NODEV

No such device.

ERRNO_NOENT

No such file or directory.

ERRNO_NOEXEC

Executable file format error.

ERRNO_NOLCK

No locks available.

ERRNO_NOLINK

Reserved.

ERRNO_NOMEM

Not enough space.

ERRNO_NOMSG

No message of the desired type.

ERRNO_NOPROTOOPT

Protocol not available.

ERRNO_NOSPC

No space left on device.

ERRNO_NOSYS

Function not supported.

ERRNO_NOTCAPABLE

Extension: Capabilities insufficient.

ERRNO_NOTCONN

The socket is not connected.

ERRNO_NOTDIR

Not a directory or a symbolic link to a directory.

ERRNO_NOTEMPTY

Directory not empty.

ERRNO_NOTRECOVERABLE

State not recoverable.

ERRNO_NOTSOCK

Not a socket.

ERRNO_NOTSUP

Not supported, or operation not supported on socket.

ERRNO_NOTTY

Inappropriate I/O control operation.

ERRNO_NXIO

No such device or address.

ERRNO_OVERFLOW

Value too large to be stored in data type.

ERRNO_OWNERDEAD

Previous owner died.

ERRNO_PERM

Operation not permitted.

ERRNO_PIPE

Broken pipe.

ERRNO_PROTO

Protocol error.

ERRNO_PROTONOSUPPORT

Protocol not supported.

ERRNO_PROTOTYPE

Protocol wrong type for socket.

ERRNO_RANGE

Result too large.

ERRNO_ROFS

Read-only file system.

ERRNO_SPIPE

Invalid seek.

ERRNO_SRCH

No such process.

ERRNO_STALE

Reserved.

ERRNO_SUCCESS

No error occurred. System call completed successfully.

ERRNO_TIMEDOUT

Connection timed out.

ERRNO_TXTBSY

Text file busy.

ERRNO_XDEV

Cross-device link.

EVENTRWFLAGS_FD_READWRITE_HANGUP

The peer of this socket has closed or disconnected.

EVENTTYPE_CLOCK

The time value of clock subscription::u.clock.clock_id has reached timestamp subscription::u.clock.timeout.

EVENTTYPE_FD_READ

File descriptor subscription::u.fd_readwrite.fd has data available for reading. This event always triggers for regular files.

EVENTTYPE_FD_WRITE

File descriptor subscription::u.fd_readwrite.fd has capacity available for writing. This event always triggers for regular files.

FDFLAGS_APPEND

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

FDFLAGS_DSYNC

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

FDFLAGS_NONBLOCK

Non-blocking mode.

FDFLAGS_RSYNC

Synchronized read I/O operations.

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

FILETYPE_BLOCK_DEVICE

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

FILETYPE_CHARACTER_DEVICE

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

FILETYPE_DIRECTORY

The file descriptor or file refers to a directory inode.

FILETYPE_REGULAR_FILE

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

FILETYPE_SOCKET_DGRAM

The file descriptor or file refers to a datagram socket.

FILETYPE_SOCKET_STREAM

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

FILETYPE_SYMBOLIC_LINK

The file refers to a symbolic link inode.

FILETYPE_UNKNOWN

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

FSTFLAGS_ATIM

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

FSTFLAGS_ATIM_NOW

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

FSTFLAGS_MTIM

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

FSTFLAGS_MTIM_NOW

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

LOOKUPFLAGS_SYMLINK_FOLLOW

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

OFLAGS_CREAT

Create file if it does not exist.

OFLAGS_DIRECTORY

Fail if not a directory.

OFLAGS_EXCL

Fail if file already exists.

OFLAGS_TRUNC

Truncate file to size 0.

PREOPENTYPE_DIR

A pre-opened directory.

RIFLAGS_RECV_PEEK

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

RIFLAGS_RECV_WAITALL

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

RIGHTS_FD_ADVISE

The right to invoke fd_advise.

RIGHTS_FD_ALLOCATE

The right to invoke fd_allocate.

RIGHTS_FD_DATASYNC

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

RIGHTS_FD_FDSTAT_SET_FLAGS

The right to invoke fd_fdstat_set_flags.

RIGHTS_FD_FILESTAT_GET

The right to invoke fd_filestat_get.

RIGHTS_FD_FILESTAT_SET_SIZE

The right to invoke fd_filestat_set_size.

RIGHTS_FD_FILESTAT_SET_TIMES

The right to invoke fd_filestat_set_times.

RIGHTS_FD_READ

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

RIGHTS_FD_READDIR

The right to invoke fd_readdir.

RIGHTS_FD_SEEK

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

RIGHTS_FD_SYNC

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

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

RIGHTS_FD_WRITE

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

RIGHTS_PATH_CREATE_DIRECTORY

The right to invoke path_create_directory.

RIGHTS_PATH_CREATE_FILE

If path_open is set, the right to invoke path_open with oflags::creat.

RIGHTS_PATH_FILESTAT_GET

The right to invoke path_filestat_get.

RIGHTS_PATH_FILESTAT_SET_SIZE

The right to change a file's size (there is no path_filestat_set_size). If path_open is set, includes the right to invoke path_open with oflags::trunc.

RIGHTS_PATH_FILESTAT_SET_TIMES

The right to invoke path_filestat_set_times.

RIGHTS_PATH_LINK_SOURCE

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

RIGHTS_PATH_LINK_TARGET

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

RIGHTS_PATH_OPEN

The right to invoke path_open.

RIGHTS_PATH_READLINK

The right to invoke path_readlink.

RIGHTS_PATH_REMOVE_DIRECTORY

The right to invoke path_remove_directory.

RIGHTS_PATH_RENAME_SOURCE

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

RIGHTS_PATH_RENAME_TARGET

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

RIGHTS_PATH_SYMLINK

The right to invoke path_symlink.

RIGHTS_PATH_UNLINK_FILE

The right to invoke path_unlink_file.

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

RIGHTS_SOCK_SHUTDOWN

The right to invoke sock_shutdown.

ROFLAGS_RECV_DATA_TRUNCATED

Returned by sock_recv: Message data has been truncated.

SDFLAGS_RD

Disables further receive operations.

SDFLAGS_WR

Disables further send operations.

SIGNAL_ABRT

Process abort signal. Action: Terminates the process.

SIGNAL_ALRM

Alarm clock. Action: Terminates the process.

SIGNAL_BUS

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

SIGNAL_CHLD

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

SIGNAL_CONT

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

SIGNAL_FPE

Erroneous arithmetic operation. Action: Terminates the process.

SIGNAL_HUP

Hangup. Action: Terminates the process.

SIGNAL_ILL

Illegal instruction. Action: Terminates the process.

SIGNAL_INT

Terminate interrupt signal. Action: Terminates the process.

SIGNAL_KILL

Kill. Action: Terminates the process.

SIGNAL_NONE

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

SIGNAL_PIPE

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

SIGNAL_POLL

I/O possible. Action: Terminates the process.

SIGNAL_PROF

Profiling timer expired. Action: Terminates the process.

SIGNAL_PWR

Power failure. Action: Terminates the process.

SIGNAL_QUIT

Terminal quit signal. Action: Terminates the process.

SIGNAL_SEGV

Invalid memory reference. Action: Terminates the process.

SIGNAL_STOP

Stop executing. Action: Stops executing.

SIGNAL_SYS

Bad system call. Action: Terminates the process.

SIGNAL_TERM

Termination signal. Action: Terminates the process.

SIGNAL_TRAP

Trace/breakpoint trap. Action: Terminates the process.

SIGNAL_TSTP

Terminal stop signal. Action: Stops executing.

SIGNAL_TTIN

Background process attempting read. Action: Stops executing.

SIGNAL_TTOU

Background process attempting write. Action: Stops executing.

SIGNAL_URG

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

SIGNAL_USR1

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

SIGNAL_USR2

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

SIGNAL_VTALRM

Virtual timer expired. Action: Terminates the process.

SIGNAL_WINCH

Window changed. Action: Ignored.

SIGNAL_XCPU

CPU time limit exceeded. Action: Terminates the process.

SIGNAL_XFSZ

File size limit exceeded. Action: Terminates the process.

SUBCLOCKFLAGS_SUBSCRIPTION_CLOCK_ABSTIME

If set, treat the timestamp provided in subscription::u.clock.timeout as an absolute timestamp of clock subscription::u.clock.clock_id. If clear, treat the timestamp provided in subscription::u.clock.timeout relative to the current time value of clock subscription::u.clock.clock_id.

WHENCE_CUR

Seek relative to current position.

WHENCE_END

Seek relative to end-of-file.

WHENCE_SET

Seek relative to start-of-file.

Functions

args_get

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

args_sizes_get

Return command-line argument data sizes.

clock_res_get

Return the resolution of a clock. Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return WASI_EINVAL Note: This is similar to clock_getres in POSIX.

clock_time_get

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

environ_get

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

environ_sizes_get

Return command-line argument data sizes.

fd_advise

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

fd_allocate

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

fd_close

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

fd_datasync

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

fd_fdstat_get

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

fd_fdstat_set_flags

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

fd_fdstat_set_rights

Adjust the rights associated with a file descriptor. This can only be used to remove rights, and returns ENOTCAPABLE if called in a way that would attempt to add rights

fd_filestat_get

Return the attributes of an open file.

fd_filestat_set_size

Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. Note: This is similar to ftruncate in POSIX.

fd_filestat_set_times

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

fd_pread

Read from a file descriptor, without using and updating the file descriptor's offset. Note: This is similar to preadv in POSIX.

fd_prestat_dir_name

Return a description of the given preopened file descriptor.

fd_prestat_get

Return a description of the given preopened file descriptor.

fd_pwrite

Write to a file descriptor, without using and updating the file descriptor's offset. Note: This is similar to pwritev in POSIX.

fd_read

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

fd_readdir

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

fd_renumber

Atomically replace a file descriptor by renumbering another file descriptor. Due to the strong focus on thread safety, this environment does not provide a mechanism to duplicate or renumber a file descriptor to an arbitrary number, like dup2(). This would be prone to race conditions, as an actual file descriptor with the same number could be allocated by a different thread at the same time. This function provides a way to atomically renumber file descriptors, which would disappear if dup2() were to be removed entirely.

fd_seek

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

fd_sync

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

fd_tell

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

fd_write

Write to a file descriptor. Note: This is similar to writev in POSIX.

path_create_directory

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

path_filestat_get

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

path_filestat_set_times

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

path_link

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

path_open

Open a file or directory. The returned file descriptor is not guaranteed to be the lowest-numbered file descriptor not currently open; it is randomized to prevent applications from depending on making assumptions about indexes, since this is error-prone in multi-threaded contexts. The returned file descriptor is guaranteed to be less than 2**31. Note: This is similar to openat in POSIX.

path_readlink

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

path_remove_directory

Remove a directory. Return ENOTEMPTY if the directory is not empty. Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

path_rename

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

path_symlink

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

path_unlink_file

Unlink a file. Return EISDIR if the path refers to a directory. Note: This is similar to unlinkat(fd, path, 0) in POSIX.

poll_oneoff

Concurrently poll for the occurrence of a set of events.

proc_exit

Terminate the process normally. An exit code of 0 indicates successful termination of the program. The meanings of other values is dependent on the environment.

proc_raise

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

random_get

Write high-quality random data into a buffer. This function blocks when the implementation is unable to immediately provide sufficient high-quality random data. This function may execute slowly, so when large mounts of random data are required, it's advisable to use this function to seed a pseudo-random number generator, rather than to provide the random data directly.

sched_yield

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

sock_recv

Receive a message from a socket. Note: This is similar to recv in POSIX, though it also supports reading the data into multiple buffers in the manner of readv.

sock_send

Send a message on a socket. Note: This is similar to send in POSIX, though it also supports writing the data from multiple buffers in the manner of writev.

sock_shutdown

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

Type Definitions

Advice
CiovecArray
Clockid
Device
Dircookie
Dirnamlen
Errno
Eventrwflags
Eventtype
Exitcode
Fd
Fdflags
Filedelta
Filesize
Filetype
Fstflags
Inode
IovecArray
Linkcount
Lookupflags
Oflags
Preopentype
Result
Riflags
Rights
Roflags
Sdflags
Siflags
Signal
Size
Subclockflags
Timestamp
Userdata
Whence

Unions

EventU
PrestatU
SubscriptionU