Crate wasix

source ·
Expand description

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

Structs

Constants

Functions

  • args_get⚠
    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.
  • args_sizes_get⚠
    Return command-line argument data sizes.
  • bus_call⚠
    Invokes a call within a running bus process.
  • bus_close⚠
    Closes a bus process and releases all associated resources
  • bus_open_local⚠
    Spawns a new bus process for a particular web WebAssembly binary that is referenced by its process name.
  • bus_open_remote⚠
    Spawns a new bus process for a particular web WebAssembly binary that is referenced by its process name on a remote instance.
  • bus_poll⚠
    Polls for any outstanding events from a particular bus process by its handle
  • bus_subcall⚠
    Invokes a call within the context of another call
  • call_close⚠
    Closes a bus call based on its bus call handle
  • call_fault⚠
    Causes a fault on a particular call that was made to this process from another process; where ‘bid’ is the callering process context.
  • call_reply⚠
    Replies to a call that was made to this process from another process; where ‘cid’ is the call context. This will may also drop the handle and release any associated resources (if keepalive is not set)
  • callback_reactor⚠
    Registers a callback function for reactors
  • callback_signal⚠
    Registers a callback function for signals
  • callback_thread⚠
    Registers a callback function for new threads
  • callback_thread_local_destroy⚠
    Registers a callback function for destruction of thread locals
  • chdir⚠
    Sets the current working directory
  • 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 errno::inval. 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.
  • clock_time_set⚠
    Sets the time value of a clock. Note: This is similar to clock_settime in POSIX.
  • environ_get⚠
    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.
  • environ_sizes_get⚠
    Return environment variable 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_dup⚠
    Atomically duplicate a file handle.
  • fd_event⚠
    Creates a file handle for event notifications
  • 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 errno::notcapable 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_pipe⚠
    Opens a pipe with two file handles
  • 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 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.
  • 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.
  • futex_wait⚠
    Wait for a futex_wake operation to wake us. Returns with EINVAL if the futex doesn’t hold the expected value. Returns false on timeout, and true in all other cases.
  • futex_wake⚠
    Wake up one thread that’s blocked on futex_wait on this futex. Returns true if this actually woke up such a thread, or false if no thread was waiting on this futex.
  • futex_wake_all⚠
    Wake up all threads that are waiting on futex_wait on this futex.
  • getcwd⚠
    Returns the current working directory If the path exceeds the size of the buffer then this function will fill the path_len with the needed size and return EOVERFLOW
  • http_request⚠
    Makes a HTTP request to a remote web resource and returns a socket handles that are used to send and receive data
  • http_status⚠
    Retrieves the status of a HTTP request
  • 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 errno::notempty 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 errno::isdir 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.
  • port_addr_add⚠
    Adds another static address to the local port
  • port_addr_clear⚠
    Clears all the addresses on the local port
  • port_addr_list⚠
    Returns a list of all the addresses owned by the local port This function fills the output buffer as much as possible. If the buffer is not big enough then the naddrs address will be filled with the buffer size needed and the EOVERFLOW will be returned
  • port_addr_remove⚠
    Removes an address from the local port
  • port_bridge⚠
    Securely connects to a particular remote network
  • port_dhcp_acquire⚠
    Acquires a set of addresses using DHCP
  • port_gateway_set⚠
    Adds a default gateway to the port
  • port_mac⚠
    Returns the MAC address of the local port
  • port_route_add⚠
    Adds a new route to the local port
  • port_route_clear⚠
    Clears all the routes in the local port
  • port_route_list⚠
    Returns a list of all the routes owned by the local port This function fills the output buffer as much as possible. If the buffer is too small this will return EOVERFLOW and fill nroutes with the size of the buffer needed.
  • port_route_remove⚠
    Removes an existing route from the local port
  • port_unbridge⚠
    Disconnects from a remote network
  • proc_exec⚠
    execve() executes the program referred to by pathname. This causes the program that is currently being run by the calling process to be replaced with a new program, with newly initialized stack, heap, and (initialized and uninitialized) data segments
  • 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_fork⚠
    Forks the current process into a new subprocess. If the function returns a zero then its the new subprocess. If it returns a positive number then its the current process and the $pid represents the child.
  • proc_id⚠
    Returns the handle of the current process
  • proc_join⚠
    Wait for process to exit
  • proc_parent⚠
    Returns the parent handle of a particular process
  • proc_raise⚠
    Send a signal to the process of the calling thread. Note: This is similar to raise in POSIX.
  • proc_raise_interval⚠
    Send a signal to the process of the calling thread on a regular basis Note: This is similar to setitimer in POSIX.
  • proc_signal⚠
    Sends a signal to a process
  • proc_spawn⚠
    Spawns a new process within the context of this machine
  • 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.
  • resolve⚠
    Resolves a hostname and a port to one or more IP addresses.
  • sched_yield⚠
    Temporarily yield execution of the calling thread. Note: This is similar to sched_yield in POSIX.
  • sock_accept⚠
    Accept a new incoming connection. Note: This is similar to accept in POSIX.
  • sock_addr_local⚠
    Returns the local address to which the socket is bound.
  • sock_addr_peer⚠
    Returns the remote address to which the socket is connected to.
  • sock_bind⚠
    Bind a socket Note: This is similar to bind in POSIX using PF_INET
  • sock_connect⚠
    Initiate a connection on a socket to the specified address
  • sock_get_opt_flag⚠
    Retrieve status of particular socket seting Note: This is similar to getsockopt in POSIX for SO_REUSEADDR
  • sock_get_opt_size⚠
    Retrieve the size of particular option for this socket Note: This is similar to getsockopt in POSIX for SO_RCVBUF
  • sock_get_opt_time⚠
    Retrieve one of the times on the socket
  • sock_join_multicast_v4⚠
    Joins a particular multicast IPv4 group
  • sock_join_multicast_v6⚠
    Joins a particular multicast IPv6 group
  • sock_leave_multicast_v4⚠
    Leaves a particular multicast IPv4 group
  • sock_leave_multicast_v6⚠
    Leaves a particular multicast IPv6 group
  • sock_listen⚠
    Listen for connections on a socket
  • sock_open⚠
    Create an endpoint for communication.
  • 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_recv_from⚠
    Receive a message and its peer address from a socket. Note: This is similar to recvfrom 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_send_file⚠
    Sends the entire contents of a file down a socket
  • sock_send_to⚠
    Send a message on a socket to a specific address. Note: This is similar to sendto in POSIX, though it also supports writing the data from multiple buffers in the manner of writev.
  • sock_set_opt_flag⚠
    Sets a particular socket setting Note: This is similar to setsockopt in POSIX for SO_REUSEADDR
  • sock_set_opt_size⚠
    Set size of particular option for this socket Note: This is similar to setsockopt in POSIX for SO_RCVBUF
  • sock_set_opt_time⚠
    Sets one of the times the socket
  • sock_shutdown⚠
    Shut down socket send and receive channels. Note: This is similar to shutdown in POSIX.
  • sock_status⚠
    Returns the current status of a socket
  • stack_checkpoint⚠
    Creates a checkpoint of the current stack which allows it to be restored later using its stack hash. The value supplied will be returned upon restoration (and hence must be none zero) - zero will be returned when the stack is first recorded. This function will read the __stack_pointer global
  • stack_restore⚠
    Restores the current stack to a previous stack described by a supplied stack snapshot. This function will manipulate the __stack_pointer global
  • thread_exit⚠
    Terminates the current running thread, if this is the last thread then the process will also exit with the specified exit code. An exit code of 0 indicates successful termination of the thread. The meanings of other values is dependent on the environment.
  • thread_id⚠
    Returns the index of the current thread (threads indices are sequencial from zero)
  • thread_join⚠
    Joins this thread with another thread, blocking this one until the other finishes
  • thread_local_create⚠
    Create a thread local variable If The web assembly process exports function named ‘_thread_local_destroy’ then it will be invoked when the thread goes out of scope and dies.
  • thread_local_destroy⚠
    Destroys a thread local variable
  • thread_local_get⚠
    Gets the value of a thread local variable
  • thread_local_set⚠
    Sets the value of a thread local variable
  • thread_parallelism⚠
    Returns the available parallelism which is normally the number of available cores that can run concurrently
  • thread_signal⚠
    Sends a signal to a thread
  • thread_sleep⚠
    Sends the current thread to sleep for a period of time
  • thread_spawn⚠
    Creates a new thread by spawning that shares the same memory address space, file handles and main event loops. The web assembly process must export function named ‘wasi_thread_start’
  • tty_get⚠
    Retrieves the current state of the TTY
  • tty_set⚠
    Updates the properties of the rect
  • ws_connect⚠
    Connects to a websocket at a particular network URL

Type Definitions

Unions