Skip to content
Permalink
main
Switch branches/tags

WASI/phases/snapshot/docs.md

Go to file
@npmccallum
npmccallum Add sock_accept() to snapshot1 (#458)
Latest commit 0ba0c5e Jan 18, 2022 History 
This function allows a server to accept incoming connections. A few
notes are in order.

Although there are legitimate questions about the capabilities model in
numerous networking APIs, this particular API is both immensely useful
and not a violation of the capabilities model. There is still no way to
create an arbitrary socket. The only thing that WASM can do is accept
incoming connections on a predefined listening socket.

Signed-off-by: Nathaniel McCallum <nathaniel@profian.com>
9 contributors

Users who have contributed to this file

@alexcrichton @pchickey @kubkon @vapier @npmccallum @cratelyn @MaulingMonkey @ailisp @torch2424
Types size: u32 filesize: u64 timestamp: u64 clockid: Variant Variant cases errno: Variant Variant cases rights: Record Record members fd: Handle Supertypes iovec: Record Record members ciovec: Record Record members iovec_array: List<iovec> ciovec_array: List<ciovec> filedelta: s64 whence: Variant Variant cases dircookie: u64 dirnamlen: u32 inode: u64 filetype: Variant Variant cases dirent: Record Record members advice: Variant Variant cases fdflags: Record Record members fdstat: Record Record members device: u64 fstflags: Record Record members lookupflags: Record Record members oflags: Record Record members linkcount: u64 filestat: Record Record members userdata: u64 eventtype: Variant Variant cases eventrwflags: Record Record members event_fd_readwrite: Record Record members event: Record Record members subclockflags: Record Record members subscription_clock: Record Record members subscription_fd_readwrite: Record Record members subscription_u: Variant Variant Layout Variant cases subscription: Record Record members exitcode: u32 signal: Variant Variant cases riflags: Record Record members roflags: Record Record members siflags: u16 sdflags: Record Record members preopentype: Variant Variant cases prestat_dir: Record Record members prestat: Variant Variant Layout Variant cases Modules wasi_snapshot_preview1 Imports Memory Functions args_get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) -> Result<(), errno> Params Results Variant Layout Variant cases args_sizes_get() -> Result<(size, size), errno> Params Results Variant Layout Variant cases environ_get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) -> Result<(), errno> Params Results Variant Layout Variant cases environ_sizes_get() -> Result<(size, size), errno> Params Results Variant Layout Variant cases clock_res_get(id: clockid) -> Result<timestamp, errno> Params Results Variant Layout Variant cases clock_time_get(id: clockid, precision: timestamp) -> Result<timestamp, errno> Params Results Variant Layout Variant cases fd_advise(fd: fd, offset: filesize, len: filesize, advice: advice) -> Result<(), errno> Params Results Variant Layout Variant cases fd_allocate(fd: fd, offset: filesize, len: filesize) -> Result<(), errno> Params Results Variant Layout Variant cases fd_close(fd: fd) -> Result<(), errno> Params Results Variant Layout Variant cases fd_datasync(fd: fd) -> Result<(), errno> Params Results Variant Layout Variant cases fd_fdstat_get(fd: fd) -> Result<fdstat, errno> Params Results Variant Layout Variant cases fd_fdstat_set_flags(fd: fd, flags: fdflags) -> Result<(), errno> Params Results Variant Layout Variant cases fd_fdstat_set_rights(fd: fd, fs_rights_base: rights, fs_rights_inheriting: rights) -> Result<(), errno> Params Results Variant Layout Variant cases fd_filestat_get(fd: fd) -> Result<filestat, errno> Params Results Variant Layout Variant cases fd_filestat_set_size(fd: fd, size: filesize) -> Result<(), errno> Params Results Variant Layout Variant cases fd_filestat_set_times(fd: fd, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> Result<(), errno> Params Results Variant Layout Variant cases fd_pread(fd: fd, iovs: iovec_array, offset: filesize) -> Result<size, errno> Params Results Variant Layout Variant cases fd_prestat_get(fd: fd) -> Result<prestat, errno> Params Results Variant Layout Variant cases fd_prestat_dir_name(fd: fd, path: Pointer<u8>, path_len: size) -> Result<(), errno> Params Results Variant Layout Variant cases fd_pwrite(fd: fd, iovs: ciovec_array, offset: filesize) -> Result<size, errno> Params Results Variant Layout Variant cases fd_read(fd: fd, iovs: iovec_array) -> Result<size, errno> Params Results Variant Layout Variant cases fd_readdir(fd: fd, buf: Pointer<u8>, buf_len: size, cookie: dircookie) -> Result<size, errno> Params Results Variant Layout Variant cases fd_renumber(fd: fd, to: fd) -> Result<(), errno> Params Results Variant Layout Variant cases fd_seek(fd: fd, offset: filedelta, whence: whence) -> Result<filesize, errno> Params Results Variant Layout Variant cases fd_sync(fd: fd) -> Result<(), errno> Params Results Variant Layout Variant cases fd_tell(fd: fd) -> Result<filesize, errno> Params Results Variant Layout Variant cases fd_write(fd: fd, iovs: ciovec_array) -> Result<size, errno> Params Results Variant Layout Variant cases path_create_directory(fd: fd, path: string) -> Result<(), errno> Params Results Variant Layout Variant cases path_filestat_get(fd: fd, flags: lookupflags, path: string) -> Result<filestat, errno> Params Results Variant Layout Variant cases path_filestat_set_times(fd: fd, flags: lookupflags, path: string, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> Result<(), errno> Params Results Variant Layout Variant cases path_link(old_fd: fd, old_flags: lookupflags, old_path: string, new_fd: fd, new_path: string) -> Result<(), errno> Params Results Variant Layout Variant cases path_open(fd: fd, dirflags: lookupflags, path: string, oflags: oflags, fs_rights_base: rights, fs_rights_inheriting: rights, fdflags: fdflags) -> Result<fd, errno> Params Results Variant Layout Variant cases path_readlink(fd: fd, path: string, buf: Pointer<u8>, buf_len: size) -> Result<size, errno> Params Results Variant Layout Variant cases path_remove_directory(fd: fd, path: string) -> Result<(), errno> Params Results Variant Layout Variant cases path_rename(fd: fd, old_path: string, new_fd: fd, new_path: string) -> Result<(), errno> Params Results Variant Layout Variant cases path_symlink(old_path: string, fd: fd, new_path: string) -> Result<(), errno> Params Results Variant Layout Variant cases path_unlink_file(fd: fd, path: string) -> Result<(), errno> Params Results Variant Layout Variant cases poll_oneoff(in: ConstPointer<subscription>, out: Pointer<event>, nsubscriptions: size) -> Result<size, errno> Params Results Variant Layout Variant cases proc_exit(rval: exitcode) Params Results proc_raise(sig: signal) -> Result<(), errno> Params Results Variant Layout Variant cases sched_yield() -> Result<(), errno> Params Results Variant Layout Variant cases random_get(buf: Pointer<u8>, buf_len: size) -> Result<(), errno> Params Results Variant Layout Variant cases sock_accept(fd: fd, flags: fdflags) -> Result<fd, errno> Params Results Variant Layout Variant cases sock_recv(fd: fd, ri_data: iovec_array, ri_flags: riflags) -> Result<(size, roflags), errno> Params Results Variant Layout Variant cases sock_send(fd: fd, si_data: ciovec_array, si_flags: siflags) -> Result<size, errno> Params Results Variant Layout Variant cases sock_shutdown(fd: fd, how: sdflags) -> Result<(), errno> Params Results Variant Layout Variant cases
2541 lines (1701 sloc) 81.3 KB
Raw Blame
Open in GitHub Desktop

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

Variant 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

Variant 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

Record members

Bit: 0

Bit: 1

Bit: 2

Bit: 3

Bit: 4

  • 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: 5

Bit: 6

  • fd_advise: bool The right to invoke fd_advise.

Bit: 7

Bit: 8

Bit: 9

Bit: 10

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

Bit: 11

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

Bit: 12

  • path_open: bool The right to invoke path_open.

Bit: 13

  • fd_readdir: bool The right to invoke fd_readdir.

Bit: 14

Bit: 15

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

Bit: 16

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

Bit: 17

Bit: 18

  • path_filestat_set_size: bool The right to change a file's size (there is no path_filestat_set_size). If path_open is set, includes the right to invoke path_open with oflags::trunc.

Bit: 19

Bit: 20

Bit: 21

Bit: 22

Bit: 23

Bit: 24

Bit: 25

Bit: 26

Bit: 27

Bit: 28

Bit: 29

fd: Handle

A file descriptor handle.

Size: 4

Alignment: 4

Supertypes

iovec: Record

A region of memory for scatter/gather reads.

Size: 8

Alignment: 4

Record members

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

Offset: 0

  • buf_len: size The length of the buffer to be filled.

Offset: 4

ciovec: Record

A region of memory for scatter/gather writes.

Size: 8

Alignment: 4

Record members

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

Offset: 0

  • buf_len: size The length of the buffer to be written.

Offset: 4

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

Variant 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

Variant 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

Record members

  • d_next: dircookie The offset of the next directory entry stored in this directory.

Offset: 0

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

Offset: 8

  • d_namlen: dirnamlen The length of the name of the directory entry.

Offset: 16

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

Offset: 20

advice: Variant

File or memory access pattern advisory information.

Size: 1

Alignment: 1

Variant 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

Record members

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

Bit: 0

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

Bit: 1

  • nonblock: bool Non-blocking mode.

Bit: 2

  • rsync: bool Synchronized read I/O operations.

Bit: 3

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

Bit: 4

fdstat: Record

File descriptor attributes.

Size: 24

Alignment: 8

Record members

Offset: 0

  • fs_flags: fdflags File descriptor flags.

Offset: 2

  • fs_rights_base: rights Rights that apply to this file descriptor.

Offset: 8

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

Offset: 16

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

Record members

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

Bit: 0

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

Bit: 1

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

Bit: 2

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

Bit: 3

lookupflags: Record

Flags determining the method of how paths are resolved.

Size: 4

Alignment: 4

Record members

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

Bit: 0

oflags: Record

Open flags used by path_open.

Size: 2

Alignment: 2

Record members

  • creat: bool Create file if it does not exist.

Bit: 0

  • directory: bool Fail if not a directory.

Bit: 1

  • excl: bool Fail if file already exists.

Bit: 2

  • trunc: bool Truncate file to size 0.

Bit: 3

linkcount: u64

Number of hard links to an inode.

Size: 8

Alignment: 8

filestat: Record

File attributes.

Size: 64

Alignment: 8

Record members

  • dev: device Device ID of device containing the file.

Offset: 0

  • ino: inode File serial number.

Offset: 8

Offset: 16

  • nlink: linkcount Number of hard links to the file.

Offset: 24

  • 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: 32

  • atim: timestamp Last data access timestamp.

Offset: 40

  • mtim: timestamp Last data modification timestamp.

Offset: 48

  • ctim: timestamp Last file status change timestamp.

Offset: 56

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

Variant cases

eventrwflags: Record

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

Size: 2

Alignment: 2

Record members

  • fd_readwrite_hangup: bool The peer of this socket has closed or disconnected.

Bit: 0

event_fd_readwrite: Record

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

Size: 16

Alignment: 8

Record members

  • nbytes: filesize The number of bytes available for reading or writing.

Offset: 0

Offset: 8

event: Record

An event that occurred.

Size: 32

Alignment: 8

Record members

Offset: 0

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

Offset: 8

  • type: eventtype The type of event that occured

Offset: 10

Offset: 16

subclockflags: Record

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

Size: 2

Alignment: 2

Record members

Bit: 0

subscription_clock: Record

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

Size: 32

Alignment: 8

Record members

  • id: clockid The clock against which to compare the timestamp.

Offset: 0

  • timeout: timestamp The absolute or relative timestamp.

Offset: 8

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

Offset: 16

  • flags: subclockflags Flags specifying whether the timeout is absolute or relative

Offset: 24

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

Record members

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

Offset: 0

subscription_u: Variant

The contents of a subscription.

Size: 40

Alignment: 8

Variant Layout

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

Variant cases

subscription: Record

Subscription to an event.

Size: 48

Alignment: 8

Record members

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

Offset: 0

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

Offset: 8

exitcode: u32

Exit code generated by a process when exiting.

Size: 4

Alignment: 4

signal: Variant

Signal condition.

Size: 1

Alignment: 1

Variant 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

Record members

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

Bit: 0

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

Bit: 1

roflags: Record

Flags returned by sock_recv.

Size: 2

Alignment: 2

Record members

  • recv_data_truncated: bool Returned by sock_recv: Message data has been truncated.

Bit: 0

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

Record members

  • rd: bool Disables further receive operations.

Bit: 0

  • wr: bool Disables further send operations.

Bit: 1

preopentype: Variant

Identifiers for preopened capabilities.

Size: 1

Alignment: 1

Variant cases

  • dir A pre-opened directory.

prestat_dir: Record

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

Size: 4

Alignment: 4

Record members

Offset: 0

prestat: Variant

Information about a pre-opened capability.

Size: 8

Alignment: 4

Variant Layout

  • size: 8
  • align: 4
  • tag_size: 1

Variant cases

Modules

wasi_snapshot_preview1

Imports

Memory

Functions

args_get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) -> Result<(), errno>

Read command-line argument data. The size of the array should match that returned by args_sizes_get. Each argument is expected to be \0 terminated.

Params

  • argv: Pointer<Pointer<u8>>

  • argv_buf: Pointer<u8>

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

args_sizes_get() -> Result<(size, size), errno>

Return command-line argument data sizes.

Params
Results
  • error: Result<(size, size), errno> Returns the number of arguments and the size of the argument string data, or an error.
Variant Layout
  • size: 12
  • align: 4
  • tag_size: 4
Variant cases
  • ok: (size, size)

####### Record members

Offset: 0

Offset: 4

environ_get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) -> Result<(), errno>

Read environment variable data. The sizes of the buffers should match that returned by environ_sizes_get. Key/value pairs are expected to be joined with =s, and terminated with \0s.

Params

  • environ: Pointer<Pointer<u8>>

  • environ_buf: Pointer<u8>

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

environ_sizes_get() -> Result<(size, size), errno>

Return environment variable data sizes.

Params
Results
  • error: Result<(size, size), errno> Returns the number of environment variable arguments and the size of the environment variable data.
Variant Layout
  • size: 12
  • align: 4
  • tag_size: 4
Variant cases
  • ok: (size, size)

####### Record members

Offset: 0

Offset: 4

clock_res_get(id: clockid) -> Result<timestamp, errno>

Return the resolution of a clock. Implementations are required to provide a non-zero value for supported clocks. For unsupported clocks, return errno::inval. Note: This is similar to clock_getres in POSIX.

Params
  • id: clockid The clock for which to return the resolution.
Results
  • error: Result<timestamp, errno> The resolution of the clock, or an error if one happened.
Variant Layout
  • size: 16
  • align: 8
  • tag_size: 4
Variant cases

clock_time_get(id: clockid, precision: timestamp) -> Result<timestamp, errno>

Return the time value of a clock. Note: This is similar to clock_gettime in POSIX.

Params

  • id: clockid The clock for which to return the time.

  • precision: timestamp The maximum lag (exclusive) that the returned time value may have, compared to its actual value.

Results
  • error: Result<timestamp, errno> The time value of the clock.
Variant Layout
  • size: 16
  • align: 8
  • tag_size: 4
Variant cases

fd_advise(fd: fd, offset: filesize, len: filesize, advice: advice) -> Result<(), errno>

Provide file advisory information on a file descriptor. Note: This is similar to posix_fadvise in POSIX.

Params

  • fd: fd

  • offset: filesize The offset within the file to which the advisory applies.

  • len: filesize The length of the region to which the advisory applies.

  • advice: advice The advice.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_allocate(fd: fd, offset: filesize, len: filesize) -> Result<(), errno>

Force the allocation of space in a file. Note: This is similar to posix_fallocate in POSIX.

Params

  • fd: fd

  • offset: filesize The offset at which to start the allocation.

  • len: filesize The length of the area that is allocated.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_close(fd: fd) -> Result<(), errno>

Close a file descriptor. Note: This is similar to close in POSIX.

Params
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_datasync(fd: fd) -> Result<(), errno>

Synchronize the data of a file to disk. Note: This is similar to fdatasync in POSIX.

Params
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_fdstat_get(fd: fd) -> Result<fdstat, errno>

Get the attributes of a file descriptor. Note: This returns similar flags to fsync(fd, F_GETFL) in POSIX, as well as additional fields.

Params
Results
  • error: Result<fdstat, errno> The buffer where the file descriptor's attributes are stored.
Variant Layout
  • size: 32
  • align: 8
  • tag_size: 4
Variant cases

fd_fdstat_set_flags(fd: fd, flags: fdflags) -> Result<(), errno>

Adjust the flags associated with a file descriptor. Note: This is similar to fcntl(fd, F_SETFL, flags) in POSIX.

Params

  • fd: fd

  • flags: fdflags The desired values of the file descriptor flags.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_fdstat_set_rights(fd: fd, fs_rights_base: rights, fs_rights_inheriting: rights) -> Result<(), errno>

Adjust the rights associated with a file descriptor. This can only be used to remove rights, and returns errno::notcapable if called in a way that would attempt to add rights

Params

  • fd: fd

  • fs_rights_base: rights The desired rights of the file descriptor.

  • fs_rights_inheriting: rights

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_filestat_get(fd: fd) -> Result<filestat, errno>

Return the attributes of an open file.

Params
Results
  • error: Result<filestat, errno> The buffer where the file's attributes are stored.
Variant Layout
  • size: 72
  • align: 8
  • tag_size: 4
Variant cases

fd_filestat_set_size(fd: fd, size: filesize) -> Result<(), errno>

Adjust the size of an open file. If this increases the file's size, the extra bytes are filled with zeros. Note: This is similar to ftruncate in POSIX.

Params
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_filestat_set_times(fd: fd, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> Result<(), errno>

Adjust the timestamps of an open file or directory. Note: This is similar to futimens in POSIX.

Params

  • fd: fd

  • atim: timestamp The desired values of the data access timestamp.

  • mtim: timestamp The desired values of the data modification timestamp.

  • fst_flags: fstflags A bitmask indicating which timestamps to adjust.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_pread(fd: fd, iovs: iovec_array, offset: filesize) -> Result<size, errno>

Read from a file descriptor, without using and updating the file descriptor's offset. Note: This is similar to preadv in POSIX.

Params

  • fd: fd

  • iovs: iovec_array List of scatter/gather vectors in which to store data.

  • offset: filesize The offset within the file at which to read.

Results
  • error: Result<size, errno> The number of bytes read.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_prestat_get(fd: fd) -> Result<prestat, errno>

Return a description of the given preopened file descriptor.

Params
Results
  • error: Result<prestat, errno> The buffer where the description is stored.
Variant Layout
  • size: 12
  • align: 4
  • tag_size: 4
Variant cases

fd_prestat_dir_name(fd: fd, path: Pointer<u8>, path_len: size) -> Result<(), errno>

Return a description of the given preopened file descriptor.

Params

  • fd: fd

  • path: Pointer<u8> A buffer into which to write the preopened directory name.

  • path_len: size

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_pwrite(fd: fd, iovs: ciovec_array, offset: filesize) -> Result<size, errno>

Write to a file descriptor, without using and updating the file descriptor's offset. Note: This is similar to pwritev in POSIX.

Params

  • fd: fd

  • iovs: ciovec_array List of scatter/gather vectors from which to retrieve data.

  • offset: filesize The offset within the file at which to write.

Results
  • error: Result<size, errno> The number of bytes written.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_read(fd: fd, iovs: iovec_array) -> Result<size, errno>

Read from a file descriptor. Note: This is similar to readv in POSIX.

Params

  • fd: fd

  • iovs: iovec_array List of scatter/gather vectors to which to store data.

Results
  • error: Result<size, errno> The number of bytes read.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_readdir(fd: fd, buf: Pointer<u8>, buf_len: size, cookie: dircookie) -> Result<size, errno>

Read directory entries from a directory. When successful, the contents of the output buffer consist of a sequence of directory entries. Each directory entry consists of a dirent object, followed by dirent::d_namlen bytes holding the name of the directory entry. This function fills the output buffer as much as possible, potentially truncating the last directory entry. This allows the caller to grow its read buffer size in case it's too small to fit a single large directory entry, or skip the oversized directory entry.

Params

  • fd: fd

  • buf: Pointer<u8> The buffer where directory entries are stored

  • buf_len: size

  • cookie: dircookie The location within the directory to start reading

Results
  • error: Result<size, errno> The number of bytes stored in the read buffer. If less than the size of the read buffer, the end of the directory has been reached.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_renumber(fd: fd, to: fd) -> Result<(), errno>

Atomically replace a file descriptor by renumbering another file descriptor. Due to the strong focus on thread safety, this environment does not provide a mechanism to duplicate or renumber a file descriptor to an arbitrary number, like dup2(). This would be prone to race conditions, as an actual file descriptor with the same number could be allocated by a different thread at the same time. This function provides a way to atomically renumber file descriptors, which would disappear if dup2() were to be removed entirely.

Params

  • fd: fd

  • to: fd The file descriptor to overwrite.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_seek(fd: fd, offset: filedelta, whence: whence) -> Result<filesize, errno>

Move the offset of a file descriptor. Note: This is similar to lseek in POSIX.

Params

  • fd: fd

  • offset: filedelta The number of bytes to move.

  • whence: whence The base from which the offset is relative.

Results
  • error: Result<filesize, errno> The new offset of the file descriptor, relative to the start of the file.
Variant Layout
  • size: 16
  • align: 8
  • tag_size: 4
Variant cases

fd_sync(fd: fd) -> Result<(), errno>

Synchronize the data and metadata of a file to disk. Note: This is similar to fsync in POSIX.

Params
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

fd_tell(fd: fd) -> Result<filesize, errno>

Return the current offset of a file descriptor. Note: This is similar to lseek(fd, 0, SEEK_CUR) in POSIX.

Params
Results
  • error: Result<filesize, errno> The current offset of the file descriptor, relative to the start of the file.
Variant Layout
  • size: 16
  • align: 8
  • tag_size: 4
Variant cases

fd_write(fd: fd, iovs: ciovec_array) -> Result<size, errno>

Write to a file descriptor. Note: This is similar to writev in POSIX.

Params

  • fd: fd

  • iovs: ciovec_array List of scatter/gather vectors from which to retrieve data.

Results
  • error: Result<size, errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_create_directory(fd: fd, path: string) -> Result<(), errno>

Create a directory. Note: This is similar to mkdirat in POSIX.

Params

  • fd: fd

  • path: string The path at which to create the directory.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_filestat_get(fd: fd, flags: lookupflags, path: string) -> Result<filestat, errno>

Return the attributes of a file or directory. Note: This is similar to stat in POSIX.

Params

  • fd: fd

  • flags: lookupflags Flags determining the method of how the path is resolved.

  • path: string The path of the file or directory to inspect.

Results
  • error: Result<filestat, errno> The buffer where the file's attributes are stored.
Variant Layout
  • size: 72
  • align: 8
  • tag_size: 4
Variant cases

path_filestat_set_times(fd: fd, flags: lookupflags, path: string, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> Result<(), errno>

Adjust the timestamps of a file or directory. Note: This is similar to utimensat in POSIX.

Params

  • fd: fd

  • flags: lookupflags Flags determining the method of how the path is resolved.

  • path: string The path of the file or directory to operate on.

  • atim: timestamp The desired values of the data access timestamp.

  • mtim: timestamp The desired values of the data modification timestamp.

  • fst_flags: fstflags A bitmask indicating which timestamps to adjust.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_link(old_fd: fd, old_flags: lookupflags, old_path: string, new_fd: fd, new_path: string) -> Result<(), errno>

Create a hard link. Note: This is similar to linkat in POSIX.

Params

  • old_fd: fd

  • old_flags: lookupflags Flags determining the method of how the path is resolved.

  • old_path: string The source path from which to link.

  • new_fd: fd The working directory at which the resolution of the new path starts.

  • new_path: string The destination path at which to create the hard link.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_open(fd: fd, dirflags: lookupflags, path: string, oflags: oflags, fs_rights_base: rights, fs_rights_inheriting: rights, fdflags: fdflags) -> Result<fd, errno>

Open a file or directory. The returned file descriptor is not guaranteed to be the lowest-numbered file descriptor not currently open; it is randomized to prevent applications from depending on making assumptions about indexes, since this is error-prone in multi-threaded contexts. The returned file descriptor is guaranteed to be less than 2**31. Note: This is similar to openat in POSIX.

Params

  • fd: fd

  • dirflags: lookupflags Flags determining the method of how the path is resolved.

  • path: string The relative path of the file or directory to open, relative to the path_open::fd directory.

  • oflags: oflags The method by which to open the file.

  • fs_rights_base: rights The initial rights of the newly created file descriptor. The implementation is allowed to return a file descriptor with fewer rights than specified, if and only if those rights do not apply to the type of file being opened. The base rights are rights that will apply to operations using the file descriptor itself, while the inheriting rights are rights that apply to file descriptors derived from it.

  • fs_rights_inheriting: rights

  • fdflags: fdflags

Results
  • error: Result<fd, errno> The file descriptor of the file that has been opened.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_readlink(fd: fd, path: string, buf: Pointer<u8>, buf_len: size) -> Result<size, errno>

Read the contents of a symbolic link. Note: This is similar to readlinkat in POSIX.

Params

  • fd: fd

  • path: string The path of the symbolic link from which to read.

  • buf: Pointer<u8> The buffer to which to write the contents of the symbolic link.

  • buf_len: size

Results
  • error: Result<size, errno> The number of bytes placed in the buffer.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_remove_directory(fd: fd, path: string) -> Result<(), errno>

Remove a directory. Return errno::notempty if the directory is not empty. Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

Params

  • fd: fd

  • path: string The path to a directory to remove.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_rename(fd: fd, old_path: string, new_fd: fd, new_path: string) -> Result<(), errno>

Rename a file or directory. Note: This is similar to renameat in POSIX.

Params

  • fd: fd

  • old_path: string The source path of the file or directory to rename.

  • new_fd: fd The working directory at which the resolution of the new path starts.

  • new_path: string The destination path to which to rename the file or directory.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_symlink(old_path: string, fd: fd, new_path: string) -> Result<(), errno>

Create a symbolic link. Note: This is similar to symlinkat in POSIX.

Params

  • old_path: string The contents of the symbolic link.

  • fd: fd

  • new_path: string The destination path at which to create the symbolic link.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

path_unlink_file(fd: fd, path: string) -> Result<(), errno>

Unlink a file. Return errno::isdir if the path refers to a directory. Note: This is similar to unlinkat(fd, path, 0) in POSIX.

Params

  • fd: fd

  • path: string The path to a file to unlink.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

poll_oneoff(in: ConstPointer<subscription>, out: Pointer<event>, nsubscriptions: size) -> Result<size, errno>

Concurrently poll for the occurrence of a set of events.

Params

  • in: ConstPointer<subscription> The events to which to subscribe.

  • out: Pointer<event> The events that have occurred.

  • nsubscriptions: size Both the number of subscriptions and events.

Results
  • error: Result<size, errno> The number of events stored.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

proc_exit(rval: exitcode)

Terminate the process normally. An exit code of 0 indicates successful termination of the program. The meanings of other values is dependent on the environment.

Params
  • rval: exitcode The exit code returned by the process.
Results

proc_raise(sig: signal) -> Result<(), errno>

Send a signal to the process of the calling thread. Note: This is similar to raise in POSIX.

Params
  • sig: signal The signal condition to trigger.
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

sched_yield() -> Result<(), errno>

Temporarily yield execution of the calling thread. Note: This is similar to sched_yield in POSIX.

Params
Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

random_get(buf: Pointer<u8>, buf_len: size) -> Result<(), errno>

Write high-quality random data into a buffer. This function blocks when the implementation is unable to immediately provide sufficient high-quality random data. This function may execute slowly, so when large mounts of random data are required, it's advisable to use this function to seed a pseudo-random number generator, rather than to provide the random data directly.

Params

  • buf: Pointer<u8> The buffer to fill with random data.

  • buf_len: size

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

sock_accept(fd: fd, flags: fdflags) -> Result<fd, errno>

Accept a new incoming connection. Note: This is similar to accept in POSIX.

Params

  • fd: fd The listening socket.

  • flags: fdflags The desired values of the file descriptor flags.

Results
  • error: Result<fd, errno> New socket connection
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

sock_recv(fd: fd, ri_data: iovec_array, ri_flags: riflags) -> Result<(size, roflags), errno>

Receive a message from a socket. Note: This is similar to recv in POSIX, though it also supports reading the data into multiple buffers in the manner of readv.

Params

  • fd: fd

  • ri_data: iovec_array List of scatter/gather vectors to which to store data.

  • ri_flags: riflags Message flags.

Results
  • error: Result<(size, roflags), errno> Number of bytes stored in ri_data and message flags.
Variant Layout
  • size: 12
  • align: 4
  • tag_size: 4
Variant cases
  • ok: (size, roflags)

####### Record members

Offset: 0

Offset: 4

sock_send(fd: fd, si_data: ciovec_array, si_flags: siflags) -> Result<size, errno>

Send a message on a socket. Note: This is similar to send in POSIX, though it also supports writing the data from multiple buffers in the manner of writev.

Params

  • fd: fd

  • si_data: ciovec_array List of scatter/gather vectors to which to retrieve data

  • si_flags: siflags Message flags.

Results
  • error: Result<size, errno> Number of bytes transmitted.
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases

sock_shutdown(fd: fd, how: sdflags) -> Result<(), errno>

Shut down socket send and receive channels. Note: This is similar to shutdown in POSIX.

Params

  • fd: fd

  • how: sdflags Which channels on the socket to shut down.

Results
  • error: Result<(), errno>
Variant Layout
  • size: 8
  • align: 4
  • tag_size: 4
Variant cases