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