type datetime-#### `record timezone-display` +#### `type timezone` +`u32` +
A timezone. +
In timezones that recognize daylight saving time, also known as daylight +time and summer time, the information returned from the functions varies +over time to reflect these adjustments.
+This represents a resource.
+record timezone-displayInformation useful for displaying the timezone of a specific datetime.
This information may vary within a single timezone to reflect daylight
saving time adjustments.
-04:00.
-type timezoneu32
A timezone. -
In timezones that recognize daylight saving time, also known as daylight -time and summer time, the information returned from the functions varies -over time to reflect these adjustments.
-This represents a resource.
display: functype pollable-#### `enum stream-status` +#### `record stream-error` +
An error type returned from a stream operation. Currently this +doesn't provide any additional information.
+enum stream-statusStreams provide a sequence of data and then end; once they end, they no longer provide any further data.
For example, a stream reading from a file ends when the stream reaches @@ -284,25 +288,6 @@ socket ends when the socket is closed.
The stream has ended and will not produce any further data. -
record stream-errorAn error type returned from a stream operation. Currently this -doesn't provide any additional information.
-type output-streamu32
An output bytestream. In the future, this will be replaced by handle -types. -
This conceptually represents a stream<u8, _>. It's temporary
-scaffolding until component-model's async features are ready.
output-streams are non-blocking to the extent practical on
-underlying platforms. Except where specified otherwise, I/O operations also
-always return promptly, after the number of bytes that can be written
-promptly, which could even be zero. To wait for the stream to be ready to
-accept data, the subscribe-to-output-stream function to obtain a
-pollable which can be polled for using wasi_poll.
And at present, it is a u32 instead of being an actual handle, until
-the wit-bindgen implementation of handles and resources is ready.
This represents a resource.
type input-streamu32
An input bytestream. In the future, this will be replaced by handle
@@ -318,6 +303,21 @@ can be polled for using wasi_poll.
And at present, it is a u32 instead of being an actual handle, until
the wit-bindgen implementation of handles and resources is ready.
This represents a resource.
+type output-streamu32
An output bytestream. In the future, this will be replaced by handle +types. +
This conceptually represents a stream<u8, _>. It's temporary
+scaffolding until component-model's async features are ready.
output-streams are non-blocking to the extent practical on
+underlying platforms. Except where specified otherwise, I/O operations also
+always return promptly, after the number of bytes that can be written
+promptly, which could even be zero. To wait for the stream to be ready to
+accept data, the subscribe-to-output-stream function to obtain a
+pollable which can be polled for using wasi_poll.
And at present, it is a u32 instead of being an actual handle, until
+the wit-bindgen implementation of handles and resources is ready.
This represents a resource.
read: func-#### `flags path-flags` +#### `type filesize` +`u64` +
File size or length of a region within a file. +
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
+Note: This was called filetype in earlier versions of WASI.
The type of the descriptor or file is unknown or is different from +any of the other types specified. +
The descriptor refers to a block device inode. +
The descriptor refers to a character device inode. +
The descriptor refers to a directory inode. +
The descriptor refers to a named pipe. +
The file refers to a symbolic link inode. +
The descriptor refers to a regular file inode. +
The descriptor refers to a socket. +
flags descriptor-flagsDescriptor flags.
+Note: This was called fdflags in earlier versions of WASI.
read:
Read mode: Data can be read. +
Write mode: Data can be written to. +
Requests non-blocking operation. +
When this flag is enabled, functions may return immediately with an
+error-code::would-block error code in situations where they would
+otherwise block. However, this non-blocking behavior is not
+required. Implementations are permitted to ignore this flag and
+block. This is similar to O_NONBLOCK in POSIX.
Request that writes be performed according to synchronized I/O file +integrity completion. The data stored in the file and the file's +metadata are synchronized. This is similar to `O_SYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Request that writes be performed according to synchronized I/O data +integrity completion. Only the data stored in the file is +synchronized. This is similar to `O_DSYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Requests that reads be performed at the same level of integrety +requested for writes. This is similar to `O_RSYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Mutating directories mode: Directory contents may be mutated. +
When this flag is unset on a descriptor, operations using the
+descriptor which would create, rename, delete, modify the data or
+metadata of filesystem objects, or obtain another handle which
+would permit any of those, shall fail with error-code::read-only if
+they would otherwise succeed.
This may only be set on directories.
+flags path-flagsFlags determining the method of how paths are resolved.
record metadata-hash-valueA 128-bit hash value, split into parts because wasm doesn't have a -128-bit integer type.
-variant access-typeAccess type used by access-at.
lower: u64
64 bits of a 128-bit hash value. +
+Test for readability, writeability, or executability.
upper: u64
Another 64 bits of a 128-bit hash value. +
+Test whether the path exists.
type link-countu64
Number of hard links to an inode. -
type filesizeu64
File size or length of a region within a file. +
record descriptor-statFile attributes.
+Note: This was called filestat in earlier versions of WASI.
File type. +
Number of hard links to the file. +
For regular files, the file size in bytes. For symbolic links, the +length in bytes of the pathname contained in the symbolic link. +
data-access-timestamp: datetime
Last data access timestamp. +
data-modification-timestamp: datetime
Last data modification timestamp. +
status-change-timestamp: datetime
Last file status change timestamp. +
variant new-timestampWhen setting a timestamp, this gives the value to set it to.
+Leave the timestamp set to its previous value. +
Set the timestamp to the current time of the system clock associated +with the filesystem. +
Set the timestamp to the given value. +
record directory-entryA directory entry.
+The type of the file referred to by this directory entry. +
name: string
The name of the object. +
enum error-codeError codes returned by functions, similar to errno in POSIX.
Not all of these error codes are returned by the functions provided by this
@@ -712,241 +871,71 @@ merely for alignment with POSIX.
No such file or directory, similar to `ENOENT` in POSIX. -
No locks available, similar to `ENOLCK` in POSIX. -
Not enough space, similar to `ENOMEM` in POSIX. -
No space left on device, similar to `ENOSPC` in POSIX. -
Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. -
Directory not empty, similar to `ENOTEMPTY` in POSIX. -
State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. -
Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. -
Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. -
No such device or address, similar to `ENXIO` in POSIX. -
Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. -
Operation not permitted, similar to `EPERM` in POSIX. -
Broken pipe, similar to `EPIPE` in POSIX. -
Read-only file system, similar to `EROFS` in POSIX. -
Invalid seek, similar to `ESPIPE` in POSIX. -
Text file busy, similar to `ETXTBSY` in POSIX. -
Cross-device link, similar to `EXDEV` in POSIX. -
type directory-entry-streamu32
A stream of directory entries. -
This represents a stream of dir-entry.
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
-Note: This was called filetype in earlier versions of WASI.
The type of the descriptor or file is unknown or is different from -any of the other types specified. -
The descriptor refers to a block device inode. -
The descriptor refers to a character device inode. -
The descriptor refers to a directory inode. -
The descriptor refers to a named pipe. -
The file refers to a symbolic link inode. -
The descriptor refers to a regular file inode. -
The descriptor refers to a socket. -
record directory-entryA directory entry.
-The type of the file referred to by this directory entry. -
name: string
The name of the object. +
No such file or directory, similar to `ENOENT` in POSIX.
flags descriptor-flagsDescriptor flags.
-Note: This was called fdflags in earlier versions of WASI.
read:
Read mode: Data can be read. +
+No locks available, similar to `ENOLCK` in POSIX.
Write mode: Data can be written to. +
+Not enough space, similar to `ENOMEM` in POSIX.
Requests non-blocking operation. -
When this flag is enabled, functions may return immediately with an
-error-code::would-block error code in situations where they would
-otherwise block. However, this non-blocking behavior is not
-required. Implementations are permitted to ignore this flag and
-block. This is similar to O_NONBLOCK in POSIX.
No space left on device, similar to `ENOSPC` in POSIX.
Request that writes be performed according to synchronized I/O file -integrity completion. The data stored in the file and the file's -metadata are synchronized. This is similar to `O_SYNC` in POSIX. -
The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.
+ +Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX.
Request that writes be performed according to synchronized I/O data -integrity completion. Only the data stored in the file is -synchronized. This is similar to `O_DSYNC` in POSIX. -
The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.
+ +Directory not empty, similar to `ENOTEMPTY` in POSIX.
Requests that reads be performed at the same level of integrety -requested for writes. This is similar to `O_RSYNC` in POSIX. -
The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.
+ +State not recoverable, similar to `ENOTRECOVERABLE` in POSIX.
Mutating directories mode: Directory contents may be mutated. -
When this flag is unset on a descriptor, operations using the
-descriptor which would create, rename, delete, modify the data or
-metadata of filesystem objects, or obtain another handle which
-would permit any of those, shall fail with error-code::read-only if
-they would otherwise succeed.
This may only be set on directories.
+ +Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX.
type descriptoru32
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. -
This represents a resource.
-variant new-timestampWhen setting a timestamp, this gives the value to set it to.
-Leave the timestamp set to its previous value. +
+Inappropriate I/O control operation, similar to `ENOTTY` in POSIX.
Set the timestamp to the current time of the system clock associated -with the filesystem. +
+No such device or address, similar to `ENXIO` in POSIX.
Set the timestamp to the given value. +
+Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX.
record descriptor-statFile attributes.
-Note: This was called filestat in earlier versions of WASI.
File type. +
+Operation not permitted, similar to `EPERM` in POSIX.
Number of hard links to the file. +
+Broken pipe, similar to `EPIPE` in POSIX.
For regular files, the file size in bytes. For symbolic links, the -length in bytes of the pathname contained in the symbolic link. +
+Read-only file system, similar to `EROFS` in POSIX.
data-access-timestamp: datetime
Last data access timestamp. +
+Invalid seek, similar to `ESPIPE` in POSIX.
data-modification-timestamp: datetime
Last data modification timestamp. +
+Text file busy, similar to `ETXTBSY` in POSIX.
status-change-timestamp: datetime
Last file status change timestamp. +
+Cross-device link, similar to `EXDEV` in POSIX.
enum advicevariant access-typeAccess type used by access-at.
type descriptoru32
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. +
This represents a resource.
+record metadata-hash-valueA 128-bit hash value, split into parts because wasm doesn't have a +128-bit integer type.
+Test for readability, writeability, or executability. +
lower: u64
64 bits of a 128-bit hash value.
Test whether the path exists. +
upper: u64
Another 64 bits of a 128-bit hash value.
type directory-entry-streamu32
A stream of directory entries. +
This represents a stream of dir-entry.
read-via-stream: funcFYI, In the future this will be replaced by handle types.
-tuple ipv6-addressrecord ipv6-socket-addressport: u16flow-info: u32address: ipv6-addressscope-id: u32tuple ipv4-addressrecord ipv4-socket-addressport: u16address: ipv4-addressvariant ip-socket-addressenum ip-address-familyvariant ip-addressipv4: ipv4-addressipv6: ipv6-addressenum error-codeError codes.
In theory, every API can return any error code. @@ -1844,6 +1786,64 @@ combined with a couple of errors that are always possible:
A permanent failure in name resolution occurred. +
enum ip-address-familytuple ipv4-addresstuple ipv6-addressvariant ip-addressipv4: ipv4-addressipv6: ipv6-addressrecord ipv4-socket-addressport: u16address: ipv4-addressrecord ipv6-socket-addressport: u16flow-info: u32address: ipv6-addressscope-id: u32variant ip-socket-addressdrop-network: funcwasi:clocks/wall-clockwasi:poll/pollwasi:clocks/monotonic-clockwasi:clocks/timezonewasi:io/streamswasi:filesystem/typeswasi:filesystem/preopenswasi:sockets/networkwasi:sockets/instance-networkwasi:sockets/ip-name-lookupwasi:sockets/tcpwasi:sockets/tcp-create-socketwasi:sockets/udpwasi:sockets/udp-create-socketwasi:random/randomwasi:random/insecurewasi:random/insecure-seedwasi:cli/environmentwasi:cli/exitwasi:cli/stdinwasi:cli/stdoutwasi:cli/stderrwasi:cli/terminal-inputwasi:cli/terminal-outputwasi:cli/terminal-stdinwasi:cli/terminal-stdoutwasi:cli/terminal-stderrWASI Wall Clock is a clock API intended to let users query the current +time. The name "wall" makes an analogy to a "clock on the wall", which +is not necessarily monotonic as it may be reset.
+It is intended to be portable at least between Unix-family platforms and +Windows.
+A wall clock is a clock which measures the date and time according to +some external reference.
+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.
+record datetimeA time and date in seconds plus nanoseconds.
+seconds: u64nanoseconds: u32now: funcRead 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 returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.
+The nanoseconds field of the output is always less than 1000000000.
+datetimeresolution: funcQuery the resolution of the clock.
+The nanoseconds field of the output is always less than 1000000000.
+datetimeA poll API intended to let users wait for I/O events on multiple handles +at once.
+type pollableu32
A "pollable" handle. +
This is conceptually represents a stream<_, _>, or in other words,
+a stream that one can wait on, repeatedly, but which does not itself
+produce any data. It's temporary scaffolding until component-model's
+async features are ready.
And at present, it is a u32 instead of being an actual handle, until
+the wit-bindgen implementation of handles and resources is ready.
pollable lifetimes are not automatically managed. Users must ensure
+that they do not outlive the resource they reference.
This represents a resource.
+drop-pollable: funcDispose of the specified pollable, after which it may no longer
+be used.
poll-oneoff: funcPoll for completion on a set of pollables.
+This function takes a list of pollables, which identify I/O sources of +interest, and waits until one or more of the events is ready for I/O.
+The result list<bool> is the same length as the argument
+list<pollable>, and indicates the readiness of each corresponding
+element in that list, with true indicating ready. A single call can
+return multiple true elements.
A timeout can be implemented by adding a pollable from the +wasi-clocks API to the list.
+This function does not return a result; polling in itself does not
+do any I/O so it doesn't fail. If any of the I/O sources identified by
+the pollables has an error, it is indicated by marking the source as
+ready in the list<bool>.
The "oneoff" in the name refers to the fact that this function must do a +linear scan through the entire list of subscriptions, which may be +inefficient if the number is large and the same subscriptions are used +many times. In the future, this is expected to be obsoleted by the +component model async proposal, which will include a scalable waiting +facility.
+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.
+It is intended for measuring elapsed time.
+type pollable+#### `type instant` +`u64` +
A timestamp in nanoseconds. +
now: funcRead the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.
+instantresolution: funcQuery the resolution of the clock.
+instantsubscribe: funcCreate a pollable which will resolve once the specified time has been
+reached.
pollabletype datetime+#### `type timezone` +`u32` +
A timezone. +
In timezones that recognize daylight saving time, also known as daylight +time and summer time, the information returned from the functions varies +over time to reflect these adjustments.
+This represents a resource.
+record timezone-displayInformation useful for displaying the timezone of a specific datetime.
This information may vary within a single timezone to reflect daylight
+saving time adjustments.
utc-offset: s32
The number of seconds difference between UTC time and the local +time of the timezone. +
The returned value will always be less than 86400 which is the +number of seconds in a day (246060).
+In implementations that do not expose an actual time zone, this +should return 0.
+name: string
The abbreviated name of the timezone to display to a user. The name +`UTC` indicates Coordinated Universal Time. Otherwise, this should +reference local standards for the name of the time zone. +
In implementations that do not expose an actual time zone, this
+should be the string UTC.
In time zones that do not have an applicable name, a formatted
+representation of the UTC offset may be returned, such as -04:00.
in-daylight-saving-time: bool
Whether daylight saving time is active. +
In implementations that do not expose an actual time zone, this +should return false.
+display: funcReturn information needed to display the given datetime. This includes
+the UTC offset, the time zone name, and a flag indicating whether
+daylight saving time is active.
If the timezone cannot be determined for the given datetime, return a
+timezone-display for UTC with a utc-offset of 0 and no daylight
+saving time.
timezone-displayutc-offset: funcThe same as display, but only return the UTC offset.
drop-timezone: funcDispose of the specified input-stream, after which it may no longer +be used.
+WASI I/O is an I/O abstraction API which is currently focused on providing +stream types.
+In the future, the component model is expected to add built-in stream types; +when it does, they are expected to subsume this API.
+type pollable+#### `record stream-error` +
An error type returned from a stream operation. Currently this +doesn't provide any additional information.
+enum stream-statusStreams provide a sequence of data and then end; once they end, they +no longer provide any further data.
+For example, a stream reading from a file ends when the stream reaches +the end of the file. For another example, a stream reading from a +socket ends when the socket is closed.
+The stream is open and may produce further data. +
The stream has ended and will not produce any further data. +
type input-streamu32
An input bytestream. In the future, this will be replaced by handle +types. +
This conceptually represents a stream<u8, _>. It's temporary
+scaffolding until component-model's async features are ready.
input-streams are non-blocking to the extent practical on underlying
+platforms. I/O operations always return promptly; if fewer bytes are
+promptly available than requested, they return the number of bytes promptly
+available, which could even be zero. To wait for data to be available,
+use the subscribe-to-input-stream function to obtain a pollable which
+can be polled for using wasi_poll.
And at present, it is a u32 instead of being an actual handle, until
+the wit-bindgen implementation of handles and resources is ready.
This represents a resource.
+type output-streamu32
An output bytestream. In the future, this will be replaced by handle +types. +
This conceptually represents a stream<u8, _>. It's temporary
+scaffolding until component-model's async features are ready.
output-streams are non-blocking to the extent practical on
+underlying platforms. Except where specified otherwise, I/O operations also
+always return promptly, after the number of bytes that can be written
+promptly, which could even be zero. To wait for the stream to be ready to
+accept data, the subscribe-to-output-stream function to obtain a
+pollable which can be polled for using wasi_poll.
And at present, it is a u32 instead of being an actual handle, until
+the wit-bindgen implementation of handles and resources is ready.
This represents a resource.
+read: funcRead bytes from a stream.
+This function returns a list of bytes containing the data that was
+read, along with a stream-status which indicates whether the end of
+the stream was reached. The returned list will contain up to len
+bytes; it may return fewer than requested, but not more.
Once a stream has reached the end, subsequent calls to read or
+skip will always report end-of-stream rather than producing more
+data.
If len is 0, it represents a request to read 0 bytes, which should
+always succeed, assuming the stream hasn't reached its end yet, and
+return an empty list.
The len here is a u64, but some callees may not be able to allocate
+a buffer as large as that would imply.
+FIXME: describe what happens if allocation fails.
this: input-streamlen: u64u8>, stream-status), stream-error>blocking-read: funcRead bytes from a stream, with blocking.
+This is similar to read, except that it blocks until at least one
+byte can be read.
this: input-streamlen: u64u8>, stream-status), stream-error>skip: funcSkip bytes from a stream.
+This is similar to the read function, but avoids copying the
+bytes into the instance.
Once a stream has reached the end, subsequent calls to read or
+skip will always report end-of-stream rather than producing more
+data.
This function returns the number of bytes skipped, along with a
+stream-status indicating whether the end of the stream was
+reached. The returned value will be at most len; it may be less.
this: input-streamlen: u64u64, stream-status), stream-error>blocking-skip: funcSkip bytes from a stream, with blocking.
+This is similar to skip, except that it blocks until at least one
+byte can be consumed.
this: input-streamlen: u64u64, stream-status), stream-error>subscribe-to-input-stream: funcCreate a pollable which will resolve once either the specified stream
+has bytes available to read or the other end of the stream has been
+closed.
this: input-streampollabledrop-input-stream: funcDispose of the specified input-stream, after which it may no longer
+be used.
this: input-streamwrite: funcWrite bytes to a stream.
+This function returns a u64 indicating the number of bytes from
+buf that were written; it may be less than the full list.
this: output-streambuf: list<u8>u64, stream-error>blocking-write: funcWrite bytes to a stream, with blocking.
+This is similar to write, except that it blocks until at least one
+byte can be written.
this: output-streambuf: list<u8>u64, stream-error>write-zeroes: funcWrite multiple zero bytes to a stream.
+This function returns a u64 indicating the number of zero bytes
+that were written; it may be less than len.
this: output-streamlen: u64u64, stream-error>blocking-write-zeroes: funcWrite multiple zero bytes to a stream, with blocking.
+This is similar to write-zeroes, except that it blocks until at least
+one byte can be written.
this: output-streamlen: u64u64, stream-error>splice: funcRead from one stream and write to another.
+This function returns the number of bytes transferred; it may be less
+than len.
Unlike other I/O functions, this function blocks until all the data +read from the input stream has been written to the output stream.
+this: output-streamsrc: input-streamlen: u64u64, stream-status), stream-error>blocking-splice: funcRead from one stream and write to another, with blocking.
+This is similar to splice, except that it blocks until at least
+one byte can be read.
this: output-streamsrc: input-streamlen: u64u64, stream-status), stream-error>forward: funcForward the entire contents of an input stream to an output stream.
+This function repeatedly reads from the input stream and writes +the data to the output stream, until the end of the input stream +is reached, or an error is encountered.
+Unlike other I/O functions, this function blocks until the end +of the input stream is seen and all the data has been written to +the output stream.
+This function returns the number of bytes transferred.
+this: output-streamsrc: input-streamu64, stream-error>subscribe-to-output-stream: funcCreate a pollable which will resolve once either the specified stream
+is ready to accept bytes or the other end of the stream has been closed.
this: output-streampollabledrop-output-stream: funcDispose of the specified output-stream, after which it may no longer
+be used.
this: output-streamWASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.
+It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.
+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.
type input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type datetime` +[`datetime`](#datetime) +
+#### `type filesize` +`u64` +
File size or length of a region within a file. +
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
+Note: This was called filetype in earlier versions of WASI.
The type of the descriptor or file is unknown or is different from +any of the other types specified. +
The descriptor refers to a block device inode. +
The descriptor refers to a character device inode. +
The descriptor refers to a directory inode. +
The descriptor refers to a named pipe. +
The file refers to a symbolic link inode. +
The descriptor refers to a regular file inode. +
The descriptor refers to a socket. +
flags descriptor-flagsDescriptor flags.
+Note: This was called fdflags in earlier versions of WASI.
read:
Read mode: Data can be read. +
Write mode: Data can be written to. +
Requests non-blocking operation. +
When this flag is enabled, functions may return immediately with an
+error-code::would-block error code in situations where they would
+otherwise block. However, this non-blocking behavior is not
+required. Implementations are permitted to ignore this flag and
+block. This is similar to O_NONBLOCK in POSIX.
Request that writes be performed according to synchronized I/O file +integrity completion. The data stored in the file and the file's +metadata are synchronized. This is similar to `O_SYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Request that writes be performed according to synchronized I/O data +integrity completion. Only the data stored in the file is +synchronized. This is similar to `O_DSYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Requests that reads be performed at the same level of integrety +requested for writes. This is similar to `O_RSYNC` in POSIX. +
The precise semantics of this operation have not yet been defined for +WASI. At this time, it should be interpreted as a request, and not a +requirement.
+Mutating directories mode: Directory contents may be mutated. +
When this flag is unset on a descriptor, operations using the
+descriptor which would create, rename, delete, modify the data or
+metadata of filesystem objects, or obtain another handle which
+would permit any of those, shall fail with error-code::read-only if
+they would otherwise succeed.
This may only be set on directories.
+flags path-flagsFlags determining the method of how paths are resolved.
+symlink-follow: As long as the resolved path corresponds to a symbolic link, it is +expanded. +
flags open-flagsOpen flags used by open-at.
Create file if it does not exist, similar to `O_CREAT` in POSIX. +
Fail if not a directory, similar to `O_DIRECTORY` in POSIX. +
Fail if file already exists, similar to `O_EXCL` in POSIX. +
Truncate file to size 0, similar to `O_TRUNC` in POSIX. +
flags modesPermissions mode used by open-at, change-file-permissions-at, and
+similar.
True if the resource is considered readable by the containing +filesystem. +
True if the resource is considered writable by the containing +filesystem. +
True if the resource is considered executable by the containing +filesystem. This does not apply to directories. +
variant access-typeAccess type used by access-at.
Test for readability, writeability, or executability. +
Test whether the path exists. +
type link-countu64
Number of hard links to an inode. +
record descriptor-statFile attributes.
+Note: This was called filestat in earlier versions of WASI.
File type. +
Number of hard links to the file. +
For regular files, the file size in bytes. For symbolic links, the +length in bytes of the pathname contained in the symbolic link. +
data-access-timestamp: datetime
Last data access timestamp. +
data-modification-timestamp: datetime
Last data modification timestamp. +
status-change-timestamp: datetime
Last file status change timestamp. +
variant new-timestampWhen setting a timestamp, this gives the value to set it to.
+Leave the timestamp set to its previous value. +
Set the timestamp to the current time of the system clock associated +with the filesystem. +
Set the timestamp to the given value. +
record directory-entryA directory entry.
+The type of the file referred to by this directory entry. +
name: string
The name of the object. +
enum error-codeError 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.
Permission denied, similar to `EACCES` in POSIX. +
Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX. +
Connection already in progress, similar to `EALREADY` in POSIX. +
Bad descriptor, similar to `EBADF` in POSIX. +
Device or resource busy, similar to `EBUSY` in POSIX. +
Resource deadlock would occur, similar to `EDEADLK` in POSIX. +
Storage quota exceeded, similar to `EDQUOT` in POSIX. +
File exists, similar to `EEXIST` in POSIX. +
File too large, similar to `EFBIG` in POSIX. +
Illegal byte sequence, similar to `EILSEQ` in POSIX. +
Operation in progress, similar to `EINPROGRESS` in POSIX. +
Interrupted function, similar to `EINTR` in POSIX. +
Invalid argument, similar to `EINVAL` in POSIX. +
I/O error, similar to `EIO` in POSIX. +
Is a directory, similar to `EISDIR` in POSIX. +
Too many levels of symbolic links, similar to `ELOOP` in POSIX. +
Too many links, similar to `EMLINK` in POSIX. +
Message too large, similar to `EMSGSIZE` in POSIX. +
Filename too long, similar to `ENAMETOOLONG` in POSIX. +
No such device, similar to `ENODEV` in POSIX. +
No such file or directory, similar to `ENOENT` in POSIX. +
No locks available, similar to `ENOLCK` in POSIX. +
Not enough space, similar to `ENOMEM` in POSIX. +
No space left on device, similar to `ENOSPC` in POSIX. +
Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. +
Directory not empty, similar to `ENOTEMPTY` in POSIX. +
State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. +
Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. +
Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. +
No such device or address, similar to `ENXIO` in POSIX. +
Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. +
Operation not permitted, similar to `EPERM` in POSIX. +
Broken pipe, similar to `EPIPE` in POSIX. +
Read-only file system, similar to `EROFS` in POSIX. +
Invalid seek, similar to `ESPIPE` in POSIX. +
Text file busy, similar to `ETXTBSY` in POSIX. +
Cross-device link, similar to `EXDEV` in POSIX. +
enum adviceFile or memory access pattern advisory information.
+The application has no advice to give on its behavior with respect +to the specified data. +
The application expects to access the specified data sequentially +from lower offsets to higher offsets. +
The application expects to access the specified data in a random +order. +
The application expects to access the specified data in the near +future. +
The application expects that it will not access the specified data +in the near future. +
The application expects to access the specified data once and then +not reuse it thereafter. +
type descriptoru32
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. +
This represents a resource.
+record metadata-hash-valueA 128-bit hash value, split into parts because wasm doesn't have a +128-bit integer type.
+lower: u64
64 bits of a 128-bit hash value. +
upper: u64
Another 64 bits of a 128-bit hash value. +
type directory-entry-streamu32
A stream of directory entries. +
This represents a stream of dir-entry.
read-via-stream: funcReturn a stream for reading from a file, if available.
+May fail with an error-code describing why the file cannot be read.
+Multiple read, write, and append streams may be active on the same open +file and they do not interfere with each other.
+Note: This allows using read-stream, which is similar to read in POSIX.
this: descriptoroffset: filesizeinput-stream, error-code>write-via-stream: funcReturn a stream for writing to a file, if available.
+May fail with an error-code describing why the file cannot be written.
+Note: This allows using write-stream, which is similar to write in
+POSIX.
this: descriptoroffset: filesizeoutput-stream, error-code>append-via-stream: funcReturn a stream for appending to a file, if available.
+May fail with an error-code describing why the file cannot be appended.
+Note: This allows using write-stream, which is similar to write with
+O_APPEND in in POSIX.
this: descriptoroutput-stream, error-code>advise: funcProvide file advisory information on a descriptor.
+This is similar to posix_fadvise in POSIX.
error-code>sync-data: funcSynchronize 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.
this: descriptorerror-code>get-flags: funcGet 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.
this: descriptordescriptor-flags, error-code>get-type: funcGet 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.
this: descriptordescriptor-type, error-code>set-flags: funcSet status flags associated with a descriptor.
+This function may only change the non-blocking flag.
Note: This is similar to fcntl(fd, F_SETFL, flags) in POSIX.
Note: This was called fd_fdstat_set_flags in earlier versions of WASI.
this: descriptorflags: descriptor-flagserror-code>set-size: funcAdjust 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.
this: descriptorsize: filesizeerror-code>set-times: funcAdjust 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.
this: descriptordata-access-timestamp: new-timestampdata-modification-timestamp: new-timestamperror-code>read: funcRead from a descriptor, without using and updating the descriptor's offset.
+This function returns a list of bytes containing the data that was
+read, along with a bool which, when true, indicates that the end of the
+file was reached. The returned list will contain up to length bytes; it
+may return fewer than requested, if the end of the file is reached or
+if the I/O operation is interrupted.
In the future, this may change to return a stream<u8, error-code>.
Note: This is similar to pread in POSIX.
u8>, bool), error-code>write: funcWrite to a descriptor, without using and updating the descriptor's offset.
+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.
+In the future, this may change to take a stream<u8, error-code>.
Note: This is similar to pwrite in POSIX.
this: descriptorbuffer: list<u8>offset: filesizefilesize, error-code>read-directory: funcRead 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: descriptordirectory-entry-stream, error-code>sync: funcSynchronize 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.
this: descriptorerror-code>create-directory-at: funcCreate a directory.
+Note: This is similar to mkdirat in POSIX.
this: descriptorpath: stringerror-code>stat: funcReturn 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.
this: descriptordescriptor-stat, error-code>stat-at: funcReturn 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.
this: descriptorpath-flags: path-flagspath: stringdescriptor-stat, error-code>set-times-at: funcAdjust 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.
this: descriptorpath-flags: path-flagspath: stringdata-access-timestamp: new-timestampdata-modification-timestamp: new-timestamperror-code>link-at: funcCreate a hard link.
+Note: This is similar to linkat in POSIX.
this: descriptorold-path-flags: path-flagsold-path: stringnew-descriptor: descriptornew-path: stringerror-code>open-at: funcOpen a file or directory.
+The returned descriptor is not guaranteed to be the lowest-numbered +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 descriptor is +guaranteed to be less than 2**31.
+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.
this: descriptorpath-flags: path-flagspath: stringopen-flags: open-flagsflags: descriptor-flagsmodes: modesdescriptor, error-code>readlink-at: funcRead 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.
this: descriptorpath: stringstring, error-code>remove-directory-at: funcRemove 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.
this: descriptorpath: stringerror-code>rename-at: funcRename a filesystem object.
+Note: This is similar to renameat in POSIX.
this: descriptorold-path: stringnew-descriptor: descriptornew-path: stringerror-code>symlink-at: funcCreate 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.
this: descriptorold-path: stringnew-path: stringerror-code>access-at: funcCheck accessibility of a filesystem path.
+Check whether the given filesystem path names an object which is +readable, writable, or executable, or whether it exists.
+This does not a guarantee that subsequent accesses will succeed, as +filesystem permissions may be modified asynchronously by external +entities.
+Note: This is similar to faccessat with the AT_EACCESS flag in POSIX.
this: descriptorpath-flags: path-flagspath: stringtype: access-typeerror-code>unlink-file-at: funcUnlink a filesystem object that is not a directory.
+Return error-code::is-directory if the path refers to a directory.
+Note: This is similar to unlinkat(fd, path, 0) in POSIX.
this: descriptorpath: stringerror-code>change-file-permissions-at: funcChange the permissions of a filesystem object that is not a directory.
+Note that the ultimate meanings of these permissions is +filesystem-specific.
+Note: This is similar to fchmodat in POSIX.
this: descriptorpath-flags: path-flagspath: stringmodes: modeserror-code>change-directory-permissions-at: funcChange the permissions of a directory.
+Note that the ultimate meanings of these permissions is +filesystem-specific.
+Unlike in POSIX, the executable flag is not reinterpreted as a "search"
+flag. read on a directory implies readability and searchability, and
+execute is not valid for directories.
Note: This is similar to fchmodat in POSIX.
this: descriptorpath-flags: path-flagspath: stringmodes: modeserror-code>lock-shared: funcRequest a shared advisory lock for an open file.
+This requests a shared lock; more than one shared lock can be held for +a file at the same time.
+If the open file has an exclusive lock, this function downgrades the lock +to a shared lock. If it has a shared lock, this function has no effect.
+This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.
+It is unspecified how shared locks interact with locks acquired by +non-WASI programs.
+This function blocks until the lock can be acquired.
+Not all filesystems support locking; on filesystems which don't support
+locking, this function returns error-code::unsupported.
Note: This is similar to flock(fd, LOCK_SH) in Unix.
this: descriptorerror-code>lock-exclusive: funcRequest an exclusive advisory lock for an open file.
+This requests an exclusive lock; no other locks may be held for the +file while an exclusive lock is held.
+If the open file has a shared lock and there are no exclusive locks held +for the file, this function upgrades the lock to an exclusive lock. If the +open file already has an exclusive lock, this function has no effect.
+This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.
+It is unspecified whether this function succeeds if the file descriptor +is not opened for writing. It is unspecified how exclusive locks interact +with locks acquired by non-WASI programs.
+This function blocks until the lock can be acquired.
+Not all filesystems support locking; on filesystems which don't support
+locking, this function returns error-code::unsupported.
Note: This is similar to flock(fd, LOCK_EX) in Unix.
this: descriptorerror-code>try-lock-shared: funcRequest a shared advisory lock for an open file.
+This requests a shared lock; more than one shared lock can be held for +a file at the same time.
+If the open file has an exclusive lock, this function downgrades the lock +to a shared lock. If it has a shared lock, this function has no effect.
+This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.
+It is unspecified how shared locks interact with locks acquired by +non-WASI programs.
+This function returns error-code::would-block if the lock cannot be
+acquired.
Not all filesystems support locking; on filesystems which don't support
+locking, this function returns error-code::unsupported.
Note: This is similar to flock(fd, LOCK_SH | LOCK_NB) in Unix.
this: descriptorerror-code>try-lock-exclusive: funcRequest an exclusive advisory lock for an open file.
+This requests an exclusive lock; no other locks may be held for the +file while an exclusive lock is held.
+If the open file has a shared lock and there are no exclusive locks held +for the file, this function upgrades the lock to an exclusive lock. If the +open file already has an exclusive lock, this function has no effect.
+This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.
+It is unspecified whether this function succeeds if the file descriptor +is not opened for writing. It is unspecified how exclusive locks interact +with locks acquired by non-WASI programs.
+This function returns error-code::would-block if the lock cannot be
+acquired.
Not all filesystems support locking; on filesystems which don't support
+locking, this function returns error-code::unsupported.
Note: This is similar to flock(fd, LOCK_EX | LOCK_NB) in Unix.
this: descriptorerror-code>unlock: funcRelease a shared or exclusive lock on an open file.
+Note: This is similar to flock(fd, LOCK_UN) in Unix.
this: descriptorerror-code>drop-descriptor: funcDispose of the specified descriptor, after which it may no longer
+be used.
this: descriptorread-directory-entry: funcRead a single directory entry from a directory-entry-stream.
directory-entry>, error-code>drop-directory-entry-stream: funcDispose of the specified directory-entry-stream, after which it may no longer
+be used.
is-same-object: funcTest 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.
this: descriptorother: descriptormetadata-hash: funcReturn 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 encourated to provide the following properties:
+However, none of these is required.
+this: descriptormetadata-hash-value, error-code>metadata-hash-at: funcReturn 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.
this: descriptorpath-flags: path-flagspath: stringmetadata-hash-value, error-code>type descriptor+---- +
get-directories: funcReturn the set of preopened directories, and their path.
+descriptor, string)>type networku32
An opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface. +
FYI, In the future this will be replaced by handle types.
+enum error-codeError 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:
+unknownaccess-deniednot-supportedout-of-memorySee each individual API for what the POSIX equivalents are. They sometimes differ per API.
+Unknown error +
Access denied. +
POSIX equivalent: EACCES, EPERM
+The operation is not supported. +
POSIX equivalent: EOPNOTSUPP
+Not enough memory to complete the operation. +
POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
+The operation timed out before it could finish completely. +
This operation is incompatible with another asynchronous operation that is already in progress. +
Trying to finish an asynchronous operation that: +- has not been started yet, or: +- was already finished by a previous `finish-*` call. +
Note: this is scheduled to be removed when futures are natively supported.
The operation has been aborted because it could not be completed immediately. +
Note: this is scheduled to be removed when futures are natively supported.
The specified address-family is not supported. +
An IPv4 address was passed to an IPv6 resource, or vice versa. +
The socket address is not a valid remote address. E.g. the IP address is set to INADDR_ANY, or the port is set to 0. +
The operation is only supported on IPv4 resources. +
The operation is only supported on IPv6 resources. +
A new socket resource could not be created because of a system limit. +
The socket is already attached to another network. +
The socket is already bound. +
The socket is already in the Connection state. +
The socket is not bound to any local address. +
The socket is not in the Connection state. +
A bind operation failed because the provided address is not an address that the `network` can bind to. +
A bind operation failed because the provided address is already in use. +
A bind operation failed because there are no ephemeral ports available. +
The remote address is not reachable +
The socket is already in the Listener state. +
The socket is already in the Listener state. +
The connection was forcefully rejected +
The connection was reset. +
The provided name is a syntactically invalid domain name. +
Name does not exist or has no suitable associated IP addresses. +
A temporary failure in name resolution occurred. +
A permanent failure in name resolution occurred. +
enum ip-address-familytuple ipv4-addresstuple ipv6-addressvariant ip-addressipv4: ipv4-addressipv6: ipv6-addressrecord ipv4-socket-addressport: u16address: ipv4-addressrecord ipv6-socket-addressport: u16flow-info: u32address: ipv6-addressscope-id: u32variant ip-socket-addressdrop-network: funcDispose of the specified network, after which it may no longer be used.
Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+This interface provides a value-export of the default network handle..
+type network+---- +
instance-network: funcGet a handle to the default network.
+networktype pollable+#### `type network` +[`network`](#network) +
+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-address` +[`ip-address`](#ip_address) +
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +
+#### `type resolve-address-stream` +`u32` +
+---- +
resolve-addresses: funcResolve an internet host name to a list of IP addresses.
+See the wasi-socket proposal README.md for a comparison with getaddrinfo.
+name: The name to look up. IP addresses are not allowed. Unicode domain names are automatically converted
+to ASCII using IDNA encoding.address-family: If provided, limit the results to addresses of this specific address family.include-unavailable: When set to true, this function will also return addresses of which the runtime
+thinks (or knows) can't be connected to at the moment. For example, this will return IPv6 addresses on
+systems without an active IPv6 interface. Notes:This function never blocks. It either immediately fails or immediately returns successfully with a resolve-address-stream
+that can be used to (asynchronously) fetch the results.
At the moment, the stream never completes successfully with 0 items. Ie. the first call
+to resolve-next-address never returns ok(none). This may change in the future.
invalid-name: name is a syntactically invalid domain name.invalid-name: name is an IP address.address-family-not-supported: The specified address-family is not supported. (EAI_FAMILY)network: networkname: stringaddress-family: option<ip-address-family>include-unavailable: boolresolve-address-stream, error-code>resolve-next-address: funcReturns the next address from the resolver.
+This function should be called multiple times. On each call, it will
+return the next address in connection order preference. If all
+addresses have been exhausted, this function returns none.
+After which, you should release the stream with drop-resolve-address-stream.
This function never returns IPv4-mapped IPv6 addresses.
+name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)ip-address>, error-code>drop-resolve-address-stream: funcDispose of the specified resolve-address-stream, after which it may no longer be used.
Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+subscribe: funcCreate a pollable which will resolve once the stream is ready for I/O.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future is natively supported in Preview3.
pollabletype input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type pollable` +[`pollable`](#pollable) +
+#### `type network` +[`network`](#network) +
+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address) +
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +
+#### `type tcp-socket` +`u32` +
A TCP socket handle. +
enum shutdown-typeSimilar to `SHUT_RD` in POSIX. +
Similar to `SHUT_WR` in POSIX. +
Similar to `SHUT_RDWR` in POSIX. +
start-bind: funcBind the socket to a specific network on 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.
When a socket is not explicitly bound, the first invocation to a listen or connect operation will +implicitly bind the socket.
+Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+start errorsaddress-family-mismatch: The local-address has the wrong address family. (EINVAL)already-bound: The socket is already bound. (EINVAL)concurrency-conflict: Another bind, connect or listen operation is already in progress. (EALREADY)finish errorsephemeral-ports-exhausted: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: Address is already in use. (EADDRINUSE)address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)not-in-progress: A bind operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)error-code>finish-bind: functhis: tcp-socketerror-code>start-connect: funcConnect to a remote endpoint.
+On success:
+start errorsaddress-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)invalid-remote-address: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)already-attached: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.already-connected: The socket is already in the Connection state. (EISCONN)already-listening: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)concurrency-conflict: Another bind, connect or listen operation is already in progress. (EALREADY)finish errorstimeout: Connection timed out. (ETIMEDOUT)connection-refused: The connection was forcefully rejected. (ECONNREFUSED)connection-reset: The connection was reset. (ECONNRESET)remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)ephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)error-code>finish-connect: functhis: tcp-socketinput-stream, output-stream), error-code>start-listen: funcStart listening for new connections.
+Transitions the socket into the Listener state.
+Unlike POSIX:
+start errorsnot-bound: The socket is not bound to any local address. (EDESTADDRREQ)already-connected: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)already-listening: The socket is already in the Listener state.concurrency-conflict: Another bind, connect or listen operation is already in progress. (EINVAL on BSD)finish errorsephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)not-in-progress: A listen operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)this: tcp-socketerror-code>finish-listen: functhis: tcp-socketerror-code>accept: funcAccept a new client socket.
+The returned socket is bound and in the Connection state.
+On success, this function returns the newly accepted client socket along with +a pair of streams that can be used to read & write to the connection.
+not-listening: Socket is not in the Listener state. (EINVAL)would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)Host implementations must skip over transient errors returned by the native accept syscall.
+this: tcp-sockettcp-socket, input-stream, output-stream), error-code>local-address: funcGet the bound local address.
+not-bound: The socket is not bound to any local address.this: tcp-socketip-socket-address, error-code>remote-address: funcGet the bound remote address.
+not-connected: The socket is not connected to a remote address. (ENOTCONN)this: tcp-socketip-socket-address, error-code>address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
+this: tcp-socketipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+ipv6-only-operation: (get/set) this socket is an IPv4 socket.already-bound: (set) The socket is already bound.not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketbool, error-code>set-ipv6-only: functhis: tcp-socketvalue: boolerror-code>set-listen-backlog-size: funcHints the desired listen queue size. Implementations are free to ignore this.
+already-connected: (set) The socket is already in the Connection state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketvalue: u64error-code>keep-alive: funcEquivalent to the SO_KEEPALIVE socket option.
+concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketbool, error-code>set-keep-alive: functhis: tcp-socketvalue: boolerror-code>no-delay: funcEquivalent to the TCP_NODELAY socket option.
+concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketbool, error-code>set-no-delay: functhis: tcp-socketvalue: boolerror-code>unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+already-connected: (set) The socket is already in the Connection state.already-listening: (set) The socket is already in the Listener state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketu8, error-code>set-unicast-hop-limit: functhis: tcp-socketvalue: u8error-code>receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+Note #1: an implementation may choose to cap or round the buffer size when setting the value. +In other words, after setting a value, reading the same setting back may return a different value.
+Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of +actual data to be sent/received by the application, because the kernel might also use the buffer space +for internal metadata structures.
+Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+already-connected: (set) The socket is already in the Connection state.already-listening: (set) The socket is already in the Listener state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)this: tcp-socketu64, error-code>set-receive-buffer-size: functhis: tcp-socketvalue: u64error-code>send-buffer-size: functhis: tcp-socketu64, error-code>set-send-buffer-size: functhis: tcp-socketvalue: u64error-code>subscribe: funcCreate a pollable which will resolve once the socket is ready for I/O.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future is natively supported in Preview3.
this: tcp-socketpollableshutdown: funcInitiate a graceful shutdown.
+input-stream associated with this socket will return an End Of Stream indication.
+Any data still in the receive queue at time of calling shutdown will be discarded.output-stream associated with this socket will return an error.The shutdown function does not close (drop) the socket.
+not-connected: The socket is not in the Connection state. (ENOTCONN)error-code>drop-tcp-socket: funcDispose of the specified tcp-socket, after which it may no longer be used.
Similar to the POSIX close function.
Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+this: tcp-sockettype network+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +
+#### `type tcp-socket` +[`tcp-socket`](#tcp_socket) +
+---- +
create-tcp-socket: funcCreate a new TCP socket.
+Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX.
This function does not require a network capability handle. This is considered to be safe because
+at time of creation, the socket is not bound to any network yet. Up to the moment bind/listen/connect
+is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
+not-supported: The host does not support TCP sockets. (EOPNOTSUPP)address-family-not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)tcp-socket, error-code>type pollable+#### `type network` +[`network`](#network) +
+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address) +
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +
+#### `type udp-socket` +`u32` +
A UDP socket handle. +
record datagramdata: list<u8>remote-address: ip-socket-addressstart-bind: funcBind the socket to a specific network on 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.
When a socket is not explicitly bound, the first invocation to connect will implicitly bind the socket.
+Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+start errorsaddress-family-mismatch: The local-address has the wrong address family. (EINVAL)already-bound: The socket is already bound. (EINVAL)concurrency-conflict: Another bind or connect operation is already in progress. (EALREADY)finish errorsephemeral-ports-exhausted: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: Address is already in use. (EADDRINUSE)address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)not-in-progress: A bind operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)error-code>finish-bind: functhis: udp-socketerror-code>start-connect: funcSet the destination address.
+The local-address is updated based on the best network path to remote-address.
When a destination address is set:
+remote-address.send function can only be used to send to this destination.Note that this function does not generate any network traffic and the peer is not aware of this "connection".
+Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+start errorsaddress-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-remote-address: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)already-attached: The socket is already bound to a different network. The network passed to connect must be identical to the one passed to bind.concurrency-conflict: Another bind or connect operation is already in progress. (EALREADY)finish errorsephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)error-code>finish-connect: functhis: udp-socketerror-code>receive: funcReceive messages on the socket.
+This function attempts to receive up to max-results datagrams on the socket without blocking.
+The returned list may contain fewer elements than requested, but never more.
+If max-results is 0, this function returns successfully with an empty list.
not-bound: The socket is not bound to any local address. (EINVAL)remote-unreachable: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)would-block: There is no pending data available to be read at the moment. (EWOULDBLOCK, EAGAIN)this: udp-socketmax-results: u64datagram>, error-code>send: funcSend messages on the socket.
+This function attempts to send all provided datagrams on the socket without blocking and
+returns how many messages were actually sent (or queued for sending).
This function semantically behaves the same as iterating the datagrams list and sequentially
+sending each individual datagram until either the end of the list has been reached or the first error occurred.
+If at least one datagram has been sent successfully, this function never returns an error.
If the input list is empty, the function returns ok(0).
The remote address option is required. To send a message to the "connected" peer,
+call remote-address to get their address.
address-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-remote-address: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)already-connected: The socket is in "connected" mode and the datagram.remote-address does not match the address passed to connect. (EISCONN)not-bound: The socket is not bound to any local address. Unlike POSIX, this function does not perform an implicit bind.remote-unreachable: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)datagram-too-large: The datagram is too large. (EMSGSIZE)would-block: The send buffer is currently full. (EWOULDBLOCK, EAGAIN)this: udp-socketdatagrams: list<datagram>u64, error-code>local-address: funcGet the current bound address.
+not-bound: The socket is not bound to any local address.this: udp-socketip-socket-address, error-code>remote-address: funcGet the address set with connect.
not-connected: The socket is not connected to a remote address. (ENOTCONN)this: udp-socketip-socket-address, error-code>address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
+this: udp-socketipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+ipv6-only-operation: (get/set) this socket is an IPv4 socket.already-bound: (set) The socket is already bound.not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)this: udp-socketbool, error-code>set-ipv6-only: functhis: udp-socketvalue: boolerror-code>unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)this: udp-socketu8, error-code>set-unicast-hop-limit: functhis: udp-socketvalue: u8error-code>receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+Note #1: an implementation may choose to cap or round the buffer size when setting the value. +In other words, after setting a value, reading the same setting back may return a different value.
+Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of +actual data to be sent/received by the application, because the kernel might also use the buffer space +for internal metadata structures.
+Fails when this socket is in the Listening state.
+Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)this: udp-socketu64, error-code>set-receive-buffer-size: functhis: udp-socketvalue: u64error-code>send-buffer-size: functhis: udp-socketu64, error-code>set-send-buffer-size: functhis: udp-socketvalue: u64error-code>subscribe: funcCreate a pollable which will resolve once the socket is ready for I/O.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future is natively supported in Preview3.
this: udp-socketpollabledrop-udp-socket: funcDispose of the specified udp-socket, after which it may no longer be used.
Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+this: udp-sockettype network+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +
+#### `type udp-socket` +[`udp-socket`](#udp_socket) +
+---- +
create-udp-socket: funcCreate a new UDP socket.
+Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX.
This function does not require a network capability handle. This is considered to be safe because
+at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect is called,
+the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
+not-supported: The host does not support UDP sockets. (EOPNOTSUPP)address-family-not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)udp-socket, error-code>WASI Random is a random data API.
+It is intended to be portable at least between Unix-family platforms and +Windows.
+get-random-bytes: funcReturn 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.
+This function must always return fresh data. Deterministic environments +must omit this function, rather than implementing it with deterministic +data.
+len: u64get-random-u64: funcReturn 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.
The insecure interface for insecure pseudo-random numbers.
+It is intended to be portable at least between Unix-family platforms and +Windows.
+get-insecure-random-bytes: funcReturn 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.
+len: u64get-insecure-random-u64: funcReturn 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.
The insecure-seed interface for seeding hash-map DoS resistance.
+It is intended to be portable at least between Unix-family platforms and +Windows.
+insecure-seed: funcReturn 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.
+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.
+get-environment: funcGet 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.
+get-arguments: funcGet the POSIX-style arguments to the program.
+initial-cwd: funcReturn a path that programs should use as their initial current working
+directory, interpreting . as shorthand for this.
exit: funcExit the current instance and any linked instances.
+status: resulttype input-stream+---- +
get-stdin: funcinput-streamtype output-stream+---- +
get-stdout: funcoutput-streamtype output-stream+---- +
get-stderr: funcoutput-streamtype terminal-inputu32
The input side of a terminal. +
This represents a resource.
+drop-terminal-input: funcDispose of the specified terminal-input after which it may no longer +be used.
+this: terminal-inputtype terminal-outputu32
The output side of a terminal. +
This represents a resource.
+drop-terminal-output: funcDispose of the specified terminal-output, after which it may no longer +be used.
+this: terminal-outputAn interface providing an optional terminal-input for stdin as a
+link-time authority.
type terminal-input+---- +
get-terminal-stdin: funcIf stdin is connected to a terminal, return a terminal-input handle
+allowing further interaction with it.
terminal-input>An interface providing an optional terminal-output for stdout as a
+link-time authority.
type terminal-output+---- +
get-terminal-stdout: funcIf stdout is connected to a terminal, return a terminal-output handle
+allowing further interaction with it.
terminal-output>An interface providing an optional terminal-output for stderr as a
+link-time authority.
type terminal-output+---- +
get-terminal-stderr: funcIf stderr is connected to a terminal, return a terminal-output handle
+allowing further interaction with it.
terminal-output>