diff --git a/command.md b/command.md index 646c049..e918f51 100644 --- a/command.md +++ b/command.md @@ -8,6 +8,7 @@
  • interface wasi:clocks/timezone
  • interface wasi:io/streams
  • interface wasi:filesystem/types
  • +
  • interface wasi:filesystem/preopens
  • interface wasi:sockets/network
  • interface wasi:sockets/instance-network
  • interface wasi:sockets/ip-name-lookup
  • @@ -19,7 +20,6 @@
  • interface wasi:random/insecure
  • interface wasi:random/insecure-seed
  • interface wasi:cli/environment
  • -
  • interface wasi:cli/preopens
  • interface wasi:cli/exit
  • interface wasi:cli/stdin
  • interface wasi:cli/stdout
  • @@ -101,24 +101,31 @@ be used.

    poll-oneoff: func

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

    -

    Note that the return type would ideally be list<bool>, but that would -be more difficult to polyfill given the current state of wit-bindgen. -See https://github.com/bytecodealliance/preview2-prototyping/pull/11#issuecomment-1329873061 -for details. For now, we use zero to mean "not ready" and non-zero to -mean "ready".

    Params
    Return values

    Import interface wasi:clocks/monotonic-clock

    WASI Monotonic Clock is a clock API intended to let users measure elapsed @@ -255,7 +262,24 @@ when it does, they are expected to subsume this API.

    type pollable

    pollable

    -#### `record stream-error` +#### `enum stream-status` +

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

    +
    Enum Cases
    + +

    record stream-error

    An error type returned from a stream operation. Currently this doesn't provide any additional information.

    Record Fields
    @@ -294,9 +318,9 @@ the wit-bindgen implementation of handles and resources is ready.

    read: func

    Read bytes from a stream.

    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 -stream was reached. The returned list will contain up to len bytes; it -may return fewer than requested, but not more.

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

    @@ -313,7 +337,7 @@ FIXME: describe what happens if allocation fails.

    Return values

    blocking-read: func

    Read bytes from a stream, with blocking.

    @@ -326,7 +350,7 @@ byte can be read.

    Return values

    skip: func

    Skip bytes from a stream.

    @@ -335,9 +359,9 @@ 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 bool -indicating whether the end of the stream was reached. The returned -value will be at most len; it may be less.

    +

    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.

    Params
    Return values

    blocking-skip: func

    Skip bytes from a stream, with blocking.

    @@ -358,7 +382,7 @@ byte can be consumed.

    Return values

    subscribe-to-input-stream: func

    Create a pollable which will resolve once either the specified stream @@ -445,7 +469,7 @@ read from the input stream has been written to the output stream.

    Return values

    blocking-splice: func

    Read from one stream and write to another, with blocking.

    @@ -459,7 +483,7 @@ one byte can be read.

    Return values

    forward: func

    Forward the entire contents of an input stream to an output stream.

    @@ -574,12 +598,23 @@ filesystem. filesystem. This does not apply to directories. +

    record metadata-hash-value

    +

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

    +
    Record Fields
    +

    type link-count

    u64

    Number of hard links to an inode. -

    type inode

    -

    u64

    -

    Filesystem object serial number that is unique within its file system.

    type filesize

    u64

    File size or length of a region within a file. @@ -743,11 +778,6 @@ merely for alignment with POSIX.

    u32

    A stream of directory entries.

    This represents a stream of dir-entry.

    -

    type device

    -

    u64

    -

    Identifier for a device containing a file system. Can be used in -combination with `inode` to uniquely identify a file or directory in -the filesystem.

    enum descriptor-type

    The type of a filesystem object referenced by a descriptor.

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

    @@ -792,14 +822,6 @@ any of the other types specified.
    Record Fields
    Return values

    append-via-stream: func

    -

    Return a stream for appending to a file.

    +

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

    Params
    @@ -1017,7 +1034,7 @@ POSIX.

    Return values

    advise: func

    Provide file advisory information on a descriptor.

    @@ -1195,7 +1212,11 @@ opened for writing.

    stat: func

    Return the attributes of an open file or directory.

    -

    Note: This is similar to fstat in POSIX.

    +

    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

    stat-at: func

    Return the attributes of a file or directory.

    -

    Note: This is similar to fstatat in POSIX.

    +

    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

    receive: func

    -

    Receive a message.

    -

    Returns:

    - +

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

    Typical errors