@ 261013.2raw
current
<(git log)

World command

Import interface wasi:cli/environment@0.3.2

Functions

get-environment: func

Get the POSIX-style environment variables.

Each environment variable is provided as a pair of string variable names and string value.

Morally, these are a value import, but until value imports are available in the component model, this import function should return the same values each time it is called.

Return values

get-arguments: func

Get the POSIX-style arguments to the program.

Return values

get-initial-cwd: func

Return a path that programs should use as their initial current working directory, interpreting . as shorthand for this.

Return values

Import interface wasi:cli/exit@0.3.2

Functions

exit: func

Exit the current instance and any linked instances.

Params

exit-with-code: func

Exit the current instance and any linked instances, reporting the specified status code to the host.

The meaning of the code depends on the context, with 0 usually meaning "success", and other values indicating various types of failure.

This function does not return; the effect is analogous to a trap, but without the connotation that something bad has happened.

Params

Import interface wasi:cli/types@0.3.2

Types

enum error-code

Enum Cases

Import interface wasi:cli/stdin@0.3.2

Types

type error-code

error-code

Functions

read-via-stream: func

Return a stream for reading from stdin.

This function returns a stream which provides data read from stdin, and a future to signal read results.

If the stream's readable end is dropped the future will resolve to success.

If the stream's writable end is dropped the future will either resolve to success if stdin was closed by the writer or to an error-code if reading failed for some other reason.

Multiple streams may be active at the same time. The behavior of concurrent reads is implementation-specific.

Return values

Import interface wasi:cli/stdout@0.3.2

Types

type error-code

error-code

Functions

write-via-stream: func

Write the given stream to stdout.

If the stream's writable end is dropped this function will either return success once the entire contents of the stream have been written or an error-code representing a failure.

Otherwise if there is an error the readable end of the stream will be dropped and this function will return an error-code.

Params
Return values

Import interface wasi:cli/stderr@0.3.2

Types

type error-code

error-code

Functions

write-via-stream: func

Write the given stream to stderr.

If the stream's writable end is dropped this function will either return success once the entire contents of the stream have been written or an error-code representing a failure.

Otherwise if there is an error the readable end of the stream will be dropped and this function will return an error-code.

Params
Return values

Import interface wasi:cli/terminal-input@0.3.2

Terminal input.

In the future, this may include functions for disabling echoing, disabling input buffering so that keyboard events are sent through immediately, querying supported features, and so on.

Types

resource terminal-input

The input side of a terminal.

Import interface wasi:cli/terminal-output@0.3.2

Terminal output.

In the future, this may include functions for querying the terminal size, being notified of terminal size changes, querying supported features, and so on.

Types

resource terminal-output

The output side of a terminal.

Import interface wasi:cli/terminal-stdin@0.3.2

An interface providing an optional terminal-input for stdin as a link-time authority.

Types

type terminal-input

terminal-input

Functions

get-terminal-stdin: func

If stdin is connected to a terminal, return a terminal-input handle allowing further interaction with it.

Return values

Import interface wasi:cli/terminal-stdout@0.3.2

An interface providing an optional terminal-output for stdout as a link-time authority.

Types

type terminal-output

terminal-output

Functions

get-terminal-stdout: func

If stdout is connected to a terminal, return a terminal-output handle allowing further interaction with it.

Return values

Import interface wasi:cli/terminal-stderr@0.3.2

An interface providing an optional terminal-output for stderr as a link-time authority.

Types

type terminal-output

terminal-output

Functions

get-terminal-stderr: func

If stderr is connected to a terminal, return a terminal-output handle allowing further interaction with it.

Return values

Import interface wasi:clocks/types@0.3.2

This interface common types used throughout wasi:clocks.

Types

type duration

u64

A duration of time, in nanoseconds.

Import interface wasi:clocks/monotonic-clock@0.3.2

WASI Monotonic Clock is a clock API intended to let users measure elapsed time.

It is intended to be portable at least between Unix-family platforms and Windows.

A monotonic clock is a clock which has an unspecified initial value, and successive reads of the clock will produce non-decreasing values.

Types

type duration

duration

type mark

u64

A mark on a monotonic clock is a number of nanoseconds since an unspecified initial value, and can only be compared to instances from the same monotonic-clock.

Functions

now: func

Read the current value of the clock.

The clock is monotonic, therefore calling this function repeatedly will produce a sequence of non-decreasing values.

For completeness, this function traps if it's not possible to represent the value of the clock in a mark. Consequently, implementations should ensure that the starting time is low enough to avoid the possibility of overflow in practice.

Return values

get-resolution: func

Query the resolution of the clock. Returns the duration of time corresponding to a clock tick.

Return values

wait-until: func

Wait until the specified mark has occurred.

Params

wait-for: func

Wait for the specified duration to elapse.

Params

Import interface wasi:clocks/system-clock@0.3.2

WASI System Clock is a clock API intended to let users query the current time. The clock is not necessarily monotonic as it may be reset.

It is intended to be portable at least between Unix-family platforms and Windows.

External references may be reset, so this clock is not necessarily monotonic, making it unsuitable for measuring elapsed time.

It is intended for reporting the current date and time for humans.

Types

type duration

duration

record instant

An "instant", or "exact time", is a point in time without regard to any time zone: just the time since a particular external reference point, often called an "epoch".

Here, the epoch is 1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, also known as Unix Time.

Note that even if the seconds field is negative, incrementing nanoseconds always represents moving forwards in time. For example, { -1 seconds, 999999999 nanoseconds } represents the instant one nanosecond before the epoch. For more on various different ways to represent time, see https://tc39.es/proposal-temporal/docs/timezone.html

Record Fields

Functions

now: func

Read the current value of the clock.

This clock is not monotonic, therefore calling this function repeatedly will not necessarily produce a sequence of non-decreasing values.

The nanoseconds field of the output is always less than 1000000000.

Return values

get-resolution: func

Query the resolution of the clock. Returns the smallest duration of time that the implementation permits distinguishing.

Return values

Import interface wasi:clocks/timezone@0.3.2

Types

type instant

instant

Functions

iana-id: func

Return the IANA identifier of the currently configured timezone. This should be an identifier from the IANA Time Zone Database.

For displaying to a user, the identifier should be converted into a localized name by means of an internationalization API.

If the implementation does not expose an actual timezone, or is unable to provide mappings from times to deltas between the configured timezone and UTC, or determining the current timezone fails, or the timezone does not have an IANA identifier, this returns nothing.

Return values

utc-offset: func

The number of nanoseconds difference between UTC time and the local time of the currently configured timezone, at the exact time of instant.

The magnitude of the returned value will always be less than 86,400,000,000,000 which is the number of nanoseconds in a day (246060*1e9).

If the implementation does not expose an actual timezone, or is unable to provide mappings from times to deltas between the configured timezone and UTC, or determining the current timezone fails, this returns nothing.

Params
Return values

to-debug-string: func

Returns a string that is suitable to assist humans in debugging whether any timezone is available, and if so, which. This may be the same string as iana-id, or a formatted representation of the UTC offset such as -04:00, or something else.

WARNING: The returned string should not be consumed mechanically! It may change across platforms, hosts, or other implementation details. Parsing this string is a major platform-compatibility hazard.

Return values

Import interface wasi:filesystem/types@0.3.2

WASI filesystem is a filesystem API primarily intended to let users run WASI programs that access their files on their existing filesystems, without significant overhead.

Paths are passed as interface-type strings, meaning they must consist of a sequence of Unicode Scalar Values (USVs). Some filesystems may contain paths which are not accessible by this API.

The directory separator in WASI is always the forward-slash (/).

All paths in WASI are relative paths, and are interpreted relative to a descriptor referring to a base directory. If a path argument to any WASI function starts with /, or if any step of resolving a path, including .. and symbolic link steps, reaches a directory outside of the base directory, or reaches a symlink to an absolute or rooted path in the underlying filesystem, the function fails with error-code::not-permitted.

For more information about WASI path resolution and sandboxing, see WASI filesystem path resolution.

Though this package presents a portable interface modelled on POSIX, it prioritizes compatibility over portability: allowing users to access their files on their machine is more important than exposing a single semantics across all platforms. Notably, depending on the underlying operating system and file system:

Users that need well-defined, portable semantics should use a key-value store or a database instead.

Types

type instant

instant

type filesize

u64

File size or length of a region within a file.

variant descriptor-type

The type of a filesystem object referenced by a descriptor.

Note: This was called filetype in earlier versions of WASI.

Variant Cases

flags descriptor-flags

Descriptor flags.

Note: This was called fdflags in earlier versions of WASI.

Flags members

flags path-flags

Flags determining the method of how paths are resolved.

Flags members

flags open-flags

Open flags used by open-at.

Flags members

type link-count

u64

Number of hard links to an inode.

record descriptor-stat

File attributes.

Note: This was called filestat in earlier versions of WASI.

Record Fields

variant new-timestamp

When setting a timestamp, this gives the value to set it to.

Variant Cases

record directory-entry

A directory entry.

Record Fields

variant error-code

Error codes returned by functions, similar to errno in POSIX. 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.

Variant Cases

enum advice

File or memory access pattern advisory information.

Enum Cases

record metadata-hash-value

A 128-bit hash value, split into parts because wasm doesn't have a 128-bit integer type.

Record Fields

resource descriptor

A descriptor is a reference to a filesystem object, which may be a file, directory, named pipe, special file, or other object on which filesystem calls may be made.

Functions

[method]descriptor.read-via-stream: func

Return a stream for reading from a file.

Multiple read, write, and append streams may be active on the same open file and they do not interfere with each other.

This function returns a stream which provides the data received from the file, and a future providing additional error information in case an error is encountered.

If no error is encountered, stream.read on the stream will return read-status::closed with no error-context and the future resolves to the value ok. If an error is encountered, stream.read on the stream returns read-status::closed with an error-context and the future resolves to err with an error-code.

Note: This is similar to pread in POSIX.

Params
Return values

[method]descriptor.write-via-stream: func

Return a stream for writing to a file, if available.

May fail with an error-code describing why the file cannot be written.

It is valid to write past the end of a file; the file is extended to the extent of the write, with bytes between the previous end and the start of the write set to zero.

This function returns once either full contents of the stream are written or an error is encountered.

Note: This is similar to pwrite in POSIX.

Params
Return values

[method]descriptor.append-via-stream: func

Return a stream for appending to a file, if available.

May fail with an error-code describing why the file cannot be appended.

This function returns once either full contents of the stream are written or an error is encountered.

Note: This is similar to write with O_APPEND in POSIX.

Params
Return values

[method]descriptor.advise: func

Provide file advisory information on a descriptor.

This is similar to posix_fadvise in POSIX.

Params
Return values

[method]descriptor.sync-data: func

Synchronize the data of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fdatasync in POSIX.

Params
Return values

[method]descriptor.get-flags: func

Get flags associated with a descriptor.

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

Note: This returns the value that was the fs_flags value returned from fdstat_get in earlier versions of WASI.

Params
Return values

[method]descriptor.get-type: func

Get the dynamic type of a descriptor.

Note: This returns the same value as the type field of the fd-stat returned by stat, stat-at and similar.

Note: This returns similar flags to the st_mode & S_IFMT value provided by fstat in POSIX.

Note: This returns the value that was the fs_filetype value returned from fdstat_get in earlier versions of WASI.

Params
Return values

[method]descriptor.set-size: func

Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros.

Note: This was called fd_filestat_set_size in earlier versions of WASI.

Params
Return values

[method]descriptor.set-times: func

Adjust the timestamps of an open file or directory.

Note: This is similar to futimens in POSIX.

Note: This was called fd_filestat_set_times in earlier versions of WASI.

Params
Return values

[method]descriptor.read-directory: func

Read directory entries from a directory.

On filesystems where directories contain entries referring to themselves and their parents, often named . and .. respectively, these entries are omitted.

This always returns a new stream which starts at the beginning of the directory. Multiple streams may be active on the same directory, and they do not interfere with each other.

This function returns a future, which will resolve to an error code if reading full contents of the directory fails.

Params
Return values

[method]descriptor.sync: func

Synchronize the data and metadata of a file to disk.

This function succeeds with no effect if the file descriptor is not opened for writing.

Note: This is similar to fsync in POSIX.

Params
Return values

[method]descriptor.create-directory-at: func

Create a directory.

Note: This is similar to mkdirat in POSIX.

Params
Return values

[method]descriptor.stat: func

Return the attributes of an open file or directory.

Note: This is similar to fstat in POSIX, except that it does not return device and inode information. For testing whether two descriptors refer to the same underlying filesystem object, use is-same-object. To obtain additional data that can be used do determine whether a file has been modified, use metadata-hash.

Note: This was called fd_filestat_get in earlier versions of WASI.

Params
Return values

[method]descriptor.stat-at: func

Return the attributes of a file or directory.

Note: This is similar to fstatat in POSIX, except that it does not return device and inode information. See the stat description for a discussion of alternatives.

Note: This was called path_filestat_get in earlier versions of WASI.

Params
Return values

[method]descriptor.set-times-at: func

Adjust the timestamps of a file or directory.

Note: This is similar to utimensat in POSIX.

Note: This was called path_filestat_set_times in earlier versions of WASI.

Params
Return values

[method]descriptor.link-at: func

Create a hard link.

Fails with error-code::no-entry if the old path does not exist, with error-code::exist if the new path already exists, and error-code::not-permitted if the old path is not a file.

Note: This is similar to linkat in POSIX.

Params
Return values

[method]descriptor.open-at: func

Open a file or directory.

If flags contains descriptor-flags::mutate-directory, and the base descriptor doesn't have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

If flags contains write or mutate-directory, or open-flags contains truncate or create, and the base descriptor doesn't have descriptor-flags::mutate-directory set, open-at fails with error-code::read-only.

Note: This is similar to openat in POSIX.

Params
Return values

[method]descriptor.readlink-at: func

Read the contents of a symbolic link.

If the contents contain an absolute or rooted path in the underlying filesystem, this function fails with error-code::not-permitted.

Note: This is similar to readlinkat in POSIX.

Params
Return values

[method]descriptor.remove-directory-at: func

Remove a directory.

Return error-code::not-empty if the directory is not empty.

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

Params
Return values

[method]descriptor.rename-at: func

Rename a filesystem object.

Note: This is similar to renameat in POSIX.

Params
Return values

[method]descriptor.symlink-at: func

Create a symbolic link (also known as a "symlink").

If old-path starts with /, the function fails with error-code::not-permitted.

Note: This is similar to symlinkat in POSIX.

Params
Return values

[method]descriptor.unlink-file-at: func

Unlink a filesystem object that is not a directory.

This is similar to unlinkat(fd, path, 0) in POSIX.

Error returns are as specified by POSIX.

If the filesystem object is a directory, error-code::access or error-code::is-directory may be returned instead of the POSIX-specified error-code::not-permitted.

Params
Return values

[method]descriptor.is-same-object: func

Test whether two descriptors refer to the same filesystem object.

In POSIX, this corresponds to testing whether the two descriptors have the same device (st_dev) and inode (st_ino or d_ino) numbers. wasi-filesystem does not expose device and inode numbers, so this function may be used instead.

Params
Return values

[method]descriptor.metadata-hash: func

Return a hash of the metadata associated with a filesystem object referred to by a descriptor.

This returns a hash of the last-modification timestamp and file size, and may also include the inode number, device number, birth timestamp, and other metadata fields that may change when the file is modified or replaced. It may also include a secret value chosen by the implementation and not otherwise exposed.

Implementations are encouraged to provide the following properties:

However, none of these is required.

Params
Return values

[method]descriptor.metadata-hash-at: func

Return a hash of the metadata associated with a filesystem object referred to by a directory descriptor and a relative path.

This performs the same hash computation as metadata-hash.

Params
Return values

Import interface wasi:filesystem/preopens@0.3.2

Types

type descriptor

descriptor

Functions

get-directories: func

Return the set of preopened directories, and their paths.

Return values

Import interface wasi:sockets/types@0.3.2

Types

type duration

duration

variant error-code

Error codes.

In theory, every API can return any error code. In practice, API's typically only return the errors documented per API combined with a couple of errors that are always possible:

See each individual API for what the POSIX equivalents are. They sometimes differ per API.

Variant Cases

enum ip-address-family

Enum Cases

tuple ipv4-address

Tuple Fields

tuple ipv6-address

Tuple Fields

variant ip-address

Variant Cases

record ipv4-socket-address

Record Fields

record ipv6-socket-address

Record Fields

variant ip-socket-address

Variant Cases

resource tcp-socket

A TCP socket resource.

The socket can be in one of the following states:

Note: Except where explicitly mentioned, whenever this documentation uses the term "bound" without backticks it actually means: in the bound state or higher. (i.e. bound, listening, connecting or connected)

WASI uses shared ownership semantics: the tcp-socket handle and all derived stream and future values reference a single underlying OS socket:

The OS socket is closed only after the last handle is dropped. This model has observable effects; for example, it affects when the local port binding is released.

In addition to the general error codes documented on the types::error-code type, TCP socket methods may always return error(invalid-state) when in the closed state.

resource udp-socket

A UDP socket handle.

Functions

[static]tcp-socket.create: func

Create a new TCP socket.

Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model's async support.

Typical errors

References

Params
Return values

[method]tcp-socket.bind: func

Bind the socket to the provided IP address and port.

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which network interface(s) to bind to. If the TCP/UDP port is zero, the socket will be bound to a random free port.

Bind can be attempted multiple times on the same socket, even with different arguments on each iteration. But never concurrently and only as long as the previous bind failed. Once a bind succeeds, the binding can't be changed anymore.

Typical errors

Implementors note

The bind operation shouldn't be affected by the TIME_WAIT state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR socket option should be set implicitly on all platforms, except on Windows where this is the default behavior and SO_REUSEADDR performs something different.

References

Params
Return values

[method]tcp-socket.connect: func

Connect to a remote endpoint.

On success, the socket is transitioned into the connected state and the remote-address of the socket is updated. The local-address may be updated as well, based on the best network path to remote-address. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

After a failed connection attempt, the socket will be in the closed state and the only valid action left is to drop the socket. A single socket can not be used to connect more than once.

Typical errors

References

Params
Return values

[method]tcp-socket.listen: func

Start listening and return a stream of new inbound connections.

Transitions the socket into the listening state. This can be called at most once per socket.

If the socket is not already explicitly bound, this function will implicitly bind the socket to a random free port.

Normally, the returned sockets are bound, in the connected state and immediately ready for I/O. Though, depending on exact timing and circumstances, a newly accepted connection may already be closed by the time the server attempts to perform its first I/O on it. This is true regardless of whether the WASI implementation uses "synthesized" sockets or not (see Implementors Notes below).

The following properties are inherited from the listener socket:

Typical errors

Implementors note

This method returns a single perpetual stream that should only close on fatal errors (if any). Yet, the POSIX' accept function may also return transient errors (e.g. ECONNABORTED). The exact details differ per operation system. For example, the Linux manual mentions:

Linux accept() passes already-pending network errors on the new socket as an error code from accept(). This behavior differs from other BSD socket implementations. For reliable operation the application should detect the network errors defined for the protocol after accept() and treat them like EAGAIN by retrying. In the case of TCP/IP, these are ENETDOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH. Source: https://man7.org/linux/man-pages/man2/accept.2.html

WASI implementations have two options to handle this:

In either case, the stream returned by this listen method remains operational.

WASI requires listen to perform an implicit bind if the socket has not already been bound. Not all platforms (notably Windows) exhibit this behavior out of the box. On platforms that require it, the WASI implementation can emulate this behavior by performing the bind itself if the guest hasn't already done so.

References

Params
Return values

[method]tcp-socket.send: func

Transmit data to peer.

The caller should close the stream when it has no more data to send to the peer. Under normal circumstances this will cause a FIN packet to be sent out. Closing the stream is equivalent to calling shutdown(SHUT_WR) in POSIX.

This function may be called at most once and returns once the full contents of the stream are transmitted or an error is encountered.

Typical errors

References

Params
Return values

[method]tcp-socket.receive: func

Read data from peer.

Returns a stream of data sent by the peer. The implementation drops the stream once no more data is available. At that point, the returned future resolves to:

receive may be called only once per socket. Subsequent calls return a closed stream and a future resolved to err(invalid-state).

If the caller is not expecting to receive any more data from the peer, they should drop the stream. Any data still in the receive queue will be discarded. This is equivalent to calling shutdown(SHUT_RD) in POSIX.

Typical errors

References

Params
Return values

[method]tcp-socket.get-local-address: func

Get the bound local address.

POSIX mentions:

If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

WASI is stricter and requires get-local-address to return invalid-state when the socket hasn't been bound yet.

Typical errors

References

Params
Return values

[method]tcp-socket.get-remote-address: func

Get the remote address.

Typical errors

References

Params
Return values

[method]tcp-socket.get-is-listening: func

Whether the socket is in the listening state.

Equivalent to the SO_ACCEPTCONN socket option.

Params
Return values

[method]tcp-socket.get-address-family: func

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

Equivalent to the SO_DOMAIN socket option.

Params
Return values

[method]tcp-socket.set-listen-backlog-size: func

Hints the desired listen queue size. Implementations are free to ignore this.

If the provided value is 0, an invalid-argument error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded.

Typical errors

Params
Return values

[method]tcp-socket.get-keep-alive-enabled: func

Enables or disables keepalive.

The keepalive behavior can be adjusted using:

Equivalent to the SO_KEEPALIVE socket option.

Params
Return values

[method]tcp-socket.set-keep-alive-enabled: func

Params
Return values

[method]tcp-socket.get-keep-alive-idle-time: func

Amount of time the connection has to be idle before TCP starts sending keepalive packets.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

Typical errors

Params
Return values

[method]tcp-socket.set-keep-alive-idle-time: func

Params
Return values

[method]tcp-socket.get-keep-alive-interval: func

The time between keepalive packets.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPINTVL socket option.

Typical errors

Params
Return values

[method]tcp-socket.set-keep-alive-interval: func

Params
Return values

[method]tcp-socket.get-keep-alive-count: func

The maximum amount of keepalive packets TCP should send before aborting the connection.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPCNT socket option.

Typical errors

Params
Return values

[method]tcp-socket.set-keep-alive-count: func

Params
Return values

[method]tcp-socket.get-hop-limit: func

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

If the provided value is 0, an invalid-argument error is returned.

Typical errors

Params
Return values

[method]tcp-socket.set-hop-limit: func

Params
Return values

[method]tcp-socket.get-receive-buffer-size: func

Kernel buffer space reserved for sending/receiving on this socket. Implementations usually treat this as a cap the buffer can grow to, rather than allocating the full amount immediately.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

This is only a performance hint. The implementation may ignore it or tweak it based on real traffic patterns. Linux and macOS appear to behave differently depending on whether a buffer size was explicitly set. When set, they tend to honor it; when not set, they dynamically adjust the buffer size as the connection progresses. This is especially noticeable when comparing the values from before and after connection establishment.

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

Typical errors

Params
Return values

[method]tcp-socket.set-receive-buffer-size: func

Params
Return values

[method]tcp-socket.get-send-buffer-size: func

Params
Return values

[method]tcp-socket.set-send-buffer-size: func

Params
Return values

[static]udp-socket.create: func

Create a new UDP socket.

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model's async support.

References:

Params
Return values

[method]udp-socket.bind: func

Bind the socket to the provided IP address and port.

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which network interface(s) to bind to. If the port is zero, the socket will be bound to a random free port.

Typical errors

References

Params
Return values

[method]udp-socket.connect: func

Associate this socket with a specific peer address.

On success, the remote-address of the socket is updated. The local-address may be updated as well, based on the best network path to remote-address. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

When a UDP socket is "connected", the send and receive methods are limited to communicating with that peer only:

The name "connect" was kept to align with the existing POSIX terminology. Other than that, this function only changes the local socket configuration and does not generate any network traffic. The peer is not aware of this "connection".

This method may be called multiple times on the same socket to change its association, but only the most recent one will be effective.

Typical errors

Implementors note

If the socket is already connected, some platforms (e.g. Linux) require a disconnect before connecting to a different peer address.

References

Params
Return values

[method]udp-socket.disconnect: func

Dissociate this socket from its peer address.

After calling this method, send & receive are free to communicate with any remote address again.

The POSIX equivalent of this is calling connect with an AF_UNSPEC address.

Typical errors

References

Params
Return values

[method]udp-socket.send: func

Send a message on the socket to a particular peer.

If the socket is connected, the peer address may be left empty. In that case this is equivalent to send in POSIX. Otherwise it is equivalent to sendto.

Additionally, if the socket is connected, a remote-address argument may be provided but then it must be identical to the address passed to connect.

If the socket has not been explicitly bound, it will be implicitly bound to a random free port.

Implementations may trap if the data length exceeds 64 KiB.

Typical errors

Implementors note

WASI requires send to perform an implicit bind if the socket has not been bound. Not all platforms (notably Windows) exhibit this behavior natively. On such platforms, the WASI implementation should emulate it by performing the bind if the guest has not already done so.

References

Params
Return values

[method]udp-socket.receive: func

Receive a message on the socket.

On success, the return value contains a tuple of the received data and the address of the sender. Theoretical maximum length of the data is 64 KiB. Though in practice, it will typically be less than 1500 bytes.

If the socket is connected, the sender address is guaranteed to match the remote address passed to connect.

Typical errors

References

Params
Return values

[method]udp-socket.get-local-address: func

Get the current bound address.

POSIX mentions:

If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

WASI is stricter and requires get-local-address to return invalid-state when the socket hasn't been bound yet.

Typical errors

References

Params
Return values

[method]udp-socket.get-remote-address: func

Get the address the socket is currently "connected" to.

Typical errors

References

Params
Return values

[method]udp-socket.get-address-family: func

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

Equivalent to the SO_DOMAIN socket option.

Params
Return values

[method]udp-socket.get-unicast-hop-limit: func

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

If the provided value is 0, an invalid-argument error is returned.

Typical errors

Params
Return values

[method]udp-socket.set-unicast-hop-limit: func

Params
Return values

[method]udp-socket.get-receive-buffer-size: func

Kernel buffer space reserved for sending/receiving on this socket. Implementations usually treat this as a cap the buffer can grow to, rather than allocating the full amount immediately.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

Typical errors

Params
Return values

[method]udp-socket.set-receive-buffer-size: func

Params
Return values

[method]udp-socket.get-send-buffer-size: func

Params
Return values

[method]udp-socket.set-send-buffer-size: func

Params
Return values

Import interface wasi:sockets/ip-name-lookup@0.3.2

Types

type ip-address

ip-address

variant error-code

Lookup error codes.

Variant Cases

Functions

resolve-addresses: func

Resolve an internet host name to a list of IP addresses.

Unicode domain names are automatically converted to ASCII using IDNA encoding. If the input is an IP address string, the address is parsed and returned as-is without making any external requests.

See the wasi-socket proposal README.md for a comparison with getaddrinfo.

The results are returned in connection order preference.

This function never succeeds with 0 results. It either fails or succeeds with at least one address. Additionally, this function never returns IPv4-mapped IPv6 addresses.

References:

Params
Return values

Import interface wasi:random/random@0.3.2

WASI Random is a random data API.

It is intended to be portable at least between Unix-family platforms and Windows.

Functions

get-random-bytes: func

Return up to max-len cryptographically-secure random or pseudo-random bytes.

This function must produce data at least as cryptographically secure and fast as an adequately seeded cryptographically-secure pseudo-random number generator (CSPRNG). It must not block, from the perspective of the calling program, under any circumstances, including on the first request and on requests for numbers of bytes. The returned data must always be unpredictable.

Implementations MAY return fewer bytes than requested (a short read). Callers that require exactly max-len bytes MUST call this function in a loop until the desired number of bytes has been accumulated. Implementations MUST return at least 1 byte when max-len is greater than zero. When max-len is zero, implementations MUST return an empty list without trapping.

This function must always return fresh data. Deterministic environments must omit this function, rather than implementing it with deterministic data.

Params
Return values

get-random-u64: func

Return a cryptographically-secure random or pseudo-random u64 value.

This function returns the same type of data as get-random-bytes, represented as a u64.

Return values

Import interface wasi:random/insecure@0.3.2

The insecure interface for insecure pseudo-random numbers.

It is intended to be portable at least between Unix-family platforms and Windows.

Functions

get-insecure-random-bytes: func

Return up to max-len insecure pseudo-random bytes.

This function is not cryptographically secure. Do not use it for anything related to security.

There are no requirements on the values of the returned bytes, however implementations are encouraged to return evenly distributed values with a long period.

Implementations MAY return fewer bytes than requested (a short read). Callers that require exactly max-len bytes MUST call this function in a loop until the desired number of bytes has been accumulated. Implementations MUST return at least 1 byte when max-len is greater than zero. When max-len is zero, implementations MUST return an empty list without trapping.

Params
Return values

get-insecure-random-u64: func

Return an insecure pseudo-random u64 value.

This function returns the same type of pseudo-random data as get-insecure-random-bytes, represented as a u64.

Return values

Import interface wasi:random/insecure-seed@0.3.2

The insecure-seed interface for seeding hash-map DoS resistance.

It is intended to be portable at least between Unix-family platforms and Windows.

Functions

get-insecure-seed: func

Return a 128-bit value that may contain a pseudo-random value.

The returned value is not required to be computed from a CSPRNG, and may even be entirely deterministic. Host implementations are encouraged to provide pseudo-random values to any program exposed to attacker-controlled content, to enable DoS protection built into many languages' hash-map implementations.

This function is intended to only be called once, by a source language to initialize Denial Of Service (DoS) protection in its hash-map implementation.

Expected future evolution

This will likely be changed to a value import, to prevent it from being called multiple times and potentially used for purposes other than DoS protection.

Return values

Export interface wasi:cli/run@0.3.2

Functions

run: func

Run the program.

Return values