| blob | 0b97423b8f1794719cce6984ed578722a84c5be8 |
1 .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992
2 .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013
3 .\"
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" May be distributed under the GNU General Public License.
6 .\" %%%LICENSE_END
7 .\"
8 .\" Modified by Michael Haardt <michael@moria.de>
9 .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu>
10 .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
11 .\" New man page (copied from 'fork.2').
12 .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl>
13 .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr>
14 .\" Modified 26 Jun 2001 by Michael Kerrisk
15 .\" Mostly upgraded to 2.4.x
16 .\" Added prototype for sys_clone() plus description
17 .\" Added CLONE_THREAD with a brief description of thread groups
18 .\" Added CLONE_PARENT and revised entire page remove ambiguity
19 .\" between "calling process" and "parent process"
20 .\" Added CLONE_PTRACE and CLONE_VFORK
21 .\" Added EPERM and EINVAL error codes
22 .\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>)
23 .\" various other minor tidy ups and clarifications.
24 .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com>
25 .\" Updated notes for 2.4.7+ behavior of CLONE_THREAD
26 .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
27 .\" Added description for CLONE_NEWNS, which was added in 2.4.19
28 .\" Slightly rephrased, aeb.
29 .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb.
30 .\" Modified 1 Jan 2004 - various updates, aeb
31 .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb.
32 .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid()
33 .\" wrapper under BUGS.
34 .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED.
35 .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD.
36 .\" 2008-11-18, mtk, order CLONE_* flags alphabetically
37 .\" 2008-11-18, mtk, document CLONE_NEWPID
38 .\" 2008-11-19, mtk, document CLONE_NEWUTS
39 .\" 2008-11-19, mtk, document CLONE_NEWIPC
40 .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO
41 .\"
42 .TH CLONE 2 2014-08-19 "Linux" "Linux Programmer's Manual"
43 .SH NAME
44 clone, __clone2 \- create a child process
45 .SH SYNOPSIS
46 .nf
47 /* Prototype for the glibc wrapper function */
49 .B #include <sched.h>
51 .BI "int clone(int (*" "fn" ")(void *), void *" child_stack ,
52 .BI " int " flags ", void *" "arg" ", ... "
53 .BI " /* pid_t *" ptid ", struct user_desc *" tls \
54 ", pid_t *" ctid " */ );"
56 /* Prototype for the raw system call */
58 .BI "long clone(unsigned long " flags ", void *" child_stack ,
59 .BI " void *" ptid ", void *" ctid ,
60 .BI " struct pt_regs *" regs );
61 .fi
62 .sp
63 .in -4n
64 Feature Test Macro Requirements for glibc wrapper function (see
65 .BR feature_test_macros (7)):
66 .in
67 .sp
68 .BR clone ():
69 .ad l
70 .RS 4
71 .PD 0
72 .TP 4
73 Since glibc 2.14:
74 _GNU_SOURCE
75 .TP 4
76 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
77 Before glibc 2.14:
78 _BSD_SOURCE || _SVID_SOURCE
79 /* _GNU_SOURCE also suffices */
80 .PD
81 .RE
82 .ad b
83 .SH DESCRIPTION
84 .BR clone ()
85 creates a new process, in a manner similar to
86 .BR fork (2).
88 This page describes both the glibc
89 .BR clone ()
90 wrapper function and the underlying system call on which it is based.
91 The main text describes the wrapper function;
92 the differences for the raw system call
93 are described toward the end of this page.
95 Unlike
96 .BR fork (2),
97 .BR clone ()
98 allows the child process to share parts of its execution context with
99 the calling process, such as the memory space, the table of file
100 descriptors, and the table of signal handlers.
101 (Note that on this manual
102 page, "calling process" normally corresponds to "parent process".
103 But see the description of
104 .B CLONE_PARENT
105 below.)
107 The main use of
108 .BR clone ()
109 is to implement threads: multiple threads of control in a program that
110 run concurrently in a shared memory space.
112 When the child process is created with
113 .BR clone (),
114 it executes the function
115 .IR fn ( arg ).
116 (This differs from
117 .BR fork (2),
118 where execution continues in the child from the point
119 of the
120 .BR fork (2)
121 call.)
122 The
123 .I fn
124 argument is a pointer to a function that is called by the child
125 process at the beginning of its execution.
126 The
127 .I arg
128 argument is passed to the
129 .I fn
130 function.
132 When the
133 .IR fn ( arg )
134 function application returns, the child process terminates.
135 The integer returned by
136 .I fn
137 is the exit code for the child process.
138 The child process may also terminate explicitly by calling
139 .BR exit (2)
140 or after receiving a fatal signal.
142 The
143 .I child_stack
144 argument specifies the location of the stack used by the child process.
145 Since the child and calling process may share memory,
146 it is not possible for the child process to execute in the
147 same stack as the calling process.
148 The calling process must therefore
149 set up memory space for the child stack and pass a pointer to this
150 space to
151 .BR clone ().
152 Stacks grow downward on all processors that run Linux
153 (except the HP PA processors), so
154 .I child_stack
155 usually points to the topmost address of the memory space set up for
156 the child stack.
158 The low byte of
159 .I flags
160 contains the number of the
161 .I "termination signal"
162 sent to the parent when the child dies.
163 If this signal is specified as anything other than
164 .BR SIGCHLD ,
165 then the parent process must specify the
166 .B __WALL
167 or
168 .B __WCLONE
169 options when waiting for the child with
170 .BR wait (2).
171 If no signal is specified, then the parent process is not signaled
172 when the child terminates.
174 .I flags
175 may also be bitwise-or'ed with zero or more of the following constants,
176 in order to specify what is shared between the calling process
177 and the child process:
178 .TP
179 .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)"
180 Erase child thread ID at location
181 .I ctid
182 in child memory when the child exits, and do a wakeup on the futex
183 at that address.
184 The address involved may be changed by the
185 .BR set_tid_address (2)
186 system call.
187 This is used by threading libraries.
188 .TP
189 .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)"
190 Store child thread ID at location
191 .I ctid
192 in child memory.
193 .TP
194 .BR CLONE_FILES " (since Linux 2.0)"
195 If
196 .B CLONE_FILES
197 is set, the calling process and the child process share the same file
198 descriptor table.
199 Any file descriptor created by the calling process or by the child
200 process is also valid in the other process.
201 Similarly, if one of the processes closes a file descriptor,
202 or changes its associated flags (using the
203 .BR fcntl (2)
204 .B F_SETFD
205 operation), the other process is also affected.
207 If
208 .B CLONE_FILES
209 is not set, the child process inherits a copy of all file descriptors
210 opened in the calling process at the time of
211 .BR clone ().
212 (The duplicated file descriptors in the child refer to the
213 same open file descriptions (see
214 .BR open (2))
215 as the corresponding file descriptors in the calling process.)
216 Subsequent operations that open or close file descriptors,
217 or change file descriptor flags,
218 performed by either the calling
219 process or the child process do not affect the other process.
220 .TP
221 .BR CLONE_FS " (since Linux 2.0)"
222 If
223 .B CLONE_FS
224 is set, the caller and the child process share the same filesystem
225 information.
226 This includes the root of the filesystem, the current
227 working directory, and the umask.
228 Any call to
229 .BR chroot (2),
230 .BR chdir (2),
231 or
232 .BR umask (2)
233 performed by the calling process or the child process also affects the
234 other process.
236 If
237 .B CLONE_FS
238 is not set, the child process works on a copy of the filesystem
239 information of the calling process at the time of the
240 .BR clone ()
241 call.
242 Calls to
243 .BR chroot (2),
244 .BR chdir (2),
245 .BR umask (2)
246 performed later by one of the processes do not affect the other process.
247 .TP
248 .BR CLONE_IO " (since Linux 2.6.25)"
249 If
250 .B CLONE_IO
251 is set, then the new process shares an I/O context with
252 the calling process.
253 If this flag is not set, then (as with
254 .BR fork (2))
255 the new process has its own I/O context.
257 .\" The following based on text from Jens Axboe
258 The I/O context is the I/O scope of the disk scheduler (i.e,
259 what the I/O scheduler uses to model scheduling of a process's I/O).
260 If processes share the same I/O context,
261 they are treated as one by the I/O scheduler.
262 As a consequence, they get to share disk time.
263 For some I/O schedulers,
264 .\" the anticipatory and CFQ scheduler
265 if two processes share an I/O context,
266 they will be allowed to interleave their disk access.
267 If several threads are doing I/O on behalf of the same process
268 .RB ( aio_read (3),
269 for instance), they should employ
270 .BR CLONE_IO
271 to get better I/O performance.
272 .\" with CFQ and AS.
274 If the kernel is not configured with the
275 .B CONFIG_BLOCK
276 option, this flag is a no-op.
277 .TP
278 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
279 If
280 .B CLONE_NEWIPC
281 is set, then create the process in a new IPC namespace.
282 If this flag is not set, then (as with
283 .BR fork (2)),
284 the process is created in the same IPC namespace as
285 the calling process.
286 This flag is intended for the implementation of containers.
288 An IPC namespace provides an isolated view of System\ V IPC objects (see
289 .BR svipc (7))
290 and (since Linux 2.6.30)
291 .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f
292 .\" https://lwn.net/Articles/312232/
293 POSIX message queues
294 (see
295 .BR mq_overview (7)).
296 The common characteristic of these IPC mechanisms is that IPC
297 objects are identified by mechanisms other than filesystem
298 pathnames.
300 Objects created in an IPC namespace are visible to all other processes
301 that are members of that namespace,
302 but are not visible to processes in other IPC namespaces.
304 When an IPC namespace is destroyed
305 (i.e., when the last process that is a member of the namespace terminates),
306 all IPC objects in the namespace are automatically destroyed.
308 Only a privileged process
309 .RB ( CAP_SYS_ADMIN )
310 can employ
311 .BR CLONE_NEWIPC .
312 This flag can't be specified in conjunction with
313 .BR CLONE_SYSVSEM .
315 For further information on IPC namespaces, see
316 .BR namespaces (7).
317 .TP
318 .BR CLONE_NEWNET " (since Linux 2.6.24)"
319 (The implementation of this flag was completed only
320 by about kernel version 2.6.29.)
322 If
323 .B CLONE_NEWNET
324 is set, then create the process in a new network namespace.
325 If this flag is not set, then (as with
326 .BR fork (2))
327 the process is created in the same network namespace as
328 the calling process.
329 This flag is intended for the implementation of containers.
331 A network namespace provides an isolated view of the networking stack
332 (network device interfaces, IPv4 and IPv6 protocol stacks,
333 IP routing tables, firewall rules, the
334 .I /proc/net
335 and
336 .I /sys/class/net
337 directory trees, sockets, etc.).
338 A physical network device can live in exactly one
339 network namespace.
340 A virtual network device ("veth") pair provides a pipe-like abstraction
341 .\" FIXME . Add pointer to veth(4) page when it is eventually completed
342 that can be used to create tunnels between network namespaces,
343 and can be used to create a bridge to a physical network device
344 in another namespace.
346 When a network namespace is freed
347 (i.e., when the last process in the namespace terminates),
348 its physical network devices are moved back to the
349 initial network namespace (not to the parent of the process).
350 For further information on network namespaces, see
351 .BR namespaces (7).
353 Only a privileged process
354 .RB ( CAP_SYS_ADMIN )
355 can employ
356 .BR CLONE_NEWNET .
358 .TP
359 .BR CLONE_NEWNS " (since Linux 2.4.19)"
360 If
361 .B CLONE_NEWNS
362 is set, the cloned child is started in a new mount namespace,
363 initialized with a copy of the namespace of the parent.
364 If
365 .B CLONE_NEWNS
366 is not set, the child lives in the same mount
367 namespace as the parent.
369 For further information on mount namespaces, see
370 .BR namespaces (7).
372 Only a privileged process
373 .RB ( CAP_SYS_ADMIN )
374 can employ
375 .BR CLONE_NEWNS .
376 It is not permitted to specify both
377 .B CLONE_NEWNS
378 and
379 .B CLONE_FS
380 in the same
381 .BR clone ()
382 call.
384 .TP
385 .BR CLONE_NEWPID " (since Linux 2.6.24)"
386 .\" This explanation draws a lot of details from
387 .\" http://lwn.net/Articles/259217/
388 .\" Authors: Pavel Emelyanov <xemul@openvz.org>
389 .\" and Kir Kolyshkin <kir@openvz.org>
390 .\"
391 .\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
392 .\" Author: Pavel Emelyanov <xemul@openvz.org>
393 If
394 .B CLONE_NEWPID
395 is set, then create the process in a new PID namespace.
396 If this flag is not set, then (as with
397 .BR fork (2))
398 the process is created in the same PID namespace as
399 the calling process.
400 This flag is intended for the implementation of containers.
402 For further information on PID namespaces, see
403 .BR namespaces (7).
405 Only a privileged process
406 .RB ( CAP_SYS_ADMIN )
407 can employ
408 .BR CLONE_NEWPID .
409 This flag can't be specified in conjunction with
410 .BR CLONE_THREAD .
412 .TP
413 .BR CLONE_NEWUSER
414 (This flag first became meaningful for
415 .BR clone ()
416 in Linux 2.6.23,
417 the current
418 .BR clone()
419 semantics were merged in Linux 3.5,
420 and the final pieces to make the user namespaces completely usable were
421 merged in Linux 3.8.)
423 If
424 .B CLONE_NEWUSER
425 is set, then create the process in a new user namespace.
426 If this flag is not set, then (as with
427 .BR fork (2))
428 the process is created in the same user namespace as the calling process.
430 For further information on user namespaces, see
431 .BR namespaces (7).
433 Before Linux 3.8, use of
434 .BR CLONE_NEWUSER
435 required that the caller have three capabilities:
436 .BR CAP_SYS_ADMIN ,
437 .BR CAP_SETUID ,
438 and
439 .BR CAP_SETGID .
440 .\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed
441 Starting with Linux 3.8,
442 no privileges are needed to create a user namespace.
444 .TP
445 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
446 If
447 .B CLONE_NEWUTS
448 is set, then create the process in a new UTS namespace,
449 whose identifiers are initialized by duplicating the identifiers
450 from the UTS namespace of the calling process.
451 If this flag is not set, then (as with
452 .BR fork (2))
453 the process is created in the same UTS namespace as
454 the calling process.
455 This flag is intended for the implementation of containers.
457 A UTS namespace is the set of identifiers returned by
458 .BR uname (2);
459 among these, the domain name and the hostname can be modified by
460 .BR setdomainname (2)
461 and
462 .BR sethostname (2),
463 respectively.
464 Changes made to the identifiers in a UTS namespace
465 are visible to all other processes in the same namespace,
466 but are not visible to processes in other UTS namespaces.
468 Only a privileged process
469 .RB ( CAP_SYS_ADMIN )
470 can employ
471 .BR CLONE_NEWUTS .
473 For further information on UTS namespaces, see
474 .BR namespaces (7).
475 .TP
476 .BR CLONE_PARENT " (since Linux 2.3.12)"
477 If
478 .B CLONE_PARENT
479 is set, then the parent of the new child (as returned by
480 .BR getppid (2))
481 will be the same as that of the calling process.
483 If
484 .B CLONE_PARENT
485 is not set, then (as with
486 .BR fork (2))
487 the child's parent is the calling process.
489 Note that it is the parent process, as returned by
490 .BR getppid (2),
491 which is signaled when the child terminates, so that
492 if
493 .B CLONE_PARENT
494 is set, then the parent of the calling process, rather than the
495 calling process itself, will be signaled.
496 .TP
497 .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)"
498 Store child thread ID at location
499 .I ptid
500 in parent and child memory.
501 (In Linux 2.5.32-2.5.48 there was a flag
502 .B CLONE_SETTID
503 that did this.)
504 .TP
505 .BR CLONE_PID " (obsolete)"
506 If
507 .B CLONE_PID
508 is set, the child process is created with the same process ID as
509 the calling process.
510 This is good for hacking the system, but otherwise
511 of not much use.
512 Since 2.3.21 this flag can be
513 specified only by the system boot process (PID 0).
514 It disappeared in Linux 2.5.16.
515 .TP
516 .BR CLONE_PTRACE " (since Linux 2.2)"
517 If
518 .B CLONE_PTRACE
519 is specified, and the calling process is being traced,
520 then trace the child also (see
521 .BR ptrace (2)).
522 .TP
523 .BR CLONE_SETTLS " (since Linux 2.5.32)"
524 The
525 .I newtls
526 argument is the new TLS (Thread Local Storage) descriptor.
527 (See
528 .BR set_thread_area (2).)
529 .TP
530 .BR CLONE_SIGHAND " (since Linux 2.0)"
531 If
532 .B CLONE_SIGHAND
533 is set, the calling process and the child process share the same table of
534 signal handlers.
535 If the calling process or child process calls
536 .BR sigaction (2)
537 to change the behavior associated with a signal, the behavior is
538 changed in the other process as well.
539 However, the calling process and child
540 processes still have distinct signal masks and sets of pending
541 signals.
542 So, one of them may block or unblock some signals using
543 .BR sigprocmask (2)
544 without affecting the other process.
546 If
547 .B CLONE_SIGHAND
548 is not set, the child process inherits a copy of the signal handlers
549 of the calling process at the time
550 .BR clone ()
551 is called.
552 Calls to
553 .BR sigaction (2)
554 performed later by one of the processes have no effect on the other
555 process.
557 Since Linux 2.6.0-test6,
558 .I flags
559 must also include
560 .B CLONE_VM
561 if
562 .B CLONE_SIGHAND
563 is specified
564 .TP
565 .BR CLONE_STOPPED " (since Linux 2.6.0-test2)"
566 If
567 .B CLONE_STOPPED
568 is set, then the child is initially stopped (as though it was sent a
569 .B SIGSTOP
570 signal), and must be resumed by sending it a
571 .B SIGCONT
572 signal.
574 This flag was
575 .I deprecated
576 from Linux 2.6.25 onward,
577 and was
578 .I removed
579 altogether in Linux 2.6.38.
580 .\" glibc 2.8 removed this defn from bits/sched.h
581 .TP
582 .BR CLONE_SYSVSEM " (since Linux 2.5.10)"
583 If
584 .B CLONE_SYSVSEM
585 is set, then the child and the calling process share
586 a single list of System\ V semaphore undo values (see
587 .BR semop (2)).
588 If this flag is not set, then the child has a separate undo list,
589 which is initially empty.
590 .TP
591 .BR CLONE_THREAD " (since Linux 2.4.0-test8)"
592 If
593 .B CLONE_THREAD
594 is set, the child is placed in the same thread group as the calling process.
595 To make the remainder of the discussion of
596 .B CLONE_THREAD
597 more readable, the term "thread" is used to refer to the
598 processes within a thread group.
600 Thread groups were a feature added in Linux 2.4 to support the
601 POSIX threads notion of a set of threads that share a single PID.
602 Internally, this shared PID is the so-called
603 thread group identifier (TGID) for the thread group.
604 Since Linux 2.4, calls to
605 .BR getpid (2)
606 return the TGID of the caller.
608 The threads within a group can be distinguished by their (system-wide)
609 unique thread IDs (TID).
610 A new thread's TID is available as the function result
611 returned to the caller of
612 .BR clone (),
613 and a thread can obtain
614 its own TID using
615 .BR gettid (2).
617 When a call is made to
618 .BR clone ()
619 without specifying
620 .BR CLONE_THREAD ,
621 then the resulting thread is placed in a new thread group
622 whose TGID is the same as the thread's TID.
623 This thread is the
624 .I leader
625 of the new thread group.
627 A new thread created with
628 .B CLONE_THREAD
629 has the same parent process as the caller of
630 .BR clone ()
631 (i.e., like
632 .BR CLONE_PARENT ),
633 so that calls to
634 .BR getppid (2)
635 return the same value for all of the threads in a thread group.
636 When a
637 .B CLONE_THREAD
638 thread terminates, the thread that created it using
639 .BR clone ()
640 is not sent a
641 .B SIGCHLD
642 (or other termination) signal;
643 nor can the status of such a thread be obtained
644 using
645 .BR wait (2).
646 (The thread is said to be
647 .IR detached .)
649 After all of the threads in a thread group terminate
650 the parent process of the thread group is sent a
651 .B SIGCHLD
652 (or other termination) signal.
654 If any of the threads in a thread group performs an
655 .BR execve (2),
656 then all threads other than the thread group leader are terminated,
657 and the new program is executed in the thread group leader.
659 If one of the threads in a thread group creates a child using
660 .BR fork (2),
661 then any thread in the group can
662 .BR wait (2)
663 for that child.
665 Since Linux 2.5.35,
666 .I flags
667 must also include
668 .B CLONE_SIGHAND
669 if
670 .B CLONE_THREAD
671 is specified
672 (and note that, since Linux 2.6.0-test6,
673 .BR CLONE_SIGHAND
674 also requires
675 .BR CLONE_VM
676 to be included).
678 Signals may be sent to a thread group as a whole (i.e., a TGID) using
679 .BR kill (2),
680 or to a specific thread (i.e., TID) using
681 .BR tgkill (2).
683 Signal dispositions and actions are process-wide:
684 if an unhandled signal is delivered to a thread, then
685 it will affect (terminate, stop, continue, be ignored in)
686 all members of the thread group.
688 Each thread has its own signal mask, as set by
689 .BR sigprocmask (2),
690 but signals can be pending either: for the whole process
691 (i.e., deliverable to any member of the thread group),
692 when sent with
693 .BR kill (2);
694 or for an individual thread, when sent with
695 .BR tgkill (2).
696 A call to
697 .BR sigpending (2)
698 returns a signal set that is the union of the signals pending for the
699 whole process and the signals that are pending for the calling thread.
701 If
702 .BR kill (2)
703 is used to send a signal to a thread group,
704 and the thread group has installed a handler for the signal, then
705 the handler will be invoked in exactly one, arbitrarily selected
706 member of the thread group that has not blocked the signal.
707 If multiple threads in a group are waiting to accept the same signal using
708 .BR sigwaitinfo (2),
709 the kernel will arbitrarily select one of these threads
710 to receive a signal sent using
711 .BR kill (2).
712 .TP
713 .BR CLONE_UNTRACED " (since Linux 2.5.46)"
714 If
715 .B CLONE_UNTRACED
716 is specified, then a tracing process cannot force
717 .B CLONE_PTRACE
718 on this child process.
719 .TP
720 .BR CLONE_VFORK " (since Linux 2.2)"
721 If
722 .B CLONE_VFORK
723 is set, the execution of the calling process is suspended
724 until the child releases its virtual memory
725 resources via a call to
726 .BR execve (2)
727 or
728 .BR _exit (2)
729 (as with
730 .BR vfork (2)).
732 If
733 .B CLONE_VFORK
734 is not set, then both the calling process and the child are schedulable
735 after the call, and an application should not rely on execution occurring
736 in any particular order.
737 .TP
738 .BR CLONE_VM " (since Linux 2.0)"
739 If
740 .B CLONE_VM
741 is set, the calling process and the child process run in the same memory
742 space.
743 In particular, memory writes performed by the calling process
744 or by the child process are also visible in the other process.
745 Moreover, any memory mapping or unmapping performed with
746 .BR mmap (2)
747 or
748 .BR munmap (2)
749 by the child or calling process also affects the other process.
751 If
752 .B CLONE_VM
753 is not set, the child process runs in a separate copy of the memory
754 space of the calling process at the time of
755 .BR clone ().
756 Memory writes or file mappings/unmappings performed by one of the
757 processes do not affect the other, as with
758 .BR fork (2).
759 .SS C library/kernel ABI differences
760 The raw
761 .BR clone ()
762 system call corresponds more closely to
763 .BR fork (2)
764 in that execution in the child continues from the point of the
765 call.
766 As such, the
767 .I fn
768 and
769 .I arg
770 arguments of the
771 .BR clone ()
772 wrapper function are omitted.
773 Furthermore, the argument order changes.
774 The raw system call interface on x86 and many other architectures is roughly:
775 .in +4
776 .nf
778 .BI "long clone(unsigned long " flags ", void *" child_stack ,
779 .BI " void *" ptid ", void *" ctid ,
780 .BI " struct pt_regs *" regs );
782 .fi
783 .in
784 Another difference for the raw system call is that the
785 .I child_stack
786 argument may be zero, in which case copy-on-write semantics ensure that the
787 child gets separate copies of stack pages when either process modifies
788 the stack.
789 In this case, for correct operation, the
790 .B CLONE_VM
791 option should not be specified.
793 For some architectures, the order of the arguments for the system call
794 differs from that shown above.
795 On the score, microblaze, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
796 and MIPS architectures,
797 the order of the fourth and fifth arguments is reversed.
798 On the cris and s390 architectures,
799 the order of the first and second arguments is reversed.
800 .SS blackfin, m68k, and sparc
801 The argument-passing conventions on
802 blackfin, m68k, and sparc are different from the descriptions above.
803 For details, see the kernel (and glibc) source.
804 .SS ia64
805 On ia64, a different interface is used:
806 .nf
808 .BI "int __clone2(int (*" "fn" ")(void *), "
809 .BI " void *" child_stack_base ", size_t " stack_size ,
810 .BI " int " flags ", void *" "arg" ", ... "
811 .BI " /* pid_t *" ptid ", struct user_desc *" tls \
812 ", pid_t *" ctid " */ );"
813 .fi
814 .PP
815 The prototype shown above is for the glibc wrapper function;
816 the raw system call interface has no
817 .I fn
818 or
819 .I arg
820 argument, and changes the order of the arguments so that
821 .I flags
822 is the first argument, and
823 .I tls
824 is the last argument.
825 .PP
826 .BR __clone2 ()
827 operates in the same way as
828 .BR clone (),
829 except that
830 .I child_stack_base
831 points to the lowest address of the child's stack area,
832 and
833 .I stack_size
834 specifies the size of the stack pointed to by
835 .IR child_stack_base .
836 .SS Linux 2.4 and earlier
837 In Linux 2.4 and earlier,
838 .BR clone ()
839 does not take arguments
840 .IR ptid ,
841 .IR tls ,
842 and
843 .IR ctid .
844 .SH RETURN VALUE
845 .\" gettid(2) returns current->pid;
846 .\" getpid(2) returns current->tgid;
847 On success, the thread ID of the child process is returned
848 in the caller's thread of execution.
849 On failure, \-1 is returned
850 in the caller's context, no child process will be created, and
851 .I errno
852 will be set appropriately.
853 .SH ERRORS
854 .TP
855 .B EAGAIN
856 Too many processes are already running; see
857 .BR fork (2).
858 .TP
859 .B EINVAL
860 .B CLONE_SIGHAND
861 was specified, but
862 .B CLONE_VM
863 was not.
864 (Since Linux 2.6.0-test6.)
865 .TP
866 .B EINVAL
867 .B CLONE_THREAD
868 was specified, but
869 .B CLONE_SIGHAND
870 was not.
871 (Since Linux 2.5.35.)
872 .\" .TP
873 .\" .B EINVAL
874 .\" Precisely one of
875 .\" .B CLONE_DETACHED
876 .\" and
877 .\" .B CLONE_THREAD
878 .\" was specified.
879 .\" (Since Linux 2.6.0-test6.)
880 .TP
881 .B EINVAL
882 Both
883 .B CLONE_FS
884 and
885 .B CLONE_NEWNS
886 were specified in
887 .IR flags .
888 .TP
889 .B EINVAL
890 Both
891 .B CLONE_NEWIPC
892 and
893 .B CLONE_SYSVSEM
894 were specified in
895 .IR flags .
896 .TP
897 .B EINVAL
898 Both
899 .BR CLONE_NEWPID
900 and
901 .BR CLONE_THREAD
902 were specified in
903 .IR flags .
904 .TP
905 .B EINVAL
906 Returned by
907 .BR clone ()
908 when a zero value is specified for
909 .IR child_stack .
910 .TP
911 .B EINVAL
912 .BR CLONE_NEWIPC
913 was specified in
914 .IR flags ,
915 but the kernel was not configured with the
916 .B CONFIG_SYSVIPC
917 and
918 .BR CONFIG_IPC_NS
919 options.
920 .TP
921 .B EINVAL
922 .BR CLONE_NEWNET
923 was specified in
924 .IR flags ,
925 but the kernel was not configured with the
926 .B CONFIG_NET_NS
927 option.
928 .TP
929 .B EINVAL
930 .BR CLONE_NEWPID
931 was specified in
932 .IR flags ,
933 but the kernel was not configured with the
934 .B CONFIG_PID_NS
935 option.
936 .TP
937 .B EINVAL
938 .BR CLONE_NEWUTS
939 was specified in
940 .IR flags ,
941 but the kernel was not configured with the
942 .B CONFIG_UTS
943 option.
944 .TP
945 .B ENOMEM
946 Cannot allocate sufficient memory to allocate a task structure for the
947 child, or to copy those parts of the caller's context that need to be
948 copied.
949 .TP
950 .B EPERM
951 .BR CLONE_NEWIPC ,
952 .BR CLONE_NEWNET ,
953 .BR CLONE_NEWNS ,
954 .BR CLONE_NEWPID ,
955 or
956 .BR CLONE_NEWUTS
957 was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP).
958 .TP
959 .B EPERM
960 .B CLONE_PID
961 was specified by a process other than process 0.
962 .SH CONFORMING TO
963 .BR clone ()
964 is Linux-specific and should not be used in programs
965 intended to be portable.
966 .SH NOTES
967 In the kernel 2.4.x series,
968 .B CLONE_THREAD
969 generally does not make the parent of the new thread the same
970 as the parent of the calling process.
971 However, for kernel versions 2.4.7 to 2.4.18 the
972 .B CLONE_THREAD
973 flag implied the
974 .B CLONE_PARENT
975 flag (as in kernel 2.6).
977 For a while there was
978 .B CLONE_DETACHED
979 (introduced in 2.5.32):
980 parent wants no child-exit signal.
981 In 2.6.2 the need to give this
982 together with
983 .B CLONE_THREAD
984 disappeared.
985 This flag is still defined, but has no effect.
987 On i386,
988 .BR clone ()
989 should not be called through vsyscall, but directly through
990 .IR "int $0x80" .
991 .SH BUGS
992 Versions of the GNU C library that include the NPTL threading library
993 contain a wrapper function for
994 .BR getpid (2)
995 that performs caching of PIDs.
996 This caching relies on support in the glibc wrapper for
997 .BR clone (),
998 but as currently implemented,
999 the cache may not be up to date in some circumstances.
1000 In particular,
1001 if a signal is delivered to the child immediately after the
1002 .BR clone ()
1003 call, then a call to
1004 .BR getpid (2)
1005 in a handler for the signal may return the PID
1006 of the calling process ("the parent"),
1007 if the clone wrapper has not yet had a chance to update the PID
1008 cache in the child.
1009 (This discussion ignores the case where the child was created using
1010 .BR CLONE_THREAD ,
1011 when
1012 .BR getpid (2)
1013 .I should
1014 return the same value in the child and in the process that called
1015 .BR clone (),
1016 since the caller and the child are in the same thread group.
1017 The stale-cache problem also does not occur if the
1018 .I flags
1019 argument includes
1020 .BR CLONE_VM .)
1021 To get the truth, it may be necessary to use code such as the following:
1022 .nf
1024 #include <syscall.h>
1026 pid_t mypid;
1028 mypid = syscall(SYS_getpid);
1029 .fi
1030 .\" See also the following bug reports
1031 .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
1032 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
1033 .SH EXAMPLE
1034 The following program demonstrates the use of
1035 .BR clone ()
1036 to create a child process that executes in a separate UTS namespace.
1037 The child changes the hostname in its UTS namespace.
1038 Both parent and child then display the system hostname,
1039 making it possible to see that the hostname
1040 differs in the UTS namespaces of the parent and child.
1041 For an example of the use of this program, see
1042 .BR setns (2).
1043 .SS Program source
1044 .nf
1045 #define _GNU_SOURCE
1046 #include <sys/wait.h>
1047 #include <sys/utsname.h>
1048 #include <sched.h>
1049 #include <string.h>
1050 #include <stdio.h>
1051 #include <stdlib.h>
1052 #include <unistd.h>
1054 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
1055 } while (0)
1057 static int /* Start function for cloned child */
1058 childFunc(void *arg)
1059 {
1060 struct utsname uts;
1062 /* Change hostname in UTS namespace of child */
1064 if (sethostname(arg, strlen(arg)) == \-1)
1065 errExit("sethostname");
1067 /* Retrieve and display hostname */
1069 if (uname(&uts) == \-1)
1070 errExit("uname");
1071 printf("uts.nodename in child: %s\\n", uts.nodename);
1073 /* Keep the namespace open for a while, by sleeping.
1074 This allows some experimentation\-\-for example, another
1075 process might join the namespace. */
1077 sleep(200);
1079 return 0; /* Child terminates now */
1080 }
1082 #define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */
1084 int
1085 main(int argc, char *argv[])
1086 {
1087 char *stack; /* Start of stack buffer */
1088 char *stackTop; /* End of stack buffer */
1089 pid_t pid;
1090 struct utsname uts;
1092 if (argc < 2) {
1093 fprintf(stderr, "Usage: %s <child\-hostname>\\n", argv[0]);
1094 exit(EXIT_SUCCESS);
1095 }
1097 /* Allocate stack for child */
1099 stack = malloc(STACK_SIZE);
1100 if (stack == NULL)
1101 errExit("malloc");
1102 stackTop = stack + STACK_SIZE; /* Assume stack grows downward */
1104 /* Create child that has its own UTS namespace;
1105 child commences execution in childFunc() */
1107 pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
1108 if (pid == \-1)
1109 errExit("clone");
1110 printf("clone() returned %ld\\n", (long) pid);
1112 /* Parent falls through to here */
1114 sleep(1); /* Give child time to change its hostname */
1116 /* Display hostname in parent\(aqs UTS namespace. This will be
1117 different from hostname in child\(aqs UTS namespace. */
1119 if (uname(&uts) == \-1)
1120 errExit("uname");
1121 printf("uts.nodename in parent: %s\\n", uts.nodename);
1123 if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */
1124 errExit("waitpid");
1125 printf("child has terminated\\n");
1127 exit(EXIT_SUCCESS);
1128 }
1129 .fi
1130 .SH SEE ALSO
1131 .BR fork (2),
1132 .BR futex (2),
1133 .BR getpid (2),
1134 .BR gettid (2),
1135 .BR kcmp (2),
1136 .BR set_thread_area (2),
1137 .BR set_tid_address (2),
1138 .BR setns (2),
1139 .BR tkill (2),
1140 .BR unshare (2),
1141 .BR wait (2),
1142 .BR proc (5),
1143 .BR capabilities (7),
1144 .BR pthreads (7)