Crate cloudabi [−] [src]

PLEASE NOTE: This entire crate including this documentation is automatically generated from cloudabi.txt

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 49 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 a file descriptor to a TCP listener, and a file descriptor to the directory for which to serve files. The web server will then be unable to do anything other than reading files in that directory, and process incoming network connections.

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

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. It does not have open, but does have openat.

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.

auxv	Auxiliary vector entry.
ciovec	A region of memory for scatter/gather writes.
condvar	A userspace condition variable.
device	Identifier for a device containing a file system. Can be used in combination with `inode` to uniquely identify a file on the local system.
dircookie	A reference to the offset of a directory entry.
dirent	A directory entry.
event	An event that occurred.
event_fd_readwrite
event_proc_terminate
eventrwflags	The state of the file descriptor subscribed to with `FD_READ` or `FD_WRITE`.
fd	A file descriptor number.
fdflags	File descriptor flags.
fdsflags	Which file descriptor attributes to adjust.
fdstat	File descriptor attributes.
filestat	File attributes.
fsflags	Which file attributes to adjust.
inode	File serial number that is unique within its file system.
iovec	A region of memory for scatter/gather reads.
lock	A userspace read-recursive readers-writer lock, similar to a Linux futex or a FreeBSD umtx.
lookup	Path lookup properties.
lookupflags	Flags determining the method of how paths are resolved.
mflags	Memory mapping flags.
mprot	Memory page protection options.
msflags	Methods of synchronizing memory with physical storage.
oflags	Open flags used by `file_open()`.
recv_in	Arguments of `sock_recv()`.
recv_out	Results of `sock_recv()`.
riflags	Flags provided to `sock_recv()`.
rights	File descriptor rights, determining which actions may be performed.
roflags	Flags returned by `sock_recv()`.
sdflags	Which channels on a socket need to be shut down.
send_in	Arguments of `sock_send()`.
send_out	Results of `sock_send()`.
siflags	Flags provided to `sock_send()`. As there are currently no flags defined, it must be set to zero.
subclockflags	Flags determining how the timestamp provided in `subscription.union.clock.timeout` should be interpreted.
subrwflags	Flags influencing the method of polling for read or writing on a file descriptor.
subscription	Subscription to an event.
subscription_clock
subscription_condvar
subscription_fd_readwrite
subscription_lock
subscription_proc_terminate
tcb	The Thread Control Block (TCB).
threadattr	Attributes for thread creation.
tid	Unique system-local identifier of a thread. This identifier is only valid during the lifetime of the thread.
ulflags	Specifies whether files are unlinked or directories are removed.

Enums

advice	File or memory access pattern advisory information.
auxtype	Enumeration describing the kind of value stored in `auxv`.
clockid	Identifiers for clocks.
errno	Error codes returned by system calls.
eventtype	Type of a subscription to an event or its occurrence.
filetype	The type of a file descriptor or file.
scope	Indicates whether an object is stored in private or shared memory.
signal	Signal condition.
whence	Relative to which position the offset of the file descriptor should be set.

Constants

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.
DIRCOOKIE_START	Permanent reference to the first directory entry within a directory.
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.
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.
LOCK_UNLOCKED	Value indicating that the lock is in its initial unlocked state.
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.
MAP_ANON_FD	Passed to `mem_map()` when creating a mapping to anonymous memory.
PROCESS_CHILD	Returned to the child process by `proc_fork()`.

Functions

clock_res_get ^⚠	Obtains the resolution of a clock.
clock_time_get ^⚠	Obtains the time value of a clock.
condvar_signal ^⚠	Wakes up threads waiting on a userspace condition variable.
fd_close ^⚠	Closes a file descriptor.
fd_create1 ^⚠	Creates a file descriptor.
fd_create2 ^⚠	Creates a pair of file descriptors.
fd_datasync ^⚠	Synchronizes the data of a file to disk.
fd_dup ^⚠	Duplicates a file descriptor.
fd_pread ^⚠	Reads from a file descriptor, without using and updating the file descriptor's offset.
fd_pwrite ^⚠	Writes to a file descriptor, without using and updating the file descriptor's offset.
fd_read ^⚠	Reads from a file descriptor.
fd_replace ^⚠	Atomically replaces a file descriptor by a copy of another file descriptor.
fd_seek ^⚠	Moves the offset of the file descriptor.
fd_stat_get ^⚠	Gets attributes of a file descriptor.
fd_stat_put ^⚠	Adjusts attributes of a file descriptor.
fd_sync ^⚠	Synchronizes the data and metadata of a file to disk.
fd_write ^⚠	Writes to a file descriptor.
file_advise ^⚠	Provides file advisory information on a file descriptor.
file_allocate ^⚠	Forces the allocation of space in a file.
file_create ^⚠	Creates a file of a specified type.
file_link ^⚠	Creates a hard link.
file_open ^⚠	Opens a file.
file_readdir ^⚠	Reads directory entries from a directory.
file_readlink ^⚠	Reads the contents of a symbolic link.
file_rename ^⚠	Renames a file.
file_stat_fget ^⚠	Gets attributes of a file by file descriptor.
file_stat_fput ^⚠	Adjusts attributes of a file by file descriptor.
file_stat_get ^⚠	Gets attributes of a file by path.
file_stat_put ^⚠	Adjusts attributes of a file by path.
file_symlink ^⚠	Creates a symbolic link.
file_unlink ^⚠	Unlinks a file, or removes a directory.
lock_unlock ^⚠	Unlocks a write-locked userspace lock.
mem_advise ^⚠	Provides memory advisory information on a region of memory.
mem_map ^⚠	Creates a memory mapping, making the contents of a file accessible through memory.
mem_protect ^⚠	Change the protection of a memory mapping.
mem_sync ^⚠	Synchronize a region of memory with its physical storage.
mem_unmap ^⚠	Unmaps a region of memory.
poll ^⚠	Concurrently polls for the occurrence of a set of events.
proc_exec ^⚠	Replaces the process by a new executable.
proc_exit ^⚠	Terminates the process normally.
proc_fork ^⚠	Forks the process of the calling thread.
proc_raise ^⚠	Sends a signal to the process of the calling thread.
random_get ^⚠	Obtains random data from the kernel random number generator.
sock_recv ^⚠	Receives a message on a socket.
sock_send ^⚠	Sends a message on a socket.
sock_shutdown ^⚠	Shuts down socket send and receive channels.
thread_create ^⚠	Creates a new thread within the current process.
thread_exit ^⚠	Terminates the calling thread.
thread_yield ^⚠	Temporarily yields execution of the calling thread.

Type Definitions

exitcode	Exit code generated by a process when exiting.
filedelta	Relative offset within a file.
filesize	Non-negative file size or length of a region within a file.
linkcount	Number of hard links to an inode.
nthreads	Specifies the number of threads sleeping on a condition variable that should be woken up.
processentry	Entry point for a process (`_start`).
threadentry	Entry point for additionally created threads.
timestamp	Timestamp in nanoseconds.
userdata	User-provided value that can be attached to objects that is retained when extracted from the kernel.

Unions

auxv_union	A union inside `auxv`.
event_union	A union inside `event`.
subscription_union	A union inside `subscription`.