Refer to https://hackmd.io/@q/wasi-preview1-api for modules.

Types

size: u32

• Size: 4
• Alignment: 4

filesize: u64

Non-negative file size or length of a region within a file.

• Size: 8
• Alignment: 8

timestamp: u64

Timestamp in nanoseconds.

• Size: 8
• Alignment: 8

clockid: Variant

Identifiers for clocks.

• Size: 4

• Alignment: 4

• Cases:

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

  • monotonic
    The store-wide monotonic clock, which is defined as a clock measuring
    real time, whose value cannot be adjusted and which cannot have negative
    clock jumps. The epoch of this clock is undefined. The absolute time
    value of this clock therefore has no meaning.

  • process_cputime_id
    The CPU-time clock associated with the current process.

  • thread_cputime_id
    The CPU-time clock associated with the current thread.

errno: Variant

Error codes returned by functions.
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.

• Size: 2

• Alignment: 2

• Cases:

  • success
    No error occurred. System call completed successfully.

  • 2big
    Argument list too long.

  • acces
    Permission denied.

  • addrinuse
    Address in use.

  • addrnotavail
    Address not available.

  • afnosupport
    Address family not supported.

  • again
    Resource unavailable, or operation would block.

  • already
    Connection already in progress.

  • badf
    Bad file descriptor.

  • badmsg
    Bad message.

  • busy
    Device or resource busy.

  • canceled
    Operation canceled.

  • child
    No child processes.

  • connaborted
    Connection aborted.

  • connrefused
    Connection refused.

  • connreset
    Connection reset.

  • deadlk
    Resource deadlock would occur.

  • destaddrreq
    Destination address required.

  • dom
    Mathematics argument out of domain of function.

  • dquot
    Reserved.

  • exist
    File exists.

  • fault
    Bad address.

  • fbig
    File too large.

  • hostunreach
    Host is unreachable.

  • idrm
    Identifier removed.

  • ilseq
    Illegal byte sequence.

  • inprogress
    Operation in progress.

  • intr
    Interrupted function.

  • inval
    Invalid argument.

  • io
    I/O error.

  • isconn
    Socket is connected.

  • isdir
    Is a directory.

  • loop
    Too many levels of symbolic links.

  • mfile
    File descriptor value too large.

  • mlink
    Too many links.

  • msgsize
    Message too large.

  • multihop
    Reserved.

  • nametoolong
    Filename too long.

  • netdown
    Network is down.

  • netreset
    Connection aborted by network.

  • netunreach
    Network unreachable.

  • nfile
    Too many files open in system.

  • nobufs
    No buffer space available.

  • nodev
    No such device.

  • noent
    No such file or directory.

  • noexec
    Executable file format error.

  • nolck
    No locks available.

  • nolink
    Reserved.

  • nomem
    Not enough space.

  • nomsg
    No message of the desired type.

  • noprotoopt
    Protocol not available.

  • nospc
    No space left on device.

  • nosys
    Function not supported.

  • notconn
    The socket is not connected.

  • notdir
    Not a directory or a symbolic link to a directory.

  • notempty
    Directory not empty.

  • notrecoverable
    State not recoverable.

  • notsock
    Not a socket.

  • notsup
    Not supported, or operation not supported on socket.

  • notty
    Inappropriate I/O control operation.

  • nxio
    No such device or address.

  • overflow
    Value too large to be stored in data type.

  • ownerdead
    Previous owner died.

  • perm
    Operation not permitted.

  • pipe
    Broken pipe.

  • proto
    Protocol error.

  • protonosupport
    Protocol not supported.

  • prototype
    Protocol wrong type for socket.

  • range
    Result too large.

  • rofs
    Read-only file system.

  • spipe
    Invalid seek.

  • srch
    No such process.

  • stale
    Reserved.

  • timedout
    Connection timed out.

  • txtbsy
    Text file busy.

  • xdev
    Cross-device link.

  • notcapable
    Extension: Capabilities insufficient.

rights: Record

File descriptor rights, determining which actions may be performed.

• Size: 8

• Alignment: 8

  • (Bit: 0) fd_datasync: bool
    The right to invoke fd_datasync.
    If path_open is set, includes the right to invoke
    path_open with fdflags::dsync.

  • (Bit: 1) fd_read: bool
    The right to invoke fd_read and sock_recv.
    If rights::fd_seek is set, includes the right to invoke fd_pread.

  • (Bit: 2) fd_seek: bool
    The right to invoke fd_seek. This flag implies rights::fd_tell.

  • (Bit: 3) fd_fdstat_set_flags: bool
    The right to invoke fd_fdstat_set_flags.

  • (Bit: 4) fd_sync: bool
    The right to invoke fd_sync.
    If path_open is set, includes the right to invoke
    path_open with fdflags::rsync and fdflags::dsync.

  • (Bit: 5) fd_tell: bool
    The right to invoke fd_seek in such a way that the file offset
    remains unaltered (i.e., whence::cur with offset zero), or to
    invoke fd_tell.

  • (Bit: 6) fd_write: bool
    The right to invoke fd_write and sock_send.
    If rights::fd_seek is set, includes the right to invoke fd_pwrite.

  • (Bit: 7) fd_advise: bool
    The right to invoke fd_advise.

  • (Bit: 8) fd_allocate: bool
    The right to invoke fd_allocate.

  • (Bit: 9) path_create_directory: bool
    The right to invoke path_create_directory.

  • (Bit: 10) path_create_file: bool
    If path_open is set, the right to invoke path_open with oflags::creat.

  • (Bit: 11) path_link_source: bool
    The right to invoke path_link with the file descriptor as the
    source directory.

  • (Bit: 12) path_link_target: bool
    The right to invoke path_link with the file descriptor as the
    target directory.

  • (Bit: 13) path_open: bool
    The right to invoke path_open.

  • (Bit: 14) fd_readdir: bool
    The right to invoke fd_readdir.

  • (Bit: 15) path_readlink: bool
    The right to invoke path_readlink.

  • (Bit: 16) path_rename_source: bool
    The right to invoke path_rename with the file descriptor as the source directory.

  • (Bit: 17) path_rename_target: bool
    The right to invoke path_rename with the file descriptor as the target directory.

  • (Bit: 18) path_filestat_get: bool
    The right to invoke path_filestat_get.

  • (Bit: 19) path_filestat_set_size: bool
    The right to change a file's size.
    If path_open is set, includes the right to invoke path_open with oflags::trunc.
    Note: there is no function named path_filestat_set_size. This follows POSIX design,
    which only has ftruncate and does not provide ftruncateat.
    While such function would be desirable from the API design perspective, there are virtually
    no use cases for it since no code written for POSIX systems would use it.
    Moreover, implementing it would require multiple syscalls, leading to inferior performance.

  • (Bit: 20) path_filestat_set_times: bool
    The right to invoke path_filestat_set_times.

  • (Bit: 21) fd_filestat_get: bool
    The right to invoke fd_filestat_get.

  • (Bit: 22) fd_filestat_set_size: bool
    The right to invoke fd_filestat_set_size.

  • (Bit: 23) fd_filestat_set_times: bool
    The right to invoke fd_filestat_set_times.

  • (Bit: 24) path_symlink: bool
    The right to invoke path_symlink.

  • (Bit: 25) path_remove_directory: bool
    The right to invoke path_remove_directory.

  • (Bit: 26) path_unlink_file: bool
    The right to invoke path_unlink_file.

  • (Bit: 27) poll_fd_readwrite: bool
    If rights::fd_read is set, includes the right to invoke poll_oneoff to subscribe to eventtype::fd_read.
    If rights::fd_write is set, includes the right to invoke poll_oneoff to subscribe to eventtype::fd_write.

  • (Bit: 28) sock_shutdown: bool
    The right to invoke sock_shutdown.

  • (Bit: 29) sock_accept: bool
    The right to invoke sock_accept.

fd: Handle

A file descriptor handle.

• Size: 4
• Alignment: 4

iovec: Record

A region of memory for scatter/gather reads.

• Size: 8

• Alignment: 4

  • (Offset: 0) buf: Pointer<u8>
    The address of the buffer to be filled.

  • (Offset: 4) buf_len: size
    The length of the buffer to be filled.

ciovec: Record

A region of memory for scatter/gather writes.

• Size: 8

• Alignment: 4

  • (Offset: 0) buf: ConstPointer<u8>
    The address of the buffer to be written.

  • (Offset: 4) buf_len: size
    The length of the buffer to be written.

iovec_array: List<iovec>

• Size: 8
• Alignment: 4

ciovec_array: List<ciovec>

• Size: 8
• Alignment: 4

filedelta: s64

Relative offset within a file.

• Size: 8
• Alignment: 8

whence: Variant

The position relative to which to set the offset of the file descriptor.

• Size: 1

• Alignment: 1

• Cases:

  • set
    Seek relative to start-of-file.

  • cur
    Seek relative to current position.

  • end
    Seek relative to end-of-file.

dircookie: u64

A reference to the offset of a directory entry.

The value 0 signifies the start of the directory.

• Size: 8
• Alignment: 8

dirnamlen: u32

The type for the dirent::d_namlen field of dirent struct.

• Size: 4
• Alignment: 4

inode: u64

File serial number that is unique within its file system.

• Size: 8
• Alignment: 8

filetype: Variant

The type of a file descriptor or file.

• Size: 1

• Alignment: 1

• Cases:

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

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

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

  • directory
    The file descriptor or file refers to a directory inode.

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

  • socket_dgram
    The file descriptor or file refers to a datagram socket.

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

  • symbolic_link
    The file refers to a symbolic link inode.

dirent: Record

A directory entry.

• Size: 24

• Alignment: 8

  • (Offset: 0) d_next: dircookie
    The offset of the next directory entry stored in this directory.

  • (Offset: 8) d_ino: inode
    The serial number of the file referred to by this directory entry.

  • (Offset: 16) d_namlen: dirnamlen
    The length of the name of the directory entry.

  • (Offset: 20) d_type: filetype
    The type of the file referred to by this directory entry.

advice: Variant

File or memory access pattern advisory information.

• Size: 1

• Alignment: 1

• Cases:

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

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

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

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

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

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

fdflags: Record

File descriptor flags.

• Size: 2

• Alignment: 2

  • (Bit: 0) append: bool
    Append mode: Data written to the file is always appended to the file's end.

  • (Bit: 1) dsync: bool
    Write according to synchronized I/O data integrity completion. Only the data stored in the file is synchronized.

  • (Bit: 2) nonblock: bool
    Non-blocking mode.

  • (Bit: 3) rsync: bool
    Synchronized read I/O operations.

  • (Bit: 4) sync: bool
    Write according to synchronized I/O file integrity completion. In
    addition to synchronizing the data stored in the file, the implementation
    may also synchronously update the file's metadata.

fdstat: Record

File descriptor attributes.

• Size: 24

• Alignment: 8

  • (Offset: 0) fs_filetype: filetype
    File type.

  • (Offset: 2) fs_flags: fdflags
    File descriptor flags.

  • (Offset: 8) fs_rights_base: rights
    Rights that apply to this file descriptor.

  • (Offset: 16) fs_rights_inheriting: rights
    Maximum set of rights that may be installed on new file descriptors that
    are created through this file descriptor, e.g., through path_open.

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.

• Size: 8
• Alignment: 8

fstflags: Record

Which file time attributes to adjust.

• Size: 2

• Alignment: 2

  • (Bit: 0) atim: bool
    Adjust the last data access timestamp to the value stored in filestat::atim.

  • (Bit: 1) atim_now: bool
    Adjust the last data access timestamp to the time of clock clockid::realtime.

  • (Bit: 2) mtim: bool
    Adjust the last data modification timestamp to the value stored in filestat::mtim.

  • (Bit: 3) mtim_now: bool
    Adjust the last data modification timestamp to the time of clock clockid::realtime.

lookupflags: Record

Flags determining the method of how paths are resolved.

• Size: 4

• Alignment: 4

  • (Bit: 0) symlink_follow: bool
    As long as the resolved path corresponds to a symbolic link, it is expanded.

oflags: Record

Open flags used by path_open.

• Size: 2

• Alignment: 2

  • (Bit: 0) creat: bool
    Create file if it does not exist.

  • (Bit: 1) directory: bool
    Fail if not a directory.

  • (Bit: 2) excl: bool
    Fail if file already exists.

  • (Bit: 3) trunc: bool
    Truncate file to size 0.

linkcount: u64

Number of hard links to an inode.

• Size: 8
• Alignment: 8

filestat: Record

File attributes.

• Size: 64

• Alignment: 8

  • (Offset: 0) dev: device
    Device ID of device containing the file.

  • (Offset: 8) ino: inode
    File serial number.

  • (Offset: 16) filetype: filetype
    File type.

  • (Offset: 24) nlink: linkcount
    Number of hard links to the file.

  • (Offset: 32) size: filesize
    For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link.

  • (Offset: 40) atim: timestamp
    Last data access timestamp.
    This can be 0 if the underlying platform doesn't provide suitable
    timestamp for this file.

  • (Offset: 48) mtim: timestamp
    Last data modification timestamp.
    This can be 0 if the underlying platform doesn't provide suitable
    timestamp for this file.

  • (Offset: 56) ctim: timestamp
    Last file status change timestamp.
    This can be 0 if the underlying platform doesn't provide suitable
    timestamp for this file.

userdata: u64

User-provided value that may be attached to objects that is retained when
extracted from the implementation.

• Size: 8
• Alignment: 8

eventtype: Variant

Type of a subscription to an event or its occurrence.

• Size: 1

• Alignment: 1

• Cases:

  • clock
    The time value of clock subscription_clock::id has
    reached timestamp subscription_clock::timeout.

  • fd_read
    File descriptor subscription_fd_readwrite::file_descriptor has data
    available for reading. This event always triggers for regular files.

  • fd_write
    File descriptor subscription_fd_readwrite::file_descriptor has capacity
    available for writing. This event always triggers for regular files.

eventrwflags: Record

The state of the file descriptor subscribed to with
eventtype::fd_read or eventtype::fd_write.

• Size: 2

• Alignment: 2

  • (Bit: 0) fd_readwrite_hangup: bool
    The peer of this socket has closed or disconnected.

event_fd_readwrite: Record

The contents of an event when type is eventtype::fd_read or
eventtype::fd_write.

• Size: 16

• Alignment: 8

  • (Offset: 0) nbytes: filesize
    The number of bytes available for reading or writing.

  • (Offset: 8) flags: eventrwflags
    The state of the file descriptor.

event: Record

An event that occurred.

• Size: 32

• Alignment: 8

  • (Offset: 0) userdata: userdata
    User-provided value that got attached to subscription::userdata.

  • (Offset: 8) error: errno
    If non-zero, an error that occurred while processing the subscription request.

  • (Offset: 10) type: eventtype
    The type of event that occured

  • (Offset: 16) fd_readwrite: event_fd_readwrite
    The contents of the event, if it is an eventtype::fd_read or
    eventtype::fd_write. eventtype::clock events ignore this field.

subclockflags: Record

Flags determining how to interpret the timestamp provided in
subscription_clock::timeout.

• Size: 2

• Alignment: 2

  • (Bit: 0) subscription_clock_abstime: bool
    If set, treat the timestamp provided in
    subscription_clock::timeout as an absolute timestamp of clock
    subscription_clock::id. If clear, treat the timestamp
    provided in subscription_clock::timeout relative to the
    current time value of clock subscription_clock::id.

subscription_clock: Record

The contents of a subscription when type is eventtype::clock.

• Size: 32

• Alignment: 8

  • (Offset: 0) id: clockid
    The clock against which to compare the timestamp.

  • (Offset: 8) timeout: timestamp
    The absolute or relative timestamp.

  • (Offset: 16) precision: timestamp
    The amount of time that the implementation may wait additionally
    to coalesce with other events.

  • (Offset: 24) flags: subclockflags
    Flags specifying whether the timeout is absolute or relative

subscription_fd_readwrite: Record

The contents of a subscription when type is type is
eventtype::fd_read or eventtype::fd_write.

• Size: 4

• Alignment: 4

  • (Offset: 0) file_descriptor: fd
    The file descriptor on which to wait for it to become ready for reading or writing.

subscription_u: Variant

The contents of a subscription.

• Size: 40
• Alignment: 8

Variants

• size: 40; align: 8; tag_size: 1
• Cases:

  • clock: subscription_clock

  • fd_read: subscription_fd_readwrite

  • fd_write: subscription_fd_readwrite

subscription: Record

Subscription to an event.

• Size: 48

• Alignment: 8

  • (Offset: 0) userdata: userdata
    User-provided value that is attached to the subscription in the
    implementation and returned through event::userdata.

  • (Offset: 8) u: subscription_u
    The type of the event to which to subscribe, and its contents

exitcode: u32

Exit code generated by a process when exiting.

• Size: 4
• Alignment: 4

signal: Variant

Signal condition.

• Size: 1

• Alignment: 1

• Cases:

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

  • hup
    Hangup.
    Action: Terminates the process.

  • int
    Terminate interrupt signal.
    Action: Terminates the process.

  • quit
    Terminal quit signal.
    Action: Terminates the process.

  • ill
    Illegal instruction.
    Action: Terminates the process.

  • trap
    Trace/breakpoint trap.
    Action: Terminates the process.

  • abrt
    Process abort signal.
    Action: Terminates the process.

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

  • fpe
    Erroneous arithmetic operation.
    Action: Terminates the process.

  • kill
    Kill.
    Action: Terminates the process.

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

  • segv
    Invalid memory reference.
    Action: Terminates the process.

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

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

  • alrm
    Alarm clock.
    Action: Terminates the process.

  • term
    Termination signal.
    Action: Terminates the process.

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

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

  • stop
    Stop executing.
    Action: Stops executing.

  • tstp
    Terminal stop signal.
    Action: Stops executing.

  • ttin
    Background process attempting read.
    Action: Stops executing.

  • ttou
    Background process attempting write.
    Action: Stops executing.

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

  • xcpu
    CPU time limit exceeded.
    Action: Terminates the process.

  • xfsz
    File size limit exceeded.
    Action: Terminates the process.

  • vtalrm
    Virtual timer expired.
    Action: Terminates the process.

  • prof
    Profiling timer expired.
    Action: Terminates the process.

  • winch
    Window changed.
    Action: Ignored.

  • poll
    I/O possible.
    Action: Terminates the process.

  • pwr
    Power failure.
    Action: Terminates the process.

  • sys
    Bad system call.
    Action: Terminates the process.

riflags: Record

Flags provided to sock_recv.

• Size: 2

• Alignment: 2

  • (Bit: 0) recv_peek: bool
    Returns the message without removing it from the socket's receive queue.

  • (Bit: 1) recv_waitall: bool
    On byte-stream sockets, block until the full amount of data can be returned.

roflags: Record

Flags returned by sock_recv.

• Size: 2

• Alignment: 2

  • (Bit: 0) recv_data_truncated: bool
    Returned by sock_recv: Message data has been truncated.

siflags: u16

Flags provided to sock_send. As there are currently no flags
defined, it must be set to zero.

• Size: 2
• Alignment: 2

sdflags: Record

Which channels on a socket to shut down.

• Size: 1

• Alignment: 1

  • (Bit: 0) rd: bool
    Disables further receive operations.

  • (Bit: 1) wr: bool
    Disables further send operations.

preopentype: Variant

Identifiers for preopened capabilities.

• Size: 1

• Alignment: 1

• Cases:

  • dir
    A pre-opened directory.

prestat_dir: Record

The contents of a prestat when type is preopentype::dir.

• Size: 4

• Alignment: 4

  • (Offset: 0) pr_name_len: size
    The length of the directory name for use with fd_prestat_dir_name.

prestat: Variant

Information about a pre-opened capability.

• Size: 8
• Alignment: 4

Variants

• size: 8; align: 4; tag_size: 1
• Cases:
  • dir: prestat_dir