Skip to content

docs.md

Latest commit

 

History

History
2036 lines (1333 loc) · 69 KB

docs.md

File metadata and controls

2036 lines (1333 loc) · 69 KB

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: Enum(u32)

Identifiers for clocks.

Size: 4

Alignment: 4

Variants

  • 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: Enum(u16)

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

Variants

  • 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: Flags(u64)

File descriptor rights, determining which actions may be performed.

Size: 8

Alignment: 8

Flags

fd

A file descriptor handle.

Size: 4

Alignment: 4

Supertypes

iovec: Struct

A region of memory for scatter/gather reads.

Size: 8

Alignment: 4

Struct 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: Struct

A region of memory for scatter/gather writes.

Size: 8

Alignment: 4

Struct 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: Array<iovec>

Size: 8

Alignment: 4

ciovec_array: Array<ciovec>

Size: 8

Alignment: 4

filedelta: s64

Relative offset within a file.

Size: 8

Alignment: 8

whence: Enum(u8)

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

Size: 1

Alignment: 1

Variants

  • 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: Enum(u8)

The type of a file descriptor or file.

Size: 1

Alignment: 1

Variants

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

A directory entry.

Size: 24

Alignment: 8

Struct 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: Enum(u8)

File or memory access pattern advisory information.

Size: 1

Alignment: 1

Variants

  • 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: Flags(u16)

File descriptor flags.

Size: 2

Alignment: 2

Flags

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

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

  • nonblock Non-blocking mode.

  • rsync Synchronized read I/O operations.

  • sync 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: Struct

File descriptor attributes.

Size: 24

Alignment: 8

Struct 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: Flags(u16)

Which file time attributes to adjust.

Size: 2

Alignment: 2

Flags

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

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

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

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

lookupflags: Flags(u32)

Flags determining the method of how paths are resolved.

Size: 4

Alignment: 4

Flags

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

oflags: Flags(u16)

Open flags used by path_open.

Size: 2

Alignment: 2

Flags

  • creat Create file if it does not exist.

  • directory Fail if not a directory.

  • excl Fail if file already exists.

  • trunc Truncate file to size 0.

linkcount: u64

Number of hard links to an inode.

Size: 8

Alignment: 8

filestat: Struct

File attributes.

Size: 64

Alignment: 8

Struct 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: Enum(u8)

Type of a subscription to an event or its occurrence.

Size: 1

Alignment: 1

Variants

eventrwflags: Flags(u16)

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

Size: 2

Alignment: 2

Flags

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

event_fd_readwrite: Struct

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

Size: 16

Alignment: 8

Struct members

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

Offset: 0

Offset: 8

event: Struct

An event that occurred.

Size: 32

Alignment: 8

Struct 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: Flags(u16)

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

Size: 2

Alignment: 2

Flags

subscription_clock: Struct

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

Size: 32

Alignment: 8

Struct 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: Struct

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

Size: 4

Alignment: 4

Struct members

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

Offset: 0

subscription_u: Union

The contents of a subscription.

Size: 40

Alignment: 8

Union Layout

  • tag_size: 1
  • tag_align: 1
  • contents_offset: 8
  • contents_size: 32
  • contents_align: 8

Union variants

subscription: Struct

Subscription to an event.

Size: 48

Alignment: 8

Struct 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: Enum(u8)

Signal condition.

Size: 1

Alignment: 1

Variants

  • 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: Flags(u16)

Flags provided to sock_recv.

Size: 2

Alignment: 2

Flags

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

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

roflags: Flags(u16)

Flags returned by sock_recv.

Size: 2

Alignment: 2

Flags

  • recv_data_truncated 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: Flags(u8)

Which channels on a socket to shut down.

Size: 1

Alignment: 1

Flags

  • rd Disables further receive operations.

  • wr Disables further send operations.

preopentype: Enum(u8)

Identifiers for preopened capabilities.

Size: 1

Alignment: 1

Variants

  • dir A pre-opened directory.

prestat_dir: Struct

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

Size: 4

Alignment: 4

Struct members

Offset: 0

prestat: Union

Information about a pre-opened capability.

Size: 8

Alignment: 4

Union Layout

  • tag_size: 1
  • tag_align: 1
  • contents_offset: 4
  • contents_size: 4
  • contents_align: 4

Union variants

Modules

wasi_snapshot_preview1

Imports

Memory

Functions

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

Read command-line argument data. The size of the array should match that returned by args_sizes_get

Params

  • argv: Pointer<Pointer<u8>>

  • argv_buf: Pointer<u8>

Results

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

Return command-line argument data sizes.

Params
Results

  • error: errno

  • argc: size The number of arguments.

  • argv_buf_size: size The size of the argument string data.

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

Read environment variable data. The sizes of the buffers should match that returned by environ_sizes_get.

Params

  • environ: Pointer<Pointer<u8>>

  • environ_buf: Pointer<u8>

Results

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

Return environment variable data sizes.

Params
Results

  • error: errno

  • environc: size The number of environment variable arguments.

  • environ_buf_size: size The size of the environment variable data.

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

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

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

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

fd_advise(fd: fd, offset: filesize, len: filesize, advice: advice) -> 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

fd_allocate(fd: fd, offset: filesize, len: filesize) -> 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

fd_close(fd: fd) -> errno

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

Params
Results

fd_datasync(fd: fd) -> errno

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

Params
Results

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

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: errno

  • stat: fdstat The buffer where the file descriptor's attributes are stored.

fd_fdstat_set_flags(fd: fd, flags: fdflags) -> 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

fd_fdstat_set_rights(fd: fd, fs_rights_base: rights, fs_rights_inheriting: rights) -> 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

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

Return the attributes of an open file.

Params
Results

  • error: errno

  • buf: filestat The buffer where the file's attributes are stored.

fd_filestat_set_size(fd: fd, size: filesize) -> 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

fd_filestat_set_times(fd: fd, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> 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

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

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: errno

  • nread: size The number of bytes read.

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

Return a description of the given preopened file descriptor.

Params
Results

  • error: errno

  • buf: prestat The buffer where the description is stored.

fd_prestat_dir_name(fd: fd, path: Pointer<u8>, path_len: size) -> 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

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

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: errno

  • nwritten: size The number of bytes written.

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

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: errno

  • nread: size The number of bytes read.

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

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: errno

  • bufused: size 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.

fd_renumber(fd: fd, to: fd) -> 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

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

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: errno

  • newoffset: filesize The new offset of the file descriptor, relative to the start of the file.

fd_sync(fd: fd) -> errno

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

Params
Results

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

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

Params
Results

  • error: errno

  • offset: filesize The current offset of the file descriptor, relative to the start of the file.

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

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: errno

  • nwritten: size The number of bytes written.

path_create_directory(fd: fd, path: string) -> 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

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

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: errno

  • buf: filestat The buffer where the file's attributes are stored.

path_filestat_set_times(fd: fd, flags: lookupflags, path: string, atim: timestamp, mtim: timestamp, fst_flags: fstflags) -> 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

path_link(old_fd: fd, old_flags: lookupflags, old_path: string, new_fd: fd, new_path: string) -> 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

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

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: errno

  • opened_fd: fd The file descriptor of the file that has been opened.

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

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: errno

  • bufused: size The number of bytes placed in the buffer.

path_remove_directory(fd: fd, path: string) -> 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

path_rename(fd: fd, old_path: string, new_fd: fd, new_path: string) -> 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

path_symlink(old_path: string, fd: fd, new_path: string) -> 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

path_unlink_file(fd: fd, path: string) -> 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

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

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: errno

  • nevents: size The number of events stored.

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) -> 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

sched_yield() -> errno

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

Params
Results

random_get(buf: Pointer<u8>, buf_len: size) -> 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

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

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: errno

  • ro_datalen: size Number of bytes stored in ri_data.

  • ro_flags: roflags Message flags.

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

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: errno

  • so_datalen: size Number of bytes transmitted.

sock_shutdown(fd: fd, how: sdflags) -> 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
⚡