]>
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 | |
4 | .\" and Michael Kerrisk, 2001, 2002 | |
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 | |
16 | .\" Added CLONE_PARENT and revised entire page remove ambiguity | |
17 | .\" between "calling process" and "parent process" | |
18 | .\" Added CLONE_PTRACE and CLONE_VFORK | |
19 | .\" Added EPERM and EINVAL error codes | |
20 | .\" Renamed "__clone" to "clone" (which is the protype in <sched.h>) | |
21 | .\" various other minor tidy ups and clarifications. | |
305a0578 | 22 | .\" Modified 26 Jun 2001 by Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 23 | .\" Updated notes for 2.4.7+ behaviour of CLONE_THREAD |
305a0578 | 24 | .\" Modified 15 Oct 2002 by Michael Kerrisk <mtk-manpages@gmx.net> |
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 | |
29 | .\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc - aeb. | |
30 | .\" | |
31 | .TH CLONE 2 2004-09-10 "Linux 2.6" "Linux Programmer's Manual" | |
32 | .SH NAME | |
33 | clone \- create a child process | |
34 | .SH SYNOPSIS | |
35 | .B #include <sched.h> | |
36 | .sp | |
37 | .BI "int clone(int (*" "fn" ")(void *), void *" "child_stack" ", int " "flags" ", void *" "arg" ); | |
38 | .sp | |
39 | .BI "_syscall2(int, " clone ", int, " flags ", void *, " child_stack ) | |
40 | .sp | |
41 | .BI "_syscall5(int, " clone ", int, " flags ", void *, " child_stack , | |
42 | .br | |
43 | .BI " int *, " parent_tidptr ", struct user_desc *, " newtls , | |
44 | .br | |
45 | .BI " int *, " child_tidptr ) | |
46 | .SH DESCRIPTION | |
47 | .B clone | |
48 | creates a new process, just like | |
49 | .BR fork (2). | |
50 | .B clone | |
51 | is a library function layered on top | |
52 | of the underlying | |
53 | .BR clone | |
54 | system call, hereinafter referred to as | |
55 | .BR sys_clone . | |
56 | A description of | |
57 | .BR sys_clone | |
58 | is given towards the end of this page. | |
59 | ||
60 | Unlike | |
61 | .BR fork (2), | |
62 | these calls | |
63 | allow the child process to share parts of its execution context with | |
64 | the calling process, such as the memory space, the table of file | |
65 | descriptors, and the table of signal handlers. (Note that on this manual | |
66 | page, "calling process" normally corresponds to "parent process". But see | |
67 | the description of | |
68 | .B CLONE_PARENT | |
69 | below.) | |
70 | ||
71 | The main use of | |
72 | .B clone | |
73 | is to implement threads: multiple threads of control in a program that | |
74 | run concurrently in a shared memory space. | |
75 | ||
76 | When the child process is created with | |
77 | .BR clone , | |
78 | it executes the function | |
79 | application | |
80 | .IR fn ( arg ). | |
81 | (This differs from | |
82 | .BR fork (2), | |
83 | where execution continues in the child from the point | |
84 | of the | |
85 | .BR fork (2) | |
86 | call.) | |
87 | The | |
88 | .I fn | |
89 | argument is a pointer to a function that is called by the child | |
90 | process at the beginning of its execution. | |
91 | The | |
92 | .I arg | |
93 | argument is passed to the | |
94 | .I fn | |
95 | function. | |
96 | ||
97 | When the | |
98 | .IR fn ( arg ) | |
99 | function application returns, the child process terminates. The | |
100 | integer returned by | |
101 | .I fn | |
102 | is the exit code for the child process. The child process may also | |
103 | terminate explicitly by calling | |
104 | .BR exit (2) | |
105 | or after receiving a fatal signal. | |
106 | ||
107 | The | |
108 | .I child_stack | |
109 | argument specifies the location of the stack used by the child | |
110 | process. Since the child and calling process may share memory, | |
111 | it is not possible for the child process to execute in the | |
112 | same stack as the calling process. The calling process must therefore | |
113 | set up memory space for the child stack and pass a pointer to this | |
114 | space to | |
115 | .BR clone . | |
116 | Stacks grow downwards on all processors that run Linux | |
117 | (except the HP PA processors), so | |
118 | .I child_stack | |
119 | usually points to the topmost address of the memory space set up for | |
120 | the child stack. | |
121 | ||
122 | The low byte of | |
123 | .I flags | |
124 | contains the number of the signal sent to the parent when the child | |
125 | dies. If this signal is specified as anything other than | |
126 | .BR SIGCHLD , | |
127 | then the parent process must specify the | |
128 | .B __WALL | |
129 | or | |
130 | .B __WCLONE | |
131 | options when waiting for the child with | |
132 | .BR wait (2). | |
133 | If no signal is specified, then the parent process is not signaled | |
134 | when the child terminates. | |
135 | ||
136 | .I flags | |
137 | may also be bitwise-or'ed with one or several of the following | |
138 | constants, in order to specify what is shared between the calling process | |
139 | and the child process: | |
140 | ||
141 | .TP | |
142 | .BR CLONE_PARENT " (since Linux 2.3.12)" | |
143 | If | |
144 | .B CLONE_PARENT | |
145 | is set, then the parent of the new child (as returned by | |
146 | .BR getppid (2)) | |
147 | will be the same as that of the calling process. | |
148 | ||
149 | If | |
150 | .B CLONE_PARENT | |
151 | is not set, then (as with | |
152 | .BR fork (2)) | |
153 | the child's parent is the calling process. | |
154 | ||
155 | Note that it is the parent process, as returned by | |
156 | .BR getppid (2), | |
157 | which is signaled when the child terminates, so that | |
158 | if | |
159 | .B CLONE_PARENT | |
160 | is set, then the parent of the calling process, rather than the | |
161 | calling process itself, will be signaled. | |
162 | ||
163 | .TP | |
164 | .B CLONE_FS | |
165 | If | |
166 | .B CLONE_FS | |
167 | is set, the caller and the child processes share the same file system | |
168 | information. This includes the root of the file system, the current | |
169 | working directory, and the umask. Any call to | |
170 | .BR chroot (2), | |
171 | .BR chdir (2), | |
172 | or | |
173 | .BR umask (2) | |
174 | performed by the calling process or the child process also takes effect in the | |
175 | other process. | |
176 | ||
177 | If | |
178 | .B CLONE_FS | |
179 | is not set, the child process works on a copy of the file system | |
180 | information of the calling process at the time of the | |
181 | .BR clone | |
182 | call. | |
183 | Calls to | |
184 | .BR chroot (2), | |
185 | .BR chdir (2), | |
186 | .BR umask (2) | |
187 | performed later by one of the processes do not affect the other process. | |
188 | ||
189 | .TP | |
190 | .B CLONE_FILES | |
191 | If | |
192 | .B CLONE_FILES | |
193 | is set, the calling process and the child processes share the same file | |
194 | descriptor table. File descriptors always refer to the same files in | |
195 | the calling process and in the child process. Any file descriptor created by | |
196 | the calling process or by the child process is also valid in the other | |
197 | process. Similarly, if one of the processes closes a file descriptor, | |
198 | or changes its associated flags, the other process is also affected. | |
199 | ||
200 | If | |
201 | .B CLONE_FILES | |
202 | is not set, the child process inherits a copy of all file descriptors | |
203 | opened in the calling process at the time of | |
204 | .BR clone . | |
205 | Operations on file descriptors performed later by either the calling process or | |
206 | the child process do not affect the other process. | |
207 | ||
208 | .TP | |
209 | .BR CLONE_NEWNS " (since Linux 2.4.19) | |
210 | Start the child in a new namespace. | |
211 | ||
212 | Every process lives in a namespace. The | |
213 | .I namespace | |
214 | of a process is the data (the set of mounts) describing the file hierarchy | |
215 | as seen by that process. After a | |
216 | .BR fork (2) | |
217 | or | |
218 | .BR clone (2) | |
219 | where the | |
220 | .B CLONE_NEWNS | |
221 | flag is not set, the child lives in the same namespace as the parent. | |
222 | The system calls | |
223 | .BR mount (2) | |
224 | and | |
225 | .BR umount (2) | |
226 | change the namespace of the calling process, and hence affect | |
227 | all processes that live in the same namespace, but do not affect | |
228 | processes in a different namespace. | |
229 | ||
230 | After a | |
231 | .BR clone (2) | |
232 | where the | |
233 | .B CLONE_NEWNS | |
234 | flag is set, the cloned child is started in a new namespace, | |
235 | initialized with a copy of the namespace of the parent. | |
236 | ||
237 | Only a privileged process (one having the CAP_SYS_ADMIN capability) | |
238 | may specify the | |
239 | .B CLONE_NEWNS | |
240 | flag. | |
241 | It is not permitted to specify both | |
242 | .B CLONE_NEWNS | |
243 | and | |
244 | .B CLONE_FS | |
245 | in the same | |
246 | .BR clone | |
247 | call. | |
248 | ||
249 | .TP | |
250 | .B CLONE_SIGHAND | |
251 | If | |
252 | .B CLONE_SIGHAND | |
253 | is set, the calling process and the child processes share the same table of | |
254 | signal handlers. If the calling process or child process calls | |
255 | .BR sigaction (2) | |
256 | to change the behavior associated with a signal, the behavior is | |
257 | changed in the other process as well. However, the calling process and child | |
258 | processes still have distinct signal masks and sets of pending | |
259 | signals. So, one of them may block or unblock some signals using | |
260 | .BR sigprocmask (2) | |
261 | without affecting the other process. | |
262 | ||
263 | If | |
264 | .B CLONE_SIGHAND | |
265 | is not set, the child process inherits a copy of the signal handlers | |
266 | of the calling process at the time | |
267 | .B clone | |
268 | is called. Calls to | |
269 | .BR sigaction (2) | |
270 | performed later by one of the processes have no effect on the other | |
271 | process. | |
272 | ||
273 | .TP | |
274 | .B CLONE_PTRACE | |
275 | If | |
276 | .B CLONE_PTRACE | |
277 | is specified, and the calling process is being traced, then trace the child also (see | |
278 | .BR ptrace (2)). | |
279 | ||
280 | .TP | |
281 | .B CLONE_VFORK | |
282 | If | |
283 | .B CLONE_VFORK | |
284 | is set, the execution of the calling process is suspended | |
285 | until the child releases its virtual memory | |
286 | resources via a call to | |
287 | .BR execve (2) | |
288 | or | |
289 | .BR _exit (2) | |
290 | (as with | |
291 | .BR vfork (2)). | |
292 | ||
293 | If | |
294 | .B CLONE_VFORK | |
295 | is not set then both the calling process and the child are schedulable | |
296 | after the call, and an application should not rely on execution occurring | |
297 | in any particular order. | |
298 | ||
299 | .TP | |
300 | .B CLONE_VM | |
301 | If | |
302 | .B CLONE_VM | |
303 | is set, the calling process and the child processes run in the same memory | |
304 | space. In particular, memory writes performed by the calling process | |
305 | or by the child process are also visible in the other process. | |
306 | Moreover, any memory mapping or unmapping performed with | |
307 | .BR mmap (2) | |
308 | or | |
309 | .BR munmap (2) | |
310 | by the child or calling process also affects the other process. | |
311 | ||
312 | If | |
313 | .B CLONE_VM | |
314 | is not set, the child process runs in a separate copy of the memory | |
315 | space of the calling process at the time of | |
316 | .BR clone . | |
317 | Memory writes or file mappings/unmappings performed by one of the | |
318 | processes do not affect the other, as with | |
319 | .BR fork (2). | |
320 | ||
321 | .TP | |
322 | .BR CLONE_PID " (obsolete)" | |
323 | If | |
324 | .B CLONE_PID | |
325 | is set, the child process is created with the same process ID as | |
326 | the calling process. This is good for hacking the system, but otherwise | |
327 | of not much use. Since 2.3.21 this flag can be | |
328 | specified only by the system boot process (PID 0). | |
329 | It disappeared in Linux 2.5.16. | |
330 | ||
331 | .TP | |
332 | .BR CLONE_THREAD " (since Linux 2.4.0-test8)" | |
333 | If | |
334 | .B CLONE_THREAD | |
335 | is set, the child is placed in the same thread group as the calling process. | |
336 | .\" For a while there was CLONE_DETACHED (introduced in 2.5.32): | |
337 | .\" parent wants no child-exit signal. In 2.6.2 the need to give this | |
338 | .\" together with CLONE_THREAD disappeared. | |
339 | ||
340 | If | |
341 | .B CLONE_THREAD | |
342 | is not set, then the child is placed in its own (new) | |
343 | thread group, whose ID is the same as the process ID. | |
344 | ||
345 | (Thread groups are feature added in Linux 2.4 to support the | |
346 | POSIX threads notion of a set of threads sharing a single PID. In Linux | |
347 | since 2.4, calls to | |
348 | .BR getpid (2) | |
349 | return the thread group ID of the caller.) | |
350 | ||
351 | .TP | |
352 | .BR CLONE_SETTLS " (since Linux 2.5.32)" | |
353 | The | |
354 | .I newtls | |
355 | parameter is the new TLS (Thread Local Storage) descriptor. | |
356 | (See | |
357 | .BR set_thread_area (2).) | |
358 | ||
359 | .TP | |
360 | .BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" | |
361 | Store child thread ID at location | |
362 | .I parent_tidptr | |
363 | in parent and child memory. | |
364 | (In Linux 2.5.32-2.5.48 there was a flag CLONE_SETTID that did this.) | |
365 | ||
366 | .TP | |
367 | .BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" | |
368 | Store child thread ID at location | |
369 | .I child_tidptr | |
370 | in child memory. | |
371 | ||
372 | .TP | |
373 | .BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" | |
374 | Erase child thread ID at location | |
375 | .I child_tidptr | |
376 | in child memory when the child exits, and do a wakeup on the futex | |
377 | at that address. | |
378 | The address involved may be changed by the | |
379 | .BR set_tid_address (2) | |
380 | system call. This is used by threading libraries. | |
381 | ||
382 | ||
383 | .SS "sys_clone" | |
384 | The | |
385 | .B sys_clone | |
386 | system call corresponds more closely to | |
387 | .BR fork (2) | |
388 | in that execution in the child continues from the point of the | |
389 | call. Thus, | |
390 | .B sys_clone | |
391 | only requires the | |
392 | .I flags | |
393 | and | |
394 | .I child_stack | |
395 | arguments, which have the same meaning as for | |
396 | .BR clone . | |
397 | (Note that the order of these arguments differs from | |
398 | .BR clone .) | |
399 | ||
400 | Another difference for | |
401 | .B sys_clone | |
402 | is that the | |
403 | .I child_stack | |
404 | argument may be zero, in which case copy-on-write semantics ensure that the | |
405 | child gets separate copies of stack pages when either process modifies | |
406 | the stack. In this case, for correct operation, the | |
407 | .B CLONE_VM | |
408 | option should not be specified. | |
409 | ||
410 | Since Linux 2.5.49 the system call has five parameters. | |
411 | The two new parameters are | |
412 | .I parent_tidptr | |
413 | which points to the location (in parent and child memory) where | |
414 | the parent thread ID will be written in case CLONE_PARENT_SETTID | |
415 | was specified, and | |
416 | .I child_tidptr | |
417 | which points to the location (in child memory) where the child thread ID | |
418 | will be written in case CLONE_CHILD_SETTID was specified. | |
419 | ||
420 | .SH "RETURN VALUE" | |
421 | .\" gettid() returns current->pid; | |
422 | .\" getpid() returns current->tgid; | |
423 | On success, the thread ID of the child process is returned | |
424 | in the caller's thread of execution. On failure, a \-1 will be returned | |
425 | in the caller's context, no child process will be created, and | |
426 | .I errno | |
427 | will be set appropriately. | |
428 | ||
429 | .SH ERRORS | |
430 | .TP | |
431 | .B EAGAIN | |
432 | Too many processes are already running. | |
433 | .TP | |
434 | .B EINVAL | |
435 | .B CLONE_SIGHAND | |
436 | was specified, but | |
437 | .B CLONE_VM | |
438 | was not. (Since Linux 2.6.0-test6.) | |
439 | .TP | |
440 | .B EINVAL | |
441 | .B CLONE_THREAD | |
442 | was specified, but | |
443 | .B CLONE_SIGHAND | |
444 | was not. (Since Linux 2.5.35.) | |
445 | .TP | |
446 | .B EINVAL | |
447 | Precisely one of | |
448 | .B CLONE_DETACHED | |
449 | and | |
450 | .B CLONE_THREAD | |
451 | was specified. (Since Linux 2.6.0-test6.) | |
452 | .TP | |
453 | .B EINVAL | |
454 | Both | |
455 | .B CLONE_FS | |
456 | and | |
457 | .B CLONE_NEWNS | |
458 | were specified in | |
459 | .IR flags . | |
460 | .TP | |
461 | .B EINVAL | |
462 | Returned by | |
463 | .B clone | |
464 | when a zero value is specified for | |
465 | .IR child_stack . | |
466 | .TP | |
467 | .B ENOMEM | |
468 | Cannot allocate sufficient memory to allocate a task structure for the | |
469 | child, or to copy those parts of the caller's context that need to be | |
470 | copied. | |
471 | .TP | |
472 | .B EPERM | |
473 | .B CLONE_NEWNS | |
474 | was specified by a non-root process (process without CAP_SYS_ADMIN). | |
475 | .TP | |
476 | .B EPERM | |
477 | .B CLONE_PID | |
478 | was specified by a process other than process 0. | |
479 | ||
480 | .SH AVAILABILITY | |
481 | There is no entry for | |
482 | .B clone | |
483 | in libc5. glibc2 provides | |
484 | .B clone | |
485 | as described in this manual page. | |
486 | ||
487 | .SH NOTES | |
488 | For kernel versions 2.4.7-2.4.18 the CLONE_THREAD flag implied the | |
489 | CLONE_PARENT flag. | |
490 | ||
491 | .SH "CONFORMING TO" | |
492 | The | |
493 | .B clone | |
494 | and | |
495 | .B sys_clone | |
496 | calls are Linux-specific and should not be used in programs | |
497 | intended to be portable. | |
498 | ||
499 | .SH "SEE ALSO" | |
500 | .BR fork (2), | |
501 | .BR getpid (2), | |
502 | .BR gettid (2), | |
503 | .BR wait (2), | |
504 | .BR capabilities (7) |