-
Notifications
You must be signed in to change notification settings - Fork 0
/
__clone2.html
1364 lines (1076 loc) · 46.9 KB
/
__clone2.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:52 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>CLONE</title>
</head>
<body>
<h1 align="center">CLONE</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#EXAMPLE">EXAMPLE</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">clone, __clone2
- create a child process</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">/* Prototype
for the glibc wrapper function */</p>
<p style="margin-left:11%; margin-top: 1em"><b>#define
_GNU_SOURCE <br>
#include <sched.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
clone(int (*</b><i>fn</i><b>)(void *), void
*</b><i>child_stack</i><b>, <br>
int</b> <i>flags</i><b>, void *</b><i>arg</i><b>, ... <br>
/* pid_t *</b><i>ptid</i><b>, void *</b><i>newtls</i><b>,
pid_t *</b><i>ctid</i> <b>*/ );</b></p>
<p style="margin-left:11%; margin-top: 1em">/* For the
prototype of the raw system call, see NOTES */</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>clone</b>()
creates a new process, in a manner similar to
<b>fork</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">This page
describes both the glibc <b>clone</b>() wrapper function and
the underlying system call on which it is based. The main
text describes the wrapper function; the differences for the
raw system call are described toward the end of this
page.</p>
<p style="margin-left:11%; margin-top: 1em">Unlike
<b>fork</b>(2), <b>clone</b>() allows the child process to
share parts of its execution context with the calling
process, such as the virtual address space, the table of
file descriptors, and the table of signal handlers. (Note
that on this manual page, "calling process"
normally corresponds to "parent process". But see
the description of <b>CLONE_PARENT</b> below.)</p>
<p style="margin-left:11%; margin-top: 1em">One use of
<b>clone</b>() is to implement threads: multiple flows of
control in a program that run concurrently in a shared
address space.</p>
<p style="margin-left:11%; margin-top: 1em">When the child
process is created with <b>clone</b>(), it commences
execution by calling the function pointed to by the argument
<i>fn</i>. (This differs from <b>fork</b>(2), where
execution continues in the child from the point of the
<b>fork</b>(2) call.) The <i>arg</i> argument is passed as
the argument of the function <i>fn</i>.</p>
<p style="margin-left:11%; margin-top: 1em">When the
<i>fn</i>(<i>arg</i>) function returns, the child process
terminates. The integer returned by <i>fn</i> is the exit
status for the child process. The child process may also
terminate explicitly by calling <b>exit</b>(2) or after
receiving a fatal signal.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>child_stack</i> argument specifies the location of the
stack used by the child process. Since the child and calling
process may share memory, it is not possible for the child
process to execute in the same stack as the calling process.
The calling process must therefore set up memory space for
the child stack and pass a pointer to this space to
<b>clone</b>(). Stacks grow downward on all processors that
run Linux (except the HP PA processors), so
<i>child_stack</i> usually points to the topmost address of
the memory space set up for the child stack.</p>
<p style="margin-left:11%; margin-top: 1em">The low byte of
<i>flags</i> contains the number of the <i>termination
signal</i> sent to the parent when the child dies. If this
signal is specified as anything other than <b>SIGCHLD</b>,
then the parent process must specify the <b>__WALL</b> or
<b>__WCLONE</b> options when waiting for the child with
<b>wait</b>(2). If no signal is specified, then the parent
process is not signaled when the child terminates.</p>
<p style="margin-left:11%; margin-top: 1em"><i>flags</i>
may also be bitwise-ORed with zero or more of the following
constants, in order to specify what is shared between the
calling process and the child process: <b><br>
CLONE_CHILD_CLEARTID</b> (since Linux 2.5.49)</p>
<p style="margin-left:22%;">Clear (zero) the child thread
ID at the location <i>ctid</i> in child memory when the
child exits, and do a wakeup on the futex at that address.
The address involved may be changed by the
<b>set_tid_address</b>(2) system call. This is used by
threading libraries.</p>
<p style="margin-left:11%;"><b>CLONE_CHILD_SETTID</b>
(since Linux 2.5.49)</p>
<p style="margin-left:22%;">Store the child thread ID at
the location <i>ctid</i> in the child’s memory. The
store operation completes before <b>clone</b>() returns
control to user space in the child process. (Note that the
store operation may not have completed before <b>clone</b>()
returns in the parent process, which will be relevant if the
<b>CLONE_VM</b> flag is also employed.)</p>
<p style="margin-left:11%;"><b>CLONE_FILES</b> (since Linux
2.0)</p>
<p style="margin-left:22%;">If <b>CLONE_FILES</b> is set,
the calling process and the child process share the same
file descriptor table. Any file descriptor created by the
calling process or by the child process is also valid in the
other process. Similarly, if one of the processes closes a
file descriptor, or changes its associated flags (using the
<b>fcntl</b>(2) <b>F_SETFD</b> operation), the other process
is also affected. If a process sharing a file descriptor
table calls <b>execve</b>(2), its file descriptor table is
duplicated (unshared).</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_FILES</b> is not set, the child process inherits a
copy of all file descriptors opened in the calling process
at the time of <b>clone</b>(). Subsequent operations that
open or close file descriptors, or change file descriptor
flags, performed by either the calling process or the child
process do not affect the other process. Note, however, that
the duplicated file descriptors in the child refer to the
same open file descriptions as the corresponding file
descriptors in the calling process, and thus share file
offsets and file status flags (see <b>open</b>(2)).</p>
<p style="margin-left:11%;"><b>CLONE_FS</b> (since Linux
2.0)</p>
<p style="margin-left:22%;">If <b>CLONE_FS</b> is set, the
caller and the child process share the same filesystem
information. This includes the root of the filesystem, the
current working directory, and the umask. Any call to
<b>chroot</b>(2), <b>chdir</b>(2), or <b>umask</b>(2)
performed by the calling process or the child process also
affects the other process.</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_FS</b> is not set, the child process works on a
copy of the filesystem information of the calling process at
the time of the <b>clone</b>() call. Calls to
<b>chroot</b>(2), <b>chdir</b>(2), or <b>umask</b>(2)
performed later by one of the processes do not affect the
other process.</p>
<p style="margin-left:11%;"><b>CLONE_IO</b> (since Linux
2.6.25)</p>
<p style="margin-left:22%;">If <b>CLONE_IO</b> is set, then
the new process shares an I/O context with the calling
process. If this flag is not set, then (as with
<b>fork</b>(2)) the new process has its own I/O context.</p>
<p style="margin-left:22%; margin-top: 1em">The I/O context
is the I/O scope of the disk scheduler (i.e., what the I/O
scheduler uses to model scheduling of a process’s
I/O). If processes share the same I/O context, they are
treated as one by the I/O scheduler. As a consequence, they
get to share disk time. For some I/O schedulers, if two
processes share an I/O context, they will be allowed to
interleave their disk access. If several threads are doing
I/O on behalf of the same process (<b>aio_read</b>(3), for
instance), they should employ <b>CLONE_IO</b> to get better
I/O performance.</p>
<p style="margin-left:22%; margin-top: 1em">If the kernel
is not configured with the <b>CONFIG_BLOCK</b> option, this
flag is a no-op.</p>
<p style="margin-left:11%;"><b>CLONE_NEWCGROUP</b> (since
Linux 4.6)</p>
<p style="margin-left:22%;">Create the process in a new
cgroup namespace. If this flag is not set, then (as with
<b>fork</b>(2)) the process is created in the same cgroup
namespaces as the calling process. This flag is intended for
the implementation of containers.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on cgroup namespaces, see
<b>cgroup_namespaces</b>(7).</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWCGROUP</b>.</p>
<p style="margin-left:11%;"><b>CLONE_NEWIPC</b> (since
Linux 2.6.19)</p>
<p style="margin-left:22%;">If <b>CLONE_NEWIPC</b> is set,
then create the process in a new IPC namespace. If this flag
is not set, then (as with <b>fork</b>(2)), the process is
created in the same IPC namespace as the calling process.
This flag is intended for the implementation of
containers.</p>
<p style="margin-left:22%; margin-top: 1em">An IPC
namespace provides an isolated view of System V IPC
objects (see <b>sysvipc</b>(7)) and (since Linux 2.6.30)
POSIX message queues (see <b>mq_overview</b>(7)). The common
characteristic of these IPC mechanisms is that IPC objects
are identified by mechanisms other than filesystem
pathnames.</p>
<p style="margin-left:22%; margin-top: 1em">Objects created
in an IPC namespace are visible to all other processes that
are members of that namespace, but are not visible to
processes in other IPC namespaces.</p>
<p style="margin-left:22%; margin-top: 1em">When an IPC
namespace is destroyed (i.e., when the last process that is
a member of the namespace terminates), all IPC objects in
the namespace are automatically destroyed.</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWIPC</b>. This flag can’t be specified in
conjunction with <b>CLONE_SYSVSEM</b>.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on IPC namespaces, see <b>namespaces</b>(7).</p>
<p style="margin-left:11%;"><b>CLONE_NEWNET</b> (since
Linux 2.6.24)</p>
<p style="margin-left:22%;">(The implementation of this
flag was completed only by about kernel version 2.6.29.)</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_NEWNET</b> is set, then create the process in a new
network namespace. If this flag is not set, then (as with
<b>fork</b>(2)) the process is created in the same network
namespace as the calling process. This flag is intended for
the implementation of containers.</p>
<p style="margin-left:22%; margin-top: 1em">A network
namespace provides an isolated view of the networking stack
(network device interfaces, IPv4 and IPv6 protocol stacks,
IP routing tables, firewall rules, the <i>/proc/net</i> and
<i>/sys/class/net</i> directory trees, sockets, etc.). A
physical network device can live in exactly one network
namespace. A virtual network (<b>veth</b>(4)) device pair
provides a pipe-like abstraction that can be used to create
tunnels between network namespaces, and can be used to
create a bridge to a physical network device in another
namespace.</p>
<p style="margin-left:22%; margin-top: 1em">When a network
namespace is freed (i.e., when the last process in the
namespace terminates), its physical network devices are
moved back to the initial network namespace (not to the
parent of the process). For further information on network
namespaces, see <b>namespaces</b>(7).</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWNET</b>.</p>
<p style="margin-left:11%;"><b>CLONE_NEWNS</b> (since Linux
2.4.19)</p>
<p style="margin-left:22%;">If <b>CLONE_NEWNS</b> is set,
the cloned child is started in a new mount namespace,
initialized with a copy of the namespace of the parent. If
<b>CLONE_NEWNS</b> is not set, the child lives in the same
mount namespace as the parent.</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWNS</b>. It is not permitted to specify both
<b>CLONE_NEWNS</b> and <b>CLONE_FS</b> in the same
<b>clone</b>() call.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on mount namespaces, see <b>namespaces</b>(7)
and <b>mount_namespaces</b>(7).</p>
<p style="margin-left:11%;"><b>CLONE_NEWPID</b> (since
Linux 2.6.24)</p>
<p style="margin-left:22%;">If <b>CLONE_NEWPID</b> is set,
then create the process in a new PID namespace. If this flag
is not set, then (as with <b>fork</b>(2)) the process is
created in the same PID namespace as the calling process.
This flag is intended for the implementation of
containers.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on PID namespaces, see <b>namespaces</b>(7) and
<b>pid_namespaces</b>(7).</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWPID</b>. This flag can’t be specified in
conjunction with <b>CLONE_THREAD</b> or
<b>CLONE_PARENT</b>.</p>
<p style="margin-left:11%;"><b>CLONE_NEWUSER</b></p>
<p style="margin-left:22%;">(This flag first became
meaningful for <b>clone</b>() in Linux 2.6.23, the current
<b>clone</b>() semantics were merged in Linux 3.5, and the
final pieces to make the user namespaces completely usable
were merged in Linux 3.8.)</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_NEWUSER</b> is set, then create the process in a
new user namespace. If this flag is not set, then (as with
<b>fork</b>(2)) the process is created in the same user
namespace as the calling process.</p>
<p style="margin-left:22%; margin-top: 1em">Before Linux
3.8, use of <b>CLONE_NEWUSER</b> required that the caller
have three capabilities: <b>CAP_SYS_ADMIN</b>,
<b>CAP_SETUID</b>, and <b>CAP_SETGID</b>. Starting with
Linux 3.8, no privileges are needed to create a user
namespace.</p>
<p style="margin-left:22%; margin-top: 1em">This flag
can’t be specified in conjunction with
<b>CLONE_THREAD</b> or <b>CLONE_PARENT</b>. For security
reasons, <b>CLONE_NEWUSER</b> cannot be specified in
conjunction with <b>CLONE_FS</b>.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on user namespaces, see <b>namespaces</b>(7) and
<b>user_namespaces</b>(7).</p>
<p style="margin-left:11%;"><b>CLONE_NEWUTS</b> (since
Linux 2.6.19)</p>
<p style="margin-left:22%;">If <b>CLONE_NEWUTS</b> is set,
then create the process in a new UTS namespace, whose
identifiers are initialized by duplicating the identifiers
from the UTS namespace of the calling process. If this flag
is not set, then (as with <b>fork</b>(2)) the process is
created in the same UTS namespace as the calling process.
This flag is intended for the implementation of
containers.</p>
<p style="margin-left:22%; margin-top: 1em">A UTS namespace
is the set of identifiers returned by <b>uname</b>(2); among
these, the domain name and the hostname can be modified by
<b>setdomainname</b>(2) and <b>sethostname</b>(2),
respectively. Changes made to the identifiers in a UTS
namespace are visible to all other processes in the same
namespace, but are not visible to processes in other UTS
namespaces.</p>
<p style="margin-left:22%; margin-top: 1em">Only a
privileged process (<b>CAP_SYS_ADMIN</b>) can employ
<b>CLONE_NEWUTS</b>.</p>
<p style="margin-left:22%; margin-top: 1em">For further
information on UTS namespaces, see <b>namespaces</b>(7).</p>
<p style="margin-left:11%;"><b>CLONE_PARENT</b> (since
Linux 2.3.12)</p>
<p style="margin-left:22%;">If <b>CLONE_PARENT</b> is set,
then the parent of the new child (as returned by
<b>getppid</b>(2)) will be the same as that of the calling
process.</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_PARENT</b> is not set, then (as with
<b>fork</b>(2)) the child’s parent is the calling
process.</p>
<p style="margin-left:22%; margin-top: 1em">Note that it is
the parent process, as returned by <b>getppid</b>(2), which
is signaled when the child terminates, so that if
<b>CLONE_PARENT</b> is set, then the parent of the calling
process, rather than the calling process itself, will be
signaled.</p>
<p style="margin-left:11%;"><b>CLONE_PARENT_SETTID</b>
(since Linux 2.5.49)</p>
<p style="margin-left:22%;">Store the child thread ID at
the location <i>ptid</i> in the parent’s memory. (In
Linux 2.5.32-2.5.48 there was a flag <b>CLONE_SETTID</b>
that did this.) The store operation completes before
<b>clone</b>() returns control to user space.</p>
<p style="margin-left:11%;"><b>CLONE_PID</b> (Linux 2.0 to
2.5.15)</p>
<p style="margin-left:22%;">If <b>CLONE_PID</b> is set, the
child process is created with the same process ID as the
calling process. This is good for hacking the system, but
otherwise of not much use. From Linux 2.3.21 onward, this
flag could be specified only by the system boot process (PID
0). The flag disappeared completely from the kernel sources
in Linux 2.5.16. Since then, the kernel silently ignores
this bit if it is specified in <i>flags</i>.</p>
<p style="margin-left:11%;"><b>CLONE_PTRACE</b> (since
Linux 2.2)</p>
<p style="margin-left:22%;">If <b>CLONE_PTRACE</b> is
specified, and the calling process is being traced, then
trace the child also (see <b>ptrace</b>(2)).</p>
<p style="margin-left:11%;"><b>CLONE_SETTLS</b> (since
Linux 2.5.32)</p>
<p style="margin-left:22%;">The TLS (Thread Local Storage)
descriptor is set to <i>newtls</i>.</p>
<p style="margin-left:22%; margin-top: 1em">The
interpretation of <i>newtls</i> and the resulting effect is
architecture dependent. On x86, <i>newtls</i> is interpreted
as a <i>struct user_desc *</i> (see
<b>set_thread_area</b>(2)). On x86-64 it is the new value to
be set for the %fs base register (see the <b>ARCH_SET_FS</b>
argument to <b>arch_prctl</b>(2)). On architectures with a
dedicated TLS register, it is the new value of that
register.</p>
<p style="margin-left:11%;"><b>CLONE_SIGHAND</b> (since
Linux 2.0)</p>
<p style="margin-left:22%;">If <b>CLONE_SIGHAND</b> is set,
the calling process and the child process share the same
table of signal handlers. If the calling process or child
process calls <b>sigaction</b>(2) to change the behavior
associated with a signal, the behavior is changed in the
other process as well. However, the calling process and
child processes still have distinct signal masks and sets of
pending signals. So, one of them may block or unblock
signals using <b>sigprocmask</b>(2) without affecting the
other process.</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_SIGHAND</b> is not set, the child process inherits
a copy of the signal handlers of the calling process at the
time <b>clone</b>() is called. Calls to <b>sigaction</b>(2)
performed later by one of the processes have no effect on
the other process.</p>
<p style="margin-left:22%; margin-top: 1em">Since Linux
2.6.0, <i>flags</i> must also include <b>CLONE_VM</b> if
<b>CLONE_SIGHAND</b> is specified</p>
<p style="margin-left:11%;"><b>CLONE_STOPPED</b> (since
Linux 2.6.0)</p>
<p style="margin-left:22%;">If <b>CLONE_STOPPED</b> is set,
then the child is initially stopped (as though it was sent a
<b>SIGSTOP</b> signal), and must be resumed by sending it a
<b>SIGCONT</b> signal.</p>
<p style="margin-left:22%; margin-top: 1em">This flag was
<i>deprecated</i> from Linux 2.6.25 onward, and was
<i>removed</i> altogether in Linux 2.6.38. Since then, the
kernel silently ignores it without error. Starting with
Linux 4.6, the same bit was reused for the
<b>CLONE_NEWCGROUP</b> flag.</p>
<p style="margin-left:11%;"><b>CLONE_SYSVSEM</b> (since
Linux 2.5.10)</p>
<p style="margin-left:22%;">If <b>CLONE_SYSVSEM</b> is set,
then the child and the calling process share a single list
of System V semaphore adjustment (<i>semadj</i>) values (see
<b>semop</b>(2)). In this case, the shared list accumulates
<i>semadj</i> values across all processes sharing the list,
and semaphore adjustments are performed only when the last
process that is sharing the list terminates (or ceases
sharing the list using <b>unshare</b>(2)). If this flag is
not set, then the child has a separate <i>semadj</i> list
that is initially empty.</p>
<p style="margin-left:11%;"><b>CLONE_THREAD</b> (since
Linux 2.4.0)</p>
<p style="margin-left:22%;">If <b>CLONE_THREAD</b> is set,
the child is placed in the same thread group as the calling
process. To make the remainder of the discussion of
<b>CLONE_THREAD</b> more readable, the term
"thread" is used to refer to the processes within
a thread group.</p>
<p style="margin-left:22%; margin-top: 1em">Thread groups
were a feature added in Linux 2.4 to support the POSIX
threads notion of a set of threads that share a single PID.
Internally, this shared PID is the so-called thread group
identifier (TGID) for the thread group. Since Linux 2.4,
calls to <b>getpid</b>(2) return the TGID of the caller.</p>
<p style="margin-left:22%; margin-top: 1em">The threads
within a group can be distinguished by their (system-wide)
unique thread IDs (TID). A new thread’s TID is
available as the function result returned to the caller of
<b>clone</b>(), and a thread can obtain its own TID using
<b>gettid</b>(2).</p>
<p style="margin-left:22%; margin-top: 1em">When a call is
made to <b>clone</b>() without specifying
<b>CLONE_THREAD</b>, then the resulting thread is placed in
a new thread group whose TGID is the same as the
thread’s TID. This thread is the <i>leader</i> of the
new thread group.</p>
<p style="margin-left:22%; margin-top: 1em">A new thread
created with <b>CLONE_THREAD</b> has the same parent process
as the caller of <b>clone</b>() (i.e., like
<b>CLONE_PARENT</b>), so that calls to <b>getppid</b>(2)
return the same value for all of the threads in a thread
group. When a <b>CLONE_THREAD</b> thread terminates, the
thread that created it using <b>clone</b>() is not sent a
<b>SIGCHLD</b> (or other termination) signal; nor can the
status of such a thread be obtained using <b>wait</b>(2).
(The thread is said to be <i>detached</i>.)</p>
<p style="margin-left:22%; margin-top: 1em">After all of
the threads in a thread group terminate the parent process
of the thread group is sent a <b>SIGCHLD</b> (or other
termination) signal.</p>
<p style="margin-left:22%; margin-top: 1em">If any of the
threads in a thread group performs an <b>execve</b>(2), then
all threads other than the thread group leader are
terminated, and the new program is executed in the thread
group leader.</p>
<p style="margin-left:22%; margin-top: 1em">If one of the
threads in a thread group creates a child using
<b>fork</b>(2), then any thread in the group can
<b>wait</b>(2) for that child.</p>
<p style="margin-left:22%; margin-top: 1em">Since Linux
2.5.35, <i>flags</i> must also include <b>CLONE_SIGHAND</b>
if <b>CLONE_THREAD</b> is specified (and note that, since
Linux 2.6.0, <b>CLONE_SIGHAND</b> also requires
<b>CLONE_VM</b> to be included).</p>
<p style="margin-left:22%; margin-top: 1em">Signal
dispositions and actions are process-wide: if an unhandled
signal is delivered to a thread, then it will affect
(terminate, stop, continue, be ignored in) all members of
the thread group.</p>
<p style="margin-left:22%; margin-top: 1em">Each thread has
its own signal mask, as set by <b>sigprocmask</b>(2).</p>
<p style="margin-left:22%; margin-top: 1em">A signal may be
process-directed or thread-directed. A process-directed
signal is targeted at a thread group (i.e., a TGID), and is
delivered to an arbitrarily selected thread from among those
that are not blocking the signal. A signal may be process
directed because it was generated by the kernel for reasons
other than a hardware exception, or because it was sent
using <b>kill</b>(2) or <b>sigqueue</b>(3). A
thread-directed signal is targeted at (i.e., delivered to) a
specific thread. A signal may be thread directed because it
was sent using <b>tgkill</b>(2) or
<b>pthread_sigqueue</b>(3), or because the thread executed a
machine language instruction that triggered a hardware
exception (e.g., invalid memory access triggering
<b>SIGSEGV</b> or a floating-point exception triggering
<b>SIGFPE</b>).</p>
<p style="margin-left:22%; margin-top: 1em">A call to
<b>sigpending</b>(2) returns a signal set that is the union
of the pending process-directed signals and the signals that
are pending for the calling thread.</p>
<p style="margin-left:22%; margin-top: 1em">If a
process-directed signal is delivered to a thread group, and
the thread group has installed a handler for the signal,
then the handler will be invoked in exactly one, arbitrarily
selected member of the thread group that has not blocked the
signal. If multiple threads in a group are waiting to accept
the same signal using <b>sigwaitinfo</b>(2), the kernel will
arbitrarily select one of these threads to receive the
signal.</p>
<p style="margin-left:11%;"><b>CLONE_UNTRACED</b> (since
Linux 2.5.46)</p>
<p style="margin-left:22%;">If <b>CLONE_UNTRACED</b> is
specified, then a tracing process cannot force
<b>CLONE_PTRACE</b> on this child process.</p>
<p style="margin-left:11%;"><b>CLONE_VFORK</b> (since Linux
2.2)</p>
<p style="margin-left:22%;">If <b>CLONE_VFORK</b> is set,
the execution of the calling process is suspended until the
child releases its virtual memory resources via a call to
<b>execve</b>(2) or <b>_exit</b>(2) (as with
<b>vfork</b>(2)).</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_VFORK</b> is not set, then both the calling process
and the child are schedulable after the call, and an
application should not rely on execution occurring in any
particular order.</p>
<p style="margin-left:11%;"><b>CLONE_VM</b> (since Linux
2.0)</p>
<p style="margin-left:22%;">If <b>CLONE_VM</b> is set, the
calling process and the child process run in the same memory
space. In particular, memory writes performed by the calling
process or by the child process are also visible in the
other process. Moreover, any memory mapping or unmapping
performed with <b>mmap</b>(2) or <b>munmap</b>(2) by the
child or calling process also affects the other process.</p>
<p style="margin-left:22%; margin-top: 1em">If
<b>CLONE_VM</b> is not set, the child process runs in a
separate copy of the memory space of the calling process at
the time of <b>clone</b>(). Memory writes or file
mappings/unmappings performed by one of the processes do not
affect the other, as with <b>fork</b>(2).</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Note that the
glibc <b>clone</b>() wrapper function makes some changes in
the memory pointed to by <i>child_stack</i> (changes
required to set the stack up correctly for the child)
<i>before</i> invoking the <b>clone</b>() system call. So,
in cases where <b>clone</b>() is used to recursively create
children, do not use the buffer employed for the
parent’s stack as the stack of the child.</p>
<p style="margin-left:11%; margin-top: 1em"><b>C
library/kernel differences</b> <br>
The raw <b>clone</b>() system call corresponds more closely
to <b>fork</b>(2) in that execution in the child continues
from the point of the call. As such, the <i>fn</i> and
<i>arg</i> arguments of the <b>clone</b>() wrapper function
are omitted.</p>
<p style="margin-left:11%; margin-top: 1em">Another
difference for the raw <b>clone</b>() system call is that
the <i>child_stack</i> argument may be NULL, in which case
the child uses a duplicate of the parent’s stack.
(Copy-on-write semantics ensure that the child gets separate
copies of stack pages when either process modifies the
stack.) In this case, for correct operation, the
<b>CLONE_VM</b> option should not be specified. (If the
child <i>shares</i> the parent’s memory because of the
use of the <b>CLONE_VM</b> flag, then no copy-on-write
duplication occurs and chaos is likely to result.)</p>
<p style="margin-left:11%; margin-top: 1em">The order of
the arguments also differs in the raw system call, and there
are variations in the arguments across architectures, as
detailed in the following paragraphs.</p>
<p style="margin-left:11%; margin-top: 1em">The raw system
call interface on x86-64 and some other architectures
(including sh, tile, ia-64, and alpha) is:</p>
<p style="margin-left:17%; margin-top: 1em"><b>long
clone(unsigned long</b> <i>flags</i><b>, void
*</b><i>child_stack</i><b>, <br>
int *</b><i>ptid</i><b>, int *</b><i>ctid</i><b>, <br>
unsigned long</b> <i>newtls</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em">On x86-32, and
several other common architectures (including score, ARM,
ARM 64, PA-RISC, arc, Power PC, xtensa, and MIPS), the order
of the last two arguments is reversed:</p>
<p style="margin-left:17%; margin-top: 1em"><b>long
clone(unsigned long</b> <i>flags</i><b>, void
*</b><i>child_stack</i><b>, <br>
int *</b><i>ptid</i><b>, unsigned long</b> <i>newtls</i><b>,
<br>
int *</b><i>ctid</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em">On the cris and
s390 architectures, the order of the first two arguments is
reversed:</p>
<p style="margin-left:17%; margin-top: 1em"><b>long
clone(void *</b><i>child_stack</i><b>, unsigned long</b>
<i>flags</i><b>, <br>
int *</b><i>ptid</i><b>, int *</b><i>ctid</i><b>, <br>
unsigned long</b> <i>newtls</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em">On the
microblaze architecture, an additional argument is
supplied:</p>
<p style="margin-left:17%; margin-top: 1em"><b>long
clone(unsigned long</b> <i>flags</i><b>, void
*</b><i>child_stack</i><b>, <br>
int</b> <i>stack_size</i><b>,</b> /* Size of stack */
<b><br>
int *</b><i>ptid</i><b>, int *</b><i>ctid</i><b>, <br>
unsigned long</b> <i>newtls</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>blackfin,
m68k, and sparc</b> <br>
The argument-passing conventions on blackfin, m68k, and
sparc are different from the descriptions above. For
details, see the kernel (and glibc) source.</p>
<p style="margin-left:11%; margin-top: 1em"><b>ia64</b>
<br>
On ia64, a different interface is used:</p>
<p style="margin-left:17%; margin-top: 1em"><b>int
__clone2(int (*</b><i>fn</i><b>)(void *), <br>
void *</b><i>child_stack_base</i><b>, size_t</b>
<i>stack_size</i><b>, <br>
int</b> <i>flags</i><b>, void *</b><i>arg</i><b>, ... <br>
/* pid_t *</b><i>ptid</i><b>, struct user_desc
*</b><i>tls</i><b>, pid_t *</b><i>ctid</i> <b>*/ );</b></p>
<p style="margin-left:11%; margin-top: 1em">The prototype
shown above is for the glibc wrapper function; for the
system call itself, the prototype can be described as
follows (it is identical to the <b>clone</b>() prototype on
microblaze):</p>
<p style="margin-left:17%; margin-top: 1em"><b>long
clone2(unsigned long</b> <i>flags</i><b>, void
*</b><i>child_stack_base</i><b>, <br>
int</b> <i>stack_size</i><b>,</b> /* Size of stack */
<b><br>
int *</b><i>ptid</i><b>, int *</b><i>ctid</i><b>, <br>
unsigned long</b> <i>tls</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>__clone2</b>()
operates in the same way as <b>clone</b>(), except that
<i>child_stack_base</i> points to the lowest address of the
child’s stack area, and <i>stack_size</i> specifies
the size of the stack pointed to by
<i>child_stack_base</i>.</p>
<p style="margin-left:11%; margin-top: 1em"><b>Linux 2.4
and earlier</b> <br>
In Linux 2.4 and earlier, <b>clone</b>() does not take
arguments <i>ptid</i>, <i>tls</i>, and <i>ctid</i>.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success, the
thread ID of the child process is returned in the
caller’s thread of execution. On failure, -1 is
returned in the caller’s context, no child process
will be created, and <i>errno</i> will be set
appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">Too many processes are already
running; see <b>fork</b>(2).</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_SIGHAND</b> was specified, but <b>CLONE_VM</b>
was not. (Since Linux 2.6.0.)</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_THREAD</b> was specified, but
<b>CLONE_SIGHAND</b> was not. (Since Linux 2.5.35.)</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_THREAD</b> was specified, but the current
process previously called <b>unshare</b>(2) with the
<b>CLONE_NEWPID</b> flag or used <b>setns</b>(2) to
reassociate itself with a PID namespace.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Both <b>CLONE_FS</b> and <b>CLONE_NEWNS</b> were
specified in <i>flags</i>.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>EINVAL</b> (since Linux
3.9)</p>
<p style="margin-left:22%;">Both <b>CLONE_NEWUSER</b> and
<b>CLONE_FS</b> were specified in <i>flags</i>.</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Both <b>CLONE_NEWIPC</b> and <b>CLONE_SYSVSEM</b> were
specified in <i>flags</i>.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>One (or both) of <b>CLONE_NEWPID</b> or
<b>CLONE_NEWUSER</b> and one (or both) of
<b>CLONE_THREAD</b> or <b>CLONE_PARENT</b> were specified in
<i>flags</i>.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>Returned by the glibc <b>clone</b>() wrapper function
when <i>fn</i> or <i>child_stack</i> is specified as
NULL.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_NEWIPC</b> was specified in <i>flags</i>, but
the kernel was not configured with the <b>CONFIG_SYSVIPC</b>
and <b>CONFIG_IPC_NS</b> options.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_NEWNET</b> was specified in <i>flags</i>, but
the kernel was not configured with the <b>CONFIG_NET_NS</b>
option.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_NEWPID</b> was specified in <i>flags</i>, but
the kernel was not configured with the <b>CONFIG_PID_NS</b>
option.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_NEWUSER</b> was specified in <i>flags</i>, but
the kernel was not configured with the <b>CONFIG_USER_NS</b>
option.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>CLONE_NEWUTS</b> was specified in <i>flags</i>, but
the kernel was not configured with the <b>CONFIG_UTS_NS</b>
option.</p> </td></tr>