]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 1992 Drew Eckhardt <drew@cs.colorado.edu>, March 28, 1992 | |
1130df60 | 4 | .\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005 |
fea681da MK |
5 | .\" May be distributed under the GNU General Public License. |
6 | .\" Modified by Michael Haardt <michael@moria.de> | |
7 | .\" Modified 24 Jul 1993 by Rik Faith <faith@cs.unc.edu> | |
8 | .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>: | |
9 | .\" New man page (copied from 'fork.2'). | |
10 | .\" Modified 10 June 1995 by Andries Brouwer <aeb@cwi.nl> | |
11 | .\" Modified 25 April 1998 by Xavier Leroy <Xavier.Leroy@inria.fr> | |
12 | .\" Modified 26 Jun 2001 by Michael Kerrisk | |
13 | .\" Mostly upgraded to 2.4.x | |
14 | .\" Added prototype for sys_clone() plus description | |
15 | .\" Added CLONE_THREAD with a brief description of thread groups | |
c13182ef | 16 | .\" Added CLONE_PARENT and revised entire page remove ambiguity |
fea681da MK |
17 | .\" between "calling process" and "parent process" |
18 | .\" Added CLONE_PTRACE and CLONE_VFORK | |
19 | .\" Added EPERM and EINVAL error codes | |
fd8a5be4 | 20 | .\" Renamed "__clone" to "clone" (which is the prototype in <sched.h>) |
fea681da | 21 | .\" various other minor tidy ups and clarifications. |
c11b1abf | 22 | .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk.manpages@gmail.com> |
d9bfdb9c | 23 | .\" Updated notes for 2.4.7+ behavior of CLONE_THREAD |
c11b1abf | 24 | .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
25 | .\" Added description for CLONE_NEWNS, which was added in 2.4.19 |
26 | .\" Slightly rephrased, aeb. | |
27 | .\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. | |
28 | .\" Modified 1 Jan 2004 - various updates, aeb | |
0967c11f | 29 | .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. |
d9bfdb9c | 30 | .\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() |
31830ef0 | 31 | .\" wrapper under BUGS. |
fd8a5be4 MK |
32 | .\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. |
33 | .\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. | |
fea681da | 34 | .\" |
360ed6b3 | 35 | .\" FIXME Document CLONE_NEWIPC, which is new in 2.6.18 |
185341d4 | 36 | .\" (also supported for unshare()?) |
360ed6b3 | 37 | .\" FIXME Document CLONE_NEWUTS, which is new in 2.6.19 |
185341d4 MK |
38 | .\" (also supported for unshare()?) |
39 | .\" FIXME Document CLONE_NEWUSER, which is new in 2.6.23 | |
40 | .\" (also supported for unshare()?) | |
21a0b03d MK |
41 | .\" FIXME 2.6.25 marks the unused CLONE_STOPPED as obsolete, and it will |
42 | .\" probably be removed in the future. | |
43 | .\" FIXME 2.6.25: CLONE_IO flag to clone() causes I/O contexts (used in the | |
44 | .\" CFQ block I/O scheduler) to be shared with the new child process. | |
360ed6b3 | 45 | .\" |
ef37eaf2 | 46 | .TH CLONE 2 2008-04-13 "Linux" "Linux Programmer's Manual" |
fea681da | 47 | .SH NAME |
9b0e0996 | 48 | clone, __clone2 \- create a child process |
fea681da | 49 | .SH SYNOPSIS |
c10859eb | 50 | .nf |
cc4615cc MK |
51 | .B #define _GNU_SOURCE |
52 | .\" Actually _BSD_SOURCE || _SVID_SOURCE | |
53 | .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749 | |
fea681da | 54 | .B #include <sched.h> |
c10859eb | 55 | |
ff929e3b MK |
56 | .BI "int clone(int (*" "fn" ")(void *), void *" child_stack , |
57 | .BI " int " flags ", void *" "arg" ", ... " | |
58 | .BI " /* pid_t *" pid ", struct user_desc *" tls \ | |
59 | ", pid_t *" ctid " */ );" | |
c10859eb | 60 | .fi |
fea681da | 61 | .SH DESCRIPTION |
edcc65ff MK |
62 | .BR clone () |
63 | creates a new process, in a manner similar to | |
fea681da | 64 | .BR fork (2). |
735f354f | 65 | It is actually a library function layered on top of the underlying |
e511ffb6 | 66 | .BR clone () |
fea681da MK |
67 | system call, hereinafter referred to as |
68 | .BR sys_clone . | |
69 | A description of | |
0daa9e92 | 70 | .B sys_clone |
fea681da MK |
71 | is given towards the end of this page. |
72 | ||
73 | Unlike | |
74 | .BR fork (2), | |
c13182ef | 75 | these calls |
fea681da MK |
76 | allow the child process to share parts of its execution context with |
77 | the calling process, such as the memory space, the table of file | |
c13182ef MK |
78 | descriptors, and the table of signal handlers. |
79 | (Note that on this manual | |
80 | page, "calling process" normally corresponds to "parent process". | |
81 | But see the description of | |
82 | .B CLONE_PARENT | |
fea681da MK |
83 | below.) |
84 | ||
85 | The main use of | |
edcc65ff | 86 | .BR clone () |
fea681da MK |
87 | is to implement threads: multiple threads of control in a program that |
88 | run concurrently in a shared memory space. | |
89 | ||
90 | When the child process is created with | |
c13182ef | 91 | .BR clone (), |
fea681da MK |
92 | it executes the function |
93 | application | |
c13182ef | 94 | .IR fn ( arg ). |
fea681da | 95 | (This differs from |
c13182ef | 96 | .BR fork (2), |
fea681da | 97 | where execution continues in the child from the point |
c13182ef MK |
98 | of the |
99 | .BR fork (2) | |
fea681da MK |
100 | call.) |
101 | The | |
102 | .I fn | |
103 | argument is a pointer to a function that is called by the child | |
104 | process at the beginning of its execution. | |
105 | The | |
106 | .I arg | |
107 | argument is passed to the | |
108 | .I fn | |
109 | function. | |
110 | ||
c13182ef | 111 | When the |
fea681da | 112 | .IR fn ( arg ) |
c13182ef MK |
113 | function application returns, the child process terminates. |
114 | The integer returned by | |
fea681da | 115 | .I fn |
c13182ef MK |
116 | is the exit code for the child process. |
117 | The child process may also terminate explicitly by calling | |
fea681da MK |
118 | .BR exit (2) |
119 | or after receiving a fatal signal. | |
120 | ||
121 | The | |
122 | .I child_stack | |
c13182ef MK |
123 | argument specifies the location of the stack used by the child process. |
124 | Since the child and calling process may share memory, | |
fea681da | 125 | it is not possible for the child process to execute in the |
c13182ef MK |
126 | same stack as the calling process. |
127 | The calling process must therefore | |
fea681da MK |
128 | set up memory space for the child stack and pass a pointer to this |
129 | space to | |
edcc65ff | 130 | .BR clone (). |
fea681da MK |
131 | Stacks grow downwards on all processors that run Linux |
132 | (except the HP PA processors), so | |
133 | .I child_stack | |
134 | usually points to the topmost address of the memory space set up for | |
135 | the child stack. | |
136 | ||
137 | The low byte of | |
138 | .I flags | |
fd8a5be4 MK |
139 | contains the number of the |
140 | .I "termination signal" | |
141 | sent to the parent when the child dies. | |
142 | If this signal is specified as anything other than | |
fea681da MK |
143 | .BR SIGCHLD , |
144 | then the parent process must specify the | |
c13182ef MK |
145 | .B __WALL |
146 | or | |
fea681da | 147 | .B __WCLONE |
c13182ef MK |
148 | options when waiting for the child with |
149 | .BR wait (2). | |
fea681da MK |
150 | If no signal is specified, then the parent process is not signaled |
151 | when the child terminates. | |
152 | ||
153 | .I flags | |
fd8a5be4 MK |
154 | may also be bitwise-or'ed with zero or more of the following constants, |
155 | in order to specify what is shared between the calling process | |
fea681da | 156 | and the child process: |
fea681da MK |
157 | .TP |
158 | .BR CLONE_PARENT " (since Linux 2.3.12)" | |
159 | If | |
160 | .B CLONE_PARENT | |
161 | is set, then the parent of the new child (as returned by | |
162 | .BR getppid (2)) | |
163 | will be the same as that of the calling process. | |
164 | ||
165 | If | |
166 | .B CLONE_PARENT | |
167 | is not set, then (as with | |
168 | .BR fork (2)) | |
169 | the child's parent is the calling process. | |
170 | ||
c13182ef | 171 | Note that it is the parent process, as returned by |
fea681da MK |
172 | .BR getppid (2), |
173 | which is signaled when the child terminates, so that | |
c13182ef | 174 | if |
fea681da | 175 | .B CLONE_PARENT |
c13182ef | 176 | is set, then the parent of the calling process, rather than the |
fea681da | 177 | calling process itself, will be signaled. |
fea681da MK |
178 | .TP |
179 | .B CLONE_FS | |
180 | If | |
181 | .B CLONE_FS | |
182 | is set, the caller and the child processes share the same file system | |
c13182ef MK |
183 | information. |
184 | This includes the root of the file system, the current | |
185 | working directory, and the umask. | |
186 | Any call to | |
fea681da MK |
187 | .BR chroot (2), |
188 | .BR chdir (2), | |
189 | or | |
190 | .BR umask (2) | |
edcc65ff | 191 | performed by the calling process or the child process also affects the |
fea681da MK |
192 | other process. |
193 | ||
c13182ef | 194 | If |
fea681da MK |
195 | .B CLONE_FS |
196 | is not set, the child process works on a copy of the file system | |
197 | information of the calling process at the time of the | |
edcc65ff | 198 | .BR clone () |
fea681da MK |
199 | call. |
200 | Calls to | |
201 | .BR chroot (2), | |
202 | .BR chdir (2), | |
203 | .BR umask (2) | |
204 | performed later by one of the processes do not affect the other process. | |
fea681da MK |
205 | .TP |
206 | .B CLONE_FILES | |
207 | If | |
208 | .B CLONE_FILES | |
209 | is set, the calling process and the child processes share the same file | |
edcc65ff | 210 | descriptor table. |
c13182ef | 211 | Any file descriptor created by the calling process or by the child |
edcc65ff MK |
212 | process is also valid in the other process. |
213 | Similarly, if one of the processes closes a file descriptor, | |
214 | or changes its associated flags (using the | |
215 | .BR fcntl (2) | |
216 | .B F_SETFD | |
217 | operation), the other process is also affected. | |
fea681da MK |
218 | |
219 | If | |
220 | .B CLONE_FILES | |
221 | is not set, the child process inherits a copy of all file descriptors | |
222 | opened in the calling process at the time of | |
edcc65ff MK |
223 | .BR clone (). |
224 | (The duplicated file descriptors in the child refer to the | |
c13182ef | 225 | same open file descriptions (see |
edcc65ff MK |
226 | .BR open (2)) |
227 | as the corresponding file descriptors in the calling process.) | |
228 | Subsequent operations that open or close file descriptors, | |
229 | or change file descriptor flags, | |
c13182ef | 230 | performed by either the calling |
edcc65ff | 231 | process or the child process do not affect the other process. |
fea681da | 232 | .TP |
c10859eb | 233 | .BR CLONE_NEWNS " (since Linux 2.4.19)" |
fea681da MK |
234 | Start the child in a new namespace. |
235 | ||
c13182ef MK |
236 | Every process lives in a namespace. |
237 | The | |
fea681da MK |
238 | .I namespace |
239 | of a process is the data (the set of mounts) describing the file hierarchy | |
c13182ef MK |
240 | as seen by that process. |
241 | After a | |
fea681da MK |
242 | .BR fork (2) |
243 | or | |
2777b1ca | 244 | .BR clone () |
fea681da MK |
245 | where the |
246 | .B CLONE_NEWNS | |
247 | flag is not set, the child lives in the same namespace as the parent. | |
248 | The system calls | |
249 | .BR mount (2) | |
250 | and | |
251 | .BR umount (2) | |
252 | change the namespace of the calling process, and hence affect | |
253 | all processes that live in the same namespace, but do not affect | |
254 | processes in a different namespace. | |
255 | ||
256 | After a | |
2777b1ca | 257 | .BR clone () |
fea681da MK |
258 | where the |
259 | .B CLONE_NEWNS | |
260 | flag is set, the cloned child is started in a new namespace, | |
261 | initialized with a copy of the namespace of the parent. | |
262 | ||
0b9bdf82 | 263 | Only a privileged process (one having the \fBCAP_SYS_ADMIN\fP capability) |
fea681da MK |
264 | may specify the |
265 | .B CLONE_NEWNS | |
266 | flag. | |
267 | It is not permitted to specify both | |
268 | .B CLONE_NEWNS | |
269 | and | |
270 | .B CLONE_FS | |
271 | in the same | |
e511ffb6 | 272 | .BR clone () |
fea681da | 273 | call. |
fea681da MK |
274 | .TP |
275 | .B CLONE_SIGHAND | |
276 | If | |
277 | .B CLONE_SIGHAND | |
278 | is set, the calling process and the child processes share the same table of | |
c13182ef MK |
279 | signal handlers. |
280 | If the calling process or child process calls | |
fea681da | 281 | .BR sigaction (2) |
c13182ef MK |
282 | to change the behavior associated with a signal, the behavior is |
283 | changed in the other process as well. | |
284 | However, the calling process and child | |
fea681da | 285 | processes still have distinct signal masks and sets of pending |
c13182ef MK |
286 | signals. |
287 | So, one of them may block or unblock some signals using | |
fea681da MK |
288 | .BR sigprocmask (2) |
289 | without affecting the other process. | |
290 | ||
291 | If | |
292 | .B CLONE_SIGHAND | |
293 | is not set, the child process inherits a copy of the signal handlers | |
294 | of the calling process at the time | |
edcc65ff | 295 | .BR clone () |
c13182ef MK |
296 | is called. |
297 | Calls to | |
fea681da MK |
298 | .BR sigaction (2) |
299 | performed later by one of the processes have no effect on the other | |
300 | process. | |
29546c24 MK |
301 | |
302 | Since Linux 2.6.0-test6, | |
303 | .I flags | |
304 | must also include | |
305 | .B CLONE_VM | |
306 | if | |
307 | .B CLONE_SIGHAND | |
308 | is specified | |
fea681da MK |
309 | .TP |
310 | .B CLONE_PTRACE | |
c13182ef | 311 | If |
fea681da | 312 | .B CLONE_PTRACE |
a69b6bda MK |
313 | is specified, and the calling process is being traced, |
314 | then trace the child also (see | |
fea681da | 315 | .BR ptrace (2)). |
a69b6bda MK |
316 | .TP |
317 | .BR CLONE_UNTRACED " (since Linux 2.5.46)" | |
c13182ef | 318 | If |
a69b6bda MK |
319 | .B CLONE_UNTRACED |
320 | is specified, then a tracing process cannot force | |
321 | .B CLONE_PTRACE | |
322 | on this child process. | |
323 | .TP | |
324 | .BR CLONE_STOPPED " (since Linux 2.6.0-test2)" | |
325 | If | |
326 | .B CLONE_STOPPED | |
327 | is set, then the child is initially stopped (as though it was sent a | |
328 | .B SIGSTOP | |
329 | signal), and must be resumed by sending it a | |
330 | .B SIGCONT | |
331 | signal. | |
ef37eaf2 MK |
332 | |
333 | .I "From Linux 2.6.25 this flag is deprecated." | |
334 | You probably never wanted to use it, | |
335 | you certainly shouldn't be using, and soon it will go away. | |
a69b6bda | 336 | .TP |
fea681da MK |
337 | .B CLONE_VFORK |
338 | If | |
339 | .B CLONE_VFORK | |
340 | is set, the execution of the calling process is suspended | |
341 | until the child releases its virtual memory | |
342 | resources via a call to | |
343 | .BR execve (2) | |
344 | or | |
345 | .BR _exit (2) | |
c13182ef | 346 | (as with |
fea681da MK |
347 | .BR vfork (2)). |
348 | ||
c13182ef | 349 | If |
fea681da MK |
350 | .B CLONE_VFORK |
351 | is not set then both the calling process and the child are schedulable | |
352 | after the call, and an application should not rely on execution occurring | |
353 | in any particular order. | |
fea681da MK |
354 | .TP |
355 | .B CLONE_VM | |
356 | If | |
357 | .B CLONE_VM | |
358 | is set, the calling process and the child processes run in the same memory | |
c13182ef MK |
359 | space. |
360 | In particular, memory writes performed by the calling process | |
fea681da MK |
361 | or by the child process are also visible in the other process. |
362 | Moreover, any memory mapping or unmapping performed with | |
363 | .BR mmap (2) | |
364 | or | |
365 | .BR munmap (2) | |
366 | by the child or calling process also affects the other process. | |
367 | ||
368 | If | |
369 | .B CLONE_VM | |
370 | is not set, the child process runs in a separate copy of the memory | |
371 | space of the calling process at the time of | |
edcc65ff | 372 | .BR clone (). |
fea681da MK |
373 | Memory writes or file mappings/unmappings performed by one of the |
374 | processes do not affect the other, as with | |
375 | .BR fork (2). | |
fea681da MK |
376 | .TP |
377 | .BR CLONE_PID " (obsolete)" | |
378 | If | |
379 | .B CLONE_PID | |
c13182ef MK |
380 | is set, the child process is created with the same process ID as |
381 | the calling process. | |
382 | This is good for hacking the system, but otherwise | |
383 | of not much use. | |
384 | Since 2.3.21 this flag can be | |
fea681da MK |
385 | specified only by the system boot process (PID 0). |
386 | It disappeared in Linux 2.5.16. | |
fea681da MK |
387 | .TP |
388 | .BR CLONE_THREAD " (since Linux 2.4.0-test8)" | |
389 | If | |
390 | .B CLONE_THREAD | |
391 | is set, the child is placed in the same thread group as the calling process. | |
fd8a5be4 MK |
392 | To make the remainder of the discussion of |
393 | .B CLONE_THREAD | |
394 | more readable, the term "thread" is used to refer to the | |
395 | processes within a thread group. | |
fea681da | 396 | |
fd8a5be4 MK |
397 | Thread groups were a feature added in Linux 2.4 to support the |
398 | POSIX threads notion of a set of threads that share a single PID. | |
399 | Internally, this shared PID is the so-called | |
400 | thread group identifier (TGID) for the thread group. | |
c13182ef | 401 | Since Linux 2.4, calls to |
fea681da | 402 | .BR getpid (2) |
fd8a5be4 MK |
403 | return the TGID of the caller. |
404 | ||
405 | The threads within a group can be distinguished by their (system-wide) | |
406 | unique thread IDs (TID). | |
407 | A new thread's TID is available as the function result | |
408 | returned to the caller of | |
409 | .BR clone (), | |
410 | and a thread can obtain | |
411 | its own TID using | |
412 | .BR gettid (2). | |
413 | ||
c13182ef | 414 | When a call is made to |
fd8a5be4 MK |
415 | .BR clone () |
416 | without specifying | |
417 | .BR CLONE_THREAD , | |
418 | then the resulting thread is placed in a new thread group | |
419 | whose TGID is the same as the thread's TID. | |
420 | This thread is the | |
421 | .I leader | |
422 | of the new thread group. | |
423 | ||
424 | A new thread created with | |
425 | .B CLONE_THREAD | |
426 | has the same parent process as the caller of | |
427 | .BR clone () | |
c13182ef | 428 | (i.e., like |
fd8a5be4 MK |
429 | .BR CLONE_PARENT ), |
430 | so that calls to | |
431 | .BR getppid (2) | |
432 | return the same value for all of the threads in a thread group. | |
433 | When a | |
c13182ef | 434 | .B CLONE_THREAD |
fd8a5be4 MK |
435 | thread terminates, the thread that created it using |
436 | .BR clone () | |
437 | is not sent a | |
438 | .B SIGCHLD | |
439 | (or other termination) signal; | |
440 | nor can the status of such a thread be obtained | |
441 | using | |
442 | .BR wait (2). | |
443 | (The thread is said to be | |
444 | .IR detached .) | |
445 | ||
e2fbf61d MK |
446 | After all of the threads in a thread group terminate |
447 | the parent process of the thread group is sent a | |
fd8a5be4 MK |
448 | .B SIGCHLD |
449 | (or other termination) signal. | |
450 | ||
451 | If any of the threads in a thread group performs an | |
452 | .BR execve (2), | |
453 | then all threads other than the thread group leader are terminated, | |
454 | and the new program is executed in the thread group leader. | |
455 | ||
f7110f60 MK |
456 | If one of the threads in a thread group creates a child using |
457 | .BR fork (2), | |
458 | then any thread in the group can | |
459 | .BR wait (2) | |
460 | for that child. | |
461 | ||
edcc65ff | 462 | Since Linux 2.5.35, |
fd8a5be4 MK |
463 | .I flags |
464 | must also include | |
465 | .B CLONE_SIGHAND | |
466 | if | |
467 | .B CLONE_THREAD | |
468 | is specified. | |
e2fbf61d MK |
469 | |
470 | Signals may be sent to a thread group as a whole (i.e., a TGID) using | |
471 | .BR kill (2), | |
472 | or to a specific thread (i.e., TID) using | |
473 | .BR tgkill (2). | |
474 | ||
475 | Signal dispositions and actions are process-wide: | |
476 | if an unhandled signal is delivered to a thread, then | |
477 | it will affect (terminate, stop, continue, be ignored in) | |
478 | all members of the thread group. | |
479 | ||
99408a60 | 480 | Each thread has its own signal mask, as set by |
e2fbf61d | 481 | .BR sigprocmask (2), |
82a06020 | 482 | but signals can be pending either: for the whole process |
e2fbf61d MK |
483 | (i.e., deliverable to any member of the thread group), |
484 | when sent with | |
82a06020 | 485 | .BR kill (2); |
e2fbf61d MK |
486 | or for an individual thread, when sent with |
487 | .BR tgkill (2). | |
99408a60 MK |
488 | A call to |
489 | .BR sigpending (2) | |
490 | returns a signal set that is the union of the signals pending for the | |
491 | whole process and the signals that are pending for the calling thread. | |
e2fbf61d | 492 | |
c13182ef | 493 | If |
e2fbf61d MK |
494 | .BR kill (2) |
495 | is used to send a signal to a thread group, | |
496 | and the thread group has installed a handler for the signal, then | |
497 | the handler will be invoked in exactly one, arbitrarily selected | |
498 | member of the thread group that has not blocked the signal. | |
c13182ef | 499 | If multiple threads in a group are waiting to accept the same signal using |
e2fbf61d MK |
500 | .BR sigwaitinfo (2), |
501 | the kernel will arbitrarily select one of these threads | |
c13182ef | 502 | to receive a signal sent using |
e2fbf61d | 503 | .BR kill (2). |
a69b6bda MK |
504 | .TP |
505 | .BR CLONE_SYSVSEM " (since Linux 2.5.10)" | |
506 | If | |
507 | .B CLONE_SYSVSEM | |
508 | is set, then the child and the calling process share | |
509 | a single list of System V semaphore undo values (see | |
510 | .BR semop (2)). | |
511 | If this flag is not set, then the child has a separate undo list, | |
512 | which is initially empty. | |
fea681da MK |
513 | .TP |
514 | .BR CLONE_SETTLS " (since Linux 2.5.32)" | |
515 | The | |
516 | .I newtls | |
517 | parameter is the new TLS (Thread Local Storage) descriptor. | |
518 | (See | |
519 | .BR set_thread_area (2).) | |
fea681da MK |
520 | .TP |
521 | .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" | |
522 | Store child thread ID at location | |
523 | .I parent_tidptr | |
524 | in parent and child memory. | |
682edefb MK |
525 | (In Linux 2.5.32-2.5.48 there was a flag |
526 | .B CLONE_SETTID | |
527 | that did this.) | |
fea681da MK |
528 | .TP |
529 | .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" | |
530 | Store child thread ID at location | |
531 | .I child_tidptr | |
532 | in child memory. | |
fea681da MK |
533 | .TP |
534 | .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" | |
535 | Erase child thread ID at location | |
536 | .I child_tidptr | |
537 | in child memory when the child exits, and do a wakeup on the futex | |
538 | at that address. | |
539 | The address involved may be changed by the | |
540 | .BR set_tid_address (2) | |
c13182ef MK |
541 | system call. |
542 | This is used by threading libraries. | |
fea681da MK |
543 | .SS "sys_clone" |
544 | The | |
545 | .B sys_clone | |
546 | system call corresponds more closely to | |
547 | .BR fork (2) | |
548 | in that execution in the child continues from the point of the | |
c13182ef MK |
549 | call. |
550 | Thus, | |
fea681da MK |
551 | .B sys_clone |
552 | only requires the | |
553 | .I flags | |
c13182ef | 554 | and |
fea681da | 555 | .I child_stack |
c13182ef MK |
556 | arguments, which have the same meaning as for |
557 | .BR clone (). | |
fea681da | 558 | (Note that the order of these arguments differs from |
c13182ef | 559 | .BR clone ().) |
fea681da | 560 | |
c13182ef | 561 | Another difference for |
fea681da MK |
562 | .B sys_clone |
563 | is that the | |
564 | .I child_stack | |
c13182ef | 565 | argument may be zero, in which case copy-on-write semantics ensure that the |
fea681da | 566 | child gets separate copies of stack pages when either process modifies |
c13182ef MK |
567 | the stack. |
568 | In this case, for correct operation, the | |
fea681da MK |
569 | .B CLONE_VM |
570 | option should not be specified. | |
571 | ||
572 | Since Linux 2.5.49 the system call has five parameters. | |
573 | The two new parameters are | |
574 | .I parent_tidptr | |
575 | which points to the location (in parent and child memory) where | |
682edefb MK |
576 | the child thread ID will be written in case |
577 | .B CLONE_PARENT_SETTID | |
fea681da MK |
578 | was specified, and |
579 | .I child_tidptr | |
580 | which points to the location (in child memory) where the child thread ID | |
682edefb MK |
581 | will be written in case |
582 | .B CLONE_CHILD_SETTID | |
583 | was specified. | |
fea681da | 584 | .SH "RETURN VALUE" |
0bfa087b MK |
585 | .\" gettid(2) returns current->pid; |
586 | .\" getpid(2) returns current->tgid; | |
fea681da | 587 | On success, the thread ID of the child process is returned |
c13182ef MK |
588 | in the caller's thread of execution. |
589 | On failure, a \-1 will be returned | |
fea681da MK |
590 | in the caller's context, no child process will be created, and |
591 | .I errno | |
592 | will be set appropriately. | |
fea681da MK |
593 | .SH ERRORS |
594 | .TP | |
595 | .B EAGAIN | |
596 | Too many processes are already running. | |
597 | .TP | |
598 | .B EINVAL | |
599 | .B CLONE_SIGHAND | |
600 | was specified, but | |
601 | .B CLONE_VM | |
2e8a7fb3 MK |
602 | was not. |
603 | (Since Linux 2.6.0-test6.) | |
fea681da MK |
604 | .TP |
605 | .B EINVAL | |
606 | .B CLONE_THREAD | |
607 | was specified, but | |
608 | .B CLONE_SIGHAND | |
609 | was not. (Since Linux 2.5.35.) | |
29546c24 MK |
610 | .\" .TP |
611 | .\" .B EINVAL | |
612 | .\" Precisely one of | |
613 | .\" .B CLONE_DETACHED | |
614 | .\" and | |
615 | .\" .B CLONE_THREAD | |
616 | .\" was specified. (Since Linux 2.6.0-test6.) | |
fea681da MK |
617 | .TP |
618 | .B EINVAL | |
619 | Both | |
620 | .B CLONE_FS | |
621 | and | |
622 | .B CLONE_NEWNS | |
623 | were specified in | |
624 | .IR flags . | |
625 | .TP | |
626 | .B EINVAL | |
c13182ef | 627 | Returned by |
edcc65ff | 628 | .BR clone () |
c13182ef | 629 | when a zero value is specified for |
fea681da MK |
630 | .IR child_stack . |
631 | .TP | |
632 | .B ENOMEM | |
633 | Cannot allocate sufficient memory to allocate a task structure for the | |
634 | child, or to copy those parts of the caller's context that need to be | |
635 | copied. | |
636 | .TP | |
637 | .B EPERM | |
638 | .B CLONE_NEWNS | |
0b9bdf82 | 639 | was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). |
fea681da MK |
640 | .TP |
641 | .B EPERM | |
642 | .B CLONE_PID | |
643 | was specified by a process other than process 0. | |
a759cc87 | 644 | .SH VERSIONS |
fea681da | 645 | There is no entry for |
edcc65ff | 646 | .BR clone () |
a759cc87 MK |
647 | in libc5. |
648 | glibc2 provides | |
edcc65ff | 649 | .BR clone () |
fea681da | 650 | as described in this manual page. |
a1d5f77c MK |
651 | .SH "CONFORMING TO" |
652 | The | |
653 | .BR clone () | |
654 | and | |
655 | .B sys_clone | |
8382f16d | 656 | calls are Linux-specific and should not be used in programs |
a1d5f77c | 657 | intended to be portable. |
fea681da | 658 | .SH NOTES |
fd8a5be4 MK |
659 | In the kernel 2.4.x series, |
660 | .B CLONE_THREAD | |
661 | generally does not make the parent of the new thread the same | |
662 | as the parent of the calling process. | |
663 | However, for kernel versions 2.4.7 to 2.4.18 the | |
664 | .B CLONE_THREAD | |
665 | flag implied the | |
c13182ef | 666 | .B CLONE_PARENT |
fd8a5be4 | 667 | flag (as in kernel 2.6). |
fea681da | 668 | |
c13182ef MK |
669 | For a while there was |
670 | .B CLONE_DETACHED | |
a5053dcb | 671 | (introduced in 2.5.32): |
c13182ef | 672 | parent wants no child-exit signal. |
a5053dcb | 673 | In 2.6.2 the need to give this |
c13182ef MK |
674 | together with |
675 | .B CLONE_THREAD | |
a5053dcb MK |
676 | disappeared. |
677 | This flag is still defined, but has no effect. | |
678 | ||
34ccb744 | 679 | On i386, |
a5a997ca MK |
680 | .BR clone () |
681 | should not be called through vsyscall, but directly through | |
682 | .IR "int $0x80" . | |
ff929e3b | 683 | |
22399250 | 684 | On ia64, a different system call is used: |
ff929e3b MK |
685 | .nf |
686 | ||
9b0e0996 MK |
687 | .BI "int __clone2(int (*" "fn" ")(void *), " |
688 | .BI " void *" child_stack_base ", size_t " stack_size , | |
689 | .BI " int " flags ", void *" "arg" ", ... " | |
690 | .BI " /* pid_t *" pid ", struct user_desc *" tls \ | |
ff929e3b MK |
691 | ", pid_t *" ctid " */ );" |
692 | .fi | |
693 | .PP | |
694 | The | |
9b0e0996 | 695 | .BR __clone2 () |
c13182ef | 696 | system call operates in the same way as |
ff929e3b MK |
697 | .BR clone (), |
698 | except that | |
699 | .I child_stack_base | |
700 | points to the lowest address of the child's stack area, | |
701 | and | |
702 | .I stack_size | |
703 | specifies the size of the stack pointed to by | |
704 | .IR child_stack_base . | |
31830ef0 MK |
705 | .SH BUGS |
706 | Versions of the GNU C library that include the NPTL threading library | |
c13182ef | 707 | contain a wrapper function for |
0bfa087b | 708 | .BR getpid (2) |
31830ef0 | 709 | that performs caching of PIDs. |
c13182ef | 710 | In programs linked against such libraries, calls to |
0bfa087b | 711 | .BR getpid (2) |
31830ef0 MK |
712 | may return the same value, even when the threads were not created using |
713 | .B CLONE_THREAD | |
714 | (and thus are not in the same thread group). | |
715 | To get the truth, it may be necessary to use code such as the following | |
716 | .nf | |
717 | ||
718 | #include <syscall.h> | |
719 | ||
720 | pid_t mypid; | |
721 | ||
722 | mypid = syscall(SYS_getpid); | |
723 | .fi | |
fea681da MK |
724 | .SH "SEE ALSO" |
725 | .BR fork (2), | |
2b44301c | 726 | .BR futex (2), |
fea681da MK |
727 | .BR getpid (2), |
728 | .BR gettid (2), | |
f2d0bbf1 | 729 | .BR set_thread_area (2), |
2b44301c | 730 | .BR set_tid_address (2), |
f2d0bbf1 | 731 | .BR tkill (2), |
5cc01e9c | 732 | .BR unshare (2), |
fea681da | 733 | .BR wait (2), |
3616b7c0 MK |
734 | .BR capabilities (7), |
735 | .BR pthreads (7) |