clone

Partial in Antinomie 0.7.0 · Syscall list

Synopsis

long clone(unsigned long clone_flags, unsigned long newsp, int *parent_tidptr, int *child_tidptr, unsigned long tls);

Number (x86-64)	56
ABI	common
Kernel entry point	sys_clone

This is the raw kernel prototype from the pinned Linux 6.12.94 schema, not the libc wrapper.

Description

Creates a new thread or process, with flags choosing exactly what is shared with the caller. fork, vfork and threads are variants of it.

Arguments

Name	Type	Meaning
clone_flags (arg0)	unsigned long	CLONE_* flags choosing what is shared (memory, file table, signal handlers, thread group, …) and low bits holding the termination signal.
newsp (arg1)	unsigned long	Stack pointer for the child, or 0 to reuse the parent stack copy-on-write.
parent_tidptr (arg2)	int *	Where the kernel stores the child tid for the parent.
child_tidptr (arg3)	int *	Where the kernel stores or clears the child tid in the child.
tls (arg4)	unsigned long	New thread-local storage descriptor.

Return value

On success: the child’s thread id in the parent, 0 in the child.

In an Antinomie trace the Return column and the ret filter field show the raw kernel return value. On failure that is the negative errno, for example -2 for ENOENT, not the -1 plus errno that the libc wrapper gives. syscall.errno holds the positive errno and syscall.success is false.

Common errors

Raw return	Name	Meaning
-11	EAGAIN	The call would block, or a resource is temporarily unavailable.
-22	EINVAL	An argument is invalid.
-12	ENOMEM	The kernel is out of memory.

Man page

clone(2) on man7.org

Captured by Antinomie

Coverage mark: Partial. The child tid word written by CLONE_CHILD_SETTID/CLONE_CHILD_CLEARTID is written by the child (or at its exit) and is recorded with the “not observed asynchronously” status.

Every call is recorded as an Entry record (the six argument words and the pointees copied at entry) and an Exit record (the return value and the pointees copied at exit).

Arguments

Argument	When	How	Recorded field key	Condition
clone_flags (arg0)	Entry	raw scalar word; Syscall Trace also decodes it into flag names (clone group), listing unknown bits separately	args.0, args.clone_flags
newsp (arg1)	Entry	raw scalar word	args.1, args.newsp
parent_tidptr (arg2)	Entry	the pointer itself, as a raw word	args.2, args.raw[2]
↳ pointee	Exit	pid_t (4 bytes) the kernel wrote for the parent	arg2.parent_tid	result is greater than 0 and CLONE_PARENT_SETTID is set
↳ pointee	Exit	int (4 bytes) pidfd the kernel wrote	arg2.pidfd	result is greater than 0 and CLONE_PIDFD is set
child_tidptr (arg3)	Entry	the pointer itself, as a raw word	args.3, args.raw[3]
↳ pointee	Exit	4 bytes, status “not observed asynchronously”	arg3.child_tid	result is greater than 0 and CLONE_CHILD_SETTID is set
↳ pointee	Exit	4 bytes, status “not observed asynchronously”	arg3.clear_child_tid	result is greater than 0 and CLONE_CHILD_CLEARTID is set
tls (arg4)	Entry	raw scalar word	args.4, args.tls

Derived and lifecycle records

• A lifecycle.child_cookie, lifecycle.child_pid, lifecycle.child_tgid and lifecycle.child_start_boot_ns record is emitted for the new task when the kernel creates it (this is how Antinomie builds the process tree).

Filter fields

• Result: ret, syscall.errno, syscall.success, syscall.duration_ns.
• Argument words: args.clone_flags (arg0), args.newsp (arg1), args.parent_tidptr (arg2), args.child_tidptr (arg3), args.tls (arg4); args.0 to args.5 by position.
• Structure wait_status behind parent_tidptr (arg2): args.parent_tidptr.<member> for value.
• Structure wait_status behind child_tidptr (arg3): args.child_tidptr.<member> for value.

See Syscall Trace filter for the full syntax.

Known gaps

• The child writes its own tid, and the kernel clears it at the child’s exit, so those two words are not read.
• See the coverage mark above for the code paths that record a gap.

For what the capture statuses mean, see Capture statuses. For what is never recorded, see Known gaps.