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: 2012-05-10 20:02+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=CHARSET\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man2/arch_prctl.2:24
26 #: build/C/man2/arch_prctl.2:24
32 #: build/C/man2/arch_prctl.2:24 build/C/man2/futex.2:17 build/C/man2/kexec_load.2:25 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:25 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:28 build/C/man2/pciconfig_read.2:5 build/C/man2/personality.2:30 build/C/man2/pivot_root.2:7 build/C/man2/process_vm_readv.2:27 build/C/man2/ptrace.2:49 build/C/man2/quotactl.2:25 build/C/man2/sendfile.2:15 build/C/man2/set_tid_address.2:23 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
38 #: build/C/man2/arch_prctl.2:24 build/C/man2/futex.2:17 build/C/man2/kexec_load.2:25 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:25 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:28 build/C/man2/pciconfig_read.2:5 build/C/man2/personality.2:30 build/C/man2/pivot_root.2:7 build/C/man2/process_vm_readv.2:27 build/C/man2/ptrace.2:49 build/C/man2/quotactl.2:25 build/C/man2/sendfile.2:15 build/C/man2/set_tid_address.2:23 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
40 msgid "Linux Programmer's Manual"
44 #: build/C/man2/arch_prctl.2:25 build/C/man2/futex.2:18 build/C/man2/kexec_load.2:26 build/C/man2/lookup_dcookie.2:28 build/C/man2/modify_ldt.2:26 build/C/man2/nfsservctl.2:9 build/C/man2/outb.2:29 build/C/man2/pciconfig_read.2:6 build/C/man2/personality.2:31 build/C/man2/pivot_root.2:8 build/C/man2/process_vm_readv.2:28 build/C/man2/ptrace.2:50 build/C/man2/quotactl.2:26 build/C/man2/sendfile.2:16 build/C/man2/set_tid_address.2:24 build/C/man2/splice.2:27 build/C/man2/tee.2:27 build/C/man2/vm86.2:27 build/C/man2/vmsplice.2:27
50 #: build/C/man2/arch_prctl.2:27
51 msgid "arch_prctl - set architecture-specific thread state"
55 #: build/C/man2/arch_prctl.2:27 build/C/man2/futex.2:20 build/C/man2/kexec_load.2:28 build/C/man2/lookup_dcookie.2:30 build/C/man2/modify_ldt.2:28 build/C/man2/nfsservctl.2:11 build/C/man2/pciconfig_read.2:8 build/C/man2/personality.2:33 build/C/man2/pivot_root.2:10 build/C/man2/process_vm_readv.2:30 build/C/man2/ptrace.2:52 build/C/man2/quotactl.2:28 build/C/man2/sendfile.2:18 build/C/man2/set_tid_address.2:26 build/C/man2/splice.2:29 build/C/man2/tee.2:29 build/C/man2/vm86.2:29 build/C/man2/vmsplice.2:29
61 #: build/C/man2/arch_prctl.2:30
63 msgid "B<#include E<lt>asm/prctl.hE<gt>>\n"
67 #: build/C/man2/arch_prctl.2:32
69 msgid "B<#include E<lt>sys/prctl.hE<gt>>\n"
73 #: build/C/man2/arch_prctl.2:35
76 "B<int arch_prctl(int >I<code>B<, unsigned long >I<addr>B<);>\n"
77 "B<int arch_prctl(int >I<code>B<, unsigned long *>I<addr>B<);>\n"
80 #. Return type was long before glibc 2.7
82 #: build/C/man2/arch_prctl.2:36 build/C/man2/futex.2:32 build/C/man2/kexec_load.2:35 build/C/man2/lookup_dcookie.2:32 build/C/man2/modify_ldt.2:34 build/C/man2/nfsservctl.2:18 build/C/man2/outb.2:33 build/C/man2/pciconfig_read.2:19 build/C/man2/personality.2:37 build/C/man2/pivot_root.2:12 build/C/man2/process_vm_readv.2:48 build/C/man2/ptrace.2:59 build/C/man2/quotactl.2:36 build/C/man2/sendfile.2:43 build/C/man2/set_tid_address.2:32 build/C/man2/splice.2:39 build/C/man2/tee.2:38 build/C/man2/vm86.2:35 build/C/man2/vmsplice.2:39
88 #: build/C/man2/arch_prctl.2:51
90 "The B<arch_prctl>() function sets architecture-specific process or thread "
91 "state. I<code> selects a subfunction and passes argument I<addr> to it; "
92 "I<addr> is interpreted as either an I<unsigned long> for the \"set\" "
93 "operations, or as an I<unsigned long *>, for the \"get\" operations."
97 #: build/C/man2/arch_prctl.2:53
98 msgid "Sub functions for x86-64 are:"
102 #: build/C/man2/arch_prctl.2:53
104 msgid "B<ARCH_SET_FS>"
108 #: build/C/man2/arch_prctl.2:59
109 msgid "Set the 64-bit base for the I<FS> register to I<addr>."
113 #: build/C/man2/arch_prctl.2:59
115 msgid "B<ARCH_GET_FS>"
119 #: build/C/man2/arch_prctl.2:67
121 "Return the 64-bit base value for the I<FS> register of the current thread in "
122 "the I<unsigned long> pointed to by I<addr>."
126 #: build/C/man2/arch_prctl.2:67
128 msgid "B<ARCH_SET_GS>"
132 #: build/C/man2/arch_prctl.2:73
133 msgid "Set the 64-bit base for the I<GS> register to I<addr>."
137 #: build/C/man2/arch_prctl.2:73
139 msgid "B<ARCH_GET_GS>"
143 #: build/C/man2/arch_prctl.2:81
145 "Return the 64-bit base value for the I<GS> register of the current thread in "
146 "the I<unsigned long> pointed to by I<addr>."
150 #: build/C/man2/arch_prctl.2:81 build/C/man2/futex.2:173 build/C/man2/kexec_load.2:110 build/C/man2/lookup_dcookie.2:43 build/C/man2/modify_ldt.2:96 build/C/man2/nfsservctl.2:51 build/C/man2/pciconfig_read.2:47 build/C/man2/personality.2:55 build/C/man2/pivot_root.2:95 build/C/man2/process_vm_readv.2:207 build/C/man2/ptrace.2:1580 build/C/man2/sendfile.2:104 build/C/man2/set_tid_address.2:80 build/C/man2/splice.2:127 build/C/man2/tee.2:85 build/C/man2/vm86.2:52 build/C/man2/vmsplice.2:113
156 #: build/C/man2/arch_prctl.2:87
158 "On success, B<arch_prctl>() returns 0; on error, -1 is returned, and "
159 "I<errno> is set to indicate the error."
163 #: build/C/man2/arch_prctl.2:87 build/C/man2/futex.2:210 build/C/man2/kexec_load.2:117 build/C/man2/lookup_dcookie.2:50 build/C/man2/modify_ldt.2:106 build/C/man2/pciconfig_read.2:74 build/C/man2/personality.2:62 build/C/man2/pivot_root.2:99 build/C/man2/process_vm_readv.2:227 build/C/man2/ptrace.2:1594 build/C/man2/quotactl.2:425 build/C/man2/sendfile.2:111 build/C/man2/set_tid_address.2:83 build/C/man2/splice.2:142 build/C/man2/tee.2:100 build/C/man2/vm86.2:57 build/C/man2/vmsplice.2:122
169 #: build/C/man2/arch_prctl.2:88 build/C/man2/futex.2:222 build/C/man2/lookup_dcookie.2:51 build/C/man2/modify_ldt.2:107 build/C/man2/process_vm_readv.2:249 build/C/man2/process_vm_readv.2:254 build/C/man2/ptrace.2:1598 build/C/man2/quotactl.2:426 build/C/man2/sendfile.2:121 build/C/man2/vm86.2:58
175 #: build/C/man2/arch_prctl.2:92
177 "I<addr> points to an unmapped address or is outside the process address "
182 #: build/C/man2/arch_prctl.2:92 build/C/man2/futex.2:227 build/C/man2/kexec_load.2:122 build/C/man2/lookup_dcookie.2:54 build/C/man2/modify_ldt.2:111 build/C/man2/pciconfig_read.2:75 build/C/man2/personality.2:63 build/C/man2/pivot_root.2:108 build/C/man2/process_vm_readv.2:228 build/C/man2/process_vm_readv.2:239 build/C/man2/process_vm_readv.2:243 build/C/man2/ptrace.2:1609 build/C/man2/quotactl.2:432 build/C/man2/quotactl.2:499 build/C/man2/sendfile.2:124 build/C/man2/splice.2:147 build/C/man2/tee.2:101 build/C/man2/vmsplice.2:127
188 #: build/C/man2/arch_prctl.2:96
189 msgid "I<code> is not a valid subcommand."
193 #: build/C/man2/arch_prctl.2:96 build/C/man2/kexec_load.2:129 build/C/man2/lookup_dcookie.2:65 build/C/man2/pciconfig_read.2:102 build/C/man2/pivot_root.2:114 build/C/man2/process_vm_readv.2:265 build/C/man2/ptrace.2:1619 build/C/man2/quotactl.2:454 build/C/man2/vm86.2:66
199 #. Man page written by Andi Kleen.
201 #: build/C/man2/arch_prctl.2:102
202 msgid "I<addr> is outside the process address space."
206 #: build/C/man2/arch_prctl.2:102 build/C/man2/futex.2:247 build/C/man2/kexec_load.2:138 build/C/man2/lookup_dcookie.2:78 build/C/man2/modify_ldt.2:128 build/C/man2/nfsservctl.2:56 build/C/man2/outb.2:58 build/C/man2/pciconfig_read.2:107 build/C/man2/personality.2:66 build/C/man2/pivot_root.2:122 build/C/man2/process_vm_readv.2:277 build/C/man2/ptrace.2:1637 build/C/man2/sendfile.2:144 build/C/man2/set_tid_address.2:89 build/C/man2/splice.2:169 build/C/man2/tee.2:118 build/C/man2/vm86.2:71 build/C/man2/vmsplice.2:142
208 msgid "CONFORMING TO"
212 #: build/C/man2/arch_prctl.2:106
214 "B<arch_prctl>() is a Linux/x86-64 extension and should not be used in "
215 "programs intended to be portable."
219 #: build/C/man2/arch_prctl.2:106 build/C/man2/futex.2:249 build/C/man2/kexec_load.2:140 build/C/man2/lookup_dcookie.2:81 build/C/man2/modify_ldt.2:131 build/C/man2/pivot_root.2:125 build/C/man2/process_vm_readv.2:279 build/C/man2/ptrace.2:1639 build/C/man2/sendfile.2:151 build/C/man2/splice.2:171 build/C/man2/tee.2:120 build/C/man2/vmsplice.2:144
225 #: build/C/man2/arch_prctl.2:109
227 "B<arch_prctl>() is only supported on Linux/x86-64 for 64-bit programs "
232 #: build/C/man2/arch_prctl.2:111
233 msgid "The 64-bit base changes when a new 32-bit segment selector is loaded."
237 #: build/C/man2/arch_prctl.2:114
238 msgid "B<ARCH_SET_GS> is disabled in some kernels."
242 #: build/C/man2/arch_prctl.2:129
244 "Context switches for 64-bit segment bases are rather expensive. It may be a "
245 "faster alternative to set a 32-bit base using a segment selector by setting "
246 "up an LDT with B<modify_ldt>(2) or using the B<set_thread_area>(2) system "
247 "call in kernel 2.5 or later. B<arch_prctl>() is only needed when you want "
248 "to set bases that are larger than 4GB. Memory in the first 2GB of address "
249 "space can be allocated by using B<mmap>(2) with the B<MAP_32BIT> flag."
253 #: build/C/man2/arch_prctl.2:134
255 "As of version 2.7, glibc provides no prototype for B<arch_prctl>(). You "
256 "have to declare it yourself for now. This may be fixed in future glibc "
261 #: build/C/man2/arch_prctl.2:137
262 msgid "I<FS> may be already used by the threading library."
266 #: build/C/man2/arch_prctl.2:137 build/C/man2/futex.2:263 build/C/man2/kexec_load.2:155 build/C/man2/modify_ldt.2:134 build/C/man2/outb.2:67 build/C/man2/pciconfig_read.2:109 build/C/man2/pivot_root.2:137 build/C/man2/process_vm_readv.2:329 build/C/man2/ptrace.2:1746 build/C/man2/quotactl.2:505 build/C/man2/sendfile.2:193 build/C/man2/set_tid_address.2:91 build/C/man2/splice.2:225 build/C/man2/tee.2:196 build/C/man2/vmsplice.2:153
272 #: build/C/man2/arch_prctl.2:142
273 msgid "B<mmap>(2), B<modify_ldt>(2), B<prctl>(2), B<set_thread_area>(2)"
277 #: build/C/man2/arch_prctl.2:144
278 msgid "AMD X86-64 Programmer's manual"
282 #: build/C/man2/arch_prctl.2:144 build/C/man2/futex.2:274 build/C/man2/kexec_load.2:158 build/C/man2/lookup_dcookie.2:88 build/C/man2/modify_ldt.2:136 build/C/man2/nfsservctl.2:58 build/C/man2/outb.2:70 build/C/man2/pciconfig_read.2:111 build/C/man2/personality.2:70 build/C/man2/pivot_root.2:143 build/C/man2/process_vm_readv.2:332 build/C/man2/ptrace.2:1760 build/C/man2/quotactl.2:510 build/C/man2/sendfile.2:199 build/C/man2/set_tid_address.2:94 build/C/man2/splice.2:229 build/C/man2/tee.2:199 build/C/man2/vm86.2:74 build/C/man2/vmsplice.2:156
288 #: build/C/man2/arch_prctl.2:151 build/C/man2/futex.2:281 build/C/man2/kexec_load.2:165 build/C/man2/lookup_dcookie.2:95 build/C/man2/modify_ldt.2:143 build/C/man2/nfsservctl.2:65 build/C/man2/outb.2:77 build/C/man2/pciconfig_read.2:118 build/C/man2/personality.2:77 build/C/man2/pivot_root.2:150 build/C/man2/process_vm_readv.2:339 build/C/man2/ptrace.2:1767 build/C/man2/quotactl.2:517 build/C/man2/sendfile.2:206 build/C/man2/set_tid_address.2:101 build/C/man2/splice.2:236 build/C/man2/tee.2:206 build/C/man2/vm86.2:81 build/C/man2/vmsplice.2:163
290 "This page is part of release 3.40 of the Linux I<man-pages> project. A "
291 "description of the project, and information about reporting bugs, can be "
292 "found at http://www.kernel.org/doc/man-pages/."
296 #: build/C/man2/futex.2:17
302 #: build/C/man2/futex.2:17
308 #: build/C/man2/futex.2:20
309 msgid "futex - Fast Userspace Locking system call"
313 #: build/C/man2/futex.2:25
316 "B<#include E<lt>linux/futex.hE<gt>>\n"
317 "B<#include E<lt>sys/time.hE<gt>>\n"
321 #: build/C/man2/futex.2:28
324 "B<int futex(int *>I<uaddr>B<, int >I<op>B<, int >I<val>B<, const struct "
325 "timespec *>I<timeout>B<,>\n"
328 #. int *? void *? u32 *?
330 #: build/C/man2/futex.2:31
332 msgid "B< int *>I<uaddr2>B<, int >I<val3>B<);>\n"
336 #: build/C/man2/futex.2:48
338 "The B<futex>() system call provides a method for a program to wait for a "
339 "value at a given address to change, and a method to wake up anyone waiting "
340 "on a particular address (while the addresses for the same memory in separate "
341 "processes may not be equal, the kernel maps them internally so the same "
342 "memory mapped in different locations will correspond for B<futex>() "
343 "calls). This system call is typically used to implement the contended case "
344 "of a lock in shared memory, as described in B<futex>(7)."
348 #: build/C/man2/futex.2:55
350 "When a B<futex>(7) operation did not finish uncontended in userspace, a "
351 "call needs to be made to the kernel to arbitrate. Arbitration can either "
352 "mean putting the calling process to sleep or, conversely, waking a waiting "
357 #: build/C/man2/futex.2:62
359 "Callers of this function are expected to adhere to the semantics as set out "
360 "in B<futex>(7). As these semantics involve writing nonportable assembly "
361 "instructions, this in turn probably means that most users will in fact be "
362 "library authors and not general application developers."
366 #: build/C/man2/futex.2:70
368 "The I<uaddr> argument needs to point to an aligned integer which stores the "
369 "counter. The operation to execute is passed via the I<op> argument, along "
370 "with a value I<val>."
374 #: build/C/man2/futex.2:72
375 msgid "Five operations are currently defined:"
379 #: build/C/man2/futex.2:72 build/C/man2/futex.2:177
381 msgid "B<FUTEX_WAIT>"
385 #: build/C/man2/futex.2:90
387 "This operation atomically verifies that the futex address I<uaddr> still "
388 "contains the value I<val>, and sleeps awaiting B<FUTEX_WAKE> on this futex "
389 "address. If the I<timeout> argument is non-NULL, its contents describe the "
390 "maximum duration of the wait, which is infinite otherwise. The arguments "
391 "I<uaddr2> and I<val3> are ignored."
395 #: build/C/man2/futex.2:98
397 "For B<futex>(7), this call is executed if decrementing the count gave a "
398 "negative value (indicating contention), and will sleep until another process "
399 "releases the futex and executes the B<FUTEX_WAKE> operation."
403 #: build/C/man2/futex.2:98 build/C/man2/futex.2:194
405 msgid "B<FUTEX_WAKE>"
409 #: build/C/man2/futex.2:109
411 "This operation wakes at most I<val> processes waiting on this futex address "
412 "(i.e., inside B<FUTEX_WAIT>). The arguments I<timeout>, I<uaddr2> and "
413 "I<val3> are ignored."
417 #: build/C/man2/futex.2:115
419 "For B<futex>(7), this is executed if incrementing the count showed that "
420 "there were waiters, once the futex value has been set to 1 (indicating that "
425 #: build/C/man2/futex.2:115
427 msgid "B<FUTEX_FD> (present up to and including Linux 2.6.25)"
430 #. , suitable for .BR poll (2).
432 #: build/C/man2/futex.2:131
434 "To support asynchronous wakeups, this operation associates a file descriptor "
435 "with a futex. If another process executes a B<FUTEX_WAKE>, the process will "
436 "receive the signal number that was passed in I<val>. The calling process "
437 "must close the returned file descriptor after use. The arguments "
438 "I<timeout>, I<uaddr2> and I<val3> are ignored."
442 #: build/C/man2/futex.2:136
444 "To prevent race conditions, the caller should test if the futex has been "
445 "upped after B<FUTEX_FD> returns."
449 #: build/C/man2/futex.2:140
451 "Because it was inherently racy, B<FUTEX_FD> has been removed from Linux "
456 #: build/C/man2/futex.2:140
458 msgid "B<FUTEX_REQUEUE> (since Linux 2.5.70)"
462 #: build/C/man2/futex.2:155
464 "This operation was introduced in order to avoid a \"thundering herd\" effect "
465 "when B<FUTEX_WAKE> is used and all processes woken up need to acquire "
466 "another futex. This call wakes up I<val> processes, and requeues all other "
467 "waiters on the futex at address I<uaddr2>. The arguments I<timeout> and "
468 "I<val3> are ignored."
472 #: build/C/man2/futex.2:155
474 msgid "B<FUTEX_CMP_REQUEUE> (since Linux 2.6.7)"
478 #: build/C/man2/futex.2:173
480 "There was a race in the intended use of B<FUTEX_REQUEUE>, so "
481 "B<FUTEX_CMP_REQUEUE> was introduced. This is similar to B<FUTEX_REQUEUE>, "
482 "but first checks whether the location I<uaddr> still contains the value "
483 "I<val3>. If not, the operation fails with the error B<EAGAIN>. The "
484 "argument I<timeout> is ignored."
488 #: build/C/man2/futex.2:177
490 "Depending on which operation was executed, the returned value for a "
491 "successful call can have differing meanings."
495 #: build/C/man2/futex.2:194
497 "Returns 0 if the process was woken by a B<FUTEX_WAKE> call. In case of "
498 "timeout, the operation fails with the error B<ETIMEDOUT>. If the futex was "
499 "not equal to the expected value, the operation fails with the error "
500 "B<EWOULDBLOCK>. Signals (see B<signal>(7)) or other spurious wakeups cause "
501 "B<FUTEX_WAIT> to fail with the error B<EINTR>."
505 #: build/C/man2/futex.2:197 build/C/man2/futex.2:203 build/C/man2/futex.2:206
506 msgid "Returns the number of processes woken up."
510 #: build/C/man2/futex.2:197
516 #: build/C/man2/futex.2:200
517 msgid "Returns the new file descriptor associated with the futex."
521 #: build/C/man2/futex.2:200
523 msgid "B<FUTEX_REQUEUE>"
527 #: build/C/man2/futex.2:203
529 msgid "B<FUTEX_CMP_REQUEUE>"
533 #: build/C/man2/futex.2:210
535 "In the event of an error, all operations return -1, and set I<errno> to "
536 "indicate the error."
540 #: build/C/man2/futex.2:211 build/C/man2/quotactl.2:484
546 #: build/C/man2/futex.2:214
547 msgid "No read access to futex memory."
551 #: build/C/man2/futex.2:214 build/C/man2/sendfile.2:112
557 #: build/C/man2/futex.2:222
559 "B<FUTEX_CMP_REQUEUE> found an unexpected futex value. (This probably "
560 "indicates a race; use the safe B<FUTEX_WAKE> now.)"
564 #: build/C/man2/futex.2:227
565 msgid "Error in getting I<timeout> information from userspace."
569 #: build/C/man2/futex.2:230
570 msgid "An operation was not defined or error in page alignment."
574 #: build/C/man2/futex.2:230
580 #: build/C/man2/futex.2:233
581 msgid "The system limit on the total number of open files has been reached."
585 #: build/C/man2/futex.2:233 build/C/man2/modify_ldt.2:124 build/C/man2/pciconfig_read.2:90 build/C/man2/quotactl.2:445 build/C/man2/vm86.2:62
591 #: build/C/man2/futex.2:237
592 msgid "Invalid operation specified in I<op>."
596 #: build/C/man2/futex.2:237 build/C/man2/kexec_load.2:134 build/C/man2/lookup_dcookie.2:73 build/C/man2/pivot_root.2:119 build/C/man2/process_vm_readv.2:274 build/C/man2/sendfile.2:138 build/C/man2/set_tid_address.2:86 build/C/man2/splice.2:165 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
602 #: build/C/man2/futex.2:247
604 "Initial futex support was merged in Linux 2.5.7 but with different semantics "
605 "from what was described above. A 4-argument system call with the semantics "
606 "described in this page was introduced in Linux 2.5.40. In Linux 2.5.70 one "
607 "argument was added. In Linux 2.6.7 a sixth argument was added\\(emmessy, "
608 "especially on the s390 architecture."
612 #: build/C/man2/futex.2:249 build/C/man2/kexec_load.2:140 build/C/man2/set_tid_address.2:91 build/C/man2/splice.2:171 build/C/man2/tee.2:120 build/C/man2/vmsplice.2:144
613 msgid "This system call is Linux-specific."
618 #. Futexes were designed and worked on by
619 #. Hubertus Franke (IBM Thomas J. Watson Research Center),
620 #. Matthew Kirkwood, Ingo Molnar (Red Hat)
621 #. and Rusty Russell (IBM Linux Technology Center).
622 #. This page written by bert hubert.
624 #: build/C/man2/futex.2:263
626 "To reiterate, bare futexes are not intended as an easy-to-use abstraction "
627 "for end-users. (There is no wrapper function for this system call in "
628 "glibc.) Implementors are expected to be assembly literate and to have read "
629 "the sources of the futex userspace library referenced below."
633 #: build/C/man2/futex.2:265
638 #: build/C/man2/futex.2:268
640 "I<Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux> (proceedings "
641 "of the Ottawa Linux Symposium 2002), online at"
645 #: build/C/man2/futex.2:270
646 msgid "http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf"
650 #: build/C/man2/futex.2:272
651 msgid "Futex example library, futex-*.tar.bz2 at"
655 #: build/C/man2/futex.2:274
656 msgid "ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/."
660 #: build/C/man2/kexec_load.2:25
666 #: build/C/man2/kexec_load.2:25
672 #: build/C/man2/kexec_load.2:28
673 msgid "kexec_load - load a new kernel for later execution"
677 #: build/C/man2/kexec_load.2:30
678 msgid "B<#include E<lt>linux/kexec.hE<gt>>"
682 #: build/C/man2/kexec_load.2:32
684 "B<long kexec_load(unsigned long >I<entry>B<, unsigned long "
685 ">I<nr_segments>B<,>"
689 #: build/C/man2/kexec_load.2:35
690 msgid "B< struct kexec_segment *>I<segments>B<, unsigned long >I<flags>B<);>"
694 #: build/C/man2/kexec_load.2:40
696 "The B<kexec_load>() system call loads a new kernel that can be executed "
697 "later by B<reboot>(2)."
701 #: build/C/man2/kexec_load.2:46
703 "The I<flags> argument is a mask whose high-order bits control the operation "
704 "of the call. The following values can be specified in I<flags>:"
708 #: build/C/man2/kexec_load.2:46
710 msgid "B<KEXEC_ON_CRASH> (since Linux 2.6.13)"
713 #. FIXME figure out how this is really used
715 #: build/C/man2/kexec_load.2:50
716 msgid "Execute the new kernel automatically on a system crash."
720 #: build/C/man2/kexec_load.2:50
722 msgid "B<KEXEC_PRESERVE_CONTEXT> (since Linux 2.7.27)"
726 #: build/C/man2/kexec_load.2:60
728 "Preserve the system hardware and software states before executing the new "
729 "kernel. This could be used for system suspend. This flag is only available "
730 "if the kernel was configured with B<CONFIG_KEXEC_JUMP>, and is only "
731 "effective if I<nr_segments> is greater than 0."
735 #: build/C/man2/kexec_load.2:80
737 "The low-order bits of I<flags> contain the architecture of the "
738 "to-be-executed kernel. Specify (OR) the constant B<KEXEC_ARCH_DEFAULT> to "
739 "use the current architecture, or one of the following architecture constants "
740 "B<KEXEC_ARCH_386>, B<KEXEC_ARCH_X86_64>, B<KEXEC_ARCH_PPC>, "
741 "B<KEXEC_ARCH_PPC64>, B<KEXEC_ARCH_IA_64>, B<KEXEC_ARCH_ARM>, "
742 "B<KEXEC_ARCH_S390>, B<KEXEC_ARCH_SH>, B<KEXEC_ARCH_MIPS>, and "
743 "B<KEXEC_ARCH_MIPS_LE>. The architecture must be executable on the CPU of "
748 #: build/C/man2/kexec_load.2:94
750 "The I<entry> argument is the physical entry address in the kernel image. "
751 "The I<nr_segments> argument is the number of segments pointed to by the "
752 "I<segments> pointer. The I<segments> argument is an array of "
753 "I<kexec_segment> structures which define the kernel layout:"
757 #: build/C/man2/kexec_load.2:103
760 "struct kexec_segment {\n"
761 " void *buf; /* Buffer in user space */\n"
762 " size_t bufsz; /* Buffer length in user space */\n"
763 " void *mem; /* Physical address of kernel */\n"
764 " size_t memsz; /* Physical address length */\n"
768 #. FIXME elaborate on the following:
770 #: build/C/man2/kexec_load.2:110
772 "The kernel image defined by I<segments> is copied from the calling process "
773 "into previously reserved memory."
777 #: build/C/man2/kexec_load.2:117
779 "On success, B<kexec_load>() returns 0. On error, -1 is returned and "
780 "I<errno> is set to indicate the error."
784 #: build/C/man2/kexec_load.2:118 build/C/man2/pivot_root.2:104 build/C/man2/ptrace.2:1595 build/C/man2/quotactl.2:493
790 #: build/C/man2/kexec_load.2:122
792 "Another crash kernel is already being loaded or a crash kernel is already in "
796 #. KEXEC_SEGMENT_MAX == 16
798 #: build/C/man2/kexec_load.2:129
799 msgid "I<flags> is invalid; or I<nr_segments> is too large"
803 #: build/C/man2/kexec_load.2:134
804 msgid "The caller does not have the B<CAP_SYS_BOOT> capability."
808 #: build/C/man2/kexec_load.2:138
809 msgid "The B<kexec_load>() system call first appeared in Linux 2.6.13."
813 #: build/C/man2/kexec_load.2:145
815 "Currently, there is no glibc support for B<kexec_load>(). Call it using "
819 #. FIXME Andi submitted a patch for this.
820 #. Check if it got accepted later.
822 #: build/C/man2/kexec_load.2:152
824 "The required constants are in the kernel source file I<linux/kexec.h>, which "
825 "is not currently exported to glibc. Therefore, these constants must be "
830 #: build/C/man2/kexec_load.2:155
832 "This system call is only available if the kernel was configured with "
837 #: build/C/man2/kexec_load.2:158
838 msgid "B<reboot>(2), B<syscall>(2)"
842 #: build/C/man2/lookup_dcookie.2:27
844 msgid "LOOKUP_DCOOKIE"
848 #: build/C/man2/lookup_dcookie.2:27
854 #: build/C/man2/lookup_dcookie.2:30
855 msgid "lookup_dcookie - return a directory entry's path"
859 #: build/C/man2/lookup_dcookie.2:32
861 "B<int lookup_dcookie(u64 >I<cookie>B<, char *>I<buffer>B<, size_t "
866 #: build/C/man2/lookup_dcookie.2:38
868 "Look up the full path of the directory entry specified by the value "
869 "I<cookie>. The cookie is an opaque identifier uniquely identifying a "
870 "particular directory entry. The buffer given is filled in with the full "
871 "path of the directory entry."
875 #: build/C/man2/lookup_dcookie.2:43
877 "For B<lookup_dcookie>() to return successfully, the kernel must still hold "
878 "a cookie reference to the directory entry."
882 #: build/C/man2/lookup_dcookie.2:50
884 "On success, B<lookup_dcookie>() returns the length of the path string "
885 "copied into the buffer. On error, -1 is returned, and I<errno> is set "
890 #: build/C/man2/lookup_dcookie.2:54
891 msgid "The buffer was not valid."
895 #: build/C/man2/lookup_dcookie.2:58
897 "The kernel has no registered cookie/directory entry mappings at the time of "
898 "lookup, or the cookie does not refer to a valid directory entry."
902 #: build/C/man2/lookup_dcookie.2:58
904 msgid "B<ENAMETOOLONG>"
908 #: build/C/man2/lookup_dcookie.2:61
909 msgid "The name could not fit in the buffer."
913 #: build/C/man2/lookup_dcookie.2:61 build/C/man2/process_vm_readv.2:260 build/C/man2/sendfile.2:134 build/C/man2/splice.2:155 build/C/man2/tee.2:111 build/C/man2/vmsplice.2:135
919 #: build/C/man2/lookup_dcookie.2:65
921 "The kernel could not allocate memory for the temporary buffer holding the "
926 #: build/C/man2/lookup_dcookie.2:70
928 "The process does not have the capability B<CAP_SYS_ADMIN> required to look "
933 #: build/C/man2/lookup_dcookie.2:70 build/C/man2/quotactl.2:472
939 #: build/C/man2/lookup_dcookie.2:73
940 msgid "The buffer was not large enough to hold the path of the directory entry."
944 #: build/C/man2/lookup_dcookie.2:78
946 "Available since Linux 2.5.43. The B<ENAMETOOLONG> error return was added in "
951 #: build/C/man2/lookup_dcookie.2:81
952 msgid "B<lookup_dcookie>() is Linux-specific."
956 #: build/C/man2/lookup_dcookie.2:85
958 "B<lookup_dcookie>() is a special-purpose system call, currently used only "
959 "by the oprofile profiler. It relies on a kernel driver to register cookies "
960 "for directory entries."
964 #: build/C/man2/lookup_dcookie.2:88
966 "The path returned may be suffixed by the string \" (deleted)\" if the "
967 "directory entry has been removed."
971 #: build/C/man2/modify_ldt.2:25
977 #: build/C/man2/modify_ldt.2:25 build/C/man2/pivot_root.2:7
983 #: build/C/man2/modify_ldt.2:28
984 msgid "modify_ldt - get or set ldt"
988 #: build/C/man2/modify_ldt.2:31
990 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
994 #: build/C/man2/modify_ldt.2:33
997 "B<int modify_ldt(int >I<func>B<, void *>I<ptr>B<, unsigned long "
998 ">I<bytecount>B<);>\n"
1002 #: build/C/man2/modify_ldt.2:39
1004 "B<modify_ldt>() reads or writes the local descriptor table (ldt) for a "
1005 "process. The ldt is a per-process memory management table used by the i386 "
1006 "processor. For more information on this table, see an Intel 386 processor "
1011 #: build/C/man2/modify_ldt.2:49
1013 "When I<func> is 0, B<modify_ldt>() reads the ldt into the memory pointed to "
1014 "by I<ptr>. The number of bytes read is the smaller of I<bytecount> and the "
1015 "actual size of the ldt."
1019 #. FIXME ? say something about func == 2 and func == 0x11?
1020 #. In Linux 2.4, func == 2 returned "the default ldt"
1021 #. In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
1022 #. Linux 2.4 and 2.6 implement an operation for func == 0x11
1024 #: build/C/man2/modify_ldt.2:67
1026 "When I<func> is 1, B<modify_ldt>() modifies one ldt entry. I<ptr> points "
1027 "to a I<user_desc> structure and I<bytecount> must equal the size of this "
1032 #: build/C/man2/modify_ldt.2:71
1033 msgid "The I<user_desc> structure is defined in I<E<lt>asm/ldt.hE<gt>> as:"
1037 #: build/C/man2/modify_ldt.2:85
1040 "struct user_desc {\n"
1041 " unsigned int entry_number;\n"
1042 " unsigned long base_addr;\n"
1043 " unsigned int limit;\n"
1044 " unsigned int seg_32bit:1;\n"
1045 " unsigned int contents:2;\n"
1046 " unsigned int read_exec_only:1;\n"
1047 " unsigned int limit_in_pages:1;\n"
1048 " unsigned int seg_not_present:1;\n"
1049 " unsigned int useable:1;\n"
1054 #. The ldt is specific for the calling process. Any attempts to change
1055 #. the ldt to include the address space of another process or the kernel
1056 #. will result in a segmentation violation when trying to access the memory
1057 #. outside of the process address space. The memory protection is enforced
1058 #. at the paging layer.
1060 #: build/C/man2/modify_ldt.2:96
1061 msgid "In Linux 2.4 and earlier, this structure was named I<modify_ldt_ldt_s>."
1065 #: build/C/man2/modify_ldt.2:106
1067 "On success, B<modify_ldt>() returns either the actual number of bytes read "
1068 "(for reading) or 0 (for writing). On failure, B<modify_ldt>() returns -1 "
1069 "and sets I<errno> to indicate the error."
1073 #: build/C/man2/modify_ldt.2:111
1074 msgid "I<ptr> points outside the address space."
1078 #: build/C/man2/modify_ldt.2:124
1080 "I<ptr> is 0, or I<func> is 1 and I<bytecount> is not equal to the size of "
1081 "the structure I<modify_ldt_ldt_s>, or I<func> is 1 and the new ldt entry has "
1086 #: build/C/man2/modify_ldt.2:128
1087 msgid "I<func> is neither 0 nor 1."
1091 #: build/C/man2/modify_ldt.2:131
1093 "This call is Linux-specific and should not be used in programs intended to "
1098 #: build/C/man2/modify_ldt.2:134 build/C/man2/pivot_root.2:128
1100 "Glibc does not provide a wrapper for this system call; call it using "
1105 #: build/C/man2/modify_ldt.2:136
1110 #: build/C/man2/nfsservctl.2:8
1116 #: build/C/man2/nfsservctl.2:8
1122 #: build/C/man2/nfsservctl.2:11
1123 msgid "nfsservctl - syscall interface to kernel nfs daemon"
1127 #: build/C/man2/nfsservctl.2:14
1129 msgid "B<#include E<lt>linux/nfsd/syscall.hE<gt>>\n"
1133 #: build/C/man2/nfsservctl.2:17
1136 "B<long nfsservctl(int >I<cmd>B<, struct nfsctl_arg *>I<argp>B<,>\n"
1137 "B< union nfsctl_res *>I<resp>B<);>\n"
1141 #: build/C/man2/nfsservctl.2:21
1142 msgid "I<Note>: Since Linux 3.1, this system call no longer exists."
1146 #: build/C/man2/nfsservctl.2:33
1150 " * These are the commands understood by nfsctl().\n"
1152 "#define NFSCTL_SVC 0 /* This is a server process. */\n"
1153 "#define NFSCTL_ADDCLIENT 1 /* Add an NFS client. */\n"
1154 "#define NFSCTL_DELCLIENT 2 /* Remove an NFS client. */\n"
1155 "#define NFSCTL_EXPORT 3 /* export a file system. */\n"
1156 "#define NFSCTL_UNEXPORT 4 /* unexport a file system. */\n"
1157 "#define NFSCTL_UGIDUPDATE 5 /* update a client's UID/GID map. */\n"
1158 "#define NFSCTL_GETFH 6 /* get an fh (used by mountd) */\n"
1162 #: build/C/man2/nfsservctl.2:45
1165 "struct nfsctl_arg {\n"
1166 " int ca_version; /* safeguard */\n"
1168 " struct nfsctl_svc u_svc;\n"
1169 " struct nfsctl_client u_client;\n"
1170 " struct nfsctl_export u_export;\n"
1171 " struct nfsctl_uidmap u_umap;\n"
1172 " struct nfsctl_fhparm u_getfh;\n"
1173 " unsigned int u_debug;\n"
1179 #: build/C/man2/nfsservctl.2:50
1182 "union nfsctl_res {\n"
1183 " struct knfs_fh cr_getfh;\n"
1184 " unsigned int cr_debug;\n"
1189 #: build/C/man2/nfsservctl.2:56 build/C/man2/pivot_root.2:99 build/C/man2/vm86.2:57
1191 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
1196 #: build/C/man2/nfsservctl.2:58
1197 msgid "This call is Linux-specific."
1201 #: build/C/man2/outb.2:28
1207 #: build/C/man2/outb.2:28
1213 #: build/C/man2/outb.2:33
1215 "outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, "
1216 "outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O"
1220 #: build/C/man2/outb.2:38
1222 "This family of functions is used to do low-level port input and output. The "
1223 "out* functions do port output, the in* functions do port input; the b-suffix "
1224 "functions are byte-width and the w-suffix functions word-width; the "
1225 "_p-suffix functions pause until the I/O completes."
1228 #. , given the following information
1229 #. in addition to that given in
1232 #: build/C/man2/outb.2:44
1234 "They are primarily designed for internal kernel use, but can be used from "
1239 #: build/C/man2/outb.2:49
1241 "You compile with B<-O> or B<-O2> or similar. The functions are defined as "
1242 "inline macros, and will not be substituted in without optimization enabled, "
1243 "causing unresolved references at link time."
1247 #: build/C/man2/outb.2:58
1249 "You use B<ioperm>(2) or alternatively B<iopl>(2) to tell the kernel to "
1250 "allow the user space application to access the I/O ports in question. "
1251 "Failure to do this will cause the application to receive a segmentation "
1256 #: build/C/man2/outb.2:67
1258 "B<outb>() and friends are hardware-specific. The I<value> argument is "
1259 "passed first and the I<port> argument is passed second, which is the "
1260 "opposite order from most DOS implementations."
1264 #: build/C/man2/outb.2:70
1265 msgid "B<ioperm>(2), B<iopl>(2)"
1269 #: build/C/man2/pciconfig_read.2:5
1271 msgid "PCICONFIG_READ"
1275 #: build/C/man2/pciconfig_read.2:5
1281 #: build/C/man2/pciconfig_read.2:8
1283 "pciconfig_read, pciconfig_write, pciconfig_iobase - pci device information "
1288 #: build/C/man2/pciconfig_read.2:11
1290 msgid "B<#include E<lt>pci.hE<gt>>\n"
1294 #: build/C/man2/pciconfig_read.2:18
1297 "B<int pciconfig_read(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1298 "B< unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1300 "B<int pciconfig_write(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1301 "B< unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1303 "B<int pciconfig_iobase(long >I<which>B<, unsigned long >I<bus>B<,>\n"
1304 "B< unsigned long >I<devfn>B<);>\n"
1308 #: build/C/man2/pciconfig_read.2:24
1310 "Most of the interaction with PCI devices is already handled by the kernel "
1311 "PCI layer, and thus these calls should not normally need to be accessed from "
1316 #: build/C/man2/pciconfig_read.2:24 build/C/man2/pciconfig_read.2:48
1318 msgid "B<pciconfig_read>()"
1322 #: build/C/man2/pciconfig_read.2:33
1323 msgid "Reads to I<buf> from device I<dev> at offset I<off> value."
1327 #: build/C/man2/pciconfig_read.2:33 build/C/man2/pciconfig_read.2:54
1329 msgid "B<pciconfig_write>()"
1333 #: build/C/man2/pciconfig_read.2:42
1334 msgid "Writes from I<buf> to device I<dev> at offset I<off> value."
1338 #: build/C/man2/pciconfig_read.2:42 build/C/man2/pciconfig_read.2:60
1340 msgid "B<pciconfig_iobase>()"
1344 #: build/C/man2/pciconfig_read.2:47
1346 "You pass it a bus/devfn pair and get a physical address for either the "
1347 "memory offset (for things like prep, this is 0xc0000000), the IO base for "
1348 "PIO cycles, or the ISA holes if any."
1352 #: build/C/man2/pciconfig_read.2:54 build/C/man2/pciconfig_read.2:60
1354 "On success zero is returned. On error, -1 is returned and I<errno> is set "
1359 #: build/C/man2/pciconfig_read.2:74
1361 "Returns information on locations of various I/O regions in physical memory "
1362 "according to the I<which> value. Values for I<which> are: "
1363 "B<IOBASE_BRIDGE_NUMBER>, B<IOBASE_MEMORY>, B<IOBASE_IO>, B<IOBASE_ISA_IO>, "
1364 "B<IOBASE_ISA_MEM>."
1368 #: build/C/man2/pciconfig_read.2:81
1369 msgid "I<len> value is invalid. This does not apply to B<pciconfig_iobase>()."
1373 #: build/C/man2/pciconfig_read.2:81 build/C/man2/ptrace.2:1612 build/C/man2/sendfile.2:130
1379 #: build/C/man2/pciconfig_read.2:84
1384 #: build/C/man2/pciconfig_read.2:84
1390 #: build/C/man2/pciconfig_read.2:90
1392 "For B<pciconfig_iobase>(), \"hose\" value is NULL. For the other calls, "
1393 "could not find a slot."
1397 #: build/C/man2/pciconfig_read.2:95
1398 msgid "The system has not implemented these calls (B<CONFIG_PCI> not defined)."
1402 #: build/C/man2/pciconfig_read.2:95
1404 msgid "B<EOPNOTSUPP>"
1408 #: build/C/man2/pciconfig_read.2:102
1410 "This return value is only valid for B<pciconfig_iobase>(). It is returned "
1411 "if the value for I<which> is invalid."
1415 #: build/C/man2/pciconfig_read.2:107
1417 "User does not have the B<CAP_SYS_ADMIN> capability. This does not apply to "
1418 "B<pciconfig_iobase>()."
1422 #: build/C/man2/pciconfig_read.2:109
1423 msgid "These calls are Linux-specific, available since Linux 2.0.26/2.1.11."
1427 #: build/C/man2/pciconfig_read.2:111
1428 msgid "B<capabilities>(7)"
1432 #: build/C/man2/personality.2:30
1438 #: build/C/man2/personality.2:30
1444 #: build/C/man2/personality.2:33
1445 msgid "personality - set the process execution domain"
1449 #: build/C/man2/personality.2:35
1450 msgid "B<#include E<lt>sys/personality.hE<gt>>"
1454 #: build/C/man2/personality.2:37
1455 msgid "B<int personality(unsigned long >I<persona>B<);>"
1459 #: build/C/man2/personality.2:45
1461 "Linux supports different execution domains, or personalities, for each "
1462 "process. Among other things, execution domains tell Linux how to map signal "
1463 "numbers into signal actions. The execution domain system allows Linux to "
1464 "provide limited support for binaries compiled under other UNIX-like "
1465 "operating systems."
1469 #: build/C/man2/personality.2:55
1471 "This function will return the current B<personality>() when I<persona> "
1472 "equals 0xffffffff. Otherwise, it will make the execution domain referenced "
1473 "by I<persona> the new execution domain of the calling process."
1477 #: build/C/man2/personality.2:62
1479 "On success, the previous I<persona> is returned. On error, -1 is returned, "
1480 "and I<errno> is set appropriately."
1484 #: build/C/man2/personality.2:66
1485 msgid "The kernel was unable to change the personality."
1489 #: build/C/man2/personality.2:70
1491 "B<personality>() is Linux-specific and should not be used in programs "
1492 "intended to be portable."
1496 #: build/C/man2/pivot_root.2:7
1502 #: build/C/man2/pivot_root.2:10
1503 msgid "pivot_root - change the root file system"
1507 #: build/C/man2/pivot_root.2:12
1508 msgid "B<int pivot_root(const char *>I<new_root>B<, const char *>I<put_old>B<);>"
1514 #. capability is required.
1516 #: build/C/man2/pivot_root.2:21
1518 "B<pivot_root>() moves the root file system of the calling process to the "
1519 "directory I<put_old> and makes I<new_root> the new root file system of the "
1524 #: build/C/man2/pivot_root.2:28
1526 "The typical use of B<pivot_root>() is during system startup, when the "
1527 "system mounts a temporary root file system (e.g., an B<initrd>), then mounts "
1528 "the real root file system, and eventually turns the latter into the current "
1529 "root of all relevant processes or threads."
1533 #: build/C/man2/pivot_root.2:40
1535 "B<pivot_root>() may or may not change the current root and the current "
1536 "working directory of any processes or threads which use the old root "
1537 "directory. The caller of B<pivot_root>() must ensure that processes with "
1538 "root or current working directory at the old root operate correctly in "
1539 "either case. An easy way to ensure this is to change their root and current "
1540 "working directory to I<new_root> before invoking B<pivot_root>()."
1544 #: build/C/man2/pivot_root.2:58
1546 "The paragraph above is intentionally vague because the implementation of "
1547 "B<pivot_root>() may change in the future. At the time of writing, "
1548 "B<pivot_root>() changes root and current working directory of each process "
1549 "or thread to I<new_root> if they point to the old root directory. This is "
1550 "necessary in order to prevent kernel threads from keeping the old root "
1551 "directory busy with their root and current working directory, even if they "
1552 "never access the file system in any way. In the future, there may be a "
1553 "mechanism for kernel threads to explicitly relinquish any access to the file "
1554 "system, such that this fairly intrusive mechanism can be removed from "
1559 #: build/C/man2/pivot_root.2:66
1561 "Note that this also applies to the calling process: B<pivot_root>() may or "
1562 "may not affect its current working directory. It is therefore recommended "
1563 "to call B<chdir(\"/\")> immediately after B<pivot_root>()."
1567 #: build/C/man2/pivot_root.2:68
1568 msgid "The following restrictions apply to I<new_root> and I<put_old>:"
1572 #: build/C/man2/pivot_root.2:68 build/C/man2/pivot_root.2:70 build/C/man2/pivot_root.2:73 build/C/man2/pivot_root.2:77
1578 #: build/C/man2/pivot_root.2:70
1579 msgid "They must be directories."
1583 #: build/C/man2/pivot_root.2:73
1585 "I<new_root> and I<put_old> must not be on the same file system as the "
1590 #: build/C/man2/pivot_root.2:77
1592 "I<put_old> must be underneath I<new_root>, that is, adding a nonzero number "
1593 "of I</..> to the string pointed to by I<put_old> must yield the same "
1594 "directory as I<new_root>."
1598 #: build/C/man2/pivot_root.2:79
1599 msgid "No other file system may be mounted on I<put_old>."
1603 #: build/C/man2/pivot_root.2:83
1604 msgid "See also B<pivot_root>(8) for additional usage examples."
1608 #: build/C/man2/pivot_root.2:90
1610 "If the current root is not a mount point (e.g., after B<chroot>(2) or "
1611 "B<pivot_root>(), see also below), not the old root directory, but the mount "
1612 "point of that file system is mounted on I<put_old>."
1616 #: build/C/man2/pivot_root.2:95
1618 "I<new_root> does not have to be a mount point. In this case, "
1619 "I</proc/mounts> will show the mount point of the file system containing "
1620 "I<new_root> as root (I</>)."
1624 #: build/C/man2/pivot_root.2:104
1626 "B<pivot_root>() may return (in I<errno>) any of the errors returned by "
1627 "B<stat>(2). Additionally, it may return:"
1631 #: build/C/man2/pivot_root.2:108
1633 "I<new_root> or I<put_old> are on the current root file system, or a file "
1634 "system is already mounted on I<put_old>."
1638 #: build/C/man2/pivot_root.2:111
1639 msgid "I<put_old> is not underneath I<new_root>."
1643 #: build/C/man2/pivot_root.2:111
1649 #: build/C/man2/pivot_root.2:114
1650 msgid "I<new_root> or I<put_old> is not a directory."
1654 #: build/C/man2/pivot_root.2:119
1655 msgid "The calling process does not have the B<CAP_SYS_ADMIN> capability."
1659 #: build/C/man2/pivot_root.2:122
1660 msgid "B<pivot_root>() was introduced in Linux 2.3.41."
1664 #: build/C/man2/pivot_root.2:125
1665 msgid "B<pivot_root>() is Linux-specific and hence is not portable."
1669 #: build/C/man2/pivot_root.2:128 build/C/man2/ptrace.2:1675
1675 #: build/C/man2/pivot_root.2:132
1677 "B<pivot_root>() should not have to change root and current working "
1678 "directory of all other processes in the system."
1682 #: build/C/man2/pivot_root.2:137
1684 "Some of the more obscure uses of B<pivot_root>() may quickly lead to "
1689 #: build/C/man2/pivot_root.2:143
1690 msgid "B<chdir>(2), B<chroot>(2), B<stat>(2), B<initrd>(4), B<pivot_root>(8)"
1694 #: build/C/man2/process_vm_readv.2:27
1696 msgid "PROCESS_VM_READV"
1700 #: build/C/man2/process_vm_readv.2:27
1706 #: build/C/man2/process_vm_readv.2:30
1708 "process_vm_readv, process_vm_writev - transfer data between process address "
1713 #: build/C/man2/process_vm_readv.2:33
1715 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
1719 #: build/C/man2/process_vm_readv.2:40
1722 "B<ssize_t process_vm_readv(pid_t >I<pid>B<,>\n"
1723 "B< const struct iovec *>I<local_iov>B<,>\n"
1724 "B< unsigned long >I<liovcnt>B<,>\n"
1725 "B< const struct iovec *>I<remote_iov>B<,>\n"
1726 "B< unsigned long >I<riovcnt>B<,>\n"
1727 "B< unsigned long >I<flags>B<);>\n"
1731 #: build/C/man2/process_vm_readv.2:47
1734 "B<ssize_t process_vm_writev(pid_t >I<pid>B<,>\n"
1735 "B< const struct iovec *>I<local_iov>B<,>\n"
1736 "B< unsigned long >I<liovcnt>B<,>\n"
1737 "B< const struct iovec *>I<remote_iov>B<,>\n"
1738 "B< unsigned long >I<riovcnt>B<,>\n"
1739 "B< unsigned long >I<flags>B<);>\n"
1743 #: build/C/man2/process_vm_readv.2:55
1745 "These system calls transfer data between the address space of the calling "
1746 "process (\"the local process\") and the process identified by I<pid> (\"the "
1747 "remote process\"). The data moves directly between the address spaces of "
1748 "the two processes, without passing through kernel space."
1752 #: build/C/man2/process_vm_readv.2:80
1754 "The B<process_vm_readv>() system call transfers data from the remote "
1755 "process to the local process. The data to be transferred is identified by "
1756 "I<remote_iov> and I<riovcnt>: I<remote_iov> is a pointer to an array "
1757 "describing address ranges in the process I<pid>, and I<riovcnt> specifies "
1758 "the number of elements in I<remote_iov>. The data is transferred to the "
1759 "locations specified by I<local_iov> and I<liovcnt>: I<local_iov> is a "
1760 "pointer to an array describing address ranges in the calling process, and "
1761 "I<liovcnt> specifies the number of elements in I<local_iov>."
1765 #: build/C/man2/process_vm_readv.2:94
1767 "The B<process_vm_writev>() system call is the converse of "
1768 "B<process_vm_readv>()\\(emit transfers data from the local process to the "
1769 "remote process. Other than the direction of the transfer, the arguments "
1770 "I<liovcnt>, I<local_iov>, I<riovcnt>, and I<remote_iov> have the same "
1771 "meaning as for B<process_vm_readv>()."
1775 #: build/C/man2/process_vm_readv.2:104
1777 "The I<local_iov> and I<remote_iov> arguments point to an array of I<iovec> "
1778 "structures, defined in I<E<lt>sys/uio.hE<gt>> as:"
1782 #: build/C/man2/process_vm_readv.2:111
1786 " void *iov_base; /* Starting address */\n"
1787 " size_t iov_len; /* Number of bytes to transfer */\n"
1792 #: build/C/man2/process_vm_readv.2:127
1794 "Buffers are processed in array order. This means that B<process_vm_readv>() "
1795 "completely fills I<local_iov[0]> before proceeding to I<local_iov[1]>, and "
1796 "so on. Likewise, I<remote_iov[0]> is completely read before proceeding to "
1797 "I<remote_iov[1]>, and so on."
1801 #: build/C/man2/process_vm_readv.2:138
1803 "Similarly, B<process_vm_writev>() writes out the entire contents of "
1804 "I<local_iov[0]> before proceeding to I<local_iov[1]>, and it completely "
1805 "fills I<remote_iov[0]> before proceeding to I<remote_iov[1]>."
1809 #: build/C/man2/process_vm_readv.2:146
1811 "The lengths of I<remote_iov[i].iov_len> and I<local_iov[i].iov_len> do not "
1812 "have to be the same. Thus, it is possible to split a single local buffer "
1813 "into multiple remote buffers, or vice versa."
1817 #: build/C/man2/process_vm_readv.2:150
1818 msgid "The I<flags> argument is currently unused and must be set to 0."
1821 #. In time, glibc might provide a wrapper that works around this limit,
1822 #. as is done for readv()/writev()
1824 #: build/C/man2/process_vm_readv.2:163
1826 "The values specified in the I<liovcnt> and I<riovcnt> arguments must be less "
1827 "than or equal to B<IOV_MAX> (defined in I<E<lt>limits.hE<gt>> or accessible "
1828 "via the call I<sysconf(_SC_IOV_MAX)>)."
1832 #: build/C/man2/process_vm_readv.2:173
1834 "The count arguments and I<local_iov> are checked before doing any "
1835 "transfers. If the counts are too big, or I<local_iov> is invalid, or the "
1836 "addresses refer to regions that are inaccessible to the local process, none "
1837 "of the vectors will be processed and an error will be returned immediately."
1841 #: build/C/man2/process_vm_readv.2:193
1843 "Note, however, that these system calls do not check the memory regions in "
1844 "the remote process until just before doing the read/write. Consequently, a "
1845 "partial read/write (see RETURN VALUE) may result if one of the "
1846 "I<remote_iov> elements points to an invalid memory region in the remote "
1847 "process. No further reads/writes will be attempted beyond that point. Keep "
1848 "this in mind when attempting to read data of unknown length (such as C "
1849 "strings that are null-terminated) from a remote process, by avoiding "
1850 "spanning memory pages (typically 4KiB) in a single remote I<iovec> element. "
1851 "(Instead, split the remote read into two I<remote_iov> elements and have "
1852 "them merge back into a single write I<local_iov> entry. The first read "
1853 "entry goes up to the page boundary, while the second starts on the next page "
1858 #: build/C/man2/process_vm_readv.2:207
1860 "In order to read from or write to another process, either the caller must "
1861 "have the capability B<CAP_SYS_PTRACE>, or the real user ID, effective user "
1862 "ID, and saved set-user-ID of the remote process must match the real user ID "
1863 "of the caller I<and> the real group ID, effective group ID, and saved "
1864 "set-group-ID of the remote process must match the real group ID of the "
1865 "caller. (The permission required is exactly the same as that required to "
1866 "perform a B<ptrace>(2) B<PTRACE_ATTACH> on the remote process.)"
1870 #: build/C/man2/process_vm_readv.2:223
1872 "On success, B<process_vm_readv>() returns the number of bytes read and "
1873 "B<process_vm_writev>() returns the number of bytes written. This return "
1874 "value may be less than the total number of requested bytes, if a partial "
1875 "read/write occurred. (Partial transfers apply at the granularity of "
1876 "I<iovec> elements. These system calls won't perform a partial transfer that "
1877 "splits a single I<iovec> element.) The caller should check the return value "
1878 "to determine whether a partial read/write occurred."
1882 #: build/C/man2/process_vm_readv.2:227
1883 msgid "On error, -1 is returned and I<errno> is set appropriately."
1887 #: build/C/man2/process_vm_readv.2:239
1889 "The sum of the I<iov_len> values of either I<local_iov> or I<remote_iov> "
1890 "overflows a I<ssize_t> value."
1894 #: build/C/man2/process_vm_readv.2:243
1895 msgid "I<flags> is not 0."
1899 #: build/C/man2/process_vm_readv.2:249
1900 msgid "I<liovcnt> or I<riovcnt> is too large."
1904 #: build/C/man2/process_vm_readv.2:254
1906 "The memory described by I<local_iov> is outside the caller's accessible "
1911 #: build/C/man2/process_vm_readv.2:260
1913 "The memory described by I<remote_iov> is outside the accessible address "
1914 "space of the process I<pid>."
1918 #: build/C/man2/process_vm_readv.2:265
1919 msgid "Could not allocate memory for internal copies of the I<iovec> structures."
1923 #: build/C/man2/process_vm_readv.2:269
1925 "The caller does not have permission to access the address space of the "
1930 #: build/C/man2/process_vm_readv.2:269 build/C/man2/ptrace.2:1632 build/C/man2/quotactl.2:459 build/C/man2/quotactl.2:502
1936 #: build/C/man2/process_vm_readv.2:274
1937 msgid "No process with ID I<pid> exists."
1941 #: build/C/man2/process_vm_readv.2:277
1943 "These system calls were added in Linux 3.2. Support is provided in glibc "
1944 "since version 2.15."
1948 #: build/C/man2/process_vm_readv.2:279
1949 msgid "These system calls are nonstandard Linux extensions."
1953 #: build/C/man2/process_vm_readv.2:285
1955 "The data transfers performed by B<process_vm_readv>() and "
1956 "B<process_vm_writev>() are not guaranteed to be atomic in any way."
1959 #. Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
1960 #. See also some benchmarks at http://lwn.net/Articles/405284/
1961 #. and http://marc.info/?l=linux-mm&m=130105930902915&w=2
1963 #: build/C/man2/process_vm_readv.2:293
1965 "These system calls were designed to permit fast message passing by allowing "
1966 "messages to be exchanged with a single copy operation (rather than the "
1967 "double copy that would be required when using, for example, shared memory or "
1972 #: build/C/man2/process_vm_readv.2:293 build/C/man2/splice.2:222 build/C/man2/tee.2:129
1978 #: build/C/man2/process_vm_readv.2:301
1980 "The following code sample demonstrates the use of B<process_vm_readv>(). It "
1981 "reads 20 bytes at the address 0x10000 from the process with PID 10 and "
1982 "writes the first 10 bytes into I<buf1> and the second 10 bytes into I<buf2>."
1986 #: build/C/man2/process_vm_readv.2:304
1988 msgid "#include E<lt>sys/uio.hE<gt>\n"
1992 #: build/C/man2/process_vm_readv.2:314
1998 " struct iovec local[2];\n"
1999 " struct iovec remote[1];\n"
2003 " pid_t pid = 10; /* PID of remote process */\n"
2007 #: build/C/man2/process_vm_readv.2:321
2010 " local[0].iov_base = buf1;\n"
2011 " local[0].iov_len = 10;\n"
2012 " local[1].iov_base = buf2;\n"
2013 " local[1].iov_len = 10;\n"
2014 " remote[0].iov_base = (void *) 0x10000;\n"
2015 " remote[1].iov_len = 20;\n"
2019 #: build/C/man2/process_vm_readv.2:328
2022 " nread = process_vm_readv(pid, local, 2, remote, 1, 0);\n"
2023 " if (nread != 20)\n"
2031 #: build/C/man2/process_vm_readv.2:332
2032 msgid "B<readv>(2), B<writev>(2)"
2036 #: build/C/man2/ptrace.2:49
2042 #: build/C/man2/ptrace.2:49
2048 #: build/C/man2/ptrace.2:52
2049 msgid "ptrace - process trace"
2053 #: build/C/man2/ptrace.2:55
2055 msgid "B<#include E<lt>sys/ptrace.hE<gt>>\n"
2059 #: build/C/man2/ptrace.2:58
2062 "B<long ptrace(enum __ptrace_request >I<request>B<, pid_t >I<pid>B<, >\n"
2063 "B< void *>I<addr>B<, void *>I<data>B<);>\n"
2067 #: build/C/man2/ptrace.2:67
2069 "The B<ptrace>() system call provides a means by which one process (the "
2070 "\"tracer\") may observe and control the execution of another process (the "
2071 "\"tracee\"), and examine and change the tracee's memory and registers. It "
2072 "is primarily used to implement breakpoint debugging and system call tracing."
2076 #: build/C/man2/ptrace.2:78
2078 "A tracee first needs to be attached to the tracer. Attachment and "
2079 "subsequent commands are per thread: in a multithreaded process, every thread "
2080 "can be individually attached to a (potentially different) tracer, or left "
2081 "not attached and thus not debugged. Therefore, \"tracee\" always means "
2082 "\"(one) thread\", never \"a (possibly multithreaded) process\". Ptrace "
2083 "commands are always sent to a specific tracee using a call of the form"
2087 #: build/C/man2/ptrace.2:80
2089 msgid " ptrace(PTRACE_foo, pid, ...)\n"
2093 #: build/C/man2/ptrace.2:84
2094 msgid "where I<pid> is the thread ID of the corresponding Linux thread."
2098 #: build/C/man2/ptrace.2:90
2100 "(Note that in this page, a \"multithreaded process\" means a thread group "
2101 "consisting of threads created using the B<clone>(2) B<CLONE_THREAD> flag.)"
2105 #: build/C/man2/ptrace.2:99
2107 "A process can initiate a trace by calling B<fork>(2) and having the "
2108 "resulting child do a B<PTRACE_TRACEME>, followed (typically) by an "
2109 "B<execve>(2). Alternatively, one process may commence tracing another "
2110 "process using B<PTRACE_ATTACH>."
2114 #: build/C/man2/ptrace.2:116
2116 "While being traced, the tracee will stop each time a signal is delivered, "
2117 "even if the signal is being ignored. (An exception is B<SIGKILL>, which has "
2118 "its usual effect.) The tracer will be notified at its next call to "
2119 "B<waitpid>(2) (or one of the related \"wait\" system calls); that call will "
2120 "return a I<status> value containing information that indicates the cause of "
2121 "the stop in the tracee. While the tracee is stopped, the tracer can use "
2122 "various ptrace requests to inspect and modify the tracee. The tracer then "
2123 "causes the tracee to continue, optionally ignoring the delivered signal (or "
2124 "even delivering a different signal instead)."
2128 #: build/C/man2/ptrace.2:126
2130 "If the B<PTRACE_O_TRACEEXEC> option is not in effect, all successful calls "
2131 "to B<execve>(2) by the traced process will cause it to be sent a B<SIGTRAP> "
2132 "signal, giving the parent a chance to gain control before the new program "
2137 #: build/C/man2/ptrace.2:130
2139 "When the tracer is finished tracing, it can cause the tracee to continue "
2140 "executing in a normal, untraced mode via B<PTRACE_DETACH>."
2144 #: build/C/man2/ptrace.2:134
2145 msgid "The value of I<request> determines the action to be performed:"
2149 #: build/C/man2/ptrace.2:134
2151 msgid "B<PTRACE_TRACEME>"
2155 #: build/C/man2/ptrace.2:144
2157 "Indicate that this process is to be traced by its parent. A process "
2158 "probably shouldn't make this request if its parent isn't expecting to trace "
2159 "it. (I<pid>, I<addr>, and I<data> are ignored.)"
2163 #: build/C/man2/ptrace.2:157
2165 "The B<PTRACE_TRACEME> request is used only by the tracee; the remaining "
2166 "requests are used only by the tracer. In the following requests, I<pid> "
2167 "specifies the thread ID of the tracee to be acted on. For requests other "
2168 "than B<PTRACE_ATTACH> and B<PTRACE_KILL>, the tracee must be stopped."
2172 #: build/C/man2/ptrace.2:157
2174 msgid "B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>"
2178 #: build/C/man2/ptrace.2:168
2180 "Read a word at the address I<addr> in the tracee's memory, returning the "
2181 "word as the result of the B<ptrace>() call. Linux does not have separate "
2182 "text and data address spaces, so these two requests are currently "
2183 "equivalent. (I<data> is ignored.)"
2187 #: build/C/man2/ptrace.2:168
2189 msgid "B<PTRACE_PEEKUSER>"
2192 #. PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
2193 #. and that is the name that seems common on other systems.
2195 #: build/C/man2/ptrace.2:186
2197 "Read a word at offset I<addr> in the tracee's USER area, which holds the "
2198 "registers and other information about the process (see "
2199 "I<E<lt>sys/user.hE<gt>>). The word is returned as the result of the "
2200 "B<ptrace>() call. Typically, the offset must be word-aligned, though this "
2201 "might vary by architecture. See NOTES. (I<data> is ignored.)"
2205 #: build/C/man2/ptrace.2:186
2207 msgid "B<PTRACE_POKETEXT>, B<PTRACE_POKEDATA>"
2211 #: build/C/man2/ptrace.2:198
2213 "Copy the word I<data> to the address I<addr> in the tracee's memory. As for "
2214 "B<PTRACE_PEEKTEXT> and B<PTRACE_PEEKDATA>, these two requests are currently "
2219 #: build/C/man2/ptrace.2:198
2221 msgid "B<PTRACE_POKEUSER>"
2224 #. PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
2225 #. and that is the name that seems common on other systems.
2226 #. FIXME In the preceding sentence, which modifications are disallowed,
2227 #. and when they are disallowed, how does userspace discover that fact?
2229 #: build/C/man2/ptrace.2:214
2231 "Copy the word I<data> to offset I<addr> in the tracee's USER area. As for "
2232 "B<PTRACE_PEEKUSER>, the offset must typically be word-aligned. In order to "
2233 "maintain the integrity of the kernel, some modifications to the USER area "
2238 #: build/C/man2/ptrace.2:214
2240 msgid "B<PTRACE_GETREGS>, B<PTRACE_GETFPREGS>"
2244 #: build/C/man2/ptrace.2:233
2246 "Copy the tracee's general-purpose or floating-point registers, respectively, "
2247 "to the address I<data> in the tracer. See I<E<lt>sys/user.hE<gt>> for "
2248 "information on the format of this data. (I<addr> is ignored.) Note that "
2249 "SPARC systems have the meaning of I<data> and I<addr> reversed; that is, "
2250 "I<data> is ignored and the registers are copied to the address I<addr>."
2254 #: build/C/man2/ptrace.2:233
2256 msgid "B<PTRACE_GETSIGINFO> (since Linux 2.3.99-pre6)"
2260 #: build/C/man2/ptrace.2:245
2262 "Retrieve information about the signal that caused the stop. Copy a "
2263 "I<siginfo_t> structure (see B<sigaction>(2)) from the tracee to the address "
2264 "I<data> in the tracer. (I<addr> is ignored.)"
2268 #: build/C/man2/ptrace.2:245
2270 msgid "B<PTRACE_SETREGS>, B<PTRACE_SETFPREGS>"
2273 #. FIXME In the preceding sentence, which modifications are disallowed,
2274 #. and when they are disallowed, how does userspace discover that fact?
2276 #: build/C/man2/ptrace.2:266
2278 "Copy the tracee's general-purpose or floating-point registers, respectively, "
2279 "from the address I<data> in the tracer. As for B<PTRACE_POKEUSER>, some "
2280 "general-purpose register modifications may be disallowed. (I<addr> is "
2281 "ignored.) Note that SPARC systems have the meaning of I<data> and I<addr> "
2282 "reversed; that is, I<data> is ignored and the registers are copied from the "
2287 #: build/C/man2/ptrace.2:266
2289 msgid "B<PTRACE_SETSIGINFO> (since Linux 2.3.99-pre6)"
2293 #: build/C/man2/ptrace.2:282
2295 "Set signal information: copy a I<siginfo_t> structure from the address "
2296 "I<data> in the tracer to the tracee. This will affect only signals that "
2297 "would normally be delivered to the tracee and were caught by the tracer. It "
2298 "may be difficult to tell these normal signals from synthetic signals "
2299 "generated by B<ptrace>() itself. (I<addr> is ignored.)"
2303 #: build/C/man2/ptrace.2:282
2305 msgid "B<PTRACE_SETOPTIONS> (since Linux 2.4.6; see BUGS for caveats)"
2309 #: build/C/man2/ptrace.2:291
2311 "Set ptrace options from I<data>. (I<addr> is ignored.) I<data> is "
2312 "interpreted as a bit mask of options, which are specified by the following "
2317 #: build/C/man2/ptrace.2:292
2319 msgid "B<PTRACE_O_TRACESYSGOOD> (since Linux 2.4.6)"
2323 #: build/C/man2/ptrace.2:301
2325 "When delivering system call traps, set bit 7 in the signal number (i.e., "
2326 "deliver I<SIGTRAP|0x80>). This makes it easy for the tracer to distinguish "
2327 "normal traps from those caused by a system call. (B<PTRACE_O_TRACESYSGOOD> "
2328 "may not work on all architectures.)"
2332 #: build/C/man2/ptrace.2:301
2334 msgid "B<PTRACE_O_TRACEFORK> (since Linux 2.5.46)"
2338 #: build/C/man2/ptrace.2:313
2340 "Stop the tracee at the next B<fork>(2) and automatically start tracing the "
2341 "newly forked process, which will start with a B<SIGSTOP>. A B<waitpid>(2) "
2342 "by the tracer will return a I<status> value such that"
2346 #: build/C/man2/ptrace.2:316
2348 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_FORKE<lt>E<lt>8))\n"
2352 #: build/C/man2/ptrace.2:320 build/C/man2/ptrace.2:339 build/C/man2/ptrace.2:358
2353 msgid "The PID of the new process can be retrieved with B<PTRACE_GETEVENTMSG>."
2357 #: build/C/man2/ptrace.2:320
2359 msgid "B<PTRACE_O_TRACEVFORK> (since Linux 2.5.46)"
2363 #: build/C/man2/ptrace.2:332
2365 "Stop the tracee at the next B<vfork>(2) and automatically start tracing the "
2366 "newly vforked process, which will start with a B<SIGSTOP>. A B<waitpid>(2) "
2367 "by the tracer will return a I<status> value such that"
2371 #: build/C/man2/ptrace.2:335
2373 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORKE<lt>E<lt>8))\n"
2377 #: build/C/man2/ptrace.2:339
2379 msgid "B<PTRACE_O_TRACECLONE> (since Linux 2.5.46)"
2383 #: build/C/man2/ptrace.2:351
2385 "Stop the tracee at the next B<clone>(2) and automatically start tracing the "
2386 "newly cloned process, which will start with a B<SIGSTOP>. A B<waitpid>(2) "
2387 "by the tracer will return a I<status> value such that"
2391 #: build/C/man2/ptrace.2:354
2393 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_CLONEE<lt>E<lt>8))\n"
2397 #: build/C/man2/ptrace.2:379
2399 "This option may not catch B<clone>(2) calls in all cases. If the tracee "
2400 "calls B<clone>(2) with the B<CLONE_VFORK> flag, B<PTRACE_EVENT_VFORK> will "
2401 "be delivered instead if B<PTRACE_O_TRACEVFORK> is set; otherwise if the "
2402 "tracee calls B<clone>(2) with the exit signal set to B<SIGCHLD>, "
2403 "B<PTRACE_EVENT_FORK> will be delivered if B<PTRACE_O_TRACEFORK> is set."
2407 #: build/C/man2/ptrace.2:379
2409 msgid "B<PTRACE_O_TRACEEXEC> (since Linux 2.5.46)"
2413 #: build/C/man2/ptrace.2:388
2415 "Stop the tracee at the next B<execve>(2). A B<waitpid>(2) by the tracer "
2416 "will return a I<status> value such that"
2420 #: build/C/man2/ptrace.2:391
2422 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXECE<lt>E<lt>8))\n"
2426 #: build/C/man2/ptrace.2:397
2428 "If the execing thread is not a thread group leader, the thread ID is reset "
2429 "to thread group leader's ID before this stop. Since Linux 3.0, the former "
2430 "thread ID can be retrieved with B<PTRACE_GETEVENTMSG>."
2434 #: build/C/man2/ptrace.2:397
2436 msgid "B<PTRACE_O_TRACEVFORKDONE> (since Linux 2.5.60)"
2440 #: build/C/man2/ptrace.2:406
2442 "Stop the tracee at the completion of the next B<vfork>(2). A B<waitpid>(2) "
2443 "by the tracer will return a I<status> value such that"
2447 #: build/C/man2/ptrace.2:409
2449 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONEE<lt>E<lt>8))\n"
2453 #: build/C/man2/ptrace.2:413
2455 "The PID of the new process can (since Linux 2.6.18) be retrieved with "
2456 "B<PTRACE_GETEVENTMSG>."
2460 #: build/C/man2/ptrace.2:413
2462 msgid "B<PTRACE_O_TRACEEXIT> (since Linux 2.5.60)"
2466 #: build/C/man2/ptrace.2:421
2468 "Stop the tracee at exit. A B<waitpid>(2) by the tracer will return a "
2469 "I<status> value such that"
2473 #: build/C/man2/ptrace.2:424
2475 msgid " statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXITE<lt>E<lt>8))\n"
2479 #: build/C/man2/ptrace.2:428
2480 msgid "The tracee's exit status can be retrieved with B<PTRACE_GETEVENTMSG>."
2484 #: build/C/man2/ptrace.2:436
2486 "The tracee is stopped early during process exit, when registers are still "
2487 "available, allowing the tracer to see where the exit occurred, whereas the "
2488 "normal exit notification is done after the process is finished exiting. "
2489 "Even though context is available, the tracer cannot prevent the exit from "
2490 "happening at this point."
2494 #: build/C/man2/ptrace.2:437
2496 msgid "B<PTRACE_GETEVENTMSG> (since Linux 2.5.46)"
2500 #: build/C/man2/ptrace.2:457
2502 "Retrieve a message (as an I<unsigned long>) about the ptrace event that "
2503 "just happened, placing it at the address I<data> in the tracer. For "
2504 "B<PTRACE_EVENT_EXIT>, this is the tracee's exit status. For "
2505 "B<PTRACE_EVENT_FORK>, B<PTRACE_EVENT_VFORK>, B<PTRACE_EVENT_VFORK_DONE>, and "
2506 "B<PTRACE_EVENT_CLONE>, this is the PID of the new process. (I<addr> is "
2511 #: build/C/man2/ptrace.2:457
2513 msgid "B<PTRACE_CONT>"
2517 #: build/C/man2/ptrace.2:469
2519 "Restart the stopped tracee process. If I<data> is nonzero, it is "
2520 "interpreted as the number of a signal to be delivered to the tracee; "
2521 "otherwise, no signal is delivered. Thus, for example, the tracer can "
2522 "control whether a signal sent to the tracee is delivered or not. (I<addr> "
2527 #: build/C/man2/ptrace.2:469
2529 msgid "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>"
2533 #: build/C/man2/ptrace.2:493
2535 "Restart the stopped tracee as for B<PTRACE_CONT>, but arrange for the tracee "
2536 "to be stopped at the next entry to or exit from a system call, or after "
2537 "execution of a single instruction, respectively. (The tracee will also, as "
2538 "usual, be stopped upon receipt of a signal.) From the tracer's perspective, "
2539 "the tracee will appear to have been stopped by receipt of a B<SIGTRAP>. So, "
2540 "for B<PTRACE_SYSCALL>, for example, the idea is to inspect the arguments to "
2541 "the system call at the first stop, then do another B<PTRACE_SYSCALL> and "
2542 "inspect the return value of the system call at the second stop. The I<data> "
2543 "argument is treated as for B<PTRACE_CONT>. (I<addr> is ignored.)"
2547 #: build/C/man2/ptrace.2:493
2549 msgid "B<PTRACE_SYSEMU>, B<PTRACE_SYSEMU_SINGLESTEP> (since Linux 2.6.14)"
2553 #: build/C/man2/ptrace.2:511
2555 "For B<PTRACE_SYSEMU>, continue and stop on entry to the next system call, "
2556 "which will not be executed. For B<PTRACE_SYSEMU_SINGLESTEP>, do the same "
2557 "but also singlestep if not a system call. This call is used by programs "
2558 "like User Mode Linux that want to emulate all the tracee's system calls. "
2559 "The I<data> argument is treated as for B<PTRACE_CONT>. (I<addr> is ignored; "
2560 "not supported on all architectures.)"
2564 #: build/C/man2/ptrace.2:511
2566 msgid "B<PTRACE_KILL>"
2570 #: build/C/man2/ptrace.2:520
2572 "Send the tracee a B<SIGKILL> to terminate it. (I<addr> and I<data> are "
2576 #. [Note from Denys Vlasenko:
2577 #. deprecation suggested by Oleg Nesterov. He prefers to deprecate it
2578 #. instead of describing (and needing to support) PTRACE_KILL's quirks.]
2580 #: build/C/man2/ptrace.2:539
2582 "I<This operation is deprecated; do not use it!> Instead, send a B<SIGKILL> "
2583 "directly using B<kill>(2) or B<tgkill>(2). The problem with B<PTRACE_KILL> "
2584 "is that it requires the tracee to be in signal-delivery-stop, otherwise it "
2585 "may not work (i.e., may complete successfully but won't kill the tracee). "
2586 "By contrast, sending a B<SIGKILL> directly has no such limitation."
2590 #: build/C/man2/ptrace.2:539
2592 msgid "B<PTRACE_ATTACH>"
2595 #. No longer true (removed by Denys Vlasenko, 2011, who remarks:
2596 #. "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
2597 #. Basically, it's not true for any Linux in practical use.
2598 #. ; the behavior of the tracee is as if it had done a
2599 #. .BR PTRACE_TRACEME .
2600 #. The calling process actually becomes the parent of the tracee
2601 #. process for most purposes (e.g., it will receive
2602 #. notification of tracee events and appears in
2604 #. output as the tracee's parent), but a
2606 #. by the tracee will still return the PID of the original parent.
2608 #: build/C/man2/ptrace.2:567
2610 "Attach to the process specified in I<pid>, making it a tracee of the calling "
2611 "process. The tracee is sent a B<SIGSTOP>, but will not necessarily have "
2612 "stopped by the completion of this call; use B<waitpid>(2) to wait for the "
2613 "tracee to stop. See the \"Attaching and detaching\" subsection for "
2614 "additional information. (I<addr> and I<data> are ignored.)"
2618 #: build/C/man2/ptrace.2:567
2620 msgid "B<PTRACE_DETACH>"
2624 #: build/C/man2/ptrace.2:576
2626 "Restart the stopped tracee as for B<PTRACE_CONT>, but first detach from it. "
2627 "Under Linux, a tracee can be detached in this way regardless of which method "
2628 "was used to initiate tracing. (I<addr> is ignored.)"
2632 #: build/C/man2/ptrace.2:576
2634 msgid "Death under ptrace"
2638 #: build/C/man2/ptrace.2:585
2640 "When a (possibly multithreaded) process receives a killing signal (one whose "
2641 "disposition is set to B<SIG_DFL> and whose default action is to kill the "
2642 "process), all threads exit. Tracees report their death to their tracer(s). "
2643 "Notification of this event is delivered via B<waitpid>(2)."
2647 #: build/C/man2/ptrace.2:594
2649 "Note that the killing signal will first cause signal-delivery-stop (on one "
2650 "tracee only), and only after it is injected by the tracer (or after it was "
2651 "dispatched to a thread which isn't traced), will death from the signal "
2652 "happen on I<all> tracees within a multithreaded process. (The term "
2653 "\"signal-delivery-stop\" is explained below.)"
2657 #: build/C/man2/ptrace.2:608
2659 "B<SIGKILL> operates similarly, with exceptions. No signal-delivery-stop is "
2660 "generated for B<SIGKILL> and therefore the tracer can't suppress it. "
2661 "B<SIGKILL> kills even within system calls (syscall-exit-stop is not "
2662 "generated prior to death by B<SIGKILL>). The net effect is that B<SIGKILL> "
2663 "always kills the process (all its threads), even if some threads of the "
2664 "process are ptraced."
2668 #: build/C/man2/ptrace.2:613
2670 "When the tracee calls B<_exit>(2), it reports its death to its tracer. "
2671 "Other threads are not affected."
2675 #: build/C/man2/ptrace.2:617
2677 "When any thread executes B<exit_group>(2), every tracee in its thread group "
2678 "reports its death to its tracer."
2682 #: build/C/man2/ptrace.2:631
2684 "If the B<PTRACE_O_TRACEEXIT> option is on, B<PTRACE_EVENT_EXIT> will happen "
2685 "before actual death. This applies to exits via B<exit>(2), "
2686 "B<exit_group>(2), and signal deaths (except B<SIGKILL>), and when threads "
2687 "are torn down on B<execve>(2) in a multithreaded process."
2691 #: build/C/man2/ptrace.2:656
2693 "The tracer cannot assume that the ptrace-stopped tracee exists. There are "
2694 "many scenarios when the tracee may die while stopped (such as B<SIGKILL>). "
2695 "Therefore, the tracer must be prepared to handle an B<ESRCH> error on any "
2696 "ptrace operation. Unfortunately, the same error is returned if the tracee "
2697 "exists but is not ptrace-stopped (for commands which require a stopped "
2698 "tracee), or if it is not traced by the process which issued the ptrace "
2699 "call. The tracer needs to keep track of the stopped/running state of the "
2700 "tracee, and interpret B<ESRCH> as \"tracee died unexpectedly\" only if it "
2701 "knows that the tracee has been observed to enter ptrace-stop. Note that "
2702 "there is no guarantee that I<waitpid(WNOHANG)> will reliably report the "
2703 "tracee's death status if a ptrace operation returned B<ESRCH>. "
2704 "I<waitpid(WNOHANG)> may return 0 instead. In other words, the tracee may be "
2705 "\"not yet fully dead\", but already refusing ptrace requests."
2709 #: build/C/man2/ptrace.2:670
2711 "The tracer can't assume that the tracee I<always> ends its life by reporting "
2712 "I<WIFEXITED(status)> or I<WIFSIGNALED(status)>; there are cases where this "
2713 "does not occur. For example, if a thread other than thread group leader "
2714 "does an B<execve>(2), it disappears; its PID will never be seen again, and "
2715 "any subsequent ptrace stops will be reported under the thread group leader's "
2720 #: build/C/man2/ptrace.2:670
2722 msgid "Stopped states"
2726 #: build/C/man2/ptrace.2:672
2727 msgid "A tracee can be in two states: running or stopped."
2731 #: build/C/man2/ptrace.2:676
2733 "There are many kinds of states when the tracee is stopped, and in ptrace "
2734 "discussions they are often conflated. Therefore, it is important to use "
2739 #: build/C/man2/ptrace.2:687
2741 "In this manual page, any stopped state in which the tracee is ready to "
2742 "accept ptrace commands from the tracer is called I<ptrace-stop>. "
2743 "Ptrace-stops can be further subdivided into I<signal-delivery-stop>, "
2744 "I<group-stop>, I<syscall-stop>, and so on. These stopped states are "
2745 "described in detail below."
2749 #: build/C/man2/ptrace.2:692
2751 "When the running tracee enters ptrace-stop, it notifies its tracer using "
2752 "B<waitpid>(2) (or one of the other \"wait\" system calls). Most of this "
2753 "manual page assumes that the tracer waits with:"
2757 #: build/C/man2/ptrace.2:694
2759 msgid " pid = waitpid(pid_or_minus_1, &status, __WALL);\n"
2763 #. Do we require __WALL usage, or will just using 0 be ok? (With 0,
2764 #. I am not 100% sure there aren't ugly corner cases.) Are the
2765 #. rules different if user wants to use waitid? Will waitid require
2768 #: build/C/man2/ptrace.2:706
2770 "Ptrace-stopped tracees are reported as returns with I<pid> greater than 0 "
2771 "and I<WIFSTOPPED(status)> true."
2775 #: build/C/man2/ptrace.2:714
2777 "The B<__WALL> flag does not include the B<WSTOPPED> and B<WEXITED> flags, "
2778 "but implies their functionality."
2782 #: build/C/man2/ptrace.2:721
2784 "Setting the B<WCONTINUED> flag when calling B<waitpid>(2) is not "
2785 "recommended: the \"continued\" state is per-process and consuming it can "
2786 "confuse the real parent of the tracee."
2790 #: build/C/man2/ptrace.2:729
2792 "Use of the B<WNOHANG> flag may cause B<waitpid>(2) to return 0 (\"no wait "
2793 "results available yet\") even if the tracer knows there should be a "
2794 "notification. Example:"
2798 #: build/C/man2/ptrace.2:733
2801 " kill(tracee, SIGKILL);\n"
2802 " waitpid(tracee, &status, __WALL | WNOHANG);\n"
2806 #: build/C/man2/ptrace.2:756
2808 "The following kinds of ptrace-stops exist: signal-delivery-stops, "
2809 "group-stops, B<PTRACE_EVENT> stops, syscall-stops. They all are reported by "
2810 "B<waitpid>(2) with I<WIFSTOPPED(status)> true. They may be differentiated "
2811 "by examining the value I<statusE<gt>E<gt>8>, and if there is ambiguity in "
2812 "that value, by querying B<PTRACE_GETSIGINFO>. (Note: the "
2813 "I<WSTOPSIG(status)> macro can't be used to perform this examination, because "
2814 "it returns the value I<(status\\E<gt>E<gt>8)\\ &\\ 0xff>.)"
2818 #: build/C/man2/ptrace.2:756
2820 msgid "Signal-delivery-stop"
2824 #: build/C/man2/ptrace.2:776
2826 "When a (possibly multithreaded) process receives any signal except "
2827 "B<SIGKILL>, the kernel selects an arbitrary thread which handles the "
2828 "signal. (If the signal is generated with B<tgkill>(2), the target thread "
2829 "can be explicitly selected by the caller.) If the selected thread is "
2830 "traced, it enters signal-delivery-stop. At this point, the signal is not "
2831 "yet delivered to the process, and can be suppressed by the tracer. If the "
2832 "tracer doesn't suppress the signal, it passes the signal to the tracee in "
2833 "the next ptrace restart request. This second step of signal delivery is "
2834 "called I<signal injection> in this manual page. Note that if the signal is "
2835 "blocked, signal-delivery-stop doesn't happen until the signal is unblocked, "
2836 "with the usual exception that B<SIGSTOP> can't be blocked."
2840 #: build/C/man2/ptrace.2:790
2842 "Signal-delivery-stop is observed by the tracer as B<waitpid>(2) returning "
2843 "with I<WIFSTOPPED(status)> true, with the signal returned by "
2844 "I<WSTOPSIG(status)>. If the signal is B<SIGTRAP>, this may be a different "
2845 "kind of ptrace-stop; see the \"Syscall-stops\" and \"execve\" sections below "
2846 "for details. If I<WSTOPSIG(status)> returns a stopping signal, this may be "
2847 "a group-stop; see below."
2851 #: build/C/man2/ptrace.2:790
2853 msgid "Signal injection and suppression"
2857 #: build/C/man2/ptrace.2:793
2859 "After signal-delivery-stop is observed by the tracer, the tracer should "
2860 "restart the tracee with the call"
2864 #: build/C/man2/ptrace.2:795
2866 msgid " ptrace(PTRACE_restart, pid, 0, sig)\n"
2870 #: build/C/man2/ptrace.2:808
2872 "where B<PTRACE_restart> is one of the restarting ptrace requests. If I<sig> "
2873 "is 0, then a signal is not delivered. Otherwise, the signal I<sig> is "
2874 "delivered. This operation is called I<signal injection> in this manual "
2875 "page, to distinguish it from signal-delivery-stop."
2879 #: build/C/man2/ptrace.2:814
2881 "The I<sig> value may be different from the I<WSTOPSIG(status)> value: the "
2882 "tracer can cause a different signal to be injected."
2886 #: build/C/man2/ptrace.2:830
2888 "Note that a suppressed signal still causes system calls to return "
2889 "prematurely. In this case system calls will be restarted: the tracer will "
2890 "observe the tracee to reexecute the interrupted system call (or "
2891 "B<restart_syscall>(2) system call for a few syscalls which use a different "
2892 "mechanism for restarting) if the tracer uses B<PTRACE_SYSCALL>. Even system "
2893 "calls (such as B<poll>(2)) which are not restartable after signal are "
2894 "restarted after signal is suppressed; however, kernel bugs exist which cause "
2895 "some syscalls to fail with B<EINTR> even though no observable signal is "
2896 "injected to the tracee."
2900 #: build/C/man2/ptrace.2:841
2902 "Restarting ptrace commands issued in ptrace-stops other than "
2903 "signal-delivery-stop are not guaranteed to inject a signal, even if I<sig> "
2904 "is nonzero. No error is reported; a nonzero I<sig> may simply be ignored. "
2905 "Ptrace users should not try to \"create a new signal\" this way: use "
2906 "B<tgkill>(2) instead."
2910 #: build/C/man2/ptrace.2:848
2912 "The fact that signal injection requests may be ignored when restarting the "
2913 "tracee after ptrace stops that are not signal-delivery-stops is a cause of "
2914 "confusion among ptrace users. One typical scenario is that the tracer "
2915 "observes group-stop, mistakes it for signal-delivery-stop, restarts the "
2920 #: build/C/man2/ptrace.2:850
2922 msgid " ptrace(PTRACE_rest, pid, 0, stopsig)\n"
2926 #: build/C/man2/ptrace.2:856
2928 "with the intention of injecting I<stopsig>, but I<stopsig> gets ignored and "
2929 "the tracee continues to run."
2933 #: build/C/man2/ptrace.2:876
2935 "The B<SIGCONT> signal has a side effect of waking up (all threads of) a "
2936 "group-stopped process. This side effect happens before "
2937 "signal-delivery-stop. The tracer can't suppress this side effect (it can "
2938 "only suppress signal injection, which only causes the B<SIGCONT> handler to "
2939 "not be executed in the tracee, if such a handler is installed). In fact, "
2940 "waking up from group-stop may be followed by signal-delivery-stop for "
2941 "signal(s) I<other than> B<SIGCONT>, if they were pending when B<SIGCONT> "
2942 "was delivered. In other words, B<SIGCONT> may be not the first signal "
2943 "observed by the tracee after it was sent."
2947 #: build/C/man2/ptrace.2:880
2949 "Stopping signals cause (all threads of) a process to enter group-stop. This "
2950 "side effect happens after signal injection, and therefore can be suppressed "
2954 #. In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
2957 #. /* The debugger continued. Ignore SIGSTOP. */
2958 #. if (signr == SIGSTOP)
2961 #: build/C/man2/ptrace.2:890
2962 msgid "In Linux 2.4 and earlier, the B<SIGSTOP> signal can't be injected."
2966 #: build/C/man2/ptrace.2:907
2968 "B<PTRACE_GETSIGINFO> can be used to retrieve a I<siginfo_t> structure which "
2969 "corresponds to the delivered signal. B<PTRACE_SETSIGINFO> may be used to "
2970 "modify it. If B<PTRACE_SETSIGINFO> has been used to alter I<siginfo_t>, the "
2971 "I<si_signo> field and the I<sig> parameter in the restarting command must "
2972 "match, otherwise the result is undefined."
2976 #: build/C/man2/ptrace.2:907
2982 #: build/C/man2/ptrace.2:919
2984 "When a (possibly multithreaded) process receives a stopping signal, all "
2985 "threads stop. If some threads are traced, they enter a group-stop. Note "
2986 "that the stopping signal will first cause signal-delivery-stop (on one "
2987 "tracee only), and only after it is injected by the tracer (or after it was "
2988 "dispatched to a thread which isn't traced), will group-stop be initiated on "
2989 "I<all> tracees within the multithreaded process. As usual, every tracee "
2990 "reports its group-stop separately to the corresponding tracer."
2994 #: build/C/man2/ptrace.2:928
2996 "Group-stop is observed by the tracer as B<waitpid>(2) returning with "
2997 "I<WIFSTOPPED(status)> true, with the stopping signal available via "
2998 "I<WSTOPSIG(status)>. The same result is returned by some other classes of "
2999 "ptrace-stops, therefore the recommended practice is to perform the call"
3003 #: build/C/man2/ptrace.2:930
3005 msgid " ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)\n"
3009 #: build/C/man2/ptrace.2:951
3011 "The call can be avoided if the signal is not B<SIGSTOP>, B<SIGTSTP>, "
3012 "B<SIGTTIN>, or B<SIGTTOU>; only these four signals are stopping signals. If "
3013 "the tracer sees something else, it can't be a group-stop. Otherwise, the "
3014 "tracer needs to call B<PTRACE_GETSIGINFO>. If B<PTRACE_GETSIGINFO> fails "
3015 "with B<EINVAL>, then it is definitely a group-stop. (Other failure codes "
3016 "are possible, such as B<ESRCH> (\"no such process\") if a B<SIGKILL> killed "
3021 #: build/C/man2/ptrace.2:960
3023 "As of kernel 2.6.38, after the tracer sees the tracee ptrace-stop and until "
3024 "it restarts or kills it, the tracee will not run, and will not send "
3025 "notifications (except B<SIGKILL> death) to the tracer, even if the tracer "
3026 "enters into another B<waitpid>(2) call."
3030 #: build/C/man2/ptrace.2:974
3032 "The kernel behavior described in the previous paragraph causes a problem "
3033 "with transparent handling of stopping signals. If the tracer restarts the "
3034 "tracee after group-stop, the stopping signal is effectively ignored\\(emthe "
3035 "tracee doesn't remain stopped, it runs. If the tracer doesn't restart the "
3036 "tracee before entering into the next B<waitpid>(2), future B<SIGCONT> "
3037 "signals will not be reported to the tracer; this would cause the B<SIGCONT> "
3038 "signals to have no effect on the tracee."
3042 #: build/C/man2/ptrace.2:974
3044 msgid "PTRACE_EVENT stops"
3048 #: build/C/man2/ptrace.2:980
3050 "If the tracer sets B<PTRACE_O_TRACE_*> options, the tracee will enter "
3051 "ptrace-stops called B<PTRACE_EVENT> stops."
3055 #: build/C/man2/ptrace.2:994
3057 "B<PTRACE_EVENT> stops are observed by the tracer as B<waitpid>(2) returning "
3058 "with I<WIFSTOPPED(status)>, and I<WSTOPSIG(status)> returns B<SIGTRAP>. An "
3059 "additional bit is set in the higher byte of the status word: the value "
3060 "I<statusE<gt>E<gt>8> will be"
3064 #: build/C/man2/ptrace.2:996
3066 msgid " (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
3070 #: build/C/man2/ptrace.2:998
3071 msgid "The following events exist:"
3075 #: build/C/man2/ptrace.2:998
3077 msgid "B<PTRACE_EVENT_VFORK>"
3081 #: build/C/man2/ptrace.2:1011
3083 "Stop before return from B<vfork>(2) or B<clone>(2) with the B<CLONE_VFORK> "
3084 "flag. When the tracee is continued after this stop, it will wait for child "
3085 "to exit/exec before continuing its execution (in other words, the usual "
3086 "behavior on B<vfork>(2))."
3090 #: build/C/man2/ptrace.2:1011
3092 msgid "B<PTRACE_EVENT_FORK>"
3096 #: build/C/man2/ptrace.2:1019
3098 "Stop before return from B<fork>(2) or B<clone>(2) with the exit signal set "
3103 #: build/C/man2/ptrace.2:1019
3105 msgid "B<PTRACE_EVENT_CLONE>"
3109 #: build/C/man2/ptrace.2:1023
3110 msgid "Stop before return from B<clone>(2)."
3114 #: build/C/man2/ptrace.2:1023
3116 msgid "B<PTRACE_EVENT_VFORK_DONE>"
3120 #: build/C/man2/ptrace.2:1033
3122 "Stop before return from B<vfork>(2) or B<clone>(2) with the B<CLONE_VFORK> "
3123 "flag, but after the child unblocked this tracee by exiting or execing."
3127 #: build/C/man2/ptrace.2:1039
3129 "For all four stops described above, the stop occurs in the parent (i.e., the "
3130 "tracee), not in the newly created thread. B<PTRACE_GETEVENTMSG> can be used "
3131 "to retrieve the new thread's ID."
3135 #: build/C/man2/ptrace.2:1039
3137 msgid "B<PTRACE_EVENT_EXEC>"
3141 #: build/C/man2/ptrace.2:1046
3143 "Stop before return from B<execve>(2). Since Linux 3.0, "
3144 "B<PTRACE_GETEVENTMSG> returns the former thread ID."
3148 #: build/C/man2/ptrace.2:1046
3150 msgid "B<PTRACE_EVENT_EXIT>"
3154 #: build/C/man2/ptrace.2:1062
3156 "Stop before exit (including death from B<exit_group>(2)), signal death, or "
3157 "exit caused by B<execve>(2) in a multithreaded process. "
3158 "B<PTRACE_GETEVENTMSG> returns the exit status. Registers can be examined "
3159 "(unlike when \"real\" exit happens). The tracee is still alive; it needs to "
3160 "be B<PTRACE_CONT>ed or B<PTRACE_DETACH>ed to finish exiting."
3164 #: build/C/man2/ptrace.2:1074
3166 "B<PTRACE_GETSIGINFO> on B<PTRACE_EVENT> stops returns B<SIGTRAP> in "
3167 "I<si_signo>, with I<si_code> set to I<(eventE<lt>E<lt>8)\\ |\\ SIGTRAP>."
3171 #: build/C/man2/ptrace.2:1074
3173 msgid "Syscall-stops"
3177 #: build/C/man2/ptrace.2:1087
3179 "If the tracee was restarted by B<PTRACE_SYSCALL>, the tracee enters "
3180 "syscall-enter-stop just prior to entering any system call. If the tracer "
3181 "restarts the tracee with B<PTRACE_SYSCALL>, the tracee enters "
3182 "syscall-exit-stop when the system call is finished, or if it is interrupted "
3183 "by a signal. (That is, signal-delivery-stop never happens between "
3184 "syscall-enter-stop and syscall-exit-stop; it happens I<after> "
3185 "syscall-exit-stop.)"
3189 #: build/C/man2/ptrace.2:1101
3191 "Other possibilities are that the tracee may stop in a B<PTRACE_EVENT> stop, "
3192 "exit (if it entered B<_exit>(2) or B<exit_group>(2)), be killed by "
3193 "B<SIGKILL>, or die silently (if it is a thread group leader, the "
3194 "B<execve>(2) happened in another thread, and that thread is not traced by "
3195 "the same tracer; this situation is discussed later)."
3199 #: build/C/man2/ptrace.2:1116
3201 "Syscall-enter-stop and syscall-exit-stop are observed by the tracer as "
3202 "B<waitpid>(2) returning with I<WIFSTOPPED(status)> true, and "
3203 "I<WSTOPSIG(status)> giving B<SIGTRAP>. If the B<PTRACE_O_TRACESYSGOOD> "
3204 "option was set by the tracer, then I<WSTOPSIG(status)> will give the value "
3205 "I<(SIGTRAP\\ |\\ 0x80)>."
3209 #: build/C/man2/ptrace.2:1122
3211 "Syscall-stops can be distinguished from signal-delivery-stop with B<SIGTRAP> "
3212 "by querying B<PTRACE_GETSIGINFO> for the following cases:"
3216 #: build/C/man2/ptrace.2:1122
3218 msgid "I<si_code> E<lt>= 0"
3222 #: build/C/man2/ptrace.2:1134
3224 "B<SIGTRAP> was delivered as a result of a userspace action, for example, a "
3225 "system call (B<tgkill>(2), B<kill>(2), B<sigqueue>(3), etc.), expiration of "
3226 "a POSIX timer, change of state on a POSIX message queue, or completion of an "
3227 "asynchronous I/O request."
3231 #: build/C/man2/ptrace.2:1134
3233 msgid "I<si_code> == SI_KERNEL (0x80)"
3237 #: build/C/man2/ptrace.2:1138
3238 msgid "B<SIGTRAP> was sent by the kernel."
3242 #: build/C/man2/ptrace.2:1138
3244 msgid "I<si_code> == SIGTRAP or I<si_code> == (SIGTRAP|0x80)"
3248 #: build/C/man2/ptrace.2:1141
3249 msgid "This is a syscall-stop."
3253 #: build/C/man2/ptrace.2:1146
3255 "However, syscall-stops happen very often (twice per system call), and "
3256 "performing B<PTRACE_GETSIGINFO> for every syscall-stop may be somewhat "
3261 #: build/C/man2/ptrace.2:1169
3263 "Some architectures allow the cases to be distinguished by examining "
3264 "registers. For example, on x86, I<rax> == -B<ENOSYS> in "
3265 "syscall-enter-stop. Since B<SIGTRAP> (like any other signal) always happens "
3266 "I<after> syscall-exit-stop, and at this point I<rax> almost never contains "
3267 "-B<ENOSYS>, the B<SIGTRAP> looks like \"syscall-stop which is not "
3268 "syscall-enter-stop\"; in other words, it looks like a \"stray "
3269 "syscall-exit-stop\" and can be detected this way. But such detection is "
3270 "fragile and is best avoided."
3274 #: build/C/man2/ptrace.2:1175
3276 "Using the B<PTRACE_O_TRACESYSGOOD> option is the recommended method to "
3277 "distinguish syscall-stops from other kinds of ptrace-stops, since it is "
3278 "reliable and does not incur a performance penalty."
3282 #: build/C/man2/ptrace.2:1186
3284 "Syscall-enter-stop and syscall-exit-stop are indistinguishable from each "
3285 "other by the tracer. The tracer needs to keep track of the sequence of "
3286 "ptrace-stops in order to not misinterpret syscall-enter-stop as "
3287 "syscall-exit-stop or vice versa. The rule is that syscall-enter-stop is "
3288 "always followed by syscall-exit-stop, B<PTRACE_EVENT> stop or the tracee's "
3289 "death; no other kinds of ptrace-stop can occur in between."
3293 #: build/C/man2/ptrace.2:1191
3295 "If after syscall-enter-stop, the tracer uses a restarting command other than "
3296 "B<PTRACE_SYSCALL>, syscall-exit-stop is not generated."
3300 #: build/C/man2/ptrace.2:1203
3302 "B<PTRACE_GETSIGINFO> on syscall-stops returns B<SIGTRAP> in I<si_signo>, "
3303 "with I<si_code> set to B<SIGTRAP> or I<(SIGTRAP|0x80)>."
3307 #: build/C/man2/ptrace.2:1203
3309 msgid "PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops"
3314 #. document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
3315 #. PTRACE_SYSEMU_SINGLESTEP
3317 #: build/C/man2/ptrace.2:1209
3318 msgid "[Details of these kinds of stops are yet to be documented.]"
3322 #: build/C/man2/ptrace.2:1209
3324 msgid "Informational and restarting ptrace commands"
3328 #: build/C/man2/ptrace.2:1217
3330 "Most ptrace commands (all except B<PTRACE_ATTACH>, B<PTRACE_TRACEME>, and "
3331 "B<PTRACE_KILL>) require the tracee to be in a ptrace-stop, otherwise they "
3332 "fail with B<ESRCH>."
3336 #: build/C/man2/ptrace.2:1222
3338 "When the tracee is in ptrace-stop, the tracer can read and write data to the "
3339 "tracee using informational commands. These commands leave the tracee in "
3340 "ptrace-stopped state:"
3344 #: build/C/man2/ptrace.2:1232
3347 " ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);\n"
3348 " ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);\n"
3349 " ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);\n"
3350 " ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);\n"
3351 " ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);\n"
3352 " ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);\n"
3353 " ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);\n"
3354 " ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
3358 #: build/C/man2/ptrace.2:1244
3360 "Note that some errors are not reported. For example, setting signal "
3361 "information (I<siginfo>) may have no effect in some ptrace-stops, yet the "
3362 "call may succeed (return 0 and not set I<errno>); querying "
3363 "B<PTRACE_GETEVENTMSG> may succeed and return some random value if current "
3364 "ptrace-stop is not documented as returning a meaningful event message."
3368 #: build/C/man2/ptrace.2:1246
3373 #: build/C/man2/ptrace.2:1248
3375 msgid " ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
3379 #: build/C/man2/ptrace.2:1257
3381 "affects one tracee. The tracee's current flags are replaced. Flags are "
3382 "inherited by new tracees created and \"auto-attached\" via active "
3383 "B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or B<PTRACE_O_TRACECLONE> "
3388 #: build/C/man2/ptrace.2:1260
3390 "Another group of commands makes the ptrace-stopped tracee run. They have "
3395 #: build/C/man2/ptrace.2:1262
3397 msgid " ptrace(cmd, pid, 0, sig);\n"
3401 #: build/C/man2/ptrace.2:1282
3403 "where I<cmd> is B<PTRACE_CONT>, B<PTRACE_DETACH>, B<PTRACE_SYSCALL>, "
3404 "B<PTRACE_SINGLESTEP>, B<PTRACE_SYSEMU>, or B<PTRACE_SYSEMU_SINGLESTEP>. If "
3405 "the tracee is in signal-delivery-stop, I<sig> is the signal to be injected "
3406 "(if it is nonzero). Otherwise, I<sig> may be ignored. (When restarting a "
3407 "tracee from a ptrace-stop other than signal-delivery-stop, recommended "
3408 "practice is to always pass 0 in I<sig>.)"
3412 #: build/C/man2/ptrace.2:1282
3414 msgid "Attaching and detaching"
3418 #: build/C/man2/ptrace.2:1284
3419 msgid "A thread can be attached to the tracer using the call"
3423 #: build/C/man2/ptrace.2:1286
3425 msgid " ptrace(PTRACE_ATTACH, pid, 0, 0);\n"
3429 #. FIXME: Describe how to attach to a thread which is already
3432 #: build/C/man2/ptrace.2:1310
3434 "This also sends B<SIGSTOP> to this thread. If the tracer wants this "
3435 "B<SIGSTOP> to have no effect, it needs to suppress it. Note that if other "
3436 "signals are concurrently sent to this thread during attach, the tracer may "
3437 "see the tracee enter signal-delivery-stop with other signal(s) first! The "
3438 "usual practice is to reinject these signals until B<SIGSTOP> is seen, then "
3439 "suppress B<SIGSTOP> injection. The design bug here is that a ptrace attach "
3440 "and a concurrently delivered B<SIGSTOP> may race and the concurrent "
3441 "B<SIGSTOP> may be lost."
3445 #: build/C/man2/ptrace.2:1317
3447 "Since attaching sends B<SIGSTOP> and the tracer usually suppresses it, this "
3448 "may cause a stray B<EINTR> return from the currently executing system call "
3449 "in the tracee, as described in the \"Signal injection and suppression\" "
3454 #: build/C/man2/ptrace.2:1319
3459 #: build/C/man2/ptrace.2:1321
3461 msgid " ptrace(PTRACE_TRACEME, 0, 0, 0);\n"
3465 #: build/C/man2/ptrace.2:1327
3467 "turns the calling thread into a tracee. The thread continues to run "
3468 "(doesn't enter ptrace-stop). A common practice is to follow the "
3469 "B<PTRACE_TRACEME> with"
3473 #: build/C/man2/ptrace.2:1329
3475 msgid " raise(SIGSTOP);\n"
3479 #: build/C/man2/ptrace.2:1332
3481 "and allow the parent (which is our tracer now) to observe our "
3482 "signal-delivery-stop."
3486 #: build/C/man2/ptrace.2:1356
3488 "If the B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or "
3489 "B<PTRACE_O_TRACECLONE> options are in effect, then children created by, "
3490 "respectively, B<vfork>(2) or B<clone>(2) with the B<CLONE_VFORK> flag, "
3491 "B<fork>(2) or B<clone>(2) with the exit signal set to B<SIGCHLD>, and "
3492 "other kinds of B<clone>(2), are automatically attached to the same tracer "
3493 "which traced their parent. B<SIGSTOP> is delivered to the children, causing "
3494 "them to enter signal-delivery-stop after they exit the system call which "
3499 #: build/C/man2/ptrace.2:1358
3500 msgid "Detaching of the tracee is performed by:"
3504 #: build/C/man2/ptrace.2:1360
3506 msgid " ptrace(PTRACE_DETACH, pid, 0, sig);\n"
3510 #: build/C/man2/ptrace.2:1368
3512 "B<PTRACE_DETACH> is a restarting operation; therefore it requires the tracee "
3513 "to be in ptrace-stop. If the tracee is in signal-delivery-stop, a signal "
3514 "can be injected. Otherwise, the I<sig> parameter may be silently ignored."
3517 #. FIXME: Describe how to detach from a group-stopped tracee so that it
3518 #. doesn't run, but continues to wait for SIGCONT.
3520 #: build/C/man2/ptrace.2:1392
3522 "If the tracee is running when the tracer wants to detach it, the usual "
3523 "solution is to send B<SIGSTOP> (using B<tgkill>(2), to make sure it goes to "
3524 "the correct thread), wait for the tracee to stop in signal-delivery-stop for "
3525 "B<SIGSTOP> and then detach it (suppressing B<SIGSTOP> injection). A design "
3526 "bug is that this can race with concurrent B<SIGSTOP>s. Another complication "
3527 "is that the tracee may enter other ptrace-stops and needs to be restarted "
3528 "and waited for again, until B<SIGSTOP> is seen. Yet another complication is "
3529 "to be sure that the tracee is not already ptrace-stopped, because no signal "
3530 "delivery happens while it is\\(emnot even B<SIGSTOP>."
3534 #: build/C/man2/ptrace.2:1400
3536 "If the tracer dies, all tracees are automatically detached and restarted, "
3537 "unless they were in group-stop. Handling of restart from group-stop is "
3538 "currently buggy, but the \"as planned\" behavior is to leave tracee stopped "
3539 "and waiting for B<SIGCONT>. If the tracee is restarted from "
3540 "signal-delivery-stop, the pending signal is injected."
3544 #: build/C/man2/ptrace.2:1400
3546 msgid "execve(2) under ptrace"
3549 #. clone(2) THREAD_CLONE says:
3550 #. If any of the threads in a thread group performs an execve(2),
3551 #. then all threads other than the thread group leader are terminated,
3552 #. and the new program is executed in the thread group leader.
3554 #. In kernel 3.1 sources, see fs/exec.c::de_thread()
3556 #: build/C/man2/ptrace.2:1419
3558 "When one thread in a multithreaded process calls B<execve>(2), the kernel "
3559 "destroys all other threads in the process, and resets the thread ID of the "
3560 "execing thread to the thread group ID (process ID). (Or, to put things "
3561 "another way, when a multithreaded process does an B<execve>(2), at "
3562 "completion of the call, it appears as though the B<execve>(2) occurred in "
3563 "the thread group leader, regardless of which thread did the B<execve>(2).) "
3564 "This resetting of the thread ID looks very confusing to tracers:"
3568 #: build/C/man2/ptrace.2:1419 build/C/man2/ptrace.2:1429 build/C/man2/ptrace.2:1437 build/C/man2/ptrace.2:1443 build/C/man2/ptrace.2:1572
3574 #: build/C/man2/ptrace.2:1429
3576 "All other threads stop in B<PTRACE_EVENT_EXIT> stop, if the "
3577 "B<PTRACE_O_TRACEEXIT> option was turned on. Then all other threads except "
3578 "the thread group leader report death as if they exited via B<_exit>(2) with "
3583 #: build/C/man2/ptrace.2:1437
3585 "The execing tracee changes its thread ID while it is in the B<execve>(2). "
3586 "(Remember, under ptrace, the \"pid\" returned from B<waitpid>(2), or fed "
3587 "into ptrace calls, is the tracee's thread ID.) That is, the tracee's thread "
3588 "ID is reset to be the same as its process ID, which is the same as the "
3589 "thread group leader's thread ID."
3593 #: build/C/man2/ptrace.2:1443
3595 "Then a B<PTRACE_EVENT_EXEC> stop happens, if the B<PTRACE_O_TRACEEXEC> "
3596 "option was turned on."
3600 #: build/C/man2/ptrace.2:1464
3602 "If the thread group leader has reported its B<PTRACE_EVENT_EXIT> stop by "
3603 "this time, it appears to the tracer that the dead thread leader \"reappears "
3604 "from nowhere\". (Note: the thread group leader does not report death via "
3605 "I<WIFEXITED(status)> until there is at least one other live thread. This "
3606 "eliminates the possibility that the tracer will see it dying and then "
3607 "reappearing.) If the thread group leader was still alive, for the tracer "
3608 "this may look as if thread group leader returns from a different system call "
3609 "than it entered, or even \"returned from a system call even though it was "
3610 "not in any system call\". If the thread group leader was not traced (or was "
3611 "traced by a different tracer), then during B<execve>(2) it will appear as "
3612 "if it has become a tracee of the tracer of the execing tracee."
3616 #: build/C/man2/ptrace.2:1467
3618 "All of the above effects are the artifacts of the thread ID change in the "
3623 #: build/C/man2/ptrace.2:1487
3625 "The B<PTRACE_O_TRACEEXEC> option is the recommended tool for dealing with "
3626 "this situation. First, it enables B<PTRACE_EVENT_EXEC> stop, which occurs "
3627 "before B<execve>(2) returns. In this stop, the tracer can use "
3628 "B<PTRACE_GETEVENTMSG> to retrieve the tracee's former thread ID. (This "
3629 "feature was introduced in Linux 3.0). Second, the B<PTRACE_O_TRACEEXEC> "
3630 "option disables legacy B<SIGTRAP> generation on B<execve>(2)."
3634 #: build/C/man2/ptrace.2:1493
3636 "When the tracer receives B<PTRACE_EVENT_EXEC> stop notification, it is "
3637 "guaranteed that except this tracee and the thread group leader, no other "
3638 "threads from the process are alive."
3642 #: build/C/man2/ptrace.2:1501
3644 "On receiving the B<PTRACE_EVENT_EXEC> stop notification, the tracer should "
3645 "clean up all its internal data structures describing the threads of this "
3646 "process, and retain only one data structure\\(emone which describes the "
3647 "single still running tracee, with"
3651 #: build/C/man2/ptrace.2:1503
3653 msgid " thread ID == thread group ID == process ID.\n"
3657 #: build/C/man2/ptrace.2:1507
3658 msgid "Example: two threads call B<execve>(2) at the same time:"
3662 #: build/C/man2/ptrace.2:1518
3665 "*** we get syscall-enter-stop in thread 1: **\n"
3666 "PID1 execve(\"/bin/foo\", \"foo\" E<lt>unfinished ...E<gt>\n"
3667 "*** we issue PTRACE_SYSCALL for thread 1 **\n"
3668 "*** we get syscall-enter-stop in thread 2: **\n"
3669 "PID2 execve(\"/bin/bar\", \"bar\" E<lt>unfinished ...E<gt>\n"
3670 "*** we issue PTRACE_SYSCALL for thread 2 **\n"
3671 "*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **\n"
3672 "*** we get syscall-exit-stop for PID0: **\n"
3673 "PID0 E<lt>... execve resumedE<gt> ) = 0\n"
3677 #: build/C/man2/ptrace.2:1541
3679 "If the B<PTRACE_O_TRACEEXEC> option is I<not> in effect for the execing "
3680 "tracee, the kernel delivers an extra B<SIGTRAP> to the tracee after "
3681 "B<execve>(2) returns. This is an ordinary signal (similar to one which can "
3682 "be generated by I<kill -TRAP>), not a special kind of ptrace-stop. "
3683 "Employing B<PTRACE_GETSIGINFO> for this signal returns I<si_code> set to 0 "
3684 "(I<SI_USER>). This signal may be blocked by signal mask, and thus may be "
3685 "delivered (much) later."
3689 #: build/C/man2/ptrace.2:1560
3691 "Usually, the tracer (for example, B<strace>(1)) would not want to show this "
3692 "extra post-execve B<SIGTRAP> signal to the user, and would suppress its "
3693 "delivery to the tracee (if B<SIGTRAP> is set to B<SIG_DFL>, it is a killing "
3694 "signal). However, determining I<which> B<SIGTRAP> to suppress is not easy. "
3695 "Setting the B<PTRACE_O_TRACEEXEC> option and thus suppressing this extra "
3696 "B<SIGTRAP> is the recommended approach."
3700 #: build/C/man2/ptrace.2:1560
3706 #: build/C/man2/ptrace.2:1567
3708 "The ptrace API (ab)uses the standard UNIX parent/child signaling over "
3709 "B<waitpid>(2). This used to cause the real parent of the process to stop "
3710 "receiving several kinds of B<waitpid>(2) notifications when the child "
3711 "process is traced by some other process."
3715 #: build/C/man2/ptrace.2:1570
3717 "Many of these bugs have been fixed, but as of Linux 2.6.38 several still "
3718 "exist; see BUGS below."
3722 #: build/C/man2/ptrace.2:1572
3723 msgid "As of Linux 2.6.38, the following is believed to work correctly:"
3727 #: build/C/man2/ptrace.2:1580
3729 "exit/death by signal is reported first to the tracer, then, when the tracer "
3730 "consumes the B<waitpid>(2) result, to the real parent (to the real parent "
3731 "only when the whole multithreaded process exits). If the tracer and the "
3732 "real parent are the same process, the report is sent only once."
3736 #: build/C/man2/ptrace.2:1594
3738 "On success, B<PTRACE_PEEK*> requests return the requested data, while other "
3739 "requests return zero. On error, all requests return -1, and I<errno> is set "
3740 "appropriately. Since the value returned by a successful B<PTRACE_PEEK*> "
3741 "request may be -1, the caller must clear I<errno> before the call, and then "
3742 "check it afterward to determine whether or not an error occurred."
3746 #: build/C/man2/ptrace.2:1598
3747 msgid "(i386 only) There was an error with allocating or freeing a debug register."
3751 #: build/C/man2/ptrace.2:1609
3753 "There was an attempt to read from or write to an invalid area in the "
3754 "tracer's or the tracee's memory, probably because the area wasn't mapped or "
3755 "accessible. Unfortunately, under Linux, different variations of this fault "
3756 "will return B<EIO> or B<EFAULT> more or less arbitrarily."
3760 #: build/C/man2/ptrace.2:1612
3761 msgid "An attempt was made to set an invalid option."
3765 #: build/C/man2/ptrace.2:1619
3767 "I<request> is invalid, or an attempt was made to read from or write to an "
3768 "invalid area in the tracer's or the tracee's memory, or there was a "
3769 "word-alignment violation, or an invalid signal was specified during a "
3774 #: build/C/man2/ptrace.2:1632
3776 "The specified process cannot be traced. This could be because the tracer "
3777 "has insufficient privileges (the required capability is B<CAP_SYS_PTRACE>); "
3778 "unprivileged processes cannot trace processes that they cannot send signals "
3779 "to or those running set-user-ID/set-group-ID programs, for obvious reasons. "
3780 "Alternatively, the process may already be being traced, or (on kernels "
3781 "before 2.6.26) be B<init>(8) (PID 1)."
3785 #: build/C/man2/ptrace.2:1637
3787 "The specified process does not exist, or is not currently being traced by "
3788 "the caller, or is not stopped (for requests that require a stopped tracee)."
3792 #: build/C/man2/ptrace.2:1639
3793 msgid "SVr4, 4.3BSD."
3797 #: build/C/man2/ptrace.2:1652
3799 "Although arguments to B<ptrace>() are interpreted according to the "
3800 "prototype given, glibc currently declares B<ptrace>() as a variadic "
3801 "function with only the I<request> argument fixed. This means that unneeded "
3802 "trailing arguments may be omitted, though doing so makes use of undocumented "
3803 "B<gcc>(1) behavior."
3806 #. See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
3808 #: build/C/man2/ptrace.2:1657
3810 "In Linux kernels before 2.6.26, B<init>(8), the process with PID 1, may not "
3814 #. See http://lkml.org/lkml/2008/5/8/375
3816 #: build/C/man2/ptrace.2:1664
3818 "The layout of the contents of memory and the USER area are quite "
3819 "operating-system- and architecture-specific. The offset supplied, and the "
3820 "data returned, might not entirely match with the definition of I<struct "
3825 #: build/C/man2/ptrace.2:1667
3827 "The size of a \"word\" is determined by the operating-system variant (e.g., "
3828 "for 32-bit Linux it is 32 bits, etc.)."
3832 #: build/C/man2/ptrace.2:1675
3834 "This page documents the way the B<ptrace>() call works currently in Linux. "
3835 "Its behavior differs noticeably on other flavors of UNIX. In any case, use "
3836 "of B<ptrace>() is highly specific to the operating system and architecture."
3840 #: build/C/man2/ptrace.2:1686
3842 "On hosts with 2.6 kernel headers, B<PTRACE_SETOPTIONS> is declared with a "
3843 "different value than the one for 2.4. This leads to applications compiled "
3844 "with 2.6 kernel headers failing when run on 2.4 kernels. This can be worked "
3845 "around by redefining B<PTRACE_SETOPTIONS> to B<PTRACE_OLDSETOPTIONS>, if "
3850 #: build/C/man2/ptrace.2:1689
3852 "Group-stop notifications are sent to the tracer, but not to real parent. "
3853 "Last confirmed on 2.6.38.6."
3856 #. Note from Denys Vlasenko:
3857 #. Here "exits" means any kind of death - _exit, exit_group,
3858 #. signal death. Signal death and exit_group cases are trivial,
3859 #. though: since signal death and exit_group kill all other threads
3860 #. too, "until all other threads exit" thing happens rather soon
3861 #. in these cases. Therefore, only _exit presents observably
3862 #. puzzling behavior to ptrace users: thread leader _exit's,
3863 #. but WIFEXITED isn't reported! We are trying to explain here
3865 #. FIXME: ^^^ need to test/verify this scenario
3867 #: build/C/man2/ptrace.2:1720
3869 "If a thread group leader is traced and exits by calling B<_exit>(2), a "
3870 "B<PTRACE_EVENT_EXIT> stop will happen for it (if requested), but the "
3871 "subsequent B<WIFEXITED> notification will not be delivered until all other "
3872 "threads exit. As explained above, if one of other threads calls "
3873 "B<execve>(2), the death of the thread group leader will I<never> be "
3874 "reported. If the execed thread is not traced by this tracer, the tracer "
3875 "will never know that B<execve>(2) happened. One possible workaround is to "
3876 "B<PTRACE_DETACH> the thread group leader instead of restarting it in this "
3877 "case. Last confirmed on 2.6.38.6."
3881 #: build/C/man2/ptrace.2:1730
3883 "A B<SIGKILL> signal may still cause a B<PTRACE_EVENT_EXIT> stop before "
3884 "actual signal death. This may be changed in the future; B<SIGKILL> is meant "
3885 "to always immediately kill tasks even under ptrace. Last confirmed on "
3890 #: build/C/man2/ptrace.2:1746
3892 "Some system calls return with B<EINTR> if a signal was sent to a tracee, but "
3893 "delivery was suppressed by the tracer. (This is very typical operation: it "
3894 "is usually done by debuggers on every attach, in order to not introduce a "
3895 "bogus B<SIGSTOP>). As of Linux 3.2.9, the following system calls are "
3896 "affected (this list is likely incomplete): B<epoll_wait>(2), and B<read>(2) "
3897 "from an B<inotify>(7) file descriptor."
3901 #: build/C/man2/ptrace.2:1760
3903 "B<gdb>(1), B<strace>(1), B<clone>(2), B<execve>(2), B<fork>(2), "
3904 "B<gettid>(2), B<sigaction>(2), B<tgkill>(2), B<vfork>(2), B<waitpid>(2), "
3905 "B<exec>(3), B<capabilities>(7), B<signal>(7)"
3909 #: build/C/man2/quotactl.2:25
3915 #: build/C/man2/quotactl.2:25
3921 #: build/C/man2/quotactl.2:28
3922 msgid "quotactl - manipulate disk quotas"
3926 #: build/C/man2/quotactl.2:32
3929 "B<#include E<lt>sys/quota.hE<gt>>\n"
3930 "B<#include E<lt>xfs/xqm.hE<gt>>\n"
3934 #: build/C/man2/quotactl.2:35
3937 "B<int quotactl(int >I<cmd>B<, const char *>I<special>B<, int >I<id>B<, "
3938 "caddr_t >I<addr>B<);>\n"
3942 #: build/C/man2/quotactl.2:47
3944 "The quota system can be used to set per-user and per-group limits on the "
3945 "amount of disk space used on a file system. For each user and/or group, a "
3946 "soft limit and a hard limit can be set for each file system. The hard limit "
3947 "can't be exceeded. The soft limit can be exceeded, but warnings will "
3948 "ensue. Moreover, the user can't exceed the soft limit for more than one "
3949 "week (by default) at a time; after this time, the soft limit counts as a "
3954 #: build/C/man2/quotactl.2:72
3956 "The B<quotactl>() call manipulates disk quotas. The I<cmd> argument "
3957 "indicates a command to be applied to the user or group ID specified in "
3958 "I<id>. To initialize the I<cmd> argument, use the I<QCMD(subcmd, type)> "
3959 "macro. The I<type> value is either B<USRQUOTA>, for user quotas, or "
3960 "B<GRPQUOTA>, for group quotas. The I<subcmd> value is described below."
3964 #: build/C/man2/quotactl.2:77
3966 "The I<special> argument is a pointer to a null-terminated string containing "
3967 "the pathname of the (mounted) block special device for the file system being "
3972 #: build/C/man2/quotactl.2:85
3974 "The I<addr> argument is the address of an optional, command-specific, data "
3975 "structure that is copied in or out of the system. The interpretation of "
3976 "I<addr> is given with each command below."
3980 #: build/C/man2/quotactl.2:89
3981 msgid "The I<subcmd> value is one of the following:"
3985 #: build/C/man2/quotactl.2:89
3987 msgid "B<Q_QUOTAON>"
3991 #: build/C/man2/quotactl.2:96
3993 "Turn on quotas for a file system. The I<id> argument is the identification "
3994 "number of the quota format to be used. Currently, there are three supported "
3999 #: build/C/man2/quotactl.2:97
4001 msgid "B<QFMT_VFS_OLD>"
4005 #: build/C/man2/quotactl.2:100
4006 msgid "The original quota format."
4010 #: build/C/man2/quotactl.2:100
4012 msgid "B<QFMT_VFS_V0>"
4016 #: build/C/man2/quotactl.2:104
4018 "The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and "
4019 "quota limits up to 2^42 bytes and 2^32 inodes."
4023 #: build/C/man2/quotactl.2:104
4025 msgid "B<QFMT_VFS_V1>"
4029 #: build/C/man2/quotactl.2:108
4031 "A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^64 "
4032 "bytes and 2^64 inodes."
4036 #: build/C/man2/quotactl.2:119
4038 "The I<addr> argument points to the pathname of a file containing the quotas "
4039 "for the file system. The quota file must exist; it is normally created with "
4040 "the B<quotacheck>(8) program. This operation requires privilege "
4041 "(B<CAP_SYS_ADMIN>)."
4045 #: build/C/man2/quotactl.2:119
4047 msgid "B<Q_QUOTAOFF>"
4051 #: build/C/man2/quotactl.2:129
4053 "Turn off quotas for a file system. The I<addr> and I<id> arguments are "
4054 "ignored. This operation requires privilege (B<CAP_SYS_ADMIN>)."
4058 #: build/C/man2/quotactl.2:129
4060 msgid "B<Q_GETQUOTA>"
4064 #: build/C/man2/quotactl.2:140
4066 "Get disk quota limits and current usage for user or group I<id>. The "
4067 "I<addr> argument is a pointer to a I<dqblk> structure defined in "
4068 "I<E<lt>sys/quota.hE<gt>> as follows:"
4072 #: build/C/man2/quotactl.2:145 build/C/man2/quotactl.2:232
4075 "/* uint64_t is an unsigned 64-bit integer;\n"
4076 " uint32_t is an unsigned 32-bit integer */\n"
4080 #: build/C/man2/quotactl.2:165
4083 "struct dqblk { /* Definition since Linux 2.4.22 */\n"
4084 " uint64_t dqb_bhardlimit; /* absolute limit on disk\n"
4085 " quota blocks alloc */\n"
4086 " uint64_t dqb_bsoftlimit; /* preferred limit on\n"
4087 " disk quota blocks */\n"
4088 " uint64_t dqb_curspace; /* current quota block\n"
4090 " uint64_t dqb_ihardlimit; /* maximum number of\n"
4091 " allocated inodes */\n"
4092 " uint64_t dqb_isoftlimit; /* preferred inode limit */\n"
4093 " uint64_t dqb_curinodes; /* current number of\n"
4094 " allocated inodes */\n"
4095 " uint64_t dqb_btime; /* time limit for excessive\n"
4097 " uint64_t dqb_itime; /* time limit for excessive\n"
4099 " uint32_t dqb_valid; /* bit mask of QIF_*\n"
4105 #: build/C/man2/quotactl.2:168
4108 "/* Flags in dqb_valid that indicate which fields in\n"
4109 " dqblk structure are valid. */\n"
4113 #: build/C/man2/quotactl.2:179
4116 "#define QIF_BLIMITS 1\n"
4117 "#define QIF_SPACE 2\n"
4118 "#define QIF_ILIMITS 4\n"
4119 "#define QIF_INODES 8\n"
4120 "#define QIF_BTIME 16\n"
4121 "#define QIF_ITIME 32\n"
4122 "#define QIF_LIMITS (QIF_BLIMITS | QIF_ILIMITS)\n"
4123 "#define QIF_USAGE (QIF_SPACE | QIF_INODES)\n"
4124 "#define QIF_TIMES (QIF_BTIME | QIF_ITIME)\n"
4125 "#define QIF_ALL (QIF_LIMITS | QIF_USAGE | QIF_TIMES)\n"
4129 #: build/C/man2/quotactl.2:196
4131 "The I<dqb_valid> field is a bit mask that is set to indicate the entries in "
4132 "the I<dqblk> structure that are valid. Currently, the kernel fills in all "
4133 "entries of the I<dqblk> structure and marks them as valid in the "
4134 "I<dqb_valid> field. Unprivileged users may retrieve only their own quotas; "
4135 "a privileged user (B<CAP_SYS_ADMIN>) can retrieve the quotas of any user."
4139 #: build/C/man2/quotactl.2:196
4141 msgid "B<Q_SETQUOTA>"
4145 #: build/C/man2/quotactl.2:216
4147 "Set quota information for user or group I<id>, using the information "
4148 "supplied in the I<dqblk> structure pointed to by I<addr>. The I<dqb_valid> "
4149 "field of the I<dqblk> structure indicates which entries in the structure "
4150 "have been set by the caller. This operation supersedes the B<Q_SETQLIM> and "
4151 "B<Q_SETUSE> operations in the previous quota interfaces. This operation "
4152 "requires privilege (B<CAP_SYS_ADMIN>)."
4156 #: build/C/man2/quotactl.2:216
4158 msgid "B<Q_GETINFO>"
4162 #: build/C/man2/quotactl.2:227
4164 "Get information (like grace times) about quotafile. The I<addr> argument "
4165 "should be a pointer to a I<dqinfo> structure. This structure is defined in "
4166 "I<E<lt>sys/quota.hE<gt>> as follows:"
4170 #: build/C/man2/quotactl.2:236
4173 "struct dqinfo { /* Defined since kernel 2.4.22 */\n"
4174 " uint64_t dqi_bgrace; /* Time before block soft limit\n"
4175 " becomes hard limit */\n"
4179 #: build/C/man2/quotactl.2:243
4182 " uint64_t dqi_igrace; /* Time before inode soft limit\n"
4183 " becomes hard limit */\n"
4184 " uint32_t dqi_flags; /* Flags for quotafile\n"
4186 " uint32_t dqi_valid;\n"
4191 #: build/C/man2/quotactl.2:245
4193 msgid "/* Bits for dqi_flags */\n"
4197 #: build/C/man2/quotactl.2:247
4199 msgid "/* Quota format QFMT_VFS_OLD */\n"
4203 #: build/C/man2/quotactl.2:249
4205 msgid "#define V1_DQF_RSQUASH\t1 /* Root squash enabled */\n"
4209 #: build/C/man2/quotactl.2:251
4211 msgid "/* Other quota formats have no dqi_flags bits defined */\n"
4215 #: build/C/man2/quotactl.2:254
4218 "/* Flags in dqi_valid that indicate which fields in\n"
4219 " dqinfo structure are valid. */\n"
4223 #: build/C/man2/quotactl.2:259
4226 "# define IIF_BGRACE\t1\n"
4227 "# define IIF_IGRACE\t2\n"
4228 "# define IIF_FLAGS\t4\n"
4229 "# define IIF_ALL\t(IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)\n"
4233 #: build/C/man2/quotactl.2:275
4235 "The I<dqi_valid> field in the I<dqinfo> structure indicates the entries in "
4236 "the structure that are valid. Currently, the kernel fills in all entries of "
4237 "the I<dqinfo> structure and marks them all as valid in the I<dqi_valid> "
4238 "field. The I<id> argument is ignored."
4242 #: build/C/man2/quotactl.2:275
4244 msgid "B<Q_SETINFO>"
4248 #: build/C/man2/quotactl.2:299
4250 "Set information about quotafile. The I<addr> argument should be a pointer "
4251 "to a I<dqinfo> structure. The I<dqi_valid> field of the I<dqinfo> structure "
4252 "indicates the entries in the structure that have been set by the caller. "
4253 "This operation supersedes the B<Q_SETGRACE> and B<Q_SETFLAGS> operations in "
4254 "the previous quota interfaces. The I<id> argument is ignored. This "
4255 "operation requires privilege (B<CAP_SYS_ADMIN>)."
4259 #: build/C/man2/quotactl.2:299
4265 #: build/C/man2/quotactl.2:306
4267 "Get quota format used on the specified file system. The I<addr> argument "
4268 "should be a pointer to a 4-byte buffer where the format number will be "
4273 #: build/C/man2/quotactl.2:306
4279 #: build/C/man2/quotactl.2:317
4281 "Update the on-disk copy of quota usages for a file system. If I<special> is "
4282 "NULL, then all file systems with active quotas are sync'ed. The I<addr> and "
4283 "I<id> arguments are ignored."
4287 #: build/C/man2/quotactl.2:317
4289 msgid "B<Q_GETSTATS>"
4292 #. Q_GETSTATS was removed in kernel 2.4.22.
4294 #: build/C/man2/quotactl.2:337
4296 "Get statistics and other generic information about the quota subsystem. The "
4297 "I<addr> argument should be a pointer to a I<dqstats> structure in which data "
4298 "should be stored. This structure is defined in I<E<lt>sys/quota.hE<gt>.> "
4299 "The I<special> and I<id> arguments are ignored. This operation is obsolete "
4300 "and not supported by recent kernels. Files in I</proc/sys/fs/quota/> carry "
4301 "the information instead."
4305 #: build/C/man2/quotactl.2:340
4307 "For XFS file systems making use of the XFS Quota Manager (XQM), the above "
4308 "commands are bypassed and the following commands are used:"
4312 #: build/C/man2/quotactl.2:340
4314 msgid "B<Q_XQUOTAON>"
4318 #: build/C/man2/quotactl.2:361
4320 "Turn on quotas for an XFS file system. XFS provides the ability to turn "
4321 "on/off quota limit enforcement with quota accounting. Therefore, XFS "
4322 "expects I<addr> to be a pointer to an I<unsigned int> that contains either "
4323 "the flags B<XFS_QUOTA_UDQ_ACCT> and/or B<XFS_QUOTA_UDQ_ENFD> (for user "
4324 "quota), or B<XFS_QUOTA_GDQ_ACCT> and/or B<XFS_QUOTA_GDQ_ENFD> (for group "
4325 "quota), as defined in I<E<lt>xfs/xqm.hE<gt>>. This operation requires "
4326 "privilege (B<CAP_SYS_ADMIN>)."
4330 #: build/C/man2/quotactl.2:361
4332 msgid "B<Q_XQUOTAOFF>"
4336 #: build/C/man2/quotactl.2:372
4338 "Turn off quotas for an XFS file system. As with B<Q_QUOTAON>, XFS file "
4339 "systems expect a pointer to an I<unsigned int> that specifies whether quota "
4340 "accounting and/or limit enforcement need to be turned off. This operation "
4341 "requires privilege (B<CAP_SYS_ADMIN>)."
4345 #: build/C/man2/quotactl.2:372
4347 msgid "B<Q_XGETQUOTA>"
4351 #: build/C/man2/quotactl.2:386
4353 "Get disk quota limits and current usage for user I<id>. The I<addr> "
4354 "argument is a pointer to an I<fs_disk_quota> structure (defined in "
4355 "I<E<lt>xfs/xqm.hE<gt>>). Unprivileged users may retrieve only their own "
4356 "quotas; a privileged user (B<CAP_SYS_ADMIN>) may retrieve the quotas of any "
4361 #: build/C/man2/quotactl.2:386
4363 msgid "B<Q_XSETQLIM>"
4367 #: build/C/man2/quotactl.2:398
4369 "Set disk quota limits for user I<id>. The I<addr> argument is a pointer to "
4370 "an I<fs_disk_quota> structure (defined in I<E<lt>xfs/xqm.hE<gt>>). This "
4371 "operation requires privilege (B<CAP_SYS_ADMIN>)."
4375 #: build/C/man2/quotactl.2:398
4377 msgid "B<Q_XGETQSTAT>"
4381 #: build/C/man2/quotactl.2:406
4383 "Returns an I<fs_quota_stat> structure containing XFS file system specific "
4384 "quota information. This is useful for finding out how much space is used to "
4385 "store quota information, and also to get quotaon/off status of a given local "
4390 #: build/C/man2/quotactl.2:406
4392 msgid "B<Q_XQUOTARM>"
4396 #: build/C/man2/quotactl.2:410
4398 "Free the disk space taken by disk quotas. Quotas must have already been "
4403 #: build/C/man2/quotactl.2:417
4405 "There is no command equivalent to B<Q_SYNC> for XFS since B<sync>(1) writes "
4406 "quota information to disk (in addition to the other file system metadata "
4407 "that it writes out)."
4411 #: build/C/man2/quotactl.2:417
4413 msgid "RETURN VALUES"
4417 #: build/C/man2/quotactl.2:425
4419 "On success, B<quotactl>() returns 0; on error -1 is returned, and I<errno> "
4420 "is set to indicate the error."
4424 #: build/C/man2/quotactl.2:432
4425 msgid "I<addr> or I<special> is invalid."
4429 #: build/C/man2/quotactl.2:438
4430 msgid "I<cmd> or I<type> is invalid."
4434 #: build/C/man2/quotactl.2:438
4440 #: build/C/man2/quotactl.2:445
4441 msgid "The file specified by I<special> or I<addr> does not exist."
4445 #: build/C/man2/quotactl.2:450
4446 msgid "The kernel has not been compiled with the B<CONFIG_QUOTA> option."
4450 #: build/C/man2/quotactl.2:450
4456 #: build/C/man2/quotactl.2:454
4457 msgid "I<special> is not a block device."
4461 #: build/C/man2/quotactl.2:459
4463 "The caller lacked the required privilege (B<CAP_SYS_ADMIN>) for the "
4464 "specified operation."
4468 #: build/C/man2/quotactl.2:463
4470 "No disk quota is found for the indicated user. Quotas have not been turned "
4471 "on for this file system."
4475 #: build/C/man2/quotactl.2:472
4476 msgid "If I<cmd> is B<Q_SETQUOTA>, B<quotactl>() may also set I<errno> to:"
4480 #: build/C/man2/quotactl.2:475
4481 msgid "Specified limits are out of range allowed by quota format."
4485 #: build/C/man2/quotactl.2:484
4486 msgid "If I<cmd> is B<Q_QUOTAON>, B<quotactl>() may also set I<errno> to:"
4490 #: build/C/man2/quotactl.2:493
4492 "The quota file pointed to by I<addr> exists, but is not a regular file; or, "
4493 "the quota file pointed to by I<addr> exists, but is not on the file system "
4494 "pointed to by I<special>."
4498 #: build/C/man2/quotactl.2:499
4499 msgid "B<Q_QUOTAON> attempted, but another B<Q_QUOTAON> had already been performed."
4503 #: build/C/man2/quotactl.2:502
4504 msgid "The quota file is corrupted."
4508 #: build/C/man2/quotactl.2:505
4509 msgid "Specified quota format was not found."
4513 #: build/C/man2/quotactl.2:510
4514 msgid "B<quota>(1), B<getrlimit>(2), B<quotacheck>(8), B<quotaon>(8)"
4518 #: build/C/man2/sendfile.2:15
4524 #: build/C/man2/sendfile.2:15
4530 #: build/C/man2/sendfile.2:18
4531 msgid "sendfile - transfer data between file descriptors"
4535 #: build/C/man2/sendfile.2:20
4536 msgid "B<#include E<lt>sys/sendfile.hE<gt>>"
4539 #. The below is too ugly. Comments about glibc versions belong
4540 #. in the notes, not in the header.
4542 #. .B #include <features.h>
4544 #. .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
4546 #. .B #include <sys/sendfile.h>
4550 #. .B #include <sys/types.h>
4552 #. .B /* No system prototype before glibc 2.1. */
4554 #. .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
4555 #. offset ", size_t" " count" )
4559 #: build/C/man2/sendfile.2:43
4561 "B<ssize_t sendfile(int>I< out_fd>B<, int>I< in_fd>B<, off_t *>I<offset>B<, "
4562 "size_t>I< count>B<);>"
4566 #: build/C/man2/sendfile.2:53
4568 "B<sendfile>() copies data between one file descriptor and another. Because "
4569 "this copying is done within the kernel, B<sendfile>() is more efficient "
4570 "than the combination of B<read>(2) and B<write>(2), which would require "
4571 "transferring data to and from user space."
4575 #: build/C/man2/sendfile.2:58
4577 "I<in_fd> should be a file descriptor opened for reading and I<out_fd> should "
4578 "be a descriptor opened for writing."
4582 #: build/C/man2/sendfile.2:79
4584 "If I<offset> is not NULL, then it points to a variable holding the file "
4585 "offset from which B<sendfile>() will start reading data from I<in_fd>. "
4586 "When B<sendfile>() returns, this variable will be set to the offset of the "
4587 "byte following the last byte that was read. If I<offset> is not NULL, then "
4588 "B<sendfile>() does not modify the current file offset of I<in_fd>; "
4589 "otherwise the current file offset is adjusted to reflect the number of bytes "
4590 "read from I<in_fd>."
4594 #: build/C/man2/sendfile.2:86
4596 "If I<offset> is NULL, then data will be read from I<in_fd> starting at the "
4597 "current file offset, and the file offset will be updated by the call."
4601 #: build/C/man2/sendfile.2:89
4602 msgid "I<count> is the number of bytes to copy between the file descriptors."
4606 #: build/C/man2/sendfile.2:96
4608 "The I<in_fd> argument must correspond to a file which supports "
4609 "B<mmap>(2)-like operations (i.e., it cannot be a socket)."
4613 #: build/C/man2/sendfile.2:104
4615 "In Linux kernels before 2.6.33, I<out_fd> must refer to a socket. Since "
4616 "Linux 2.6.33 it can be any file. If it is a regular file, then "
4617 "B<sendfile>() changes the file offset appropriately."
4621 #: build/C/man2/sendfile.2:111
4623 "If the transfer was successful, the number of bytes written to I<out_fd> is "
4624 "returned. On error, -1 is returned, and I<errno> is set appropriately."
4628 #: build/C/man2/sendfile.2:117
4630 "Nonblocking I/O has been selected using B<O_NONBLOCK> and the write would "
4635 #: build/C/man2/sendfile.2:117 build/C/man2/splice.2:143 build/C/man2/vmsplice.2:123
4641 #: build/C/man2/sendfile.2:121
4643 "The input file was not opened for reading or the output file was not opened "
4648 #: build/C/man2/sendfile.2:124
4649 msgid "Bad address."
4653 #: build/C/man2/sendfile.2:130
4655 "Descriptor is not valid or locked, or an B<mmap>(2)-like operation is not "
4656 "available for I<in_fd>."
4660 #: build/C/man2/sendfile.2:134
4661 msgid "Unspecified error while reading from I<in_fd>."
4665 #: build/C/man2/sendfile.2:138
4666 msgid "Insufficient memory to read from I<in_fd>."
4670 #: build/C/man2/sendfile.2:144
4672 "B<sendfile>() is a new feature in Linux 2.2. The include file "
4673 "I<E<lt>sys/sendfile.hE<gt>> is present since glibc 2.1."
4677 #: build/C/man2/sendfile.2:146
4678 msgid "Not specified in POSIX.1-2001, or other standards."
4682 #: build/C/man2/sendfile.2:151
4684 "Other UNIX systems implement B<sendfile>() with different semantics and "
4685 "prototypes. It should not be used in portable programs."
4689 #: build/C/man2/sendfile.2:161
4691 "If you plan to use B<sendfile>() for sending files to a TCP socket, but "
4692 "need to send some header data in front of the file contents, you will find "
4693 "it useful to employ the B<TCP_CORK> option, described in B<tcp>(7), to "
4694 "minimize the number of packets and to tune performance."
4698 #: build/C/man2/sendfile.2:167
4700 "In Linux 2.4 and earlier, I<out_fd> could also refer to a regular file, and "
4701 "B<sendfile>() changed the current offset of that file."
4705 #: build/C/man2/sendfile.2:179
4707 "The original Linux B<sendfile>() system call was not designed to handle "
4708 "large file offsets. Consequently, Linux 2.4 added B<sendfile64>(), with a "
4709 "wider type for the I<offset> argument. The glibc B<sendfile>() wrapper "
4710 "function transparently deals with the kernel differences."
4714 #: build/C/man2/sendfile.2:188
4716 "Applications may wish to fall back to B<read>(2)/B<write>(2) in the case "
4717 "where B<sendfile>() fails with B<EINVAL> or B<ENOSYS>."
4721 #: build/C/man2/sendfile.2:193
4723 "The Linux-specific B<splice>(2) call supports transferring data between "
4724 "arbitrary files (e.g., a pair of sockets)."
4728 #: build/C/man2/sendfile.2:198
4729 msgid "B<mmap>(2), B<open>(2), B<socket>(2), B<splice>(2)"
4733 #: build/C/man2/set_tid_address.2:23
4735 msgid "SET_TID_ADDRESS"
4739 #: build/C/man2/set_tid_address.2:23
4745 #: build/C/man2/set_tid_address.2:26
4746 msgid "set_tid_address - set pointer to thread ID"
4750 #: build/C/man2/set_tid_address.2:29
4752 msgid "B<#include E<lt>linux/unistd.hE<gt>>\n"
4756 #: build/C/man2/set_tid_address.2:31
4758 msgid "B<long set_tid_address(int *>I<tidptr>B<);>\n"
4762 #: build/C/man2/set_tid_address.2:38
4764 "The kernel keeps for each process two values called I<set_child_tid> and "
4765 "I<clear_child_tid> that are NULL by default."
4769 #: build/C/man2/set_tid_address.2:38
4771 msgid "set_child_tid"
4775 #: build/C/man2/set_tid_address.2:48
4777 "If a process is started using B<clone>(2) with the B<CLONE_CHILD_SETTID> "
4778 "flag, I<set_child_tid> is set to I<child_tidptr>, the fifth argument of that "
4783 #: build/C/man2/set_tid_address.2:53
4785 "When I<set_child_tid> is set, the very first thing the new process does is "
4786 "writing its PID at this address."
4790 #: build/C/man2/set_tid_address.2:53
4792 msgid "clear_child_tid"
4796 #: build/C/man2/set_tid_address.2:63
4798 "If a process is started using B<clone>(2) with the B<CLONE_CHILD_CLEARTID> "
4799 "flag, I<clear_child_tid> is set to I<child_tidptr>, the fifth argument of "
4804 #: build/C/man2/set_tid_address.2:70
4806 "The system call B<set_tid_address>() sets the I<clear_child_tid> value for "
4807 "the calling process to I<tidptr>."
4811 #: build/C/man2/set_tid_address.2:80
4813 "When I<clear_child_tid> is set, and the process exits, and the process was "
4814 "sharing memory with other processes or threads, then 0 is written at this "
4815 "address, and a I<futex(child_tidptr, FUTEX_WAKE, 1, NULL, NULL, 0);> call is "
4816 "done. (That is, wake a single process waiting on this futex.) Errors are "
4821 #: build/C/man2/set_tid_address.2:83
4822 msgid "B<set_tid_address>() always returns the PID of the calling process."
4826 #: build/C/man2/set_tid_address.2:86
4827 msgid "B<set_tid_address>() always succeeds."
4831 #: build/C/man2/set_tid_address.2:89
4833 "This call is present since Linux 2.5.48. Details as given here are valid "
4834 "since Linux 2.5.49."
4838 #: build/C/man2/set_tid_address.2:94
4839 msgid "B<clone>(2), B<futex>(2)"
4843 #: build/C/man2/splice.2:26
4849 #: build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vmsplice.2:26
4855 #: build/C/man2/splice.2:29
4856 msgid "splice - splice data to/from a pipe"
4860 #: build/C/man2/splice.2:33 build/C/man2/tee.2:33
4863 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
4864 "B<#include E<lt>fcntl.hE<gt>>\n"
4867 #. Return type was long before glibc 2.7
4869 #: build/C/man2/splice.2:38
4872 "B<ssize_t splice(int >I<fd_in>B<, loff_t *>I<off_in>B<, int >I<fd_out>B<,>\n"
4873 "B< loff_t *>I<off_out>B<, size_t >I<len>B<, unsigned int "
4878 #: build/C/man2/splice.2:50
4880 "B<splice>() moves data between two file descriptors without copying between "
4881 "kernel address space and user address space. It transfers up to I<len> "
4882 "bytes of data from the file descriptor I<fd_in> to the file descriptor "
4883 "I<fd_out>, where one of the descriptors must refer to a pipe."
4887 #: build/C/man2/splice.2:80
4889 "If I<fd_in> refers to a pipe, then I<off_in> must be NULL. If I<fd_in> does "
4890 "not refer to a pipe and I<off_in> is NULL, then bytes are read from I<fd_in> "
4891 "starting from the current file offset, and the current file offset is "
4892 "adjusted appropriately. If I<fd_in> does not refer to a pipe and I<off_in> "
4893 "is not NULL, then I<off_in> must point to a buffer which specifies the "
4894 "starting offset from which bytes will be read from I<fd_in>; in this case, "
4895 "the current file offset of I<fd_in> is not changed. Analogous statements "
4896 "apply for I<fd_out> and I<off_out>."
4900 #: build/C/man2/splice.2:85 build/C/man2/vmsplice.2:78
4902 "The I<flags> argument is a bit mask that is composed by ORing together zero "
4903 "or more of the following values:"
4907 #: build/C/man2/splice.2:85 build/C/man2/tee.2:62 build/C/man2/vmsplice.2:78
4909 msgid "B<SPLICE_F_MOVE>"
4913 #: build/C/man2/splice.2:98
4915 "Attempt to move pages instead of copying. This is only a hint to the "
4916 "kernel: pages may still be copied if the kernel cannot move the pages from "
4917 "the pipe, or if the pipe buffers don't refer to full pages. The initial "
4918 "implementation of this flag was buggy: therefore starting in Linux 2.6.21 it "
4919 "is a no-op (but is still permitted in a B<splice>() call); in the future, a "
4920 "correct implementation may be restored."
4924 #: build/C/man2/splice.2:98 build/C/man2/tee.2:68 build/C/man2/vmsplice.2:84
4926 msgid "B<SPLICE_F_NONBLOCK>"
4930 #: build/C/man2/splice.2:107
4932 "Do not block on I/O. This makes the splice pipe operations nonblocking, but "
4933 "B<splice>() may nevertheless block because the file descriptors that are "
4934 "spliced to/from may block (unless they have the B<O_NONBLOCK> flag set)."
4938 #: build/C/man2/splice.2:107 build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
4940 msgid "B<SPLICE_F_MORE>"
4944 #: build/C/man2/splice.2:121
4946 "More data will be coming in a subsequent splice. This is a helpful hint "
4947 "when the I<fd_out> refers to a socket (see also the description of "
4948 "B<MSG_MORE> in B<send>(2), and the description of B<TCP_CORK> in B<tcp>(7))"
4952 #: build/C/man2/splice.2:121 build/C/man2/tee.2:79 build/C/man2/vmsplice.2:97
4954 msgid "B<SPLICE_F_GIFT>"
4958 #: build/C/man2/splice.2:127
4959 msgid "Unused for B<splice>(); see B<vmsplice>(2)."
4963 #: build/C/man2/splice.2:136
4965 "Upon successful completion, B<splice>() returns the number of bytes spliced "
4966 "to or from the pipe. A return value of 0 means that there was no data to "
4967 "transfer, and it would not make sense to block, because there are no writers "
4968 "connected to the write end of the pipe referred to by I<fd_in>."
4972 #: build/C/man2/splice.2:142
4973 msgid "On error, B<splice>() returns -1 and I<errno> is set to indicate the error."
4977 #: build/C/man2/splice.2:147
4979 "One or both file descriptors are not valid, or do not have proper read-write "
4983 #. The append-mode error is given since 2.6.27; in earlier kernels,
4984 #. splice() in append mode was broken
4986 #: build/C/man2/splice.2:155
4988 "Target file system doesn't support splicing; target file is opened in append "
4989 "mode; neither of the descriptors refers to a pipe; or offset given for "
4990 "nonseekable device."
4994 #: build/C/man2/splice.2:158 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
4995 msgid "Out of memory."
4999 #: build/C/man2/splice.2:158
5005 #: build/C/man2/splice.2:165
5007 "Either I<off_in> or I<off_out> was not NULL, but the corresponding file "
5008 "descriptor refers to a pipe."
5012 #: build/C/man2/splice.2:169
5013 msgid "The B<splice>() system call first appeared in Linux 2.6.17."
5017 #: build/C/man2/splice.2:181
5019 "The three system calls B<splice>(), B<vmsplice>(2), and B<tee>(2), provide "
5020 "userspace programs with full control over an arbitrary kernel buffer, "
5021 "implemented within the kernel using the same type of buffer that is used for "
5022 "a pipe. In overview, these system calls perform the following tasks:"
5026 #: build/C/man2/splice.2:181
5032 #: build/C/man2/splice.2:185
5034 "moves data from the buffer to an arbitrary file descriptor, or vice versa, "
5035 "or from one buffer to another."
5039 #: build/C/man2/splice.2:185
5045 #: build/C/man2/splice.2:188
5046 msgid "\"copies\" the data from one buffer to another."
5050 #: build/C/man2/splice.2:188
5052 msgid "B<vmsplice>(2)"
5056 #: build/C/man2/splice.2:191
5057 msgid "\"copies\" data from user space into the buffer."
5061 #. Linus: Now, imagine using the above in a media server, for example.
5062 #. Let's say that a year or two has passed, so that the video drivers
5063 #. have been updated to be able to do the splice thing, and what can
5066 #. - splice from the (mpeg or whatever - let's just assume that the video
5067 #. input is either digital or does the encoding on its own - like they
5068 #. pretty much all do) video input into a pipe (remember: no copies - the
5069 #. video input will just DMA directly into memory, and splice will just
5070 #. set up the pages in the pipe buffer)
5071 #. - tee that pipe to split it up
5072 #. - splice one end to a file (ie "save the compressed stream to disk")
5073 #. - splice the other end to a real-time video decoder window for your
5074 #. real-time viewing pleasure.
5076 #. Linus: Now, the advantage of splice()/tee() is that you can
5077 #. do zero-copy movement of data, and unlike sendfile() you can
5078 #. do it on _arbitrary_ data (and, as shown by "tee()", it's more
5079 #. than just sending the data to somebody else: you can duplicate
5080 #. the data and choose to forward it to two or more different
5081 #. users - for things like logging etc.).
5083 #: build/C/man2/splice.2:222
5085 "Though we talk of copying, actual copies are generally avoided. The kernel "
5086 "does this by implementing a pipe buffer as a set of reference-counted "
5087 "pointers to pages of kernel memory. The kernel creates \"copies\" of pages "
5088 "in a buffer by creating new pointers (for the output buffer) referring to "
5089 "the pages, and increasing the reference counts for the pages: only pointers "
5090 "are copied, not the pages of the buffer."
5094 #: build/C/man2/splice.2:225
5095 msgid "See B<tee>(2)."
5099 #: build/C/man2/splice.2:229
5100 msgid "B<sendfile>(2), B<tee>(2), B<vmsplice>(2)"
5104 #: build/C/man2/tee.2:26
5110 #: build/C/man2/tee.2:29
5111 msgid "tee - duplicating pipe content"
5115 #: build/C/man2/tee.2:36
5118 "B<ssize_t tee(int >I<fd_in>B<, int >I<fd_out>B<, size_t >I<len>B<, unsigned "
5119 "int >I<flags>B<);>\n"
5122 #. Example programs http://brick.kernel.dk/snaps
5125 #. add a "tee(in, out1, out2)" system call that duplicates the pages
5126 #. (again, incrementing their reference count, not copying the data) from
5127 #. one pipe to two other pipes.
5129 #: build/C/man2/tee.2:56
5131 "B<tee>() duplicates up to I<len> bytes of data from the pipe referred to by "
5132 "the file descriptor I<fd_in> to the pipe referred to by the file descriptor "
5133 "I<fd_out>. It does not consume the data that is duplicated from I<fd_in>; "
5134 "therefore, that data can be copied by a subsequent B<splice>(2)."
5138 #: build/C/man2/tee.2:62
5140 "I<flags> is a series of modifier flags, which share the name space with "
5141 "B<splice>(2) and B<vmsplice>(2):"
5145 #: build/C/man2/tee.2:68
5146 msgid "Currently has no effect for B<tee>(); see B<splice>(2)."
5149 #. Not used for vmsplice
5150 #. May be in the future -- therefore EAGAIN
5152 #: build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
5153 msgid "Do not block on I/O; see B<splice>(2) for further details."
5157 #: build/C/man2/tee.2:79
5159 "Currently has no effect for B<tee>(), but may be implemented in the future; "
5164 #: build/C/man2/tee.2:85
5165 msgid "Unused for B<tee>(); see B<vmsplice>(2)."
5169 #: build/C/man2/tee.2:94
5171 "Upon successful completion, B<tee>() returns the number of bytes that were "
5172 "duplicated between the input and output. A return value of 0 means that "
5173 "there was no data to transfer, and it would not make sense to block, because "
5174 "there are no writers connected to the write end of the pipe referred to by "
5179 #: build/C/man2/tee.2:100
5180 msgid "On error, B<tee>() returns -1 and I<errno> is set to indicate the error."
5184 #: build/C/man2/tee.2:111
5186 "I<fd_in> or I<fd_out> does not refer to a pipe; or I<fd_in> and I<fd_out> "
5187 "refer to the same pipe."
5191 #: build/C/man2/tee.2:118
5192 msgid "The B<tee>() system call first appeared in Linux 2.6.17."
5196 #: build/C/man2/tee.2:129
5198 "Conceptually, B<tee>() copies the data between the two pipes. In reality "
5199 "no real data copying takes place though: under the covers, B<tee>() assigns "
5200 "data in the output by merely grabbing a reference to the input."
5204 #: build/C/man2/tee.2:135
5206 "The following example implements a basic B<tee>(1) program using the "
5207 "B<tee>() system call."
5211 #: build/C/man2/tee.2:144
5214 "#define _GNU_SOURCE\n"
5215 "#include E<lt>fcntl.hE<gt>\n"
5216 "#include E<lt>stdio.hE<gt>\n"
5217 "#include E<lt>stdlib.hE<gt>\n"
5218 "#include E<lt>unistd.hE<gt>\n"
5219 "#include E<lt>errno.hE<gt>\n"
5220 "#include E<lt>limits.hE<gt>\n"
5224 #: build/C/man2/tee.2:150
5228 "main(int argc, char *argv[])\n"
5235 #: build/C/man2/tee.2:155
5238 " if (argc != 2) {\n"
5239 " fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
5240 " exit(EXIT_FAILURE);\n"
5245 #: build/C/man2/tee.2:161
5248 " fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);\n"
5249 " if (fd == -1) {\n"
5250 " perror(\"open\");\n"
5251 " exit(EXIT_FAILURE);\n"
5256 #: build/C/man2/tee.2:168
5261 " * tee stdin to stdout.\n"
5263 " len = tee(STDIN_FILENO, STDOUT_FILENO,\n"
5264 " INT_MAX, SPLICE_F_NONBLOCK);\n"
5268 #: build/C/man2/tee.2:177
5271 " if (len E<lt> 0) {\n"
5272 " if (errno == EAGAIN)\n"
5274 " perror(\"tee\");\n"
5275 " exit(EXIT_FAILURE);\n"
5282 #: build/C/man2/tee.2:191
5286 " * Consume stdin by splicing it to a file.\n"
5288 " while (len E<gt> 0) {\n"
5289 " slen = splice(STDIN_FILENO, NULL, fd, NULL,\n"
5290 " len, SPLICE_F_MOVE);\n"
5291 " if (slen E<lt> 0) {\n"
5292 " perror(\"splice\");\n"
5301 #: build/C/man2/tee.2:195
5305 " exit(EXIT_SUCCESS);\n"
5310 #: build/C/man2/tee.2:199
5311 msgid "B<splice>(2), B<vmsplice>(2)"
5315 #: build/C/man2/vm86.2:26
5321 #: build/C/man2/vm86.2:26
5327 #: build/C/man2/vm86.2:29
5328 msgid "vm86old, vm86 - enter virtual 8086 mode"
5332 #: build/C/man2/vm86.2:31
5333 msgid "B<#include E<lt>sys/vm86.hE<gt>>"
5337 #: build/C/man2/vm86.2:33
5338 msgid "B<int vm86old(struct vm86_struct *>I<info>B<);>"
5342 #: build/C/man2/vm86.2:35
5343 msgid "B<int vm86(unsigned long >I<fn>B<, struct vm86plus_struct *>I<v86>B<);>"
5347 #: build/C/man2/vm86.2:46
5349 "The system call B<vm86>() was introduced in Linux 0.97p2. In Linux 2.1.15 "
5350 "and 2.0.28 it was renamed to B<vm86old>(), and a new B<vm86>() was "
5351 "introduced. The definition of I<struct vm86_struct> was changed in 1.1.8 "
5356 #: build/C/man2/vm86.2:50
5358 "These calls cause the process to enter VM86 mode (virtual-8086 in Intel "
5359 "literature), and are used by B<dosemu>."
5363 #: build/C/man2/vm86.2:52
5364 msgid "VM86 mode is an emulation of real mode within a protected mode task."
5368 #: build/C/man2/vm86.2:62
5370 "This return value is specific to i386 and indicates a problem with getting "
5375 #: build/C/man2/vm86.2:66
5377 "This return value indicates the call is not implemented on the present "
5382 #: build/C/man2/vm86.2:71
5384 "Saved kernel stack exists. (This is a kernel sanity check; the saved stack "
5385 "should only exist within vm86 mode itself.)"
5389 #: build/C/man2/vm86.2:74
5391 "This call is specific to Linux on 32-bit Intel processors, and should not be "
5392 "used in programs intended to be portable."
5396 #: build/C/man2/vmsplice.2:26
5402 #: build/C/man2/vmsplice.2:29
5403 msgid "vmsplice - splice user pages into a pipe"
5407 #: build/C/man2/vmsplice.2:34
5410 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
5411 "B<#include E<lt>fcntl.hE<gt>>\n"
5412 "B<#include E<lt>sys/uio.hE<gt>>\n"
5416 #: build/C/man2/vmsplice.2:37
5419 "B<ssize_t vmsplice(int >I<fd>B<, const struct iovec *>I<iov>B<,>\n"
5420 "B< unsigned long >I<nr_segs>B<, unsigned int "
5424 #. Linus: vmsplice() system call to basically do a "write to
5425 #. the buffer", but using the reference counting and VM traversal
5426 #. to actually fill the buffer. This means that the user needs to
5427 #. be careful not to reuse the user-space buffer it spliced into
5428 #. the kernel-space one (contrast this to "write()", which copies
5429 #. the actual data, and you can thus reuse the buffer immediately
5430 #. after a successful write), but that is often easy to do.
5432 #: build/C/man2/vmsplice.2:57
5434 "The B<vmsplice>() system call maps I<nr_segs> ranges of user memory "
5435 "described by I<iov> into a pipe. The file descriptor I<fd> must refer to a "
5440 #: build/C/man2/vmsplice.2:64
5442 "The pointer I<iov> points to an array of I<iovec> structures as defined in "
5443 "I<E<lt>sys/uio.hE<gt>>:"
5447 #: build/C/man2/vmsplice.2:71
5451 " void *iov_base; /* Starting address */\n"
5452 " size_t iov_len; /* Number of bytes */\n"
5457 #: build/C/man2/vmsplice.2:84
5458 msgid "Unused for B<vmsplice>(); see B<splice>(2)."
5462 #: build/C/man2/vmsplice.2:97
5464 "Currently has no effect for B<vmsplice>(), but may be implemented in the "
5465 "future; see B<splice>(2)."
5468 #. FIXME Explain the following line in a little more detail:
5469 #. .... if we expect to later SPLICE_F_MOVE to the cache.
5471 #: build/C/man2/vmsplice.2:113
5473 "The user pages are a gift to the kernel. The application may not modify "
5474 "this memory ever, or page cache and on-disk data may differ. Gifting pages "
5475 "to the kernel means that a subsequent B<splice>(2) B<SPLICE_F_MOVE> can "
5476 "successfully move the pages; if this flag is not specified, then a "
5477 "subsequent B<splice>(2) B<SPLICE_F_MOVE> must copy the pages. Data must "
5478 "also be properly page aligned, both in memory and length."
5482 #: build/C/man2/vmsplice.2:122
5484 "Upon successful completion, B<vmsplice>() returns the number of bytes "
5485 "transferred to the pipe. On error, B<vmsplice>() returns -1 and I<errno> "
5486 "is set to indicate the error."
5490 #: build/C/man2/vmsplice.2:127
5491 msgid "I<fd> either not valid, or doesn't refer to a pipe."
5495 #: build/C/man2/vmsplice.2:135
5497 "I<nr_segs> is 0 or greater than B<IOV_MAX>; or memory not aligned if "
5498 "B<SPLICE_F_GIFT> set."
5502 #: build/C/man2/vmsplice.2:142
5503 msgid "The B<vmsplice>() system call first appeared in Linux 2.6.17."
5507 #: build/C/man2/vmsplice.2:153
5509 "B<vmsplice>() follows the other vectorized read/write type functions when "
5510 "it comes to limitations on number of segments being passed in. This limit "
5511 "is B<IOV_MAX> as defined in I<E<lt>limits.hE<gt>>. At the time of this "
5512 "writing, that limit is 1024."
5516 #: build/C/man2/vmsplice.2:156
5517 msgid "B<splice>(2), B<tee>(2)"