1CLONE(2)                   Linux Programmer's Manual                  CLONE(2)
2
3
4

NAME

6       clone, __clone2 - create a child process
7

SYNOPSIS

9       /* Prototype for the glibc wrapper function */
10
11       #include <sched.h>
12
13       int clone(int (*fn)(void *), void *child_stack,
14                 int flags, void *arg, ...
15                 /* pid_t *ptid, struct user_desc *tls, pid_t *ctid */ );
16
17       /* Prototype for the raw system call */
18
19       long clone(unsigned long flags, void *child_stack,
20                 void *ptid, void *ctid,
21                 struct pt_regs *regs);
22
23   Feature  Test  Macro  Requirements  for  glibc  wrapper  function (see fea‐
24   ture_test_macros(7)):
25
26       clone():
27           Since glibc 2.14:
28               _GNU_SOURCE
29           Before glibc 2.14:
30               _BSD_SOURCE || _SVID_SOURCE
31                   /* _GNU_SOURCE also suffices */
32

DESCRIPTION

34       clone() creates a new process, in a manner similar to fork(2).
35
36       This page describes both the glibc clone()  wrapper  function  and  the
37       underlying  system  call on which it is based.  The main text describes
38       the wrapper function; the differences  for  the  raw  system  call  are
39       described toward the end of this page.
40
41       Unlike  fork(2), clone() allows the child process to share parts of its
42       execution context with the calling process, such as the  memory  space,
43       the table of file descriptors, and the table of signal handlers.  (Note
44       that on this manual page, "calling  process"  normally  corresponds  to
45       "parent process".  But see the description of CLONE_PARENT below.)
46
47       The  main  use  of clone() is to implement threads: multiple threads of
48       control in a program that run concurrently in a shared memory space.
49
50       When the child process is created with clone(), it executes  the  func‐
51       tion fn(arg).  (This differs from fork(2), where execution continues in
52       the child from the point of the fork(2) call.)  The fn  argument  is  a
53       pointer to a function that is called by the child process at the begin‐
54       ning of its execution.  The arg argument is passed to the fn function.
55
56       When the fn(arg) function application returns, the child process termi‐
57       nates.   The  integer  returned  by  fn  is the exit code for the child
58       process.  The child process may also terminate  explicitly  by  calling
59       exit(2) or after receiving a fatal signal.
60
61       The  child_stack  argument  specifies the location of the stack used by
62       the child process.  Since the child and calling process may share  mem‐
63       ory,  it  is  not possible for the child process to execute in the same
64       stack as the calling process.  The calling process must  therefore  set
65       up memory space for the child stack and pass a pointer to this space to
66       clone().  Stacks grow downward on all processors that run Linux (except
67       the  HP  PA  processors),  so child_stack usually points to the topmost
68       address of the memory space set up for the child stack.
69
70       The low byte of flags contains the number  of  the  termination  signal
71       sent to the parent when the child dies.  If this signal is specified as
72       anything other than SIGCHLD, then the parent process must  specify  the
73       __WALL or __WCLONE options when waiting for the child with wait(2).  If
74       no signal is specified, then the parent process is  not  signaled  when
75       the child terminates.
76
77       flags may also be bitwise-or'ed with zero or more of the following con‐
78       stants, in order to specify what is shared between the calling  process
79       and the child process:
80
81       CLONE_CHILD_CLEARTID (since Linux 2.5.49)
82              Erase  child thread ID at location ctid in child memory when the
83              child exits, and do a wakeup on the futex at that address.   The
84              address involved may be changed by the set_tid_address(2) system
85              call.  This is used by threading libraries.
86
87       CLONE_CHILD_SETTID (since Linux 2.5.49)
88              Store child thread ID at location ctid in child memory.
89
90       CLONE_FILES (since Linux 2.0)
91              If CLONE_FILES is set, the calling process and the child process
92              share  the same file descriptor table.  Any file descriptor cre‐
93              ated by the calling process or by  the  child  process  is  also
94              valid  in the other process.  Similarly, if one of the processes
95              closes a file descriptor, or changes its associated flags (using
96              the  fcntl(2)  F_SETFD  operation),  the  other  process is also
97              affected.
98
99              If CLONE_FILES is not set, the child process inherits a copy  of
100              all  file  descriptors opened in the calling process at the time
101              of clone().  (The duplicated file descriptors in the child refer
102              to  the  same open file descriptions (see open(2)) as the corre‐
103              sponding file descriptors in the calling  process.)   Subsequent
104              operations  that  open or close file descriptors, or change file
105              descriptor flags, performed by either the calling process or the
106              child process do not affect the other process.
107
108       CLONE_FS (since Linux 2.0)
109              If  CLONE_FS  is set, the caller and the child process share the
110              same file system information.  This includes  the  root  of  the
111              file  system, the current working directory, and the umask.  Any
112              call to chroot(2), chdir(2), or umask(2) performed by the  call‐
113              ing process or the child process also affects the other process.
114
115              If CLONE_FS is not set, the child process works on a copy of the
116              file system information of the calling process at  the  time  of
117              the  clone()  call.  Calls to chroot(2), chdir(2), umask(2) per‐
118              formed later by one of the processes do  not  affect  the  other
119              process.
120
121       CLONE_IO (since Linux 2.6.25)
122              If  CLONE_IO  is set, then the new process shares an I/O context
123              with the calling process.  If this flag is  not  set,  then  (as
124              with fork(2)) the new process has its own I/O context.
125
126              The  I/O  context  is  the I/O scope of the disk scheduler (i.e,
127              what the I/O scheduler uses to model scheduling of  a  process's
128              I/O).  If processes share the same I/O context, they are treated
129              as one by the I/O scheduler.  As  a  consequence,  they  get  to
130              share  disk  time.   For  some  I/O schedulers, if two processes
131              share an I/O context, they will be allowed to  interleave  their
132              disk  access.  If several threads are doing I/O on behalf of the
133              same process (aio_read(3), for  instance),  they  should  employ
134              CLONE_IO to get better I/O performance.
135
136              If  the  kernel  is not configured with the CONFIG_BLOCK option,
137              this flag is a no-op.
138
139       CLONE_NEWIPC (since Linux 2.6.19)
140              If CLONE_NEWIPC is set, then create the process  in  a  new  IPC
141              namespace.  If this flag is not set, then (as with fork(2)), the
142              process is created in the same  IPC  namespace  as  the  calling
143              process.   This  flag is intended for the implementation of con‐
144              tainers.
145
146              An IPC namespace provides an  isolated  view  of  System  V  IPC
147              objects  (see  svipc(7))  and (since Linux 2.6.30) POSIX message
148              queues (see mq_overview(7)).  The common characteristic of these
149              IPC  mechanisms is that IPC objects are identified by mechanisms
150              other than filesystem pathnames.
151
152              Objects created in an IPC namespace are  visible  to  all  other
153              processes  that are members of that namespace, but are not visi‐
154              ble to processes in other IPC namespaces.
155
156              When an IPC namespace is destroyed (i.e., when the last  process
157              that  is  a member of the namespace terminates), all IPC objects
158              in the namespace are automatically destroyed.
159
160              Use of this flag requires: a kernel  configured  with  the  CON‐
161              FIG_SYSVIPC  and  CONFIG_IPC_NS  options and that the process be
162              privileged (CAP_SYS_ADMIN).  This flag  can't  be  specified  in
163              conjunction with CLONE_SYSVSEM.
164
165       CLONE_NEWNET (since Linux 2.6.24)
166              (The  implementation  of  this  flag was completed only by about
167              kernel version 2.6.29.)
168
169              If CLONE_NEWNET is set, then create the process in a new network
170              namespace.  If this flag is not set, then (as with fork(2)), the
171              process is created in the same network namespace as the  calling
172              process.   This  flag is intended for the implementation of con‐
173              tainers.
174
175              A network namespace provides an isolated view of the  networking
176              stack (network device interfaces, IPv4 and IPv6 protocol stacks,
177              IP  routing  tables,   firewall   rules,   the   /proc/net   and
178              /sys/class/net directory trees, sockets, etc.).  A physical net‐
179              work device can live in exactly one network namespace.   A  vir‐
180              tual  network device ("veth") pair provides a pipe-like abstrac‐
181              tion that can be used to create tunnels between  network  names‐
182              paces,  and can be used to create a bridge to a physical network
183              device in another namespace.
184
185              When a network namespace is freed (i.e., when the  last  process
186              in  the  namespace terminates), its physical network devices are
187              moved back to the initial network namespace (not to  the  parent
188              of the process).
189
190              Use  of  this  flag  requires: a kernel configured with the CON‐
191              FIG_NET_NS  option  and   that   the   process   be   privileged
192              (CAP_SYS_ADMIN).
193
194       CLONE_NEWNS (since Linux 2.4.19)
195              Start the child in a new mount namespace.
196
197              Every  process  lives  in a mount namespace.  The namespace of a
198              process is the data (the set  of  mounts)  describing  the  file
199              hierarchy  as  seen by that process.  After a fork(2) or clone()
200              where the CLONE_NEWNS flag is not set, the child  lives  in  the
201              same  mount  namespace as the parent.  The system calls mount(2)
202              and umount(2) change the mount namespace of the calling process,
203              and  hence affect all processes that live in the same namespace,
204              but do not affect processes in a different mount namespace.
205
206              After a clone() where the CLONE_NEWNS flag is  set,  the  cloned
207              child  is  started  in a new mount namespace, initialized with a
208              copy of the namespace of the parent.
209
210              Only a privileged process (one having the CAP_SYS_ADMIN capabil‐
211              ity)  may  specify the CLONE_NEWNS flag.  It is not permitted to
212              specify both CLONE_NEWNS and CLONE_FS in the same clone() call.
213
214       CLONE_NEWPID (since Linux 2.6.24)
215              If CLONE_NEWPID is set, then create the process  in  a  new  PID
216              namespace.  If this flag is not set, then (as with fork(2)), the
217              process is created in the same  PID  namespace  as  the  calling
218              process.   This  flag is intended for the implementation of con‐
219              tainers.
220
221              A PID namespace provides an isolated environment for PIDs:  PIDs
222              in  a  new namespace start at 1, somewhat like a standalone sys‐
223              tem, and calls to fork(2), vfork(2),  or  clone()  will  produce
224              processes with PIDs that are unique within the namespace.
225
226              The  first process created in a new namespace (i.e., the process
227              created using the CLONE_NEWPID flag) has the PID 1, and  is  the
228              "init"  process  for  the namespace.  Children that are orphaned
229              within the namespace will be reparented to this  process  rather
230              than  init(8).   Unlike the traditional init process, the "init"
231              process of a PID namespace can terminate, and if it does, all of
232              the processes in the namespace are terminated.
233
234              PID  namespaces  form  a hierarchy.  When a new PID namespace is
235              created, the processes in that namespace are visible in the  PID
236              namespace  of the process that created the new namespace; analo‐
237              gously, if the parent PID  namespace  is  itself  the  child  of
238              another  PID  namespace,  then processes in the child and parent
239              PID namespaces will both  be  visible  in  the  grandparent  PID
240              namespace.   Conversely, the processes in the "child" PID names‐
241              pace do not see the processes  in  the  parent  namespace.   The
242              existence  of  a namespace hierarchy means that each process may
243              now have multiple PIDs: one for each namespace in  which  it  is
244              visible;  each  of these PIDs is unique within the corresponding
245              namespace.  (A call to getpid(2) always returns the PID  associ‐
246              ated with the namespace in which the process lives.)
247
248              After  creating the new namespace, it is useful for the child to
249              change its root directory and mount a  new  procfs  instance  at
250              /proc   so  that  tools  such  as  ps(1)  work  correctly.   (If
251              CLONE_NEWNS is also included in flags, then it  isn't  necessary
252              to  change  the  root  directory:  a  new procfs instance can be
253              mounted directly over /proc.)
254
255              Use of this flag requires: a kernel  configured  with  the  CON‐
256              FIG_PID_NS   option   and   that   the   process  be  privileged
257              (CAP_SYS_ADMIN).  This flag can't be  specified  in  conjunction
258              with CLONE_THREAD.
259
260       CLONE_NEWUTS (since Linux 2.6.19)
261              If  CLONE_NEWUTS  is  set,  then create the process in a new UTS
262              namespace, whose identifiers are initialized by duplicating  the
263              identifiers  from  the UTS namespace of the calling process.  If
264              this flag is not set, then (as with  fork(2)),  the  process  is
265              created  in the same UTS namespace as the calling process.  This
266              flag is intended for the implementation of containers.
267
268              A UTS namespace is the set of identifiers returned by  uname(2);
269              among  these,  the domain name and the host name can be modified
270              by setdomainname(2) and  sethostname(2), respectively.   Changes
271              made  to  the  identifiers in a UTS namespace are visible to all
272              other processes in the same namespace, but are  not  visible  to
273              processes in other UTS namespaces.
274
275              Use  of  this  flag  requires: a kernel configured with the CON‐
276              FIG_UTS_NS  option  and   that   the   process   be   privileged
277              (CAP_SYS_ADMIN).
278
279       CLONE_PARENT (since Linux 2.3.12)
280              If  CLONE_PARENT  is  set,  then the parent of the new child (as
281              returned by getppid(2)) will be the same as that of the  calling
282              process.
283
284              If  CLONE_PARENT  is not set, then (as with fork(2)) the child's
285              parent is the calling process.
286
287              Note that it is the parent process, as returned  by  getppid(2),
288              which  is  signaled  when  the  child  terminates,  so  that  if
289              CLONE_PARENT is set, then the parent  of  the  calling  process,
290              rather than the calling process itself, will be signaled.
291
292       CLONE_PARENT_SETTID (since Linux 2.5.49)
293              Store  child thread ID at location ptid in parent and child mem‐
294              ory.  (In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that
295              did this.)
296
297       CLONE_PID (obsolete)
298              If  CLONE_PID is set, the child process is created with the same
299              process ID as the calling process.  This is good for hacking the
300              system,  but  otherwise of not much use.  Since 2.3.21 this flag
301              can be specified only by the system boot process  (PID  0).   It
302              disappeared in Linux 2.5.16.
303
304       CLONE_PTRACE (since Linux 2.2)
305              If  CLONE_PTRACE  is specified, and the calling process is being
306              traced, then trace the child also (see ptrace(2)).
307
308       CLONE_SETTLS (since Linux 2.5.32)
309              The newtls argument  is  the  new  TLS  (Thread  Local  Storage)
310              descriptor.  (See set_thread_area(2).)
311
312       CLONE_SIGHAND (since Linux 2.0)
313              If  CLONE_SIGHAND  is  set,  the  calling  process and the child
314              process share the same table of signal handlers.  If the calling
315              process or child process calls sigaction(2) to change the behav‐
316              ior associated with a signal, the behavior  is  changed  in  the
317              other  process  as well.  However, the calling process and child
318              processes still have distinct signal masks and sets  of  pending
319              signals.   So,  one  of  them  may block or unblock some signals
320              using sigprocmask(2) without affecting the other process.
321
322              If CLONE_SIGHAND is not set, the child process inherits  a  copy
323              of  the  signal  handlers  of  the  calling  process at the time
324              clone() is called.  Calls to sigaction(2) performed later by one
325              of the processes have no effect on the other process.
326
327              Since  Linux  2.6.0-test6,  flags  must also include CLONE_VM if
328              CLONE_SIGHAND is specified
329
330       CLONE_STOPPED (since Linux 2.6.0-test2)
331              If CLONE_STOPPED is set, then the child is initially stopped (as
332              though  it  was  sent  a SIGSTOP signal), and must be resumed by
333              sending it a SIGCONT signal.
334
335              This flag was deprecated  from  Linux  2.6.25  onward,  and  was
336              removed altogether in Linux 2.6.38.
337
338       CLONE_SYSVSEM (since Linux 2.5.10)
339              If  CLONE_SYSVSEM is set, then the child and the calling process
340              share a single list of  System  V  semaphore  undo  values  (see
341              semop(2)).   If this flag is not set, then the child has a sepa‐
342              rate undo list, which is initially empty.
343
344       CLONE_THREAD (since Linux 2.4.0-test8)
345              If CLONE_THREAD is set, the child is placed in the  same  thread
346              group as the calling process.  To make the remainder of the dis‐
347              cussion of CLONE_THREAD more readable, the term "thread" is used
348              to refer to the processes within a thread group.
349
350              Thread  groups  were a feature added in Linux 2.4 to support the
351              POSIX threads notion of a set of threads  that  share  a  single
352              PID.   Internally, this shared PID is the so-called thread group
353              identifier (TGID) for the thread group.  Since Linux 2.4,  calls
354              to getpid(2) return the TGID of the caller.
355
356              The  threads  within a group can be distinguished by their (sys‐
357              tem-wide) unique thread IDs (TID).  A new thread's TID is avail‐
358              able  as  the function result returned to the caller of clone(),
359              and a thread can obtain its own TID using gettid(2).
360
361              When a call is made to clone() without specifying  CLONE_THREAD,
362              then  the resulting thread is placed in a new thread group whose
363              TGID is the same as the thread's TID.  This thread is the leader
364              of the new thread group.
365
366              A  new  thread  created  with  CLONE_THREAD  has the same parent
367              process as the caller of clone() (i.e., like  CLONE_PARENT),  so
368              that  calls  to  getppid(2) return the same value for all of the
369              threads in a thread group.  When a  CLONE_THREAD  thread  termi‐
370              nates,  the  thread  that created it using clone() is not sent a
371              SIGCHLD (or other termination) signal; nor  can  the  status  of
372              such a thread be obtained using wait(2).  (The thread is said to
373              be detached.)
374
375              After all of the threads in a thread group terminate the  parent
376              process of the thread group is sent a SIGCHLD (or other termina‐
377              tion) signal.
378
379              If any of the threads in a thread group performs  an  execve(2),
380              then  all  threads other than the thread group leader are termi‐
381              nated, and the new program  is  executed  in  the  thread  group
382              leader.
383
384              If  one  of  the threads in a thread group creates a child using
385              fork(2), then any thread in  the  group  can  wait(2)  for  that
386              child.
387
388              Since  Linux  2.5.35,  flags  must also include CLONE_SIGHAND if
389              CLONE_THREAD is specified.
390
391              Signals may be sent to a thread group as a whole (i.e., a  TGID)
392              using  kill(2),  or  to  a  specific  thread  (i.e.,  TID) using
393              tgkill(2).
394
395              Signal dispositions and actions are process-wide: if  an  unhan‐
396              dled  signal is delivered to a thread, then it will affect (ter‐
397              minate, stop, continue, be ignored in) all members of the thread
398              group.
399
400              Each  thread  has its own signal mask, as set by sigprocmask(2),
401              but signals can be pending either: for the whole process  (i.e.,
402              deliverable  to  any member of the thread group), when sent with
403              kill(2); or for an individual thread, when sent with  tgkill(2).
404              A  call  to sigpending(2) returns a signal set that is the union
405              of the signals pending for the whole  process  and  the  signals
406              that are pending for the calling thread.
407
408              If  kill(2)  is used to send a signal to a thread group, and the
409              thread group has installed a handler for the  signal,  then  the
410              handler  will  be  invoked  in exactly one, arbitrarily selected
411              member of the thread group that has not blocked the signal.   If
412              multiple  threads in a group are waiting to accept the same sig‐
413              nal using sigwaitinfo(2), the kernel will arbitrarily select one
414              of these threads to receive a signal sent using kill(2).
415
416       CLONE_UNTRACED (since Linux 2.5.46)
417              If  CLONE_UNTRACED  is  specified, then a tracing process cannot
418              force CLONE_PTRACE on this child process.
419
420       CLONE_VFORK (since Linux 2.2)
421              If CLONE_VFORK is set, the execution of the calling  process  is
422              suspended  until the child releases its virtual memory resources
423              via a call to execve(2) or _exit(2) (as with vfork(2)).
424
425              If CLONE_VFORK is not set then both the calling process and  the
426              child  are schedulable after the call, and an application should
427              not rely on execution occurring in any particular order.
428
429       CLONE_VM (since Linux 2.0)
430              If CLONE_VM is set, the calling process and  the  child  process
431              run in the same memory space.  In particular, memory writes per‐
432              formed by the calling process or by the child process  are  also
433              visible  in  the other process.  Moreover, any memory mapping or
434              unmapping performed with mmap(2) or munmap(2) by  the  child  or
435              calling process also affects the other process.
436
437              If  CLONE_VM  is  not  set, the child process runs in a separate
438              copy of the memory space of the calling process at the  time  of
439              clone().  Memory writes or file mappings/unmappings performed by
440              one of the processes do not affect the other, as with fork(2).
441
442   The raw system call interface
443       The raw clone() system call corresponds more closely to fork(2) in that
444       execution  in the child continues from the point of the call.  As such,
445       the fn and arg arguments of the clone() wrapper function  are  omitted.
446       Furthermore, the argument order changes.  The raw system call interface
447       on x86 and many other architectures is roughly:
448
449           long clone(unsigned long flags, void *child_stack,
450                      void *ptid, void *ctid,
451                      struct pt_regs *regs);
452
453       Another difference for the raw system  call  is  that  the  child_stack
454       argument may be zero, in which case copy-on-write semantics ensure that
455       the child gets separate copies of stack pages when either process modi‐
456       fies  the  stack.   In  this  case, for correct operation, the CLONE_VM
457       option should not be specified.
458
459       For some architectures, the order of the arguments for the system  call
460       differs  from that shown above.  On the score, microblaze, ARM, ARM 64,
461       PA-RISC, arc, Power PC, xtensa, and MIPS architectures,  the  order  of
462       the  fourth  and  fifth  arguments  is  reversed.  On the cris and s390
463       architectures, the order of the first and second arguments is reversed.
464
465   blackfin, m68k, and sparc
466       The argument-passing conventions on blackfin, m68k, and sparc are  dif‐
467       ferent  from  descriptions  above.   For  details,  see the kernel (and
468       glibc) source.
469
470   ia64
471       On ia64, a different interface is used:
472
473       int __clone2(int (*fn)(void *),
474                    void *child_stack_base, size_t stack_size,
475                    int flags, void *arg, ...
476                 /* pid_t *ptid, struct user_desc *tls, pid_t *ctid */ );
477
478       The prototype shown above is for the glibc wrapper  function;  the  raw
479       system  call interface has no fn or arg argument, and changes the order
480       of the arguments so that flags is the first argument, and  tls  is  the
481       last argument.
482
483       __clone2()   operates   in   the  same  way  as  clone(),  except  that
484       child_stack_base points to the lowest  address  of  the  child's  stack
485       area,  and  stack_size  specifies  the  size of the stack pointed to by
486       child_stack_base.
487
488   Linux 2.4 and earlier
489       In Linux 2.4 and earlier, clone() does not take  arguments  ptid,  tls,
490       and ctid.
491

RETURN VALUE

493       On success, the thread ID of the child process is returned in the call‐
494       er's thread of execution.  On failure, -1 is returned in  the  caller's
495       context, no child process will be created, and errno will be set appro‐
496       priately.
497

ERRORS

499       EAGAIN Too many processes are already running.
500
501       EINVAL CLONE_SIGHAND was specified, but CLONE_VM was not.  (Since Linux
502              2.6.0-test6.)
503
504       EINVAL CLONE_THREAD  was  specified, but CLONE_SIGHAND was not.  (Since
505              Linux 2.5.35.)
506
507       EINVAL Both CLONE_FS and CLONE_NEWNS were specified in flags.
508
509       EINVAL Both CLONE_NEWIPC and CLONE_SYSVSEM were specified in flags.
510
511       EINVAL Both CLONE_NEWPID and CLONE_THREAD were specified in flags.
512
513       EINVAL Returned  by  clone()  when  a  zero  value  is  specified   for
514              child_stack.
515
516       EINVAL CLONE_NEWIPC was specified in flags, but the kernel was not con‐
517              figured with the CONFIG_SYSVIPC and CONFIG_IPC_NS options.
518
519       EINVAL CLONE_NEWNET was specified in flags, but the kernel was not con‐
520              figured with the CONFIG_NET_NS option.
521
522       EINVAL CLONE_NEWPID was specified in flags, but the kernel was not con‐
523              figured with the CONFIG_PID_NS option.
524
525       EINVAL CLONE_NEWUTS was specified in flags, but the kernel was not con‐
526              figured with the CONFIG_UTS option.
527
528       ENOMEM Cannot  allocate  sufficient memory to allocate a task structure
529              for the child, or to copy those parts of  the  caller's  context
530              that need to be copied.
531
532       EPERM  CLONE_NEWIPC,   CLONE_NEWNET,   CLONE_NEWNS,   CLONE_NEWPID,  or
533              CLONE_NEWUTS was specified by an unprivileged  process  (process
534              without CAP_SYS_ADMIN).
535
536       EPERM  CLONE_PID was specified by a process other than process 0.
537

VERSIONS

539       There  is  no  entry  for clone() in libc5.  glibc2 provides clone() as
540       described in this manual page.
541

CONFORMING TO

543       clone() is Linux-specific and should not be used in  programs  intended
544       to be portable.
545

NOTES

547       In  the  kernel  2.4.x series, CLONE_THREAD generally does not make the
548       parent of the new thread the same as the parent of the calling process.
549       However,  for  kernel  versions  2.4.7  to 2.4.18 the CLONE_THREAD flag
550       implied the CLONE_PARENT flag (as in kernel 2.6).
551
552       For a while there was CLONE_DETACHED  (introduced  in  2.5.32):  parent
553       wants  no  child-exit  signal.  In 2.6.2 the need to give this together
554       with CLONE_THREAD disappeared.  This flag is still defined, but has  no
555       effect.
556
557       On  i386,  clone()  should not be called through vsyscall, but directly
558       through int $0x80.
559

BUGS

561       Versions of the GNU C library that include the NPTL  threading  library
562       contain a wrapper function for getpid(2) that performs caching of PIDs.
563       This caching relies on support in the glibc wrapper for clone(), but as
564       currently  implemented, the cache may not be up to date in some circum‐
565       stances.  In particular, if a signal is delivered to the child  immedi‐
566       ately after the clone() call, then a call to getpid(2) in a handler for
567       the signal may return the PID of the calling process ("the parent"), if
568       the  clone  wrapper has not yet had a chance to update the PID cache in
569       the child.  (This discussion ignores the case where the child was  cre‐
570       ated using CLONE_THREAD, when getpid(2) should return the same value in
571       the child and in the process that called clone(), since the caller  and
572       the  child  are in the same thread group.  The stale-cache problem also
573       does not occur if the flags argument includes CLONE_VM.)   To  get  the
574       truth, it may be necessary to use code such as the following:
575
576           #include <syscall.h>
577
578           pid_t mypid;
579
580           mypid = syscall(SYS_getpid);
581

EXAMPLE

583   Create a child that executes in a separate UTS namespace
584       The following program demonstrates the use of clone() to create a child
585       process that executes in a separate UTS namespace.  The  child  changes
586       the  hostname in its UTS namespace.  Both parent and child then display
587       the system hostname, making it possible to see that the  hostname  dif‐
588       fers  in the UTS namespaces of the parent and child.  For an example of
589       the use of this program, see setns(2).
590
591       #define _GNU_SOURCE
592       #include <sys/wait.h>
593       #include <sys/utsname.h>
594       #include <sched.h>
595       #include <string.h>
596       #include <stdio.h>
597       #include <stdlib.h>
598       #include <unistd.h>
599
600       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
601                               } while (0)
602
603       static int              /* Start function for cloned child */
604       childFunc(void *arg)
605       {
606           struct utsname uts;
607
608           /* Change hostname in UTS namespace of child */
609
610           if (sethostname(arg, strlen(arg)) == -1)
611               errExit("sethostname");
612
613           /* Retrieve and display hostname */
614
615           if (uname(&uts) == -1)
616               errExit("uname");
617           printf("uts.nodename in child:  %s\n", uts.nodename);
618
619           /* Keep the namespace open for a while, by sleeping.
620              This allows some experimentation--for example, another
621              process might join the namespace. */
622
623           sleep(200);
624
625           return 0;           /* Child terminates now */
626       }
627
628       #define STACK_SIZE (1024 * 1024)    /* Stack size for cloned child */
629
630       int
631       main(int argc, char *argv[])
632       {
633           char *stack;                    /* Start of stack buffer */
634           char *stackTop;                 /* End of stack buffer */
635           pid_t pid;
636           struct utsname uts;
637
638           if (argc < 2) {
639               fprintf(stderr, "Usage: %s <child-hostname>\n", argv[0]);
640               exit(EXIT_SUCCESS);
641           }
642
643           /* Allocate stack for child */
644
645           stack = malloc(STACK_SIZE);
646           if (stack == NULL)
647               errExit("malloc");
648           stackTop = stack + STACK_SIZE;  /* Assume stack grows downward */
649
650           /* Create child that has its own UTS namespace;
651              child commences execution in childFunc() */
652
653           pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);
654           if (pid == -1)
655               errExit("clone");
656           printf("clone() returned %ld\n", (long) pid);
657
658           /* Parent falls through to here */
659
660           sleep(1);           /* Give child time to change its hostname */
661
662           /* Display hostname in parent's UTS namespace. This will be
663              different from hostname in child's UTS namespace. */
664
665           if (uname(&uts) == -1)
666               errExit("uname");
667           printf("uts.nodename in parent: %s\n", uts.nodename);
668
669           if (waitpid(pid, NULL, 0) == -1)    /* Wait for child */
670               errExit("waitpid");
671           printf("child has terminated\n");
672
673           exit(EXIT_SUCCESS);
674       }
675

SEE ALSO

677       fork(2), futex(2), getpid(2), gettid(2),  kcmp(2),  set_thread_area(2),
678       set_tid_address(2),  setns(2), tkill(2), unshare(2), wait(2), capabili‐
679       ties(7), pthreads(7)
680

COLOPHON

682       This page is part of release 3.53 of the Linux  man-pages  project.   A
683       description  of  the project, and information about reporting bugs, can
684       be found at http://www.kernel.org/doc/man-pages/.
685
686
687
688Linux                             2013-04-16                          CLONE(2)
Impressum