clone(2)

Purpose

clone() creates a new (“child”) process with fine-grained control over what execution context is shared with the caller: virtual address space, file-descriptor table, signal-handler table, filesystem info, I/O context, and namespaces. It is the kernel primitive behind fork(2), vfork(2), and pthread_create(3). clone3() (since 5.3) is a struct-based superset with room for more flag bits and an explicit stack size.

Synopsis

#define _GNU_SOURCE
#include <sched.h>
int clone(int (*fn)(void *), void *stack, int flags, void *arg,
          ... /* pid_t *parent_tid, void *tls, pid_t *child_tid */ );

#include <linux/sched.h>   /* struct clone_args */
long syscall(SYS_clone3, struct clone_args *cl_args, size_t size);

Raw system call on x86-64: long clone(unsigned long flags, void *stack, int *parent_tid, int *child_tid, unsigned long tls); on x86-32 and ARM the last two arguments are swapped: (... int *parent_tid, unsigned long tls, int *child_tid) (clone.2, C library/kernel differences). On ia64 the entry point is __clone2(fn, stack_base, stack_size, ...) - raw clone2 takes (flags, stack_base, stack_size, …) like microblaze (clone.2).

Arguments and behavior

With the glibc wrapper the child starts executing at fn(arg) and terminates when fn returns; the wrapper rejects fn == NULL or stack == NULL with EINVAL. The raw syscall behaves like fork(): execution continues from the call site in the child, and stack may be NULL (copy-on-write copy of the parent stack; then CLONE_VM must not be set). stack points to the topmost byte of the child stack area on downward-growing architectures; no stack size is conveyed by the old interface, while clone3 passes stack (lowest byte) and stack_size explicitly (clone.2).

clone_args fields (all u64, linux/sched.h; struct version sizes CLONE_ARGS_SIZE_VER0/VER1/VER2 = 64/80/88):

size semantics (clone.2 plus kernel/fork.c copy_clone_args_from_user): size < 64 -> EINVAL; size > PAGE_SIZE -> E2BIG; the kernel copies its known 88 bytes and requires any user-supplied trailing bytes to be zero (copy_struct_from_user convention).

Return value and errors

Success: the old clone returns the child’s TID in the caller; clone3 returns 0 in the child and the child’s PID in the parent. Main errors (clone.2):

Flags and constants

Values from /usr/include/linux/sched.h; “Since” from clone.2 unless noted:

The low byte of clone’s flags is the child termination signal (fork = SIGCHLD only); clone3 moves it to exit_signal, and kernel/fork.c (clone3_args_valid) rejects exit_signal values with bits outside 0xff and rejects the CLONE_DETACHED and legacy low-byte patterns.

Security and notes

All CLONE_NEW* namespace flags except CLONE_NEWUSER need CAP_SYS_ADMIN; CLONE_NEWUSER has needed no privileges since 3.8 but cannot combine with CLONE_FS, CLONE_THREAD, or CLONE_PARENT. CLONE_PIDFD cannot combine with CLONE_THREAD, so a pidfd always names a thread-group leader. pthread_atfork(3) handlers do not run across clone calls. The glibc wrapper writes into the child stack buffer before the syscall, so do not pass the parent’s own stack buffer (clone.2, NOTES). Thread libraries pass (CLONE_VM | CLONE_FS | CLONE_FILES | CLONE_SIGHAND | CLONE_THREAD | CLONE_SYSVSEM | CLONE_SETTLS | CLONE_PARENT_SETTID | CLONE_CHILD_CLEARTID) plus SIGCHLD-free exit signal 0; see worklog 1-a (musl pthread_create.c) for the exact thread flag set. Cross-reference: fork, pidfd_open, set_tid_address, wait4.

References

• https://man7.org/linux/man-pages/man2/clone.2.html (clone3.2 is its .so alias)
• kernel/fork.c (clone3, copy_clone_args_from_user, clone3_args_valid; fetched from torvalds master; source file named in worklog 1-a)
• /usr/include/linux/sched.h (CLONE_* values, clone_args sizes)