| 1 |
'\" t |
| 2 |
.\" Copyright 1992, Drew Eckhardt <[email protected]> |
| 3 |
.\" Copyright 2001-2019, Michael Kerrisk <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: GPL-1.0-or-later |
| 7 |
.\" |
| 8 |
.TH clone 2 2026-02-08 "Linux man-pages 6.18" |
| 9 |
.SH NAME |
| 10 |
clone, __clone2, clone3 \- create a child process |
| 11 |
.SH LIBRARY |
| 12 |
Standard C library |
| 13 |
.RI ( libc ,\~ \-lc ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
/* Prototype for the glibc wrapper function */ |
| 17 |
.P |
| 18 |
.B #define _GNU_SOURCE |
| 19 |
.B #include <sched.h> |
| 20 |
.P |
| 21 |
.BI "int clone(typeof(int (void *_Nullable)) *" fn , |
| 22 |
.BI " void *" stack , |
| 23 |
.BI " int " flags , |
| 24 |
.BI " void *_Nullable " arg ", ..." |
| 25 |
.BI " \f[R]/*\f[] pid_t *_Nullable " parent_tid , |
| 26 |
.BI " void *_Nullable " tls , |
| 27 |
.BI " pid_t *_Nullable " child_tid " \f[R]*/\f[] );" |
| 28 |
.P |
| 29 |
/* For the prototype of the raw clone() system call, see VERSIONS. */ |
| 30 |
.P |
| 31 |
.BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */" |
| 32 |
.BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */" |
| 33 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 34 |
.B #include <unistd.h> |
| 35 |
.P |
| 36 |
.BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); |
| 37 |
.fi |
| 38 |
.P |
| 39 |
.IR Note : |
| 40 |
glibc provides no wrapper for |
| 41 |
.BR clone3 (), |
| 42 |
necessitating the use of |
| 43 |
.BR syscall (2). |
| 44 |
.SH DESCRIPTION |
| 45 |
These system calls |
| 46 |
create a new ("child") process, in a manner similar to |
| 47 |
.BR fork (2). |
| 48 |
.P |
| 49 |
By contrast with |
| 50 |
.BR fork (2), |
| 51 |
these system calls provide more precise control over what pieces of execution |
| 52 |
context are shared between the calling process and the child process. |
| 53 |
For example, using these system calls, the caller can control whether |
| 54 |
or not the two processes share the virtual address space, |
| 55 |
the table of file descriptors, and the table of signal handlers. |
| 56 |
These system calls also allow the new child process to be placed |
| 57 |
in separate |
| 58 |
.BR namespaces (7). |
| 59 |
.P |
| 60 |
Note that in this manual |
| 61 |
page, "calling process" normally corresponds to "parent process". |
| 62 |
But see the descriptions of |
| 63 |
.B CLONE_PARENT |
| 64 |
and |
| 65 |
.B CLONE_THREAD |
| 66 |
below. |
| 67 |
.P |
| 68 |
This page describes the following interfaces: |
| 69 |
.IP \[bu] 3 |
| 70 |
The glibc |
| 71 |
.BR clone () |
| 72 |
wrapper function and the underlying system call on which it is based. |
| 73 |
The main text describes the wrapper function; |
| 74 |
the differences for the raw system call |
| 75 |
are described toward the end of this page. |
| 76 |
.IP \[bu] |
| 77 |
The newer |
| 78 |
.BR clone3 () |
| 79 |
system call. |
| 80 |
.P |
| 81 |
In the remainder of this page, the terminology "the clone call" is used |
| 82 |
when noting details that apply to all of these interfaces. |
| 83 |
.\" |
| 84 |
.SS The clone() wrapper function |
| 85 |
When the child process is created with the |
| 86 |
.BR clone () |
| 87 |
wrapper function, |
| 88 |
it commences execution by calling the function pointed to by the argument |
| 89 |
.IR fn . |
| 90 |
(This differs from |
| 91 |
.BR fork (2), |
| 92 |
where execution continues in the child from the point |
| 93 |
of the |
| 94 |
.BR fork (2) |
| 95 |
call.) |
| 96 |
The |
| 97 |
.I arg |
| 98 |
argument is passed as the argument of the function |
| 99 |
.IR fn . |
| 100 |
.P |
| 101 |
When the |
| 102 |
.IR fn ( arg ) |
| 103 |
function returns, the child process terminates. |
| 104 |
The integer returned by |
| 105 |
.I fn |
| 106 |
is the exit status for the child process. |
| 107 |
The child process may also terminate explicitly by calling |
| 108 |
.BR exit (2) |
| 109 |
or after receiving a fatal signal. |
| 110 |
.P |
| 111 |
The |
| 112 |
.I stack |
| 113 |
argument specifies the location of the stack used by the child process. |
| 114 |
Since the child and calling process may share memory, |
| 115 |
it is not possible for the child process to execute in the |
| 116 |
same stack as the calling process. |
| 117 |
The calling process must therefore |
| 118 |
set up memory space for the child stack and pass a pointer to this |
| 119 |
space to |
| 120 |
.BR clone (). |
| 121 |
Stacks grow downward on all processors that run Linux |
| 122 |
(except the HP PA processors), so |
| 123 |
.I stack |
| 124 |
usually points to the topmost address of the memory space set up for |
| 125 |
the child stack. |
| 126 |
Note that |
| 127 |
.BR clone () |
| 128 |
does not provide a means whereby the caller can inform the kernel of the |
| 129 |
size of the stack area. |
| 130 |
.P |
| 131 |
The remaining arguments to |
| 132 |
.BR clone () |
| 133 |
are discussed below. |
| 134 |
.\" |
| 135 |
.SS clone3() |
| 136 |
The |
| 137 |
.BR clone3 () |
| 138 |
system call provides a superset of the functionality of the older |
| 139 |
.BR clone () |
| 140 |
interface. |
| 141 |
It also provides a number of API improvements, including: |
| 142 |
space for additional flags bits; |
| 143 |
cleaner separation in the use of various arguments; |
| 144 |
and the ability to specify the size of the child's stack area. |
| 145 |
.P |
| 146 |
As with |
| 147 |
.BR fork (2), |
| 148 |
.BR clone3 () |
| 149 |
returns in both the parent and the child. |
| 150 |
It returns 0 in the child process and returns the PID of the child |
| 151 |
in the parent. |
| 152 |
.P |
| 153 |
The |
| 154 |
.I cl_args |
| 155 |
argument of |
| 156 |
.BR clone3 () |
| 157 |
is a structure of the following form: |
| 158 |
.P |
| 159 |
.in +4n |
| 160 |
.EX |
| 161 |
struct clone_args { |
| 162 |
u64 flags; /* Flags bit mask */ |
| 163 |
u64 pidfd; /* Where to store PID file descriptor |
| 164 |
(\f[I]int *\f[]) */ |
| 165 |
u64 child_tid; /* Where to store child TID, |
| 166 |
in child\[aq]s memory (\f[I]pid_t *\f[]) */ |
| 167 |
u64 parent_tid; /* Where to store child TID, |
| 168 |
in parent\[aq]s memory (\f[I]pid_t *\f[]) */ |
| 169 |
u64 exit_signal; /* Signal to deliver to parent on |
| 170 |
child termination */ |
| 171 |
u64 stack; /* Pointer to lowest byte of stack */ |
| 172 |
u64 stack_size; /* Size of stack */ |
| 173 |
u64 tls; /* Location of new TLS */ |
| 174 |
u64 set_tid; /* Pointer to a \f[I]pid_t\f[] array |
| 175 |
(since Linux 5.5) */ |
| 176 |
u64 set_tid_size; /* Number of elements in \f[I]set_tid\f[] |
| 177 |
(since Linux 5.5) */ |
| 178 |
u64 cgroup; /* File descriptor for target cgroup |
| 179 |
of child (since Linux 5.7) */ |
| 180 |
}; |
| 181 |
.EE |
| 182 |
.in |
| 183 |
.P |
| 184 |
The |
| 185 |
.I size |
| 186 |
argument that is supplied to |
| 187 |
.BR clone3 () |
| 188 |
should be initialized to the size of this structure. |
| 189 |
(The existence of the |
| 190 |
.I size |
| 191 |
argument permits future extensions to the |
| 192 |
.I clone_args |
| 193 |
structure.) |
| 194 |
.P |
| 195 |
The stack for the child process is specified via |
| 196 |
.IR cl_args.stack , |
| 197 |
which points to the lowest byte of the stack area, |
| 198 |
and |
| 199 |
.IR cl_args.stack_size , |
| 200 |
which specifies the size of the stack in bytes. |
| 201 |
In the case where the |
| 202 |
.B CLONE_VM |
| 203 |
flag (see below) is specified, a stack must be explicitly allocated |
| 204 |
and specified. |
| 205 |
Otherwise, these two fields can be specified as NULL and 0, |
| 206 |
which causes the child to use the same stack area as the parent |
| 207 |
(in the child's own virtual address space). |
| 208 |
.P |
| 209 |
The remaining fields in the |
| 210 |
.I cl_args |
| 211 |
argument are discussed below. |
| 212 |
.\" |
| 213 |
.SS Equivalence between clone() and clone3() arguments |
| 214 |
Unlike the older |
| 215 |
.BR clone () |
| 216 |
interface, where arguments are passed individually, in the newer |
| 217 |
.BR clone3 () |
| 218 |
interface the arguments are packaged into the |
| 219 |
.I clone_args |
| 220 |
structure shown above. |
| 221 |
This structure allows for a superset of the information passed via the |
| 222 |
.BR clone () |
| 223 |
arguments. |
| 224 |
.P |
| 225 |
The following table shows the equivalence between the arguments of |
| 226 |
.BR clone () |
| 227 |
and the fields in the |
| 228 |
.I clone_args |
| 229 |
argument supplied to |
| 230 |
.BR clone3 (): |
| 231 |
.RS 4 |
| 232 |
.TS |
| 233 |
lb lb lb |
| 234 |
l l l |
| 235 |
li li l. |
| 236 |
clone() clone3() Notes |
| 237 |
\f[I]cl_args\f[] field |
| 238 |
flags & \[ti]0xff flags T{ |
| 239 |
For most flags; |
| 240 |
details below |
| 241 |
T} |
| 242 |
parent_tid pidfd See CLONE_PIDFD |
| 243 |
child_tid child_tid See CLONE_CHILD_SETTID |
| 244 |
parent_tid parent_tid See CLONE_PARENT_SETTID |
| 245 |
flags & 0xff exit_signal |
| 246 |
stack stack |
| 247 |
\f[R]---\f[] stack_size |
| 248 |
tls tls See CLONE_SETTLS |
| 249 |
\f[R]---\f[] set_tid See below for details |
| 250 |
\f[R]---\f[] set_tid_size |
| 251 |
\f[R]---\f[] cgroup See CLONE_INTO_CGROUP |
| 252 |
.TE |
| 253 |
.RE |
| 254 |
.\" |
| 255 |
.SS The child termination signal |
| 256 |
When the child process terminates, a signal may be sent to the parent. |
| 257 |
The termination signal is specified in the low byte of |
| 258 |
.I flags |
| 259 |
.RB ( clone ()) |
| 260 |
or in |
| 261 |
.I cl_args.exit_signal |
| 262 |
.RB ( clone3 ()). |
| 263 |
If this signal is specified as anything other than |
| 264 |
.BR SIGCHLD , |
| 265 |
then the parent process must specify the |
| 266 |
.B __WALL |
| 267 |
or |
| 268 |
.B __WCLONE |
| 269 |
options when waiting for the child with |
| 270 |
.BR wait (2). |
| 271 |
If no signal (i.e., zero) is specified, then the parent process is not signaled |
| 272 |
when the child terminates. |
| 273 |
.\" |
| 274 |
.SS The set_tid array |
| 275 |
By default, the kernel chooses the next sequential PID for the new |
| 276 |
process in each of the PID namespaces where it is present. |
| 277 |
When creating a process with |
| 278 |
.BR clone3 (), |
| 279 |
the |
| 280 |
.I set_tid |
| 281 |
array (available since Linux 5.5) |
| 282 |
can be used to select specific PIDs for the process in some |
| 283 |
or all of the PID namespaces where it is present. |
| 284 |
If the PID of the newly created process should be set only for the current |
| 285 |
PID namespace or in the newly created PID namespace (if |
| 286 |
.I flags |
| 287 |
contains |
| 288 |
.BR CLONE_NEWPID ) |
| 289 |
then the first element in the |
| 290 |
.I set_tid |
| 291 |
array has to be the desired PID and |
| 292 |
.I set_tid_size |
| 293 |
needs to be 1. |
| 294 |
.P |
| 295 |
If the PID of the newly created process should have a certain value in |
| 296 |
multiple PID namespaces, then the |
| 297 |
.I set_tid |
| 298 |
array can have multiple entries. |
| 299 |
The first entry defines the PID in the most |
| 300 |
deeply nested PID namespace and each of the following entries contains |
| 301 |
the PID in the |
| 302 |
corresponding ancestor PID namespace. |
| 303 |
The number of PID namespaces in which a PID |
| 304 |
should be set is defined by |
| 305 |
.I set_tid_size |
| 306 |
which cannot be larger than the number of currently nested PID namespaces. |
| 307 |
.P |
| 308 |
To create a process with the following PIDs in a PID namespace hierarchy: |
| 309 |
.RS 4 |
| 310 |
.TS |
| 311 |
lb lb lb |
| 312 |
l l l. |
| 313 |
PID NS level Requested PID Notes |
| 314 |
0 31496 Outermost PID namespace |
| 315 |
1 42 |
| 316 |
2 7 Innermost PID namespace |
| 317 |
.TE |
| 318 |
.RE |
| 319 |
.P |
| 320 |
Set the array to: |
| 321 |
.P |
| 322 |
.in +4n |
| 323 |
.EX |
| 324 |
set_tid[0] = 7; |
| 325 |
set_tid[1] = 42; |
| 326 |
set_tid[2] = 31496; |
| 327 |
set_tid_size = 3; |
| 328 |
.EE |
| 329 |
.in |
| 330 |
.P |
| 331 |
If only the PIDs in the two innermost PID namespaces |
| 332 |
need to be specified, set the array to: |
| 333 |
.P |
| 334 |
.in +4n |
| 335 |
.EX |
| 336 |
set_tid[0] = 7; |
| 337 |
set_tid[1] = 42; |
| 338 |
set_tid_size = 2; |
| 339 |
.EE |
| 340 |
.in |
| 341 |
.P |
| 342 |
The PID in the PID namespaces outside the two innermost PID namespaces |
| 343 |
is selected the same way as any other PID is selected. |
| 344 |
.P |
| 345 |
The |
| 346 |
.I set_tid |
| 347 |
feature requires |
| 348 |
.B CAP_SYS_ADMIN |
| 349 |
or |
| 350 |
(since Linux 5.9) |
| 351 |
.\" commit 124ea650d3072b005457faed69909221c2905a1f |
| 352 |
.\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 |
| 353 |
.B CAP_CHECKPOINT_RESTORE |
| 354 |
in all owning user namespaces of the target PID namespaces. |
| 355 |
.P |
| 356 |
Callers may only choose a PID greater than 1 in a given PID namespace |
| 357 |
if an |
| 358 |
.B init |
| 359 |
process (i.e., a process with PID 1) already exists in that namespace. |
| 360 |
Otherwise the PID |
| 361 |
entry for this PID namespace must be 1. |
| 362 |
.\" |
| 363 |
.SS The flags mask |
| 364 |
Both |
| 365 |
.BR clone () |
| 366 |
and |
| 367 |
.BR clone3 () |
| 368 |
allow a flags bit mask that modifies their behavior |
| 369 |
and allows the caller to specify what is shared between the calling process |
| 370 |
and the child process. |
| 371 |
This bit mask\[em]the |
| 372 |
.I flags |
| 373 |
argument of |
| 374 |
.BR clone () |
| 375 |
or the |
| 376 |
.I cl_args.flags |
| 377 |
field passed to |
| 378 |
.BR clone3 ()\[em]is |
| 379 |
referred to as the |
| 380 |
.I flags |
| 381 |
mask in the remainder of this page. |
| 382 |
.P |
| 383 |
The |
| 384 |
.I flags |
| 385 |
mask is specified as a bitwise OR of zero or more of |
| 386 |
the constants listed below. |
| 387 |
Except as noted below, these flags are available |
| 388 |
(and have the same effect) in both |
| 389 |
.BR clone () |
| 390 |
and |
| 391 |
.BR clone3 (). |
| 392 |
.TP |
| 393 |
.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" |
| 394 |
Clear (zero) the child thread ID at the location pointed to by |
| 395 |
.I child_tid |
| 396 |
.RB ( clone ()) |
| 397 |
or |
| 398 |
.I cl_args.child_tid |
| 399 |
.RB ( clone3 ()) |
| 400 |
in child memory when the child exits, and do a wakeup on the futex |
| 401 |
at that address. |
| 402 |
The address involved may be changed by the |
| 403 |
.BR set_tid_address (2) |
| 404 |
system call. |
| 405 |
This is used by threading libraries. |
| 406 |
.TP |
| 407 |
.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" |
| 408 |
Store the child thread ID at the location pointed to by |
| 409 |
.I child_tid |
| 410 |
.RB ( clone ()) |
| 411 |
or |
| 412 |
.I cl_args.child_tid |
| 413 |
.RB ( clone3 ()) |
| 414 |
in the child's memory. |
| 415 |
The store operation completes before the clone call |
| 416 |
returns control to user space in the child process. |
| 417 |
(Note that the store operation may not have completed before the clone call |
| 418 |
returns in the parent process, which is relevant if the |
| 419 |
.B CLONE_VM |
| 420 |
flag is also employed.) |
| 421 |
.TP |
| 422 |
.BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)" |
| 423 |
.\" commit b612e5df4587c934bd056bf05f4a1deca4de4f75 |
| 424 |
By default, signal dispositions in the child thread are the same as |
| 425 |
in the parent. |
| 426 |
If this flag is specified, |
| 427 |
then all signals that are handled in the parent |
| 428 |
(and not set to |
| 429 |
.BR SIG_IGN ) |
| 430 |
are reset to their default dispositions |
| 431 |
.RB ( SIG_DFL ) |
| 432 |
in the child. |
| 433 |
.IP |
| 434 |
Specifying this flag together with |
| 435 |
.B CLONE_SIGHAND |
| 436 |
is nonsensical and disallowed. |
| 437 |
.TP |
| 438 |
.BR CLONE_DETACHED " (historical)" |
| 439 |
For a while (during the Linux 2.5 development series) |
| 440 |
.\" added in Linux 2.5.32; removed in Linux 2.6.0-test4 |
| 441 |
there was a |
| 442 |
.B CLONE_DETACHED |
| 443 |
flag, |
| 444 |
which caused the parent not to receive a signal when the child terminated. |
| 445 |
Ultimately, the effect of this flag was subsumed under the |
| 446 |
.B CLONE_THREAD |
| 447 |
flag and by the time Linux 2.6.0 was released, this flag had no effect. |
| 448 |
Since Linux 2.6.2, |
| 449 |
the need to give this flag together with |
| 450 |
.B CLONE_THREAD |
| 451 |
disappeared. |
| 452 |
.IP |
| 453 |
This flag is still defined, but it is usually ignored when calling |
| 454 |
.BR clone (). |
| 455 |
However, see the description of |
| 456 |
.B CLONE_PIDFD |
| 457 |
for some exceptions. |
| 458 |
.TP |
| 459 |
.BR CLONE_FILES " (since Linux 2.0)" |
| 460 |
If |
| 461 |
.B CLONE_FILES |
| 462 |
is set, the calling process and the child process share the same file |
| 463 |
descriptor table. |
| 464 |
Any file descriptor created by the calling process or by the child |
| 465 |
process is also valid in the other process. |
| 466 |
Similarly, if one of the processes closes a file descriptor, |
| 467 |
or changes its associated flags (using the |
| 468 |
.BR fcntl (2) |
| 469 |
.B F_SETFD |
| 470 |
operation), the other process is also affected. |
| 471 |
If a process sharing a file descriptor table calls |
| 472 |
.BR execve (2), |
| 473 |
its file descriptor table is duplicated (unshared). |
| 474 |
.IP |
| 475 |
If |
| 476 |
.B CLONE_FILES |
| 477 |
is not set, the child process inherits a copy of all file descriptors |
| 478 |
opened in the calling process at the time of the clone call. |
| 479 |
Subsequent operations that open or close file descriptors, |
| 480 |
or change file descriptor flags, |
| 481 |
performed by either the calling |
| 482 |
process or the child process do not affect the other process. |
| 483 |
Note, however, |
| 484 |
that the duplicated file descriptors in the child refer to the same |
| 485 |
open file descriptions as the corresponding file descriptors |
| 486 |
in the calling process, |
| 487 |
and thus share file offsets and file status flags (see |
| 488 |
.BR open (2)). |
| 489 |
.TP |
| 490 |
.BR CLONE_FS " (since Linux 2.0)" |
| 491 |
If |
| 492 |
.B CLONE_FS |
| 493 |
is set, the caller and the child process share the same filesystem |
| 494 |
information. |
| 495 |
This includes the root of the filesystem, the current |
| 496 |
working directory, and the umask. |
| 497 |
Any call to |
| 498 |
.BR chroot (2), |
| 499 |
.BR chdir (2), |
| 500 |
or |
| 501 |
.BR umask (2) |
| 502 |
performed by the calling process or the child process also affects the |
| 503 |
other process. |
| 504 |
.IP |
| 505 |
If |
| 506 |
.B CLONE_FS |
| 507 |
is not set, the child process works on a copy of the filesystem |
| 508 |
information of the calling process at the time of the clone call. |
| 509 |
Calls to |
| 510 |
.BR chroot (2), |
| 511 |
.BR chdir (2), |
| 512 |
or |
| 513 |
.BR umask (2) |
| 514 |
performed later by one of the processes do not affect the other process. |
| 515 |
.TP |
| 516 |
.BR CLONE_INTO_CGROUP " (since Linux 5.7)" |
| 517 |
.\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68 |
| 518 |
By default, a child process is placed in the same version 2 |
| 519 |
cgroup as its parent. |
| 520 |
The |
| 521 |
.B CLONE_INTO_CGROUP |
| 522 |
flag allows the child process to be created in a different version 2 cgroup. |
| 523 |
(Note that |
| 524 |
.B CLONE_INTO_CGROUP |
| 525 |
has effect only for version 2 cgroups.) |
| 526 |
.IP |
| 527 |
In order to place the child process in a different cgroup, |
| 528 |
the caller specifies |
| 529 |
.B CLONE_INTO_CGROUP |
| 530 |
in |
| 531 |
.I cl_args.flags |
| 532 |
and passes a file descriptor that refers to a version 2 cgroup in the |
| 533 |
.I cl_args.cgroup |
| 534 |
field. |
| 535 |
(This file descriptor can be obtained by opening a cgroup v2 directory |
| 536 |
using either the |
| 537 |
.B O_RDONLY |
| 538 |
or the |
| 539 |
.B O_PATH |
| 540 |
flag.) |
| 541 |
Note that all of the usual restrictions (described in |
| 542 |
.BR cgroups (7)) |
| 543 |
on placing a process into a version 2 cgroup apply. |
| 544 |
.IP |
| 545 |
Among the possible use cases for |
| 546 |
.B CLONE_INTO_CGROUP |
| 547 |
are the following: |
| 548 |
.RS |
| 549 |
.IP \[bu] 3 |
| 550 |
Spawning a process into a cgroup different from the parent's cgroup |
| 551 |
makes it possible for a service manager to directly spawn new |
| 552 |
services into dedicated cgroups. |
| 553 |
This eliminates the accounting |
| 554 |
jitter that would be caused if the child process was first created in the |
| 555 |
same cgroup as the parent and then |
| 556 |
moved into the target cgroup. |
| 557 |
Furthermore, spawning the child process directly into a target cgroup |
| 558 |
is significantly cheaper than moving the child process into |
| 559 |
the target cgroup after it has been created. |
| 560 |
.IP \[bu] |
| 561 |
The |
| 562 |
.B CLONE_INTO_CGROUP |
| 563 |
flag also allows the creation of |
| 564 |
frozen child processes by spawning them into a frozen cgroup. |
| 565 |
(See |
| 566 |
.BR cgroups (7) |
| 567 |
for a description of the freezer controller.) |
| 568 |
.IP \[bu] |
| 569 |
For threaded applications (or even thread implementations which |
| 570 |
make use of cgroups to limit individual threads), it is possible to |
| 571 |
establish a fixed cgroup layout before spawning each thread |
| 572 |
directly into its target cgroup. |
| 573 |
.RE |
| 574 |
.TP |
| 575 |
.BR CLONE_IO " (since Linux 2.6.25)" |
| 576 |
If |
| 577 |
.B CLONE_IO |
| 578 |
is set, then the new process shares an I/O context with |
| 579 |
the calling process. |
| 580 |
If this flag is not set, then (as with |
| 581 |
.BR fork (2)) |
| 582 |
the new process has its own I/O context. |
| 583 |
.IP |
| 584 |
.\" The following based on text from Jens Axboe |
| 585 |
The I/O context is the I/O scope of the disk scheduler (i.e., |
| 586 |
what the I/O scheduler uses to model scheduling of a process's I/O). |
| 587 |
If processes share the same I/O context, |
| 588 |
they are treated as one by the I/O scheduler. |
| 589 |
As a consequence, they get to share disk time. |
| 590 |
For some I/O schedulers, |
| 591 |
.\" the anticipatory and CFQ scheduler |
| 592 |
if two processes share an I/O context, |
| 593 |
they will be allowed to interleave their disk access. |
| 594 |
If several threads are doing I/O on behalf of the same process |
| 595 |
.RB ( aio_read (3), |
| 596 |
for instance), they should employ |
| 597 |
.B CLONE_IO |
| 598 |
to get better I/O performance. |
| 599 |
.\" with CFQ and AS. |
| 600 |
.IP |
| 601 |
If the kernel is not configured with the |
| 602 |
.B CONFIG_BLOCK |
| 603 |
option, this flag is a no-op. |
| 604 |
.TP |
| 605 |
.BR CLONE_NEWCGROUP " (since Linux 4.6)" |
| 606 |
Create the process in a new cgroup namespace. |
| 607 |
If this flag is not set, then (as with |
| 608 |
.BR fork (2)) |
| 609 |
the process is created in the same cgroup namespaces as the calling process. |
| 610 |
.IP |
| 611 |
For further information on cgroup namespaces, see |
| 612 |
.BR cgroup_namespaces (7). |
| 613 |
.IP |
| 614 |
Only a privileged process |
| 615 |
.RB ( CAP_SYS_ADMIN ) |
| 616 |
can employ |
| 617 |
.BR CLONE_NEWCGROUP . |
| 618 |
.\" |
| 619 |
.TP |
| 620 |
.BR CLONE_NEWIPC " (since Linux 2.6.19)" |
| 621 |
If |
| 622 |
.B CLONE_NEWIPC |
| 623 |
is set, then create the process in a new IPC namespace. |
| 624 |
If this flag is not set, then (as with |
| 625 |
.BR fork (2)), |
| 626 |
the process is created in the same IPC namespace as |
| 627 |
the calling process. |
| 628 |
.IP |
| 629 |
For further information on IPC namespaces, see |
| 630 |
.BR ipc_namespaces (7). |
| 631 |
.IP |
| 632 |
Only a privileged process |
| 633 |
.RB ( CAP_SYS_ADMIN ) |
| 634 |
can employ |
| 635 |
.BR CLONE_NEWIPC . |
| 636 |
This flag can't be specified in conjunction with |
| 637 |
.BR CLONE_SYSVSEM . |
| 638 |
.TP |
| 639 |
.BR CLONE_NEWNET " (since Linux 2.6.24)" |
| 640 |
(The implementation of this flag was completed only |
| 641 |
by about Linux 2.6.29.) |
| 642 |
.IP |
| 643 |
If |
| 644 |
.B CLONE_NEWNET |
| 645 |
is set, then create the process in a new network namespace. |
| 646 |
If this flag is not set, then (as with |
| 647 |
.BR fork (2)) |
| 648 |
the process is created in the same network namespace as |
| 649 |
the calling process. |
| 650 |
.IP |
| 651 |
For further information on network namespaces, see |
| 652 |
.BR network_namespaces (7). |
| 653 |
.IP |
| 654 |
Only a privileged process |
| 655 |
.RB ( CAP_SYS_ADMIN ) |
| 656 |
can employ |
| 657 |
.BR CLONE_NEWNET . |
| 658 |
.TP |
| 659 |
.BR CLONE_NEWNS " (since Linux 2.4.19)" |
| 660 |
If |
| 661 |
.B CLONE_NEWNS |
| 662 |
is set, the cloned child is started in a new mount namespace, |
| 663 |
initialized with a copy of the namespace of the parent. |
| 664 |
If |
| 665 |
.B CLONE_NEWNS |
| 666 |
is not set, the child lives in the same mount |
| 667 |
namespace as the parent. |
| 668 |
.IP |
| 669 |
For further information on mount namespaces, see |
| 670 |
.BR namespaces (7) |
| 671 |
and |
| 672 |
.BR mount_namespaces (7). |
| 673 |
.IP |
| 674 |
Only a privileged process |
| 675 |
.RB ( CAP_SYS_ADMIN ) |
| 676 |
can employ |
| 677 |
.BR CLONE_NEWNS . |
| 678 |
It is not permitted to specify both |
| 679 |
.B CLONE_NEWNS |
| 680 |
and |
| 681 |
.B CLONE_FS |
| 682 |
.\" See https://lwn.net/Articles/543273/ |
| 683 |
in the same clone call. |
| 684 |
.TP |
| 685 |
.BR CLONE_NEWPID " (since Linux 2.6.24)" |
| 686 |
.\" This explanation draws a lot of details from |
| 687 |
.\" http://lwn.net/Articles/259217/ |
| 688 |
.\" Authors: Pavel Emelyanov <[email protected]> |
| 689 |
.\" and Kir Kolyshkin <[email protected]> |
| 690 |
.\" |
| 691 |
.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 |
| 692 |
.\" Author: Pavel Emelyanov <[email protected]> |
| 693 |
If |
| 694 |
.B CLONE_NEWPID |
| 695 |
is set, then create the process in a new PID namespace. |
| 696 |
If this flag is not set, then (as with |
| 697 |
.BR fork (2)) |
| 698 |
the process is created in the same PID namespace as |
| 699 |
the calling process. |
| 700 |
.IP |
| 701 |
For further information on PID namespaces, see |
| 702 |
.BR namespaces (7) |
| 703 |
and |
| 704 |
.BR pid_namespaces (7). |
| 705 |
.IP |
| 706 |
Only a privileged process |
| 707 |
.RB ( CAP_SYS_ADMIN ) |
| 708 |
can employ |
| 709 |
.BR CLONE_NEWPID . |
| 710 |
This flag can't be specified in conjunction with |
| 711 |
.BR CLONE_THREAD . |
| 712 |
.TP |
| 713 |
.B CLONE_NEWUSER |
| 714 |
(This flag first became meaningful for |
| 715 |
.BR clone () |
| 716 |
in Linux 2.6.23, |
| 717 |
the current |
| 718 |
.BR clone () |
| 719 |
semantics were merged in Linux 3.5, |
| 720 |
and the final pieces to make the user namespaces completely usable were |
| 721 |
merged in Linux 3.8.) |
| 722 |
.IP |
| 723 |
If |
| 724 |
.B CLONE_NEWUSER |
| 725 |
is set, then create the process in a new user namespace. |
| 726 |
If this flag is not set, then (as with |
| 727 |
.BR fork (2)) |
| 728 |
the process is created in the same user namespace as the calling process. |
| 729 |
.IP |
| 730 |
For further information on user namespaces, see |
| 731 |
.BR namespaces (7) |
| 732 |
and |
| 733 |
.BR user_namespaces (7). |
| 734 |
.IP |
| 735 |
Before Linux 3.8, use of |
| 736 |
.B CLONE_NEWUSER |
| 737 |
required that the caller have three capabilities: |
| 738 |
.BR CAP_SYS_ADMIN , |
| 739 |
.BR CAP_SETUID , |
| 740 |
and |
| 741 |
.BR CAP_SETGID . |
| 742 |
.\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed |
| 743 |
Starting with Linux 3.8, |
| 744 |
no privileges are needed to create a user namespace. |
| 745 |
.IP |
| 746 |
This flag can't be specified in conjunction with |
| 747 |
.B CLONE_THREAD |
| 748 |
or |
| 749 |
.BR CLONE_PARENT . |
| 750 |
For security reasons, |
| 751 |
.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 |
| 752 |
.\" https://lwn.net/Articles/543273/ |
| 753 |
.\" The fix actually went into Linux 3.9 and into Linux 3.8.3. |
| 754 |
.\" However, user namespaces were, for practical purposes, |
| 755 |
.\" unusable in earlier Linux 3.8.x because of the various filesystems |
| 756 |
.\" that didn't support userns. |
| 757 |
.B CLONE_NEWUSER |
| 758 |
cannot be specified in conjunction with |
| 759 |
.BR CLONE_FS . |
| 760 |
.TP |
| 761 |
.BR CLONE_NEWUTS " (since Linux 2.6.19)" |
| 762 |
If |
| 763 |
.B CLONE_NEWUTS |
| 764 |
is set, then create the process in a new UTS namespace, |
| 765 |
whose identifiers are initialized by duplicating the identifiers |
| 766 |
from the UTS namespace of the calling process. |
| 767 |
If this flag is not set, then (as with |
| 768 |
.BR fork (2)) |
| 769 |
the process is created in the same UTS namespace as |
| 770 |
the calling process. |
| 771 |
.IP |
| 772 |
For further information on UTS namespaces, see |
| 773 |
.BR uts_namespaces (7). |
| 774 |
.IP |
| 775 |
Only a privileged process |
| 776 |
.RB ( CAP_SYS_ADMIN ) |
| 777 |
can employ |
| 778 |
.BR CLONE_NEWUTS . |
| 779 |
.TP |
| 780 |
.BR CLONE_PARENT " (since Linux 2.3.12)" |
| 781 |
If |
| 782 |
.B CLONE_PARENT |
| 783 |
is set, then the parent of the new child (as returned by |
| 784 |
.BR getppid (2)) |
| 785 |
will be the same as that of the calling process. |
| 786 |
.IP |
| 787 |
If |
| 788 |
.B CLONE_PARENT |
| 789 |
is not set, then (as with |
| 790 |
.BR fork (2)) |
| 791 |
the child's parent is the calling process. |
| 792 |
.IP |
| 793 |
Note that it is the parent process, as returned by |
| 794 |
.BR getppid (2), |
| 795 |
which is signaled when the child terminates, so that |
| 796 |
if |
| 797 |
.B CLONE_PARENT |
| 798 |
is set, then the parent of the calling process, rather than the |
| 799 |
calling process itself, is signaled. |
| 800 |
.IP |
| 801 |
The |
| 802 |
.B CLONE_PARENT |
| 803 |
flag can't be used in clone calls by the |
| 804 |
global init process (PID 1 in the initial PID namespace) |
| 805 |
and init processes in other PID namespaces. |
| 806 |
This restriction prevents the creation of multi-rooted process trees |
| 807 |
as well as the creation of unreapable zombies in the initial PID namespace. |
| 808 |
.TP |
| 809 |
.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" |
| 810 |
Store the child thread ID at the location pointed to by |
| 811 |
.I parent_tid |
| 812 |
.RB ( clone ()) |
| 813 |
or |
| 814 |
.I cl_args.parent_tid |
| 815 |
.RB ( clone3 ()) |
| 816 |
in the parent's memory. |
| 817 |
(In Linux 2.5.32-2.5.48 there was a flag |
| 818 |
.B CLONE_SETTID |
| 819 |
that did this.) |
| 820 |
The store operation completes before the clone call |
| 821 |
returns control to user space. |
| 822 |
.TP |
| 823 |
.BR CLONE_PID " (Linux 2.0 to Linux 2.5.15)" |
| 824 |
If |
| 825 |
.B CLONE_PID |
| 826 |
is set, the child process is created with the same process ID as |
| 827 |
the calling process. |
| 828 |
This is good for hacking the system, but otherwise |
| 829 |
of not much use. |
| 830 |
From Linux 2.3.21 onward, this flag could be |
| 831 |
specified only by the system boot process (PID 0). |
| 832 |
The flag disappeared completely from the kernel sources in Linux 2.5.16. |
| 833 |
Subsequently, the kernel silently ignored this bit if it was specified in the |
| 834 |
.I flags |
| 835 |
mask. |
| 836 |
Much later, the same bit was recycled for use as the |
| 837 |
.B CLONE_PIDFD |
| 838 |
flag. |
| 839 |
.TP |
| 840 |
.BR CLONE_PIDFD " (since Linux 5.2)" |
| 841 |
.\" commit b3e5838252665ee4cfa76b82bdf1198dca81e5be |
| 842 |
If this flag is specified, |
| 843 |
a PID file descriptor referring to the child process is allocated |
| 844 |
and placed at a specified location in the parent's memory. |
| 845 |
The close-on-exec flag is set on this new file descriptor. |
| 846 |
PID file descriptors can be used for the purposes described in |
| 847 |
.BR pidfd_open (2). |
| 848 |
.RS |
| 849 |
.IP \[bu] 3 |
| 850 |
When using |
| 851 |
.BR clone3 (), |
| 852 |
the PID file descriptor is placed at the location pointed to by |
| 853 |
.IR cl_args.pidfd . |
| 854 |
.IP \[bu] |
| 855 |
When using |
| 856 |
.BR clone (), |
| 857 |
the PID file descriptor is placed at the location pointed to by |
| 858 |
.IR parent_tid . |
| 859 |
Since the |
| 860 |
.I parent_tid |
| 861 |
argument is used to return the PID file descriptor, |
| 862 |
.B CLONE_PIDFD |
| 863 |
cannot be used with |
| 864 |
.B CLONE_PARENT_SETTID |
| 865 |
when calling |
| 866 |
.BR clone (). |
| 867 |
.RE |
| 868 |
.IP |
| 869 |
If |
| 870 |
.B CLONE_PIDFD |
| 871 |
is specified together with |
| 872 |
.BR CLONE_THREAD , |
| 873 |
the obtained PID file descriptor refers to a specific thread, |
| 874 |
as opposed to a thread-group leader if |
| 875 |
.B CLONE_THREAD |
| 876 |
is not specified. |
| 877 |
This feature is available since Linux 6.9. |
| 878 |
.\" commit 83b290c9e3b5d95891f43a4aeadf6071cbff25d3 |
| 879 |
.IP |
| 880 |
If the obsolete |
| 881 |
.B CLONE_DETACHED |
| 882 |
flag is specified alongside |
| 883 |
.B CLONE_PIDFD |
| 884 |
when calling |
| 885 |
.BR clone (), |
| 886 |
an error is returned. |
| 887 |
An error also results if |
| 888 |
.B CLONE_DETACHED |
| 889 |
is specified when calling |
| 890 |
.BR clone3 (). |
| 891 |
This error behavior ensures that the bit corresponding to |
| 892 |
.B CLONE_DETACHED |
| 893 |
can be reused for further PID file descriptor features in the future. |
| 894 |
.TP |
| 895 |
.BR CLONE_PTRACE " (since Linux 2.2)" |
| 896 |
If |
| 897 |
.B CLONE_PTRACE |
| 898 |
is specified, and the calling process is being traced, |
| 899 |
then trace the child also (see |
| 900 |
.BR ptrace (2)). |
| 901 |
.TP |
| 902 |
.BR CLONE_SETTLS " (since Linux 2.5.32)" |
| 903 |
The TLS (Thread Local Storage) descriptor is set to |
| 904 |
.IR tls . |
| 905 |
.IP |
| 906 |
The interpretation of |
| 907 |
.I tls |
| 908 |
and the resulting effect is architecture dependent. |
| 909 |
On x86, |
| 910 |
.I tls |
| 911 |
is interpreted as a |
| 912 |
.I struct user_desc\~* |
| 913 |
(see |
| 914 |
.BR set_thread_area (2)). |
| 915 |
On x86-64 it is the new value to be set for the %fs base register |
| 916 |
(see the |
| 917 |
.B ARCH_SET_FS |
| 918 |
argument to |
| 919 |
.BR arch_prctl (2)). |
| 920 |
On architectures with a dedicated TLS register, it is the new value |
| 921 |
of that register. |
| 922 |
.IP |
| 923 |
Use of this flag requires detailed knowledge and generally it |
| 924 |
should not be used except in libraries implementing threading. |
| 925 |
.TP |
| 926 |
.BR CLONE_SIGHAND " (since Linux 2.0)" |
| 927 |
If |
| 928 |
.B CLONE_SIGHAND |
| 929 |
is set, the calling process and the child process share the same table of |
| 930 |
signal handlers. |
| 931 |
If the calling process or child process calls |
| 932 |
.BR sigaction (2) |
| 933 |
to change the behavior associated with a signal, the behavior is |
| 934 |
changed in the other process as well. |
| 935 |
However, the calling process and child |
| 936 |
processes still have distinct signal masks and sets of pending |
| 937 |
signals. |
| 938 |
So, one of them may block or unblock signals using |
| 939 |
.BR sigprocmask (2) |
| 940 |
without affecting the other process. |
| 941 |
.IP |
| 942 |
If |
| 943 |
.B CLONE_SIGHAND |
| 944 |
is not set, the child process inherits a copy of the signal handlers |
| 945 |
of the calling process at the time of the clone call. |
| 946 |
Calls to |
| 947 |
.BR sigaction (2) |
| 948 |
performed later by one of the processes have no effect on the other |
| 949 |
process. |
| 950 |
.IP |
| 951 |
Since Linux 2.6.0, |
| 952 |
.\" Precisely: Linux 2.6.0-test6 |
| 953 |
the |
| 954 |
.I flags |
| 955 |
mask must also include |
| 956 |
.B CLONE_VM |
| 957 |
if |
| 958 |
.B CLONE_SIGHAND |
| 959 |
is specified. |
| 960 |
.TP |
| 961 |
.BR CLONE_STOPPED " (since Linux 2.6.0)" |
| 962 |
.\" Precisely: Linux 2.6.0-test2 |
| 963 |
If |
| 964 |
.B CLONE_STOPPED |
| 965 |
is set, then the child is initially stopped (as though it was sent a |
| 966 |
.B SIGSTOP |
| 967 |
signal), and must be resumed by sending it a |
| 968 |
.B SIGCONT |
| 969 |
signal. |
| 970 |
.IP |
| 971 |
This flag was |
| 972 |
.I deprecated |
| 973 |
from Linux 2.6.25 onward, |
| 974 |
and was |
| 975 |
.I removed |
| 976 |
altogether in Linux 2.6.38. |
| 977 |
Since then, the kernel silently ignores it without error. |
| 978 |
.\" glibc 2.8 removed this defn from bits/sched.h |
| 979 |
Starting with Linux 4.6, the same bit was reused for the |
| 980 |
.B CLONE_NEWCGROUP |
| 981 |
flag. |
| 982 |
.TP |
| 983 |
.BR CLONE_SYSVSEM " (since Linux 2.5.10)" |
| 984 |
If |
| 985 |
.B CLONE_SYSVSEM |
| 986 |
is set, then the child and the calling process share |
| 987 |
a single list of System V semaphore adjustment |
| 988 |
.RI ( semadj ) |
| 989 |
values (see |
| 990 |
.BR semop (2)). |
| 991 |
In this case, the shared list accumulates |
| 992 |
.I semadj |
| 993 |
values across all processes sharing the list, |
| 994 |
and semaphore adjustments are performed only when the last process |
| 995 |
that is sharing the list terminates (or ceases sharing the list using |
| 996 |
.BR unshare (2)). |
| 997 |
If this flag is not set, then the child has a separate |
| 998 |
.I semadj |
| 999 |
list that is initially empty. |
| 1000 |
.TP |
| 1001 |
.BR CLONE_THREAD " (since Linux 2.4.0)" |
| 1002 |
.\" Precisely: Linux 2.6.0-test8 |
| 1003 |
If |
| 1004 |
.B CLONE_THREAD |
| 1005 |
is set, the child is placed in the same thread group as the calling process. |
| 1006 |
To make the remainder of the discussion of |
| 1007 |
.B CLONE_THREAD |
| 1008 |
more readable, the term "thread" is used to refer to the |
| 1009 |
processes within a thread group. |
| 1010 |
.IP |
| 1011 |
Thread groups were a feature added in Linux 2.4 to support the |
| 1012 |
POSIX threads notion of a set of threads that share a single PID. |
| 1013 |
Internally, this shared PID is the so-called |
| 1014 |
thread group identifier (TGID) for the thread group. |
| 1015 |
Since Linux 2.4, calls to |
| 1016 |
.BR getpid (2) |
| 1017 |
return the TGID of the caller. |
| 1018 |
.IP |
| 1019 |
The threads within a group can be distinguished by their (system-wide) |
| 1020 |
unique thread IDs (TID). |
| 1021 |
A new thread's TID is available as the function result |
| 1022 |
returned to the caller, |
| 1023 |
and a thread can obtain |
| 1024 |
its own TID using |
| 1025 |
.BR gettid (2). |
| 1026 |
.IP |
| 1027 |
When a clone call is made without specifying |
| 1028 |
.BR CLONE_THREAD , |
| 1029 |
then the resulting thread is placed in a new thread group |
| 1030 |
whose TGID is the same as the thread's TID. |
| 1031 |
This thread is the |
| 1032 |
.I leader |
| 1033 |
of the new thread group. |
| 1034 |
.IP |
| 1035 |
A new thread created with |
| 1036 |
.B CLONE_THREAD |
| 1037 |
has the same parent process as the process that made the clone call |
| 1038 |
(i.e., like |
| 1039 |
.BR CLONE_PARENT ), |
| 1040 |
so that calls to |
| 1041 |
.BR getppid (2) |
| 1042 |
return the same value for all of the threads in a thread group. |
| 1043 |
When a |
| 1044 |
.B CLONE_THREAD |
| 1045 |
thread terminates, the thread that created it is not sent a |
| 1046 |
.B SIGCHLD |
| 1047 |
(or other termination) signal; |
| 1048 |
nor can the status of such a thread be obtained |
| 1049 |
using |
| 1050 |
.BR wait (2). |
| 1051 |
(The thread is said to be |
| 1052 |
.IR detached .) |
| 1053 |
.IP |
| 1054 |
After all of the threads in a thread group terminate |
| 1055 |
the parent process of the thread group is sent a |
| 1056 |
.B SIGCHLD |
| 1057 |
(or other termination) signal. |
| 1058 |
.IP |
| 1059 |
If any of the threads in a thread group performs an |
| 1060 |
.BR execve (2), |
| 1061 |
then all threads other than the thread group leader are terminated, |
| 1062 |
and the new program is executed in the thread group leader. |
| 1063 |
.IP |
| 1064 |
If one of the threads in a thread group creates a child using |
| 1065 |
.BR fork (2), |
| 1066 |
then any thread in the group can |
| 1067 |
.BR wait (2) |
| 1068 |
for that child. |
| 1069 |
.IP |
| 1070 |
Since Linux 2.5.35, the |
| 1071 |
.I flags |
| 1072 |
mask must also include |
| 1073 |
.B CLONE_SIGHAND |
| 1074 |
if |
| 1075 |
.B CLONE_THREAD |
| 1076 |
is specified |
| 1077 |
(and note that, since Linux 2.6.0, |
| 1078 |
.\" Precisely: Linux 2.6.0-test6 |
| 1079 |
.B CLONE_SIGHAND |
| 1080 |
also requires |
| 1081 |
.B CLONE_VM |
| 1082 |
to be included). |
| 1083 |
.IP |
| 1084 |
Signal dispositions and actions are process-wide: |
| 1085 |
if an unhandled signal is delivered to a thread, then |
| 1086 |
it will affect (terminate, stop, continue, be ignored in) |
| 1087 |
all members of the thread group. |
| 1088 |
.IP |
| 1089 |
Each thread has its own signal mask, as set by |
| 1090 |
.BR sigprocmask (2). |
| 1091 |
.IP |
| 1092 |
A signal may be process-directed or thread-directed. |
| 1093 |
A process-directed signal is targeted at a thread group (i.e., a TGID), |
| 1094 |
and is delivered to an arbitrarily selected thread from among those |
| 1095 |
that are not blocking the signal. |
| 1096 |
A signal may be process-directed because it was generated by the kernel |
| 1097 |
for reasons other than a hardware exception, or because it was sent using |
| 1098 |
.BR kill (2) |
| 1099 |
or |
| 1100 |
.BR sigqueue (3). |
| 1101 |
A thread-directed signal is targeted at (i.e., delivered to) |
| 1102 |
a specific thread. |
| 1103 |
A signal may be thread directed because it was sent using |
| 1104 |
.BR tgkill (2) |
| 1105 |
or |
| 1106 |
.BR pthread_sigqueue (3), |
| 1107 |
or because the thread executed a machine language instruction that triggered |
| 1108 |
a hardware exception |
| 1109 |
(e.g., invalid memory access triggering |
| 1110 |
.B SIGSEGV |
| 1111 |
or a floating-point exception triggering |
| 1112 |
.BR SIGFPE ). |
| 1113 |
.IP |
| 1114 |
A call to |
| 1115 |
.BR sigpending (2) |
| 1116 |
returns a signal set that is the union of the pending process-directed |
| 1117 |
signals and the signals that are pending for the calling thread. |
| 1118 |
.IP |
| 1119 |
If a process-directed signal is delivered to a thread group, |
| 1120 |
and the thread group has installed a handler for the signal, then |
| 1121 |
the handler is invoked in exactly one, arbitrarily selected |
| 1122 |
member of the thread group that has not blocked the signal. |
| 1123 |
If multiple threads in a group are waiting to accept the same signal using |
| 1124 |
.BR sigwaitinfo (2), |
| 1125 |
the kernel will arbitrarily select one of these threads |
| 1126 |
to receive the signal. |
| 1127 |
.TP |
| 1128 |
.BR CLONE_UNTRACED " (since Linux 2.5.46)" |
| 1129 |
If |
| 1130 |
.B CLONE_UNTRACED |
| 1131 |
is specified, then a tracing process cannot force |
| 1132 |
.B CLONE_PTRACE |
| 1133 |
on this child process. |
| 1134 |
.TP |
| 1135 |
.BR CLONE_VFORK " (since Linux 2.2)" |
| 1136 |
If |
| 1137 |
.B CLONE_VFORK |
| 1138 |
is set, the execution of the calling process is suspended |
| 1139 |
until the child releases its virtual memory |
| 1140 |
resources via a call to |
| 1141 |
.BR execve (2) |
| 1142 |
or |
| 1143 |
.BR _exit (2) |
| 1144 |
(as with |
| 1145 |
.BR vfork (2)). |
| 1146 |
.IP |
| 1147 |
If |
| 1148 |
.B CLONE_VFORK |
| 1149 |
is not set, then both the calling process and the child are schedulable |
| 1150 |
after the call, and an application should not rely on execution occurring |
| 1151 |
in any particular order. |
| 1152 |
.TP |
| 1153 |
.BR CLONE_VM " (since Linux 2.0)" |
| 1154 |
If |
| 1155 |
.B CLONE_VM |
| 1156 |
is set, the calling process and the child process run in the same memory |
| 1157 |
space. |
| 1158 |
In particular, memory writes performed by the calling process |
| 1159 |
or by the child process are also visible in the other process. |
| 1160 |
Moreover, any memory mapping or unmapping performed with |
| 1161 |
.BR mmap (2) |
| 1162 |
or |
| 1163 |
.BR munmap (2) |
| 1164 |
by the child or calling process also affects the other process. |
| 1165 |
.IP |
| 1166 |
If |
| 1167 |
.B CLONE_VM |
| 1168 |
is not set, the child process runs in a separate copy of the memory |
| 1169 |
space of the calling process at the time of the clone call. |
| 1170 |
Memory writes or file mappings/unmappings performed by one of the |
| 1171 |
processes do not affect the other, as with |
| 1172 |
.BR fork (2). |
| 1173 |
.IP |
| 1174 |
If the |
| 1175 |
.B CLONE_VM |
| 1176 |
flag is specified and the |
| 1177 |
.B CLONE_VFORK |
| 1178 |
flag is not specified, |
| 1179 |
then any alternate signal stack that was established by |
| 1180 |
.BR sigaltstack (2) |
| 1181 |
is cleared in the child process. |
| 1182 |
.SH RETURN VALUE |
| 1183 |
.\" gettid(2) returns current->pid; |
| 1184 |
.\" getpid(2) returns current->tgid; |
| 1185 |
On success, the thread ID of the child process is returned |
| 1186 |
in the caller's thread of execution. |
| 1187 |
On failure, \-1 is returned |
| 1188 |
in the caller's context, no child process is created, and |
| 1189 |
.I errno |
| 1190 |
is set to indicate the error. |
| 1191 |
.SH ERRORS |
| 1192 |
.TP |
| 1193 |
.BR E2BIG " (" clone3 "() only)" |
| 1194 |
The kernel does not support some functionality requested in this |
| 1195 |
.BR clone3 () |
| 1196 |
call: |
| 1197 |
The size argument is larger than what the kernel supports, |
| 1198 |
and there are non-zero values in the struct after the kernel-supported size. |
| 1199 |
.TP |
| 1200 |
.BR E2BIG " (" clone3 "() only)" |
| 1201 |
The size argument is larger than the page size. |
| 1202 |
.TP |
| 1203 |
.BR EACCES " (" clone3 "() only)" |
| 1204 |
.B CLONE_INTO_CGROUP |
| 1205 |
was specified in |
| 1206 |
.IR cl_args.flags , |
| 1207 |
but the restrictions (described in |
| 1208 |
.BR cgroups (7)) |
| 1209 |
on placing the child process into the version 2 cgroup referred to by |
| 1210 |
.I cl_args.cgroup |
| 1211 |
are not met. |
| 1212 |
.TP |
| 1213 |
.B EAGAIN |
| 1214 |
Too many processes are already running; |
| 1215 |
see |
| 1216 |
.BR fork (2). |
| 1217 |
.TP |
| 1218 |
.BR EBUSY " (" clone3 "() only)" |
| 1219 |
.B CLONE_INTO_CGROUP |
| 1220 |
was specified in |
| 1221 |
.IR cl_args.flags , |
| 1222 |
but the file descriptor specified in |
| 1223 |
.I cl_args.cgroup |
| 1224 |
refers to a version 2 cgroup in which a domain controller is enabled. |
| 1225 |
.TP |
| 1226 |
.BR EEXIST " (" clone3 "() only)" |
| 1227 |
One (or more) of the PIDs specified in |
| 1228 |
.I set_tid |
| 1229 |
already exists in the corresponding PID namespace. |
| 1230 |
.TP |
| 1231 |
.B EINVAL |
| 1232 |
Both |
| 1233 |
.B CLONE_SIGHAND |
| 1234 |
and |
| 1235 |
.B CLONE_CLEAR_SIGHAND |
| 1236 |
were specified in the |
| 1237 |
.I flags |
| 1238 |
mask. |
| 1239 |
.TP |
| 1240 |
.B EINVAL |
| 1241 |
.B CLONE_SIGHAND |
| 1242 |
was specified in the |
| 1243 |
.I flags |
| 1244 |
mask, but |
| 1245 |
.B CLONE_VM |
| 1246 |
was not. |
| 1247 |
(Since Linux 2.6.0.) |
| 1248 |
.\" Precisely: Linux 2.6.0-test6 |
| 1249 |
.TP |
| 1250 |
.B EINVAL |
| 1251 |
.B CLONE_THREAD |
| 1252 |
was specified in the |
| 1253 |
.I flags |
| 1254 |
mask, but |
| 1255 |
.B CLONE_SIGHAND |
| 1256 |
was not. |
| 1257 |
(Since Linux 2.5.35.) |
| 1258 |
.\" .TP |
| 1259 |
.\" .B EINVAL |
| 1260 |
.\" Precisely one of |
| 1261 |
.\" .B CLONE_DETACHED |
| 1262 |
.\" and |
| 1263 |
.\" .B CLONE_THREAD |
| 1264 |
.\" was specified. |
| 1265 |
.\" (Since Linux 2.6.0-test6.) |
| 1266 |
.TP |
| 1267 |
.B EINVAL |
| 1268 |
.B CLONE_THREAD |
| 1269 |
was specified in the |
| 1270 |
.I flags |
| 1271 |
mask, but the current process previously called |
| 1272 |
.BR unshare (2) |
| 1273 |
with the |
| 1274 |
.B CLONE_NEWPID |
| 1275 |
flag or used |
| 1276 |
.BR setns (2) |
| 1277 |
to reassociate itself with a PID namespace. |
| 1278 |
.TP |
| 1279 |
.B EINVAL |
| 1280 |
.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 |
| 1281 |
Both |
| 1282 |
.B CLONE_FS |
| 1283 |
and |
| 1284 |
.B CLONE_NEWNS |
| 1285 |
were specified in the |
| 1286 |
.I flags |
| 1287 |
mask. |
| 1288 |
.TP |
| 1289 |
.BR EINVAL " (since Linux 3.9)" |
| 1290 |
Both |
| 1291 |
.B CLONE_NEWUSER |
| 1292 |
and |
| 1293 |
.B CLONE_FS |
| 1294 |
were specified in the |
| 1295 |
.I flags |
| 1296 |
mask. |
| 1297 |
.TP |
| 1298 |
.B EINVAL |
| 1299 |
Both |
| 1300 |
.B CLONE_NEWIPC |
| 1301 |
and |
| 1302 |
.B CLONE_SYSVSEM |
| 1303 |
were specified in the |
| 1304 |
.I flags |
| 1305 |
mask. |
| 1306 |
.TP |
| 1307 |
.B EINVAL |
| 1308 |
.B CLONE_NEWPID |
| 1309 |
and one (or both) of |
| 1310 |
.B CLONE_THREAD |
| 1311 |
or |
| 1312 |
.B CLONE_PARENT |
| 1313 |
were specified in the |
| 1314 |
.I flags |
| 1315 |
mask. |
| 1316 |
.TP |
| 1317 |
.B EINVAL |
| 1318 |
.B CLONE_NEWUSER |
| 1319 |
and |
| 1320 |
.B CLONE_THREAD |
| 1321 |
were specified in the |
| 1322 |
.I flags |
| 1323 |
mask. |
| 1324 |
.TP |
| 1325 |
.BR EINVAL " (since Linux 2.6.32)" |
| 1326 |
.\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c |
| 1327 |
.B CLONE_PARENT |
| 1328 |
was specified, and the caller is an init process. |
| 1329 |
.TP |
| 1330 |
.B EINVAL |
| 1331 |
Returned by the glibc |
| 1332 |
.BR clone () |
| 1333 |
wrapper function when |
| 1334 |
.I fn |
| 1335 |
or |
| 1336 |
.I stack |
| 1337 |
is specified as NULL. |
| 1338 |
.TP |
| 1339 |
.B EINVAL |
| 1340 |
.B CLONE_NEWIPC |
| 1341 |
was specified in the |
| 1342 |
.I flags |
| 1343 |
mask, |
| 1344 |
but the kernel was not configured with the |
| 1345 |
.B CONFIG_SYSVIPC |
| 1346 |
and |
| 1347 |
.B CONFIG_IPC_NS |
| 1348 |
options. |
| 1349 |
.TP |
| 1350 |
.B EINVAL |
| 1351 |
.B CLONE_NEWNET |
| 1352 |
was specified in the |
| 1353 |
.I flags |
| 1354 |
mask, |
| 1355 |
but the kernel was not configured with the |
| 1356 |
.B CONFIG_NET_NS |
| 1357 |
option. |
| 1358 |
.TP |
| 1359 |
.B EINVAL |
| 1360 |
.B CLONE_NEWPID |
| 1361 |
was specified in the |
| 1362 |
.I flags |
| 1363 |
mask, |
| 1364 |
but the kernel was not configured with the |
| 1365 |
.B CONFIG_PID_NS |
| 1366 |
option. |
| 1367 |
.TP |
| 1368 |
.B EINVAL |
| 1369 |
.B CLONE_NEWUSER |
| 1370 |
was specified in the |
| 1371 |
.I flags |
| 1372 |
mask, |
| 1373 |
but the kernel was not configured with the |
| 1374 |
.B CONFIG_USER_NS |
| 1375 |
option. |
| 1376 |
.TP |
| 1377 |
.B EINVAL |
| 1378 |
.B CLONE_NEWUTS |
| 1379 |
was specified in the |
| 1380 |
.I flags |
| 1381 |
mask, |
| 1382 |
but the kernel was not configured with the |
| 1383 |
.B CONFIG_UTS_NS |
| 1384 |
option. |
| 1385 |
.TP |
| 1386 |
.B EINVAL |
| 1387 |
.I stack |
| 1388 |
is not aligned to a suitable boundary for this architecture. |
| 1389 |
For example, on aarch64, |
| 1390 |
.I stack |
| 1391 |
must be a multiple of 16. |
| 1392 |
.TP |
| 1393 |
.BR EINVAL " (" clone3 "() only)" |
| 1394 |
.B CLONE_DETACHED |
| 1395 |
was specified in the |
| 1396 |
.I flags |
| 1397 |
mask. |
| 1398 |
.TP |
| 1399 |
.BR EINVAL " (" clone "() only)" |
| 1400 |
.B CLONE_PIDFD |
| 1401 |
was specified together with |
| 1402 |
.B CLONE_DETACHED |
| 1403 |
in the |
| 1404 |
.I flags |
| 1405 |
mask. |
| 1406 |
.TP |
| 1407 |
.BR EINVAL " (before Linux 6.9)" |
| 1408 |
.B CLONE_PIDFD |
| 1409 |
was specified together with |
| 1410 |
.B CLONE_THREAD |
| 1411 |
in the |
| 1412 |
.I flags |
| 1413 |
mask. |
| 1414 |
.TP |
| 1415 |
.BR "EINVAL " "(" clone "() only)" |
| 1416 |
.B CLONE_PIDFD |
| 1417 |
was specified together with |
| 1418 |
.B CLONE_PARENT_SETTID |
| 1419 |
in the |
| 1420 |
.I flags |
| 1421 |
mask. |
| 1422 |
.TP |
| 1423 |
.BR EINVAL " (" clone3 "() only)" |
| 1424 |
.I set_tid_size |
| 1425 |
is greater than the number of nested PID namespaces. |
| 1426 |
.TP |
| 1427 |
.BR EINVAL " (" clone3 "() only)" |
| 1428 |
One of the PIDs specified in |
| 1429 |
.I set_tid |
| 1430 |
was an invalid. |
| 1431 |
.TP |
| 1432 |
.BR EINVAL " (" clone3 "() only)" |
| 1433 |
.\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872 |
| 1434 |
.B CLONE_THREAD |
| 1435 |
or |
| 1436 |
.B CLONE_PARENT |
| 1437 |
was specified in the |
| 1438 |
.I flags |
| 1439 |
mask, but a signal was specified in |
| 1440 |
.IR exit_signal . |
| 1441 |
.TP |
| 1442 |
.BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" |
| 1443 |
.I stack |
| 1444 |
was not aligned to a 128-bit boundary. |
| 1445 |
.TP |
| 1446 |
.B ENOMEM |
| 1447 |
Cannot allocate sufficient memory to allocate a task structure for the |
| 1448 |
child, or to copy those parts of the caller's context that need to be |
| 1449 |
copied. |
| 1450 |
.TP |
| 1451 |
.BR ENOSPC " (since Linux 3.7)" |
| 1452 |
.\" commit f2302505775fd13ba93f034206f1e2a587017929 |
| 1453 |
.B CLONE_NEWPID |
| 1454 |
was specified in the |
| 1455 |
.I flags |
| 1456 |
mask, |
| 1457 |
but the limit on the nesting depth of PID namespaces |
| 1458 |
would have been exceeded; |
| 1459 |
see |
| 1460 |
.BR pid_namespaces (7). |
| 1461 |
.TP |
| 1462 |
.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) |
| 1463 |
.B CLONE_NEWUSER |
| 1464 |
was specified in the |
| 1465 |
.I flags |
| 1466 |
mask, and the call would cause the limit on the number of |
| 1467 |
nested user namespaces to be exceeded. |
| 1468 |
See |
| 1469 |
.BR user_namespaces (7). |
| 1470 |
.IP |
| 1471 |
From Linux 3.11 to Linux 4.8, the error diagnosed in this case was |
| 1472 |
.BR EUSERS . |
| 1473 |
.TP |
| 1474 |
.BR ENOSPC " (since Linux 4.9)" |
| 1475 |
One of the values in the |
| 1476 |
.I flags |
| 1477 |
mask specified the creation of a new user namespace, |
| 1478 |
but doing so would have caused the limit defined by the corresponding file in |
| 1479 |
.I /proc/sys/user |
| 1480 |
to be exceeded. |
| 1481 |
For further details, see |
| 1482 |
.BR namespaces (7). |
| 1483 |
.TP |
| 1484 |
.BR EOPNOTSUPP " (" clone3 "() only)" |
| 1485 |
.B CLONE_INTO_CGROUP |
| 1486 |
was specified in |
| 1487 |
.IR cl_args.flags , |
| 1488 |
but the file descriptor specified in |
| 1489 |
.I cl_args.cgroup |
| 1490 |
refers to a version 2 cgroup that is in the |
| 1491 |
.I domain invalid |
| 1492 |
state. |
| 1493 |
.TP |
| 1494 |
.B EPERM |
| 1495 |
.BR CLONE_NEWCGROUP , |
| 1496 |
.BR CLONE_NEWIPC , |
| 1497 |
.BR CLONE_NEWNET , |
| 1498 |
.BR CLONE_NEWNS , |
| 1499 |
.BR CLONE_NEWPID , |
| 1500 |
or |
| 1501 |
.B CLONE_NEWUTS |
| 1502 |
was specified by an unprivileged process (process without |
| 1503 |
.BR CAP_SYS_ADMIN ). |
| 1504 |
.TP |
| 1505 |
.B EPERM |
| 1506 |
.B CLONE_PID |
| 1507 |
was specified by a process other than process 0. |
| 1508 |
(This error occurs only on Linux 2.5.15 and earlier.) |
| 1509 |
.TP |
| 1510 |
.B EPERM |
| 1511 |
.B CLONE_NEWUSER |
| 1512 |
was specified in the |
| 1513 |
.I flags |
| 1514 |
mask, |
| 1515 |
but either the effective user ID or the effective group ID of the caller |
| 1516 |
does not have a mapping in the parent namespace (see |
| 1517 |
.BR user_namespaces (7)). |
| 1518 |
.TP |
| 1519 |
.BR EPERM " (since Linux 3.9)" |
| 1520 |
.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d |
| 1521 |
.B CLONE_NEWUSER |
| 1522 |
was specified in the |
| 1523 |
.I flags |
| 1524 |
mask and the caller is in a chroot environment |
| 1525 |
.\" FIXME What is the rationale for this restriction? |
| 1526 |
(i.e., the caller's root directory does not match the root directory |
| 1527 |
of the mount namespace in which it resides). |
| 1528 |
.TP |
| 1529 |
.BR EPERM " (" clone3 "() only)" |
| 1530 |
.I set_tid_size |
| 1531 |
was greater than zero, and the caller lacks the |
| 1532 |
.B CAP_SYS_ADMIN |
| 1533 |
capability in one or more of the user namespaces that own the |
| 1534 |
corresponding PID namespaces. |
| 1535 |
.TP |
| 1536 |
.BR ERESTARTNOINTR " (since Linux 2.6.17)" |
| 1537 |
.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 |
| 1538 |
System call was interrupted by a signal and will be restarted. |
| 1539 |
(This can be seen only during a trace.) |
| 1540 |
.TP |
| 1541 |
.BR EUSERS " (Linux 3.11 to Linux 4.8)" |
| 1542 |
.B CLONE_NEWUSER |
| 1543 |
was specified in the |
| 1544 |
.I flags |
| 1545 |
mask, |
| 1546 |
and the limit on the number of nested user namespaces would be exceeded. |
| 1547 |
See the discussion of the |
| 1548 |
.B ENOSPC |
| 1549 |
error above. |
| 1550 |
.SH VERSIONS |
| 1551 |
The glibc |
| 1552 |
.BR clone () |
| 1553 |
wrapper function makes some changes |
| 1554 |
in the memory pointed to by |
| 1555 |
.I stack |
| 1556 |
(changes required to set the stack up correctly for the child) |
| 1557 |
.I before |
| 1558 |
invoking the |
| 1559 |
.BR clone () |
| 1560 |
system call. |
| 1561 |
So, in cases where |
| 1562 |
.BR clone () |
| 1563 |
is used to recursively create children, |
| 1564 |
do not use the buffer employed for the parent's stack |
| 1565 |
as the stack of the child. |
| 1566 |
.P |
| 1567 |
On i386, |
| 1568 |
.BR clone () |
| 1569 |
should not be called through vsyscall, but directly through |
| 1570 |
.IR "int $0x80" . |
| 1571 |
.SS C library/kernel differences |
| 1572 |
The raw |
| 1573 |
.BR clone () |
| 1574 |
system call corresponds more closely to |
| 1575 |
.BR fork (2) |
| 1576 |
in that execution in the child continues from the point of the |
| 1577 |
call. |
| 1578 |
As such, the |
| 1579 |
.I fn |
| 1580 |
and |
| 1581 |
.I arg |
| 1582 |
arguments of the |
| 1583 |
.BR clone () |
| 1584 |
wrapper function are omitted. |
| 1585 |
.P |
| 1586 |
In contrast to the glibc wrapper, the raw |
| 1587 |
.BR clone () |
| 1588 |
system call accepts NULL as a |
| 1589 |
.I stack |
| 1590 |
argument (and |
| 1591 |
.BR clone3 () |
| 1592 |
likewise allows |
| 1593 |
.I cl_args.stack |
| 1594 |
to be NULL). |
| 1595 |
In this case, the child uses a duplicate of the parent's stack. |
| 1596 |
(Copy-on-write semantics ensure that the child gets separate copies |
| 1597 |
of stack pages when either process modifies the stack.) |
| 1598 |
In this case, for correct operation, the |
| 1599 |
.B CLONE_VM |
| 1600 |
option should not be specified. |
| 1601 |
(If the child |
| 1602 |
.I shares |
| 1603 |
the parent's memory because of the use of the |
| 1604 |
.B CLONE_VM |
| 1605 |
flag, |
| 1606 |
then no copy-on-write duplication occurs and chaos is likely to result.) |
| 1607 |
.P |
| 1608 |
The order of the arguments also differs in the raw system call, |
| 1609 |
and there are variations in the arguments across architectures, |
| 1610 |
as detailed in the following paragraphs. |
| 1611 |
.P |
| 1612 |
The raw system call interface on x86-64 and some other architectures |
| 1613 |
(including sh, tile, and alpha) is: |
| 1614 |
.P |
| 1615 |
.in +4n |
| 1616 |
.EX |
| 1617 |
.BI "long clone(unsigned long " flags ", void *" stack , |
| 1618 |
.BI " int *" parent_tid ", int *" child_tid , |
| 1619 |
.BI " unsigned long " tls ); |
| 1620 |
.EE |
| 1621 |
.in |
| 1622 |
.P |
| 1623 |
On x86-32, and several other common architectures |
| 1624 |
(including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, |
| 1625 |
and MIPS), |
| 1626 |
.\" CONFIG_CLONE_BACKWARDS |
| 1627 |
the order of the last two arguments is reversed: |
| 1628 |
.P |
| 1629 |
.in +4n |
| 1630 |
.EX |
| 1631 |
.BI "long clone(unsigned long " flags ", void *" stack , |
| 1632 |
.BI " int *" parent_tid ", unsigned long " tls , |
| 1633 |
.BI " int *" child_tid ); |
| 1634 |
.EE |
| 1635 |
.in |
| 1636 |
.P |
| 1637 |
On the cris and s390 architectures, |
| 1638 |
.\" CONFIG_CLONE_BACKWARDS2 |
| 1639 |
the order of the first two arguments is reversed: |
| 1640 |
.P |
| 1641 |
.in +4n |
| 1642 |
.EX |
| 1643 |
.BI "long clone(void *" stack ", unsigned long " flags , |
| 1644 |
.BI " int *" parent_tid ", int *" child_tid , |
| 1645 |
.BI " unsigned long " tls ); |
| 1646 |
.EE |
| 1647 |
.in |
| 1648 |
.P |
| 1649 |
On the microblaze architecture, |
| 1650 |
.\" CONFIG_CLONE_BACKWARDS3 |
| 1651 |
an additional argument is supplied: |
| 1652 |
.P |
| 1653 |
.in +4n |
| 1654 |
.EX |
| 1655 |
.BI "long clone(unsigned long " flags ", void *" stack , |
| 1656 |
.BI " int " stack_size , "\f[R] /* Size of stack */\f[]" |
| 1657 |
.BI " int *" parent_tid ", int *" child_tid , |
| 1658 |
.BI " unsigned long " tls ); |
| 1659 |
.EE |
| 1660 |
.in |
| 1661 |
.\" |
| 1662 |
.SS blackfin, m68k, and sparc |
| 1663 |
.\" Mike Frysinger noted in a 2013 mail: |
| 1664 |
.\" these arches don't define __ARCH_WANT_SYS_CLONE: |
| 1665 |
.\" blackfin ia64 m68k sparc |
| 1666 |
The argument-passing conventions on |
| 1667 |
blackfin, m68k, and sparc are different from the descriptions above. |
| 1668 |
For details, see the kernel (and glibc) source. |
| 1669 |
.SH STANDARDS |
| 1670 |
Linux. |
| 1671 |
.SH HISTORY |
| 1672 |
.TP |
| 1673 |
.BR clone3 () |
| 1674 |
Linux 5.3. |
| 1675 |
.\" There is no entry for |
| 1676 |
.\" .BR clone () |
| 1677 |
.\" in libc5. |
| 1678 |
.\" glibc2 provides |
| 1679 |
.\" .BR clone () |
| 1680 |
.\" as described in this manual page. |
| 1681 |
.SS Linux 2.4 and earlier |
| 1682 |
In the Linux 2.4.x series, |
| 1683 |
.B CLONE_THREAD |
| 1684 |
generally does not make the parent of the new thread the same |
| 1685 |
as the parent of the calling process. |
| 1686 |
However, from Linux 2.4.7 to Linux 2.4.18 the |
| 1687 |
.B CLONE_THREAD |
| 1688 |
flag implied the |
| 1689 |
.B CLONE_PARENT |
| 1690 |
flag (as in Linux 2.6.0 and later). |
| 1691 |
.P |
| 1692 |
In Linux 2.4 and earlier, |
| 1693 |
.BR clone () |
| 1694 |
does not take arguments |
| 1695 |
.IR parent_tid , |
| 1696 |
.IR tls , |
| 1697 |
and |
| 1698 |
.IR child_tid . |
| 1699 |
.SS ia64 |
| 1700 |
On ia64, a different interface is used: |
| 1701 |
.P |
| 1702 |
.in +4n |
| 1703 |
.EX |
| 1704 |
.BI "int __clone2(typeof(int (void *)) *" fn , |
| 1705 |
.BI " void *" stack_base ", size_t " stack_size , |
| 1706 |
.BI " int " flags ", void *" "arg" ", ..." |
| 1707 |
.BI " \f[R]/*\f[] pid_t *" parent_tid ", struct user_desc *" tls , |
| 1708 |
.BI " pid_t *" child_tid " \f[R]*/\f[] );" |
| 1709 |
.EE |
| 1710 |
.in |
| 1711 |
.P |
| 1712 |
The prototype shown above is for the glibc wrapper function; |
| 1713 |
for the system call itself, |
| 1714 |
the prototype can be described as follows (it is identical to the |
| 1715 |
.BR clone () |
| 1716 |
prototype on microblaze): |
| 1717 |
.P |
| 1718 |
.in +4n |
| 1719 |
.EX |
| 1720 |
.BI "long clone2(unsigned long " flags ", void *" stack_base , |
| 1721 |
.BI " int " stack_size , "\f[R] /* Size of stack */\f[]" |
| 1722 |
.BI " int *" parent_tid ", int *" child_tid , |
| 1723 |
.BI " unsigned long " tls ); |
| 1724 |
.EE |
| 1725 |
.in |
| 1726 |
.P |
| 1727 |
.BR __clone2 () |
| 1728 |
operates in the same way as |
| 1729 |
.BR clone (), |
| 1730 |
except that |
| 1731 |
.I stack_base |
| 1732 |
points to the lowest address of the child's stack area, |
| 1733 |
and |
| 1734 |
.I stack_size |
| 1735 |
specifies the size of the stack pointed to by |
| 1736 |
.IR stack_base . |
| 1737 |
.SH NOTES |
| 1738 |
One use of these system calls |
| 1739 |
is to implement threads: multiple flows of control in a program that |
| 1740 |
run concurrently in a shared address space. |
| 1741 |
.P |
| 1742 |
The |
| 1743 |
.BR kcmp (2) |
| 1744 |
system call can be used to test whether two processes share various |
| 1745 |
resources such as a file descriptor table, |
| 1746 |
System V semaphore undo operations, or a virtual address space. |
| 1747 |
.P |
| 1748 |
Handlers registered using |
| 1749 |
.BR pthread_atfork (3) |
| 1750 |
are not executed during a clone call. |
| 1751 |
.SH BUGS |
| 1752 |
GNU C library versions 2.3.4 up to and including 2.24 |
| 1753 |
contained a wrapper function for |
| 1754 |
.BR getpid (2) |
| 1755 |
that performed caching of PIDs. |
| 1756 |
This caching relied on support in the glibc wrapper for |
| 1757 |
.BR clone (), |
| 1758 |
but limitations in the implementation |
| 1759 |
meant that the cache was not up to date in some circumstances. |
| 1760 |
In particular, |
| 1761 |
if a signal was delivered to the child immediately after the |
| 1762 |
.BR clone () |
| 1763 |
call, then a call to |
| 1764 |
.BR getpid (2) |
| 1765 |
in a handler for the signal could return the PID |
| 1766 |
of the calling process ("the parent"), |
| 1767 |
if the clone wrapper had not yet had a chance to update the PID |
| 1768 |
cache in the child. |
| 1769 |
(This discussion ignores the case where the child was created using |
| 1770 |
.BR CLONE_THREAD , |
| 1771 |
when |
| 1772 |
.BR getpid (2) |
| 1773 |
.I should |
| 1774 |
return the same value in the child and in the process that called |
| 1775 |
.BR clone (), |
| 1776 |
since the caller and the child are in the same thread group. |
| 1777 |
The stale-cache problem also does not occur if the |
| 1778 |
.I flags |
| 1779 |
argument includes |
| 1780 |
.BR CLONE_VM .) |
| 1781 |
To get the truth, it was sometimes necessary to use code such as the following: |
| 1782 |
.P |
| 1783 |
.in +4n |
| 1784 |
.EX |
| 1785 |
#include <syscall.h> |
| 1786 |
\& |
| 1787 |
pid_t mypid; |
| 1788 |
\& |
| 1789 |
mypid = syscall(SYS_getpid); |
| 1790 |
.EE |
| 1791 |
.in |
| 1792 |
.\" See also the following bug reports |
| 1793 |
.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 |
| 1794 |
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 |
| 1795 |
.P |
| 1796 |
Because of the stale-cache problem, as well as other problems noted in |
| 1797 |
.BR getpid (2), |
| 1798 |
the PID caching feature was removed in glibc 2.25. |
| 1799 |
.SH EXAMPLES |
| 1800 |
The following program demonstrates the use of |
| 1801 |
.BR clone () |
| 1802 |
to create a child process that executes in a separate UTS namespace. |
| 1803 |
The child changes the hostname in its UTS namespace. |
| 1804 |
Both parent and child then display the system hostname, |
| 1805 |
making it possible to see that the hostname |
| 1806 |
differs in the UTS namespaces of the parent and child. |
| 1807 |
For an example of the use of this program, see |
| 1808 |
.BR setns (2). |
| 1809 |
.P |
| 1810 |
Within the sample program, we allocate the memory that is to |
| 1811 |
be used for the child's stack using |
| 1812 |
.BR mmap (2) |
| 1813 |
rather than |
| 1814 |
.BR malloc (3) |
| 1815 |
for the following reasons: |
| 1816 |
.IP \[bu] 3 |
| 1817 |
.BR mmap (2) |
| 1818 |
allocates a block of memory that starts on a page |
| 1819 |
boundary and is a multiple of the page size. |
| 1820 |
This is useful if we want to establish a guard page (a page with protection |
| 1821 |
.BR PROT_NONE ) |
| 1822 |
at the end of the stack using |
| 1823 |
.BR mprotect (2). |
| 1824 |
.IP \[bu] |
| 1825 |
We can specify the |
| 1826 |
.B MAP_STACK |
| 1827 |
flag to request a mapping that is suitable for a stack. |
| 1828 |
For the moment, this flag is a no-op on Linux, |
| 1829 |
but it exists and has effect on some other systems, |
| 1830 |
so we should include it for portability. |
| 1831 |
.SS Program source |
| 1832 |
.\" SRC BEGIN (clone.c) |
| 1833 |
.EX |
| 1834 |
#define _GNU_SOURCE |
| 1835 |
#include <err.h> |
| 1836 |
#include <sched.h> |
| 1837 |
#include <signal.h> |
| 1838 |
#include <stdint.h> |
| 1839 |
#include <stdio.h> |
| 1840 |
#include <stdlib.h> |
| 1841 |
#include <string.h> |
| 1842 |
#include <sys/mman.h> |
| 1843 |
#include <sys/types.h> |
| 1844 |
#include <sys/utsname.h> |
| 1845 |
#include <sys/wait.h> |
| 1846 |
#include <unistd.h> |
| 1847 |
\& |
| 1848 |
static int /* Start function for cloned child */ |
| 1849 |
childFunc(void *arg) |
| 1850 |
{ |
| 1851 |
struct utsname uts; |
| 1852 |
\& |
| 1853 |
/* Change hostname in UTS namespace of child. */ |
| 1854 |
\& |
| 1855 |
if (sethostname(arg, strlen(arg)) == \-1) |
| 1856 |
err(EXIT_FAILURE, "sethostname"); |
| 1857 |
\& |
| 1858 |
/* Retrieve and display hostname. */ |
| 1859 |
\& |
| 1860 |
if (uname(&uts) == \-1) |
| 1861 |
err(EXIT_FAILURE, "uname"); |
| 1862 |
printf("uts.nodename in child: %s\[rs]n", uts.nodename); |
| 1863 |
\& |
| 1864 |
/* Keep the namespace open for a while, by sleeping. |
| 1865 |
This allows some experimentation\-\-for example, another |
| 1866 |
process might join the namespace. */ |
| 1867 |
\& |
| 1868 |
sleep(200); |
| 1869 |
\& |
| 1870 |
return 0; /* Child terminates now */ |
| 1871 |
} |
| 1872 |
\& |
| 1873 |
#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */ |
| 1874 |
\& |
| 1875 |
int |
| 1876 |
main(int argc, char *argv[]) |
| 1877 |
{ |
| 1878 |
char *stack; /* Start of stack buffer */ |
| 1879 |
char *stackTop; /* End of stack buffer */ |
| 1880 |
pid_t pid; |
| 1881 |
struct utsname uts; |
| 1882 |
\& |
| 1883 |
if (argc < 2) { |
| 1884 |
fprintf(stderr, "Usage: %s <child\-hostname>\[rs]n", argv[0]); |
| 1885 |
exit(EXIT_SUCCESS); |
| 1886 |
} |
| 1887 |
\& |
| 1888 |
/* Allocate memory to be used for the stack of the child. */ |
| 1889 |
\& |
| 1890 |
stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE, |
| 1891 |
MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0); |
| 1892 |
if (stack == MAP_FAILED) |
| 1893 |
err(EXIT_FAILURE, "mmap"); |
| 1894 |
\& |
| 1895 |
stackTop = stack + STACK_SIZE; /* Assume stack grows downward */ |
| 1896 |
\& |
| 1897 |
/* Create child that has its own UTS namespace; |
| 1898 |
child commences execution in childFunc(). */ |
| 1899 |
\& |
| 1900 |
pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]); |
| 1901 |
if (pid == \-1) |
| 1902 |
err(EXIT_FAILURE, "clone"); |
| 1903 |
if (munmap(stack, STACK_SIZE)) |
| 1904 |
err(EXIT_FAILURE, "munmap"); |
| 1905 |
printf("clone() returned %jd\[rs]n", (intmax_t) pid); |
| 1906 |
\& |
| 1907 |
/* Parent falls through to here */ |
| 1908 |
\& |
| 1909 |
sleep(1); /* Give child time to change its hostname */ |
| 1910 |
\& |
| 1911 |
/* Display hostname in parent\[aq]s UTS namespace. This will be |
| 1912 |
different from hostname in child\[aq]s UTS namespace. */ |
| 1913 |
\& |
| 1914 |
if (uname(&uts) == \-1) |
| 1915 |
err(EXIT_FAILURE, "uname"); |
| 1916 |
printf("uts.nodename in parent: %s\[rs]n", uts.nodename); |
| 1917 |
\& |
| 1918 |
if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */ |
| 1919 |
err(EXIT_FAILURE, "waitpid"); |
| 1920 |
printf("child has terminated\[rs]n"); |
| 1921 |
\& |
| 1922 |
exit(EXIT_SUCCESS); |
| 1923 |
} |
| 1924 |
.EE |
| 1925 |
.\" SRC END |
| 1926 |
.SH SEE ALSO |
| 1927 |
.BR fork (2), |
| 1928 |
.BR futex (2), |
| 1929 |
.BR getpid (2), |
| 1930 |
.BR gettid (2), |
| 1931 |
.BR kcmp (2), |
| 1932 |
.BR mmap (2), |
| 1933 |
.BR pidfd_open (2), |
| 1934 |
.BR set_thread_area (2), |
| 1935 |
.BR set_tid_address (2), |
| 1936 |
.BR setns (2), |
| 1937 |
.BR tkill (2), |
| 1938 |
.BR unshare (2), |
| 1939 |
.BR wait (2), |
| 1940 |
.BR capabilities (7), |
| 1941 |
.BR namespaces (7), |
| 1942 |
.BR pthreads (7) |