神刀安全网

The CloudABI Specification

Nuxi CloudABI

CloudABI is what you get if you take POSIX, add capability-based security, and remove everything that’s incompatible with that. The result is a minimal ABI consisting of only 58 syscalls.

CloudABI doesn’t have its own kernel, but instead is implemented in existing kernels: FreeBSD has CloudABI support for x86-64 and arm64, and a patch-set for NetBSD and a patch-set for Linux are available as well. This means that CloudABI binaries can be executed on different operating systems, without any modification.

Capability-Based Security

Capability-based security means that processes can only perform actions that have no global impact. Processes cannot open files by their absolute path, cannot open network connections, and cannot observe global system state such as the process table.

The capabilities of a process are fully determined by its set of open file descriptors (fds). For example, files can only be opened if the process already has a file descriptor to a directory the file is in.

Unlike in POSIX, where processes are normally started with file descriptors 0, 1, and 2 reserved for standard input, output, and error, CloudABI does not reserve any file descriptor numbers for specific purposes.

In CloudABI, a process depends on its parent process to launch it with the right set of resources, since the process will not be able to open any new resources. For example, a simple static web server would need to be started with an fd to a listening socket, and an fd to the directory to serve files out of. The web server will then be unable to do anything other than reading files in that directory, and accept connections on the given socket.

So, unknown CloudABI binaries can safely be executed without the need for containers, virtual machines, or other sandboxing techonologies.

Watch Ed Schouten’s Talk at 32C3 for more information about what capability-based security for UNIX means.

Cloudlibc

Cloudlibc is an implementation of the C standard library, without all CloudABI-incompatible functions. For example, Cloudlibc does not have printf , but does have fprintf .

CloudABI-Ports

CloudABI-Ports is a collection of ports of commonly used libraries and applications to CloudABI. It contains software such as zlib , libpng , boost , memcached , and much more. The software is patched to not depend on any global state, such as files in /etc or /dev , using open() , etc.

Using CloudABI

Instructions for using CloudABI (including kernel modules/patches, toolchain, and ports) are available for several operating systems:

Specification of the ABI

The entire ABI is specified in a a file called cloudabi.txt , from which all headers and documentation (including the one you’re reading now) is generated.

Syscalls

cloudabi_sys_clock_res_get()

Obtains the resolution of a clock.

Inputs:

  • <a href="#clockid">cloudabi_clockid_t</a> <strong>clock_id</strong>

    The clock for which the resolution needs to be returned.

Outputs:

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>resolution</strong>

    The resolution of the clock.

cloudabi_sys_clock_time_get()

Obtains the time value of a clock.

Inputs:

  • <a href="#clockid">cloudabi_clockid_t</a> <strong>clock_id</strong>

    The clock for which the time needs to be returned.

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>precision</strong>

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

Outputs:

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>time</strong>

    The time value of the clock.

cloudabi_sys_condvar_signal()

Wakes up threads waiting on a userspace condition variable.

If an invocation of this system call causes all waiting threads to be woken up, the value of the condition variable is set to CLOUDABI_CONDVAR_HAS_NO_WAITERS . As long as the condition variable is set to this value, it is not needed to invoke this system call.

Inputs:

  • _Atomic(<a href="#condvar">cloudabi_condvar_t</a>) *<strong>condvar</strong>

    The userspace condition variable that has waiting threads.

  • <a href="#mflags">cloudabi_mflags_t</a> <strong>scope</strong>

    Possible values:

    • The condition variable is stored in private memory.

    • The condition variable is stored in shared memory.

  • <a href="#nthreads">cloudabi_nthreads_t</a> <strong>nwaiters</strong>

    The number of threads that need to be woken up. If it exceeds the number of waiting threads, all threads are woken up.

cloudabi_sys_fd_close()

Closes a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor that needs to be closed.

cloudabi_sys_fd_create1()

Creates a file descriptor.

Inputs:

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor that has been created.

cloudabi_sys_fd_create2()

Creates a pair of file descriptors.

Inputs:

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd1</strong>

    The first file descriptor of the pair. For pipes, this corresponds to the read end.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd2</strong>

    The second file descriptor of the pair. For pipes, this corresponds to the write end.

cloudabi_sys_fd_datasync()

Synchronizes the data of a file to disk.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor of the file whose data needs to be synchronized to disk.

cloudabi_sys_fd_dup()

Duplicates a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>from</strong>

    The file descriptor that needs to be duplicated.

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The new file descriptor.

cloudabi_sys_fd_pread()

Reads from a file descriptor, without using and updating the file descriptor’s offset.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor from which data should be read.

  • const cloudabi_iovec_t *iov and size_t iovcnt

    List of scatter/gather vectors where data should be stored.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>offset</strong>

    The offset within the file at which reading should start.

Outputs:

  • size_t <strong>nread</strong>

    The number of bytes read.

cloudabi_sys_fd_pwrite()

Writes to a file descriptor, without using and updating the file descriptor’s offset.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor to which data should be written.

  • const cloudabi_ciovec_t *iov and size_t iovcnt

    List of scatter/gather vectors where data should be retrieved.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>offset</strong>

    The offset within the file at which writing should start.

Outputs:

  • size_t <strong>nwritten</strong>

    The number of bytes written.

cloudabi_sys_fd_read()

Reads from a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor from which data should be read.

  • const cloudabi_iovec_t *iov and size_t iovcnt

    List of scatter/gather vectors where data should be stored.

Outputs:

  • size_t <strong>nread</strong>

    The number of bytes read.

cloudabi_sys_fd_replace()

Atomically replaces a file descriptor by a copy of another file descriptor.

Due to the strong focus on thread safety, this environment does not provide a mechanism to duplicate 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 system call provides a way to atomically replace file descriptors, which would disappear if dup2() were to be removed entirely.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>from</strong>

    The file descriptor that needs to be copied.

  • <a href="#fd">cloudabi_fd_t</a> <strong>to</strong>

    The file descriptor that needs to be overwritten.

cloudabi_sys_fd_seek()

Moves the offset of the file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor whose offset has to be moved.

  • <a href="#filedelta">cloudabi_filedelta_t</a> <strong>offset</strong>

    The number of bytes to move.

  • <a href="#whence">cloudabi_whence_t</a> <strong>whence</strong>

    Relative to which position the move should take place.

Outputs:

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>newoffset</strong>

    The new offset of the file descriptor, relative to the start of the file.

cloudabi_sys_fd_stat_get()

Gets attributes of a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor whose attributes have to be obtained.

  • <a href="#fdstat">cloudabi_fdstat_t</a> *<strong>buf</strong>

    The buffer where the file descriptor’s attributes are stored.

cloudabi_sys_fd_stat_put()

Adjusts attributes of a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor whose attributes have to be adjusted.

  • const <a href="#fdstat">cloudabi_fdstat_t</a> *<strong>buf</strong>

    The desired values of the file descriptor attributes that are adjusted.

  • <a href="#fdsflags">cloudabi_fdsflags_t</a> <strong>flags</strong>

    A bitmask indicating which attributes have to be adjusted.

cloudabi_sys_fd_sync()

Synchronizes the data and metadata of a file to disk.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor of the file whose data and metadata needs to be synchronized to disk.

cloudabi_sys_fd_write()

Writes to a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor to which data should be written.

  • const cloudabi_ciovec_t *iov and size_t iovcnt

    List of scatter/gather vectors where data should be retrieved.

Outputs:

  • size_t <strong>nwritten</strong>

    The number of bytes written.

cloudabi_sys_file_advise()

Provides file advisory information on a file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor for which to provide file advisory information.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>offset</strong>

    The offset within the file to which the advisory applies.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>len</strong>

    The length of the region to which the advisory applies.

  • <a href="#advice">cloudabi_advice_t</a> <strong>advice</strong>

    The advice.

cloudabi_sys_file_allocate()

Forces the allocation of space in a file.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file in which the space should be allocated.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>offset</strong>

    The offset at which the allocation should start.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>len</strong>

    The length of the area that is allocated.

cloudabi_sys_file_create()

Creates a file of a specified type.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the file to be created starts.

  • const char *path and size_t pathlen

    The path at which the file should be created.

  • <a href="#filetype">cloudabi_filetype_t</a> <strong>type</strong>

    Possible values:

cloudabi_sys_file_link()

Creates a hard link.

Inputs:

  • <a href="#lookup">cloudabi_lookup_t</a> <strong>fd1</strong>

    The working directory at which the resolution of the source path starts.

  • const char *path1 and size_t path1len

    The source path of the file that should be hard linked.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd2</strong>

    The working directory at which the resolution of the destination path starts.

  • const char *path2 and size_t path2len

    The destination path at which the hard link should be created.

cloudabi_sys_file_open()

Opens a file.

Inputs:

  • <a href="#lookup">cloudabi_lookup_t</a> <strong>dirfd</strong>

    The working directory at which the resolution of the file to be opened starts.

  • const char *path and size_t pathlen

    The path of the file that should be opened.

  • <a href="#oflags">cloudabi_oflags_t</a> <strong>oflags</strong>

    The method at which the file should be opened.

  • const <a href="#fdstat">cloudabi_fdstat_t</a> *<strong>fds</strong>

    The initial attributes of the file descriptor that is returned by this system call.

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor of the file that has been opened.

cloudabi_sys_file_readdir()

Reads 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 aobject, followed by cloudabi_dirent_t::d_namlen bytes holding the name of the directory entry.

This system call 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.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The directory from which to read the directory entries.

  • void *buf and size_t nbyte

    The buffer where directory entries are stored.

  • <a href="#dircookie">cloudabi_dircookie_t</a> <strong>cookie</strong>

    The location within the directory to start reading.

Outputs:

  • size_t <strong>bufused</strong>

    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.

cloudabi_sys_file_readlink()

Reads the contents of a symbolic link.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path of the symbolic starts.

  • const char *path and size_t pathlen

    The path of the symbolic link whose contents should be read.

  • char *buf and size_t bufsize

    The buffer where the contents of the symbolic link should be stored.

Outputs:

  • size_t <strong>bufused</strong>

    The number of bytes placed in the buffer.

cloudabi_sys_file_rename()

Renames a file.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>oldfd</strong>

    The working directory at which the resolution of the source path starts.

  • const char *old and size_t oldlen

    The source path of the file that should be renamed.

  • <a href="#fd">cloudabi_fd_t</a> <strong>newfd</strong>

    The working directory at which the resolution of the destination path starts.

  • const char *new and size_t newlen

    The destination path to which the file should be renamed.

cloudabi_sys_file_stat_fget()

Gets attributes of a file by file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor whose attributes have to be obtained.

  • <a href="#filestat">cloudabi_filestat_t</a> *<strong>buf</strong>

    The buffer where the file’s attributes are stored.

cloudabi_sys_file_stat_fput()

Adjusts attributes of a file by file descriptor.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The file descriptor whose attributes have to be adjusted.

  • const <a href="#filestat">cloudabi_filestat_t</a> *<strong>buf</strong>

    The desired values of the file attributes that are adjusted.

  • <a href="#fsflags">cloudabi_fsflags_t</a> <strong>flags</strong>

    A bitmask indicating which attributes have to be adjusted.

cloudabi_sys_file_stat_get()

Gets attributes of a file by path.

Inputs:

  • <a href="#lookup">cloudabi_lookup_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path whose attributes have to be obtained starts.

  • const char *path and size_t pathlen

    The path of the file whose attributes have to be obtained.

  • <a href="#filestat">cloudabi_filestat_t</a> *<strong>buf</strong>

    The buffer where the file’s attributes are stored.

cloudabi_sys_file_stat_put()

Adjusts attributes of a file by path.

Inputs:

  • <a href="#lookup">cloudabi_lookup_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path whose attributes have to be adjusted starts.

  • const char *path and size_t pathlen

    The path of the file whose attributes have to be adjusted.

  • const <a href="#filestat">cloudabi_filestat_t</a> *<strong>buf</strong>

    The desired values of the file attributes that are adjusted.

  • <a href="#fsflags">cloudabi_fsflags_t</a> <strong>flags</strong>

    A bitmask indicating which attributes have to be adjusted.

cloudabi_sys_file_symlink()

Creates a symbolic link.

Inputs:

  • const char *path1 and size_t path1len

    The contents of the symbolic link.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the destination path starts.

  • const char *path2 and size_t path2len

    The destination path at which the symbolic link should be created.

cloudabi_sys_file_unlink()

Unlinks a file, or removes a directory.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path starts.

  • const char *path and size_t pathlen

    The path that needs to be unlinked or removed.

  • <a href="#ulflags">cloudabi_ulflags_t</a> <strong>flags</strong>

    Possible values:

cloudabi_sys_lock_unlock()

Unlocks a write-locked userspace lock.

If a userspace lock is unlocked while having its CLOUDABI_LOCK_KERNEL_MANAGED flag set, the lock cannot be unlocked in userspace directly. This system call needs to be performed instead, so that any waiting threads can be woken up.

To prevent spurious invocations of this system call, the lock must be locked for writing. This prevents other threads from acquiring additional read locks while the system call is in progress. If the lock is acquired for reading, it must first be upgraded to a write lock.

Inputs:

  • _Atomic(<a href="#lock">cloudabi_lock_t</a>) *<strong>lock</strong>

    The userspace lock that is locked for writing by the calling thread.

  • <a href="#mflags">cloudabi_mflags_t</a> <strong>scope</strong>

    Possible values:

    • The lock is stored in private memory.

    • The lock is stored in shared memory.

cloudabi_sys_mem_advise()

Provides memory advisory information on a region of memory.

Inputs:

  • void *addr and size_t len

    The pages for which to provide memory advisory information.

  • <a href="#advice">cloudabi_advice_t</a> <strong>advice</strong>

    The advice.

cloudabi_sys_mem_lock()

Increments the lock count on a region of memory, which prevents it from leaving system memory.

Inputs:

  • const void *addr and size_t len

    The pages that need its lock count incremented.

cloudabi_sys_mem_map()

Creates a memory mapping, making the contents of a file accessible through memory.

Inputs:

  • void *<strong>addr</strong>

    Ifis set, specifies to which address the file region is mapped. Otherwise, the mapping is performed at an unused location.

  • size_t <strong>len</strong>

    The length of the memory mapping to be created.

  • <a href="#mprot">cloudabi_mprot_t</a> <strong>prot</strong>

    Initial memory protection options for the memory mapping.

  • <a href="#mflags">cloudabi_mflags_t</a> <strong>flags</strong>

    Memory mapping flags.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    Ifis set, this argument must be. Otherwise, this argument specifies the file whose contents need to be mapped.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>off</strong>

    Ifis set, this argument must be zero. Otherwise, this argument specifies the offset within the file at which the mapping starts.

Outputs:

  • void *<strong>mem</strong>

    The starting address of the memory mapping.

cloudabi_sys_mem_protect()

Change the protection of a memory mapping.

Inputs:

  • void *addr and size_t len

    The pages that need their protection changed.

  • <a href="#mprot">cloudabi_mprot_t</a> <strong>prot</strong>

    New protection options.

cloudabi_sys_mem_sync()

Synchronize a region of memory with its physical storage.

Inputs:

  • void *addr and size_t len

    The pages that need to be synchronized.

  • <a href="#msflags">cloudabi_msflags_t</a> <strong>flags</strong>

    The method of synchronization.

cloudabi_sys_mem_unlock()

Decrements the lock count on a region of memory, which prevents it from leaving system memory.

Inputs:

  • const void *addr and size_t len

    The pages that need its lock count decremented.

cloudabi_sys_mem_unmap()

Unmaps a region of memory.

Inputs:

  • void *addr and size_t len

    The pages that needs to be unmapped.

cloudabi_sys_poll()

Concurrently polls for the occurrence of a set of events.

Inputs:

  • const <a href="#subscription">cloudabi_subscription_t</a> *<strong>in</strong>

    The events to which to subscribe.

  • <a href="#event">cloudabi_event_t</a> *<strong>out</strong>

    The events that have occurred.

  • size_t <strong>nsubscriptions</strong>

    Both the number of subscriptions and events.

Outputs:

  • size_t <strong>nevents</strong>

    The number of events stored.

cloudabi_sys_poll_fd()

Concurrently polls for the occurrence of a set of events, while retaining subscriptions across calls.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The polling event queue.

  • const cloudabi_subscription_t *in and size_t nin

    Changes that need to be made to the polling event queue.

  • cloudabi_event_t *out and size_t nout

    The events that have occurred.

  • const <a href="#subscription">cloudabi_subscription_t</a> *<strong>timeout</strong>

    Subscription of type CLOUDABI_EVENTTYPE_CLOCK to serve as a timeout for the system call. The subscription is local to this invocation of this system call and is automatically purged upon completion.

Outputs:

  • size_t <strong>nevents</strong>

    The number of events stored.

cloudabi_sys_proc_exec()

Replaces the process by a new executable.

Process execution in CloudABI differs from POSIX in two ways: handling of arguments and inheritance of file descriptors.

CloudABI does not use string command line arguments. A buffer with binary data is copied into the new executable instead. The kernel does not enforce any specific structure to this data, although CloudABI’s C library uses it to store a tree structure that is semantically identical to YAML.

Due to the strong focus on thread safety, file descriptors aren’t inherited through close-on-exec flags. An explicit list of file descriptors that need to be retained needs to be provided. After execution, file descriptors are placed in the order in which they are stored in the array. This not only makes the execution process deterministic. It also prevents potential information disclosures about the layout of the original process.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    A file descriptor of the new executable.

  • const void *data and size_t datalen

    Binary argument data that is passed on to the new executable.

  • const cloudabi_fd_t *fds and size_t fdslen

    The layout of the file descriptor table after execution.

cloudabi_sys_proc_exit()

Terminates the process normally.

Inputs:

Does not return.

cloudabi_sys_proc_fork()

Forks the process of the calling thread.

After forking, a new process shall be created, having only a copy of the calling thread. The parent process will obtain a process descriptor. When closed, the child process is automatically signalled with.

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    In the parent process: the file descriptor number of the process descriptor.

    In the child process: CLOUDABI_PROCESS_CHILD .

  • <a href="#tid">cloudabi_tid_t</a> <strong>tid</strong>

    In the parent process: undefined.

    In the child process: the thread ID of the initial thread of the child process.

cloudabi_sys_proc_raise()

Sends a signal to the process of the calling thread.

Inputs:

  • <a href="#signal">cloudabi_signal_t</a> <strong>sig</strong>

    The signal condition that should be triggered. If the signal causes the process to terminate, its condition can be obtained by other processes through cloudabi_event_t::proc_terminate.signal .

cloudabi_sys_random_get()

Obtains random data from the kernel random number generator.

As this interface is not guaranteed to be fast, it is advised that the random data obtained through this system call is used as the seed for a userspace pseudo-random number generator.

Inputs:

  • void *buf and size_t nbyte

    The buffer that needs to be filled with random data.

cloudabi_sys_sock_accept()

Accepts an incoming connection on a listening socket.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The file descriptor of the listening socket.

  • <a href="#sockstat">cloudabi_sockstat_t</a> *<strong>buf</strong>

    The attributes of the socket associated with the incoming connection.

Outputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>conn</strong>

    The socket associated with the incoming connection.

cloudabi_sys_sock_bind()

Binds a UNIX socket to a path.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The file descriptor of the socket to be bound.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path to which to bind starts.

  • const char *path and size_t pathlen

    The path to which the socket should bind.

cloudabi_sys_sock_connect()

Connects a UNIX socket to another UNIX socket bound at a path.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The file descriptor of the socket to connect.

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path to which to connect starts.

  • const char *path and size_t pathlen

    The path to which the socket should onnect.

cloudabi_sys_sock_listen()

Listens for incoming connections on a socket.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The socket on which listening should be enabled.

  • <a href="#backlog">cloudabi_backlog_t</a> <strong>backlog</strong>

    Number of incoming connections the socket is capable of keeping in its backlog.

cloudabi_sys_sock_recv()

Receives a message on a socket.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The socket on which a message should be received.

  • const <a href="#recv_in">cloudabi_recv_in_t</a> *<strong>in</strong>

    Input parameters.

  • <a href="#recv_out">cloudabi_recv_out_t</a> *<strong>out</strong>

    Output parameters.

cloudabi_sys_sock_send()

Sends a message on a socket.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The socket on which a message should be sent.

  • const <a href="#send_in">cloudabi_send_in_t</a> *<strong>in</strong>

    Input parameters.

  • <a href="#send_out">cloudabi_send_out_t</a> *<strong>out</strong>

    Output parameters.

cloudabi_sys_sock_shutdown()

Shuts down socket send and receive channels.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The socket that needs its channels shut down.

  • <a href="#sdflags">cloudabi_sdflags_t</a> <strong>how</strong>

    Which channels on the socket need to be shut down.

cloudabi_sys_sock_stat_get()

Gets attributes of a socket.

Inputs:

  • <a href="#fd">cloudabi_fd_t</a> <strong>sock</strong>

    The socket whose attributes have to be obtained.

  • <a href="#sockstat">cloudabi_sockstat_t</a> *<strong>buf</strong>

    The buffer where the socket’s attributes are stored.

  • <a href="#ssflags">cloudabi_ssflags_t</a> <strong>flags</strong>

    Flags indicating how the existing socket attributes need to be changed.

cloudabi_sys_thread_create()

Creates a new thread within the current process.

Inputs:

  • <a href="#threadattr">cloudabi_threadattr_t</a> *<strong>attr</strong>

    The desired attributes of the new thread.

Outputs:

  • <a href="#tid">cloudabi_tid_t</a> <strong>tid</strong>

    The thread ID of the new thread.

cloudabi_sys_thread_exit()

Terminates the calling thread.

This system call can also unlock a single userspace lock after termination, which can be used to implement thread joining.

Inputs:

  • _Atomic(<a href="#lock">cloudabi_lock_t</a>) *<strong>lock</strong>

    Userspace lock that is locked for writing by the calling thread.

  • <a href="#mflags">cloudabi_mflags_t</a> <strong>scope</strong>

    Possible values:

    • The lock is stored in private memory.

    • The lock is stored in shared memory.

Does not return.

cloudabi_sys_thread_tcb_set()

Adjusts the machine-dependent TLS base address register.

On certain architectures, the TLS base address register can only be modified through privileged instructions (e.g., %fs on x86). This system call can be used on those architectures to adjust the contents of this register.

The results are undefined if this system call is invoked on architectures that do have writable TLS base address registers (e.g., aarch64).

Inputs:

  • void *<strong>tcb</strong>

    The new register contents.

cloudabi_sys_thread_yield()

Temporarily yields execution of the calling thread.

Types

cloudabi_advice_t ( uint8_t )

File or memory access pattern advisory information.

Used by cloudabi_sys_file_advise() and cloudabi_sys_mem_advise() .

Possible values:

  • CLOUDABI_ADVICE_DONTNEED

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

  • CLOUDABI_ADVICE_NOREUSE

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

  • CLOUDABI_ADVICE_NORMAL

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

  • CLOUDABI_ADVICE_RANDOM

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

  • CLOUDABI_ADVICE_SEQUENTIAL

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

  • CLOUDABI_ADVICE_WILLNEED

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

cloudabi_auxtype_t ( uint32_t )

Enumeration describing the kind of value stored in.

Possible values:

  • CLOUDABI_AT_ARGDATA

    Base address of the binary argument data provided to cloudabi_sys_proc_exec() .

  • CLOUDABI_AT_ARGDATALEN

    Length of the binary argument data provided to cloudabi_sys_proc_exec() .

  • CLOUDABI_AT_CANARY

    Base address of a buffer of random data that may be used for non-cryptographic purposes, for example as a canary for stack smashing protection.

  • CLOUDABI_AT_CANARYLEN

    Length of a buffer of random data that may be used for non-cryptographic purposes, for example as a canary for stack smashing protection.

  • CLOUDABI_AT_NCPUS

    Number of CPUs that the system this process is running on has.

  • CLOUDABI_AT_NULL

    Terminator of the auxiliary vector.

  • CLOUDABI_AT_PAGESZ

    Smallest memory object size for which individual memory protection controls can be configured.

  • CLOUDABI_AT_PHDR

    Address of the first ELF program header of the executable.

  • CLOUDABI_AT_PHNUM

    Number of ELF program headers of the executable.

  • CLOUDABI_AT_TID

    Thread ID of the initial thread of the process.

cloudabi_auxv_t ( struct )

Auxiliary vector entry.

The auxiliary vector is a list of key-value pairs that is provided to the process on startup. Unlike structures, it is extensible, as it is possible to add new records later on. The auxiliary vector is always terminated by an entry having type.

The auxiliary vector is part of the x86-64 ABI, but is used by this environment on all architectures.

Used by cloudabi_processentry_t .

Members:

  • <a href="#auxtype">cloudabi_auxtype_t</a> <strong>a_type</strong>

    The type of the auxiliary vector entry.

  • When a_type is CLOUDABI_AT_ARGDATALEN , CLOUDABI_AT_CANARYLEN ,,,, or:

    • size_t <strong>a_val</strong>

      A numerical value.

  • When a_type is,, or:

    • void *<strong>a_ptr</strong>

      A pointer value.

cloudabi_backlog_t ( uint32_t )

Number of incoming connections a socket is capable of keeping in its backlog.

Used by cloudabi_sys_sock_listen() .

cloudabi_ciovec_t ( struct )

A region of memory for scatter/gather writes.

Used by, cloudabi_sys_fd_pwrite() , and cloudabi_sys_fd_write() .

Members:

  • const void *iov_base and size_t iov_len

    The address and length of the buffer to be written.

cloudabi_clockid_t ( uint32_t )

Identifiers for clocks.

Used by cloudabi_subscription_t , cloudabi_sys_clock_res_get() , and cloudabi_sys_clock_time_get() .

Possible values:

  • CLOUDABI_CLOCK_MONOTONIC

    The system-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.

  • CLOUDABI_CLOCK_PROCESS_CPUTIME_ID

    The CPU-time clock associated with the current process.

  • CLOUDABI_CLOCK_REALTIME

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

  • CLOUDABI_CLOCK_THREAD_CPUTIME_ID

    The CPU-time clock associated with the current thread.

cloudabi_condvar_t ( uint32_t )

A userspace condition variable.

Used by, cloudabi_subscription_t , and cloudabi_sys_condvar_signal() .

Special values:

  • CLOUDABI_CONDVAR_HAS_NO_WAITERS

    The condition variable is in its initial state. There are no threads waiting to be woken up. If the condition variable has any other value, the kernel must be called to wake up any sleeping threads.

cloudabi_device_t ( uint64_t )

Identifier for a device containing a file system. Can be used in combination withto uniquely identify a file on the local system.

cloudabi_dircookie_t ( uint64_t )

A reference to the offset of a directory entry.

Used byand cloudabi_sys_file_readdir() .

Special values:

  • CLOUDABI_DIRCOOKIE_START

    Permanent reference to the first directory entry within a directory.

cloudabi_dirent_t ( struct )

A directory entry.

Members:

  • <a href="#dircookie">cloudabi_dircookie_t</a> <strong>d_next</strong>

    The offset of the next directory entry stored in this directory.

  • <a href="#inode">cloudabi_inode_t</a> <strong>d_ino</strong>

    The serial number of the file referred to by this directory entry.

  • uint32_t <strong>d_namlen</strong>

    The length of the name of the directory entry.

  • <a href="#filetype">cloudabi_filetype_t</a> <strong>d_type</strong>

    The type of the file referred to by this directory entry.

cloudabi_errno_t ( uint16_t )

Error codes returned by system calls.

Not all of these error codes are returned by the system calls provided by this environment, but are either used in userspace exclusively or merely provided for alignment with POSIX.

Possible values:

  • CLOUDABI_E2BIG

    Argument list too long.

  • CLOUDABI_EACCES

    Permission denied.

  • CLOUDABI_EADDRINUSE

    Address in use.

  • CLOUDABI_EADDRNOTAVAIL

    Address not available.

  • CLOUDABI_EAFNOSUPPORT

    Address family not supported.

  • CLOUDABI_EAGAIN

    Resource unavailable, or operation would block.

  • CLOUDABI_EALREADY

    Connection already in progress.

  • CLOUDABI_EBADF

    Bad file descriptor.

  • CLOUDABI_EBADMSG

    Bad message.

  • CLOUDABI_EBUSY

    Device or resource busy.

  • CLOUDABI_ECANCELED

    Operation canceled.

  • CLOUDABI_ECHILD

    No child processes.

  • CLOUDABI_ECONNABORTED

    Connection aborted.

  • CLOUDABI_ECONNREFUSED

    Connection refused.

  • CLOUDABI_ECONNRESET

    Connection reset.

  • CLOUDABI_EDEADLK

    Resource deadlock would occur.

  • CLOUDABI_EDESTADDRREQ

    Destination address required.

  • CLOUDABI_EDOM

    Mathematics argument out of domain of function.

  • CLOUDABI_EDQUOT

    Reserved.

  • CLOUDABI_EEXIST

    File exists.

  • CLOUDABI_EFAULT

    Bad address.

  • CLOUDABI_EFBIG

    File too large.

  • CLOUDABI_EHOSTUNREACH

    Host is unreachable.

  • CLOUDABI_EIDRM

    Identifier removed.

  • CLOUDABI_EILSEQ

    Illegal byte sequence.

  • CLOUDABI_EINPROGRESS

    Operation in progress.

  • CLOUDABI_EINTR

    Interrupted function.

  • CLOUDABI_EINVAL

    Invalid argument.

  • CLOUDABI_EIO

    I/O error.

  • CLOUDABI_EISCONN

    Socket is connected.

  • CLOUDABI_EISDIR

    Is a directory.

  • CLOUDABI_ELOOP

    Too many levels of symbolic links.

  • CLOUDABI_EMFILE

    File descriptor value too large.

  • CLOUDABI_EMLINK

    Too many links.

  • CLOUDABI_EMSGSIZE

    Message too large.

  • CLOUDABI_EMULTIHOP

    Reserved.

  • CLOUDABI_ENAMETOOLONG

    Filename too long.

  • CLOUDABI_ENETDOWN

    Network is down.

  • CLOUDABI_ENETRESET

    Connection aborted by network.

  • CLOUDABI_ENETUNREACH

    Network unreachable.

  • CLOUDABI_ENFILE

    Too many files open in system.

  • CLOUDABI_ENOBUFS

    No buffer space available.

  • CLOUDABI_ENODEV

    No such device.

  • CLOUDABI_ENOENT

    No such file or directory.

  • CLOUDABI_ENOEXEC

    Executable file format error.

  • CLOUDABI_ENOLCK

    No locks available.

  • CLOUDABI_ENOLINK

    Reserved.

  • CLOUDABI_ENOMEM

    Not enough space.

  • CLOUDABI_ENOMSG

    No message of the desired type.

  • CLOUDABI_ENOPROTOOPT

    Protocol not available.

  • CLOUDABI_ENOSPC

    No space left on device.

  • CLOUDABI_ENOSYS

    Function not supported.

  • CLOUDABI_ENOTCONN

    The socket is not connected.

  • CLOUDABI_ENOTDIR

    Not a directory or a symbolic link to a directory.

  • CLOUDABI_ENOTEMPTY

    Directory not empty.

  • CLOUDABI_ENOTRECOVERABLE

    State not recoverable.

  • CLOUDABI_ENOTSOCK

    Not a socket.

  • CLOUDABI_ENOTSUP

    Not supported, or operation not supported on socket.

  • CLOUDABI_ENOTTY

    Inappropriate I/O control operation.

  • CLOUDABI_ENXIO

    No such device or address.

  • CLOUDABI_EOVERFLOW

    Value too large to be stored in data type.

  • CLOUDABI_EOWNERDEAD

    Previous owner died.

  • CLOUDABI_EPERM

    Operation not permitted.

  • CLOUDABI_EPIPE

    Broken pipe.

  • CLOUDABI_EPROTO

    Protocol error.

  • CLOUDABI_EPROTONOSUPPORT

    Protocol not supported.

  • CLOUDABI_EPROTOTYPE

    Protocol wrong type for socket.

  • CLOUDABI_ERANGE

    Result too large.

  • CLOUDABI_EROFS

    Read-only file system.

  • CLOUDABI_ESPIPE

    Invalid seek.

  • CLOUDABI_ESRCH

    No such process.

  • CLOUDABI_ESTALE

    Reserved.

  • CLOUDABI_ETIMEDOUT

    Connection timed out.

  • CLOUDABI_ETXTBSY

    Text file busy.

  • CLOUDABI_EXDEV

    Cross-device link.

  • CLOUDABI_ENOTCAPABLE

    Extension: Capabilities insufficient.

cloudabi_event_t ( struct )

An event that occurred.

Used byand cloudabi_sys_poll_fd() .

Members:

  • <a href="#userdata">cloudabi_userdata_t</a> <strong>userdata</strong>

    User-provided value that got attached to cloudabi_subscription_t::userdata .

  • <a href="#errno">cloudabi_errno_t</a> <strong>error</strong>

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

  • <a href="#eventtype">cloudabi_eventtype_t</a> <strong>type</strong>

    The type of the event that occurred.

  • When type is CLOUDABI_EVENTTYPE_CLOCK :

    • clock

      • <a href="#userdata">cloudabi_userdata_t</a> <strong>identifier</strong>

        The user-defined unique identifier of the clock.

  • When type is CLOUDABI_EVENTTYPE_CONDVAR :

    • condvar

      • _Atomic(<a href="#condvar">cloudabi_condvar_t</a>) *<strong>condvar</strong>

        The condition variable that got woken up.

  • When type is CLOUDABI_EVENTTYPE_FD_READ or CLOUDABI_EVENTTYPE_FD_WRITE :

    • fd_readwrite

      • <a href="#filesize">cloudabi_filesize_t</a> <strong>nbytes</strong>

        The number of bytes available for reading or writing.

      • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

        The file descriptor that has data available for reading or writing.

      • <a href="#eventrwflags">cloudabi_eventrwflags_t</a> <strong>flags</strong>

        The state of the file descriptor.

  • When type is CLOUDABI_EVENTTYPE_LOCK_RDLOCK or CLOUDABI_EVENTTYPE_LOCK_WRLOCK :

    • lock

      • _Atomic(<a href="#lock">cloudabi_lock_t</a>) *<strong>lock</strong>

        The lock that has been acquired for reading or writing.

  • When type is CLOUDABI_EVENTTYPE_PROC_TERMINATE :

    • proc_terminate

      • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

        The process descriptor of the process that has terminated.

      • <a href="#signal">cloudabi_signal_t</a> <strong>signal</strong>

        If zero, the process has exited. Otherwise, the signal condition causing it to terminated.

      • <a href="#exitcode">cloudabi_exitcode_t</a> <strong>exitcode</strong>

        If exited, the exit code of the process.

cloudabi_eventrwflags_t ( uint16_t bitfield)

The state of the file descriptor subscribed to with CLOUDABI_EVENTTYPE_FD_READ or CLOUDABI_EVENTTYPE_FD_WRITE .

Used by.

Possible values:

  • CLOUDABI_EVENT_FD_READWRITE_HANGUP

    The peer of this FIFO or socket has closed or disconnected.

cloudabi_eventtype_t ( uint8_t )

Type of a subscription to an event or its occurence.

Used byand cloudabi_subscription_t .

Possible values:

cloudabi_exitcode_t ( uint32_t )

Exit code generated by a process when exiting.

Used byand cloudabi_sys_proc_exit() .

cloudabi_fd_t ( uint32_t )

A file descriptor number.

Unlike on POSIX-compliant systems, none of the file descriptor numbers are reserved for a purpose (e.g., stdin, stdout, stderr). Operating systems are not required to allocate new file descriptors in ascending order.

Special values:

cloudabi_fdflags_t ( uint16_t bitfield)

File descriptor flags.

Used by.

Possible values:

  • CLOUDABI_FDFLAG_APPEND

    Append mode: Data written to the file is always appended to the file’s end.

  • CLOUDABI_FDFLAG_DSYNC

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

  • CLOUDABI_FDFLAG_NONBLOCK

    Non-blocking mode.

  • CLOUDABI_FDFLAG_RSYNC

    Synchronized read I/O operations.

  • CLOUDABI_FDFLAG_SYNC

    Write according to synchronized I/O file integrity completion. In addition to synchronizing the data stored in the file, the system may also synchronously update the file’s metadata.

cloudabi_fdsflags_t ( uint16_t bitfield)

Which file descriptor attributes to adjust.

Used by cloudabi_sys_fd_stat_put() .

Possible values:

cloudabi_fdstat_t ( struct )

File descriptor attributes.

Used by cloudabi_sys_fd_stat_get() , cloudabi_sys_fd_stat_put() , and cloudabi_sys_file_open() .

Members:

  • <a href="#filetype">cloudabi_filetype_t</a> <strong>fs_filetype</strong>

    File type.

  • <a href="#fdflags">cloudabi_fdflags_t</a> <strong>fs_flags</strong>

    File descriptor flags.

  • <a href="#rights">cloudabi_rights_t</a> <strong>fs_rights_base</strong>

    Rights that apply to this file descriptor.

  • <a href="#rights">cloudabi_rights_t</a> <strong>fs_rights_inheriting</strong>

    Maximum set of rights that can be installed on new file descriptors that are created through this file descriptor, e.g., through cloudabi_sys_file_open() .

cloudabi_filedelta_t ( int64_t )

Relative offset within a file.

Used by cloudabi_sys_fd_seek() .

cloudabi_filesize_t ( uint64_t )

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

Used by,, cloudabi_sys_fd_pread() , cloudabi_sys_fd_pwrite() , cloudabi_sys_fd_seek() , cloudabi_sys_file_advise() , cloudabi_sys_file_allocate() , and cloudabi_sys_mem_map() .

cloudabi_filestat_t ( struct )

File attributes.

Used by cloudabi_sys_file_stat_fget() , cloudabi_sys_file_stat_fput() , cloudabi_sys_file_stat_get() , and cloudabi_sys_file_stat_put() .

Members:

  • <a href="#device">cloudabi_device_t</a> <strong>st_dev</strong>

    Device ID of device containing the file.

  • <a href="#inode">cloudabi_inode_t</a> <strong>st_ino</strong>

    File serial number.

  • <a href="#filetype">cloudabi_filetype_t</a> <strong>st_filetype</strong>

    File type.

  • <a href="#linkcount">cloudabi_linkcount_t</a> <strong>st_nlink</strong>

    Number of hard links to the file.

  • <a href="#filesize">cloudabi_filesize_t</a> <strong>st_size</strong>

    For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link.

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>st_atim</strong>

    Last data access timestamp.

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>st_mtim</strong>

    Last data modification timestamp.

  • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>st_ctim</strong>

    Last file status change timestamp.

cloudabi_filetype_t ( uint8_t )

The type of a file descriptor or file.

Used by,,, cloudabi_sys_fd_create1() , cloudabi_sys_fd_create2() , and cloudabi_sys_file_create() .

Possible values:

  • CLOUDABI_FILETYPE_UNKNOWN

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

  • CLOUDABI_FILETYPE_BLOCK_DEVICE

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

  • CLOUDABI_FILETYPE_CHARACTER_DEVICE

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

  • CLOUDABI_FILETYPE_DIRECTORY

    The file descriptor or file refers to a directory inode.

  • CLOUDABI_FILETYPE_FIFO

    The file descriptor or file refers to a FIFO inode or one of the two endpoints of a pipe.

  • CLOUDABI_FILETYPE_POLL

    The file descriptor refers to a polling event queue.

  • CLOUDABI_FILETYPE_PROCESS

    The file descriptor refers to a process handle.

  • CLOUDABI_FILETYPE_REGULAR_FILE

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

  • CLOUDABI_FILETYPE_SHARED_MEMORY

    The file descriptor refers to a shared memory object.

  • CLOUDABI_FILETYPE_SOCKET_DGRAM

    The file descriptor or file refers to a datagram socket.

  • CLOUDABI_FILETYPE_SOCKET_SEQPACKET

    The file descriptor or file refers to a sequenced-packet socket.

  • CLOUDABI_FILETYPE_SOCKET_STREAM

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

  • CLOUDABI_FILETYPE_SYMBOLIC_LINK

    The file refers to a symbolic link inode.

cloudabi_fsflags_t ( uint16_t bitfield)

Which file attributes to adjust.

Used by cloudabi_sys_file_stat_fput() and cloudabi_sys_file_stat_put() .

Possible values:

cloudabi_inode_t ( uint64_t )

File serial number that is unique within its file system.

cloudabi_iovec_t ( struct )

A region of memory for scatter/gather reads.

Used by, cloudabi_sys_fd_pread() , and cloudabi_sys_fd_read() .

Members:

  • void *iov_base and size_t iov_len

    The address and length of the buffer to be filled.

cloudabi_linkcount_t ( uint32_t )

Number of hard links to an inode.

cloudabi_lock_t ( uint32_t )

A userspace read-recursive readers-writer lock, similar to a Linux futex or a FreeBSD umtx.

Used by, cloudabi_subscription_t , cloudabi_sys_lock_unlock() , and cloudabi_sys_thread_exit() .

Special values:

  • CLOUDABI_LOCK_UNLOCKED

    Value indicating that the lock is in its initial unlocked state.

  • CLOUDABI_LOCK_WRLOCKED

    Bitmask indicating that the lock is write-locked. If set, the lower 30 bits of the lock contain the identifier of the thread that owns the write lock. Otherwise, the lower 30 bits of the lock contain the number of acquired read locks.

  • CLOUDABI_LOCK_KERNEL_MANAGED

    Bitmask indicating that the lock is either read locked or write locked, and that one or more threads have their execution suspended, waiting to acquire the lock. The last owner of the lock must call the kernel to unlock.

    When the lock is acquired for reading and this bit is set, it means that one or more threads are attempting to acquire this lock for writing. In that case, other threads should only acquire additional read locks if suspending execution would cause a deadlock. It is preferred to suspend execution, as this prevents starvation of writers.

  • CLOUDABI_LOCK_BOGUS

    Value indicating that the lock is in an incorrect state. A lock cannot be in its initial unlocked state, while also managed by the kernel.

cloudabi_lookup_t ( struct )

Path lookup properties.

Used by cloudabi_sys_file_link() , cloudabi_sys_file_open() , cloudabi_sys_file_stat_get() , and cloudabi_sys_file_stat_put() .

Members:

  • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

    The working directory at which the resolution of the path starts.

  • <a href="#lookupflags">cloudabi_lookupflags_t</a> <strong>flags</strong>

    Flags determining the method of how the path is resolved.

cloudabi_lookupflags_t ( uint32_t bitfield)

Flags determining the method of how paths are resolved.

Used by.

Possible values:

  • CLOUDABI_LOOKUP_SYMLINK_FOLLOW

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

cloudabi_mflags_t ( uint8_t bitfield)

Memory mapping flags.

Used by cloudabi_subscription_t , cloudabi_sys_condvar_signal() , cloudabi_sys_lock_unlock() , cloudabi_sys_mem_map() , and cloudabi_sys_thread_exit() .

Possible values:

  • CLOUDABI_MAP_ANON

    Instead of mapping the contents of the file provided, create a mapping to anonymous memory. The file descriptor argument must be set to, and the offset must be set to zero.

  • CLOUDABI_MAP_FIXED

    Require that the mapping is performed at the base address provided.

  • CLOUDABI_MAP_PRIVATE

    Changes are private.

  • CLOUDABI_MAP_SHARED

    Changes are shared.

cloudabi_mprot_t ( uint8_t bitfield)

Memory page protection options.

This implementation enforces the W^X property: Pages cannot be mapped for execution while also mapped for writing.

Used by cloudabi_sys_mem_map() and cloudabi_sys_mem_protect() .

Possible values:

  • CLOUDABI_PROT_EXEC

    Page can be executed.

  • CLOUDABI_PROT_WRITE

    Page can be written.

  • CLOUDABI_PROT_READ

    Page can be read.

cloudabi_msflags_t ( uint8_t bitfield)

Methods of synchronizing memory with physical storage.

Used by cloudabi_sys_mem_sync() .

Possible values:

  • CLOUDABI_MS_ASYNC

    Perform asynchronous writes.

  • CLOUDABI_MS_INVALIDATE

    Perform synchronous writes.

  • CLOUDABI_MS_SYNC

    Invalidate cached data.

cloudabi_msgflags_t ( uint16_t bitfield)

Flags provided to and returned by cloudabi_sys_sock_recv() and cloudabi_sys_sock_send() .

Possible values:

cloudabi_nthreads_t ( uint32_t )

Specifies the number of threads sleeping on a condition variable that should be woken up.

Used by cloudabi_sys_condvar_signal() .

cloudabi_oflags_t ( uint16_t bitfield)

Open flags used by cloudabi_sys_file_open() .

Possible values:

  • CLOUDABI_O_CREAT

    Create file if it does not exist.

  • CLOUDABI_O_DIRECTORY

    Fail if not a directory.

  • CLOUDABI_O_EXCL

    Fail if file already exists.

  • CLOUDABI_O_TRUNC

    Truncate file to size 0.

cloudabi_processentry_t (function type)

Entry point for a process ( _start ).

Parameters:

  • const <a href="#auxv">cloudabi_auxv_t</a> *<strong>auxv</strong>

    The auxiliary vector. See.

cloudabi_recv_in_t ( struct )

Arguments of cloudabi_sys_sock_recv() .

Members:

  • const cloudabi_iovec_t *ri_data and size_t ri_datalen

    List of scatter/gather vectors where message data should be stored.

  • cloudabi_fd_t *ri_fds and size_t ri_fdslen

    Buffer where numbers of incoming file descriptors should be stored.

  • <a href="#msgflags">cloudabi_msgflags_t</a> <strong>ri_flags</strong>

    Message flags. Onlyandare valid.

cloudabi_recv_out_t ( struct )

Results of cloudabi_sys_sock_recv() .

Members:

  • size_t <strong>ro_datalen</strong>

    Number of bytes stored in cloudabi_recv_in_t::ri_data .

  • size_t <strong>ro_fdslen</strong>

    Number of file descriptors stored in cloudabi_recv_in_t::ri_fds .

  • <a href="#sockaddr">cloudabi_sockaddr_t</a> <strong>ro_sockname</strong>

    Address on which the message was received.

  • <a href="#sockaddr">cloudabi_sockaddr_t</a> <strong>ro_peername</strong>

    Address of the peer sending the message.

  • <a href="#msgflags">cloudabi_msgflags_t</a> <strong>ro_flags</strong>

cloudabi_rights_t ( uint64_t bitfield)

File descriptor rights, determining which actions may be performed.

Used by.

Possible values:

cloudabi_sa_family_t ( uint8_t )

Socket address family.

Possible values:

  • CLOUDABI_AF_UNSPEC

    The socket address family is unknown or is different from any of the other address families specified.

  • CLOUDABI_AF_INET

    An IPv4 address.

  • CLOUDABI_AF_INET6

    An IPv6 address.

  • CLOUDABI_AF_UNIX

    The socket is local to the system, and may be bound to the file system.

cloudabi_sdflags_t ( uint8_t bitfield)

Which channels on a socket need to be shut down.

Used by cloudabi_sys_sock_shutdown() .

Possible values:

  • CLOUDABI_SHUT_RD

    Disables further receive operations.

  • CLOUDABI_SHUT_WR

    Disables further send operations.

cloudabi_send_in_t ( struct )

Arguments of cloudabi_sys_sock_send() .

Members:

  • const cloudabi_ciovec_t *si_data and size_t si_datalen

    List of scatter/gather vectors where message data should be retrieved.

  • const cloudabi_fd_t *si_fds and size_t si_fdslen

    File descriptors that need to be attached to the message.

  • <a href="#msgflags">cloudabi_msgflags_t</a> <strong>si_flags</strong>

    Message flags. Onlyis valid.

cloudabi_send_out_t ( struct )

Results of cloudabi_sys_sock_send() .

Members:

  • size_t <strong>so_datalen</strong>

    Number of bytes transmitted.

cloudabi_signal_t ( uint8_t )

Signal condition.

Used byand cloudabi_sys_proc_raise() .

Possible values:

  • CLOUDABI_SIGABRT

    Process abort signal.

    Action: Terminates the process.

  • CLOUDABI_SIGALRM

    Alarm clock.

    Action: Terminates the process.

  • CLOUDABI_SIGBUS

    Access to an undefined portion of a memory object.

    Action: Terminates the process.

  • CLOUDABI_SIGCHLD

    Child process terminated, stopped, or continued.

    Action: Ignored.

  • CLOUDABI_SIGCONT

    Continue executing, if stopped.

    Action: Continues executing, if stopped.

  • CLOUDABI_SIGFPE

    Erroneous arithmetic operation.

    Action: Terminates the process.

  • CLOUDABI_SIGHUP

    Hangup.

    Action: Terminates the process.

  • CLOUDABI_SIGILL

    Illegal instruction.

    Action: Terminates the process.

  • CLOUDABI_SIGINT

    Terminale interrupt signal.

    Action: Terminates the process.

  • CLOUDABI_SIGKILL

    Kill.

    Action: Terminates the process.

  • CLOUDABI_SIGPIPE

    Write on a pipe with no one to read it.

    Action: Ignored.

  • CLOUDABI_SIGQUIT

    Terminal quit signal.

    Action: Terminates the process.

  • CLOUDABI_SIGSEGV

    Invalid memory reference.

    Action: Terminates the process.

  • CLOUDABI_SIGSTOP

    Stop executing.

    Action: Stops executing.

  • CLOUDABI_SIGSYS

    Bad system call.

    Action: Terminates the process.

  • CLOUDABI_SIGTERM

    Termination signal.

    Action: Terminates the process.

  • CLOUDABI_SIGTRAP

    Trace/breakpoint trap.

    Action: Terminates the process.

  • CLOUDABI_SIGTSTP

    Terminal stop signal.

    Action: Stops executing.

  • CLOUDABI_SIGTTIN

    Background process attempting read.

    Action: Stops executing.

  • CLOUDABI_SIGTTOU

    Background process attempting write.

    Action: Stops executing.

  • CLOUDABI_SIGURG

    High bandwidth data is available at a socket.

    Action: Ignored.

  • CLOUDABI_SIGUSR1

    User-defined signal 1.

    Action: Terminates the process.

  • CLOUDABI_SIGUSR2

    User-defined signal 2.

    Action: Terminates the process.

  • CLOUDABI_SIGVTALRM

    Virtual timer expired.

    Action: Terminates the process.

  • CLOUDABI_SIGXCPU

    CPU time limit exceeded.

    Action: Terminates the process.

  • CLOUDABI_SIGXFSZ

    File size limit exceeded.

    Action: Terminates the process.

cloudabi_sockaddr_t ( struct )

Network address of a bound socket or its peer.

Members:

  • <a href="#sa_family">cloudabi_sa_family_t</a> <strong>sa_family</strong>

    Address family.

  • When sa_family is:

    • sa_inet

      • uint8_t <strong>addr</strong>[4]

        IPv4 address.

      • uint16_t <strong>port</strong>

        IPv4 port number.

  • When sa_family is:

    • sa_inet6

      • uint8_t <strong>addr</strong>[16]

        IPv6 address.

      • uint16_t <strong>port</strong>

        IPv6 port number.

cloudabi_sockstat_t ( struct )

Socket attributes.

Used by cloudabi_sys_sock_accept() and cloudabi_sys_sock_stat_get() .

Members:

  • <a href="#sockaddr">cloudabi_sockaddr_t</a> <strong>ss_sockname</strong>

    The address to which this socket is bound.

  • <a href="#sockaddr">cloudabi_sockaddr_t</a> <strong>ss_peername</strong>

    The address to which this socket is connected.

  • <a href="#errno">cloudabi_errno_t</a> <strong>ss_error</strong>

    Error code of the last completed asynchronous operation performed on this socket.

  • <a href="#sstate">cloudabi_sstate_t</a> <strong>ss_state</strong>

    Flags describing the state of the socket.

cloudabi_ssflags_t ( uint8_t bitfield)

Specifies which socket attributes need to be altered when calling cloudabi_sys_sock_stat_get() .

Possible values:

cloudabi_sstate_t ( uint32_t bitfield)

State of the socket.

Possible values:

cloudabi_subclockflags_t ( uint16_t bitfield)

Flags determining how the timestamp provided in cloudabi_subscription_t::clock.timeout should be interpreted.

Used by cloudabi_subscription_t .

Possible values:

cloudabi_subflags_t ( uint16_t bitfield)

Flags for cloudabi_sys_poll_fd() to determine how to process a subscription request. These flags are ignored by.

Used by cloudabi_subscription_t .

Possible values:

  • CLOUDABI_SUBSCRIPTION_ADD

    Adds and enables the subscription. Implies CLOUDABI_SUBSCRIPTION_ENABLE , unless CLOUDABI_SUBSCRIPTION_DISABLE is specified.

  • CLOUDABI_SUBSCRIPTION_CLEAR

    Sets the event back to the initial state, so that it no longer triggers.

  • CLOUDABI_SUBSCRIPTION_DELETE

    Deletes the subscription.

  • CLOUDABI_SUBSCRIPTION_DISABLE

    Disables the subscription so that it does not trigger, but does not delete it.

  • CLOUDABI_SUBSCRIPTION_ENABLE

    Enables the subscription so that it can trigger.

  • CLOUDABI_SUBSCRIPTION_ONESHOT

    Automatically deletes the subscription once triggered.

cloudabi_subrwflags_t ( uint16_t bitfield)

Flags influencing the method of polling for read or writing on a file descriptor.

Used by cloudabi_subscription_t .

Possible values:

  • CLOUDABI_SUBSCRIPTION_FD_READWRITE_POLL

    If set, trigger immediately when polling for reading on a regular file, just like the POSIX poll function. Otherwise, only trigger when not at the end-of-file.

cloudabi_subscription_t ( struct )

Subscription to an event.

Used byand cloudabi_sys_poll_fd() .

Members:

  • <a href="#userdata">cloudabi_userdata_t</a> <strong>userdata</strong>

    User-provided value that is attached to the subscription in the kernel and returned through cloudabi_event_t::userdata .

  • <a href="#subflags">cloudabi_subflags_t</a> <strong>flags</strong>

    Subscription adjustment flags used by cloudabi_sys_poll_fd() . Ignored by.

  • <a href="#eventtype">cloudabi_eventtype_t</a> <strong>type</strong>

    The type of the event to which to subscribe.

    Currently, CLOUDABI_EVENTTYPE_CONDVAR , CLOUDABI_EVENTTYPE_LOCK_RDLOCK , and CLOUDABI_EVENTTYPE_LOCK_WRLOCK can only be used with. It must be provided as the first subscription and may only be followed by up to one other subscription, having type CLOUDABI_EVENTTYPE_CLOCK with CLOUDABI_SUBSCRIPTION_CLOCK_ABSTIME .

  • When type is CLOUDABI_EVENTTYPE_CLOCK :

    • clock

      • <a href="#userdata">cloudabi_userdata_t</a> <strong>identifier</strong>

        The user-defined unique identifier of the clock.

      • <a href="#clockid">cloudabi_clockid_t</a> <strong>clock_id</strong>

        The clock against which the timestamp should be compared.

      • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>timeout</strong>

        The absolute or relative timestamp.

      • <a href="#timestamp">cloudabi_timestamp_t</a> <strong>precision</strong>

        The amount of time that the kernel may wait additionally to coalesce with other events.

      • <a href="#subclockflags">cloudabi_subclockflags_t</a> <strong>flags</strong>

        Flags specifying whether the timeout is absolute or relative.

  • When type is CLOUDABI_EVENTTYPE_CONDVAR :

    • condvar

      • _Atomic(<a href="#condvar">cloudabi_condvar_t</a>) *<strong>condvar</strong>

        The condition variable on which to wait to be woken up.

      • _Atomic(<a href="#lock">cloudabi_lock_t</a>) *<strong>lock</strong>

        The lock that will be released while waiting.

        The lock will be re-acquired for writing when the condition variable triggers.

      • <a href="#mflags">cloudabi_mflags_t</a> <strong>condvar_scope</strong>

        if the condition variable is stored in private memory.if the condition variable is stored in shared memory.

      • <a href="#mflags">cloudabi_mflags_t</a> <strong>lock_scope</strong>

        if the lock is stored in private memory.if the lock is stored in shared memory.

  • When type is CLOUDABI_EVENTTYPE_FD_READ or CLOUDABI_EVENTTYPE_FD_WRITE :

    • fd_readwrite

      • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

        The file descriptor on which to wait for it to become ready for reading or writing.

      • <a href="#subrwflags">cloudabi_subrwflags_t</a> <strong>flags</strong>

        Under which conditions to trigger.

  • When type is CLOUDABI_EVENTTYPE_LOCK_RDLOCK or CLOUDABI_EVENTTYPE_LOCK_WRLOCK :

    • lock

      • _Atomic(<a href="#lock">cloudabi_lock_t</a>) *<strong>lock</strong>

        The lock that should be acquired for reading or writing.

      • <a href="#mflags">cloudabi_mflags_t</a> <strong>lock_scope</strong>

        if the lock is stored in private memory.if the lock is stored in shared memory.

  • When type is CLOUDABI_EVENTTYPE_PROC_TERMINATE :

    • proc_terminate

      • <a href="#fd">cloudabi_fd_t</a> <strong>fd</strong>

        The process descriptor on which to wait for process termination.

cloudabi_threadattr_t ( struct )

Attributes for thread creation.

Used by cloudabi_sys_thread_create() .

Members:

  • <a href="#threadentry">cloudabi_threadentry_t</a> *<strong>entry_point</strong>

    Initial program counter value.

  • void *stack and size_t stack_size

    Region allocated to serve as stack space.

  • void *<strong>argument</strong>

    Argument to be forwarded to the entry point function.

cloudabi_threadentry_t (function type)

Entry point for additionally created threads.

Used by cloudabi_threadattr_t .

Parameters:

  • <a href="#tid">cloudabi_tid_t</a> <strong>tid</strong>

    Thread ID of the current thread.

  • void *<strong>aux</strong>

    Copy of the value stored in cloudabi_threadattr_t::argument .

cloudabi_tid_t ( uint32_t )

Unique system-local identifier of a thread. This identifier is only valid during the lifetime of the thread.

Threads must be aware of their thread identifier, as it is written it into locks when acquiring them for writing. It is not advised to use these identifiers for any other purpose.

Used by cloudabi_threadentry_t , cloudabi_sys_proc_fork() , and cloudabi_sys_thread_create() .

cloudabi_timestamp_t ( uint64_t )

Timestamp in nanoseconds.

Used by, cloudabi_subscription_t , cloudabi_sys_clock_res_get() , and cloudabi_sys_clock_time_get() .

cloudabi_ulflags_t ( uint8_t bitfield)

Specifies whether files are unlinked or directories are removed.

Used by cloudabi_sys_file_unlink() .

Possible values:

  • CLOUDABI_UNLINK_REMOVEDIR

    If set, removes a directory. Otherwise, unlinks any non-directory file.

cloudabi_userdata_t ( uint64_t )

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

Used byand cloudabi_subscription_t .

cloudabi_whence_t ( uint8_t )

Relative to which position the offset of the file descriptor should be set.

Used by cloudabi_sys_fd_seek() .

Possible values:

  • CLOUDABI_WHENCE_CUR

    Seek relative to current position.

  • CLOUDABI_WHENCE_END

    Seek relative to end-of-file.

  • CLOUDABI_WHENCE_SET

    Seek relative to start-of-file.

转载本站任何文章请注明:转载至神刀安全网,谢谢神刀安全网 » The CloudABI Specification

分享到:更多 ()

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
分享按钮