1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2014-04-17 13:14+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man3/CPU_SET.3:27
26 #: build/C/man3/CPU_SET.3:27
32 #: build/C/man3/CPU_SET.3:27 build/C/man2/clone.2:45 build/C/man2/kcmp.2:28 build/C/man2/sched_get_priority_max.2:29 build/C/man3/sched_getcpu.3:26 build/C/man2/sched_rr_get_interval.2:29 build/C/man2/sched_setaffinity.2:34 build/C/man2/sched_setparam.2:30 build/C/man2/sched_setscheduler.2:46 build/C/man2/sched_yield.2:29 build/C/man2/setns.2:8 build/C/man2/unshare.2:20
38 #: build/C/man3/CPU_SET.3:27 build/C/man2/clone.2:45 build/C/man2/kcmp.2:28 build/C/man2/sched_get_priority_max.2:29 build/C/man3/sched_getcpu.3:26 build/C/man2/sched_rr_get_interval.2:29 build/C/man2/sched_setaffinity.2:34 build/C/man2/sched_setparam.2:30 build/C/man2/sched_setscheduler.2:46 build/C/man2/sched_yield.2:29 build/C/man2/setns.2:8 build/C/man2/unshare.2:20
40 msgid "Linux Programmer's Manual"
44 #: build/C/man3/CPU_SET.3:28 build/C/man2/clone.2:46 build/C/man2/kcmp.2:29 build/C/man2/sched_get_priority_max.2:30 build/C/man3/sched_getcpu.3:27 build/C/man2/sched_rr_get_interval.2:30 build/C/man2/sched_setaffinity.2:35 build/C/man2/sched_setparam.2:31 build/C/man2/sched_setscheduler.2:47 build/C/man2/sched_yield.2:30 build/C/man2/setns.2:9 build/C/man2/unshare.2:21
50 #: build/C/man3/CPU_SET.3:35
52 "CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR, "
53 "CPU_EQUAL, CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, CPU_SET_S, CPU_CLR_S, "
54 "CPU_ISSET_S, CPU_ZERO_S, CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, "
55 "CPU_EQUAL_S - macros for manipulating CPU sets"
59 #: build/C/man3/CPU_SET.3:35 build/C/man2/clone.2:48 build/C/man2/kcmp.2:31 build/C/man2/sched_get_priority_max.2:32 build/C/man3/sched_getcpu.3:29 build/C/man2/sched_rr_get_interval.2:32 build/C/man2/sched_setaffinity.2:38 build/C/man2/sched_setparam.2:33 build/C/man2/sched_setscheduler.2:50 build/C/man2/sched_yield.2:32 build/C/man2/setns.2:11 build/C/man2/unshare.2:23
65 #: build/C/man3/CPU_SET.3:39 build/C/man2/sched_setaffinity.2:42 build/C/man2/setns.2:15
68 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
69 "B<#include E<lt>sched.hE<gt>>\n"
73 #: build/C/man3/CPU_SET.3:41
75 msgid "B<void CPU_ZERO(cpu_set_t *>I<set>B<);>\n"
79 #: build/C/man3/CPU_SET.3:45
82 "B<void CPU_SET(int >I<cpu>B<, cpu_set_t *>I<set>B<);>\n"
83 "B<void CPU_CLR(int >I<cpu>B<, cpu_set_t *>I<set>B<);>\n"
84 "B<int CPU_ISSET(int >I<cpu>B<, cpu_set_t *>I<set>B<);>\n"
88 #: build/C/man3/CPU_SET.3:47
90 msgid "B<int CPU_COUNT(cpu_set_t *>I<set>B<);>\n"
94 #: build/C/man3/CPU_SET.3:54
97 "B<void CPU_AND(cpu_set_t *>I<destset>B<,>\n"
98 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
99 "B<void CPU_OR(cpu_set_t *>I<destset>B<,>\n"
100 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
101 "B<void CPU_XOR(cpu_set_t *>I<destset>B<,>\n"
102 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
106 #: build/C/man3/CPU_SET.3:56
108 msgid "B<int CPU_EQUAL(cpu_set_t *>I<set1>B<, cpu_set_t *>I<set2>B<);>\n"
112 #: build/C/man3/CPU_SET.3:60
115 "B<cpu_set_t *CPU_ALLOC(int >I<num_cpus>B<);>\n"
116 "B<void CPU_FREE(cpu_set_t *>I<set>B<);>\n"
117 "B<size_t CPU_ALLOC_SIZE(int >I<num_cpus>B<);>\n"
121 #: build/C/man3/CPU_SET.3:62
123 msgid "B<void CPU_ZERO_S(size_t >I<setsize>B<, cpu_set_t *>I<set>B<);>\n"
127 #: build/C/man3/CPU_SET.3:66
130 "B<void CPU_SET_S(int >I<cpu>B<, size_t >I<setsize>B<, cpu_set_t "
132 "B<void CPU_CLR_S(int >I<cpu>B<, size_t >I<setsize>B<, cpu_set_t "
134 "B<int CPU_ISSET_S(int >I<cpu>B<, size_t >I<setsize>B<, cpu_set_t "
139 #: build/C/man3/CPU_SET.3:68
141 msgid "B<int CPU_COUNT_S(size_t >I<setsize>B<, cpu_set_t *>I<set>B<);>\n"
145 #: build/C/man3/CPU_SET.3:75
148 "B<void CPU_AND_S(size_t >I<setsize>B<, cpu_set_t *>I<destset>B<,>\n"
149 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
150 "B<void CPU_OR_S(size_t >I<setsize>B<, cpu_set_t *>I<destset>B<,>\n"
151 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
152 "B<void CPU_XOR_S(size_t >I<setsize>B<, cpu_set_t *>I<destset>B<,>\n"
153 "B< cpu_set_t *>I<srcset1>B<, cpu_set_t *>I<srcset2>B<);>\n"
157 #: build/C/man3/CPU_SET.3:78
160 "B<int CPU_EQUAL_S(size_t >I<setsize>B<, cpu_set_t *>I<set1>B<, cpu_set_t "
165 #: build/C/man3/CPU_SET.3:79 build/C/man2/clone.2:86 build/C/man2/kcmp.2:41 build/C/man2/sched_get_priority_max.2:38 build/C/man3/sched_getcpu.3:55 build/C/man2/sched_rr_get_interval.2:36 build/C/man2/sched_setaffinity.2:49 build/C/man2/sched_setparam.2:47 build/C/man2/sched_setscheduler.2:66 build/C/man2/sched_yield.2:36 build/C/man2/setns.2:18 build/C/man2/unshare.2:50
171 #: build/C/man3/CPU_SET.3:86
173 "The I<cpu_set_t> data structure represents a set of CPUs. CPU sets are used "
174 "by B<sched_setaffinity>(2) and similar interfaces."
178 #: build/C/man3/CPU_SET.3:93
180 "The I<cpu_set_t> data type is implemented as a bitset. However, the data "
181 "structure treated as considered opaque: all manipulation of CPU sets should "
182 "be done via the macros described in this page."
186 #: build/C/man3/CPU_SET.3:96
187 msgid "The following macros are provided to operate on the CPU set I<set>:"
191 #: build/C/man3/CPU_SET.3:96
193 msgid "B<CPU_ZERO>()"
197 #: build/C/man3/CPU_SET.3:101
198 msgid "Clears I<set>, so that it contains no CPUs."
202 #: build/C/man3/CPU_SET.3:101
208 #: build/C/man3/CPU_SET.3:107
209 msgid "Add CPU I<cpu> to I<set>."
213 #: build/C/man3/CPU_SET.3:107
219 #: build/C/man3/CPU_SET.3:113
220 msgid "Remove CPU I<cpu> from I<set>."
224 #: build/C/man3/CPU_SET.3:113
226 msgid "B<CPU_ISSET>()"
230 #: build/C/man3/CPU_SET.3:119
231 msgid "Test to see if CPU I<cpu> is a member of I<set>."
235 #: build/C/man3/CPU_SET.3:119
237 msgid "B<CPU_COUNT>()"
241 #: build/C/man3/CPU_SET.3:123
242 msgid "Return the number of CPUs in I<set>."
246 #: build/C/man3/CPU_SET.3:128
248 "Where a I<cpu> argument is specified, it should not produce side effects, "
249 "since the above macros may evaluate the argument more than once."
253 #: build/C/man3/CPU_SET.3:139
255 "The first available CPU on the system corresponds to a I<cpu> value of 0, "
256 "the next CPU corresponds to a I<cpu> value of 1, and so on. The constant "
257 "B<CPU_SETSIZE> (currently 1024) specifies a value one greater than the "
258 "maximum CPU number that can be stored in I<cpu_set_t>."
262 #: build/C/man3/CPU_SET.3:141
263 msgid "The following macros perform logical operations on CPU sets:"
267 #: build/C/man3/CPU_SET.3:141
273 #: build/C/man3/CPU_SET.3:150
275 "Store the intersection of the sets I<srcset1> and I<srcset2> in I<destset> "
276 "(which may be one of the source sets)."
280 #: build/C/man3/CPU_SET.3:150
286 #: build/C/man3/CPU_SET.3:159
288 "Store the union of the sets I<srcset1> and I<srcset2> in I<destset> (which "
289 "may be one of the source sets)."
293 #: build/C/man3/CPU_SET.3:159
299 #: build/C/man3/CPU_SET.3:173
301 "Store the XOR of the sets I<srcset1> and I<srcset2> in I<destset> (which may "
302 "be one of the source sets). The XOR means the set of CPUs that are in "
303 "either I<srcset1> or I<srcset2>, but not both."
307 #: build/C/man3/CPU_SET.3:173
309 msgid "B<CPU_EQUAL>()"
313 #: build/C/man3/CPU_SET.3:176
314 msgid "Test whether two CPU set contain exactly the same CPUs."
318 #: build/C/man3/CPU_SET.3:176
320 msgid "Dynamically sized CPU sets"
324 #: build/C/man3/CPU_SET.3:182
326 "Because some applications may require the ability to dynamically size CPU "
327 "sets (e.g., to allocate sets larger than that defined by the standard "
328 "I<cpu_set_t> data type), glibc nowadays provides a set of macros to support "
333 #: build/C/man3/CPU_SET.3:184
334 msgid "The following macros are used to allocate and deallocate CPU sets:"
338 #: build/C/man3/CPU_SET.3:184
340 msgid "B<CPU_ALLOC>()"
344 #: build/C/man3/CPU_SET.3:189
346 "Allocate a CPU set large enough to hold CPUs in the range 0 to "
351 #: build/C/man3/CPU_SET.3:189
353 msgid "B<CPU_ALLOC_SIZE>()"
357 #: build/C/man3/CPU_SET.3:199
359 "Return the size in bytes of the CPU set that would be needed to hold CPUs in "
360 "the range 0 to I<num_cpus-1>. This macro provides the value that can be "
361 "used for the I<setsize> argument in the B<CPU_*_S>() macros described "
366 #: build/C/man3/CPU_SET.3:199
368 msgid "B<CPU_FREE>()"
372 #: build/C/man3/CPU_SET.3:203
373 msgid "Free a CPU set previously allocated by B<CPU_ALLOC>()."
377 #: build/C/man3/CPU_SET.3:210
379 "The macros whose names end with \"_S\" are the analogs of the similarly "
380 "named macros without the suffix. These macros perform the same tasks as "
381 "their analogs, but operate on the dynamically allocated CPU set(s) whose "
382 "size is I<setsize> bytes."
386 #: build/C/man3/CPU_SET.3:210 build/C/man2/clone.2:878 build/C/man2/kcmp.2:127 build/C/man2/sched_get_priority_max.2:100 build/C/man3/sched_getcpu.3:58 build/C/man2/sched_rr_get_interval.2:73 build/C/man2/sched_setaffinity.2:107 build/C/man2/sched_setparam.2:87 build/C/man2/sched_setscheduler.2:423 build/C/man2/sched_yield.2:41 build/C/man2/setns.2:70 build/C/man2/unshare.2:207
392 #: build/C/man3/CPU_SET.3:219
394 "B<CPU_ISSET>() and B<CPU_ISSET_S>() return nonzero if I<cpu> is in I<set>; "
395 "otherwise, it returns 0."
399 #: build/C/man3/CPU_SET.3:225
400 msgid "B<CPU_COUNT>() and B<CPU_COUNT_S>() return the number of CPUs in I<set>."
404 #: build/C/man3/CPU_SET.3:230
406 "B<CPU_EQUAL>() and B<CPU_EQUAL_S>() return nonzero if the two CPU sets are "
407 "equal; otherwise it returns 0."
411 #: build/C/man3/CPU_SET.3:235
413 "B<CPU_ALLOC>() returns a pointer on success, or NULL on failure. (Errors "
414 "are as for B<malloc>(3).)"
418 #: build/C/man3/CPU_SET.3:239
420 "B<CPU_ALLOC_SIZE>() returns the number of bytes required to store a CPU set "
421 "of the specified cardinality."
425 #: build/C/man3/CPU_SET.3:241
426 msgid "The other functions do not return a value."
430 #: build/C/man3/CPU_SET.3:241 build/C/man2/clone.2:995 build/C/man2/kcmp.2:198 build/C/man3/sched_getcpu.3:70 build/C/man2/sched_setaffinity.2:148 build/C/man2/setns.2:97 build/C/man2/unshare.2:224
436 #: build/C/man3/CPU_SET.3:249
438 "The B<CPU_ZERO>(), B<CPU_SET>(), B<CPU_CLR>(), and B<CPU_ISSET>() macros "
439 "were added in glibc 2.3.3."
443 #: build/C/man3/CPU_SET.3:252
444 msgid "B<CPU_COUNT>() first appeared in glibc 2.6."
448 #: build/C/man3/CPU_SET.3:270
450 "B<CPU_AND>(), B<CPU_OR>(), B<CPU_XOR>(), B<CPU_EQUAL>(), B<CPU_ALLOC>(), "
451 "B<CPU_ALLOC_SIZE>(), B<CPU_FREE>(), B<CPU_ZERO_S>(), B<CPU_SET_S>(), "
452 "B<CPU_CLR_S>(), B<CPU_ISSET_S>(), B<CPU_AND_S>(), B<CPU_OR_S>(), "
453 "B<CPU_XOR_S>(), and B<CPU_EQUAL_S>() first appeared in glibc 2.7."
457 #: build/C/man3/CPU_SET.3:270 build/C/man2/clone.2:1002 build/C/man2/kcmp.2:202 build/C/man2/sched_get_priority_max.2:116 build/C/man3/sched_getcpu.3:72 build/C/man2/sched_rr_get_interval.2:94 build/C/man2/sched_setaffinity.2:159 build/C/man2/sched_setparam.2:110 build/C/man2/sched_setscheduler.2:445 build/C/man2/sched_yield.2:52 build/C/man2/setns.2:102 build/C/man2/unshare.2:228
459 msgid "CONFORMING TO"
463 #: build/C/man3/CPU_SET.3:272
464 msgid "These interfaces are Linux-specific."
468 #: build/C/man3/CPU_SET.3:272 build/C/man2/clone.2:1006 build/C/man2/kcmp.2:205 build/C/man3/sched_getcpu.3:75 build/C/man2/sched_rr_get_interval.2:96 build/C/man2/sched_setaffinity.2:161 build/C/man2/sched_setparam.2:112 build/C/man2/sched_setscheduler.2:448 build/C/man2/sched_yield.2:54 build/C/man2/setns.2:106 build/C/man2/unshare.2:232
474 #: build/C/man3/CPU_SET.3:275
475 msgid "To duplicate a CPU set, use B<memcpy>(3)."
479 #: build/C/man3/CPU_SET.3:282
481 "Since CPU sets are bitsets allocated in units of long words, the actual "
482 "number of CPUs in a dynamically allocated CPU set will be rounded up to the "
483 "next multiple of I<sizeof(unsigned long)>. An application should consider "
484 "the contents of these extra bits to be undefined."
488 #: build/C/man3/CPU_SET.3:294
490 "Notwithstanding the similarity in the names, note that the constant "
491 "B<CPU_SETSIZE> indicates the number of CPUs in the I<cpu_set_t> data type "
492 "(thus, it is effectively a count of bits in the bitset), while the "
493 "I<setsize> argument of the B<CPU_*_S>() macros is a size in bytes."
497 #: build/C/man3/CPU_SET.3:300
499 "The data types for arguments and return values shown in the SYNOPSIS are "
500 "hints what about is expected in each case. However, since these interfaces "
501 "are implemented as macros, the compiler won't necessarily catch all type "
502 "errors if you violate the suggestions."
506 #: build/C/man3/CPU_SET.3:300 build/C/man2/clone.2:1031 build/C/man2/sched_setscheduler.2:531
511 #. http://sourceware.org/bugzilla/show_bug.cgi?id=7029
513 #: build/C/man3/CPU_SET.3:312
515 "On 32-bit platforms with glibc 2.8 and earlier, B<CPU_ALLOC>() allocates "
516 "twice as much space as is required, and B<CPU_ALLOC_SIZE>() returns a value "
517 "twice as large as it should. This bug should not affect the semantics of a "
518 "program, but does result in wasted memory and less efficient operation of "
519 "the macros that operate on dynamically allocated CPU sets. These bugs are "
520 "fixed in glibc 2.9."
524 #: build/C/man3/CPU_SET.3:312 build/C/man2/clone.2:1073 build/C/man2/setns.2:112
530 #: build/C/man3/CPU_SET.3:315
532 "The following program demonstrates the use of some of the macros used for "
533 "dynamically allocated CPU sets."
537 #: build/C/man3/CPU_SET.3:323
540 "#define _GNU_SOURCE\n"
541 "#include E<lt>sched.hE<gt>\n"
542 "#include E<lt>stdlib.hE<gt>\n"
543 "#include E<lt>unistd.hE<gt>\n"
544 "#include E<lt>stdio.hE<gt>\n"
545 "#include E<lt>assert.hE<gt>\n"
549 #: build/C/man3/CPU_SET.3:330
553 "main(int argc, char *argv[])\n"
555 " cpu_set_t *cpusetp;\n"
557 " int num_cpus, cpu;\n"
561 #: build/C/man3/CPU_SET.3:335
564 " if (argc E<lt> 2) {\n"
565 " fprintf(stderr, \"Usage: %s E<lt>num-cpusE<gt>\\en\", argv[0]);\n"
566 " exit(EXIT_FAILURE);\n"
571 #: build/C/man3/CPU_SET.3:337
573 msgid " num_cpus = atoi(argv[1]);\n"
577 #: build/C/man3/CPU_SET.3:343
580 " cpusetp = CPU_ALLOC(num_cpus);\n"
581 " if (cpusetp == NULL) {\n"
582 " perror(\"CPU_ALLOC\");\n"
583 " exit(EXIT_FAILURE);\n"
588 #: build/C/man3/CPU_SET.3:345
590 msgid " size = CPU_ALLOC_SIZE(num_cpus);\n"
594 #: build/C/man3/CPU_SET.3:349
597 " CPU_ZERO_S(size, cpusetp);\n"
598 " for (cpu = 0; cpu E<lt> num_cpus; cpu += 2)\n"
599 " CPU_SET_S(cpu, size, cpusetp);\n"
603 #: build/C/man3/CPU_SET.3:351
605 msgid " printf(\"CPU_COUNT() of set: %d\\en\", CPU_COUNT_S(size, cpusetp));\n"
609 #: build/C/man3/CPU_SET.3:355
612 " CPU_FREE(cpusetp);\n"
613 " exit(EXIT_SUCCESS);\n"
618 #: build/C/man3/CPU_SET.3:356 build/C/man2/clone.2:1170 build/C/man2/kcmp.2:222 build/C/man2/sched_get_priority_max.2:118 build/C/man3/sched_getcpu.3:95 build/C/man2/sched_rr_get_interval.2:132 build/C/man2/sched_setaffinity.2:214 build/C/man2/sched_setparam.2:118 build/C/man2/sched_setscheduler.2:539 build/C/man2/sched_yield.2:79 build/C/man2/setns.2:199 build/C/man2/unshare.2:266
624 #: build/C/man3/CPU_SET.3:361
626 "B<sched_setaffinity>(2), B<pthread_attr_setaffinity_np>(3), "
627 "B<pthread_setaffinity_np>(3), B<cpuset>(7)"
631 #: build/C/man3/CPU_SET.3:361 build/C/man2/clone.2:1184 build/C/man2/kcmp.2:225 build/C/man2/sched_get_priority_max.2:130 build/C/man3/sched_getcpu.3:97 build/C/man2/sched_rr_get_interval.2:138 build/C/man2/sched_setaffinity.2:233 build/C/man2/sched_setparam.2:134 build/C/man2/sched_setscheduler.2:567 build/C/man2/sched_yield.2:85 build/C/man2/setns.2:205 build/C/man2/unshare.2:275
637 #: build/C/man3/CPU_SET.3:368 build/C/man2/clone.2:1191 build/C/man2/kcmp.2:232 build/C/man2/sched_get_priority_max.2:137 build/C/man3/sched_getcpu.3:104 build/C/man2/sched_rr_get_interval.2:145 build/C/man2/sched_setaffinity.2:240 build/C/man2/sched_setparam.2:141 build/C/man2/sched_setscheduler.2:574 build/C/man2/sched_yield.2:92 build/C/man2/setns.2:212 build/C/man2/unshare.2:282
639 "This page is part of release 3.64 of the Linux I<man-pages> project. A "
640 "description of the project, and information about reporting bugs, can be "
641 "found at \\%http://www.kernel.org/doc/man-pages/."
645 #: build/C/man2/clone.2:45
651 #: build/C/man2/clone.2:45
657 #: build/C/man2/clone.2:48
658 msgid "clone, __clone2 - create a child process"
662 #: build/C/man2/clone.2:51
664 msgid "/* Prototype for the glibc wrapper function */\n"
668 #: build/C/man2/clone.2:53 build/C/man3/sched_getcpu.3:32 build/C/man2/sched_setparam.2:36 build/C/man2/sched_setscheduler.2:53 build/C/man2/unshare.2:26
670 msgid "B<#include E<lt>sched.hE<gt>>\n"
674 #: build/C/man2/clone.2:58
677 "B<int clone(int (*>I<fn>B<)(void *), void *>I<child_stack>B<,>\n"
678 "B< int >I<flags>B<, void *>I<arg>B<, ... >\n"
679 "B< /* pid_t *>I<ptid>B<, struct user_desc *>I<tls>B<, pid_t "
680 "*>I<ctid>B< */ );>\n"
684 #: build/C/man2/clone.2:60
686 msgid "/* Prototype for the raw system call */\n"
690 #: build/C/man2/clone.2:64
693 "B<long clone(unsigned long >I<flags>B<, void *>I<child_stack>B<,>\n"
694 "B< void *>I<ptid>B<, void *>I<ctid>B<,>\n"
695 "B< struct pt_regs *>I<regs>B<);>\n"
699 #: build/C/man2/clone.2:69
701 "Feature Test Macro Requirements for glibc wrapper function (see "
702 "B<feature_test_macros>(7)):"
706 #: build/C/man2/clone.2:72
711 #: build/C/man2/clone.2:75 build/C/man3/sched_getcpu.3:45 build/C/man2/unshare.2:39
713 msgid "Since glibc 2.14:"
717 #: build/C/man2/clone.2:78 build/C/man3/sched_getcpu.3:48 build/C/man2/unshare.2:42
721 #. See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
723 #: build/C/man2/clone.2:78 build/C/man3/sched_getcpu.3:48 build/C/man2/unshare.2:42
725 msgid "Before glibc 2.14:"
729 #: build/C/man2/clone.2:83 build/C/man3/sched_getcpu.3:52 build/C/man2/unshare.2:47
732 "_BSD_SOURCE || _SVID_SOURCE\n"
733 " /* _GNU_SOURCE also suffices */\n"
737 #: build/C/man2/clone.2:90
738 msgid "B<clone>() creates a new process, in a manner similar to B<fork>(2)."
742 #: build/C/man2/clone.2:97
744 "This page describes both the glibc B<clone>() wrapper function and the "
745 "underlying system call on which it is based. The main text describes the "
746 "wrapper function; the differences for the raw system call are described "
747 "toward the end of this page."
751 #: build/C/man2/clone.2:109
753 "Unlike B<fork>(2), B<clone>() allows the child process to share parts of "
754 "its execution context with the calling process, such as the memory space, "
755 "the table of file descriptors, and the table of signal handlers. (Note that "
756 "on this manual page, \"calling process\" normally corresponds to \"parent "
757 "process\". But see the description of B<CLONE_PARENT> below.)"
761 #: build/C/man2/clone.2:114
763 "The main use of B<clone>() is to implement threads: multiple threads of "
764 "control in a program that run concurrently in a shared memory space."
768 #: build/C/man2/clone.2:134
770 "When the child process is created with B<clone>(), it executes the function "
771 "I<fn>(I<arg>). (This differs from B<fork>(2), where execution continues in "
772 "the child from the point of the B<fork>(2) call.) The I<fn> argument is a "
773 "pointer to a function that is called by the child process at the beginning "
774 "of its execution. The I<arg> argument is passed to the I<fn> function."
778 #: build/C/man2/clone.2:144
780 "When the I<fn>(I<arg>) function application returns, the child process "
781 "terminates. The integer returned by I<fn> is the exit code for the child "
782 "process. The child process may also terminate explicitly by calling "
783 "B<exit>(2) or after receiving a fatal signal."
787 #: build/C/man2/clone.2:160
789 "The I<child_stack> argument specifies the location of the stack used by the "
790 "child process. Since the child and calling process may share memory, it is "
791 "not possible for the child process to execute in the same stack as the "
792 "calling process. The calling process must therefore set up memory space for "
793 "the child stack and pass a pointer to this space to B<clone>(). Stacks grow "
794 "downward on all processors that run Linux (except the HP PA processors), so "
795 "I<child_stack> usually points to the topmost address of the memory space set "
796 "up for the child stack."
800 #: build/C/man2/clone.2:176
802 "The low byte of I<flags> contains the number of the I<termination signal> "
803 "sent to the parent when the child dies. If this signal is specified as "
804 "anything other than B<SIGCHLD>, then the parent process must specify the "
805 "B<__WALL> or B<__WCLONE> options when waiting for the child with "
806 "B<wait>(2). If no signal is specified, then the parent process is not "
807 "signaled when the child terminates."
811 #: build/C/man2/clone.2:181
813 "I<flags> may also be bitwise-or'ed with zero or more of the following "
814 "constants, in order to specify what is shared between the calling process "
815 "and the child process:"
819 #: build/C/man2/clone.2:181
821 msgid "B<CLONE_CHILD_CLEARTID> (since Linux 2.5.49)"
825 #: build/C/man2/clone.2:191
827 "Erase child thread ID at location I<ctid> in child memory when the child "
828 "exits, and do a wakeup on the futex at that address. The address involved "
829 "may be changed by the B<set_tid_address>(2) system call. This is used by "
830 "threading libraries."
834 #: build/C/man2/clone.2:191
836 msgid "B<CLONE_CHILD_SETTID> (since Linux 2.5.49)"
840 #: build/C/man2/clone.2:196
841 msgid "Store child thread ID at location I<ctid> in child memory."
845 #: build/C/man2/clone.2:196
847 msgid "B<CLONE_FILES> (since Linux 2.0)"
851 #: build/C/man2/clone.2:209
853 "If B<CLONE_FILES> is set, the calling process and the child process share "
854 "the same file descriptor table. Any file descriptor created by the calling "
855 "process or by the child process is also valid in the other process. "
856 "Similarly, if one of the processes closes a file descriptor, or changes its "
857 "associated flags (using the B<fcntl>(2) B<F_SETFD> operation), the other "
858 "process is also affected."
862 #: build/C/man2/clone.2:223
864 "If B<CLONE_FILES> is not set, the child process inherits a copy of all file "
865 "descriptors opened in the calling process at the time of B<clone>(). (The "
866 "duplicated file descriptors in the child refer to the same open file "
867 "descriptions (see B<open>(2)) as the corresponding file descriptors in the "
868 "calling process.) Subsequent operations that open or close file "
869 "descriptors, or change file descriptor flags, performed by either the "
870 "calling process or the child process do not affect the other process."
874 #: build/C/man2/clone.2:223
876 msgid "B<CLONE_FS> (since Linux 2.0)"
880 #: build/C/man2/clone.2:238
882 "If B<CLONE_FS> is set, the caller and the child process share the same "
883 "filesystem information. This includes the root of the filesystem, the "
884 "current working directory, and the umask. Any call to B<chroot>(2), "
885 "B<chdir>(2), or B<umask>(2) performed by the calling process or the child "
886 "process also affects the other process."
890 #: build/C/man2/clone.2:250
892 "If B<CLONE_FS> is not set, the child process works on a copy of the "
893 "filesystem information of the calling process at the time of the B<clone>() "
894 "call. Calls to B<chroot>(2), B<chdir>(2), B<umask>(2) performed later by "
895 "one of the processes do not affect the other process."
899 #: build/C/man2/clone.2:250
901 msgid "B<CLONE_IO> (since Linux 2.6.25)"
905 #: build/C/man2/clone.2:259
907 "If B<CLONE_IO> is set, then the new process shares an I/O context with the "
908 "calling process. If this flag is not set, then (as with B<fork>(2)) the "
909 "new process has its own I/O context."
912 #. The following based on text from Jens Axboe
913 #. the anticipatory and CFQ scheduler
916 #: build/C/man2/clone.2:276
918 "The I/O context is the I/O scope of the disk scheduler (i.e, what the I/O "
919 "scheduler uses to model scheduling of a process's I/O). If processes share "
920 "the same I/O context, they are treated as one by the I/O scheduler. As a "
921 "consequence, they get to share disk time. For some I/O schedulers, if two "
922 "processes share an I/O context, they will be allowed to interleave their "
923 "disk access. If several threads are doing I/O on behalf of the same process "
924 "(B<aio_read>(3), for instance), they should employ B<CLONE_IO> to get better "
929 #: build/C/man2/clone.2:280
931 "If the kernel is not configured with the B<CONFIG_BLOCK> option, this flag "
936 #: build/C/man2/clone.2:280 build/C/man2/unshare.2:96
938 msgid "B<CLONE_NEWIPC> (since Linux 2.6.19)"
942 #: build/C/man2/clone.2:290
944 "If B<CLONE_NEWIPC> is set, then create the process in a new IPC namespace. "
945 "If this flag is not set, then (as with B<fork>(2)), the process is created "
946 "in the same IPC namespace as the calling process. This flag is intended for "
947 "the implementation of containers."
950 #. commit 7eafd7c74c3f2e67c27621b987b28397110d643f
951 #. https://lwn.net/Articles/312232/
953 #: build/C/man2/clone.2:302
955 "An IPC namespace provides an isolated view of System V IPC objects (see "
956 "B<svipc>(7)) and (since Linux 2.6.30) POSIX message queues (see "
957 "B<mq_overview>(7)). The common characteristic of these IPC mechanisms is "
958 "that IPC objects are identified by mechanisms other than filesystem "
963 #: build/C/man2/clone.2:306
965 "Objects created in an IPC namespace are visible to all other processes that "
966 "are members of that namespace, but are not visible to processes in other IPC "
971 #: build/C/man2/clone.2:310
973 "When an IPC namespace is destroyed (i.e., when the last process that is a "
974 "member of the namespace terminates), all IPC objects in the namespace are "
975 "automatically destroyed."
979 #: build/C/man2/clone.2:319
981 "Use of this flag requires: a kernel configured with the B<CONFIG_SYSVIPC> "
982 "and B<CONFIG_IPC_NS> options and that the process be privileged "
983 "(B<CAP_SYS_ADMIN>). This flag can't be specified in conjunction with "
988 #: build/C/man2/clone.2:319 build/C/man2/unshare.2:113
990 msgid "B<CLONE_NEWNET> (since Linux 2.6.24)"
993 #. FIXME Check when the implementation was completed
995 #: build/C/man2/clone.2:324
997 "(The implementation of this flag was completed only by about kernel version "
1002 #: build/C/man2/clone.2:333
1004 "If B<CLONE_NEWNET> is set, then create the process in a new network "
1005 "namespace. If this flag is not set, then (as with B<fork>(2)), the process "
1006 "is created in the same network namespace as the calling process. This flag "
1007 "is intended for the implementation of containers."
1010 #. FIXME Add pointer to veth(4) page when it is eventually completed
1012 #: build/C/man2/clone.2:348
1014 "A network namespace provides an isolated view of the networking stack "
1015 "(network device interfaces, IPv4 and IPv6 protocol stacks, IP routing "
1016 "tables, firewall rules, the I</proc/net> and I</sys/class/net> directory "
1017 "trees, sockets, etc.). A physical network device can live in exactly one "
1018 "network namespace. A virtual network device (\"veth\") pair provides a "
1019 "pipe-like abstraction that can be used to create tunnels between network "
1020 "namespaces, and can be used to create a bridge to a physical network device "
1021 "in another namespace."
1025 #: build/C/man2/clone.2:353
1027 "When a network namespace is freed (i.e., when the last process in the "
1028 "namespace terminates), its physical network devices are moved back to the "
1029 "initial network namespace (not to the parent of the process)."
1033 #: build/C/man2/clone.2:358
1035 "Use of this flag requires: a kernel configured with the B<CONFIG_NET_NS> "
1036 "option and that the process be privileged (B<CAP_SYS_ADMIN>)."
1040 #: build/C/man2/clone.2:358
1042 msgid "B<CLONE_NEWNS> (since Linux 2.4.19)"
1046 #: build/C/man2/clone.2:361
1047 msgid "Start the child in a new mount namespace."
1051 #: build/C/man2/clone.2:382
1053 "Every process lives in a mount namespace. The I<namespace> of a process is "
1054 "the data (the set of mounts) describing the file hierarchy as seen by that "
1055 "process. After a B<fork>(2) or B<clone>() where the B<CLONE_NEWNS> flag "
1056 "is not set, the child lives in the same mount namespace as the parent. The "
1057 "system calls B<mount>(2) and B<umount>(2) change the mount namespace of "
1058 "the calling process, and hence affect all processes that live in the same "
1059 "namespace, but do not affect processes in a different mount namespace."
1063 #: build/C/man2/clone.2:389
1065 "After a B<clone>() where the B<CLONE_NEWNS> flag is set, the cloned child "
1066 "is started in a new mount namespace, initialized with a copy of the "
1067 "namespace of the parent."
1071 #: build/C/man2/clone.2:401
1073 "Only a privileged process (one having the B<CAP_SYS_ADMIN> capability) may "
1074 "specify the B<CLONE_NEWNS> flag. It is not permitted to specify both "
1075 "B<CLONE_NEWNS> and B<CLONE_FS> in the same B<clone>() call."
1079 #: build/C/man2/clone.2:401
1081 msgid "B<CLONE_NEWPID> (since Linux 2.6.24)"
1084 #. This explanation draws a lot of details from
1085 #. http://lwn.net/Articles/259217/
1086 #. Authors: Pavel Emelyanov <xemul@openvz.org>
1087 #. and Kir Kolyshkin <kir@openvz.org>
1089 #. The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264
1090 #. Author: Pavel Emelyanov <xemul@openvz.org>
1092 #: build/C/man2/clone.2:418
1094 "If B<CLONE_NEWPID> is set, then create the process in a new PID namespace. "
1095 "If this flag is not set, then (as with B<fork>(2)), the process is created "
1096 "in the same PID namespace as the calling process. This flag is intended for "
1097 "the implementation of containers."
1101 #: build/C/man2/clone.2:427
1103 "A PID namespace provides an isolated environment for PIDs: PIDs in a new "
1104 "namespace start at 1, somewhat like a standalone system, and calls to "
1105 "B<fork>(2), B<vfork>(2), or B<clone>() will produce processes with PIDs "
1106 "that are unique within the namespace."
1110 #: build/C/man2/clone.2:439
1112 "The first process created in a new namespace (i.e., the process created "
1113 "using the B<CLONE_NEWPID> flag) has the PID 1, and is the \"init\" process "
1114 "for the namespace. Children that are orphaned within the namespace will be "
1115 "reparented to this process rather than B<init>(8). Unlike the traditional "
1116 "B<init> process, the \"init\" process of a PID namespace can terminate, and "
1117 "if it does, all of the processes in the namespace are terminated."
1121 #: build/C/man2/clone.2:458
1123 "PID namespaces form a hierarchy. When a new PID namespace is created, the "
1124 "processes in that namespace are visible in the PID namespace of the process "
1125 "that created the new namespace; analogously, if the parent PID namespace is "
1126 "itself the child of another PID namespace, then processes in the child and "
1127 "parent PID namespaces will both be visible in the grandparent PID "
1128 "namespace. Conversely, the processes in the \"child\" PID namespace do not "
1129 "see the processes in the parent namespace. The existence of a namespace "
1130 "hierarchy means that each process may now have multiple PIDs: one for each "
1131 "namespace in which it is visible; each of these PIDs is unique within the "
1132 "corresponding namespace. (A call to B<getpid>(2) always returns the PID "
1133 "associated with the namespace in which the process lives.)"
1136 #. mount -t proc proc /proc
1138 #: build/C/man2/clone.2:474
1140 "After creating the new namespace, it is useful for the child to change its "
1141 "root directory and mount a new procfs instance at I</proc> so that tools "
1142 "such as B<ps>(1) work correctly. (If B<CLONE_NEWNS> is also included in "
1143 "I<flags>, then it isn't necessary to change the root directory: a new procfs "
1144 "instance can be mounted directly over I</proc>.)"
1148 #: build/C/man2/clone.2:481
1150 "Use of this flag requires: a kernel configured with the B<CONFIG_PID_NS> "
1151 "option and that the process be privileged (B<CAP_SYS_ADMIN>). This flag "
1152 "can't be specified in conjunction with B<CLONE_THREAD>."
1156 #: build/C/man2/clone.2:481 build/C/man2/unshare.2:149
1158 msgid "B<CLONE_NEWUTS> (since Linux 2.6.19)"
1162 #: build/C/man2/clone.2:493
1164 "If B<CLONE_NEWUTS> is set, then create the process in a new UTS namespace, "
1165 "whose identifiers are initialized by duplicating the identifiers from the "
1166 "UTS namespace of the calling process. If this flag is not set, then (as "
1167 "with B<fork>(2)), the process is created in the same UTS namespace as the "
1168 "calling process. This flag is intended for the implementation of "
1173 #: build/C/man2/clone.2:504
1175 "A UTS namespace is the set of identifiers returned by B<uname>(2); among "
1176 "these, the domain name and the hostname can be modified by "
1177 "B<setdomainname>(2) and B<sethostname>(2), respectively. Changes made to "
1178 "the identifiers in a UTS namespace are visible to all other processes in the "
1179 "same namespace, but are not visible to processes in other UTS namespaces."
1183 #: build/C/man2/clone.2:509
1185 "Use of this flag requires: a kernel configured with the B<CONFIG_UTS_NS> "
1186 "option and that the process be privileged (B<CAP_SYS_ADMIN>)."
1190 #: build/C/man2/clone.2:509
1192 msgid "B<CLONE_PARENT> (since Linux 2.3.12)"
1196 #: build/C/man2/clone.2:516
1198 "If B<CLONE_PARENT> is set, then the parent of the new child (as returned by "
1199 "B<getppid>(2)) will be the same as that of the calling process."
1203 #: build/C/man2/clone.2:522
1205 "If B<CLONE_PARENT> is not set, then (as with B<fork>(2)) the child's parent "
1206 "is the calling process."
1210 #: build/C/man2/clone.2:530
1212 "Note that it is the parent process, as returned by B<getppid>(2), which is "
1213 "signaled when the child terminates, so that if B<CLONE_PARENT> is set, then "
1214 "the parent of the calling process, rather than the calling process itself, "
1219 #: build/C/man2/clone.2:530
1221 msgid "B<CLONE_PARENT_SETTID> (since Linux 2.5.49)"
1225 #: build/C/man2/clone.2:538
1227 "Store child thread ID at location I<ptid> in parent and child memory. (In "
1228 "Linux 2.5.32-2.5.48 there was a flag B<CLONE_SETTID> that did this.)"
1232 #: build/C/man2/clone.2:538
1234 msgid "B<CLONE_PID> (obsolete)"
1238 #: build/C/man2/clone.2:549
1240 "If B<CLONE_PID> is set, the child process is created with the same process "
1241 "ID as the calling process. This is good for hacking the system, but "
1242 "otherwise of not much use. Since 2.3.21 this flag can be specified only by "
1243 "the system boot process (PID 0). It disappeared in Linux 2.5.16."
1247 #: build/C/man2/clone.2:549
1249 msgid "B<CLONE_PTRACE> (since Linux 2.2)"
1253 #: build/C/man2/clone.2:556
1255 "If B<CLONE_PTRACE> is specified, and the calling process is being traced, "
1256 "then trace the child also (see B<ptrace>(2))."
1260 #: build/C/man2/clone.2:556
1262 msgid "B<CLONE_SETTLS> (since Linux 2.5.32)"
1266 #: build/C/man2/clone.2:563
1268 "The I<newtls> argument is the new TLS (Thread Local Storage) descriptor. "
1269 "(See B<set_thread_area>(2).)"
1273 #: build/C/man2/clone.2:563
1275 msgid "B<CLONE_SIGHAND> (since Linux 2.0)"
1279 #: build/C/man2/clone.2:579
1281 "If B<CLONE_SIGHAND> is set, the calling process and the child process share "
1282 "the same table of signal handlers. If the calling process or child process "
1283 "calls B<sigaction>(2) to change the behavior associated with a signal, the "
1284 "behavior is changed in the other process as well. However, the calling "
1285 "process and child processes still have distinct signal masks and sets of "
1286 "pending signals. So, one of them may block or unblock some signals using "
1287 "B<sigprocmask>(2) without affecting the other process."
1291 #: build/C/man2/clone.2:590
1293 "If B<CLONE_SIGHAND> is not set, the child process inherits a copy of the "
1294 "signal handlers of the calling process at the time B<clone>() is called. "
1295 "Calls to B<sigaction>(2) performed later by one of the processes have no "
1296 "effect on the other process."
1300 #: build/C/man2/clone.2:598
1302 "Since Linux 2.6.0-test6, I<flags> must also include B<CLONE_VM> if "
1303 "B<CLONE_SIGHAND> is specified"
1307 #: build/C/man2/clone.2:598
1309 msgid "B<CLONE_STOPPED> (since Linux 2.6.0-test2)"
1313 #: build/C/man2/clone.2:607
1315 "If B<CLONE_STOPPED> is set, then the child is initially stopped (as though "
1316 "it was sent a B<SIGSTOP> signal), and must be resumed by sending it a "
1317 "B<SIGCONT> signal."
1320 #. glibc 2.8 removed this defn from bits/sched.h
1322 #: build/C/man2/clone.2:615
1324 "This flag was I<deprecated> from Linux 2.6.25 onward, and was I<removed> "
1325 "altogether in Linux 2.6.38."
1329 #: build/C/man2/clone.2:615
1331 msgid "B<CLONE_SYSVSEM> (since Linux 2.5.10)"
1335 #: build/C/man2/clone.2:624
1337 "If B<CLONE_SYSVSEM> is set, then the child and the calling process share a "
1338 "single list of System V semaphore undo values (see B<semop>(2)). If this "
1339 "flag is not set, then the child has a separate undo list, which is initially "
1344 #: build/C/man2/clone.2:624
1346 msgid "B<CLONE_THREAD> (since Linux 2.4.0-test8)"
1350 #: build/C/man2/clone.2:633
1352 "If B<CLONE_THREAD> is set, the child is placed in the same thread group as "
1353 "the calling process. To make the remainder of the discussion of "
1354 "B<CLONE_THREAD> more readable, the term \"thread\" is used to refer to the "
1355 "processes within a thread group."
1359 #: build/C/man2/clone.2:641
1361 "Thread groups were a feature added in Linux 2.4 to support the POSIX threads "
1362 "notion of a set of threads that share a single PID. Internally, this shared "
1363 "PID is the so-called thread group identifier (TGID) for the thread group. "
1364 "Since Linux 2.4, calls to B<getpid>(2) return the TGID of the caller."
1368 #: build/C/man2/clone.2:650
1370 "The threads within a group can be distinguished by their (system-wide) "
1371 "unique thread IDs (TID). A new thread's TID is available as the function "
1372 "result returned to the caller of B<clone>(), and a thread can obtain its own "
1373 "TID using B<gettid>(2)."
1377 #: build/C/man2/clone.2:660
1379 "When a call is made to B<clone>() without specifying B<CLONE_THREAD>, then "
1380 "the resulting thread is placed in a new thread group whose TGID is the same "
1381 "as the thread's TID. This thread is the I<leader> of the new thread group."
1385 #: build/C/man2/clone.2:682
1387 "A new thread created with B<CLONE_THREAD> has the same parent process as the "
1388 "caller of B<clone>() (i.e., like B<CLONE_PARENT>), so that calls to "
1389 "B<getppid>(2) return the same value for all of the threads in a thread "
1390 "group. When a B<CLONE_THREAD> thread terminates, the thread that created it "
1391 "using B<clone>() is not sent a B<SIGCHLD> (or other termination) signal; "
1392 "nor can the status of such a thread be obtained using B<wait>(2). (The "
1393 "thread is said to be I<detached>.)"
1397 #: build/C/man2/clone.2:687
1399 "After all of the threads in a thread group terminate the parent process of "
1400 "the thread group is sent a B<SIGCHLD> (or other termination) signal."
1404 #: build/C/man2/clone.2:692
1406 "If any of the threads in a thread group performs an B<execve>(2), then all "
1407 "threads other than the thread group leader are terminated, and the new "
1408 "program is executed in the thread group leader."
1412 #: build/C/man2/clone.2:698
1414 "If one of the threads in a thread group creates a child using B<fork>(2), "
1415 "then any thread in the group can B<wait>(2) for that child."
1419 #: build/C/man2/clone.2:711
1421 "Since Linux 2.5.35, I<flags> must also include B<CLONE_SIGHAND> if "
1422 "B<CLONE_THREAD> is specified (and note that, since Linux 2.6.0-test6, "
1423 "B<CLONE_SIGHAND> also requires B<CLONE_VM> to be included)."
1427 #: build/C/man2/clone.2:716
1429 "Signals may be sent to a thread group as a whole (i.e., a TGID) using "
1430 "B<kill>(2), or to a specific thread (i.e., TID) using B<tgkill>(2)."
1434 #: build/C/man2/clone.2:721
1436 "Signal dispositions and actions are process-wide: if an unhandled signal is "
1437 "delivered to a thread, then it will affect (terminate, stop, continue, be "
1438 "ignored in) all members of the thread group."
1442 #: build/C/man2/clone.2:734
1444 "Each thread has its own signal mask, as set by B<sigprocmask>(2), but "
1445 "signals can be pending either: for the whole process (i.e., deliverable to "
1446 "any member of the thread group), when sent with B<kill>(2); or for an "
1447 "individual thread, when sent with B<tgkill>(2). A call to B<sigpending>(2) "
1448 "returns a signal set that is the union of the signals pending for the whole "
1449 "process and the signals that are pending for the calling thread."
1453 #: build/C/man2/clone.2:746
1455 "If B<kill>(2) is used to send a signal to a thread group, and the thread "
1456 "group has installed a handler for the signal, then the handler will be "
1457 "invoked in exactly one, arbitrarily selected member of the thread group that "
1458 "has not blocked the signal. If multiple threads in a group are waiting to "
1459 "accept the same signal using B<sigwaitinfo>(2), the kernel will arbitrarily "
1460 "select one of these threads to receive a signal sent using B<kill>(2)."
1464 #: build/C/man2/clone.2:746
1466 msgid "B<CLONE_UNTRACED> (since Linux 2.5.46)"
1470 #: build/C/man2/clone.2:753
1472 "If B<CLONE_UNTRACED> is specified, then a tracing process cannot force "
1473 "B<CLONE_PTRACE> on this child process."
1477 #: build/C/man2/clone.2:753
1479 msgid "B<CLONE_VFORK> (since Linux 2.2)"
1483 #: build/C/man2/clone.2:765
1485 "If B<CLONE_VFORK> is set, the execution of the calling process is suspended "
1486 "until the child releases its virtual memory resources via a call to "
1487 "B<execve>(2) or B<_exit>(2) (as with B<vfork>(2))."
1491 #: build/C/man2/clone.2:771
1493 "If B<CLONE_VFORK> is not set, then both the calling process and the child "
1494 "are schedulable after the call, and an application should not rely on "
1495 "execution occurring in any particular order."
1499 #: build/C/man2/clone.2:771
1501 msgid "B<CLONE_VM> (since Linux 2.0)"
1505 #: build/C/man2/clone.2:784
1507 "If B<CLONE_VM> is set, the calling process and the child process run in the "
1508 "same memory space. In particular, memory writes performed by the calling "
1509 "process or by the child process are also visible in the other process. "
1510 "Moreover, any memory mapping or unmapping performed with B<mmap>(2) or "
1511 "B<munmap>(2) by the child or calling process also affects the other "
1516 #: build/C/man2/clone.2:793
1518 "If B<CLONE_VM> is not set, the child process runs in a separate copy of the "
1519 "memory space of the calling process at the time of B<clone>(). Memory "
1520 "writes or file mappings/unmappings performed by one of the processes do not "
1521 "affect the other, as with B<fork>(2)."
1525 #: build/C/man2/clone.2:793
1527 msgid "The raw system call interface"
1531 #: build/C/man2/clone.2:809
1533 "The raw B<clone>() system call corresponds more closely to B<fork>(2) in "
1534 "that execution in the child continues from the point of the call. As such, "
1535 "the I<fn> and I<arg> arguments of the B<clone>() wrapper function are "
1536 "omitted. Furthermore, the argument order changes. The raw system call "
1537 "interface on x86 and many other architectures is roughly:"
1541 #: build/C/man2/clone.2:815
1544 "B<long clone(unsigned long >I<flags>B<, void *>I<child_stack>B<,>\n"
1545 "B< void *>I<ptid>B<, void *>I<ctid>B<,>\n"
1546 "B< struct pt_regs *>I<regs>B<);>\n"
1550 #: build/C/man2/clone.2:826
1552 "Another difference for the raw system call is that the I<child_stack> "
1553 "argument may be zero, in which case copy-on-write semantics ensure that the "
1554 "child gets separate copies of stack pages when either process modifies the "
1555 "stack. In this case, for correct operation, the B<CLONE_VM> option should "
1560 #: build/C/man2/clone.2:834
1562 "For some architectures, the order of the arguments for the system call "
1563 "differs from that shown above. On the score, microblaze, ARM, ARM 64, "
1564 "PA-RISC, arc, Power PC, xtensa, and MIPS architectures, the order of the "
1565 "fourth and fifth arguments is reversed. On the cris and s390 architectures, "
1566 "the order of the first and second arguments is reversed."
1570 #: build/C/man2/clone.2:834
1572 msgid "blackfin, m68k, and sparc"
1576 #: build/C/man2/clone.2:838
1578 "The argument-passing conventions on blackfin, m68k, and sparc are different "
1579 "from descriptions above. For details, see the kernel (and glibc) source."
1583 #: build/C/man2/clone.2:838
1589 #: build/C/man2/clone.2:840
1590 msgid "On ia64, a different interface is used:"
1594 #: build/C/man2/clone.2:847
1597 "B<int __clone2(int (*>I<fn>B<)(void *), >\n"
1598 "B< void *>I<child_stack_base>B<, size_t >I<stack_size>B<,>\n"
1599 "B< int >I<flags>B<, void *>I<arg>B<, ... >\n"
1600 "B< /* pid_t *>I<ptid>B<, struct user_desc *>I<tls>B<, pid_t "
1601 "*>I<ctid>B< */ );>\n"
1605 #: build/C/man2/clone.2:859
1607 "The prototype shown above is for the glibc wrapper function; the raw system "
1608 "call interface has no I<fn> or I<arg> argument, and changes the order of the "
1609 "arguments so that I<flags> is the first argument, and I<tls> is the last "
1614 #: build/C/man2/clone.2:870
1616 "B<__clone2>() operates in the same way as B<clone>(), except that "
1617 "I<child_stack_base> points to the lowest address of the child's stack area, "
1618 "and I<stack_size> specifies the size of the stack pointed to by "
1619 "I<child_stack_base>."
1623 #: build/C/man2/clone.2:870
1625 msgid "Linux 2.4 and earlier"
1629 #: build/C/man2/clone.2:878
1631 "In Linux 2.4 and earlier, B<clone>() does not take arguments I<ptid>, "
1632 "I<tls>, and I<ctid>."
1635 #. gettid(2) returns current->pid;
1636 #. getpid(2) returns current->tgid;
1638 #: build/C/man2/clone.2:887
1640 "On success, the thread ID of the child process is returned in the caller's "
1641 "thread of execution. On failure, -1 is returned in the caller's context, no "
1642 "child process will be created, and I<errno> will be set appropriately."
1646 #: build/C/man2/clone.2:887 build/C/man2/kcmp.2:170 build/C/man2/sched_get_priority_max.2:110 build/C/man3/sched_getcpu.3:65 build/C/man2/sched_rr_get_interval.2:80 build/C/man2/sched_setaffinity.2:116 build/C/man2/sched_setparam.2:96 build/C/man2/sched_setscheduler.2:433 build/C/man2/sched_yield.2:48 build/C/man2/setns.2:77 build/C/man2/unshare.2:212
1652 #: build/C/man2/clone.2:888
1658 #: build/C/man2/clone.2:891
1659 msgid "Too many processes are already running."
1663 #: build/C/man2/clone.2:891 build/C/man2/clone.2:898 build/C/man2/clone.2:913 build/C/man2/clone.2:921 build/C/man2/clone.2:929 build/C/man2/clone.2:937 build/C/man2/clone.2:943 build/C/man2/clone.2:953 build/C/man2/clone.2:961 build/C/man2/clone.2:969 build/C/man2/kcmp.2:181 build/C/man2/sched_get_priority_max.2:111 build/C/man2/sched_rr_get_interval.2:84 build/C/man2/sched_setaffinity.2:120 build/C/man2/sched_setaffinity.2:128 build/C/man2/sched_setparam.2:97 build/C/man2/sched_setscheduler.2:434 build/C/man2/setns.2:82 build/C/man2/unshare.2:213
1669 #: build/C/man2/clone.2:898
1671 "B<CLONE_SIGHAND> was specified, but B<CLONE_VM> was not. (Since Linux "
1678 #. .B CLONE_DETACHED
1682 #. (Since Linux 2.6.0-test6.)
1684 #: build/C/man2/clone.2:913
1686 "B<CLONE_THREAD> was specified, but B<CLONE_SIGHAND> was not. (Since Linux "
1691 #: build/C/man2/clone.2:921
1692 msgid "Both B<CLONE_FS> and B<CLONE_NEWNS> were specified in I<flags>."
1696 #: build/C/man2/clone.2:929
1697 msgid "Both B<CLONE_NEWIPC> and B<CLONE_SYSVSEM> were specified in I<flags>."
1701 #: build/C/man2/clone.2:937
1702 msgid "Both B<CLONE_NEWPID> and B<CLONE_THREAD> were specified in I<flags>."
1706 #: build/C/man2/clone.2:943
1707 msgid "Returned by B<clone>() when a zero value is specified for I<child_stack>."
1711 #: build/C/man2/clone.2:953
1713 "B<CLONE_NEWIPC> was specified in I<flags>, but the kernel was not configured "
1714 "with the B<CONFIG_SYSVIPC> and B<CONFIG_IPC_NS> options."
1718 #: build/C/man2/clone.2:961
1720 "B<CLONE_NEWNET> was specified in I<flags>, but the kernel was not configured "
1721 "with the B<CONFIG_NET_NS> option."
1725 #: build/C/man2/clone.2:969
1727 "B<CLONE_NEWPID> was specified in I<flags>, but the kernel was not configured "
1728 "with the B<CONFIG_PID_NS> option."
1732 #: build/C/man2/clone.2:977
1734 "B<CLONE_NEWUTS> was specified in I<flags>, but the kernel was not configured "
1735 "with the B<CONFIG_UTS> option."
1739 #: build/C/man2/clone.2:977 build/C/man2/setns.2:89 build/C/man2/unshare.2:217
1745 #: build/C/man2/clone.2:982
1747 "Cannot allocate sufficient memory to allocate a task structure for the "
1748 "child, or to copy those parts of the caller's context that need to be "
1753 #: build/C/man2/clone.2:982 build/C/man2/clone.2:991 build/C/man2/kcmp.2:185 build/C/man2/sched_setaffinity.2:135 build/C/man2/sched_setparam.2:101 build/C/man2/sched_setscheduler.2:439 build/C/man2/setns.2:92 build/C/man2/unshare.2:221
1759 #: build/C/man2/clone.2:991
1761 "B<CLONE_NEWIPC>, B<CLONE_NEWNET>, B<CLONE_NEWNS>, B<CLONE_NEWPID>, or "
1762 "B<CLONE_NEWUTS> was specified by an unprivileged process (process without "
1763 "B<CAP_SYS_ADMIN>)."
1767 #: build/C/man2/clone.2:995
1768 msgid "B<CLONE_PID> was specified by a process other than process 0."
1772 #: build/C/man2/clone.2:1002
1774 "There is no entry for B<clone>() in libc5. glibc2 provides B<clone>() as "
1775 "described in this manual page."
1779 #: build/C/man2/clone.2:1006
1781 "B<clone>() is Linux-specific and should not be used in programs intended to "
1786 #: build/C/man2/clone.2:1016
1788 "In the kernel 2.4.x series, B<CLONE_THREAD> generally does not make the "
1789 "parent of the new thread the same as the parent of the calling process. "
1790 "However, for kernel versions 2.4.7 to 2.4.18 the B<CLONE_THREAD> flag "
1791 "implied the B<CLONE_PARENT> flag (as in kernel 2.6)."
1795 #: build/C/man2/clone.2:1026
1797 "For a while there was B<CLONE_DETACHED> (introduced in 2.5.32): parent wants "
1798 "no child-exit signal. In 2.6.2 the need to give this together with "
1799 "B<CLONE_THREAD> disappeared. This flag is still defined, but has no effect."
1803 #: build/C/man2/clone.2:1031
1805 "On i386, B<clone>() should not be called through vsyscall, but directly "
1806 "through I<int $0x80>."
1810 #: build/C/man2/clone.2:1062
1812 "Versions of the GNU C library that include the NPTL threading library "
1813 "contain a wrapper function for B<getpid>(2) that performs caching of PIDs. "
1814 "This caching relies on support in the glibc wrapper for B<clone>(), but as "
1815 "currently implemented, the cache may not be up to date in some "
1816 "circumstances. In particular, if a signal is delivered to the child "
1817 "immediately after the B<clone>() call, then a call to B<getpid>(2) in a "
1818 "handler for the signal may return the PID of the calling process (\"the "
1819 "parent\"), if the clone wrapper has not yet had a chance to update the PID "
1820 "cache in the child. (This discussion ignores the case where the child was "
1821 "created using B<CLONE_THREAD>, when B<getpid>(2) I<should> return the same "
1822 "value in the child and in the process that called B<clone>(), since the "
1823 "caller and the child are in the same thread group. The stale-cache problem "
1824 "also does not occur if the I<flags> argument includes B<CLONE_VM>.) To get "
1825 "the truth, it may be necessary to use code such as the following:"
1829 #: build/C/man2/clone.2:1065
1831 msgid " #include E<lt>syscall.hE<gt>\n"
1835 #: build/C/man2/clone.2:1067
1837 msgid " pid_t mypid;\n"
1841 #: build/C/man2/clone.2:1069
1843 msgid " mypid = syscall(SYS_getpid);\n"
1847 #: build/C/man2/clone.2:1083
1849 "The following program demonstrates the use of B<clone>() to create a child "
1850 "process that executes in a separate UTS namespace. The child changes the "
1851 "hostname in its UTS namespace. Both parent and child then display the "
1852 "system hostname, making it possible to see that the hostname differs in the "
1853 "UTS namespaces of the parent and child. For an example of the use of this "
1854 "program, see B<setns>(2)."
1858 #: build/C/man2/clone.2:1083 build/C/man2/setns.2:166
1860 msgid "Program source"
1864 #: build/C/man2/clone.2:1093
1867 "#define _GNU_SOURCE\n"
1868 "#include E<lt>sys/wait.hE<gt>\n"
1869 "#include E<lt>sys/utsname.hE<gt>\n"
1870 "#include E<lt>sched.hE<gt>\n"
1871 "#include E<lt>string.hE<gt>\n"
1872 "#include E<lt>stdio.hE<gt>\n"
1873 "#include E<lt>stdlib.hE<gt>\n"
1874 "#include E<lt>unistd.hE<gt>\n"
1878 #: build/C/man2/clone.2:1096 build/C/man2/setns.2:177
1881 "#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\e\n"
1886 #: build/C/man2/clone.2:1101
1889 "static int /* Start function for cloned child */\n"
1890 "childFunc(void *arg)\n"
1892 " struct utsname uts;\n"
1896 #: build/C/man2/clone.2:1103
1898 msgid " /* Change hostname in UTS namespace of child */\n"
1902 #: build/C/man2/clone.2:1106
1905 " if (sethostname(arg, strlen(arg)) == -1)\n"
1906 " errExit(\"sethostname\");\n"
1910 #: build/C/man2/clone.2:1108
1912 msgid " /* Retrieve and display hostname */\n"
1916 #: build/C/man2/clone.2:1112
1919 " if (uname(&uts) == -1)\n"
1920 " errExit(\"uname\");\n"
1921 " printf(\"uts.nodename in child: %s\\en\", uts.nodename);\n"
1925 #: build/C/man2/clone.2:1116
1928 " /* Keep the namespace open for a while, by sleeping.\n"
1929 " This allows some experimentation--for example, another\n"
1930 " process might join the namespace. */\n"
1934 #: build/C/man2/clone.2:1118
1936 msgid " sleep(200);\n"
1940 #: build/C/man2/clone.2:1121
1943 " return 0; /* Child terminates now */\n"
1948 #: build/C/man2/clone.2:1123
1950 msgid "#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */\n"
1954 #: build/C/man2/clone.2:1131
1958 "main(int argc, char *argv[])\n"
1960 " char *stack; /* Start of stack buffer */\n"
1961 " char *stackTop; /* End of stack buffer */\n"
1963 " struct utsname uts;\n"
1967 #: build/C/man2/clone.2:1136
1970 " if (argc E<lt> 2) {\n"
1971 " fprintf(stderr, \"Usage: %s E<lt>child-hostnameE<gt>\\en\", "
1973 " exit(EXIT_SUCCESS);\n"
1978 #: build/C/man2/clone.2:1138
1980 msgid " /* Allocate stack for child */\n"
1984 #: build/C/man2/clone.2:1143
1987 " stack = malloc(STACK_SIZE);\n"
1988 " if (stack == NULL)\n"
1989 " errExit(\"malloc\");\n"
1990 " stackTop = stack + STACK_SIZE; /* Assume stack grows downward */\n"
1994 #: build/C/man2/clone.2:1146
1997 " /* Create child that has its own UTS namespace;\n"
1998 " child commences execution in childFunc() */\n"
2002 #: build/C/man2/clone.2:1151
2005 " pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]);\n"
2007 " errExit(\"clone\");\n"
2008 " printf(\"clone() returned %ld\\en\", (long) pid);\n"
2012 #: build/C/man2/clone.2:1153
2014 msgid " /* Parent falls through to here */\n"
2018 #: build/C/man2/clone.2:1155
2020 msgid " sleep(1); /* Give child time to change its hostname */\n"
2024 #: build/C/man2/clone.2:1158
2027 " /* Display hostname in parent\\(aqs UTS namespace. This will be\n"
2028 " different from hostname in child\\(aqs UTS namespace. */\n"
2032 #: build/C/man2/clone.2:1162
2035 " if (uname(&uts) == -1)\n"
2036 " errExit(\"uname\");\n"
2037 " printf(\"uts.nodename in parent: %s\\en\", uts.nodename);\n"
2041 #: build/C/man2/clone.2:1166
2044 " if (waitpid(pid, NULL, 0) == -1) /* Wait for child */\n"
2045 " errExit(\"waitpid\");\n"
2046 " printf(\"child has terminated\\en\");\n"
2050 #: build/C/man2/clone.2:1169
2053 " exit(EXIT_SUCCESS);\n"
2058 #: build/C/man2/clone.2:1184
2060 "B<fork>(2), B<futex>(2), B<getpid>(2), B<gettid>(2), B<kcmp>(2), "
2061 "B<set_thread_area>(2), B<set_tid_address>(2), B<setns>(2), B<tkill>(2), "
2062 "B<unshare>(2), B<wait>(2), B<capabilities>(7), B<pthreads>(7)"
2066 #: build/C/man2/kcmp.2:28
2072 #: build/C/man2/kcmp.2:28
2078 #: build/C/man2/kcmp.2:31
2079 msgid "kcmp - compare two processes to determine if they share a kernel resource"
2083 #: build/C/man2/kcmp.2:34
2085 msgid "B<#include E<lt>linux/kcmp.hE<gt>>\n"
2089 #: build/C/man2/kcmp.2:37
2092 "B<int kcmp(pid_t >I<pid1>B<, pid_t >I<pid2>B<, int >I<type>B<,>\n"
2093 "B< unsigned long >I<idx1>B<, unsigned long >I<idx2>B<);>\n"
2097 #: build/C/man2/kcmp.2:41
2098 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
2102 #: build/C/man2/kcmp.2:50
2104 "The B<kcmp>() system call can be used to check whether the two processes "
2105 "identified by I<pid1> and I<pid2> share a kernel resource such as virtual "
2106 "memory, file descriptors, and so on."
2110 #: build/C/man2/kcmp.2:55
2112 "The I<type> argument specifies which resource is to be compared in the two "
2113 "processes. It has one of the following values:"
2117 #: build/C/man2/kcmp.2:55
2119 msgid "B<KCMP_FILE>"
2123 #: build/C/man2/kcmp.2:67
2125 "Check whether a file descriptor I<idx1> in the process I<pid1> refers to the "
2126 "same open file description (see B<open>(2)) as file descriptor I<idx2> in "
2127 "the process I<pid2>."
2131 #: build/C/man2/kcmp.2:67
2133 msgid "B<KCMP_FILES>"
2137 #: build/C/man2/kcmp.2:75
2139 "Check whether the process share the same set of open file descriptors. The "
2140 "arguments I<idx1> and I<idx2> are ignored."
2144 #: build/C/man2/kcmp.2:75
2150 #: build/C/man2/kcmp.2:84
2152 "Check whether the processes share the same filesystem information (i.e., "
2153 "file mode creation mask, working directory, and filesystem root). The "
2154 "arguments I<idx1> and I<idx2> are ignored."
2158 #: build/C/man2/kcmp.2:84
2164 #: build/C/man2/kcmp.2:92
2166 "Check whether the processes share I/O context. The arguments I<idx1> and "
2167 "I<idx2> are ignored."
2171 #: build/C/man2/kcmp.2:92
2173 msgid "B<KCMP_SIGHAND>"
2177 #: build/C/man2/kcmp.2:100
2179 "Check whether the processes share the same table of signal dispositions. "
2180 "The arguments I<idx1> and I<idx2> are ignored."
2184 #: build/C/man2/kcmp.2:100
2186 msgid "B<KCMP_SYSVSEM>"
2190 #: build/C/man2/kcmp.2:109
2192 "Check whether the processes share the same list of System V semaphore undo "
2193 "operations. The arguments I<idx1> and I<idx2> are ignored."
2197 #: build/C/man2/kcmp.2:109
2203 #: build/C/man2/kcmp.2:117
2205 "Check whether the processes share the same address space. The arguments "
2206 "I<idx1> and I<idx2> are ignored."
2210 #: build/C/man2/kcmp.2:127
2212 "Note the B<kcmp>() is not protected against false positives which may occur "
2213 "if tasks are running. One should stop tasks by sending B<SIGSTOP> (see "
2214 "B<signal>(7)) prior to inspection with this system call to obtain "
2215 "meaningful results."
2219 #: build/C/man2/kcmp.2:133
2221 "The return value of a successful call to B<kcmp>() is simply the result of "
2222 "arithmetic comparison of kernel pointers (when the kernel compares "
2223 "resources, it uses their memory addresses)."
2227 #: build/C/man2/kcmp.2:141
2229 "The easiest way to explain is to consider an example. Suppose that I<v1> "
2230 "and I<v2> are the addresses of appropriate resources, then the return value "
2231 "is one of the following:"
2235 #: build/C/man2/kcmp.2:142
2241 #: build/C/man2/kcmp.2:147
2243 "I<v1> is equal to I<v2>; in other words, the two processes share the "
2248 #: build/C/man2/kcmp.2:147
2254 #: build/C/man2/kcmp.2:151
2255 msgid "I<v1> is less than I<v2>."
2259 #: build/C/man2/kcmp.2:151
2265 #: build/C/man2/kcmp.2:155
2266 msgid "I<v1> is greater than I<v2>."
2270 #: build/C/man2/kcmp.2:155
2276 #: build/C/man2/kcmp.2:160
2277 msgid "I<v1> is not equal to I<v2>, but ordering information is unavailable."
2281 #: build/C/man2/kcmp.2:165
2282 msgid "On error, -1 is returned, and I<errno> is set appropriately."
2286 #: build/C/man2/kcmp.2:170
2288 "B<kcmp>() was designed to return values suitable for sorting. This is "
2289 "particularly handy if one needs to compare a large number of file "
2294 #: build/C/man2/kcmp.2:171 build/C/man2/setns.2:78
2300 #: build/C/man2/kcmp.2:181
2301 msgid "I<type> is B<KCMP_FILE> and I<fd1> or I<fd2> is not an open file descriptor."
2305 #: build/C/man2/kcmp.2:185
2306 msgid "I<type> is invalid."
2310 #: build/C/man2/kcmp.2:191
2312 "Insufficient permission to inspect process resources. The B<CAP_SYS_PTRACE> "
2313 "capability is required to inspect processes that you do not own."
2317 #: build/C/man2/kcmp.2:191 build/C/man2/sched_rr_get_interval.2:90 build/C/man2/sched_setaffinity.2:145 build/C/man2/sched_setparam.2:107 build/C/man2/sched_setscheduler.2:442
2323 #: build/C/man2/kcmp.2:198
2324 msgid "Process I<pid1> or I<pid2> does not exist."
2328 #: build/C/man2/kcmp.2:202
2329 msgid "The B<kcmp>() system call first appeared in Linux 3.5."
2333 #: build/C/man2/kcmp.2:205
2335 "B<kcmp>() is Linux-specific and should not be used in programs intended to "
2340 #: build/C/man2/kcmp.2:208
2342 "Glibc does not provide a wrapper for this system call; call it using "
2347 #: build/C/man2/kcmp.2:217
2349 "This system call is available only if the kernel was configured with "
2350 "B<CONFIG_CHECKPOINT_RESTORE>. The main use of the system call is for the "
2351 "checkpoint/restore in user space (CRIU) feature. The alternative to this "
2352 "system call would have been to expose suitable process information via the "
2353 "B<proc>(5) filesystem; this was deemed to be unsuitable for security "
2358 #: build/C/man2/kcmp.2:222
2360 "See B<clone>(2) for some background information on the shared resources "
2361 "referred to on this page."
2365 #: build/C/man2/kcmp.2:225
2366 msgid "B<clone>(2), B<unshare>(2)"
2370 #: build/C/man2/sched_get_priority_max.2:29
2372 msgid "SCHED_GET_PRIORITY_MAX"
2376 #: build/C/man2/sched_get_priority_max.2:29
2382 #: build/C/man2/sched_get_priority_max.2:32
2383 msgid "sched_get_priority_max, sched_get_priority_min - get static priority range"
2387 #: build/C/man2/sched_get_priority_max.2:34 build/C/man2/sched_rr_get_interval.2:34 build/C/man2/sched_yield.2:34
2388 msgid "B<#include E<lt>sched.hE<gt>>"
2392 #: build/C/man2/sched_get_priority_max.2:36
2393 msgid "B<int sched_get_priority_max(int >I<policy>B<);>"
2397 #: build/C/man2/sched_get_priority_max.2:38
2398 msgid "B<int sched_get_priority_min(int >I<policy>B<);>"
2402 #: build/C/man2/sched_get_priority_max.2:58
2404 "B<sched_get_priority_max>() returns the maximum priority value that can be "
2405 "used with the scheduling algorithm identified by I<policy>. "
2406 "B<sched_get_priority_min>() returns the minimum priority value that can be "
2407 "used with the scheduling algorithm identified by I<policy>. Supported "
2408 "I<policy> values are B<SCHED_FIFO>, B<SCHED_RR>, B<SCHED_OTHER>, "
2409 "B<SCHED_BATCH>, and B<SCHED_IDLE>. Further details about these policies can "
2410 "be found in B<sched_setscheduler>(2)."
2414 #: build/C/man2/sched_get_priority_max.2:67
2416 "Processes with numerically higher priority values are scheduled before "
2417 "processes with numerically lower priority values. Thus, the value returned "
2418 "by B<sched_get_priority_max>() will be greater than the value returned by "
2419 "B<sched_get_priority_min>()."
2423 #: build/C/man2/sched_get_priority_max.2:79
2425 "Linux allows the static priority value range 1 to 99 for B<SCHED_FIFO> and "
2426 "B<SCHED_RR> and the priority 0 for B<SCHED_OTHER>, B<SCHED_BATCH>, and "
2427 "B<SCHED_IDLE>. Scheduling priority ranges for the various policies are not "
2432 #: build/C/man2/sched_get_priority_max.2:91
2434 "The range of scheduling priorities may vary on other POSIX systems, thus it "
2435 "is a good idea for portable applications to use a virtual priority range and "
2436 "map it to the interval given by B<sched_get_priority_max>() and "
2437 "B<sched_get_priority_min>(). POSIX.1-2001 requires a spread of at least 32 "
2438 "between the maximum and the minimum values for B<SCHED_FIFO> and "
2443 #: build/C/man2/sched_get_priority_max.2:100
2445 "POSIX systems on which B<sched_get_priority_max>() and "
2446 "B<sched_get_priority_min>() are available define "
2447 "B<_POSIX_PRIORITY_SCHEDULING> in I<E<lt>unistd.hE<gt>>."
2451 #: build/C/man2/sched_get_priority_max.2:110
2453 "On success, B<sched_get_priority_max>() and B<sched_get_priority_min>() "
2454 "return the maximum/minimum priority value for the named scheduling policy. "
2455 "On error, -1 is returned, and I<errno> is set appropriately."
2459 #: build/C/man2/sched_get_priority_max.2:116
2460 msgid "The argument I<policy> does not identify a defined scheduling policy."
2464 #: build/C/man2/sched_get_priority_max.2:118 build/C/man2/sched_rr_get_interval.2:96 build/C/man2/sched_setparam.2:112 build/C/man2/sched_yield.2:54
2465 msgid "POSIX.1-2001."
2469 #: build/C/man2/sched_get_priority_max.2:127
2471 "B<sched_getaffinity>(2), B<sched_getparam>(2), B<sched_getscheduler>(2), "
2472 "B<sched_setaffinity>(2), B<sched_setparam>(2), B<sched_setscheduler>(2)"
2476 #: build/C/man2/sched_get_priority_max.2:130 build/C/man2/sched_rr_get_interval.2:138 build/C/man2/sched_setparam.2:134 build/C/man2/sched_setscheduler.2:564 build/C/man2/sched_yield.2:85
2478 "I<Programming for the real world - POSIX.4> by Bill O. Gallmeister, O'Reilly "
2479 "& Associates, Inc., ISBN 1-56592-074-0."
2483 #: build/C/man3/sched_getcpu.3:26
2485 msgid "SCHED_GETCPU"
2489 #: build/C/man3/sched_getcpu.3:26 build/C/man2/unshare.2:20
2495 #: build/C/man3/sched_getcpu.3:29
2496 msgid "sched_getcpu - determine CPU on which the calling thread is running"
2500 #: build/C/man3/sched_getcpu.3:34
2502 msgid "B<int sched_getcpu(void);>\n"
2506 #: build/C/man3/sched_getcpu.3:39 build/C/man2/unshare.2:33
2507 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
2511 #: build/C/man3/sched_getcpu.3:42
2512 msgid "B<sched_getcpu>():"
2516 #: build/C/man3/sched_getcpu.3:58
2518 "B<sched_getcpu>() returns the number of the CPU on which the calling thread "
2519 "is currently executing."
2523 #: build/C/man3/sched_getcpu.3:65
2525 "On success, B<sched_getcpu>() returns a nonnegative CPU number. On error, "
2526 "-1 is returned and I<errno> is set to indicate the error."
2530 #: build/C/man3/sched_getcpu.3:66 build/C/man2/sched_rr_get_interval.2:87
2536 #: build/C/man3/sched_getcpu.3:70
2537 msgid "This kernel does not implement B<getcpu>(2)."
2541 #: build/C/man3/sched_getcpu.3:72
2542 msgid "This function is available since glibc 2.6."
2546 #: build/C/man3/sched_getcpu.3:75
2547 msgid "B<sched_getcpu>() is glibc-specific."
2551 #: build/C/man3/sched_getcpu.3:77
2556 #: build/C/man3/sched_getcpu.3:81
2558 msgid "cpu = sched_getcpu();\n"
2562 #: build/C/man3/sched_getcpu.3:87
2563 msgid "is equivalent to the following B<getcpu>(2) call:"
2567 #: build/C/man3/sched_getcpu.3:93
2571 "s = getcpu(&c, NULL, NULL);\n"
2572 "cpu = (s == -1) ? s : c;\n"
2576 #: build/C/man3/sched_getcpu.3:97
2577 msgid "B<getcpu>(2)"
2581 #: build/C/man2/sched_rr_get_interval.2:29
2583 msgid "SCHED_RR_GET_INTERVAL"
2587 #: build/C/man2/sched_rr_get_interval.2:29
2593 #: build/C/man2/sched_rr_get_interval.2:32
2594 msgid "sched_rr_get_interval - get the SCHED_RR interval for the named process"
2598 #: build/C/man2/sched_rr_get_interval.2:36
2599 msgid "B<int sched_rr_get_interval(pid_t >I<pid>B<, struct timespec * >I<tp>B<);>"
2603 #: build/C/man2/sched_rr_get_interval.2:47
2605 "B<sched_rr_get_interval>() writes into the I<timespec> structure pointed to "
2606 "by I<tp> the round-robin time quantum for the process identified by I<pid>. "
2607 "The specified process should be running under the B<SCHED_RR> scheduling "
2612 #: build/C/man2/sched_rr_get_interval.2:51
2613 msgid "The I<timespec> structure has the following form:"
2617 #: build/C/man2/sched_rr_get_interval.2:58
2620 "struct timespec {\n"
2621 " time_t tv_sec; /* seconds */\n"
2622 " long tv_nsec; /* nanoseconds */\n"
2626 #. FIXME . On Linux, sched_rr_get_interval()
2627 #. returns the timeslice for SCHED_OTHER processes -- this timeslice
2628 #. is influenced by the nice value.
2629 #. For SCHED_FIFO processes, this always returns 0.
2631 #. The round-robin time quantum value is not alterable under Linux
2634 #: build/C/man2/sched_rr_get_interval.2:73
2636 "If I<pid> is zero, the time quantum for the calling process is written into "
2641 #: build/C/man2/sched_rr_get_interval.2:80
2643 "On success, B<sched_rr_get_interval>() returns 0. On error, -1 is "
2644 "returned, and I<errno> is set appropriately."
2648 #: build/C/man2/sched_rr_get_interval.2:81 build/C/man2/sched_setaffinity.2:117
2654 #: build/C/man2/sched_rr_get_interval.2:84
2655 msgid "Problem with copying information to user space."
2659 #: build/C/man2/sched_rr_get_interval.2:87
2660 msgid "Invalid pid."
2664 #: build/C/man2/sched_rr_get_interval.2:90
2665 msgid "The system call is not yet implemented (only on rather old kernels)."
2669 #: build/C/man2/sched_rr_get_interval.2:94
2670 msgid "Could not find a process with the ID I<pid>."
2674 #: build/C/man2/sched_rr_get_interval.2:103
2676 "POSIX systems on which B<sched_rr_get_interval>() is available define "
2677 "B<_POSIX_PRIORITY_SCHEDULING> in I<E<lt>unistd.hE<gt>>."
2681 #: build/C/man2/sched_rr_get_interval.2:103
2686 #. commit a4ec24b48ddef1e93f7578be53270f0b95ad666c
2688 #: build/C/man2/sched_rr_get_interval.2:117
2690 "POSIX does not specify any mechanism for controlling the size of the "
2691 "round-robin time quantum. Older Linux kernels provide a (nonportable) "
2692 "method of doing this. The quantum can be controlled by adjusting the "
2693 "process's nice value (see B<setpriority>(2)). Assigning a negative (i.e., "
2694 "high) nice value results in a longer quantum; assigning a positive (i.e., "
2695 "low) nice value results in a shorter quantum. The default quantum is 0.1 "
2696 "seconds; the degree to which changing the nice value affects the quantum has "
2697 "varied somewhat across kernel versions. This method of adjusting the "
2698 "quantum was removed starting with Linux 2.6.24."
2701 #. commit ce0dbbbb30aee6a835511d5be446462388ba9eee
2703 #. As of Linux 1.3.81
2704 #. .BR sched_rr_get_interval ()
2705 #. returns with error
2706 #. ENOSYS, because SCHED_RR has not yet been fully implemented and tested
2709 #: build/C/man2/sched_rr_get_interval.2:132
2711 "Linux 3.9 added a new mechanism for adjusting (and viewing) the B<SCHED_RR> "
2712 "quantum: the I</proc/sys/kernel/sched_rr_timeslice_ms> file exposes the "
2713 "quantum as a millisecond value, whose default is 100. Writing 0 to this "
2714 "file resets the quantum to the default value."
2718 #: build/C/man2/sched_rr_get_interval.2:135 build/C/man2/sched_setaffinity.2:177
2719 msgid "B<sched_setscheduler>(2) has a description of the Linux scheduling scheme."
2723 #: build/C/man2/sched_setaffinity.2:34
2725 msgid "SCHED_SETAFFINITY"
2729 #: build/C/man2/sched_setaffinity.2:34 build/C/man2/sched_setparam.2:30 build/C/man2/sched_setscheduler.2:46
2735 #: build/C/man2/sched_setaffinity.2:38
2737 "sched_setaffinity, sched_getaffinity - set and get a thread's CPU affinity "
2742 #: build/C/man2/sched_setaffinity.2:45
2745 "B<int sched_setaffinity(pid_t >I<pid>B<, size_t >I<cpusetsize>B<,>\n"
2746 "B< cpu_set_t *>I<mask>B<);>\n"
2750 #: build/C/man2/sched_setaffinity.2:48
2753 "B<int sched_getaffinity(pid_t >I<pid>B<, size_t >I<cpusetsize>B<,>\n"
2754 "B< cpu_set_t *>I<mask>B<);>\n"
2758 #: build/C/man2/sched_setaffinity.2:63
2760 "A thread's CPU affinity mask determines the set of CPUs on which it is "
2761 "eligible to run. On a multiprocessor system, setting the CPU affinity mask "
2762 "can be used to obtain performance benefits. For example, by dedicating one "
2763 "CPU to a particular thread (i.e., setting the affinity mask of that thread "
2764 "to specify a single CPU, and setting the affinity mask of all other threads "
2765 "to exclude that CPU), it is possible to ensure maximum execution speed for "
2766 "that thread. Restricting a thread to run on a single CPU also avoids the "
2767 "performance cost caused by the cache invalidation that occurs when a thread "
2768 "ceases to execute on one CPU and then recommences execution on a different "
2773 #: build/C/man2/sched_setaffinity.2:70
2775 "A CPU affinity mask is represented by the I<cpu_set_t> structure, a \"CPU "
2776 "set\", pointed to by I<mask>. A set of macros for manipulating CPU sets is "
2777 "described in B<CPU_SET>(3)."
2781 #: build/C/man2/sched_setaffinity.2:85
2783 "B<sched_setaffinity>() sets the CPU affinity mask of the thread whose ID is "
2784 "I<pid> to the value specified by I<mask>. If I<pid> is zero, then the "
2785 "calling thread is used. The argument I<cpusetsize> is the length (in bytes) "
2786 "of the data pointed to by I<mask>. Normally this argument would be "
2787 "specified as I<sizeof(cpu_set_t)>."
2791 #: build/C/man2/sched_setaffinity.2:92
2793 "If the thread specified by I<pid> is not currently running on one of the "
2794 "CPUs specified in I<mask>, then that thread is migrated to one of the CPUs "
2795 "specified in I<mask>."
2799 #: build/C/man2/sched_setaffinity.2:107
2801 "B<sched_getaffinity>() writes the affinity mask of the thread whose ID is "
2802 "I<pid> into the I<cpu_set_t> structure pointed to by I<mask>. The "
2803 "I<cpusetsize> argument specifies the size (in bytes) of I<mask>. If I<pid> "
2804 "is zero, then the mask of the calling thread is returned."
2808 #: build/C/man2/sched_setaffinity.2:116
2810 "On success, B<sched_setaffinity>() and B<sched_getaffinity>() return 0. "
2811 "On error, -1 is returned, and I<errno> is set appropriately."
2815 #: build/C/man2/sched_setaffinity.2:120
2816 msgid "A supplied memory address was invalid."
2820 #: build/C/man2/sched_setaffinity.2:128
2822 "The affinity bit mask I<mask> contains no processors that are currently "
2823 "physically on the system and permitted to the thread according to any "
2824 "restrictions that may be imposed by the \"cpuset\" mechanism described in "
2829 #: build/C/man2/sched_setaffinity.2:135
2831 "(B<sched_getaffinity>() and, in kernels before 2.6.9, "
2832 "B<sched_setaffinity>()) I<cpusetsize> is smaller than the size of the "
2833 "affinity mask used by the kernel."
2837 #: build/C/man2/sched_setaffinity.2:145
2839 "(B<sched_setaffinity>()) The calling thread does not have appropriate "
2840 "privileges. The caller needs an effective user ID equal to the real user ID "
2841 "or effective user ID of the thread identified by I<pid>, or it must possess "
2842 "the B<CAP_SYS_NICE> capability."
2846 #: build/C/man2/sched_setaffinity.2:148 build/C/man2/sched_setscheduler.2:445
2847 msgid "The thread whose ID is I<pid> could not be found."
2851 #: build/C/man2/sched_setaffinity.2:159
2853 "The CPU affinity system calls were introduced in Linux kernel 2.5.8. The "
2854 "system call wrappers were introduced in glibc 2.3. Initially, the glibc "
2855 "interfaces included a I<cpusetsize> argument, typed as I<unsigned int>. In "
2856 "glibc 2.3.3, the I<cpusetsize> argument was removed, but was then restored "
2857 "in glibc 2.3.4, with type I<size_t>."
2861 #: build/C/man2/sched_setaffinity.2:161
2862 msgid "These system calls are Linux-specific."
2866 #: build/C/man2/sched_setaffinity.2:174
2868 "After a call to B<sched_setaffinity>(), the set of CPUs on which the thread "
2869 "will actually run is the intersection of the set specified in the I<mask> "
2870 "argument and the set of CPUs actually present on the system. The system may "
2871 "further restrict the set of CPUs on which the thread runs if the \"cpuset\" "
2872 "mechanism described in B<cpuset>(7) is being used. These restrictions on "
2873 "the actual set of CPUs on which the thread will run are silently imposed by "
2878 #: build/C/man2/sched_setaffinity.2:194
2880 "The affinity mask is a per-thread attribute that can be adjusted "
2881 "independently for each of the threads in a thread group. The value returned "
2882 "from a call to B<gettid>(2) can be passed in the argument I<pid>. "
2883 "Specifying I<pid> as 0 will set the attribute for the calling thread, and "
2884 "passing the value returned from a call to B<getpid>(2) will set the "
2885 "attribute for the main thread of the thread group. (If you are using the "
2886 "POSIX threads API, then use B<pthread_setaffinity_np>(3) instead of "
2887 "B<sched_setaffinity>().)"
2891 #: build/C/man2/sched_setaffinity.2:200
2893 "A child created via B<fork>(2) inherits its parent's CPU affinity mask. "
2894 "The affinity mask is preserved across an B<execve>(2)."
2898 #: build/C/man2/sched_setaffinity.2:214
2900 "This manual page describes the glibc interface for the CPU affinity calls. "
2901 "The actual system call interface is slightly different, with the I<mask> "
2902 "being typed as I<unsigned long\\ *>, reflecting the fact that the underlying "
2903 "implementation of CPU sets is a simple bit mask. On success, the raw "
2904 "B<sched_getaffinity>() system call returns the size (in bytes) of the "
2905 "I<cpumask_t> data type that is used internally by the kernel to represent "
2906 "the CPU set bit mask."
2910 #: build/C/man2/sched_setaffinity.2:233
2912 "B<taskset>(1), B<clone>(2), B<getcpu>(2), B<getpriority>(2), B<gettid>(2), "
2913 "B<nice>(2), B<sched_get_priority_max>(2), B<sched_get_priority_min>(2), "
2914 "B<sched_getscheduler>(2), B<sched_setscheduler>(2), B<setpriority>(2), "
2915 "B<CPU_SET>(3), B<pthread_setaffinity_np>(3), B<sched_getcpu>(3), "
2916 "B<capabilities>(7), B<cpuset>(7)"
2920 #: build/C/man2/sched_setparam.2:30
2922 msgid "SCHED_SETPARAM"
2926 #: build/C/man2/sched_setparam.2:33
2927 msgid "sched_setparam, sched_getparam - set and get scheduling parameters"
2931 #: build/C/man2/sched_setparam.2:38
2934 "B<int sched_setparam(pid_t >I<pid>B<, const struct sched_param "
2939 #: build/C/man2/sched_setparam.2:40
2941 msgid "B<int sched_getparam(pid_t >I<pid>B<, struct sched_param *>I<param>B<);>\n"
2945 #: build/C/man2/sched_setparam.2:46 build/C/man2/sched_setscheduler.2:65
2948 "B<struct sched_param {\n"
2950 " int >I<sched_priority>B<;\n"
2956 #: build/C/man2/sched_setparam.2:60
2958 "B<sched_setparam>() sets the scheduling parameters associated with the "
2959 "scheduling policy for the process identified by I<pid>. If I<pid> is zero, "
2960 "then the parameters of the calling process are set. The interpretation of "
2961 "the argument I<param> depends on the scheduling policy of the process "
2962 "identified by I<pid>. See B<sched_setscheduler>(2) for a description of "
2963 "the scheduling policies supported under Linux."
2967 #: build/C/man2/sched_setparam.2:66
2969 "B<sched_getparam>() retrieves the scheduling parameters for the process "
2970 "identified by I<pid>. If I<pid> is zero, then the parameters of the calling "
2971 "process are retrieved."
2975 #: build/C/man2/sched_setparam.2:75
2977 "B<sched_setparam>() checks the validity of I<param> for the scheduling "
2978 "policy of the thread. The value I<param-E<gt>sched_priority> must lie "
2979 "within the range given by B<sched_get_priority_min>(2) and "
2980 "B<sched_get_priority_max>(2)."
2984 #: build/C/man2/sched_setparam.2:79
2986 "For a discussion of the privileges and resource limits related to scheduling "
2987 "priority and policy, see B<sched_setscheduler>(2)."
2991 #: build/C/man2/sched_setparam.2:87
2993 "POSIX systems on which B<sched_setparam>() and B<sched_getparam>() are "
2994 "available define B<_POSIX_PRIORITY_SCHEDULING> in I<E<lt>unistd.hE<gt>>."
2998 #: build/C/man2/sched_setparam.2:96
3000 "On success, B<sched_setparam>() and B<sched_getparam>() return 0. On "
3001 "error, -1 is returned, and I<errno> is set appropriately."
3005 #: build/C/man2/sched_setparam.2:101
3006 msgid "The argument I<param> does not make sense for the current scheduling policy."
3010 #: build/C/man2/sched_setparam.2:107
3012 "The calling process does not have appropriate privileges (Linux: does not "
3013 "have the B<CAP_SYS_NICE> capability)."
3017 #: build/C/man2/sched_setparam.2:110
3018 msgid "The process whose ID is I<pid> could not be found."
3022 #: build/C/man2/sched_setparam.2:118
3024 "Scheduling parameters are in fact per-thread attributes on Linux; see "
3025 "B<sched_setscheduler>(2)."
3029 #: build/C/man2/sched_setparam.2:131
3031 "B<getpriority>(2), B<nice>(2), B<sched_get_priority_max>(2), "
3032 "B<sched_get_priority_min>(2), B<sched_getaffinity>(2), "
3033 "B<sched_getscheduler>(2), B<sched_setaffinity>(2), B<sched_setscheduler>(2), "
3034 "B<setpriority>(2), B<capabilities>(7)"
3038 #: build/C/man2/sched_setscheduler.2:46
3040 msgid "SCHED_SETSCHEDULER"
3044 #: build/C/man2/sched_setscheduler.2:50
3046 "sched_setscheduler, sched_getscheduler - set and get scheduling "
3051 #: build/C/man2/sched_setscheduler.2:55
3053 msgid "B<int sched_setscheduler(pid_t >I<pid>B<, int >I<policy>B<,>\n"
3057 #: build/C/man2/sched_setscheduler.2:57
3059 msgid "B< const struct sched_param *>I<param>B<);>\n"
3063 #: build/C/man2/sched_setscheduler.2:59
3065 msgid "B<int sched_getscheduler(pid_t >I<pid>B<);>\n"
3069 #: build/C/man2/sched_setscheduler.2:76
3071 "B<sched_setscheduler>() sets both the scheduling policy and the associated "
3072 "parameters for the thread whose ID is specified in I<pid>. If I<pid> equals "
3073 "zero, the scheduling policy and parameters of the calling thread will be "
3074 "set. The interpretation of the argument I<param> depends on the selected "
3075 "policy. Currently, Linux supports the following \"normal\" (i.e., "
3076 "non-real-time) scheduling policies:"
3080 #: build/C/man2/sched_setscheduler.2:76
3082 msgid "B<SCHED_OTHER>"
3085 #. In the 2.6 kernel sources, SCHED_OTHER is actually called
3088 #: build/C/man2/sched_setscheduler.2:81
3089 msgid "the standard round-robin time-sharing policy;"
3093 #: build/C/man2/sched_setscheduler.2:81
3095 msgid "B<SCHED_BATCH>"
3099 #: build/C/man2/sched_setscheduler.2:84
3100 msgid "for \"batch\" style execution of processes; and"
3104 #: build/C/man2/sched_setscheduler.2:84
3106 msgid "B<SCHED_IDLE>"
3110 #: build/C/man2/sched_setscheduler.2:89
3111 msgid "for running I<very> low priority background jobs."
3115 #: build/C/man2/sched_setscheduler.2:93
3117 "The following \"real-time\" policies are also supported, for special "
3118 "time-critical applications that need precise control over the way in which "
3119 "runnable threads are selected for execution:"
3123 #: build/C/man2/sched_setscheduler.2:93
3125 msgid "B<SCHED_FIFO>"
3129 #: build/C/man2/sched_setscheduler.2:96
3130 msgid "a first-in, first-out policy; and"
3134 #: build/C/man2/sched_setscheduler.2:96
3140 #: build/C/man2/sched_setscheduler.2:99
3141 msgid "a round-robin policy."
3145 #: build/C/man2/sched_setscheduler.2:101
3146 msgid "The semantics of each of these policies are detailed below."
3150 #: build/C/man2/sched_setscheduler.2:108
3152 "B<sched_getscheduler>() queries the scheduling policy currently applied to "
3153 "the thread identified by I<pid>. If I<pid> equals zero, the policy of the "
3154 "calling thread will be retrieved."
3158 #: build/C/man2/sched_setscheduler.2:108
3160 msgid "Scheduling policies"
3164 #: build/C/man2/sched_setscheduler.2:117
3166 "The scheduler is the kernel component that decides which runnable thread "
3167 "will be executed by the CPU next. Each thread has an associated scheduling "
3168 "policy and a I<static> scheduling priority, I<sched_priority>; these are the "
3169 "settings that are modified by B<sched_setscheduler>(). The scheduler makes "
3170 "it decisions based on knowledge of the scheduling policy and static priority "
3171 "of all threads on the system."
3175 #: build/C/man2/sched_setscheduler.2:122
3177 "For threads scheduled under one of the normal scheduling policies "
3178 "(B<SCHED_OTHER>, B<SCHED_IDLE>, B<SCHED_BATCH>), I<sched_priority> is not "
3179 "used in scheduling decisions (it must be specified as 0)."
3183 #: build/C/man2/sched_setscheduler.2:136
3185 "Processes scheduled under one of the real-time policies (B<SCHED_FIFO>, "
3186 "B<SCHED_RR>) have a I<sched_priority> value in the range 1 (low) to 99 "
3187 "(high). (As the numbers imply, real-time threads always have higher "
3188 "priority than normal threads.) Note well: POSIX.1-2001 requires an "
3189 "implementation to support only a minimum 32 distinct priority levels for the "
3190 "real-time policies, and some systems supply just this minimum. Portable "
3191 "programs should use B<sched_get_priority_min>(2) and "
3192 "B<sched_get_priority_max>(2) to find the range of priorities supported for "
3193 "a particular policy."
3197 #: build/C/man2/sched_setscheduler.2:142
3199 "Conceptually, the scheduler maintains a list of runnable threads for each "
3200 "possible I<sched_priority> value. In order to determine which thread runs "
3201 "next, the scheduler looks for the nonempty list with the highest static "
3202 "priority and selects the thread at the head of this list."
3206 #: build/C/man2/sched_setscheduler.2:146
3208 "A thread's scheduling policy determines where it will be inserted into the "
3209 "list of threads with equal static priority and how it will move inside this "
3214 #: build/C/man2/sched_setscheduler.2:154
3216 "All scheduling is preemptive: if a thread with a higher static priority "
3217 "becomes ready to run, the currently running thread will be preempted and "
3218 "returned to the wait list for its static priority level. The scheduling "
3219 "policy determines the ordering only within the list of runnable threads with "
3220 "equal static priority."
3224 #: build/C/man2/sched_setscheduler.2:154
3226 msgid "SCHED_FIFO: First in-first out scheduling"
3230 #: build/C/man2/sched_setscheduler.2:163
3232 "B<SCHED_FIFO> can be used only with static priorities higher than 0, which "
3233 "means that when a B<SCHED_FIFO> threads becomes runnable, it will always "
3234 "immediately preempt any currently running B<SCHED_OTHER>, B<SCHED_BATCH>, or "
3235 "B<SCHED_IDLE> thread. B<SCHED_FIFO> is a simple scheduling algorithm "
3236 "without time slicing. For threads scheduled under the B<SCHED_FIFO> policy, "
3237 "the following rules apply:"
3241 #: build/C/man2/sched_setscheduler.2:163 build/C/man2/sched_setscheduler.2:168 build/C/man2/sched_setscheduler.2:171 build/C/man2/sched_setscheduler.2:185 build/C/man2/sched_setscheduler.2:288 build/C/man2/sched_setscheduler.2:296 build/C/man2/sched_setscheduler.2:337 build/C/man2/sched_setscheduler.2:345 build/C/man2/sched_setscheduler.2:350 build/C/man2/sched_setscheduler.2:355
3247 #: build/C/man2/sched_setscheduler.2:168
3249 "A B<SCHED_FIFO> thread that has been preempted by another thread of higher "
3250 "priority will stay at the head of the list for its priority and will resume "
3251 "execution as soon as all threads of higher priority are blocked again."
3255 #: build/C/man2/sched_setscheduler.2:171
3257 "When a B<SCHED_FIFO> thread becomes runnable, it will be inserted at the end "
3258 "of the list for its priority."
3261 #. In 2.2.x and 2.4.x, the thread is placed at the front of the queue
3262 #. In 2.0.x, the Right Thing happened: the thread went to the back -- MTK
3264 #: build/C/man2/sched_setscheduler.2:185
3266 "A call to B<sched_setscheduler>() or B<sched_setparam>(2) will put the "
3267 "B<SCHED_FIFO> (or B<SCHED_RR>) thread identified by I<pid> at the start of "
3268 "the list if it was runnable. As a consequence, it may preempt the currently "
3269 "running thread if it has the same priority. (POSIX.1-2001 specifies that "
3270 "the thread should go to the end of the list.)"
3274 #: build/C/man2/sched_setscheduler.2:189
3275 msgid "A thread calling B<sched_yield>(2) will be put at the end of the list."
3279 #: build/C/man2/sched_setscheduler.2:193
3281 "No other events will move a thread scheduled under the B<SCHED_FIFO> policy "
3282 "in the wait list of runnable threads with equal static priority."
3286 #: build/C/man2/sched_setscheduler.2:198
3288 "A B<SCHED_FIFO> thread runs until either it is blocked by an I/O request, it "
3289 "is preempted by a higher priority thread, or it calls B<sched_yield>(2)."
3293 #: build/C/man2/sched_setscheduler.2:198
3295 msgid "SCHED_RR: Round-robin scheduling"
3298 #. On Linux 2.4, the length of the RR interval is influenced
3299 #. by the process nice value -- MTK
3301 #: build/C/man2/sched_setscheduler.2:217
3303 "B<SCHED_RR> is a simple enhancement of B<SCHED_FIFO>. Everything described "
3304 "above for B<SCHED_FIFO> also applies to B<SCHED_RR>, except that each thread "
3305 "is allowed to run only for a maximum time quantum. If a B<SCHED_RR> thread "
3306 "has been running for a time period equal to or longer than the time quantum, "
3307 "it will be put at the end of the list for its priority. A B<SCHED_RR> "
3308 "thread that has been preempted by a higher priority thread and subsequently "
3309 "resumes execution as a running thread will complete the unexpired portion of "
3310 "its round-robin time quantum. The length of the time quantum can be "
3311 "retrieved using B<sched_rr_get_interval>(2)."
3315 #: build/C/man2/sched_setscheduler.2:217
3317 msgid "SCHED_OTHER: Default Linux time-sharing scheduling"
3321 #: build/C/man2/sched_setscheduler.2:233
3323 "B<SCHED_OTHER> can be used at only static priority 0. B<SCHED_OTHER> is the "
3324 "standard Linux time-sharing scheduler that is intended for all threads that "
3325 "do not require the special real-time mechanisms. The thread to run is "
3326 "chosen from the static priority 0 list based on a I<dynamic> priority that "
3327 "is determined only inside this list. The dynamic priority is based on the "
3328 "nice value (set by B<nice>(2) or B<setpriority>(2)) and increased for each "
3329 "time quantum the thread is ready to run, but denied to run by the "
3330 "scheduler. This ensures fair progress among all B<SCHED_OTHER> threads."
3334 #: build/C/man2/sched_setscheduler.2:233
3336 msgid "SCHED_BATCH: Scheduling batch processes"
3340 #: build/C/man2/sched_setscheduler.2:245
3342 "(Since Linux 2.6.16.) B<SCHED_BATCH> can be used only at static priority "
3343 "0. This policy is similar to B<SCHED_OTHER> in that it schedules the thread "
3344 "according to its dynamic priority (based on the nice value). The difference "
3345 "is that this policy will cause the scheduler to always assume that the "
3346 "thread is CPU-intensive. Consequently, the scheduler will apply a small "
3347 "scheduling penalty with respect to wakeup behaviour, so that this thread is "
3348 "mildly disfavored in scheduling decisions."
3351 #. The following paragraph is drawn largely from the text that
3352 #. accompanied Ingo Molnar's patch for the implementation of
3354 #. commit b0a9499c3dd50d333e2aedb7e894873c58da3785
3356 #: build/C/man2/sched_setscheduler.2:255
3358 "This policy is useful for workloads that are noninteractive, but do not want "
3359 "to lower their nice value, and for workloads that want a deterministic "
3360 "scheduling policy without interactivity causing extra preemptions (between "
3361 "the workload's tasks)."
3365 #: build/C/man2/sched_setscheduler.2:255
3367 msgid "SCHED_IDLE: Scheduling very low priority jobs"
3371 #: build/C/man2/sched_setscheduler.2:259
3373 "(Since Linux 2.6.23.) B<SCHED_IDLE> can be used only at static priority 0; "
3374 "the process nice value has no influence for this policy."
3378 #: build/C/man2/sched_setscheduler.2:267
3380 "This policy is intended for running jobs at extremely low priority (lower "
3381 "even than a +19 nice value with the B<SCHED_OTHER> or B<SCHED_BATCH> "
3386 #: build/C/man2/sched_setscheduler.2:267
3388 msgid "Resetting scheduling policy for child processes"
3392 #: build/C/man2/sched_setscheduler.2:283
3394 "Since Linux 2.6.32, the B<SCHED_RESET_ON_FORK> flag can be ORed in I<policy> "
3395 "when calling B<sched_setscheduler>(). As a result of including this flag, "
3396 "children created by B<fork>(2) do not inherit privileged scheduling "
3397 "policies. This feature is intended for media-playback applications, and can "
3398 "be used to prevent applications evading the B<RLIMIT_RTTIME> resource limit "
3399 "(see B<getrlimit>(2)) by creating multiple child processes."
3403 #: build/C/man2/sched_setscheduler.2:288
3405 "More precisely, if the B<SCHED_RESET_ON_FORK> flag is specified, the "
3406 "following rules apply for subsequently created children:"
3410 #: build/C/man2/sched_setscheduler.2:296
3412 "If the calling thread has a scheduling policy of B<SCHED_FIFO> or "
3413 "B<SCHED_RR>, the policy is reset to B<SCHED_OTHER> in child processes."
3417 #: build/C/man2/sched_setscheduler.2:299
3419 "If the calling process has a negative nice value, the nice value is reset to "
3420 "zero in child processes."
3424 #: build/C/man2/sched_setscheduler.2:308
3426 "After the B<SCHED_RESET_ON_FORK> flag has been enabled, it can be reset only "
3427 "if the thread has the B<CAP_SYS_NICE> capability. This flag is disabled in "
3428 "child processes created by B<fork>(2)."
3432 #: build/C/man2/sched_setscheduler.2:314
3434 "The B<SCHED_RESET_ON_FORK> flag is visible in the policy value returned by "
3435 "B<sched_getscheduler>()"
3439 #: build/C/man2/sched_setscheduler.2:314
3441 msgid "Privileges and resource limits"
3445 #: build/C/man2/sched_setscheduler.2:327
3447 "In Linux kernels before 2.6.12, only privileged (B<CAP_SYS_NICE>) threads "
3448 "can set a nonzero static priority (i.e., set a real-time scheduling "
3449 "policy). The only change that an unprivileged thread can make is to set the "
3450 "B<SCHED_OTHER> policy, and this can be done only if the effective user ID of "
3451 "the caller of B<sched_setscheduler>() matches the real or effective user ID "
3452 "of the target thread (i.e., the thread specified by I<pid>) whose policy is "
3457 #: build/C/man2/sched_setscheduler.2:337
3459 "Since Linux 2.6.12, the B<RLIMIT_RTPRIO> resource limit defines a ceiling on "
3460 "an unprivileged thread's static priority for the B<SCHED_RR> and "
3461 "B<SCHED_FIFO> policies. The rules for changing scheduling policy and "
3462 "priority are as follows:"
3466 #: build/C/man2/sched_setscheduler.2:345
3468 "If an unprivileged thread has a nonzero B<RLIMIT_RTPRIO> soft limit, then it "
3469 "can change its scheduling policy and priority, subject to the restriction "
3470 "that the priority cannot be set to a value higher than the maximum of its "
3471 "current priority and its B<RLIMIT_RTPRIO> soft limit."
3475 #: build/C/man2/sched_setscheduler.2:350
3477 "If the B<RLIMIT_RTPRIO> soft limit is 0, then the only permitted changes are "
3478 "to lower the priority, or to switch to a non-real-time policy."
3482 #: build/C/man2/sched_setscheduler.2:355
3484 "Subject to the same rules, another unprivileged thread can also make these "
3485 "changes, as long as the effective user ID of the thread making the change "
3486 "matches the real or effective user ID of the target thread."
3489 #. commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8
3491 #: build/C/man2/sched_setscheduler.2:373
3493 "Special rules apply for the B<SCHED_IDLE>. In Linux kernels before 2.6.39, "
3494 "an unprivileged thread operating under this policy cannot change its policy, "
3495 "regardless of the value of its B<RLIMIT_RTPRIO> resource limit. In Linux "
3496 "kernels since 2.6.39, an unprivileged thread can switch to either the "
3497 "B<SCHED_BATCH> or the B<SCHED_NORMAL> policy so long as its nice value falls "
3498 "within the range permitted by its B<RLIMIT_NICE> resource limit (see "
3503 #: build/C/man2/sched_setscheduler.2:384
3505 "Privileged (B<CAP_SYS_NICE>) threads ignore the B<RLIMIT_RTPRIO> limit; as "
3506 "with older kernels, they can make arbitrary changes to scheduling policy and "
3507 "priority. See B<getrlimit>(2) for further information on B<RLIMIT_RTPRIO>."
3511 #: build/C/man2/sched_setscheduler.2:384
3513 msgid "Response time"
3517 #. .BR request_irq (9).
3519 #: build/C/man2/sched_setscheduler.2:392
3521 "A blocked high priority thread waiting for the I/O has a certain response "
3522 "time before it is scheduled again. The device driver writer can greatly "
3523 "reduce this response time by using a \"slow interrupt\" interrupt handler."
3527 #: build/C/man2/sched_setscheduler.2:392
3529 msgid "Miscellaneous"
3533 #: build/C/man2/sched_setscheduler.2:397
3535 "Child processes inherit the scheduling policy and parameters across a "
3536 "B<fork>(2). The scheduling policy and parameters are preserved across "
3541 #: build/C/man2/sched_setscheduler.2:403
3543 "Memory locking is usually needed for real-time processes to avoid paging "
3544 "delays; this can be done with B<mlock>(2) or B<mlockall>(2)."
3548 #: build/C/man2/sched_setscheduler.2:415
3550 "Since a nonblocking infinite loop in a thread scheduled under B<SCHED_FIFO> "
3551 "or B<SCHED_RR> will block all threads with lower priority forever, a "
3552 "software developer should always keep available on the console a shell "
3553 "scheduled under a higher static priority than the tested application. This "
3554 "will allow an emergency kill of tested real-time applications that do not "
3555 "block or terminate as expected. See also the description of the "
3556 "B<RLIMIT_RTTIME> resource limit in B<getrlimit>(2)."
3560 #: build/C/man2/sched_setscheduler.2:423
3562 "POSIX systems on which B<sched_setscheduler>() and B<sched_getscheduler>() "
3563 "are available define B<_POSIX_PRIORITY_SCHEDULING> in I<E<lt>unistd.hE<gt>>."
3567 #: build/C/man2/sched_setscheduler.2:433
3569 "On success, B<sched_setscheduler>() returns zero. On success, "
3570 "B<sched_getscheduler>() returns the policy for the thread (a nonnegative "
3571 "integer). On error, -1 is returned, and I<errno> is set appropriately."
3575 #: build/C/man2/sched_setscheduler.2:439
3577 "The scheduling I<policy> is not one of the recognized policies, I<param> is "
3578 "NULL, or I<param> does not make sense for the I<policy>."
3582 #: build/C/man2/sched_setscheduler.2:442
3583 msgid "The calling thread does not have appropriate privileges."
3587 #: build/C/man2/sched_setscheduler.2:448
3589 "POSIX.1-2001 (but see BUGS below). The B<SCHED_BATCH> and B<SCHED_IDLE> "
3590 "policies are Linux-specific."
3594 #: build/C/man2/sched_setscheduler.2:456
3596 "POSIX.1 does not detail the permissions that an unprivileged thread requires "
3597 "in order to call B<sched_setscheduler>(), and details vary across systems. "
3598 "For example, the Solaris 7 manual page says that the real or effective user "
3599 "ID of the caller must match the real user ID or the save set-user-ID of the "
3604 #: build/C/man2/sched_setscheduler.2:477
3606 "The scheduling policy and parameters are in fact per-thread attributes on "
3607 "Linux. The value returned from a call to B<gettid>(2) can be passed in the "
3608 "argument I<pid>. Specifying I<pid> as 0 will operate on the attribute for "
3609 "the calling thread, and passing the value returned from a call to "
3610 "B<getpid>(2) will operate on the attribute for the main thread of the "
3611 "thread group. (If you are using the POSIX threads API, then use "
3612 "B<pthread_setschedparam>(3), B<pthread_getschedparam>(3), and "
3613 "B<pthread_setschedprio>(3), instead of the B<sched_*>(2) system calls.)"
3617 #: build/C/man2/sched_setscheduler.2:487
3619 "Originally, Standard Linux was intended as a general-purpose operating "
3620 "system being able to handle background processes, interactive applications, "
3621 "and less demanding real-time applications (applications that need to usually "
3622 "meet timing deadlines). Although the Linux kernel 2.6 allowed for kernel "
3623 "preemption and the newly introduced O(1) scheduler ensures that the time "
3624 "needed to schedule is fixed and deterministic irrespective of the number of "
3625 "active tasks, true real-time computing was not possible up to kernel version "
3630 #: build/C/man2/sched_setscheduler.2:487
3632 msgid "Real-time features in the mainline Linux kernel"
3635 #. FIXME . Probably this text will need some minor tweaking
3636 #. by about the time of 2.6.30; ask Carsten Emde about this then.
3638 #: build/C/man2/sched_setscheduler.2:501
3640 "From kernel version 2.6.18 onward, however, Linux is gradually becoming "
3641 "equipped with real-time capabilities, most of which are derived from the "
3642 "former I<realtime-preempt> patches developed by Ingo Molnar, Thomas "
3643 "Gleixner, Steven Rostedt, and others. Until the patches have been "
3644 "completely merged into the mainline kernel (this is expected to be around "
3645 "kernel version 2.6.30), they must be installed to achieve the best real-time "
3646 "performance. These patches are named:"
3650 #: build/C/man2/sched_setscheduler.2:505
3652 msgid "patch-I<kernelversion>-rtI<patchversion>\n"
3656 #: build/C/man2/sched_setscheduler.2:511
3658 "and can be downloaded from E<.UR "
3659 "http://www.kernel.org\\:/pub\\:/linux\\:/kernel\\:/projects\\:/rt/> E<.UE .>"
3663 #: build/C/man2/sched_setscheduler.2:520
3665 "Without the patches and prior to their full inclusion into the mainline "
3666 "kernel, the kernel configuration offers only the three preemption classes "
3667 "B<CONFIG_PREEMPT_NONE>, B<CONFIG_PREEMPT_VOLUNTARY>, and "
3668 "B<CONFIG_PREEMPT_DESKTOP> which respectively provide no, some, and "
3669 "considerable reduction of the worst-case scheduling latency."
3673 #: build/C/man2/sched_setscheduler.2:531
3675 "With the patches applied or after their full inclusion into the mainline "
3676 "kernel, the additional configuration item B<CONFIG_PREEMPT_RT> becomes "
3677 "available. If this is selected, Linux is transformed into a regular "
3678 "real-time operating system. The FIFO and RR scheduling policies that can be "
3679 "selected using B<sched_setscheduler>() are then used to run a thread with "
3680 "true real-time priority and a minimum worst-case scheduling latency."
3684 #: build/C/man2/sched_setscheduler.2:539
3686 "POSIX says that on success, B<sched_setscheduler>() should return the "
3687 "previous scheduling policy. Linux B<sched_setscheduler>() does not conform "
3688 "to this requirement, since it always returns 0 on success."
3692 #: build/C/man2/sched_setscheduler.2:560
3694 "B<chrt>(1), B<getpriority>(2), B<mlock>(2), B<mlockall>(2), B<munlock>(2), "
3695 "B<munlockall>(2), B<nice>(2), B<sched_get_priority_max>(2), "
3696 "B<sched_get_priority_min>(2), B<sched_getaffinity>(2), B<sched_getparam>(2), "
3697 "B<sched_rr_get_interval>(2), B<sched_setaffinity>(2), B<sched_setparam>(2), "
3698 "B<sched_yield>(2), B<setpriority>(2), B<capabilities>(7), B<cpuset>(7)"
3702 #: build/C/man2/sched_setscheduler.2:567
3703 msgid "The Linux kernel source file I<Documentation/scheduler/sched-rt-group.txt>"
3707 #: build/C/man2/sched_yield.2:29
3713 #: build/C/man2/sched_yield.2:29
3719 #: build/C/man2/sched_yield.2:32
3720 msgid "sched_yield - yield the processor"
3724 #: build/C/man2/sched_yield.2:36
3725 msgid "B<int sched_yield(void);>"
3729 #: build/C/man2/sched_yield.2:41
3731 "B<sched_yield>() causes the calling thread to relinquish the CPU. The "
3732 "thread is moved to the end of the queue for its static priority and a new "
3733 "thread gets to run."
3737 #: build/C/man2/sched_yield.2:48
3739 "On success, B<sched_yield>() returns 0. On error, -1 is returned, and "
3740 "I<errno> is set appropriately."
3744 #: build/C/man2/sched_yield.2:52
3745 msgid "In the Linux implementation, B<sched_yield>() always succeeds."
3749 #: build/C/man2/sched_yield.2:59
3751 "If the calling thread is the only thread in the highest priority list at "
3752 "that time, it will continue to run after a call to B<sched_yield>()."
3756 #: build/C/man2/sched_yield.2:66
3758 "POSIX systems on which B<sched_yield>() is available define "
3759 "B<_POSIX_PRIORITY_SCHEDULING> in I<E<lt>unistd.hE<gt>>."
3763 #: build/C/man2/sched_yield.2:79
3765 "Strategic calls to B<sched_yield>() can improve performance by giving other "
3766 "threads or processes a chance to run when (heavily) contended resources "
3767 "(e.g., mutexes) have been released by the caller. Avoid calling "
3768 "B<sched_yield>() unnecessarily or inappropriately (e.g., when resources "
3769 "needed by other schedulable threads are still held by the caller), since "
3770 "doing so will result in unnecessary context switches, which will degrade "
3771 "system performance."
3775 #: build/C/man2/sched_yield.2:82
3776 msgid "B<sched_setscheduler>(2) for a description of Linux scheduling"
3780 #: build/C/man2/setns.2:8
3786 #: build/C/man2/setns.2:8
3792 #: build/C/man2/setns.2:11
3793 msgid "setns - reassociate thread with a namespace"
3797 #: build/C/man2/setns.2:17
3799 msgid "B<int setns(int >I<fd>B<, int >I<nstype>B<);>\n"
3803 #: build/C/man2/setns.2:21
3805 "Given a file descriptor referring to a namespace, reassociate the calling "
3806 "thread with that namespace."
3810 #: build/C/man2/setns.2:34
3812 "The I<fd> argument is a file descriptor referring to one of the namespace "
3813 "entries in a I</proc/[pid]/ns/> directory; see B<proc>(5) for further "
3814 "information on I</proc/[pid]/ns/>. The calling thread will be reassociated "
3815 "with the corresponding namespace, subject to any constraints imposed by the "
3816 "I<nstype> argument."
3820 #: build/C/man2/setns.2:40
3822 "The I<nstype> argument specifies which type of namespace the calling thread "
3823 "may be reassociated with. This argument can have one of the following "
3828 #: build/C/man2/setns.2:40
3834 #: build/C/man2/setns.2:43
3835 msgid "Allow any type of namespace to be joined."
3839 #: build/C/man2/setns.2:43
3841 msgid "B<CLONE_NEWIPC>"
3845 #: build/C/man2/setns.2:47
3846 msgid "I<fd> must refer to an IPC namespace."
3850 #: build/C/man2/setns.2:47
3852 msgid "B<CLONE_NEWNET>"
3856 #: build/C/man2/setns.2:51
3857 msgid "I<fd> must refer to a network namespace."
3861 #: build/C/man2/setns.2:51
3863 msgid "B<CLONE_NEWUTS>"
3867 #: build/C/man2/setns.2:55
3868 msgid "I<fd> must refer to a UTS namespace."
3872 #: build/C/man2/setns.2:70
3874 "Specifying I<nstype> as 0 suffices if the caller knows (or does not care) "
3875 "what type of namespace is referred to by I<fd>. Specifying a nonzero value "
3876 "for I<nstype> is useful if the caller does not know what type of namespace "
3877 "is referred to by I<fd> and wants to ensure that the namespace is of a "
3878 "particular type. (The caller might not know the type of the namespace "
3879 "referred to by I<fd> if the file descriptor was opened by another process "
3880 "and, for example, passed to the caller via a UNIX domain socket.)"
3884 #: build/C/man2/setns.2:77
3886 "On success, I<setns>() returns 0. On failure, -1 is returned and I<errno> "
3887 "is set to indicate the error."
3891 #: build/C/man2/setns.2:82
3892 msgid "I<fd> is not a valid file descriptor."
3896 #: build/C/man2/setns.2:89
3898 "I<fd> refers to a namespace whose type does not match that specified in "
3899 "I<nstype>, or there is problem with reassociating the the thread with the "
3900 "specified namespace."
3904 #: build/C/man2/setns.2:92
3905 msgid "Cannot allocate sufficient memory to change the specified namespace."
3909 #: build/C/man2/setns.2:97
3911 "The calling thread did not have the required privilege (B<CAP_SYS_ADMIN>) "
3912 "for this operation."
3916 #: build/C/man2/setns.2:102
3918 "The B<setns>() system call first appeared in Linux in kernel 3.0; library "
3919 "support was added to glibc in version 2.14."
3923 #: build/C/man2/setns.2:106
3924 msgid "The B<setns>() system call is Linux-specific."
3928 #: build/C/man2/setns.2:112
3930 "Not all of the attributes that can be shared when a new thread is created "
3931 "using B<clone>(2) can be changed using B<setns>()."
3935 #: build/C/man2/setns.2:121
3937 "The program below takes two or more arguments. The first argument specifies "
3938 "the pathname of a namespace file in an existing I</proc/[pid]/ns/> "
3939 "directory. The remaining arguments specify a command and its arguments. "
3940 "The program opens the namespace file, joins that namespace using B<setns>(), "
3941 "and executes the specified command inside that namespace."
3945 #: build/C/man2/setns.2:131
3947 "The following shell session demonstrates the use of this program (compiled "
3948 "as a binary named I<ns_exec>) in conjunction with the B<CLONE_NEWUTS> "
3949 "example program in the B<clone>(2) man page (complied as a binary named "
3954 #: build/C/man2/setns.2:139
3956 "We begin by executing the example program in B<clone>(2) in the "
3957 "background. That program creates a child in a separate UTS namespace. The "
3958 "child changes the hostname in its namespace, and then both processes display "
3959 "the hostnames in their UTS namespaces, so that we can see that they are "
3964 #: build/C/man2/setns.2:151
3967 "$ B<su> # Need privilege for namespace operations\n"
3969 "# B<./newuts bizarro &>\n"
3971 "clone() returned 3550\n"
3972 "uts.nodename in child: bizarro\n"
3973 "uts.nodename in parent: antero\n"
3974 "# B<uname -n> # Verify hostname in the shell\n"
3979 #: build/C/man2/setns.2:158
3981 "We then run the program shown below, using it to execute a shell. Inside "
3982 "that shell, we verify that the hostname is the one set by the child created "
3983 "by the first program:"
3987 #: build/C/man2/setns.2:164
3990 "# B<./ns_exec /proc/3550/ns/uts /bin/bash>\n"
3991 "# B<uname -n> # Executed in shell started by ns_exec\n"
3996 #: build/C/man2/setns.2:174
3999 "#define _GNU_SOURCE\n"
4000 "#include E<lt>fcntl.hE<gt>\n"
4001 "#include E<lt>sched.hE<gt>\n"
4002 "#include E<lt>unistd.hE<gt>\n"
4003 "#include E<lt>stdlib.hE<gt>\n"
4004 "#include E<lt>stdio.hE<gt>\n"
4008 #: build/C/man2/setns.2:182
4012 "main(int argc, char *argv[])\n"
4018 #: build/C/man2/setns.2:187
4021 " if (argc E<lt> 3) {\n"
4022 " fprintf(stderr, \"%s /proc/PID/ns/FILE cmd args...\\en\", "
4024 " exit(EXIT_FAILURE);\n"
4029 #: build/C/man2/setns.2:191
4032 " fd = open(argv[1], O_RDONLY); /* Get descriptor for namespace */\n"
4034 " errExit(\"open\");\n"
4038 #: build/C/man2/setns.2:194
4041 " if (setns(fd, 0) == -1) /* Join that namespace */\n"
4042 " errExit(\"setns\");\n"
4046 #: build/C/man2/setns.2:198
4049 " execvp(argv[2], &argv[2]); /* Execute a command in namespace */\n"
4050 " errExit(\"execvp\");\n"
4055 #: build/C/man2/setns.2:205
4056 msgid "B<clone>(2), B<fork>(2), B<vfork>(2), B<proc>(5), B<unix>(7)"
4060 #: build/C/man2/unshare.2:20
4066 #: build/C/man2/unshare.2:23
4067 msgid "unshare - disassociate parts of the process execution context"
4071 #: build/C/man2/unshare.2:28
4073 msgid "B<int unshare(int >I<flags>B<);>\n"
4077 #: build/C/man2/unshare.2:36
4078 msgid "B<unshare>():"
4082 #: build/C/man2/unshare.2:62
4084 "B<unshare>() allows a process to disassociate parts of its execution "
4085 "context that are currently being shared with other processes. Part of the "
4086 "execution context, such as the mount namespace, is shared implicitly when a "
4087 "new process is created using B<fork>(2) or B<vfork>(2), while other parts, "
4088 "such as virtual memory, may be shared by explicit request when creating a "
4089 "process using B<clone>(2)."
4093 #: build/C/man2/unshare.2:67
4095 "The main use of B<unshare>() is to allow a process to control its shared "
4096 "execution context without creating a new process."
4100 #: build/C/man2/unshare.2:74
4102 "The I<flags> argument is a bit mask that specifies which parts of the "
4103 "execution context should be unshared. This argument is specified by ORing "
4104 "together zero or more of the following constants:"
4108 #: build/C/man2/unshare.2:74
4110 msgid "B<CLONE_FILES>"
4114 #: build/C/man2/unshare.2:82
4116 "Reverse the effect of the B<clone>(2) B<CLONE_FILES> flag. Unshare the "
4117 "file descriptor table, so that the calling process no longer shares its file "
4118 "descriptors with any other process."
4122 #: build/C/man2/unshare.2:82
4128 #: build/C/man2/unshare.2:96
4130 "Reverse the effect of the B<clone>(2) B<CLONE_FS> flag. Unshare filesystem "
4131 "attributes, so that the calling process no longer shares its root directory "
4132 "(B<chroot>(2)), current directory (B<chdir>(2)), or umask (B<umask>(2)) "
4133 "attributes with any other process."
4137 #: build/C/man2/unshare.2:113
4139 "This flag has the same effect as the B<clone>(2) B<CLONE_NEWIPC> flag. "
4140 "Unshare the System V IPC namespace, so that the calling process has a "
4141 "private copy of the System V IPC namespace which is not shared with any "
4142 "other process. Specifying this flag automatically implies B<CLONE_SYSVSEM> "
4143 "as well. Use of B<CLONE_NEWIPC> requires the B<CAP_SYS_ADMIN> capability."
4147 #: build/C/man2/unshare.2:128
4149 "This flag has the same effect as the B<clone>(2) B<CLONE_NEWNET> flag. "
4150 "Unshare the network namespace, so that the calling process is moved into a "
4151 "new network namespace which is not shared with any previously existing "
4152 "process. Use of B<CLONE_NEWNET> requires the B<CAP_SYS_ADMIN> capability."
4156 #: build/C/man2/unshare.2:128
4158 msgid "B<CLONE_NEWNS>"
4161 #. These flag name are inconsistent:
4162 #. CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
4163 #. CLONE_FS, and CLONE_FILES reverse the action of the clone()
4164 #. flags of the same name.
4166 #: build/C/man2/unshare.2:149
4168 "This flag has the same effect as the B<clone>(2) B<CLONE_NEWNS> flag. "
4169 "Unshare the mount namespace, so that the calling process has a private copy "
4170 "of its namespace which is not shared with any other process. Specifying "
4171 "this flag automatically implies B<CLONE_FS> as well. Use of B<CLONE_NEWNS> "
4172 "requires the B<CAP_SYS_ADMIN> capability."
4176 #: build/C/man2/unshare.2:163
4178 "This flag has the same effect as the B<clone>(2) B<CLONE_NEWUTS> flag. "
4179 "Unshare the UTS IPC namespace, so that the calling process has a private "
4180 "copy of the UTS namespace which is not shared with any other process. Use "
4181 "of B<CLONE_NEWUTS> requires the B<CAP_SYS_ADMIN> capability."
4185 #: build/C/man2/unshare.2:163
4187 msgid "B<CLONE_SYSVSEM> (since Linux 2.6.26)"
4190 #. commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
4191 #. As at 2.6.16, the following forced implications also apply,
4192 #. although the relevant flags are not yet implemented.
4193 #. If CLONE_THREAD is set force CLONE_VM.
4194 #. If CLONE_VM is set, force CLONE_SIGHAND.
4195 #. CLONE_NEWNSIf CLONE_SIGHAND is set and signals are also being shared
4196 #. (i.e., current->signal->count > 1), force CLONE_THREAD.
4198 #. FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented.
4201 #. Reverse the effect of the
4206 #. is also implicitly set by
4208 #. and can be reversed using this
4211 #. Unshare virtual memory, so that the calling process no
4212 #. longer shares its virtual address space with any other process.
4214 #: build/C/man2/unshare.2:200
4216 "This flag reverses the effect of the B<clone>(2) B<CLONE_SYSVSEM> flag. "
4217 "Unshare System V semaphore undo values, so that the calling process has a "
4218 "private copy which is not shared with any other process. Use of "
4219 "B<CLONE_SYSVSEM> requires the B<CAP_SYS_ADMIN> capability."
4223 #: build/C/man2/unshare.2:207
4225 "If I<flags> is specified as zero, then B<unshare>() is a no-op; no changes "
4226 "are made to the calling process's execution context."
4230 #: build/C/man2/unshare.2:212
4232 "On success, zero returned. On failure, -1 is returned and I<errno> is set "
4233 "to indicate the error."
4237 #: build/C/man2/unshare.2:217
4238 msgid "An invalid bit was specified in I<flags>."
4242 #: build/C/man2/unshare.2:221
4244 "Cannot allocate sufficient memory to copy parts of caller's context that "
4245 "need to be unshared."
4249 #: build/C/man2/unshare.2:224
4250 msgid "The calling process did not have the required privileges for this operation."
4254 #: build/C/man2/unshare.2:228
4255 msgid "The B<unshare>() system call was added to Linux in kernel 2.6.16."
4259 #: build/C/man2/unshare.2:232
4260 msgid "The B<unshare>() system call is Linux-specific."
4263 #. FIXME all of the following needs to be reviewed for the current kernel
4264 #. However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
4265 #. was not specified when doing clone(); i.e., unsharing
4266 #. signal handlers is permitted if we are not actually
4267 #. sharing signal handlers. mtk
4268 #. However, we can do unshare(CLONE_VM) if CLONE_VM
4269 #. was not specified when doing clone(); i.e., unsharing
4270 #. virtual memory is permitted if we are not actually
4271 #. sharing virtual memory. mtk
4275 #. The current implementation of unshare does not allow unsharing of
4276 #. signals and signal handlers. Signals are complex to begin with and
4277 #. to unshare signals and/or signal handlers of a currently running
4278 #. process is even more complex. If in the future there is a specific
4279 #. need to allow unsharing of signals and/or signal handlers, it can
4280 #. be incrementally added to unshare without affecting legacy
4281 #. applications using unshare.
4283 #: build/C/man2/unshare.2:266
4285 "Not all of the process attributes that can be shared when a new process is "
4286 "created using B<clone>(2) can be unshared using B<unshare>(). In "
4287 "particular, as at kernel 3.8, B<unshare>() does not implement flags that "
4288 "reverse the effects of B<CLONE_SIGHAND>, B<CLONE_THREAD>, or B<CLONE_VM>. "
4289 "Such functionality may be added in the future, if required."
4293 #: build/C/man2/unshare.2:272
4294 msgid "B<clone>(2), B<fork>(2), B<kcmp>(2), B<setns>(2), B<vfork>(2)"
4298 #: build/C/man2/unshare.2:275
4299 msgid "I<Documentation/unshare.txt> in the Linux kernel source tree"