#include <stdint.h>
#include <linux/sched.h>
#include <sched.h>
#include <cosmos/BitMask.hxx>
#include <cosmos/proc/PidFD.hxx>
#include <cosmos/proc/types.hxx>
#include <cosmos/utils.hxx>

Classes
struct	cosmos::CloneArgs
	Argument struct for proc::clone(). More...

Typedefs
using	cosmos::CloneFlags = BitMask<CloneFlag>

Enumerations
enum class	cosmos::CloneFlag : uint64_t { CHILD_CLEARTID = CLONE_CHILD_CLEARTID , CHILD_SETTID = CLONE_CHILD_SETTID , CLEAR_SIGHAND = CLONE_CLEAR_SIGHAND , DETACHED = CLONE_DETACHED , SHARE_FILES = CLONE_FILES , SHARE_FS = CLONE_FS , INTO_CGROUP = CLONE_INTO_CGROUP , SHARE_IO = CLONE_IO , NEW_CGROUP = CLONE_NEWCGROUP , NEW_IPC = CLONE_NEWIPC , NEW_NET = CLONE_NEWNET , NEW_MOUNT = CLONE_NEWNS , NEW_NS = CLONE_NEWNS , NEW_PID = CLONE_NEWPID , NEW_USER = CLONE_NEWUSER , NEW_UTS = CLONE_NEWUTS , SHARE_PARENT = CLONE_PARENT , PARENT_SETTID = CLONE_PARENT_SETTID , PIDFD = CLONE_PIDFD , PTRACE = CLONE_PTRACE , SETTLS = CLONE_SETTLS , SIGHAND = CLONE_SIGHAND , SHARE_SYSVSEM = CLONE_SYSVSEM , THREAD = CLONE_THREAD , UNTRACED = CLONE_UNTRACED , VFORK = CLONE_VFORK , SHARE_VM = CLONE_VM }

Functions
std::optional< ProcessID >	cosmos::proc::clone (const CloneArgs &args)
	Create a child thread or process according to `args`.

Detailed Description

clone3() specific data structures and functions.

Due to the complex data structures involved and due to the low level nature of this call this is placed in its own header separate from process.hxx.

Definition in file clone.hxx.

Typedef Documentation

◆ CloneFlags

using cosmos::CloneFlags = BitMask<CloneFlag>

Definition at line 57 of file clone.hxx.

Enumeration Type Documentation

◆ CloneFlag

enum class cosmos::CloneFlag : uint64_t

strong

Enumerator
CHILD_CLEARTID	Clear the child_tid CloneArgs member in child's memory when the child exits, used by threading libraries.
CHILD_SETTID	Store the child's thread ID in the child_tid CloneArgs member in child's memory before the child runs.
CLEAR_SIGHAND	Reset all signal handling dispositions to their defaults in the child.
DETACHED	Historical, should not be used.
SHARE_FILES	Share the file descriptor table between parent and child.
SHARE_FS	Parent and child share file system information like CWD, the root (/) directory and the umask.
INTO_CGROUP	Place the child into a different version 2 cgroup, according to the cgroup field file descriptor in CloneArgs.
SHARE_IO	Share the I/O context between parent and child. This affects I/O scheduling, processes that share their context are treated as one.
NEW_CGROUP	Create the child in a new cgroup namespace (requires CAP_SYS_ADMIN).
NEW_IPC	Create the child in a new IPC namespace (requires CAP_SYS_ADMIN).
NEW_NET	Create the child in a new network namespace (requires CAP_SYS_ADMIN).
NEW_MOUNT	Create the child in a new mount namespace (requires CAP_SYS_ADMIN).
NEW_PID	Create the child in a new PID namespace (requires CAP_SYS_ADMIN).
NEW_USER	Create the child in a new user namespace.
NEW_UTS	Create the child in a new UTS namespace (requires CAP_SYS_ADMIN).
SHARE_PARENT	Make the caller's parent also the child's parent.
PARENT_SETTID	Store the child's thread ID in the parent_tid CloneArgs member in parent's memory.
PIDFD	Allocate a PIDFD file descriptor for the child and store it at the location pointed to by the pidfd CloneArgs member.
PTRACE	If the current process is being traced then the child will also be traced.
SETTLS	The TLS descriptor is set to the tls member of CloneArgs (architecture dependent meaning).
SIGHAND	Parent and child share the same table of signal handlers. Signal masks and list of pending signals are still distinct.
SHARE_SYSVSEM	Parent and child share a single list of semaphore adjustment values.
THREAD	The child shares the same thread group as the parent. Thread groups are used to implement thread semantics.
UNTRACED	A tracing process cannot force CLONE_PTRACE on the child.
VFORK	The calling process is suspended until the child calls execve() or _exit(), see vfork(); should not be used.
SHARE_VM	Parent and child share the same address space and thus observe the same memory writes and mappings/unmappings.

Definition at line 27 of file clone.hxx.

                     : uint64_t {
        CHILD_CLEARTID = CLONE_CHILD_CLEARTID,  
        CHILD_SETTID   = CLONE_CHILD_SETTID,    
        CLEAR_SIGHAND  = CLONE_CLEAR_SIGHAND,   
        DETACHED       = CLONE_DETACHED,        
        SHARE_FILES    = CLONE_FILES,           
        SHARE_FS       = CLONE_FS,              
        INTO_CGROUP    = CLONE_INTO_CGROUP,     
        SHARE_IO       = CLONE_IO,              
        NEW_CGROUP     = CLONE_NEWCGROUP,       
        NEW_IPC        = CLONE_NEWIPC,          
        NEW_NET        = CLONE_NEWNET,          
        NEW_MOUNT      = CLONE_NEWNS,           
        NEW_NS         = CLONE_NEWNS,           // just a synonym using the old compatibility name
        NEW_PID        = CLONE_NEWPID,          
        NEW_USER       = CLONE_NEWUSER,         
        NEW_UTS        = CLONE_NEWUTS,          
        SHARE_PARENT   = CLONE_PARENT,          
        PARENT_SETTID  = CLONE_PARENT_SETTID,   
        PIDFD          = CLONE_PIDFD,           
        PTRACE         = CLONE_PTRACE,          
        SETTLS         = CLONE_SETTLS,          
        SIGHAND        = CLONE_SIGHAND,         
        SHARE_SYSVSEM  = CLONE_SYSVSEM,         
        THREAD         = CLONE_THREAD,          
        UNTRACED       = CLONE_UNTRACED,        
        VFORK          = CLONE_VFORK,           
        SHARE_VM       = CLONE_VM               
};

Function Documentation

◆ clone()

COSMOS_API std::optional< ProcessID > cosmos::proc::clone ( const CloneArgs & args )

Create a child thread or process according to args.

This is a lower level version of proc::fork() that allows detailed control over the child properties. Among other it allows to create lightweight threads or new namespaces for containerization.

See also: CloneArgs and CloneFlag for the detailed settings that are available.

Due to the clone call's complexity and the low level nature of this call libcosmos does not impose additional restrictions or add safety nets. This means you need to take care of the lifetime of any file descriptors that are returned from this call, like of the PID FD when using CloneFlag::PIDFD.

Note: This uses the clone3() system call which is currently not fully integrated in glibc or in tools like Valgrind.

Returns: In the parent context this returns the process ID of the new child process. In the child context std::nullopt is returned. On error an ApiError is thrown.

Definition at line 31 of file clone.cxx.

                                                    {
        const auto child = clone3(args);
 
        if (child == -1) {
                cosmos_throw (ApiError("clone3()"));
        } else if (child == 0) {
                return std::nullopt;
        }
 
        return ProcessID{child};
}

Classes

Typedefs

Enumerations