po4a/man2/po/man2.pot

   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.
   5 #
   6 #, fuzzy
   7 msgid ""
   8 msgstr ""
   9 "Project-Id-Version: PACKAGE VERSION\n"
  10 "POT-Creation-Date: 2013-03-26 16:48+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"
  14 "Language: \n"
  15 "MIME-Version: 1.0\n"
  16 "Content-Type: text/plain; charset=CHARSET\n"
  17 "Content-Transfer-Encoding: 8bit\n"
  18
  19 #. type: TH
  20 #: build/C/man2/arch_prctl.2:25
  21 #, no-wrap
  22 msgid "ARCH_PRCTL"
  23 msgstr ""
  24
  25 #. type: TH
  26 #: build/C/man2/arch_prctl.2:25
  27 #, no-wrap
  28 msgid "2007-12-26"
  29 msgstr ""
  30
  31 #. type: TH
  32 #: build/C/man2/arch_prctl.2:25 build/C/man2/futex.2:53 build/C/man2/get_robust_list.2:29 build/C/man2/getunwind.2:27 build/C/man2/kexec_load.2:26 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:24 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:26 build/C/man2/pciconfig_read.2:8 build/C/man2/perf_event_open.2:27 build/C/man2/perfmonctl.2:27 build/C/man2/personality.2:32 build/C/man2/pivot_root.2:10 build/C/man2/process_vm_readv.2:29 build/C/man2/ptrace.2:44 build/C/man2/quotactl.2:27 build/C/man2/sendfile.2:19 build/C/man2/set_tid_address.2:25 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
  33 #, no-wrap
  34 msgid "Linux"
  35 msgstr ""
  36
  37 #. type: TH
  38 #: build/C/man2/arch_prctl.2:25 build/C/man2/futex.2:53 build/C/man2/getunwind.2:27 build/C/man2/kexec_load.2:26 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:24 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:26 build/C/man2/pciconfig_read.2:8 build/C/man2/perf_event_open.2:27 build/C/man2/perfmonctl.2:27 build/C/man2/personality.2:32 build/C/man2/pivot_root.2:10 build/C/man2/process_vm_readv.2:29 build/C/man2/ptrace.2:44 build/C/man2/quotactl.2:27 build/C/man2/sendfile.2:19 build/C/man2/set_tid_address.2:25 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
  39 #, no-wrap
  40 msgid "Linux Programmer's Manual"
  41 msgstr ""
  42
  43 #. type: SH
  44 #: build/C/man2/arch_prctl.2:26 build/C/man2/futex.2:54 build/C/man2/get_robust_list.2:30 build/C/man2/getunwind.2:28 build/C/man2/kexec_load.2:27 build/C/man2/lookup_dcookie.2:28 build/C/man2/modify_ldt.2:25 build/C/man2/nfsservctl.2:9 build/C/man2/outb.2:27 build/C/man2/pciconfig_read.2:9 build/C/man2/perf_event_open.2:28 build/C/man2/perfmonctl.2:28 build/C/man2/personality.2:33 build/C/man2/pivot_root.2:11 build/C/man2/process_vm_readv.2:30 build/C/man2/ptrace.2:45 build/C/man2/quotactl.2:28 build/C/man2/sendfile.2:20 build/C/man2/set_tid_address.2:26 build/C/man2/splice.2:27 build/C/man2/tee.2:27 build/C/man2/vm86.2:27 build/C/man2/vmsplice.2:27
  45 #, no-wrap
  46 msgid "NAME"
  47 msgstr ""
  48
  49 #. type: Plain text
  50 #: build/C/man2/arch_prctl.2:28
  51 msgid "arch_prctl - set architecture-specific thread state"
  52 msgstr ""
  53
  54 #. type: SH
  55 #: build/C/man2/arch_prctl.2:28 build/C/man2/futex.2:56 build/C/man2/get_robust_list.2:32 build/C/man2/getunwind.2:30 build/C/man2/kexec_load.2:29 build/C/man2/lookup_dcookie.2:30 build/C/man2/modify_ldt.2:27 build/C/man2/nfsservctl.2:11 build/C/man2/outb.2:31 build/C/man2/pciconfig_read.2:11 build/C/man2/perf_event_open.2:30 build/C/man2/perfmonctl.2:30 build/C/man2/personality.2:35 build/C/man2/pivot_root.2:13 build/C/man2/process_vm_readv.2:32 build/C/man2/ptrace.2:47 build/C/man2/quotactl.2:30 build/C/man2/sendfile.2:22 build/C/man2/set_tid_address.2:28 build/C/man2/splice.2:29 build/C/man2/tee.2:29 build/C/man2/vm86.2:29 build/C/man2/vmsplice.2:29
  56 #, no-wrap
  57 msgid "SYNOPSIS"
  58 msgstr ""
  59
  60 #. type: Plain text
  61 #: build/C/man2/arch_prctl.2:31
  62 #, no-wrap
  63 msgid "B<#include E<lt>asm/prctl.hE<gt>>\n"
  64 msgstr ""
  65
  66 #. type: Plain text
  67 #: build/C/man2/arch_prctl.2:33
  68 #, no-wrap
  69 msgid "B<#include E<lt>sys/prctl.hE<gt>>\n"
  70 msgstr ""
  71
  72 #. type: Plain text
  73 #: build/C/man2/arch_prctl.2:36
  74 #, no-wrap
  75 msgid ""
  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"
  78 msgstr ""
  79
  80 #.  Return type was long before glibc 2.7
  81 #. type: SH
  82 #: build/C/man2/arch_prctl.2:37 build/C/man2/futex.2:68 build/C/man2/get_robust_list.2:44 build/C/man2/getunwind.2:40 build/C/man2/kexec_load.2:39 build/C/man2/lookup_dcookie.2:32 build/C/man2/modify_ldt.2:36 build/C/man2/nfsservctl.2:18 build/C/man2/outb.2:62 build/C/man2/pciconfig_read.2:22 build/C/man2/perf_event_open.2:42 build/C/man2/perfmonctl.2:39 build/C/man2/personality.2:39 build/C/man2/pivot_root.2:18 build/C/man2/process_vm_readv.2:50 build/C/man2/ptrace.2:54 build/C/man2/quotactl.2:38 build/C/man2/sendfile.2:47 build/C/man2/set_tid_address.2:34 build/C/man2/splice.2:39 build/C/man2/tee.2:38 build/C/man2/vm86.2:35 build/C/man2/vmsplice.2:39
  83 #, no-wrap
  84 msgid "DESCRIPTION"
  85 msgstr ""
  86
  87 #. type: Plain text
  88 #: build/C/man2/arch_prctl.2:52
  89 msgid ""
  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."
  94 msgstr ""
  95
  96 #. type: Plain text
  97 #: build/C/man2/arch_prctl.2:54
  98 msgid "Sub functions for x86-64 are:"
  99 msgstr ""
 100
 101 #. type: TP
 102 #: build/C/man2/arch_prctl.2:54
 103 #, no-wrap
 104 msgid "B<ARCH_SET_FS>"
 105 msgstr ""
 106
 107 #. type: Plain text
 108 #: build/C/man2/arch_prctl.2:60
 109 msgid "Set the 64-bit base for the I<FS> register to I<addr>."
 110 msgstr ""
 111
 112 #. type: TP
 113 #: build/C/man2/arch_prctl.2:60
 114 #, no-wrap
 115 msgid "B<ARCH_GET_FS>"
 116 msgstr ""
 117
 118 #. type: Plain text
 119 #: build/C/man2/arch_prctl.2:68
 120 msgid ""
 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>."
 123 msgstr ""
 124
 125 #. type: TP
 126 #: build/C/man2/arch_prctl.2:68
 127 #, no-wrap
 128 msgid "B<ARCH_SET_GS>"
 129 msgstr ""
 130
 131 #. type: Plain text
 132 #: build/C/man2/arch_prctl.2:74
 133 msgid "Set the 64-bit base for the I<GS> register to I<addr>."
 134 msgstr ""
 135
 136 #. type: TP
 137 #: build/C/man2/arch_prctl.2:74
 138 #, no-wrap
 139 msgid "B<ARCH_GET_GS>"
 140 msgstr ""
 141
 142 #. type: Plain text
 143 #: build/C/man2/arch_prctl.2:82
 144 msgid ""
 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>."
 147 msgstr ""
 148
 149 #. type: SH
 150 #: build/C/man2/arch_prctl.2:82 build/C/man2/futex.2:209 build/C/man2/get_robust_list.2:77 build/C/man2/getunwind.2:81 build/C/man2/kexec_load.2:114 build/C/man2/lookup_dcookie.2:43 build/C/man2/modify_ldt.2:98 build/C/man2/nfsservctl.2:51 build/C/man2/pciconfig_read.2:50 build/C/man2/perf_event_open.2:1804 build/C/man2/perfmonctl.2:190 build/C/man2/personality.2:57 build/C/man2/pivot_root.2:101 build/C/man2/process_vm_readv.2:209 build/C/man2/ptrace.2:1713 build/C/man2/sendfile.2:108 build/C/man2/set_tid_address.2:88 build/C/man2/splice.2:127 build/C/man2/tee.2:85 build/C/man2/vm86.2:52 build/C/man2/vmsplice.2:113
 151 #, no-wrap
 152 msgid "RETURN VALUE"
 153 msgstr ""
 154
 155 #. type: Plain text
 156 #: build/C/man2/arch_prctl.2:88
 157 msgid ""
 158 "On success, B<arch_prctl>()  returns 0; on error, -1 is returned, and "
 159 "I<errno> is set to indicate the error."
 160 msgstr ""
 161
 162 #. type: SH
 163 #: build/C/man2/arch_prctl.2:88 build/C/man2/futex.2:234 build/C/man2/get_robust_list.2:84 build/C/man2/getunwind.2:88 build/C/man2/kexec_load.2:121 build/C/man2/lookup_dcookie.2:50 build/C/man2/modify_ldt.2:108 build/C/man2/pciconfig_read.2:77 build/C/man2/perf_event_open.2:1810 build/C/man2/personality.2:64 build/C/man2/pivot_root.2:105 build/C/man2/process_vm_readv.2:229 build/C/man2/ptrace.2:1727 build/C/man2/quotactl.2:427 build/C/man2/sendfile.2:115 build/C/man2/set_tid_address.2:91 build/C/man2/splice.2:142 build/C/man2/tee.2:100 build/C/man2/vm86.2:57 build/C/man2/vmsplice.2:122
 164 #, no-wrap
 165 msgid "ERRORS"
 166 msgstr ""
 167
 168 #. type: TP
 169 #: build/C/man2/arch_prctl.2:89 build/C/man2/futex.2:249 build/C/man2/get_robust_list.2:111 build/C/man2/lookup_dcookie.2:51 build/C/man2/modify_ldt.2:109 build/C/man2/process_vm_readv.2:251 build/C/man2/process_vm_readv.2:256 build/C/man2/ptrace.2:1731 build/C/man2/quotactl.2:428 build/C/man2/sendfile.2:125 build/C/man2/vm86.2:58
 170 #, no-wrap
 171 msgid "B<EFAULT>"
 172 msgstr ""
 173
 174 #. type: Plain text
 175 #: build/C/man2/arch_prctl.2:93
 176 msgid ""
 177 "I<addr> points to an unmapped address or is outside the process address "
 178 "space."
 179 msgstr ""
 180
 181 #. type: TP
 182 #: build/C/man2/arch_prctl.2:93 build/C/man2/futex.2:261 build/C/man2/get_robust_list.2:88 build/C/man2/kexec_load.2:126 build/C/man2/lookup_dcookie.2:54 build/C/man2/modify_ldt.2:113 build/C/man2/pciconfig_read.2:78 build/C/man2/perf_event_open.2:1811 build/C/man2/personality.2:65 build/C/man2/pivot_root.2:114 build/C/man2/process_vm_readv.2:230 build/C/man2/process_vm_readv.2:241 build/C/man2/process_vm_readv.2:245 build/C/man2/ptrace.2:1742 build/C/man2/quotactl.2:434 build/C/man2/quotactl.2:501 build/C/man2/sendfile.2:128 build/C/man2/splice.2:147 build/C/man2/tee.2:101 build/C/man2/vmsplice.2:127
 183 #, no-wrap
 184 msgid "B<EINVAL>"
 185 msgstr ""
 186
 187 #. type: Plain text
 188 #: build/C/man2/arch_prctl.2:97
 189 msgid "I<code> is not a valid subcommand."
 190 msgstr ""
 191
 192 #. type: TP
 193 #: build/C/man2/arch_prctl.2:97 build/C/man2/get_robust_list.2:98 build/C/man2/kexec_load.2:133 build/C/man2/lookup_dcookie.2:65 build/C/man2/pciconfig_read.2:105 build/C/man2/pivot_root.2:120 build/C/man2/process_vm_readv.2:267 build/C/man2/ptrace.2:1752 build/C/man2/quotactl.2:456 build/C/man2/vm86.2:66
 194 #, no-wrap
 195 msgid "B<EPERM>"
 196 msgstr ""
 197
 198 #.  .SH AUTHOR
 199 #.  Man page written by Andi Kleen.
 200 #. type: Plain text
 201 #: build/C/man2/arch_prctl.2:103
 202 msgid "I<addr> is outside the process address space."
 203 msgstr ""
 204
 205 #. type: SH
 206 #: build/C/man2/arch_prctl.2:103 build/C/man2/futex.2:296 build/C/man2/getunwind.2:96 build/C/man2/kexec_load.2:142 build/C/man2/lookup_dcookie.2:78 build/C/man2/modify_ldt.2:130 build/C/man2/nfsservctl.2:56 build/C/man2/outb.2:87 build/C/man2/pciconfig_read.2:110 build/C/man2/perf_event_open.2:1829 build/C/man2/perfmonctl.2:199 build/C/man2/personality.2:68 build/C/man2/pivot_root.2:128 build/C/man2/process_vm_readv.2:279 build/C/man2/ptrace.2:1770 build/C/man2/sendfile.2:148 build/C/man2/set_tid_address.2:97 build/C/man2/splice.2:170 build/C/man2/tee.2:119 build/C/man2/vm86.2:71 build/C/man2/vmsplice.2:143
 207 #, no-wrap
 208 msgid "CONFORMING TO"
 209 msgstr ""
 210
 211 #. type: Plain text
 212 #: build/C/man2/arch_prctl.2:107
 213 msgid ""
 214 "B<arch_prctl>()  is a Linux/x86-64 extension and should not be used in "
 215 "programs intended to be portable."
 216 msgstr ""
 217
 218 #. type: SH
 219 #: build/C/man2/arch_prctl.2:107 build/C/man2/futex.2:298 build/C/man2/get_robust_list.2:119 build/C/man2/getunwind.2:99 build/C/man2/kexec_load.2:144 build/C/man2/lookup_dcookie.2:81 build/C/man2/modify_ldt.2:133 build/C/man2/perf_event_open.2:1834 build/C/man2/perfmonctl.2:202 build/C/man2/pivot_root.2:131 build/C/man2/process_vm_readv.2:281 build/C/man2/ptrace.2:1772 build/C/man2/sendfile.2:155 build/C/man2/splice.2:172 build/C/man2/tee.2:121 build/C/man2/vmsplice.2:145
 220 #, no-wrap
 221 msgid "NOTES"
 222 msgstr ""
 223
 224 #. type: Plain text
 225 #: build/C/man2/arch_prctl.2:110
 226 msgid ""
 227 "B<arch_prctl>()  is only supported on Linux/x86-64 for 64-bit programs "
 228 "currently."
 229 msgstr ""
 230
 231 #. type: Plain text
 232 #: build/C/man2/arch_prctl.2:112
 233 msgid "The 64-bit base changes when a new 32-bit segment selector is loaded."
 234 msgstr ""
 235
 236 #. type: Plain text
 237 #: build/C/man2/arch_prctl.2:115
 238 msgid "B<ARCH_SET_GS> is disabled in some kernels."
 239 msgstr ""
 240
 241 #. type: Plain text
 242 #: build/C/man2/arch_prctl.2:130
 243 msgid ""
 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."
 250 msgstr ""
 251
 252 #. type: Plain text
 253 #: build/C/man2/arch_prctl.2:135
 254 msgid ""
 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 "
 257 "versions."
 258 msgstr ""
 259
 260 #. type: Plain text
 261 #: build/C/man2/arch_prctl.2:138
 262 msgid "I<FS> may be already used by the threading library."
 263 msgstr ""
 264
 265 #. type: SH
 266 #: build/C/man2/arch_prctl.2:138 build/C/man2/futex.2:312 build/C/man2/get_robust_list.2:128 build/C/man2/getunwind.2:111 build/C/man2/kexec_load.2:159 build/C/man2/modify_ldt.2:136 build/C/man2/outb.2:96 build/C/man2/pciconfig_read.2:112 build/C/man2/perf_event_open.2:1948 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:143 build/C/man2/process_vm_readv.2:331 build/C/man2/ptrace.2:1926 build/C/man2/quotactl.2:507 build/C/man2/sendfile.2:197 build/C/man2/set_tid_address.2:99 build/C/man2/splice.2:226 build/C/man2/tee.2:197 build/C/man2/vmsplice.2:154
 267 #, no-wrap
 268 msgid "SEE ALSO"
 269 msgstr ""
 270
 271 #. type: Plain text
 272 #: build/C/man2/arch_prctl.2:143
 273 msgid "B<mmap>(2), B<modify_ldt>(2), B<prctl>(2), B<set_thread_area>(2)"
 274 msgstr ""
 275
 276 #. type: Plain text
 277 #: build/C/man2/arch_prctl.2:145
 278 msgid "AMD X86-64 Programmer's manual"
 279 msgstr ""
 280
 281 #. type: SH
 282 #: build/C/man2/arch_prctl.2:145 build/C/man2/futex.2:325 build/C/man2/get_robust_list.2:137 build/C/man2/getunwind.2:113 build/C/man2/kexec_load.2:162 build/C/man2/lookup_dcookie.2:88 build/C/man2/modify_ldt.2:138 build/C/man2/nfsservctl.2:58 build/C/man2/outb.2:99 build/C/man2/pciconfig_read.2:114 build/C/man2/perf_event_open.2:1954 build/C/man2/perfmonctl.2:209 build/C/man2/personality.2:72 build/C/man2/pivot_root.2:149 build/C/man2/process_vm_readv.2:334 build/C/man2/ptrace.2:1940 build/C/man2/quotactl.2:512 build/C/man2/sendfile.2:203 build/C/man2/set_tid_address.2:102 build/C/man2/splice.2:230 build/C/man2/tee.2:200 build/C/man2/vm86.2:74 build/C/man2/vmsplice.2:157
 283 #, no-wrap
 284 msgid "COLOPHON"
 285 msgstr ""
 286
 287 #. type: Plain text
 288 #: build/C/man2/arch_prctl.2:152 build/C/man2/futex.2:332 build/C/man2/get_robust_list.2:144 build/C/man2/getunwind.2:120 build/C/man2/kexec_load.2:169 build/C/man2/lookup_dcookie.2:95 build/C/man2/modify_ldt.2:145 build/C/man2/nfsservctl.2:65 build/C/man2/outb.2:106 build/C/man2/pciconfig_read.2:121 build/C/man2/perf_event_open.2:1961 build/C/man2/perfmonctl.2:216 build/C/man2/personality.2:79 build/C/man2/pivot_root.2:156 build/C/man2/process_vm_readv.2:341 build/C/man2/ptrace.2:1947 build/C/man2/quotactl.2:519 build/C/man2/sendfile.2:210 build/C/man2/set_tid_address.2:109 build/C/man2/splice.2:237 build/C/man2/tee.2:207 build/C/man2/vm86.2:81 build/C/man2/vmsplice.2:164
 289 msgid ""
 290 "This page is part of release 3.50 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/."
 293 msgstr ""
 294
 295 #. type: TH
 296 #: build/C/man2/futex.2:53
 297 #, no-wrap
 298 msgid "FUTEX"
 299 msgstr ""
 300
 301 #. type: TH
 302 #: build/C/man2/futex.2:53
 303 #, no-wrap
 304 msgid "2013-03-15"
 305 msgstr ""
 306
 307 #. type: Plain text
 308 #: build/C/man2/futex.2:56
 309 msgid "futex - fast user-space locking"
 310 msgstr ""
 311
 312 #. type: Plain text
 313 #: build/C/man2/futex.2:61
 314 #, no-wrap
 315 msgid ""
 316 "B<#include E<lt>linux/futex.hE<gt>>\n"
 317 "B<#include E<lt>sys/time.hE<gt>>\n"
 318 msgstr ""
 319
 320 #. type: Plain text
 321 #: build/C/man2/futex.2:64
 322 #, no-wrap
 323 msgid ""
 324 "B<int futex(int *>I<uaddr>B<, int >I<op>B<, int >I<val>B<, const struct "
 325 "timespec *>I<timeout>B<,>\n"
 326 msgstr ""
 327
 328 #.  int *? void *? u32 *?
 329 #. type: Plain text
 330 #: build/C/man2/futex.2:67
 331 #, no-wrap
 332 msgid "B<          int *>I<uaddr2>B<, int >I<val3>B<);>\n"
 333 msgstr ""
 334
 335 #. type: Plain text
 336 #: build/C/man2/futex.2:84
 337 msgid ""
 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)."
 345 msgstr ""
 346
 347 #. type: Plain text
 348 #: build/C/man2/futex.2:91
 349 msgid ""
 350 "When a B<futex>(7)  operation did not finish uncontended in user space, 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 "
 353 "process."
 354 msgstr ""
 355
 356 #. type: Plain text
 357 #: build/C/man2/futex.2:98
 358 msgid ""
 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."
 363 msgstr ""
 364
 365 #. type: Plain text
 366 #: build/C/man2/futex.2:106
 367 msgid ""
 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>."
 371 msgstr ""
 372
 373 #. type: Plain text
 374 #: build/C/man2/futex.2:108
 375 msgid "Five operations are currently defined:"
 376 msgstr ""
 377
 378 #. type: TP
 379 #: build/C/man2/futex.2:108 build/C/man2/futex.2:216
 380 #, no-wrap
 381 msgid "B<FUTEX_WAIT>"
 382 msgstr ""
 383
 384 #. type: Plain text
 385 #: build/C/man2/futex.2:126
 386 msgid ""
 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 "minimum duration of the wait, which is infinite otherwise.  The arguments "
 391 "I<uaddr2> and I<val3> are ignored."
 392 msgstr ""
 393
 394 #. type: Plain text
 395 #: build/C/man2/futex.2:134
 396 msgid ""
 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."
 400 msgstr ""
 401
 402 #. type: TP
 403 #: build/C/man2/futex.2:134 build/C/man2/futex.2:222
 404 #, no-wrap
 405 msgid "B<FUTEX_WAKE>"
 406 msgstr ""
 407
 408 #. type: Plain text
 409 #: build/C/man2/futex.2:145
 410 msgid ""
 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."
 414 msgstr ""
 415
 416 #. type: Plain text
 417 #: build/C/man2/futex.2:151
 418 msgid ""
 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 "
 421 "it is available)."
 422 msgstr ""
 423
 424 #. type: TP
 425 #: build/C/man2/futex.2:151
 426 #, no-wrap
 427 msgid "B<FUTEX_FD> (present up to and including Linux 2.6.25)"
 428 msgstr ""
 429
 430 #.  , suitable for .BR poll (2).
 431 #. type: Plain text
 432 #: build/C/man2/futex.2:167
 433 msgid ""
 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."
 439 msgstr ""
 440
 441 #. type: Plain text
 442 #: build/C/man2/futex.2:172
 443 msgid ""
 444 "To prevent race conditions, the caller should test if the futex has been "
 445 "upped after B<FUTEX_FD> returns."
 446 msgstr ""
 447
 448 #. type: Plain text
 449 #: build/C/man2/futex.2:176
 450 msgid ""
 451 "Because it was inherently racy, B<FUTEX_FD> has been removed from Linux "
 452 "2.6.26 onward."
 453 msgstr ""
 454
 455 #. type: TP
 456 #: build/C/man2/futex.2:176
 457 #, no-wrap
 458 msgid "B<FUTEX_REQUEUE> (since Linux 2.5.70)"
 459 msgstr ""
 460
 461 #. type: Plain text
 462 #: build/C/man2/futex.2:191
 463 msgid ""
 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."
 469 msgstr ""
 470
 471 #. type: TP
 472 #: build/C/man2/futex.2:191
 473 #, no-wrap
 474 msgid "B<FUTEX_CMP_REQUEUE> (since Linux 2.6.7)"
 475 msgstr ""
 476
 477 #. type: Plain text
 478 #: build/C/man2/futex.2:209
 479 msgid ""
 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."
 485 msgstr ""
 486
 487 #. type: Plain text
 488 #: build/C/man2/futex.2:216
 489 msgid ""
 490 "In the event of an error, all operations return -1, and set I<errno> to "
 491 "indicate the error.  The return value on success depends on the operation, "
 492 "as described in the following list:"
 493 msgstr ""
 494
 495 #. type: Plain text
 496 #: build/C/man2/futex.2:222
 497 msgid ""
 498 "Returns 0 if the process was woken by a B<FUTEX_WAKE> call.  See ERRORS for "
 499 "the various possible error returns."
 500 msgstr ""
 501
 502 #. type: Plain text
 503 #: build/C/man2/futex.2:225 build/C/man2/futex.2:231 build/C/man2/futex.2:234
 504 msgid "Returns the number of processes woken up."
 505 msgstr ""
 506
 507 #. type: TP
 508 #: build/C/man2/futex.2:225
 509 #, no-wrap
 510 msgid "B<FUTEX_FD>"
 511 msgstr ""
 512
 513 #. type: Plain text
 514 #: build/C/man2/futex.2:228
 515 msgid "Returns the new file descriptor associated with the futex."
 516 msgstr ""
 517
 518 #. type: TP
 519 #: build/C/man2/futex.2:228
 520 #, no-wrap
 521 msgid "B<FUTEX_REQUEUE>"
 522 msgstr ""
 523
 524 #. type: TP
 525 #: build/C/man2/futex.2:231
 526 #, no-wrap
 527 msgid "B<FUTEX_CMP_REQUEUE>"
 528 msgstr ""
 529
 530 #. type: TP
 531 #: build/C/man2/futex.2:235 build/C/man2/quotactl.2:486
 532 #, no-wrap
 533 msgid "B<EACCES>"
 534 msgstr ""
 535
 536 #. type: Plain text
 537 #: build/C/man2/futex.2:238
 538 msgid "No read access to futex memory."
 539 msgstr ""
 540
 541 #. type: TP
 542 #: build/C/man2/futex.2:238 build/C/man2/sendfile.2:116
 543 #, no-wrap
 544 msgid "B<EAGAIN>"
 545 msgstr ""
 546
 547 #. type: Plain text
 548 #: build/C/man2/futex.2:249
 549 msgid ""
 550 "B<FUTEX_CMP_REQUEUE> detected that the value pointed to by I<uaddr> is not "
 551 "equal to the expected value I<val3>.  (This probably indicates a race; use "
 552 "the safe B<FUTEX_WAKE> now.)"
 553 msgstr ""
 554
 555 #. type: Plain text
 556 #: build/C/man2/futex.2:254
 557 msgid "Error retrieving I<timeout> information from user space."
 558 msgstr ""
 559
 560 #. type: TP
 561 #: build/C/man2/futex.2:254
 562 #, no-wrap
 563 msgid "B<EINTR>"
 564 msgstr ""
 565
 566 #. type: Plain text
 567 #: build/C/man2/futex.2:261
 568 msgid ""
 569 "A B<FUTEX_WAIT> operation was interrupted by a signal (see B<signal>(7))  or "
 570 "a spurious wakeup."
 571 msgstr ""
 572
 573 #. type: Plain text
 574 #: build/C/man2/futex.2:264
 575 msgid "Invalid argument."
 576 msgstr ""
 577
 578 #. type: TP
 579 #: build/C/man2/futex.2:264
 580 #, no-wrap
 581 msgid "B<ENFILE>"
 582 msgstr ""
 583
 584 #. type: Plain text
 585 #: build/C/man2/futex.2:267
 586 msgid "The system limit on the total number of open files has been reached."
 587 msgstr ""
 588
 589 #. type: TP
 590 #: build/C/man2/futex.2:267 build/C/man2/modify_ldt.2:126 build/C/man2/pciconfig_read.2:93 build/C/man2/quotactl.2:447 build/C/man2/vm86.2:62
 591 #, no-wrap
 592 msgid "B<ENOSYS>"
 593 msgstr ""
 594
 595 #. type: Plain text
 596 #: build/C/man2/futex.2:271
 597 msgid "Invalid operation specified in I<op>."
 598 msgstr ""
 599
 600 #. type: TP
 601 #: build/C/man2/futex.2:271
 602 #, no-wrap
 603 msgid "B<ETIMEDOUT>"
 604 msgstr ""
 605
 606 #. type: Plain text
 607 #: build/C/man2/futex.2:276
 608 msgid "Timeout during the B<FUTEX_WAIT> operation."
 609 msgstr ""
 610
 611 #. type: TP
 612 #: build/C/man2/futex.2:276
 613 #, no-wrap
 614 msgid "B<EWOULDBLOCK>"
 615 msgstr ""
 616
 617 #. type: Plain text
 618 #: build/C/man2/futex.2:286
 619 msgid ""
 620 "I<op> was B<FUTEX_WAIT> and the value pointed to by I<uaddr> was not equal "
 621 "to the expected value I<val> at the time of the call."
 622 msgstr ""
 623
 624 #. type: SH
 625 #: build/C/man2/futex.2:286 build/C/man2/get_robust_list.2:115 build/C/man2/getunwind.2:94 build/C/man2/kexec_load.2:138 build/C/man2/lookup_dcookie.2:73 build/C/man2/perfmonctl.2:196 build/C/man2/pivot_root.2:125 build/C/man2/process_vm_readv.2:276 build/C/man2/sendfile.2:142 build/C/man2/set_tid_address.2:94 build/C/man2/splice.2:165 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
 626 #, no-wrap
 627 msgid "VERSIONS"
 628 msgstr ""
 629
 630 #. type: Plain text
 631 #: build/C/man2/futex.2:296
 632 msgid ""
 633 "Initial futex support was merged in Linux 2.5.7 but with different semantics "
 634 "from what was described above.  A 4-argument system call with the semantics "
 635 "described in this page was introduced in Linux 2.5.40.  In Linux 2.5.70 one "
 636 "argument was added.  In Linux 2.6.7 a sixth argument was added\\(emmessy, "
 637 "especially on the s390 architecture."
 638 msgstr ""
 639
 640 #. type: Plain text
 641 #: build/C/man2/futex.2:298 build/C/man2/kexec_load.2:144 build/C/man2/set_tid_address.2:99 build/C/man2/splice.2:172 build/C/man2/tee.2:121 build/C/man2/vmsplice.2:145
 642 msgid "This system call is Linux-specific."
 643 msgstr ""
 644
 645 #.  .SH "AUTHORS"
 646 #.  .PP
 647 #.  Futexes were designed and worked on by
 648 #.  Hubertus Franke (IBM Thomas J. Watson Research Center),
 649 #.  Matthew Kirkwood, Ingo Molnar (Red Hat)
 650 #.  and Rusty Russell (IBM Linux Technology Center).
 651 #.  This page written by bert hubert.
 652 #. type: Plain text
 653 #: build/C/man2/futex.2:312
 654 msgid ""
 655 "To reiterate, bare futexes are not intended as an easy-to-use abstraction "
 656 "for end-users.  (There is no wrapper function for this system call in "
 657 "glibc.)  Implementors are expected to be assembly literate and to have read "
 658 "the sources of the futex user-space library referenced below."
 659 msgstr ""
 660
 661 #. type: Plain text
 662 #: build/C/man2/futex.2:314
 663 msgid "B<futex>(7)"
 664 msgstr ""
 665
 666 #. type: Plain text
 667 #: build/C/man2/futex.2:317
 668 msgid ""
 669 "I<Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux> (proceedings "
 670 "of the Ottawa Linux Symposium 2002), online at"
 671 msgstr ""
 672
 673 #. type: Plain text
 674 #: build/C/man2/futex.2:320
 675 msgid ""
 676 "E<.UR http://kernel.org\\:/doc\\:/ols\\:/2002\\:/ols2002-pages-479-495.pdf> "
 677 "E<.UE>"
 678 msgstr ""
 679
 680 #. type: Plain text
 681 #: build/C/man2/futex.2:322
 682 msgid "Futex example library, futex-*.tar.bz2 at"
 683 msgstr ""
 684
 685 #. type: Plain text
 686 #: build/C/man2/futex.2:325
 687 msgid ""
 688 "E<.UR ftp://ftp.nl.kernel.org\\:/pub\\:/linux\\:/kernel\\:/people\\:/rusty/> "
 689 "E<.UE>"
 690 msgstr ""
 691
 692 #. type: TH
 693 #: build/C/man2/get_robust_list.2:29
 694 #, no-wrap
 695 msgid "GET_ROBUST_LIST"
 696 msgstr ""
 697
 698 #. type: TH
 699 #: build/C/man2/get_robust_list.2:29 build/C/man2/kexec_load.2:26 build/C/man2/modify_ldt.2:24 build/C/man2/pivot_root.2:10
 700 #, no-wrap
 701 msgid "2012-07-13"
 702 msgstr ""
 703
 704 #. type: TH
 705 #: build/C/man2/get_robust_list.2:29
 706 #, no-wrap
 707 msgid "Linux System Calls"
 708 msgstr ""
 709
 710 #. type: Plain text
 711 #: build/C/man2/get_robust_list.2:32
 712 msgid "get_robust_list, set_robust_list - get/set list of robust futexes"
 713 msgstr ""
 714
 715 #. type: Plain text
 716 #: build/C/man2/get_robust_list.2:36
 717 #, no-wrap
 718 msgid ""
 719 "B<#include E<lt>linux/futex.hE<gt>>\n"
 720 "B<#include E<lt>syscall.hE<gt>>\n"
 721 msgstr ""
 722
 723 #. type: Plain text
 724 #: build/C/man2/get_robust_list.2:40
 725 #, no-wrap
 726 msgid ""
 727 "B<long get_robust_list(int >I<pid>B<, struct robust_list_head "
 728 "**>I<head_ptr>B<,>\n"
 729 "B<\t\t\t  size_t *>I<len_ptr>B<);>\n"
 730 "B<long set_robust_list(struct robust_list_head *>I<head>B<, size_t "
 731 ">I<len>B<);>\n"
 732 msgstr ""
 733
 734 #. type: Plain text
 735 #: build/C/man2/get_robust_list.2:44
 736 msgid "I<Note>: There are no glibc wrappers for these system calls; see NOTES."
 737 msgstr ""
 738
 739 #. type: Plain text
 740 #: build/C/man2/get_robust_list.2:49
 741 msgid ""
 742 "The robust futex implementation needs to maintain per-thread lists of robust "
 743 "futexes which are unlocked when the thread exits.  These lists are managed "
 744 "in user space; the kernel is only notified about the location of the head of "
 745 "the list."
 746 msgstr ""
 747
 748 #. type: Plain text
 749 #: build/C/man2/get_robust_list.2:65
 750 msgid ""
 751 "The B<get_robust_list>()  system call returns the head of the robust futex "
 752 "list of the thread whose thread ID is specified in I<pid>.  If I<pid> is 0, "
 753 "the head of the list for the calling thread is returned.  The list head is "
 754 "stored in the location pointed to by I<head_ptr>.  The size of the object "
 755 "pointed to by I<**head_ptr> is stored in I<len_ptr>."
 756 msgstr ""
 757
 758 #. type: Plain text
 759 #: build/C/man2/get_robust_list.2:77
 760 msgid ""
 761 "The B<set_robust_list>()  system call requests the kernel to record the head "
 762 "of the list of robust futexes owned by the calling thread.  The I<head> "
 763 "argument is the list head to record.  The I<len> argument should be "
 764 "I<sizeof(*head)>."
 765 msgstr ""
 766
 767 #. type: Plain text
 768 #: build/C/man2/get_robust_list.2:84
 769 msgid ""
 770 "The B<set_robust_list>()  and B<get_robust_list>()  system calls return zero "
 771 "when the operation is successful, an error code otherwise."
 772 msgstr ""
 773
 774 #. type: Plain text
 775 #: build/C/man2/get_robust_list.2:88
 776 msgid "The B<set_robust_list>()  system call can fail with the following error:"
 777 msgstr ""
 778
 779 #. type: Plain text
 780 #: build/C/man2/get_robust_list.2:94
 781 msgid ""
 782 "I<len> does not match the size of structure B<struct robust_list_head> "
 783 "expected by kernel."
 784 msgstr ""
 785
 786 #. type: Plain text
 787 #: build/C/man2/get_robust_list.2:98
 788 msgid "The B<get_robust_list>()  system call can fail with the following errors:"
 789 msgstr ""
 790
 791 #. type: Plain text
 792 #: build/C/man2/get_robust_list.2:106
 793 msgid ""
 794 "The calling process does not have permission to see the robust futex list of "
 795 "the thread with the thread ID I<pid>, and does not have the "
 796 "B<CAP_SYS_PTRACE> capability."
 797 msgstr ""
 798
 799 #. type: TP
 800 #: build/C/man2/get_robust_list.2:106 build/C/man2/process_vm_readv.2:271 build/C/man2/ptrace.2:1765 build/C/man2/quotactl.2:461 build/C/man2/quotactl.2:504
 801 #, no-wrap
 802 msgid "B<ESRCH>"
 803 msgstr ""
 804
 805 #. type: Plain text
 806 #: build/C/man2/get_robust_list.2:111
 807 msgid "No thread with the thread ID I<pid> could be found."
 808 msgstr ""
 809
 810 #. type: Plain text
 811 #: build/C/man2/get_robust_list.2:115
 812 msgid "The head of the robust futex list can't be stored at the location I<head>."
 813 msgstr ""
 814
 815 #. type: Plain text
 816 #: build/C/man2/get_robust_list.2:119
 817 msgid ""
 818 "These system calls were added in Linux 2.6.17.  No library support is "
 819 "provided; use B<syscall>(2)."
 820 msgstr ""
 821
 822 #. type: Plain text
 823 #: build/C/man2/get_robust_list.2:124
 824 msgid ""
 825 "These system calls are not needed by normal applications.  No support for "
 826 "them is provided in glibc.  In the unlikely event that you want to call them "
 827 "directly, use B<syscall>(2)."
 828 msgstr ""
 829
 830 #. type: Plain text
 831 #: build/C/man2/get_robust_list.2:128
 832 msgid ""
 833 "A thread can have only one robust futex list; therefore applications that "
 834 "wish to use this functionality should use the robust mutexes provided by "
 835 "glibc."
 836 msgstr ""
 837
 838 #.  .BR pthread_mutexattr_setrobust_np (3)
 839 #. type: Plain text
 840 #: build/C/man2/get_robust_list.2:131
 841 msgid "B<futex>(2)"
 842 msgstr ""
 843
 844 #.  http://lwn.net/Articles/172149/
 845 #. type: Plain text
 846 #: build/C/man2/get_robust_list.2:137
 847 msgid ""
 848 "I<Documentation/robust-futexes.txt> and "
 849 "I<Documentation/robust-futex-ABI.txt> in the Linux kernel source tree"
 850 msgstr ""
 851
 852 #. type: TH
 853 #: build/C/man2/getunwind.2:27
 854 #, no-wrap
 855 msgid "GETUNWIND"
 856 msgstr ""
 857
 858 #. type: TH
 859 #: build/C/man2/getunwind.2:27 build/C/man2/perfmonctl.2:27
 860 #, no-wrap
 861 msgid "2013-02-13"
 862 msgstr ""
 863
 864 #. type: Plain text
 865 #: build/C/man2/getunwind.2:30
 866 msgid "getunwind - copy the unwind data to caller's buffer"
 867 msgstr ""
 868
 869 #. type: Plain text
 870 #: build/C/man2/getunwind.2:34
 871 #, no-wrap
 872 msgid ""
 873 "B<#include E<lt>syscall.hE<gt>>\n"
 874 "B<#include E<lt>linux/unwind.hE<gt>>\n"
 875 msgstr ""
 876
 877 #. type: Plain text
 878 #: build/C/man2/getunwind.2:36
 879 #, no-wrap
 880 msgid "B<long getunwind(void >I<*buf>B<, size_t >I<buf_size>B<);>\n"
 881 msgstr ""
 882
 883 #. type: Plain text
 884 #: build/C/man2/getunwind.2:40 build/C/man2/kexec_load.2:39 build/C/man2/modify_ldt.2:36 build/C/man2/perf_event_open.2:42 build/C/man2/perfmonctl.2:39 build/C/man2/pivot_root.2:18
 885 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
 886 msgstr ""
 887
 888 #. type: Plain text
 889 #: build/C/man2/getunwind.2:42
 890 msgid "I<Note: this function is obsolete.>"
 891 msgstr ""
 892
 893 #. type: Plain text
 894 #: build/C/man2/getunwind.2:52
 895 msgid ""
 896 "The IA-64-specific B<getunwind>()  system call copies the kernel's call "
 897 "frame unwind data into the buffer pointed to by I<buf> and returns the size "
 898 "of the unwind data; this data describes the gate page (kernel code that is "
 899 "mapped into user space)."
 900 msgstr ""
 901
 902 #. type: Plain text
 903 #: build/C/man2/getunwind.2:64
 904 msgid ""
 905 "The size of the buffer I<buf> is specified in I<buf_size>.  The data is "
 906 "copied only if I<buf_size> is greater than or equal to the size of the "
 907 "unwind data and I<buf> is not NULL; otherwise, no data is copied, and the "
 908 "call succeeds, returning the size that would be needed to store the unwind "
 909 "data."
 910 msgstr ""
 911
 912 #. type: Plain text
 913 #: build/C/man2/getunwind.2:68
 914 msgid ""
 915 "The first part of the unwind data contains an unwind table.  The rest "
 916 "contains the associated unwind information, in no particular order.  The "
 917 "unwind table contains entries of the following form:"
 918 msgstr ""
 919
 920 #. type: Plain text
 921 #: build/C/man2/getunwind.2:73
 922 #, no-wrap
 923 msgid ""
 924 "\tu64 start;      (64-bit address of start of function)\n"
 925 "\tu64 end;        (64-bit address of end of function)\n"
 926 "\tu64 info;       (BUF-relative offset to unwind info)\n"
 927 msgstr ""
 928
 929 #. type: Plain text
 930 #: build/C/man2/getunwind.2:81
 931 msgid ""
 932 "An entry whose I<start> value is zero indicates the end of the table.  For "
 933 "more information about the format, see the I<IA-64 Software Conventions and "
 934 "Runtime Architecture> manual."
 935 msgstr ""
 936
 937 #. type: Plain text
 938 #: build/C/man2/getunwind.2:88
 939 msgid ""
 940 "On success, B<getunwind>()  returns the size of unwind table.  On error, -1 "
 941 "is returned and I<errno> is set to indicate the error."
 942 msgstr ""
 943
 944 #. type: Plain text
 945 #: build/C/man2/getunwind.2:94
 946 msgid ""
 947 "B<getunwind>()  fails with the error B<EFAULT> if the unwind info can't be "
 948 "stored in the space specified by I<buf>."
 949 msgstr ""
 950
 951 #. type: Plain text
 952 #: build/C/man2/getunwind.2:96
 953 msgid "This system call is available since Linux 2.4."
 954 msgstr ""
 955
 956 #. type: Plain text
 957 #: build/C/man2/getunwind.2:99
 958 msgid ""
 959 "This system call is Linux specific, and is available only on the IA-64 "
 960 "architecture."
 961 msgstr ""
 962
 963 #. type: Plain text
 964 #: build/C/man2/getunwind.2:107
 965 msgid ""
 966 "This system call has been deprecated.  The modern way to obtain the kernel's "
 967 "unwind data is via the gate DSO.  The address of the ELF header for this DSO "
 968 "is passed to user level via B<AT_SYSINFO_EHDR> (see B<getauxval>(3))."
 969 msgstr ""
 970
 971 #. type: Plain text
 972 #: build/C/man2/getunwind.2:111
 973 msgid ""
 974 "Glibc does not provide a wrapper for this system call; in the unlikely event "
 975 "that you want to call it, use B<syscall>(2)."
 976 msgstr ""
 977
 978 #. type: Plain text
 979 #: build/C/man2/getunwind.2:113
 980 msgid "B<getauxval>(3)"
 981 msgstr ""
 982
 983 #. type: TH
 984 #: build/C/man2/kexec_load.2:26
 985 #, no-wrap
 986 msgid "KEXEC_LOAD"
 987 msgstr ""
 988
 989 #. type: Plain text
 990 #: build/C/man2/kexec_load.2:29
 991 msgid "kexec_load - load a new kernel for later execution"
 992 msgstr ""
 993
 994 #. type: Plain text
 995 #: build/C/man2/kexec_load.2:31
 996 msgid "B<#include E<lt>linux/kexec.hE<gt>>"
 997 msgstr ""
 998
 999 #. type: Plain text
1000 #: build/C/man2/kexec_load.2:33
1001 msgid ""
1002 "B<long kexec_load(unsigned long >I<entry>B<, unsigned long "
1003 ">I<nr_segments>B<,>"
1004 msgstr ""
1005
1006 #. type: Plain text
1007 #: build/C/man2/kexec_load.2:36
1008 msgid "B< struct kexec_segment *>I<segments>B<, unsigned long >I<flags>B<);>"
1009 msgstr ""
1010
1011 #. type: Plain text
1012 #: build/C/man2/kexec_load.2:44
1013 msgid ""
1014 "The B<kexec_load>()  system call loads a new kernel that can be executed "
1015 "later by B<reboot>(2)."
1016 msgstr ""
1017
1018 #. type: Plain text
1019 #: build/C/man2/kexec_load.2:50
1020 msgid ""
1021 "The I<flags> argument is a mask whose high-order bits control the operation "
1022 "of the call.  The following values can be specified in I<flags>:"
1023 msgstr ""
1024
1025 #. type: TP
1026 #: build/C/man2/kexec_load.2:50
1027 #, no-wrap
1028 msgid "B<KEXEC_ON_CRASH> (since Linux 2.6.13)"
1029 msgstr ""
1030
1031 #.  FIXME figure out how this is really used
1032 #. type: Plain text
1033 #: build/C/man2/kexec_load.2:54
1034 msgid "Execute the new kernel automatically on a system crash."
1035 msgstr ""
1036
1037 #. type: TP
1038 #: build/C/man2/kexec_load.2:54
1039 #, no-wrap
1040 msgid "B<KEXEC_PRESERVE_CONTEXT> (since Linux 2.6.27)"
1041 msgstr ""
1042
1043 #. type: Plain text
1044 #: build/C/man2/kexec_load.2:64
1045 msgid ""
1046 "Preserve the system hardware and software states before executing the new "
1047 "kernel.  This could be used for system suspend.  This flag is only available "
1048 "if the kernel was configured with B<CONFIG_KEXEC_JUMP>, and is only "
1049 "effective if I<nr_segments> is greater than 0."
1050 msgstr ""
1051
1052 #. type: Plain text
1053 #: build/C/man2/kexec_load.2:84
1054 msgid ""
1055 "The low-order bits of I<flags> contain the architecture of the "
1056 "to-be-executed kernel.  Specify (OR) the constant B<KEXEC_ARCH_DEFAULT> to "
1057 "use the current architecture, or one of the following architecture constants "
1058 "B<KEXEC_ARCH_386>, B<KEXEC_ARCH_X86_64>, B<KEXEC_ARCH_PPC>, "
1059 "B<KEXEC_ARCH_PPC64>, B<KEXEC_ARCH_IA_64>, B<KEXEC_ARCH_ARM>, "
1060 "B<KEXEC_ARCH_S390>, B<KEXEC_ARCH_SH>, B<KEXEC_ARCH_MIPS>, and "
1061 "B<KEXEC_ARCH_MIPS_LE>.  The architecture must be executable on the CPU of "
1062 "the system."
1063 msgstr ""
1064
1065 #. type: Plain text
1066 #: build/C/man2/kexec_load.2:98
1067 msgid ""
1068 "The I<entry> argument is the physical entry address in the kernel image.  "
1069 "The I<nr_segments> argument is the number of segments pointed to by the "
1070 "I<segments> pointer.  The I<segments> argument is an array of "
1071 "I<kexec_segment> structures which define the kernel layout:"
1072 msgstr ""
1073
1074 #. type: Plain text
1075 #: build/C/man2/kexec_load.2:107
1076 #, no-wrap
1077 msgid ""
1078 "struct kexec_segment {\n"
1079 "    void   *buf;        /* Buffer in user space */\n"
1080 "    size_t  bufsz;      /* Buffer length in user space */\n"
1081 "    void   *mem;        /* Physical address of kernel */\n"
1082 "    size_t  memsz;      /* Physical address length */\n"
1083 "};\n"
1084 msgstr ""
1085
1086 #.  FIXME elaborate on the following:
1087 #. type: Plain text
1088 #: build/C/man2/kexec_load.2:114
1089 msgid ""
1090 "The kernel image defined by I<segments> is copied from the calling process "
1091 "into previously reserved memory."
1092 msgstr ""
1093
1094 #. type: Plain text
1095 #: build/C/man2/kexec_load.2:121
1096 msgid ""
1097 "On success, B<kexec_load>()  returns 0.  On error, -1 is returned and "
1098 "I<errno> is set to indicate the error."
1099 msgstr ""
1100
1101 #. type: TP
1102 #: build/C/man2/kexec_load.2:122 build/C/man2/pivot_root.2:110 build/C/man2/ptrace.2:1728 build/C/man2/quotactl.2:495
1103 #, no-wrap
1104 msgid "B<EBUSY>"
1105 msgstr ""
1106
1107 #. type: Plain text
1108 #: build/C/man2/kexec_load.2:126
1109 msgid ""
1110 "Another crash kernel is already being loaded or a crash kernel is already in "
1111 "use."
1112 msgstr ""
1113
1114 #.  KEXEC_SEGMENT_MAX == 16
1115 #. type: Plain text
1116 #: build/C/man2/kexec_load.2:133
1117 msgid "I<flags> is invalid; or I<nr_segments> is too large"
1118 msgstr ""
1119
1120 #. type: Plain text
1121 #: build/C/man2/kexec_load.2:138
1122 msgid "The caller does not have the B<CAP_SYS_BOOT> capability."
1123 msgstr ""
1124
1125 #. type: Plain text
1126 #: build/C/man2/kexec_load.2:142
1127 msgid "The B<kexec_load>()  system call first appeared in Linux 2.6.13."
1128 msgstr ""
1129
1130 #. type: Plain text
1131 #: build/C/man2/kexec_load.2:149
1132 msgid ""
1133 "Currently, there is no glibc support for B<kexec_load>().  Call it using "
1134 "B<syscall>(2)."
1135 msgstr ""
1136
1137 #.  FIXME Andi submitted a patch for this.
1138 #.  Check if it got accepted later.
1139 #. type: Plain text
1140 #: build/C/man2/kexec_load.2:156
1141 msgid ""
1142 "The required constants are in the Linux kernel source file I<linux/kexec.h>, "
1143 "which is not currently exported to glibc.  Therefore, these constants must "
1144 "be defined manually."
1145 msgstr ""
1146
1147 #. type: Plain text
1148 #: build/C/man2/kexec_load.2:159
1149 msgid ""
1150 "This system call is only available if the kernel was configured with "
1151 "B<CONFIG_KEXEC>."
1152 msgstr ""
1153
1154 #. type: Plain text
1155 #: build/C/man2/kexec_load.2:162
1156 msgid "B<reboot>(2), B<syscall>(2)"
1157 msgstr ""
1158
1159 #. type: TH
1160 #: build/C/man2/lookup_dcookie.2:27
1161 #, no-wrap
1162 msgid "LOOKUP_DCOOKIE"
1163 msgstr ""
1164
1165 #. type: TH
1166 #: build/C/man2/lookup_dcookie.2:27
1167 #, no-wrap
1168 msgid "2004-06-17"
1169 msgstr ""
1170
1171 #. type: Plain text
1172 #: build/C/man2/lookup_dcookie.2:30
1173 msgid "lookup_dcookie - return a directory entry's path"
1174 msgstr ""
1175
1176 #. type: Plain text
1177 #: build/C/man2/lookup_dcookie.2:32
1178 msgid ""
1179 "B<int lookup_dcookie(u64 >I<cookie>B<, char *>I<buffer>B<, size_t "
1180 ">I<len>B<);>"
1181 msgstr ""
1182
1183 #. type: Plain text
1184 #: build/C/man2/lookup_dcookie.2:38
1185 msgid ""
1186 "Look up the full path of the directory entry specified by the value "
1187 "I<cookie>.  The cookie is an opaque identifier uniquely identifying a "
1188 "particular directory entry.  The buffer given is filled in with the full "
1189 "path of the directory entry."
1190 msgstr ""
1191
1192 #. type: Plain text
1193 #: build/C/man2/lookup_dcookie.2:43
1194 msgid ""
1195 "For B<lookup_dcookie>()  to return successfully, the kernel must still hold "
1196 "a cookie reference to the directory entry."
1197 msgstr ""
1198
1199 #. type: Plain text
1200 #: build/C/man2/lookup_dcookie.2:50
1201 msgid ""
1202 "On success, B<lookup_dcookie>()  returns the length of the path string "
1203 "copied into the buffer.  On error, -1 is returned, and I<errno> is set "
1204 "appropriately."
1205 msgstr ""
1206
1207 #. type: Plain text
1208 #: build/C/man2/lookup_dcookie.2:54
1209 msgid "The buffer was not valid."
1210 msgstr ""
1211
1212 #. type: Plain text
1213 #: build/C/man2/lookup_dcookie.2:58
1214 msgid ""
1215 "The kernel has no registered cookie/directory entry mappings at the time of "
1216 "lookup, or the cookie does not refer to a valid directory entry."
1217 msgstr ""
1218
1219 #. type: TP
1220 #: build/C/man2/lookup_dcookie.2:58
1221 #, no-wrap
1222 msgid "B<ENAMETOOLONG>"
1223 msgstr ""
1224
1225 #. type: Plain text
1226 #: build/C/man2/lookup_dcookie.2:61
1227 msgid "The name could not fit in the buffer."
1228 msgstr ""
1229
1230 #. type: TP
1231 #: build/C/man2/lookup_dcookie.2:61 build/C/man2/process_vm_readv.2:262 build/C/man2/sendfile.2:138 build/C/man2/splice.2:155 build/C/man2/tee.2:111 build/C/man2/vmsplice.2:135
1232 #, no-wrap
1233 msgid "B<ENOMEM>"
1234 msgstr ""
1235
1236 #. type: Plain text
1237 #: build/C/man2/lookup_dcookie.2:65
1238 msgid ""
1239 "The kernel could not allocate memory for the temporary buffer holding the "
1240 "path."
1241 msgstr ""
1242
1243 #. type: Plain text
1244 #: build/C/man2/lookup_dcookie.2:70
1245 msgid ""
1246 "The process does not have the capability B<CAP_SYS_ADMIN> required to look "
1247 "up cookie values."
1248 msgstr ""
1249
1250 #. type: TP
1251 #: build/C/man2/lookup_dcookie.2:70 build/C/man2/quotactl.2:474
1252 #, no-wrap
1253 msgid "B<ERANGE>"
1254 msgstr ""
1255
1256 #. type: Plain text
1257 #: build/C/man2/lookup_dcookie.2:73
1258 msgid "The buffer was not large enough to hold the path of the directory entry."
1259 msgstr ""
1260
1261 #. type: Plain text
1262 #: build/C/man2/lookup_dcookie.2:78
1263 msgid ""
1264 "Available since Linux 2.5.43.  The B<ENAMETOOLONG> error return was added in "
1265 "2.5.70."
1266 msgstr ""
1267
1268 #. type: Plain text
1269 #: build/C/man2/lookup_dcookie.2:81
1270 msgid "B<lookup_dcookie>()  is Linux-specific."
1271 msgstr ""
1272
1273 #. type: Plain text
1274 #: build/C/man2/lookup_dcookie.2:85
1275 msgid ""
1276 "B<lookup_dcookie>()  is a special-purpose system call, currently used only "
1277 "by the oprofile profiler.  It relies on a kernel driver to register cookies "
1278 "for directory entries."
1279 msgstr ""
1280
1281 #. type: Plain text
1282 #: build/C/man2/lookup_dcookie.2:88
1283 msgid ""
1284 "The path returned may be suffixed by the string \" (deleted)\" if the "
1285 "directory entry has been removed."
1286 msgstr ""
1287
1288 #. type: TH
1289 #: build/C/man2/modify_ldt.2:24
1290 #, no-wrap
1291 msgid "MODIFY_LDT"
1292 msgstr ""
1293
1294 #. type: Plain text
1295 #: build/C/man2/modify_ldt.2:27
1296 msgid "modify_ldt - get or set ldt"
1297 msgstr ""
1298
1299 #. type: Plain text
1300 #: build/C/man2/modify_ldt.2:30
1301 #, no-wrap
1302 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
1303 msgstr ""
1304
1305 #. type: Plain text
1306 #: build/C/man2/modify_ldt.2:32
1307 #, no-wrap
1308 msgid ""
1309 "B<int modify_ldt(int >I<func>B<, void *>I<ptr>B<, unsigned long "
1310 ">I<bytecount>B<);>\n"
1311 msgstr ""
1312
1313 #. type: Plain text
1314 #: build/C/man2/modify_ldt.2:41
1315 msgid ""
1316 "B<modify_ldt>()  reads or writes the local descriptor table (ldt) for a "
1317 "process.  The ldt is a per-process memory management table used by the i386 "
1318 "processor.  For more information on this table, see an Intel 386 processor "
1319 "handbook."
1320 msgstr ""
1321
1322 #. type: Plain text
1323 #: build/C/man2/modify_ldt.2:51
1324 msgid ""
1325 "When I<func> is 0, B<modify_ldt>()  reads the ldt into the memory pointed to "
1326 "by I<ptr>.  The number of bytes read is the smaller of I<bytecount> and the "
1327 "actual size of the ldt."
1328 msgstr ""
1329
1330 #
1331 #.  FIXME ? say something about func == 2 and func == 0x11?
1332 #.  In Linux 2.4, func == 2 returned "the default ldt"
1333 #.  In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
1334 #.  Linux 2.4 and 2.6 implement an operation for func == 0x11
1335 #. type: Plain text
1336 #: build/C/man2/modify_ldt.2:69
1337 msgid ""
1338 "When I<func> is 1, B<modify_ldt>()  modifies one ldt entry.  I<ptr> points "
1339 "to a I<user_desc> structure and I<bytecount> must equal the size of this "
1340 "structure."
1341 msgstr ""
1342
1343 #. type: Plain text
1344 #: build/C/man2/modify_ldt.2:73
1345 msgid "The I<user_desc> structure is defined in I<E<lt>asm/ldt.hE<gt>> as:"
1346 msgstr ""
1347
1348 #. type: Plain text
1349 #: build/C/man2/modify_ldt.2:87
1350 #, no-wrap
1351 msgid ""
1352 "struct user_desc {\n"
1353 "    unsigned int  entry_number;\n"
1354 "    unsigned long base_addr;\n"
1355 "    unsigned int  limit;\n"
1356 "    unsigned int  seg_32bit:1;\n"
1357 "    unsigned int  contents:2;\n"
1358 "    unsigned int  read_exec_only:1;\n"
1359 "    unsigned int  limit_in_pages:1;\n"
1360 "    unsigned int  seg_not_present:1;\n"
1361 "    unsigned int  useable:1;\n"
1362 "};\n"
1363 msgstr ""
1364
1365 #.  .PP
1366 #.  The ldt is specific for the calling process. Any attempts to change
1367 #.  the ldt to include the address space of another process or the kernel
1368 #.  will result in a segmentation violation when trying to access the memory
1369 #.  outside of the process address space. The memory protection is enforced
1370 #.  at the paging layer.
1371 #. type: Plain text
1372 #: build/C/man2/modify_ldt.2:98
1373 msgid "In Linux 2.4 and earlier, this structure was named I<modify_ldt_ldt_s>."
1374 msgstr ""
1375
1376 #. type: Plain text
1377 #: build/C/man2/modify_ldt.2:108
1378 msgid ""
1379 "On success, B<modify_ldt>()  returns either the actual number of bytes read "
1380 "(for reading)  or 0 (for writing).  On failure, B<modify_ldt>()  returns -1 "
1381 "and sets I<errno> to indicate the error."
1382 msgstr ""
1383
1384 #. type: Plain text
1385 #: build/C/man2/modify_ldt.2:113
1386 msgid "I<ptr> points outside the address space."
1387 msgstr ""
1388
1389 #. type: Plain text
1390 #: build/C/man2/modify_ldt.2:126
1391 msgid ""
1392 "I<ptr> is 0, or I<func> is 1 and I<bytecount> is not equal to the size of "
1393 "the structure I<modify_ldt_ldt_s>, or I<func> is 1 and the new ldt entry has "
1394 "invalid values."
1395 msgstr ""
1396
1397 #. type: Plain text
1398 #: build/C/man2/modify_ldt.2:130
1399 msgid "I<func> is neither 0 nor 1."
1400 msgstr ""
1401
1402 #. type: Plain text
1403 #: build/C/man2/modify_ldt.2:133
1404 msgid ""
1405 "This call is Linux-specific and should not be used in programs intended to "
1406 "be portable."
1407 msgstr ""
1408
1409 #. type: Plain text
1410 #: build/C/man2/modify_ldt.2:136 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:134
1411 msgid ""
1412 "Glibc does not provide a wrapper for this system call; call it using "
1413 "B<syscall>(2)."
1414 msgstr ""
1415
1416 #. type: Plain text
1417 #: build/C/man2/modify_ldt.2:138
1418 msgid "B<vm86>(2)"
1419 msgstr ""
1420
1421 #. type: TH
1422 #: build/C/man2/nfsservctl.2:8
1423 #, no-wrap
1424 msgid "NFSSERVCTL"
1425 msgstr ""
1426
1427 #. type: TH
1428 #: build/C/man2/nfsservctl.2:8
1429 #, no-wrap
1430 msgid "2012-03-05"
1431 msgstr ""
1432
1433 #. type: Plain text
1434 #: build/C/man2/nfsservctl.2:11
1435 msgid "nfsservctl - syscall interface to kernel nfs daemon"
1436 msgstr ""
1437
1438 #. type: Plain text
1439 #: build/C/man2/nfsservctl.2:14
1440 #, no-wrap
1441 msgid "B<#include E<lt>linux/nfsd/syscall.hE<gt>>\n"
1442 msgstr ""
1443
1444 #. type: Plain text
1445 #: build/C/man2/nfsservctl.2:17
1446 #, no-wrap
1447 msgid ""
1448 "B<long nfsservctl(int >I<cmd>B<, struct nfsctl_arg *>I<argp>B<,>\n"
1449 "B<                union nfsctl_res *>I<resp>B<);>\n"
1450 msgstr ""
1451
1452 #. type: Plain text
1453 #: build/C/man2/nfsservctl.2:21
1454 msgid "I<Note>: Since Linux 3.1, this system call no longer exists."
1455 msgstr ""
1456
1457 #. type: Plain text
1458 #: build/C/man2/nfsservctl.2:33
1459 #, no-wrap
1460 msgid ""
1461 "/*\n"
1462 " * These are the commands understood by nfsctl().\n"
1463 " */\n"
1464 "#define NFSCTL_SVC          0    /* This is a server process. */\n"
1465 "#define NFSCTL_ADDCLIENT    1    /* Add an NFS client. */\n"
1466 "#define NFSCTL_DELCLIENT    2    /* Remove an NFS client. */\n"
1467 "#define NFSCTL_EXPORT       3    /* export a file system. */\n"
1468 "#define NFSCTL_UNEXPORT     4    /* unexport a file system. */\n"
1469 "#define NFSCTL_UGIDUPDATE   5    /* update a client's UID/GID map. */\n"
1470 "#define NFSCTL_GETFH        6    /* get an fh (used by mountd) */\n"
1471 msgstr ""
1472
1473 #. type: Plain text
1474 #: build/C/man2/nfsservctl.2:45
1475 #, no-wrap
1476 msgid ""
1477 "struct nfsctl_arg {\n"
1478 "    int                       ca_version;     /* safeguard */\n"
1479 "    union {\n"
1480 "        struct nfsctl_svc     u_svc;\n"
1481 "        struct nfsctl_client  u_client;\n"
1482 "        struct nfsctl_export  u_export;\n"
1483 "        struct nfsctl_uidmap  u_umap;\n"
1484 "        struct nfsctl_fhparm  u_getfh;\n"
1485 "        unsigned int          u_debug;\n"
1486 "    } u;\n"
1487 "}\n"
1488 msgstr ""
1489
1490 #. type: Plain text
1491 #: build/C/man2/nfsservctl.2:50
1492 #, no-wrap
1493 msgid ""
1494 "union nfsctl_res {\n"
1495 "        struct knfs_fh          cr_getfh;\n"
1496 "        unsigned int            cr_debug;\n"
1497 "};\n"
1498 msgstr ""
1499
1500 #. type: Plain text
1501 #: build/C/man2/nfsservctl.2:56 build/C/man2/pivot_root.2:105 build/C/man2/vm86.2:57
1502 msgid ""
1503 "On success, zero is returned.  On error, -1 is returned, and I<errno> is set "
1504 "appropriately."
1505 msgstr ""
1506
1507 #. type: Plain text
1508 #: build/C/man2/nfsservctl.2:58
1509 msgid "This call is Linux-specific."
1510 msgstr ""
1511
1512 #. type: TH
1513 #: build/C/man2/outb.2:26
1514 #, no-wrap
1515 msgid "OUTB"
1516 msgstr ""
1517
1518 #. type: TH
1519 #: build/C/man2/outb.2:26
1520 #, no-wrap
1521 msgid "2012-12-31"
1522 msgstr ""
1523
1524 #. type: Plain text
1525 #: build/C/man2/outb.2:31
1526 msgid ""
1527 "outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, "
1528 "outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O"
1529 msgstr ""
1530
1531 #. type: Plain text
1532 #: build/C/man2/outb.2:34
1533 #, no-wrap
1534 msgid "B<#include E<lt>sys/io.hE<gt>>\n"
1535 msgstr ""
1536
1537 #. type: Plain text
1538 #: build/C/man2/outb.2:41
1539 #, no-wrap
1540 msgid ""
1541 "B<unsigned char inb(unsigned short int >I<port>B<);>\n"
1542 "B<unsigned char inb_p(unsigned short int >I<port>B<);>\n"
1543 "B<unsigned short int inw(unsigned short int >I<port>B<);>\n"
1544 "B<unsigned short int inw_p(unsigned short int >I<port>B<);>\n"
1545 "B<unsigned int inl(unsigned short int >I<port>B<);>\n"
1546 "B<unsigned int inl_p(unsigned short int >I<port>B<);>\n"
1547 msgstr ""
1548
1549 #. type: Plain text
1550 #: build/C/man2/outb.2:48
1551 #, no-wrap
1552 msgid ""
1553 "B<void outb(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1554 "B<void outb_p(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1555 "B<void outw(unsigned short int >I<value>B<, unsigned short int "
1556 ">I<port>B<);>\n"
1557 "B<void outw_p(unsigned short int >I<value>B<, unsigned short int "
1558 ">I<port>B<);>\n"
1559 "B<void outl(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1560 "B<void outl_p(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1561 msgstr ""
1562
1563 #. type: Plain text
1564 #: build/C/man2/outb.2:61
1565 #, no-wrap
1566 msgid ""
1567 "B<void insb(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1568 "B<           unsigned long int >I<count>B<);>\n"
1569 "B<void insw(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1570 "B<           unsigned long int >I<count>B<);>\n"
1571 "B<void insl(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1572 "B<           unsigned long int >I<count>B<);>\n"
1573 "B<void outsb(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1574 "B<           unsigned long int >I<count>B<);>\n"
1575 "B<void outsw(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1576 "B<           unsigned long int >I<count>B<);>\n"
1577 "B<void outsl(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1578 "B<           unsigned long int >I<count>B<);>\n"
1579 msgstr ""
1580
1581 #. type: Plain text
1582 #: build/C/man2/outb.2:67
1583 msgid ""
1584 "This family of functions is used to do low-level port input and output.  The "
1585 "out* functions do port output, the in* functions do port input; the b-suffix "
1586 "functions are byte-width and the w-suffix functions word-width; the "
1587 "_p-suffix functions pause until the I/O completes."
1588 msgstr ""
1589
1590 #.  , given the following information
1591 #.  in addition to that given in
1592 #.  .BR outb (9).
1593 #. type: Plain text
1594 #: build/C/man2/outb.2:73
1595 msgid ""
1596 "They are primarily designed for internal kernel use, but can be used from "
1597 "user space."
1598 msgstr ""
1599
1600 #. type: Plain text
1601 #: build/C/man2/outb.2:78
1602 msgid ""
1603 "You must compile with B<-O> or B<-O2> or similar.  The functions are defined "
1604 "as inline macros, and will not be substituted in without optimization "
1605 "enabled, causing unresolved references at link time."
1606 msgstr ""
1607
1608 #. type: Plain text
1609 #: build/C/man2/outb.2:87
1610 msgid ""
1611 "You use B<ioperm>(2)  or alternatively B<iopl>(2)  to tell the kernel to "
1612 "allow the user space application to access the I/O ports in question.  "
1613 "Failure to do this will cause the application to receive a segmentation "
1614 "fault."
1615 msgstr ""
1616
1617 #. type: Plain text
1618 #: build/C/man2/outb.2:96
1619 msgid ""
1620 "B<outb>()  and friends are hardware-specific.  The I<value> argument is "
1621 "passed first and the I<port> argument is passed second, which is the "
1622 "opposite order from most DOS implementations."
1623 msgstr ""
1624
1625 #. type: Plain text
1626 #: build/C/man2/outb.2:99
1627 msgid "B<ioperm>(2), B<iopl>(2)"
1628 msgstr ""
1629
1630 #. type: TH
1631 #: build/C/man2/pciconfig_read.2:8
1632 #, no-wrap
1633 msgid "PCICONFIG_READ"
1634 msgstr ""
1635
1636 #. type: TH
1637 #: build/C/man2/pciconfig_read.2:8
1638 #, no-wrap
1639 msgid "2003-07-14"
1640 msgstr ""
1641
1642 #. type: Plain text
1643 #: build/C/man2/pciconfig_read.2:11
1644 msgid ""
1645 "pciconfig_read, pciconfig_write, pciconfig_iobase - pci device information "
1646 "handling"
1647 msgstr ""
1648
1649 #. type: Plain text
1650 #: build/C/man2/pciconfig_read.2:14
1651 #, no-wrap
1652 msgid "B<#include E<lt>pci.hE<gt>>\n"
1653 msgstr ""
1654
1655 #. type: Plain text
1656 #: build/C/man2/pciconfig_read.2:21
1657 #, no-wrap
1658 msgid ""
1659 "B<int pciconfig_read(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1660 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1661 "*>I<buf>B<);>\n"
1662 "B<int pciconfig_write(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1663 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1664 "*>I<buf>B<);>\n"
1665 "B<int pciconfig_iobase(long >I<which>B<, unsigned long >I<bus>B<,>\n"
1666 "B<          unsigned long >I<devfn>B<);>\n"
1667 msgstr ""
1668
1669 #. type: Plain text
1670 #: build/C/man2/pciconfig_read.2:27
1671 msgid ""
1672 "Most of the interaction with PCI devices is already handled by the kernel "
1673 "PCI layer, and thus these calls should not normally need to be accessed from "
1674 "user space."
1675 msgstr ""
1676
1677 #. type: TP
1678 #: build/C/man2/pciconfig_read.2:27 build/C/man2/pciconfig_read.2:51
1679 #, no-wrap
1680 msgid "B<pciconfig_read>()"
1681 msgstr ""
1682
1683 #. type: Plain text
1684 #: build/C/man2/pciconfig_read.2:36
1685 msgid "Reads to I<buf> from device I<dev> at offset I<off> value."
1686 msgstr ""
1687
1688 #. type: TP
1689 #: build/C/man2/pciconfig_read.2:36 build/C/man2/pciconfig_read.2:57
1690 #, no-wrap
1691 msgid "B<pciconfig_write>()"
1692 msgstr ""
1693
1694 #. type: Plain text
1695 #: build/C/man2/pciconfig_read.2:45
1696 msgid "Writes from I<buf> to device I<dev> at offset I<off> value."
1697 msgstr ""
1698
1699 #. type: TP
1700 #: build/C/man2/pciconfig_read.2:45 build/C/man2/pciconfig_read.2:63
1701 #, no-wrap
1702 msgid "B<pciconfig_iobase>()"
1703 msgstr ""
1704
1705 #. type: Plain text
1706 #: build/C/man2/pciconfig_read.2:50
1707 msgid ""
1708 "You pass it a bus/devfn pair and get a physical address for either the "
1709 "memory offset (for things like prep, this is 0xc0000000), the IO base for "
1710 "PIO cycles, or the ISA holes if any."
1711 msgstr ""
1712
1713 #. type: Plain text
1714 #: build/C/man2/pciconfig_read.2:57 build/C/man2/pciconfig_read.2:63
1715 msgid ""
1716 "On success zero is returned.  On error, -1 is returned and I<errno> is set "
1717 "appropriately."
1718 msgstr ""
1719
1720 #. type: Plain text
1721 #: build/C/man2/pciconfig_read.2:77
1722 msgid ""
1723 "Returns information on locations of various I/O regions in physical memory "
1724 "according to the I<which> value.  Values for I<which> are: "
1725 "B<IOBASE_BRIDGE_NUMBER>, B<IOBASE_MEMORY>, B<IOBASE_IO>, B<IOBASE_ISA_IO>, "
1726 "B<IOBASE_ISA_MEM>."
1727 msgstr ""
1728
1729 #. type: Plain text
1730 #: build/C/man2/pciconfig_read.2:84
1731 msgid "I<len> value is invalid.  This does not apply to B<pciconfig_iobase>()."
1732 msgstr ""
1733
1734 #. type: TP
1735 #: build/C/man2/pciconfig_read.2:84 build/C/man2/ptrace.2:1745 build/C/man2/sendfile.2:134
1736 #, no-wrap
1737 msgid "B<EIO>"
1738 msgstr ""
1739
1740 #. type: Plain text
1741 #: build/C/man2/pciconfig_read.2:87
1742 msgid "I/O error."
1743 msgstr ""
1744
1745 #. type: TP
1746 #: build/C/man2/pciconfig_read.2:87
1747 #, no-wrap
1748 msgid "B<ENODEV>"
1749 msgstr ""
1750
1751 #. type: Plain text
1752 #: build/C/man2/pciconfig_read.2:93
1753 msgid ""
1754 "For B<pciconfig_iobase>(), \"hose\" value is NULL.  For the other calls, "
1755 "could not find a slot."
1756 msgstr ""
1757
1758 #. type: Plain text
1759 #: build/C/man2/pciconfig_read.2:98
1760 msgid "The system has not implemented these calls (B<CONFIG_PCI> not defined)."
1761 msgstr ""
1762
1763 #. type: TP
1764 #: build/C/man2/pciconfig_read.2:98
1765 #, no-wrap
1766 msgid "B<EOPNOTSUPP>"
1767 msgstr ""
1768
1769 #. type: Plain text
1770 #: build/C/man2/pciconfig_read.2:105
1771 msgid ""
1772 "This return value is only valid for B<pciconfig_iobase>().  It is returned "
1773 "if the value for I<which> is invalid."
1774 msgstr ""
1775
1776 #. type: Plain text
1777 #: build/C/man2/pciconfig_read.2:110
1778 msgid ""
1779 "User does not have the B<CAP_SYS_ADMIN> capability.  This does not apply to "
1780 "B<pciconfig_iobase>()."
1781 msgstr ""
1782
1783 #. type: Plain text
1784 #: build/C/man2/pciconfig_read.2:112
1785 msgid "These calls are Linux-specific, available since Linux 2.0.26/2.1.11."
1786 msgstr ""
1787
1788 #. type: Plain text
1789 #: build/C/man2/pciconfig_read.2:114
1790 msgid "B<capabilities>(7)"
1791 msgstr ""
1792
1793 #. type: TH
1794 #: build/C/man2/perf_event_open.2:27
1795 #, no-wrap
1796 msgid "PERF_EVENT_OPEN"
1797 msgstr ""
1798
1799 #. type: TH
1800 #: build/C/man2/perf_event_open.2:27
1801 #, no-wrap
1802 msgid "2013-02-04"
1803 msgstr ""
1804
1805 #. type: Plain text
1806 #: build/C/man2/perf_event_open.2:30
1807 msgid "perf_event_open - set up performance monitoring"
1808 msgstr ""
1809
1810 #. type: Plain text
1811 #: build/C/man2/perf_event_open.2:34
1812 #, no-wrap
1813 msgid ""
1814 "B<#include E<lt>linux/perf_event.hE<gt>>\n"
1815 "B<#include E<lt>linux/hw_breakpoint.hE<gt>>\n"
1816 msgstr ""
1817
1818 #. type: Plain text
1819 #: build/C/man2/perf_event_open.2:38
1820 #, no-wrap
1821 msgid ""
1822 "B<int perf_event_open(struct perf_event_attr *>I<attr>B<,>\n"
1823 "B<                    pid_t >I<pid>B<, int >I<cpu>B<, int >I<group_fd>B<,>\n"
1824 "B<                    unsigned long >I<flags>B<);>\n"
1825 msgstr ""
1826
1827 #. type: Plain text
1828 #: build/C/man2/perf_event_open.2:47
1829 msgid ""
1830 "Given a list of parameters, B<perf_event_open>()  returns a file descriptor, "
1831 "for use in subsequent system calls (B<read>(2), B<mmap>(2), B<prctl>(2), "
1832 "B<fcntl>(2), etc.)."
1833 msgstr ""
1834
1835 #. type: Plain text
1836 #: build/C/man2/perf_event_open.2:55
1837 msgid ""
1838 "A call to B<perf_event_open>()  creates a file descriptor that allows "
1839 "measuring performance information.  Each file descriptor corresponds to one "
1840 "event that is measured; these can be grouped together to measure multiple "
1841 "events simultaneously."
1842 msgstr ""
1843
1844 #. type: Plain text
1845 #: build/C/man2/perf_event_open.2:62
1846 msgid ""
1847 "Events can be enabled and disabled in two ways: via B<ioctl>(2)  and via "
1848 "B<prctl>(2)B<.> When an event is disabled it does not count or generate "
1849 "overflows but does continue to exist and maintain its count value."
1850 msgstr ""
1851
1852 #. type: Plain text
1853 #: build/C/man2/perf_event_open.2:76
1854 msgid ""
1855 "Events come in two flavors: counting and sampled.  A I<counting> event is "
1856 "one that is used for counting the aggregate number of events that occur.  In "
1857 "general, counting event results are gathered with a B<read>(2)  call.  A "
1858 "I<sampling> event periodically writes measurements to a buffer that can then "
1859 "be accessed via B<mmap>(2)B<.>"
1860 msgstr ""
1861
1862 #. type: SS
1863 #: build/C/man2/perf_event_open.2:76
1864 #, no-wrap
1865 msgid "Arguments"
1866 msgstr ""
1867
1868 #. type: Plain text
1869 #: build/C/man2/perf_event_open.2:90
1870 msgid ""
1871 "The argument I<pid> allows events to be attached to processes in various "
1872 "ways.  If I<pid> is 0, measurements happen on the current thread, if I<pid> "
1873 "is greater than 0, the process indicated by I<pid> is measured, and if "
1874 "I<pid> is -1, all processes are counted."
1875 msgstr ""
1876
1877 #. type: Plain text
1878 #: build/C/man2/perf_event_open.2:101
1879 msgid ""
1880 "The I<cpu> argument allows measurements to be specific to a CPU.  If I<cpu> "
1881 "is greater than or equal to 0, measurements are restricted to the specified "
1882 "CPU; if I<cpu> is -1, the events are measured on all CPUs."
1883 msgstr ""
1884
1885 #. type: Plain text
1886 #: build/C/man2/perf_event_open.2:107
1887 msgid "Note that the combination of I<pid> == -1 and I<cpu> == -1 is not valid."
1888 msgstr ""
1889
1890 #. type: Plain text
1891 #: build/C/man2/perf_event_open.2:115
1892 msgid ""
1893 "A I<pid> E<gt> 0 and I<cpu> == -1 setting measures per-process and follows "
1894 "that process to whatever CPU the process gets scheduled to.  Per-process "
1895 "events can be created by any user."
1896 msgstr ""
1897
1898 #. type: Plain text
1899 #: build/C/man2/perf_event_open.2:126
1900 msgid ""
1901 "A I<pid> == -1 and I<cpu> E<gt>= 0 setting is per-CPU and measures all "
1902 "processes on the specified CPU.  Per-CPU events need the B<CAP_SYS_ADMIN> "
1903 "capability or a I</proc/sys/kernel/perf_event_paranoid> value of less than "
1904 "1."
1905 msgstr ""
1906
1907 #. type: Plain text
1908 #: build/C/man2/perf_event_open.2:148
1909 msgid ""
1910 "The I<group_fd> argument allows event groups to be created.  An event group "
1911 "has one event which is the group leader.  The leader is created first, with "
1912 "I<group_fd> = -1.  The rest of the group members are created with subsequent "
1913 "B<perf_event_open>()  calls with I<group_fd> being set to the fd of the "
1914 "group leader.  (A single event on its own is created with I<group_fd> = -1 "
1915 "and is considered to be a group with only 1 member.)  An event group is "
1916 "scheduled onto the CPU as a unit: it will only be put onto the CPU if all of "
1917 "the events in the group can be put onto the CPU.  This means that the values "
1918 "of the member events can be meaningfully compared, added, divided (to get "
1919 "ratios), etc., with each other, since they have counted events for the same "
1920 "set of executed instructions."
1921 msgstr ""
1922
1923 #. type: Plain text
1924 #: build/C/man2/perf_event_open.2:152
1925 msgid "The I<flags> argument takes one of the following values:"
1926 msgstr ""
1927
1928 #. type: TP
1929 #: build/C/man2/perf_event_open.2:152
1930 #, no-wrap
1931 msgid "B<PERF_FLAG_FD_NO_GROUP>"
1932 msgstr ""
1933
1934 #.  FIXME The following sentence is unclear
1935 #.  FIXME So, why is it useful?
1936 #. type: Plain text
1937 #: build/C/man2/perf_event_open.2:159
1938 msgid ""
1939 "This flag allows creating an event as part of an event group but having no "
1940 "group leader.  It is unclear why this is useful."
1941 msgstr ""
1942
1943 #. type: TP
1944 #: build/C/man2/perf_event_open.2:159
1945 #, no-wrap
1946 msgid "B<PERF_FLAG_FD_OUTPUT>"
1947 msgstr ""
1948
1949 #. type: Plain text
1950 #: build/C/man2/perf_event_open.2:162
1951 msgid "This flag re-routes the output from an event to the group leader."
1952 msgstr ""
1953
1954 #. type: TP
1955 #: build/C/man2/perf_event_open.2:162
1956 #, no-wrap
1957 msgid "B<PERF_FLAG_PID_CGROUP> (Since Linux 2.6.39)."
1958 msgstr ""
1959
1960 #. type: Plain text
1961 #: build/C/man2/perf_event_open.2:185
1962 msgid ""
1963 "This flag activates per-container system-wide monitoring.  A container is an "
1964 "abstraction that isolates a set of resources for finer grain control (CPUs, "
1965 "memory, etc...).  In this mode, the event is measured only if the thread "
1966 "running on the monitored CPU belongs to the designated container (cgroup).  "
1967 "The cgroup is identified by passing a file descriptor opened on its "
1968 "directory in the cgroupfs filesystem.  For instance, if the cgroup to "
1969 "monitor is called I<test>, then a file descriptor opened on "
1970 "I</dev/cgroup/test> (assuming cgroupfs is mounted on I</dev/cgroup>)  must "
1971 "be passed as the I<pid> parameter.  cgroup monitoring is only available for "
1972 "system-wide events and may therefore require extra permissions."
1973 msgstr ""
1974
1975 #. type: Plain text
1976 #: build/C/man2/perf_event_open.2:190
1977 msgid ""
1978 "The I<perf_event_attr> structure provides detailed configuration information "
1979 "for the event being created."
1980 msgstr ""
1981
1982 #. type: Plain text
1983 #: build/C/man2/perf_event_open.2:197
1984 #, no-wrap
1985 msgid ""
1986 "struct perf_event_attr {\n"
1987 "    __u32     type;         /* Type of event */\n"
1988 "    __u32     size;         /* Size of attribute structure */\n"
1989 "    __u64     config;       /* Type-specific configuration */\n"
1990 msgstr ""
1991
1992 #. type: Plain text
1993 #: build/C/man2/perf_event_open.2:202
1994 #, no-wrap
1995 msgid ""
1996 "    union {\n"
1997 "        __u64 sample_period;    /* Period of sampling */\n"
1998 "        __u64 sample_freq;      /* Frequency of sampling */\n"
1999 "    };\n"
2000 msgstr ""
2001
2002 #. type: Plain text
2003 #: build/C/man2/perf_event_open.2:205
2004 #, no-wrap
2005 msgid ""
2006 "    __u64     sample_type;  /* Specifies values included in sample */\n"
2007 "    __u64     read_format;  /* Specifies values returned in read */\n"
2008 msgstr ""
2009
2010 #. type: Plain text
2011 #: build/C/man2/perf_event_open.2:231
2012 #, no-wrap
2013 msgid ""
2014 "    __u64     disabled       : 1,   /* off by default */\n"
2015 "              inherit        : 1,   /* children inherit it */\n"
2016 "              pinned         : 1,   /* must always be on PMU */\n"
2017 "              exclusive      : 1,   /* only group on PMU */\n"
2018 "              exclude_user   : 1,   /* don't count user */\n"
2019 "              exclude_kernel : 1,   /* don't count kernel */\n"
2020 "              exclude_hv     : 1,   /* don't count hypervisor */\n"
2021 "              exclude_idle   : 1,   /* don't count when idle */\n"
2022 "              mmap           : 1,   /* include mmap data */\n"
2023 "              comm           : 1,   /* include comm data */\n"
2024 "              freq           : 1,   /* use freq, not period */\n"
2025 "              inherit_stat   : 1,   /* per task counts */\n"
2026 "              enable_on_exec : 1,   /* next exec enables */\n"
2027 "              task           : 1,   /* trace fork/exit */\n"
2028 "              watermark      : 1,   /* wakeup_watermark */\n"
2029 "              precise_ip     : 2,   /* skid constraint */\n"
2030 "              mmap_data      : 1,   /* non-exec mmap data */\n"
2031 "              sample_id_all  : 1,   /* sample_type all events */\n"
2032 "              exclude_host   : 1,   /* don't count in host */\n"
2033 "              exclude_guest  : 1,   /* don't count in guest */\n"
2034 "              exclude_callchain_kernel : 1,\n"
2035 "                                    /* exclude kernel callchains */\n"
2036 "              exclude_callchain_user   : 1,\n"
2037 "\t                            /* exclude user callchains */\n"
2038 "              __reserved_1   : 41;\n"
2039 msgstr ""
2040
2041 #. type: Plain text
2042 #: build/C/man2/perf_event_open.2:236
2043 #, no-wrap
2044 msgid ""
2045 "    union {\n"
2046 "        __u32 wakeup_events;    /* wakeup every n events */\n"
2047 "        __u32 wakeup_watermark; /* bytes before wakeup */\n"
2048 "    };\n"
2049 msgstr ""
2050
2051 #. type: Plain text
2052 #: build/C/man2/perf_event_open.2:238
2053 #, no-wrap
2054 msgid "    __u32     bp_type;          /* breakpoint type */\n"
2055 msgstr ""
2056
2057 #. type: Plain text
2058 #: build/C/man2/perf_event_open.2:243
2059 #, no-wrap
2060 msgid ""
2061 "    union {\n"
2062 "        __u64 bp_addr;          /* breakpoint address */\n"
2063 "        __u64 config1;          /* extension of config */\n"
2064 "    };\n"
2065 msgstr ""
2066
2067 #. type: Plain text
2068 #: build/C/man2/perf_event_open.2:253
2069 #, no-wrap
2070 msgid ""
2071 "    union {\n"
2072 "        __u64 bp_len;           /* breakpoint length */\n"
2073 "        __u64 config2;          /* extension of config1 */\n"
2074 "    };\n"
2075 "    __u64   branch_sample_type; /* enum perf_branch_sample_type */\n"
2076 "    __u64   sample_regs_user;   /* user regs to dump on samples */\n"
2077 "    __u32   sample_stack_user;  /* size of stack to dump on\n"
2078 "                                   samples */\n"
2079 "    __u32   __reserved_2;       /* Align to u64 */\n"
2080 msgstr ""
2081
2082 #. type: Plain text
2083 #: build/C/man2/perf_event_open.2:255
2084 #, no-wrap
2085 msgid "};\n"
2086 msgstr ""
2087
2088 #. type: Plain text
2089 #: build/C/man2/perf_event_open.2:261
2090 msgid ""
2091 "The fields of the I<perf_event_attr> structure are described in more detail "
2092 "below:"
2093 msgstr ""
2094
2095 #. type: TP
2096 #: build/C/man2/perf_event_open.2:261 build/C/man2/perf_event_open.2:1272
2097 #, no-wrap
2098 msgid "I<type>"
2099 msgstr ""
2100
2101 #. type: Plain text
2102 #: build/C/man2/perf_event_open.2:265
2103 msgid ""
2104 "This field specifies the overall event type.  It has one of the following "
2105 "values:"
2106 msgstr ""
2107
2108 #. type: TP
2109 #: build/C/man2/perf_event_open.2:266
2110 #, no-wrap
2111 msgid "B<PERF_TYPE_HARDWARE>"
2112 msgstr ""
2113
2114 #. type: Plain text
2115 #: build/C/man2/perf_event_open.2:273
2116 msgid ""
2117 "This indicates one of the \"generalized\" hardware events provided by the "
2118 "kernel.  See the I<config> field definition for more details."
2119 msgstr ""
2120
2121 #. type: TP
2122 #: build/C/man2/perf_event_open.2:273
2123 #, no-wrap
2124 msgid "B<PERF_TYPE_SOFTWARE>"
2125 msgstr ""
2126
2127 #. type: Plain text
2128 #: build/C/man2/perf_event_open.2:277
2129 msgid ""
2130 "This indicates one of the software-defined events provided by the kernel "
2131 "(even if no hardware support is available)."
2132 msgstr ""
2133
2134 #. type: TP
2135 #: build/C/man2/perf_event_open.2:277
2136 #, no-wrap
2137 msgid "B<PERF_TYPE_TRACEPOINT>"
2138 msgstr ""
2139
2140 #. type: Plain text
2141 #: build/C/man2/perf_event_open.2:281
2142 msgid ""
2143 "This indicates a tracepoint provided by the kernel tracepoint "
2144 "infrastructure."
2145 msgstr ""
2146
2147 #. type: TP
2148 #: build/C/man2/perf_event_open.2:281
2149 #, no-wrap
2150 msgid "B<PERF_TYPE_HW_CACHE>"
2151 msgstr ""
2152
2153 #. type: Plain text
2154 #: build/C/man2/perf_event_open.2:287
2155 msgid ""
2156 "This indicates a hardware cache event.  This has a special encoding, "
2157 "described in the I<config> field definition."
2158 msgstr ""
2159
2160 #. type: TP
2161 #: build/C/man2/perf_event_open.2:287
2162 #, no-wrap
2163 msgid "B<PERF_TYPE_RAW>"
2164 msgstr ""
2165
2166 #. type: Plain text
2167 #: build/C/man2/perf_event_open.2:291
2168 msgid ""
2169 "This indicates a \"raw\" implementation-specific event in the I<config> "
2170 "field."
2171 msgstr ""
2172
2173 #. type: TP
2174 #: build/C/man2/perf_event_open.2:291
2175 #, no-wrap
2176 msgid "B<PERF_TYPE_BREAKPOINT> (Since Linux 2.6.33)"
2177 msgstr ""
2178
2179 #. type: Plain text
2180 #: build/C/man2/perf_event_open.2:296
2181 msgid ""
2182 "This indicates a hardware breakpoint as provided by the CPU.  Breakpoints "
2183 "can be read/write accesses to an address as well as execution of an "
2184 "instruction address."
2185 msgstr ""
2186
2187 #. type: TP
2188 #: build/C/man2/perf_event_open.2:296
2189 #, no-wrap
2190 msgid "dynamic PMU"
2191 msgstr ""
2192
2193 #. type: Plain text
2194 #: build/C/man2/perf_event_open.2:315
2195 msgid ""
2196 "Since Linux 2.6.39, B<perf_event_open>()  can support multiple PMUs.  To "
2197 "enable this, a value exported by the kernel can be used in the I<type> field "
2198 "to indicate which PMU to use.  The value to use can be found in the sysfs "
2199 "filesystem: there is a subdirectory per PMU instance under "
2200 "I</sys/bus/event_source/devices>.  In each sub-directory there is a I<type> "
2201 "file whose content is an integer that can be used in the I<type> field.  For "
2202 "instance, I</sys/bus/event_source/devices/cpu/type> contains the value for "
2203 "the core CPU PMU, which is usually 4."
2204 msgstr ""
2205
2206 #. type: TP
2207 #: build/C/man2/perf_event_open.2:316 build/C/man2/perf_event_open.2:1588
2208 #, no-wrap
2209 msgid "I<size>"
2210 msgstr ""
2211
2212 #. type: Plain text
2213 #: build/C/man2/perf_event_open.2:325
2214 msgid ""
2215 "The size of the I<perf_event_attr> structure for forward/backward "
2216 "compatibility.  Set this using I<sizeof(struct perf_event_attr)> to allow "
2217 "the kernel to see the struct size at the time of compilation."
2218 msgstr ""
2219
2220 #. type: Plain text
2221 #: build/C/man2/perf_event_open.2:340
2222 msgid ""
2223 "The related define B<PERF_ATTR_SIZE_VER0> is set to 64; this was the size of "
2224 "the first published struct.  B<PERF_ATTR_SIZE_VER1> is 72, corresponding to "
2225 "the addition of breakpoints in Linux 2.6.33.  B<PERF_ATTR_SIZE_VER2> is 80 "
2226 "corresponding to the addition of branch sampling in Linux 3.4.  "
2227 "B<PERF_ATR_SIZE_VER3> is 96 corresponding to the addition of "
2228 "I<sample_regs_user> and I<sample_stack_user> in Linux 3.7."
2229 msgstr ""
2230
2231 #. type: TP
2232 #: build/C/man2/perf_event_open.2:340
2233 #, no-wrap
2234 msgid "I<config>"
2235 msgstr ""
2236
2237 #. type: Plain text
2238 #: build/C/man2/perf_event_open.2:351
2239 msgid ""
2240 "This specifies which event you want, in conjunction with the I<type> field.  "
2241 "The I<config1> and I<config2> fields are also taken into account in cases "
2242 "where 64 bits is not enough to fully specify the event.  The encoding of "
2243 "these fields are event dependent."
2244 msgstr ""
2245
2246 #. type: Plain text
2247 #: build/C/man2/perf_event_open.2:357
2248 msgid ""
2249 "The most significant bit (bit 63) of I<config> signifies CPU-specific (raw) "
2250 "counter configuration data; if the most significant bit is unset, the next 7 "
2251 "bits are an event type and the rest of the bits are the event identifier."
2252 msgstr ""
2253
2254 #. type: Plain text
2255 #: build/C/man2/perf_event_open.2:368
2256 msgid ""
2257 "There are various ways to set the I<config> field that are dependent on the "
2258 "value of the previously described I<type> field.  What follows are various "
2259 "possible settings for I<config> separated out by I<type>."
2260 msgstr ""
2261
2262 #. type: Plain text
2263 #: build/C/man2/perf_event_open.2:378
2264 msgid ""
2265 "If I<type> is B<PERF_TYPE_HARDWARE>, we are measuring one of the generalized "
2266 "hardware CPU events.  Not all of these are available on all platforms.  Set "
2267 "I<config> to one of the following:"
2268 msgstr ""
2269
2270 #. type: TP
2271 #: build/C/man2/perf_event_open.2:379
2272 #, no-wrap
2273 msgid "B<PERF_COUNT_HW_CPU_CYCLES>"
2274 msgstr ""
2275
2276 #. type: Plain text
2277 #: build/C/man2/perf_event_open.2:383
2278 msgid "Total cycles.  Be wary of what happens during CPU frequency scaling"
2279 msgstr ""
2280
2281 #. type: TP
2282 #: build/C/man2/perf_event_open.2:383
2283 #, no-wrap
2284 msgid "B<PERF_COUNT_HW_INSTRUCTIONS>"
2285 msgstr ""
2286
2287 #. type: Plain text
2288 #: build/C/man2/perf_event_open.2:388
2289 msgid ""
2290 "Retired instructions.  Be careful, these can be affected by various issues, "
2291 "most notably hardware interrupt counts"
2292 msgstr ""
2293
2294 #. type: TP
2295 #: build/C/man2/perf_event_open.2:388
2296 #, no-wrap
2297 msgid "B<PERF_COUNT_HW_CACHE_REFERENCES>"
2298 msgstr ""
2299
2300 #. type: Plain text
2301 #: build/C/man2/perf_event_open.2:395
2302 msgid ""
2303 "Cache accesses.  Usually this indicates Last Level Cache accesses but this "
2304 "may vary depending on your CPU.  This may include prefetches and coherency "
2305 "messages; again this depends on the design of your CPU."
2306 msgstr ""
2307
2308 #. type: TP
2309 #: build/C/man2/perf_event_open.2:395
2310 #, no-wrap
2311 msgid "B<PERF_COUNT_HW_CACHE_MISSES>"
2312 msgstr ""
2313
2314 #. type: Plain text
2315 #: build/C/man2/perf_event_open.2:402
2316 msgid ""
2317 "Cache misses.  Usually this indicates Last Level Cache misses; this is "
2318 "intended to be used in conjunction with the "
2319 "B<PERF_COUNT_HW_CACHE_REFERENCES> event to calculate cache miss rates."
2320 msgstr ""
2321
2322 #. type: TP
2323 #: build/C/man2/perf_event_open.2:402
2324 #, no-wrap
2325 msgid "B<PERF_COUNT_HW_BRANCH_INSTRUCTIONS>"
2326 msgstr ""
2327
2328 #. type: Plain text
2329 #: build/C/man2/perf_event_open.2:407
2330 msgid ""
2331 "Retired branch instructions.  Prior to Linux 2.6.34, this used the wrong "
2332 "event on AMD processors."
2333 msgstr ""
2334
2335 #. type: TP
2336 #: build/C/man2/perf_event_open.2:407
2337 #, no-wrap
2338 msgid "B<PERF_COUNT_HW_BRANCH_MISSES>"
2339 msgstr ""
2340
2341 #. type: Plain text
2342 #: build/C/man2/perf_event_open.2:410
2343 msgid "Mispredicted branch instructions."
2344 msgstr ""
2345
2346 #. type: TP
2347 #: build/C/man2/perf_event_open.2:410
2348 #, no-wrap
2349 msgid "B<PERF_COUNT_HW_BUS_CYCLES>"
2350 msgstr ""
2351
2352 #. type: Plain text
2353 #: build/C/man2/perf_event_open.2:413
2354 msgid "Bus cycles, which can be different from total cycles."
2355 msgstr ""
2356
2357 #. type: TP
2358 #: build/C/man2/perf_event_open.2:413
2359 #, no-wrap
2360 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_FRONTEND> (Since Linux 3.0)"
2361 msgstr ""
2362
2363 #. type: Plain text
2364 #: build/C/man2/perf_event_open.2:416
2365 msgid "Stalled cycles during issue."
2366 msgstr ""
2367
2368 #. type: TP
2369 #: build/C/man2/perf_event_open.2:416
2370 #, no-wrap
2371 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_BACKEND> (Since Linux 3.0)"
2372 msgstr ""
2373
2374 #. type: Plain text
2375 #: build/C/man2/perf_event_open.2:419
2376 msgid "Stalled cycles during retirement."
2377 msgstr ""
2378
2379 #. type: TP
2380 #: build/C/man2/perf_event_open.2:419
2381 #, no-wrap
2382 msgid "B<PERF_COUNT_HW_REF_CPU_CYCLES> (Since Linux 3.3)"
2383 msgstr ""
2384
2385 #. type: Plain text
2386 #: build/C/man2/perf_event_open.2:422
2387 msgid "Total cycles; not affected by CPU frequency scaling."
2388 msgstr ""
2389
2390 #. type: Plain text
2391 #: build/C/man2/perf_event_open.2:432
2392 msgid ""
2393 "If I<type> is B<PERF_TYPE_SOFTWARE>, we are measuring software events "
2394 "provided by the kernel.  Set I<config> to one of the following:"
2395 msgstr ""
2396
2397 #. type: TP
2398 #: build/C/man2/perf_event_open.2:433
2399 #, no-wrap
2400 msgid "B<PERF_COUNT_SW_CPU_CLOCK>"
2401 msgstr ""
2402
2403 #. type: Plain text
2404 #: build/C/man2/perf_event_open.2:436
2405 msgid "This reports the CPU clock, a high-resolution per-CPU timer."
2406 msgstr ""
2407
2408 #. type: TP
2409 #: build/C/man2/perf_event_open.2:436
2410 #, no-wrap
2411 msgid "B<PERF_COUNT_SW_TASK_CLOCK>"
2412 msgstr ""
2413
2414 #. type: Plain text
2415 #: build/C/man2/perf_event_open.2:439
2416 msgid "This reports a clock count specific to the task that is running."
2417 msgstr ""
2418
2419 #. type: TP
2420 #: build/C/man2/perf_event_open.2:439
2421 #, no-wrap
2422 msgid "B<PERF_COUNT_SW_PAGE_FAULTS>"
2423 msgstr ""
2424
2425 #. type: Plain text
2426 #: build/C/man2/perf_event_open.2:442
2427 msgid "This reports the number of page faults."
2428 msgstr ""
2429
2430 #. type: TP
2431 #: build/C/man2/perf_event_open.2:442
2432 #, no-wrap
2433 msgid "B<PERF_COUNT_SW_CONTEXT_SWITCHES>"
2434 msgstr ""
2435
2436 #. type: Plain text
2437 #: build/C/man2/perf_event_open.2:447
2438 msgid ""
2439 "This counts context switches.  Until Linux 2.6.34, these were all reported "
2440 "as user-space events, after that they are reported as happening in the "
2441 "kernel."
2442 msgstr ""
2443
2444 #. type: TP
2445 #: build/C/man2/perf_event_open.2:447
2446 #, no-wrap
2447 msgid "B<PERF_COUNT_SW_CPU_MIGRATIONS>"
2448 msgstr ""
2449
2450 #. type: Plain text
2451 #: build/C/man2/perf_event_open.2:451
2452 msgid "This reports the number of times the process has migrated to a new CPU."
2453 msgstr ""
2454
2455 #. type: TP
2456 #: build/C/man2/perf_event_open.2:451
2457 #, no-wrap
2458 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MIN>"
2459 msgstr ""
2460
2461 #. type: Plain text
2462 #: build/C/man2/perf_event_open.2:455
2463 msgid ""
2464 "This counts the number of minor page faults.  These did not require disk I/O "
2465 "to handle."
2466 msgstr ""
2467
2468 #. type: TP
2469 #: build/C/man2/perf_event_open.2:455
2470 #, no-wrap
2471 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MAJ>"
2472 msgstr ""
2473
2474 #. type: Plain text
2475 #: build/C/man2/perf_event_open.2:459
2476 msgid ""
2477 "This counts the number of major page faults.  These required disk I/O to "
2478 "handle."
2479 msgstr ""
2480
2481 #. type: TP
2482 #: build/C/man2/perf_event_open.2:459
2483 #, no-wrap
2484 msgid "B<PERF_COUNT_SW_ALIGNMENT_FAULTS> (Since Linux 2.6.33)"
2485 msgstr ""
2486
2487 #. type: Plain text
2488 #: build/C/man2/perf_event_open.2:465
2489 msgid ""
2490 "This counts the number of alignment faults.  These happen when unaligned "
2491 "memory accesses happen; the kernel can handle these but it reduces "
2492 "performance.  This only happens on some architectures (never on x86)."
2493 msgstr ""
2494
2495 #. type: TP
2496 #: build/C/man2/perf_event_open.2:465
2497 #, no-wrap
2498 msgid "B<PERF_COUNT_SW_EMULATION_FAULTS> (Since Linux 2.6.33)"
2499 msgstr ""
2500
2501 #. type: Plain text
2502 #: build/C/man2/perf_event_open.2:471
2503 msgid ""
2504 "This counts the number of emulation faults.  The kernel sometimes traps on "
2505 "unimplemented instructions and emulates them for user space.  This can "
2506 "negatively impact performance."
2507 msgstr ""
2508
2509 #. type: Plain text
2510 #: build/C/man2/perf_event_open.2:484
2511 msgid ""
2512 "If I<type> is B<PERF_TYPE_TRACEPOINT>, then we are measuring kernel "
2513 "tracepoints.  The value to use in I<config> can be obtained from under "
2514 "debugfs I<tracing/events/*/*/id> if ftrace is enabled in the kernel."
2515 msgstr ""
2516
2517 #. type: Plain text
2518 #: build/C/man2/perf_event_open.2:495
2519 msgid ""
2520 "If I<type> is B<PERF_TYPE_HW_CACHE>, then we are measuring a hardware CPU "
2521 "cache event.  To calculate the appropriate I<config> value use the following "
2522 "equation:"
2523 msgstr ""
2524
2525 #. type: Plain text
2526 #: build/C/man2/perf_event_open.2:500
2527 #, no-wrap
2528 msgid ""
2529 "    (perf_hw_cache_id) | (perf_hw_cache_op_id E<lt>E<lt> 8) |\n"
2530 "    (perf_hw_cache_op_result_id E<lt>E<lt> 16)\n"
2531 msgstr ""
2532
2533 #. type: Plain text
2534 #: build/C/man2/perf_event_open.2:505
2535 msgid "where I<perf_hw_cache_id> is one of:"
2536 msgstr ""
2537
2538 #. type: TP
2539 #: build/C/man2/perf_event_open.2:506
2540 #, no-wrap
2541 msgid "B<PERF_COUNT_HW_CACHE_L1D>"
2542 msgstr ""
2543
2544 #. type: Plain text
2545 #: build/C/man2/perf_event_open.2:509
2546 msgid "for measuring Level 1 Data Cache"
2547 msgstr ""
2548
2549 #. type: TP
2550 #: build/C/man2/perf_event_open.2:509
2551 #, no-wrap
2552 msgid "B<PERF_COUNT_HW_CACHE_L1I>"
2553 msgstr ""
2554
2555 #. type: Plain text
2556 #: build/C/man2/perf_event_open.2:512
2557 msgid "for measuring Level 1 Instruction Cache"
2558 msgstr ""
2559
2560 #. type: TP
2561 #: build/C/man2/perf_event_open.2:512
2562 #, no-wrap
2563 msgid "B<PERF_COUNT_HW_CACHE_LL>"
2564 msgstr ""
2565
2566 #. type: Plain text
2567 #: build/C/man2/perf_event_open.2:515
2568 msgid "for measuring Last-Level Cache"
2569 msgstr ""
2570
2571 #. type: TP
2572 #: build/C/man2/perf_event_open.2:515
2573 #, no-wrap
2574 msgid "B<PERF_COUNT_HW_CACHE_DTLB>"
2575 msgstr ""
2576
2577 #. type: Plain text
2578 #: build/C/man2/perf_event_open.2:518
2579 msgid "for measuring the Data TLB"
2580 msgstr ""
2581
2582 #. type: TP
2583 #: build/C/man2/perf_event_open.2:518
2584 #, no-wrap
2585 msgid "B<PERF_COUNT_HW_CACHE_ITLB>"
2586 msgstr ""
2587
2588 #. type: Plain text
2589 #: build/C/man2/perf_event_open.2:521
2590 msgid "for measuring the Instruction TLB"
2591 msgstr ""
2592
2593 #. type: TP
2594 #: build/C/man2/perf_event_open.2:521
2595 #, no-wrap
2596 msgid "B<PERF_COUNT_HW_CACHE_BPU>"
2597 msgstr ""
2598
2599 #. type: Plain text
2600 #: build/C/man2/perf_event_open.2:524
2601 msgid "for measuring the branch prediction unit"
2602 msgstr ""
2603
2604 #. type: TP
2605 #: build/C/man2/perf_event_open.2:524
2606 #, no-wrap
2607 msgid "B<PERF_COUNT_HW_CACHE_NODE> (Since Linux 3.0)"
2608 msgstr ""
2609
2610 #. type: Plain text
2611 #: build/C/man2/perf_event_open.2:527
2612 msgid "for measuring local memory accesses"
2613 msgstr ""
2614
2615 #. type: Plain text
2616 #: build/C/man2/perf_event_open.2:532
2617 msgid "and I<perf_hw_cache_op_id> is one of"
2618 msgstr ""
2619
2620 #. type: TP
2621 #: build/C/man2/perf_event_open.2:533
2622 #, no-wrap
2623 msgid "B<PERF_COUNT_HW_CACHE_OP_READ>"
2624 msgstr ""
2625
2626 #. type: Plain text
2627 #: build/C/man2/perf_event_open.2:536
2628 msgid "for read accesses"
2629 msgstr ""
2630
2631 #. type: TP
2632 #: build/C/man2/perf_event_open.2:536
2633 #, no-wrap
2634 msgid "B<PERF_COUNT_HW_CACHE_OP_WRITE>"
2635 msgstr ""
2636
2637 #. type: Plain text
2638 #: build/C/man2/perf_event_open.2:539
2639 msgid "for write accesses"
2640 msgstr ""
2641
2642 #. type: TP
2643 #: build/C/man2/perf_event_open.2:539
2644 #, no-wrap
2645 msgid "B<PERF_COUNT_HW_CACHE_OP_PREFETCH>"
2646 msgstr ""
2647
2648 #. type: Plain text
2649 #: build/C/man2/perf_event_open.2:542
2650 msgid "for prefetch accesses"
2651 msgstr ""
2652
2653 #. type: Plain text
2654 #: build/C/man2/perf_event_open.2:547
2655 msgid "and I<perf_hw_cache_op_result_id> is one of"
2656 msgstr ""
2657
2658 #. type: TP
2659 #: build/C/man2/perf_event_open.2:548
2660 #, no-wrap
2661 msgid "B<PERF_COUNT_HW_CACHE_RESULT_ACCESS>"
2662 msgstr ""
2663
2664 #. type: Plain text
2665 #: build/C/man2/perf_event_open.2:551
2666 msgid "to measure accesses"
2667 msgstr ""
2668
2669 #. type: TP
2670 #: build/C/man2/perf_event_open.2:551
2671 #, no-wrap
2672 msgid "B<PERF_COUNT_HW_CACHE_RESULT_MISS>"
2673 msgstr ""
2674
2675 #. type: Plain text
2676 #: build/C/man2/perf_event_open.2:554
2677 msgid "to measure misses"
2678 msgstr ""
2679
2680 #. type: Plain text
2681 #: build/C/man2/perf_event_open.2:572
2682 msgid ""
2683 "If I<type> is B<PERF_TYPE_RAW>, then a custom \"raw\" I<config> value is "
2684 "needed.  Most CPUs support events that are not covered by the "
2685 "\"generalized\" events.  These are implementation defined; see your CPU "
2686 "manual (for example the Intel Volume 3B documentation or the AMD BIOS and "
2687 "Kernel Developer Guide).  The libpfm4 library can be used to translate from "
2688 "the name in the architectural manuals to the raw hex value "
2689 "B<perf_event_open>()  expects in this field."
2690 msgstr ""
2691
2692 #. type: Plain text
2693 #: build/C/man2/perf_event_open.2:581
2694 msgid ""
2695 "If I<type> is B<PERF_TYPE_BREAKPOINT>, then leave I<config> set to zero.  "
2696 "Its parameters are set in other places."
2697 msgstr ""
2698
2699 #. type: TP
2700 #: build/C/man2/perf_event_open.2:582
2701 #, no-wrap
2702 msgid "I<sample_period>, I<sample_freq>"
2703 msgstr ""
2704
2705 #. type: Plain text
2706 #: build/C/man2/perf_event_open.2:594
2707 msgid ""
2708 "A \"sampling\" counter is one that generates an interrupt every N events, "
2709 "where N is given by I<sample_period>.  A sampling counter has "
2710 "I<sample_period> E<gt> 0.  When an overflow interrupt occurs, requested data "
2711 "is recorded in the mmap buffer.  The I<sample_type> field controls what data "
2712 "is recorded on each interrupt."
2713 msgstr ""
2714
2715 #. type: Plain text
2716 #: build/C/man2/perf_event_open.2:604
2717 msgid ""
2718 "I<sample_freq> can be used if you wish to use frequency rather than period.  "
2719 "In this case you set the I<freq> flag.  The kernel will adjust the sampling "
2720 "period to try and achieve the desired rate.  The rate of adjustment is a "
2721 "timer tick."
2722 msgstr ""
2723
2724 #. type: TP
2725 #: build/C/man2/perf_event_open.2:604
2726 #, no-wrap
2727 msgid "I<sample_type>"
2728 msgstr ""
2729
2730 #. type: Plain text
2731 #: build/C/man2/perf_event_open.2:616
2732 msgid ""
2733 "The various bits in this field specify which values to include in the "
2734 "sample.  They will be recorded in a ring-buffer, which is available to user "
2735 "space using B<mmap>(2).  The order in which the values are saved in the "
2736 "sample are documented in the MMAP Layout subsection below; it is not the "
2737 "I<enum perf_event_sample_format> order."
2738 msgstr ""
2739
2740 #. type: TP
2741 #: build/C/man2/perf_event_open.2:617
2742 #, no-wrap
2743 msgid "B<PERF_SAMPLE_IP>"
2744 msgstr ""
2745
2746 #. type: Plain text
2747 #: build/C/man2/perf_event_open.2:620
2748 msgid "Records instruction pointer."
2749 msgstr ""
2750
2751 #. type: TP
2752 #: build/C/man2/perf_event_open.2:620
2753 #, no-wrap
2754 msgid "B<PERF_SAMPLE_TID>"
2755 msgstr ""
2756
2757 #. type: Plain text
2758 #: build/C/man2/perf_event_open.2:623
2759 msgid "Records the process and thread IDs."
2760 msgstr ""
2761
2762 #. type: TP
2763 #: build/C/man2/perf_event_open.2:623
2764 #, no-wrap
2765 msgid "B<PERF_SAMPLE_TIME>"
2766 msgstr ""
2767
2768 #. type: Plain text
2769 #: build/C/man2/perf_event_open.2:626
2770 msgid "Records a timestamp."
2771 msgstr ""
2772
2773 #. type: TP
2774 #: build/C/man2/perf_event_open.2:626
2775 #, no-wrap
2776 msgid "B<PERF_SAMPLE_ADDR>"
2777 msgstr ""
2778
2779 #. type: Plain text
2780 #: build/C/man2/perf_event_open.2:629
2781 msgid "Records an address, if applicable."
2782 msgstr ""
2783
2784 #. type: TP
2785 #: build/C/man2/perf_event_open.2:629
2786 #, no-wrap
2787 msgid "B<PERF_SAMPLE_READ>"
2788 msgstr ""
2789
2790 #. type: Plain text
2791 #: build/C/man2/perf_event_open.2:632
2792 msgid "Record counter values for all events in a group, not just the group leader."
2793 msgstr ""
2794
2795 #. type: TP
2796 #: build/C/man2/perf_event_open.2:632
2797 #, no-wrap
2798 msgid "B<PERF_SAMPLE_CALLCHAIN>"
2799 msgstr ""
2800
2801 #. type: Plain text
2802 #: build/C/man2/perf_event_open.2:635
2803 msgid "Records the callchain (stack backtrace)."
2804 msgstr ""
2805
2806 #. type: TP
2807 #: build/C/man2/perf_event_open.2:635
2808 #, no-wrap
2809 msgid "B<PERF_SAMPLE_ID>"
2810 msgstr ""
2811
2812 #. type: Plain text
2813 #: build/C/man2/perf_event_open.2:638
2814 msgid "Records a unique ID for the opened event's group leader."
2815 msgstr ""
2816
2817 #. type: TP
2818 #: build/C/man2/perf_event_open.2:638
2819 #, no-wrap
2820 msgid "B<PERF_SAMPLE_CPU>"
2821 msgstr ""
2822
2823 #. type: Plain text
2824 #: build/C/man2/perf_event_open.2:641
2825 msgid "Records CPU number."
2826 msgstr ""
2827
2828 #. type: TP
2829 #: build/C/man2/perf_event_open.2:641
2830 #, no-wrap
2831 msgid "B<PERF_SAMPLE_PERIOD>"
2832 msgstr ""
2833
2834 #. type: Plain text
2835 #: build/C/man2/perf_event_open.2:644
2836 msgid "Records the current sampling period."
2837 msgstr ""
2838
2839 #. type: TP
2840 #: build/C/man2/perf_event_open.2:644
2841 #, no-wrap
2842 msgid "B<PERF_SAMPLE_STREAM_ID>"
2843 msgstr ""
2844
2845 #. type: Plain text
2846 #: build/C/man2/perf_event_open.2:651
2847 msgid ""
2848 "Records a unique ID for the opened event.  Unlike B<PERF_SAMPLE_ID> the "
2849 "actual ID is returned, not the group leader.  This ID is the same as the one "
2850 "returned by PERF_FORMAT_ID."
2851 msgstr ""
2852
2853 #. type: TP
2854 #: build/C/man2/perf_event_open.2:651
2855 #, no-wrap
2856 msgid "B<PERF_SAMPLE_RAW>"
2857 msgstr ""
2858
2859 #. type: Plain text
2860 #: build/C/man2/perf_event_open.2:655
2861 msgid ""
2862 "Records additional data, if applicable.  Usually returned by tracepoint "
2863 "events."
2864 msgstr ""
2865
2866 #. type: TP
2867 #: build/C/man2/perf_event_open.2:655
2868 #, no-wrap
2869 msgid "B<PERF_SAMPLE_BRANCH_STACK> (Since Linux 3.4)"
2870 msgstr ""
2871
2872 #. type: Plain text
2873 #: build/C/man2/perf_event_open.2:659
2874 msgid "Records the branch stack.  See branch_sample_type."
2875 msgstr ""
2876
2877 #. type: TP
2878 #: build/C/man2/perf_event_open.2:659
2879 #, no-wrap
2880 msgid "B<PERF_SAMPLE_REGS_USER> (Since Linux 3.7)"
2881 msgstr ""
2882
2883 #. type: Plain text
2884 #: build/C/man2/perf_event_open.2:662
2885 msgid "Records the current register state."
2886 msgstr ""
2887
2888 #. type: TP
2889 #: build/C/man2/perf_event_open.2:662
2890 #, no-wrap
2891 msgid "B<PERF_SAMPLE_STACK_USER> (Since Linux 3.7)"
2892 msgstr ""
2893
2894 #. type: Plain text
2895 #: build/C/man2/perf_event_open.2:665 build/C/man2/perf_event_open.2:1786 build/C/man2/perf_event_open.2:1803
2896 msgid "[To be documented]"
2897 msgstr ""
2898
2899 #. type: TP
2900 #: build/C/man2/perf_event_open.2:666
2901 #, no-wrap
2902 msgid "I<read_format>"
2903 msgstr ""
2904
2905 #. type: Plain text
2906 #: build/C/man2/perf_event_open.2:673
2907 msgid ""
2908 "This field specifies the format of the data returned by B<read>(2)  on a "
2909 "B<perf_event_open>()  file descriptor."
2910 msgstr ""
2911
2912 #. type: TP
2913 #: build/C/man2/perf_event_open.2:674
2914 #, no-wrap
2915 msgid "B<PERF_FORMAT_TOTAL_TIME_ENABLED>"
2916 msgstr ""
2917
2918 #. type: Plain text
2919 #: build/C/man2/perf_event_open.2:681
2920 msgid ""
2921 "Adds the 64-bit I<time_enabled> field.  This can be used to calculate "
2922 "estimated totals if the PMU is overcommitted and multiplexing is happening."
2923 msgstr ""
2924
2925 #. type: TP
2926 #: build/C/man2/perf_event_open.2:681
2927 #, no-wrap
2928 msgid "B<PERF_FORMAT_TOTAL_TIME_RUNNING>"
2929 msgstr ""
2930
2931 #. type: Plain text
2932 #: build/C/man2/perf_event_open.2:688
2933 msgid ""
2934 "Adds the 64-bit I<time_running> field.  This can be used to calculate "
2935 "estimated totals if the PMU is overcommitted and multiplexing is happening."
2936 msgstr ""
2937
2938 #. type: TP
2939 #: build/C/man2/perf_event_open.2:688
2940 #, no-wrap
2941 msgid "B<PERF_FORMAT_ID>"
2942 msgstr ""
2943
2944 #. type: Plain text
2945 #: build/C/man2/perf_event_open.2:691
2946 msgid "Adds a 64-bit unique value that corresponds to the event group."
2947 msgstr ""
2948
2949 #. type: TP
2950 #: build/C/man2/perf_event_open.2:691
2951 #, no-wrap
2952 msgid "B<PERF_FORMAT_GROUP>"
2953 msgstr ""
2954
2955 #. type: Plain text
2956 #: build/C/man2/perf_event_open.2:694
2957 msgid "Allows all counter values in an event group to be read with one read."
2958 msgstr ""
2959
2960 #. type: TP
2961 #: build/C/man2/perf_event_open.2:695
2962 #, no-wrap
2963 msgid "I<disabled>"
2964 msgstr ""
2965
2966 #. type: Plain text
2967 #: build/C/man2/perf_event_open.2:705
2968 msgid ""
2969 "The I<disabled> bit specifies whether the counter starts out disabled or "
2970 "enabled.  If disabled, the event can later be enabled by B<ioctl>(2), "
2971 "B<prctl>(2), or I<enable_on_exec>."
2972 msgstr ""
2973
2974 #. type: TP
2975 #: build/C/man2/perf_event_open.2:705
2976 #, no-wrap
2977 msgid "I<inherit>"
2978 msgstr ""
2979
2980 #. type: Plain text
2981 #: build/C/man2/perf_event_open.2:714
2982 msgid ""
2983 "The I<inherit> bit specifies that this counter should count events of child "
2984 "tasks as well as the task specified.  This only applies to new children, not "
2985 "to any existing children at the time the counter is created (nor to any new "
2986 "children of existing children)."
2987 msgstr ""
2988
2989 #. type: Plain text
2990 #: build/C/man2/perf_event_open.2:719
2991 msgid ""
2992 "Inherit does not work for some combinations of I<read_format>s, such as "
2993 "B<PERF_FORMAT_GROUP>."
2994 msgstr ""
2995
2996 #. type: TP
2997 #: build/C/man2/perf_event_open.2:719
2998 #, no-wrap
2999 msgid "I<pinned>"
3000 msgstr ""
3001
3002 #. type: Plain text
3003 #: build/C/man2/perf_event_open.2:732
3004 msgid ""
3005 "The I<pinned> bit specifies that the counter should always be on the CPU if "
3006 "at all possible.  It only applies to hardware counters and only to group "
3007 "leaders.  If a pinned counter cannot be put onto the CPU (e.g., because "
3008 "there are not enough hardware counters or because of a conflict with some "
3009 "other event), then the counter goes into an 'error' state, where reads "
3010 "return end-of-file (i.e., B<read>(2)  returns 0) until the counter is "
3011 "subsequently enabled or disabled."
3012 msgstr ""
3013
3014 #. type: TP
3015 #: build/C/man2/perf_event_open.2:732
3016 #, no-wrap
3017 msgid "I<exclusive>"
3018 msgstr ""
3019
3020 #. type: Plain text
3021 #: build/C/man2/perf_event_open.2:741
3022 msgid ""
3023 "The I<exclusive> bit specifies that when this counter's group is on the CPU, "
3024 "it should be the only group using the CPU's counters.  In the future this "
3025 "may allow monitoring programs to support PMU features that need to run alone "
3026 "so that they do not disrupt other hardware counters."
3027 msgstr ""
3028
3029 #. type: TP
3030 #: build/C/man2/perf_event_open.2:741
3031 #, no-wrap
3032 msgid "I<exclude_user>"
3033 msgstr ""
3034
3035 #. type: Plain text
3036 #: build/C/man2/perf_event_open.2:744
3037 msgid "If this bit is set, the count excludes events that happen in user space."
3038 msgstr ""
3039
3040 #. type: TP
3041 #: build/C/man2/perf_event_open.2:744
3042 #, no-wrap
3043 msgid "I<exclude_kernel>"
3044 msgstr ""
3045
3046 #. type: Plain text
3047 #: build/C/man2/perf_event_open.2:747
3048 msgid "If this bit is set, the count excludes events that happen in kernel-space."
3049 msgstr ""
3050
3051 #. type: TP
3052 #: build/C/man2/perf_event_open.2:747
3053 #, no-wrap
3054 msgid "I<exclude_hv>"
3055 msgstr ""
3056
3057 #. type: Plain text
3058 #: build/C/man2/perf_event_open.2:755
3059 msgid ""
3060 "If this bit is set, the count excludes events that happen in the "
3061 "hypervisor.  This is mainly for PMUs that have built-in support for handling "
3062 "this (such as POWER).  Extra support is needed for handling hypervisor "
3063 "measurements on most machines."
3064 msgstr ""
3065
3066 #. type: TP
3067 #: build/C/man2/perf_event_open.2:755
3068 #, no-wrap
3069 msgid "I<exclude_idle>"
3070 msgstr ""
3071
3072 #. type: Plain text
3073 #: build/C/man2/perf_event_open.2:758
3074 msgid "If set, don't count when the CPU is idle."
3075 msgstr ""
3076
3077 #. type: TP
3078 #: build/C/man2/perf_event_open.2:758
3079 #, no-wrap
3080 msgid "I<mmap>"
3081 msgstr ""
3082
3083 #. type: Plain text
3084 #: build/C/man2/perf_event_open.2:763
3085 msgid "The I<mmap> bit enables recording of exec mmap events."
3086 msgstr ""
3087
3088 #. type: TP
3089 #: build/C/man2/perf_event_open.2:763
3090 #, no-wrap
3091 msgid "I<comm>"
3092 msgstr ""
3093
3094 #. type: Plain text
3095 #: build/C/man2/perf_event_open.2:774
3096 msgid ""
3097 "The I<comm> bit enables tracking of process command name as modified by the "
3098 "I<exec>(2)  and I<prctl>(PR_SET_NAME)  system calls.  Unfortunately for "
3099 "tools, there is no way to distinguish one system call versus the other."
3100 msgstr ""
3101
3102 #. type: TP
3103 #: build/C/man2/perf_event_open.2:774
3104 #, no-wrap
3105 msgid "I<freq>"
3106 msgstr ""
3107
3108 #. type: Plain text
3109 #: build/C/man2/perf_event_open.2:781
3110 msgid ""
3111 "If this bit is set, then I<sample_frequency> not I<sample_period> is used "
3112 "when setting up the sampling interval."
3113 msgstr ""
3114
3115 #. type: TP
3116 #: build/C/man2/perf_event_open.2:781
3117 #, no-wrap
3118 msgid "I<inherit_stat>"
3119 msgstr ""
3120
3121 #. type: Plain text
3122 #: build/C/man2/perf_event_open.2:788
3123 msgid ""
3124 "This bit enables saving of event counts on context switch for inherited "
3125 "tasks.  This is only meaningful if the I<inherit> field is set."
3126 msgstr ""
3127
3128 #. type: TP
3129 #: build/C/man2/perf_event_open.2:788
3130 #, no-wrap
3131 msgid "I<enable_on_exec>"
3132 msgstr ""
3133
3134 #. type: Plain text
3135 #: build/C/man2/perf_event_open.2:793
3136 msgid ""
3137 "If this bit is set, a counter is automatically enabled after a call to "
3138 "B<exec>(2)."
3139 msgstr ""
3140
3141 #. type: TP
3142 #: build/C/man2/perf_event_open.2:793
3143 #, no-wrap
3144 msgid "I<task>"
3145 msgstr ""
3146
3147 #. type: Plain text
3148 #: build/C/man2/perf_event_open.2:797
3149 msgid ""
3150 "If this bit is set, then fork/exit notifications are included in the ring "
3151 "buffer."
3152 msgstr ""
3153
3154 #. type: TP
3155 #: build/C/man2/perf_event_open.2:797
3156 #, no-wrap
3157 msgid "I<watermark>"
3158 msgstr ""
3159
3160 #. type: Plain text
3161 #: build/C/man2/perf_event_open.2:805
3162 msgid ""
3163 "If set, have a sampling interrupt happen when we cross the "
3164 "I<wakeup_watermark> boundary.  Otherwise interrupts happen after "
3165 "I<wakeup_events> samples."
3166 msgstr ""
3167
3168 #. type: TP
3169 #: build/C/man2/perf_event_open.2:805
3170 #, no-wrap
3171 msgid "I<precise_ip> (Since Linux 2.6.35)"
3172 msgstr ""
3173
3174 #. type: Plain text
3175 #: build/C/man2/perf_event_open.2:815
3176 msgid ""
3177 "This controls the amount of skid.  Skid is how many instructions execute "
3178 "between an event of interest happening and the kernel being able to stop and "
3179 "record the event.  Smaller skid is better and allows more accurate reporting "
3180 "of which events correspond to which instructions, but hardware is often "
3181 "limited with how small this can be."
3182 msgstr ""
3183
3184 #. type: Plain text
3185 #: build/C/man2/perf_event_open.2:817
3186 msgid "The values of this are the following:"
3187 msgstr ""
3188
3189 #. type: TP
3190 #: build/C/man2/perf_event_open.2:818
3191 #, no-wrap
3192 msgid "0 -"
3193 msgstr ""
3194
3195 #. type: Plain text
3196 #: build/C/man2/perf_event_open.2:822
3197 msgid "B<SAMPLE_IP> can have arbitrary skid"
3198 msgstr ""
3199
3200 #. type: TP
3201 #: build/C/man2/perf_event_open.2:822
3202 #, no-wrap
3203 msgid "1 -"
3204 msgstr ""
3205
3206 #. type: Plain text
3207 #: build/C/man2/perf_event_open.2:826
3208 msgid "B<SAMPLE_IP> must have constant skid"
3209 msgstr ""
3210
3211 #. type: TP
3212 #: build/C/man2/perf_event_open.2:826
3213 #, no-wrap
3214 msgid "2 -"
3215 msgstr ""
3216
3217 #. type: Plain text
3218 #: build/C/man2/perf_event_open.2:830
3219 msgid "B<SAMPLE_IP> requested to have 0 skid"
3220 msgstr ""
3221
3222 #. type: TP
3223 #: build/C/man2/perf_event_open.2:830
3224 #, no-wrap
3225 msgid "3 -"
3226 msgstr ""
3227
3228 #. type: Plain text
3229 #: build/C/man2/perf_event_open.2:836
3230 msgid "B<SAMPLE_IP> must have 0 skid.  See also B<PERF_RECORD_MISC_EXACT_IP>."
3231 msgstr ""
3232
3233 #. type: TP
3234 #: build/C/man2/perf_event_open.2:837
3235 #, no-wrap
3236 msgid "I<mmap_data> (Since Linux 2.6.36)"
3237 msgstr ""
3238
3239 #. type: Plain text
3240 #: build/C/man2/perf_event_open.2:843
3241 msgid ""
3242 "The counterpart of the I<mmap> field, but enables including data mmap events "
3243 "in the ring-buffer."
3244 msgstr ""
3245
3246 #. type: TP
3247 #: build/C/man2/perf_event_open.2:843
3248 #, no-wrap
3249 msgid "I<sample_id_all> (Since Linux 2.6.38)"
3250 msgstr ""
3251
3252 #. type: Plain text
3253 #: build/C/man2/perf_event_open.2:851
3254 msgid ""
3255 "If set, then TID, TIME, ID, CPU, and STREAM_ID can additionally be included "
3256 "in non-B<PERF_RECORD_SAMPLE>s if the corresponding I<sample_type> is "
3257 "selected."
3258 msgstr ""
3259
3260 #. type: TP
3261 #: build/C/man2/perf_event_open.2:851
3262 #, no-wrap
3263 msgid "I<exclude_host> (Since Linux 3.2)"
3264 msgstr ""
3265
3266 #. type: Plain text
3267 #: build/C/man2/perf_event_open.2:854
3268 msgid "Do not measure time spent in VM host"
3269 msgstr ""
3270
3271 #. type: TP
3272 #: build/C/man2/perf_event_open.2:854
3273 #, no-wrap
3274 msgid "I<exclude_guest> (Since Linux 3.2)"
3275 msgstr ""
3276
3277 #. type: Plain text
3278 #: build/C/man2/perf_event_open.2:857
3279 msgid "Do not measure time spent in VM guest"
3280 msgstr ""
3281
3282 #. type: TP
3283 #: build/C/man2/perf_event_open.2:857
3284 #, no-wrap
3285 msgid "I<exclude_callchain_kernel> (Since Linux 3.7)"
3286 msgstr ""
3287
3288 #. type: Plain text
3289 #: build/C/man2/perf_event_open.2:860
3290 msgid "Do not include kernel callchains."
3291 msgstr ""
3292
3293 #. type: TP
3294 #: build/C/man2/perf_event_open.2:860
3295 #, no-wrap
3296 msgid "I<exclude_callchain_user> (Since Linux 3.7)"
3297 msgstr ""
3298
3299 #. type: Plain text
3300 #: build/C/man2/perf_event_open.2:863
3301 msgid "Do not include user callchains."
3302 msgstr ""
3303
3304 #. type: TP
3305 #: build/C/man2/perf_event_open.2:863
3306 #, no-wrap
3307 msgid "I<wakeup_events>, I<wakeup_watermark>"
3308 msgstr ""
3309
3310 #. type: Plain text
3311 #: build/C/man2/perf_event_open.2:873
3312 msgid ""
3313 "This union sets how many samples (I<wakeup_events>)  or bytes "
3314 "(I<wakeup_watermark>)  happen before an overflow signal happens.  Which one "
3315 "is used is selected by the I<watermark> bitflag."
3316 msgstr ""
3317
3318 #. type: TP
3319 #: build/C/man2/perf_event_open.2:873
3320 #, no-wrap
3321 msgid "I<bp_type> (Since Linux 2.6.33)"
3322 msgstr ""
3323
3324 #. type: Plain text
3325 #: build/C/man2/perf_event_open.2:877
3326 msgid "This chooses the breakpoint type.  It is one of:"
3327 msgstr ""
3328
3329 #. type: TP
3330 #: build/C/man2/perf_event_open.2:878
3331 #, no-wrap
3332 msgid "B<HW_BREAKPOINT_EMPTY>"
3333 msgstr ""
3334
3335 #. type: Plain text
3336 #: build/C/man2/perf_event_open.2:881
3337 msgid "no breakpoint"
3338 msgstr ""
3339
3340 #. type: TP
3341 #: build/C/man2/perf_event_open.2:881
3342 #, no-wrap
3343 msgid "B<HW_BREAKPOINT_R>"
3344 msgstr ""
3345
3346 #. type: Plain text
3347 #: build/C/man2/perf_event_open.2:884
3348 msgid "count when we read the memory location"
3349 msgstr ""
3350
3351 #. type: TP
3352 #: build/C/man2/perf_event_open.2:884
3353 #, no-wrap
3354 msgid "B<HW_BREAKPOINT_W>"
3355 msgstr ""
3356
3357 #. type: Plain text
3358 #: build/C/man2/perf_event_open.2:887
3359 msgid "count when we write the memory location"
3360 msgstr ""
3361
3362 #. type: TP
3363 #: build/C/man2/perf_event_open.2:887
3364 #, no-wrap
3365 msgid "B<HW_BREAKPOINT_RW>"
3366 msgstr ""
3367
3368 #. type: Plain text
3369 #: build/C/man2/perf_event_open.2:890
3370 msgid "count when we read or write the memory location"
3371 msgstr ""
3372
3373 #. type: TP
3374 #: build/C/man2/perf_event_open.2:890
3375 #, no-wrap
3376 msgid "B<HW_BREAKPOINT_X>"
3377 msgstr ""
3378
3379 #. type: Plain text
3380 #: build/C/man2/perf_event_open.2:893
3381 msgid "count when we execute code at the memory location"
3382 msgstr ""
3383
3384 #. type: Plain text
3385 #: build/C/man2/perf_event_open.2:902
3386 msgid ""
3387 "The values can be combined via a bitwise or, but the combination of "
3388 "B<HW_BREAKPOINT_R> or B<HW_BREAKPOINT_W> with B<HW_BREAKPOINT_X> is not "
3389 "allowed."
3390 msgstr ""
3391
3392 #. type: TP
3393 #: build/C/man2/perf_event_open.2:903
3394 #, no-wrap
3395 msgid "I<bp_addr> (Since Linux 2.6.33)"
3396 msgstr ""
3397
3398 #. type: Plain text
3399 #: build/C/man2/perf_event_open.2:910
3400 msgid ""
3401 "I<bp_addr> address of the breakpoint.  For execution breakpoints this is the "
3402 "memory address of the instruction of interest; for read and write "
3403 "breakpoints it is the memory address of the memory location of interest."
3404 msgstr ""
3405
3406 #. type: TP
3407 #: build/C/man2/perf_event_open.2:910
3408 #, no-wrap
3409 msgid "I<config1> (Since Linux 2.6.39)"
3410 msgstr ""
3411
3412 #. type: Plain text
3413 #: build/C/man2/perf_event_open.2:917
3414 msgid ""
3415 "I<config1> is used for setting events that need an extra register or "
3416 "otherwise do not fit in the regular config field.  Raw OFFCORE_EVENTS on "
3417 "Nehalem/Westmere/SandyBridge use this field on 3.3 and later kernels."
3418 msgstr ""
3419
3420 #. type: TP
3421 #: build/C/man2/perf_event_open.2:917
3422 #, no-wrap
3423 msgid "I<bp_len> (Since Linux 2.6.33)"
3424 msgstr ""
3425
3426 #. type: Plain text
3427 #: build/C/man2/perf_event_open.2:931
3428 msgid ""
3429 "I<bp_len> is the length of the breakpoint being measured if I<type> is "
3430 "B<PERF_TYPE_BREAKPOINT>.  Options are B<HW_BREAKPOINT_LEN_1>, "
3431 "B<HW_BREAKPOINT_LEN_2>, B<HW_BREAKPOINT_LEN_4>, B<HW_BREAKPOINT_LEN_8>.  For "
3432 "an execution breakpoint, set this to I<sizeof(long)>."
3433 msgstr ""
3434
3435 #. type: TP
3436 #: build/C/man2/perf_event_open.2:931
3437 #, no-wrap
3438 msgid "I<config2> (Since Linux 2.6.39)"
3439 msgstr ""
3440
3441 #. type: Plain text
3442 #: build/C/man2/perf_event_open.2:938
3443 msgid "I<config2> is a further extension of the I<config1> field."
3444 msgstr ""
3445
3446 #. type: TP
3447 #: build/C/man2/perf_event_open.2:938
3448 #, no-wrap
3449 msgid "I<branch_sample_type> (Since Linux 3.4)"
3450 msgstr ""
3451
3452 #. type: Plain text
3453 #: build/C/man2/perf_event_open.2:942
3454 msgid ""
3455 "This is used with the CPUs hardware branch sampling, if available.  It can "
3456 "have one of the following values:"
3457 msgstr ""
3458
3459 #. type: TP
3460 #: build/C/man2/perf_event_open.2:943
3461 #, no-wrap
3462 msgid "B<PERF_SAMPLE_BRANCH_USER>"
3463 msgstr ""
3464
3465 #. type: Plain text
3466 #: build/C/man2/perf_event_open.2:946
3467 msgid "Branch target is in user space"
3468 msgstr ""
3469
3470 #. type: TP
3471 #: build/C/man2/perf_event_open.2:946
3472 #, no-wrap
3473 msgid "B<PERF_SAMPLE_BRANCH_KERNEL>"
3474 msgstr ""
3475
3476 #. type: Plain text
3477 #: build/C/man2/perf_event_open.2:949
3478 msgid "Branch target is in kernel space"
3479 msgstr ""
3480
3481 #. type: TP
3482 #: build/C/man2/perf_event_open.2:949
3483 #, no-wrap
3484 msgid "B<PERF_SAMPLE_BRANCH_HV>"
3485 msgstr ""
3486
3487 #. type: Plain text
3488 #: build/C/man2/perf_event_open.2:952
3489 msgid "Branch target is in hypervisor"
3490 msgstr ""
3491
3492 #. type: TP
3493 #: build/C/man2/perf_event_open.2:952
3494 #, no-wrap
3495 msgid "B<PERF_SAMPLE_BRANCH_ANY>"
3496 msgstr ""
3497
3498 #. type: Plain text
3499 #: build/C/man2/perf_event_open.2:955
3500 msgid "Any branch type."
3501 msgstr ""
3502
3503 #. type: TP
3504 #: build/C/man2/perf_event_open.2:955
3505 #, no-wrap
3506 msgid "B<PERF_SAMPLE_BRANCH_ANY_CALL>"
3507 msgstr ""
3508
3509 #. type: Plain text
3510 #: build/C/man2/perf_event_open.2:958
3511 msgid "Any call branch"
3512 msgstr ""
3513
3514 #. type: TP
3515 #: build/C/man2/perf_event_open.2:958
3516 #, no-wrap
3517 msgid "B<PERF_SAMPLE_BRANCH_ANY_RETURN>"
3518 msgstr ""
3519
3520 #. type: Plain text
3521 #: build/C/man2/perf_event_open.2:961
3522 msgid "Any return branch"
3523 msgstr ""
3524
3525 #. type: TP
3526 #: build/C/man2/perf_event_open.2:961
3527 #, no-wrap
3528 msgid "B<PERF_SAMPLE_BRANCH_IND_CALL>"
3529 msgstr ""
3530
3531 #. type: Plain text
3532 #: build/C/man2/perf_event_open.2:964
3533 msgid "Indirect calls"
3534 msgstr ""
3535
3536 #. type: TP
3537 #: build/C/man2/perf_event_open.2:964
3538 #, no-wrap
3539 msgid "B<PERF_SAMPLE_BRANCH_PLM_ALL>"
3540 msgstr ""
3541
3542 #. type: Plain text
3543 #: build/C/man2/perf_event_open.2:967
3544 msgid "User, kernel, and hv"
3545 msgstr ""
3546
3547 #. type: TP
3548 #: build/C/man2/perf_event_open.2:968
3549 #, no-wrap
3550 msgid "I<sample_regs_user> (Since Linux 3.7)"
3551 msgstr ""
3552
3553 #.  FIXME: The following reference seems to be not quite right:
3554 #. type: Plain text
3555 #: build/C/man2/perf_event_open.2:974
3556 msgid ""
3557 "This defines the set of user registers to dump on samples.  See "
3558 "I<asm/perf_regs.h>."
3559 msgstr ""
3560
3561 #. type: TP
3562 #: build/C/man2/perf_event_open.2:974
3563 #, no-wrap
3564 msgid "I<sample_stack_user> (Since Linux 3.7)"
3565 msgstr ""
3566
3567 #. type: Plain text
3568 #: build/C/man2/perf_event_open.2:977
3569 msgid "This defines the size of the user stack to dump on samples."
3570 msgstr ""
3571
3572 #. type: SS
3573 #: build/C/man2/perf_event_open.2:977
3574 #, no-wrap
3575 msgid "Reading results"
3576 msgstr ""
3577
3578 #. type: Plain text
3579 #: build/C/man2/perf_event_open.2:987
3580 msgid ""
3581 "Once a B<perf_event_open>()  file descriptor has been opened, the values of "
3582 "the events can be read from the file descriptor.  The values that are there "
3583 "are specified by the I<read_format> field in the I<attr> structure at open "
3584 "time."
3585 msgstr ""
3586
3587 #. type: Plain text
3588 #: build/C/man2/perf_event_open.2:992
3589 msgid ""
3590 "If you attempt to read into a buffer that is not big enough to hold the data "
3591 "B<ENOSPC> is returned"
3592 msgstr ""
3593
3594 #. type: Plain text
3595 #: build/C/man2/perf_event_open.2:994
3596 msgid "Here is the layout of the data returned by a read:"
3597 msgstr ""
3598
3599 #. type: IP
3600 #: build/C/man2/perf_event_open.2:994 build/C/man2/perf_event_open.2:1012 build/C/man2/ptrace.2:1552 build/C/man2/ptrace.2:1562 build/C/man2/ptrace.2:1570 build/C/man2/ptrace.2:1576 build/C/man2/ptrace.2:1705
3601 #, no-wrap
3602 msgid "*"
3603 msgstr ""
3604
3605 #. type: Plain text
3606 #: build/C/man2/perf_event_open.2:998
3607 msgid ""
3608 "If B<PERF_FORMAT_GROUP> was specified to allow reading all events in a group "
3609 "at once:"
3610 msgstr ""
3611
3612 #. type: Plain text
3613 #: build/C/man2/perf_event_open.2:1010
3614 #, no-wrap
3615 msgid ""
3616 "struct read_format {\n"
3617 "    u64 nr;            /* The number of events */\n"
3618 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3619 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3620 "    struct\n"
3621 "        u64 value;     /* The value of the event */\n"
3622 "        u64 id;        /* if PERF_FORMAT_ID */\n"
3623 "    } values[nr];\n"
3624 "};\n"
3625 msgstr ""
3626
3627 #. type: Plain text
3628 #: build/C/man2/perf_event_open.2:1018
3629 msgid "If B<PERF_FORMAT_GROUP> was I<not> specified:"
3630 msgstr ""
3631
3632 #. type: Plain text
3633 #: build/C/man2/perf_event_open.2:1027
3634 #, no-wrap
3635 msgid ""
3636 "struct read_format {\n"
3637 "    u64 value;         /* The value of the event */\n"
3638 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3639 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3640 "    u64 id;            /* if PERF_FORMAT_ID */\n"
3641 "};\n"
3642 msgstr ""
3643
3644 #. type: Plain text
3645 #: build/C/man2/perf_event_open.2:1031
3646 msgid "The values read are as follows:"
3647 msgstr ""
3648
3649 #. type: TP
3650 #: build/C/man2/perf_event_open.2:1031
3651 #, no-wrap
3652 msgid "I<nr>"
3653 msgstr ""
3654
3655 #. type: Plain text
3656 #: build/C/man2/perf_event_open.2:1037
3657 msgid ""
3658 "The number of events in this file descriptor.  Only available if "
3659 "B<PERF_FORMAT_GROUP> was specified."
3660 msgstr ""
3661
3662 #. type: TP
3663 #: build/C/man2/perf_event_open.2:1037
3664 #, no-wrap
3665 msgid "I<time_enabled>, I<time_running>"
3666 msgstr ""
3667
3668 #. type: Plain text
3669 #: build/C/man2/perf_event_open.2:1049
3670 msgid ""
3671 "Total time the event was enabled and running.  Normally these are the same.  "
3672 "If more events are started than available counter slots on the PMU, then "
3673 "multiplexing happens and events only run part of the time.  In that case the "
3674 "I<time_enabled> and I<time running> values can be used to scale an estimated "
3675 "value for the count."
3676 msgstr ""
3677
3678 #. type: TP
3679 #: build/C/man2/perf_event_open.2:1049
3680 #, no-wrap
3681 msgid "I<value>"
3682 msgstr ""
3683
3684 #. type: Plain text
3685 #: build/C/man2/perf_event_open.2:1052
3686 msgid "An unsigned 64-bit value containing the counter result."
3687 msgstr ""
3688
3689 #. type: TP
3690 #: build/C/man2/perf_event_open.2:1052 build/C/man2/perf_event_open.2:1316 build/C/man2/perf_event_open.2:1451
3691 #, no-wrap
3692 msgid "I<id>"
3693 msgstr ""
3694
3695 #. type: Plain text
3696 #: build/C/man2/perf_event_open.2:1058
3697 msgid ""
3698 "A globally unique value for this particular event, only there if "
3699 "B<PERF_FORMAT_ID> was specified in I<read_format>."
3700 msgstr ""
3701
3702 #. type: SS
3703 #: build/C/man2/perf_event_open.2:1058
3704 #, no-wrap
3705 msgid "MMAP layout"
3706 msgstr ""
3707
3708 #. type: Plain text
3709 #: build/C/man2/perf_event_open.2:1068
3710 msgid ""
3711 "When using B<perf_event_open>()  in sampled mode, asynchronous events (like "
3712 "counter overflow or B<PROT_EXEC> mmap tracking)  are logged into a "
3713 "ring-buffer.  This ring-buffer is created and accessed through B<mmap>(2)."
3714 msgstr ""
3715
3716 #. type: Plain text
3717 #: build/C/man2/perf_event_open.2:1074
3718 msgid ""
3719 "The mmap size should be 1+2^n pages, where the first page is a metadata page "
3720 "(I<struct perf_event_mmap_page>)  that contains various bits of information "
3721 "such as where the ring-buffer head is."
3722 msgstr ""
3723
3724 #. type: Plain text
3725 #: build/C/man2/perf_event_open.2:1077
3726 msgid ""
3727 "Before kernel 2.6.39, there is a bug that means you must allocate a mmap "
3728 "ring buffer when sampling even if you do not plan to access it."
3729 msgstr ""
3730
3731 #. type: Plain text
3732 #: build/C/man2/perf_event_open.2:1079
3733 msgid "The structure of the first metadata mmap page is as follows:"
3734 msgstr ""
3735
3736 #. type: Plain text
3737 #: build/C/man2/perf_event_open.2:1103
3738 #, no-wrap
3739 msgid ""
3740 "struct perf_event_mmap_page {\n"
3741 "    __u32 version;          /* version number of this structure */\n"
3742 "    __u32 compat_version;   /* lowest version this is compat with */\n"
3743 "    __u32 lock;             /* seqlock for synchronization */\n"
3744 "    __u32 index;            /* hardware counter identifier */\n"
3745 "    __s64 offset;           /* add to hardware counter value */\n"
3746 "    __u64 time_enabled;     /* time event active */\n"
3747 "    __u64 time_running;     /* time event on CPU */\n"
3748 "    union {\n"
3749 "        __u64   capabilities;\n"
3750 "        __u64   cap_usr_time  : 1,\n"
3751 "                cap_usr_rdpmc : 1,\n"
3752 "    };\n"
3753 "    __u16   pmc_width;\n"
3754 "    __u16   time_shift;\n"
3755 "    __u32   time_mult;\n"
3756 "    __u64   time_offset;\n"
3757 "    __u64   __reserved[120];   /* Pad to 1k */\n"
3758 "    __u64   data_head;         /* head in the data section */\n"
3759 "    __u64   data_tail;         /* user-space written tail */\n"
3760 "}\n"
3761 msgstr ""
3762
3763 #. type: Plain text
3764 #: build/C/man2/perf_event_open.2:1109
3765 msgid ""
3766 "The following looks at the fields in the I<perf_event_mmap_page> structure "
3767 "in more detail:"
3768 msgstr ""
3769
3770 #. type: TP
3771 #: build/C/man2/perf_event_open.2:1109
3772 #, no-wrap
3773 msgid "I<version>"
3774 msgstr ""
3775
3776 #. type: Plain text
3777 #: build/C/man2/perf_event_open.2:1112
3778 msgid "Version number of this structure."
3779 msgstr ""
3780
3781 #. type: TP
3782 #: build/C/man2/perf_event_open.2:1112
3783 #, no-wrap
3784 msgid "I<compat_version>"
3785 msgstr ""
3786
3787 #. type: Plain text
3788 #: build/C/man2/perf_event_open.2:1115
3789 msgid "The lowest version this is compatible with."
3790 msgstr ""
3791
3792 #. type: TP
3793 #: build/C/man2/perf_event_open.2:1115
3794 #, no-wrap
3795 msgid "I<lock>"
3796 msgstr ""
3797
3798 #. type: Plain text
3799 #: build/C/man2/perf_event_open.2:1118
3800 msgid "A seqlock for synchronization."
3801 msgstr ""
3802
3803 #. type: TP
3804 #: build/C/man2/perf_event_open.2:1118
3805 #, no-wrap
3806 msgid "I<index>"
3807 msgstr ""
3808
3809 #. type: Plain text
3810 #: build/C/man2/perf_event_open.2:1121
3811 msgid "A unique hardware counter identifier."
3812 msgstr ""
3813
3814 #. type: TP
3815 #: build/C/man2/perf_event_open.2:1121
3816 #, no-wrap
3817 msgid "I<offset>"
3818 msgstr ""
3819
3820 #.  FIXME clarify
3821 #. type: Plain text
3822 #: build/C/man2/perf_event_open.2:1125
3823 msgid "Add this to hardware counter value??"
3824 msgstr ""
3825
3826 #. type: TP
3827 #: build/C/man2/perf_event_open.2:1125
3828 #, no-wrap
3829 msgid "I<time_enabled>"
3830 msgstr ""
3831
3832 #. type: Plain text
3833 #: build/C/man2/perf_event_open.2:1128
3834 msgid "Time the event was active."
3835 msgstr ""
3836
3837 #. type: TP
3838 #: build/C/man2/perf_event_open.2:1128
3839 #, no-wrap
3840 msgid "I<time_running>"
3841 msgstr ""
3842
3843 #. type: Plain text
3844 #: build/C/man2/perf_event_open.2:1131
3845 msgid "Time the event was running."
3846 msgstr ""
3847
3848 #. type: TP
3849 #: build/C/man2/perf_event_open.2:1131
3850 #, no-wrap
3851 msgid "I<cap_usr_time>"
3852 msgstr ""
3853
3854 #. type: Plain text
3855 #: build/C/man2/perf_event_open.2:1134
3856 msgid "User time capability"
3857 msgstr ""
3858
3859 #. type: TP
3860 #: build/C/man2/perf_event_open.2:1134
3861 #, no-wrap
3862 msgid "I<cap_usr_rdpmc>"
3863 msgstr ""
3864
3865 #. type: Plain text
3866 #: build/C/man2/perf_event_open.2:1139
3867 msgid ""
3868 "If the hardware supports user-space read of performance counters without "
3869 "syscall (this is the \"rdpmc\" instruction on x86), then the following code "
3870 "can be used to do a read:"
3871 msgstr ""
3872
3873 #. type: Plain text
3874 #: build/C/man2/perf_event_open.2:1146
3875 #, no-wrap
3876 msgid ""
3877 "u32 seq, time_mult, time_shift, idx, width;\n"
3878 "u64 count, enabled, running;\n"
3879 "u64 cyc, time_offset;\n"
3880 "s64 pmc = 0;\n"
3881 msgstr ""
3882
3883 #. type: Plain text
3884 #: build/C/man2/perf_event_open.2:1152
3885 #, no-wrap
3886 msgid ""
3887 "do {\n"
3888 "    seq = pc-E<gt>lock;\n"
3889 "    barrier();\n"
3890 "    enabled = pc-E<gt>time_enabled;\n"
3891 "    running = pc-E<gt>time_running;\n"
3892 msgstr ""
3893
3894 #. type: Plain text
3895 #: build/C/man2/perf_event_open.2:1159
3896 #, no-wrap
3897 msgid ""
3898 "    if (pc-E<gt>cap_usr_time && enabled != running) {\n"
3899 "        cyc = rdtsc();\n"
3900 "        time_offset = pc-E<gt>time_offset;\n"
3901 "        time_mult   = pc-E<gt>time_mult;\n"
3902 "        time_shift  = pc-E<gt>time_shift;\n"
3903 "    }\n"
3904 msgstr ""
3905
3906 #. type: Plain text
3907 #: build/C/man2/perf_event_open.2:1162
3908 #, no-wrap
3909 msgid ""
3910 "    idx = pc-E<gt>index;\n"
3911 "    count = pc-E<gt>offset;\n"
3912 msgstr ""
3913
3914 #. type: Plain text
3915 #: build/C/man2/perf_event_open.2:1167
3916 #, no-wrap
3917 msgid ""
3918 "    if (pc-E<gt>cap_usr_rdpmc && idx) {\n"
3919 "        width = pc-E<gt>pmc_width;\n"
3920 "        pmc = rdpmc(idx - 1);\n"
3921 "    }\n"
3922 msgstr ""
3923
3924 #. type: Plain text
3925 #: build/C/man2/perf_event_open.2:1170
3926 #, no-wrap
3927 msgid ""
3928 "    barrier();\n"
3929 "} while (pc-E<gt>lock != seq);\n"
3930 msgstr ""
3931
3932 #. type: TP
3933 #: build/C/man2/perf_event_open.2:1172
3934 #, no-wrap
3935 msgid "I<pmc_width>"
3936 msgstr ""
3937
3938 #. type: Plain text
3939 #: build/C/man2/perf_event_open.2:1179
3940 msgid ""
3941 "If I<cap_usr_rdpmc>, this field provides the bit-width of the value read "
3942 "using the rdpmc or equivalent instruction.  This can be used to sign extend "
3943 "the result like:"
3944 msgstr ""
3945
3946 #. type: Plain text
3947 #: build/C/man2/perf_event_open.2:1185
3948 #, no-wrap
3949 msgid ""
3950 "pmc E<lt>E<lt>= 64 - pmc_width;\n"
3951 "pmc E<gt>E<gt>= 64 - pmc_width; // signed shift right\n"
3952 "count += pmc;\n"
3953 msgstr ""
3954
3955 #. type: TP
3956 #: build/C/man2/perf_event_open.2:1187
3957 #, no-wrap
3958 msgid "I<time_shift>, I<time_mult>, I<time_offset>"
3959 msgstr ""
3960
3961 #. type: Plain text
3962 #: build/C/man2/perf_event_open.2:1194
3963 msgid ""
3964 "If I<cap_usr_time>, these fields can be used to compute the time delta since "
3965 "time_enabled (in nanoseconds) using rdtsc or similar."
3966 msgstr ""
3967
3968 #. type: Plain text
3969 #: build/C/man2/perf_event_open.2:1202
3970 #, no-wrap
3971 msgid ""
3972 "    u64 quot, rem;\n"
3973 "    u64 delta;\n"
3974 "    quot = (cyc E<gt>E<gt> time_shift);\n"
3975 "    rem = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
3976 "    delta = time_offset + quot * time_mult +\n"
3977 "            ((rem * time_mult) E<gt>E<gt> time_shift);\n"
3978 msgstr ""
3979
3980 #. type: Plain text
3981 #: build/C/man2/perf_event_open.2:1214
3982 msgid ""
3983 "Where I<time_offset>, I<time_mult>, I<time_shift>, and I<cyc> are read in "
3984 "the seqcount loop described above.  This delta can then be added to enabled "
3985 "and possible running (if idx), improving the scaling:"
3986 msgstr ""
3987
3988 #. type: Plain text
3989 #: build/C/man2/perf_event_open.2:1222
3990 #, no-wrap
3991 msgid ""
3992 "    enabled += delta;\n"
3993 "    if (idx)\n"
3994 "        running += delta;\n"
3995 "    quot = count / running;\n"
3996 "    rem  = count % running;\n"
3997 "    count = quot * enabled + (rem * enabled) / running;\n"
3998 msgstr ""
3999
4000 #. type: TP
4001 #: build/C/man2/perf_event_open.2:1223
4002 #, no-wrap
4003 msgid "I<data_head>"
4004 msgstr ""
4005
4006 #. type: Plain text
4007 #: build/C/man2/perf_event_open.2:1229
4008 msgid ""
4009 "This points to the head of the data section.  The value continuously "
4010 "increases, it does not wrap.  The value needs to be manually wrapped by the "
4011 "size of the mmap buffer before accessing the samples."
4012 msgstr ""
4013
4014 #. type: Plain text
4015 #: build/C/man2/perf_event_open.2:1232
4016 msgid ""
4017 "On SMP-capable platforms, after reading the data_head value, user space "
4018 "should issue an rmb()."
4019 msgstr ""
4020
4021 #. type: TP
4022 #: build/C/man2/perf_event_open.2:1232
4023 #, no-wrap
4024 msgid "I<data_tail;>"
4025 msgstr ""
4026
4027 #. type: Plain text
4028 #: build/C/man2/perf_event_open.2:1240
4029 msgid ""
4030 "When the mapping is B<PROT_WRITE>, the I<data_tail> value should be written "
4031 "by user space to reflect the last read data.  In this case the kernel will "
4032 "not over-write unread data."
4033 msgstr ""
4034
4035 #. type: Plain text
4036 #: build/C/man2/perf_event_open.2:1242
4037 msgid "The following 2^n ring-buffer pages have the layout described below."
4038 msgstr ""
4039
4040 #. type: Plain text
4041 #: build/C/man2/perf_event_open.2:1256
4042 msgid ""
4043 "If I<perf_event_attr.sample_id_all> is set, then all event types will have "
4044 "the sample_type selected fields related to where/when (identity)  an event "
4045 "took place (TID, TIME, ID, CPU, STREAM_ID) described in "
4046 "B<PERF_RECORD_SAMPLE> below, it will be stashed just after the "
4047 "I<perf_event_header> and the fields already present for the existing fields, "
4048 "i.e., at the end of the payload.  That way a newer perf.data file will be "
4049 "supported by older perf tools, with these new optional fields being ignored."
4050 msgstr ""
4051
4052 #. type: Plain text
4053 #: build/C/man2/perf_event_open.2:1258
4054 msgid "The mmap values start with a header:"
4055 msgstr ""
4056
4057 #. type: Plain text
4058 #: build/C/man2/perf_event_open.2:1266
4059 #, no-wrap
4060 msgid ""
4061 "struct perf_event_header {\n"
4062 "    __u32   type;\n"
4063 "    __u16   misc;\n"
4064 "    __u16   size;\n"
4065 "};\n"
4066 msgstr ""
4067
4068 #. type: Plain text
4069 #: build/C/man2/perf_event_open.2:1272
4070 msgid "Below, we describe the I<perf_event_header> fields in more detail."
4071 msgstr ""
4072
4073 #. type: Plain text
4074 #: build/C/man2/perf_event_open.2:1281
4075 msgid ""
4076 "The I<type> value is one of the below.  The values in the corresponding "
4077 "record (that follows the header)  depend on the I<type> selected as shown."
4078 msgstr ""
4079
4080 #. type: TP
4081 #: build/C/man2/perf_event_open.2:1282
4082 #, no-wrap
4083 msgid "B<PERF_RECORD_MMAP>"
4084 msgstr ""
4085
4086 #. type: Plain text
4087 #: build/C/man2/perf_event_open.2:1289
4088 msgid ""
4089 "The MMAP events record the B<PROT_EXEC> mappings so that we can correlate "
4090 "user-space IPs to code.  They have the following structure:"
4091 msgstr ""
4092
4093 #. type: Plain text
4094 #: build/C/man2/perf_event_open.2:1300
4095 #, no-wrap
4096 msgid ""
4097 "struct {\n"
4098 "    struct perf_event_header header;\n"
4099 "    u32    pid, tid;\n"
4100 "    u64    addr;\n"
4101 "    u64    len;\n"
4102 "    u64    pgoff;\n"
4103 "    char   filename[];\n"
4104 "};\n"
4105 msgstr ""
4106
4107 #. type: TP
4108 #: build/C/man2/perf_event_open.2:1302
4109 #, no-wrap
4110 msgid "B<PERF_RECORD_LOST>"
4111 msgstr ""
4112
4113 #. type: Plain text
4114 #: build/C/man2/perf_event_open.2:1305
4115 msgid "This record indicates when events are lost."
4116 msgstr ""
4117
4118 #. type: Plain text
4119 #: build/C/man2/perf_event_open.2:1313
4120 #, no-wrap
4121 msgid ""
4122 "struct {\n"
4123 "    struct perf_event_header header;\n"
4124 "    u64 id;\n"
4125 "    u64 lost;\n"
4126 "};\n"
4127 msgstr ""
4128
4129 #. type: Plain text
4130 #: build/C/man2/perf_event_open.2:1319
4131 msgid "is the unique event ID for the samples that were lost."
4132 msgstr ""
4133
4134 #. type: TP
4135 #: build/C/man2/perf_event_open.2:1319
4136 #, no-wrap
4137 msgid "I<lost>"
4138 msgstr ""
4139
4140 #. type: Plain text
4141 #: build/C/man2/perf_event_open.2:1322
4142 msgid "is the number of events that were lost."
4143 msgstr ""
4144
4145 #. type: TP
4146 #: build/C/man2/perf_event_open.2:1323
4147 #, no-wrap
4148 msgid "B<PERF_RECORD_COMM>"
4149 msgstr ""
4150
4151 #. type: Plain text
4152 #: build/C/man2/perf_event_open.2:1326
4153 msgid "This record indicates a change in the process name."
4154 msgstr ""
4155
4156 #. type: Plain text
4157 #: build/C/man2/perf_event_open.2:1334
4158 #, no-wrap
4159 msgid ""
4160 "struct {\n"
4161 "    struct perf_event_header header;\n"
4162 "    u32 pid, tid;\n"
4163 "    char comm[];\n"
4164 "};\n"
4165 msgstr ""
4166
4167 #. type: TP
4168 #: build/C/man2/perf_event_open.2:1336
4169 #, no-wrap
4170 msgid "B<PERF_RECORD_EXIT>"
4171 msgstr ""
4172
4173 #. type: Plain text
4174 #: build/C/man2/perf_event_open.2:1339
4175 msgid "This record indicates a process exit event."
4176 msgstr ""
4177
4178 #. type: Plain text
4179 #: build/C/man2/perf_event_open.2:1348 build/C/man2/perf_event_open.2:1376
4180 #, no-wrap
4181 msgid ""
4182 "struct {\n"
4183 "    struct perf_event_header header;\n"
4184 "    u32 pid, ppid;\n"
4185 "    u32 tid, ptid;\n"
4186 "    u64 time;\n"
4187 "};\n"
4188 msgstr ""
4189
4190 #. type: TP
4191 #: build/C/man2/perf_event_open.2:1350
4192 #, no-wrap
4193 msgid "B<PERF_RECORD_THROTTLE>, B<PERF_RECORD_UNTHROTTLE>"
4194 msgstr ""
4195
4196 #. type: Plain text
4197 #: build/C/man2/perf_event_open.2:1353
4198 msgid "This record indicates a throttle/unthrottle event."
4199 msgstr ""
4200
4201 #. type: Plain text
4202 #: build/C/man2/perf_event_open.2:1362
4203 #, no-wrap
4204 msgid ""
4205 "struct {\n"
4206 "    struct perf_event_header header;\n"
4207 "    u64 time;\n"
4208 "    u64 id;\n"
4209 "    u64 stream_id;\n"
4210 "};\n"
4211 msgstr ""
4212
4213 #. type: TP
4214 #: build/C/man2/perf_event_open.2:1364
4215 #, no-wrap
4216 msgid "B<PERF_RECORD_FORK>"
4217 msgstr ""
4218
4219 #. type: Plain text
4220 #: build/C/man2/perf_event_open.2:1367
4221 msgid "This record indicates a fork event."
4222 msgstr ""
4223
4224 #. type: TP
4225 #: build/C/man2/perf_event_open.2:1378
4226 #, no-wrap
4227 msgid "B<PERF_RECORD_READ>"
4228 msgstr ""
4229
4230 #. type: Plain text
4231 #: build/C/man2/perf_event_open.2:1381
4232 msgid "This record indicates a read event."
4233 msgstr ""
4234
4235 #. type: Plain text
4236 #: build/C/man2/perf_event_open.2:1389
4237 #, no-wrap
4238 msgid ""
4239 "struct {\n"
4240 "    struct perf_event_header header;\n"
4241 "    u32 pid, tid;\n"
4242 "    struct read_format values;\n"
4243 "};\n"
4244 msgstr ""
4245
4246 #. type: TP
4247 #: build/C/man2/perf_event_open.2:1391
4248 #, no-wrap
4249 msgid "B<PERF_RECORD_SAMPLE>"
4250 msgstr ""
4251
4252 #. type: Plain text
4253 #: build/C/man2/perf_event_open.2:1394
4254 msgid "This record indicates a sample."
4255 msgstr ""
4256
4257 #. type: Plain text
4258 #: build/C/man2/perf_event_open.2:1422
4259 #, no-wrap
4260 msgid ""
4261 "struct {\n"
4262 "    struct perf_event_header header;\n"
4263 "    u64   ip;         /* if PERF_SAMPLE_IP */\n"
4264 "    u32   pid, tid;   /* if PERF_SAMPLE_TID */\n"
4265 "    u64   time;       /* if PERF_SAMPLE_TIME */\n"
4266 "    u64   addr;       /* if PERF_SAMPLE_ADDR */\n"
4267 "    u64   id;         /* if PERF_SAMPLE_ID */\n"
4268 "    u64   stream_id;  /* if PERF_SAMPLE_STREAM_ID */\n"
4269 "    u32   cpu, res;   /* if PERF_SAMPLE_CPU */\n"
4270 "    u64   period;     /* if PERF_SAMPLE_PERIOD */\n"
4271 "    struct read_format v; /* if PERF_SAMPLE_READ */\n"
4272 "    u64   nr;         /* if PERF_SAMPLE_CALLCHAIN */\n"
4273 "    u64   ips[nr];    /* if PERF_SAMPLE_CALLCHAIN */\n"
4274 "    u32   size;       /* if PERF_SAMPLE_RAW */\n"
4275 "    char  data[size]; /* if PERF_SAMPLE_RAW */\n"
4276 "    u64   bnr;        /* if PERF_SAMPLE_BRANCH_STACK */\n"
4277 "    struct perf_branch_entry lbr[bnr];\n"
4278 "                      /* if PERF_SAMPLE_BRANCH_STACK */\n"
4279 "    u64   abi;        /* if PERF_SAMPLE_REGS_USER */\n"
4280 "    u64   regs[weight(mask)];\n"
4281 "                      /* if PERF_SAMPLE_REGS_USER */\n"
4282 "    u64   size;       /* if PERF_SAMPLE_STACK_USER */\n"
4283 "    char  data[size]; /* if PERF_SAMPLE_STACK_USER */\n"
4284 "    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */\n"
4285 "};\n"
4286 msgstr ""
4287
4288 #. type: TP
4289 #: build/C/man2/perf_event_open.2:1424
4290 #, no-wrap
4291 msgid "I<ip>"
4292 msgstr ""
4293
4294 #. type: Plain text
4295 #: build/C/man2/perf_event_open.2:1430
4296 msgid ""
4297 "If B<PERF_SAMPLE_IP> is enabled, then a 64-bit instruction pointer value is "
4298 "included."
4299 msgstr ""
4300
4301 #. type: TP
4302 #: build/C/man2/perf_event_open.2:1430
4303 #, no-wrap
4304 msgid "I<pid>, I<tid>"
4305 msgstr ""
4306
4307 #. type: Plain text
4308 #: build/C/man2/perf_event_open.2:1436
4309 msgid ""
4310 "If B<PERF_SAMPLE_TID> is enabled, then a 32-bit process ID and 32-bit thread "
4311 "ID are included."
4312 msgstr ""
4313
4314 #. type: TP
4315 #: build/C/man2/perf_event_open.2:1436
4316 #, no-wrap
4317 msgid "I<time>"
4318 msgstr ""
4319
4320 #. type: Plain text
4321 #: build/C/man2/perf_event_open.2:1444
4322 msgid ""
4323 "If B<PERF_SAMPLE_TIME> is enabled, then a 64-bit timestamp is included.  "
4324 "This is obtained via local_clock() which is a hardware timestamp if "
4325 "available and the jiffies value if not."
4326 msgstr ""
4327
4328 #. type: TP
4329 #: build/C/man2/perf_event_open.2:1444
4330 #, no-wrap
4331 msgid "I<addr>"
4332 msgstr ""
4333
4334 #. type: Plain text
4335 #: build/C/man2/perf_event_open.2:1451
4336 msgid ""
4337 "If B<PERF_SAMPLE_ADDR> is enabled, then a 64-bit address is included.  This "
4338 "is usually the address of a tracepoint, breakpoint, or software event; "
4339 "otherwise the value is 0."
4340 msgstr ""
4341
4342 #. type: Plain text
4343 #: build/C/man2/perf_event_open.2:1459
4344 msgid ""
4345 "If B<PERF_SAMPLE_ID> is enabled, a 64-bit unique ID is included.  If the "
4346 "event is a member of an event group, the group leader ID is returned.  This "
4347 "ID is the same as the one returned by B<PERF_FORMAT_ID>."
4348 msgstr ""
4349
4350 #. type: TP
4351 #: build/C/man2/perf_event_open.2:1459
4352 #, no-wrap
4353 msgid "I<stream_id>"
4354 msgstr ""
4355
4356 #. type: Plain text
4357 #: build/C/man2/perf_event_open.2:1469
4358 msgid ""
4359 "If B<PERF_SAMPLE_STREAM_ID> is enabled, a 64-bit unique ID is included.  "
4360 "Unlike B<PERF_SAMPLE_ID> the actual ID is returned, not the group leader.  "
4361 "This ID is the same as the one returned by B<PERF_FORMAT_ID>."
4362 msgstr ""
4363
4364 #. type: TP
4365 #: build/C/man2/perf_event_open.2:1469
4366 #, no-wrap
4367 msgid "I<cpu>, I<res>"
4368 msgstr ""
4369
4370 #. type: Plain text
4371 #: build/C/man2/perf_event_open.2:1476
4372 msgid ""
4373 "If B<PERF_SAMPLE_CPU> is enabled, this is a 32-bit value indicating which "
4374 "CPU was being used, in addition to a reserved (unused)  32-bit value."
4375 msgstr ""
4376
4377 #. type: TP
4378 #: build/C/man2/perf_event_open.2:1476
4379 #, no-wrap
4380 msgid "I<period>"
4381 msgstr ""
4382
4383 #. type: Plain text
4384 #: build/C/man2/perf_event_open.2:1482
4385 msgid ""
4386 "If B<PERF_SAMPLE_PERIOD> is enabled, a 64-bit value indicating the current "
4387 "sampling period is written."
4388 msgstr ""
4389
4390 #. type: TP
4391 #: build/C/man2/perf_event_open.2:1482
4392 #, no-wrap
4393 msgid "I<v>"
4394 msgstr ""
4395
4396 #. type: Plain text
4397 #: build/C/man2/perf_event_open.2:1493
4398 msgid ""
4399 "If B<PERF_SAMPLE_READ> is enabled, a structure of type read_format is "
4400 "included which has values for all events in the event group.  The values "
4401 "included depend on the I<read_format> value used at B<perf_event_open>()  "
4402 "time."
4403 msgstr ""
4404
4405 #. type: TP
4406 #: build/C/man2/perf_event_open.2:1493
4407 #, no-wrap
4408 msgid "I<nr>, I<ips[nr]>"
4409 msgstr ""
4410
4411 #. type: Plain text
4412 #: build/C/man2/perf_event_open.2:1501
4413 msgid ""
4414 "If B<PERF_SAMPLE_CALLCHAIN> is enabled, then a 64-bit number is included "
4415 "which indicates how many following 64-bit instruction pointers will follow.  "
4416 "This is the current callchain."
4417 msgstr ""
4418
4419 #. type: TP
4420 #: build/C/man2/perf_event_open.2:1501
4421 #, no-wrap
4422 msgid "I<size>, I<data[size]>"
4423 msgstr ""
4424
4425 #. type: Plain text
4426 #: build/C/man2/perf_event_open.2:1508
4427 msgid ""
4428 "If B<PERF_SAMPLE_RAW> is enabled, then a 32-bit value indicating size is "
4429 "included followed by an array of 8-bit values of length size.  The values "
4430 "are padded with 0 to have 64-bit alignment."
4431 msgstr ""
4432
4433 #. type: Plain text
4434 #: build/C/man2/perf_event_open.2:1513
4435 msgid ""
4436 "This RAW record data is opaque with respect to the ABI.  The ABI doesn't "
4437 "make any promises with respect to the stability of its content, it may vary "
4438 "depending on event, hardware, and kernel version."
4439 msgstr ""
4440
4441 #. type: TP
4442 #: build/C/man2/perf_event_open.2:1513
4443 #, no-wrap
4444 msgid "I<bnr>, I<lbr[bnr]>"
4445 msgstr ""
4446
4447 #. type: Plain text
4448 #: build/C/man2/perf_event_open.2:1524
4449 msgid ""
4450 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then a 64-bit value indicating "
4451 "the number of records is included, followed by I<bnr> I<perf_branch_entry> "
4452 "structures.  These structures have from, to, and flags values indicating the "
4453 "from and to addresses from the branches on the callstack."
4454 msgstr ""
4455
4456 #. type: TP
4457 #: build/C/man2/perf_event_open.2:1524
4458 #, no-wrap
4459 msgid "I<abi>, I<regs[weight(mask)]>"
4460 msgstr ""
4461
4462 #. type: Plain text
4463 #: build/C/man2/perf_event_open.2:1530
4464 msgid "If B<PERF_SAMPLE_REGS_USER> is enabled, then [to be documented]."
4465 msgstr ""
4466
4467 #. type: Plain text
4468 #: build/C/man2/perf_event_open.2:1536
4469 msgid ""
4470 "The I<abi> field is one of B<PERF_SAMPLE_REGS_ABI_NONE>, "
4471 "B<PERF_SAMPLE_REGS_ABI_32> or B<PERF_SAMPLE_REGS_ABI_64>."
4472 msgstr ""
4473
4474 #. type: TP
4475 #: build/C/man2/perf_event_open.2:1536
4476 #, no-wrap
4477 msgid "I<size>, I<data[size]>, I<dyn_size>"
4478 msgstr ""
4479
4480 #. type: Plain text
4481 #: build/C/man2/perf_event_open.2:1542
4482 msgid "If B<PERF_SAMPLE_STACK_USER> is enabled, then [to be documented]."
4483 msgstr ""
4484
4485 #. type: TP
4486 #: build/C/man2/perf_event_open.2:1544
4487 #, no-wrap
4488 msgid "I<misc>"
4489 msgstr ""
4490
4491 #. type: Plain text
4492 #: build/C/man2/perf_event_open.2:1549
4493 msgid "The I<misc> field contains additional information about the sample."
4494 msgstr ""
4495
4496 #. type: Plain text
4497 #: build/C/man2/perf_event_open.2:1554
4498 msgid ""
4499 "The CPU mode can be determined from this value by masking with "
4500 "B<PERF_RECORD_MISC_CPUMODE_MASK> and looking for one of the following (note "
4501 "these are not bit masks, only one can be set at a time):"
4502 msgstr ""
4503
4504 #. type: TP
4505 #: build/C/man2/perf_event_open.2:1555
4506 #, no-wrap
4507 msgid "B<PERF_RECORD_MISC_CPUMODE_UNKNOWN>"
4508 msgstr ""
4509
4510 #. type: Plain text
4511 #: build/C/man2/perf_event_open.2:1558
4512 msgid "Unknown CPU mode."
4513 msgstr ""
4514
4515 #. type: TP
4516 #: build/C/man2/perf_event_open.2:1558
4517 #, no-wrap
4518 msgid "B<PERF_RECORD_MISC_KERNEL>"
4519 msgstr ""
4520
4521 #. type: Plain text
4522 #: build/C/man2/perf_event_open.2:1561
4523 msgid "Sample happened in the kernel."
4524 msgstr ""
4525
4526 #. type: TP
4527 #: build/C/man2/perf_event_open.2:1561
4528 #, no-wrap
4529 msgid "B<PERF_RECORD_MISC_USER>"
4530 msgstr ""
4531
4532 #. type: Plain text
4533 #: build/C/man2/perf_event_open.2:1564
4534 msgid "Sample happened in user code."
4535 msgstr ""
4536
4537 #. type: TP
4538 #: build/C/man2/perf_event_open.2:1564
4539 #, no-wrap
4540 msgid "B<PERF_RECORD_MISC_HYPERVISOR>"
4541 msgstr ""
4542
4543 #. type: Plain text
4544 #: build/C/man2/perf_event_open.2:1567
4545 msgid "Sample happened in the hypervisor."
4546 msgstr ""
4547
4548 #. type: TP
4549 #: build/C/man2/perf_event_open.2:1567
4550 #, no-wrap
4551 msgid "B<PERF_RECORD_MISC_GUEST_KERNEL>"
4552 msgstr ""
4553
4554 #. type: Plain text
4555 #: build/C/man2/perf_event_open.2:1570
4556 msgid "Sample happened in the guest kernel."
4557 msgstr ""
4558
4559 #. type: TP
4560 #: build/C/man2/perf_event_open.2:1570
4561 #, no-wrap
4562 msgid "B<PERF_RECORD_MISC_GUEST_USER>"
4563 msgstr ""
4564
4565 #. type: Plain text
4566 #: build/C/man2/perf_event_open.2:1573
4567 msgid "Sample happened in guest user code."
4568 msgstr ""
4569
4570 #. type: Plain text
4571 #: build/C/man2/perf_event_open.2:1576
4572 msgid "In addition, one of the following bits can be set:"
4573 msgstr ""
4574
4575 #. type: TP
4576 #: build/C/man2/perf_event_open.2:1577
4577 #, no-wrap
4578 msgid "B<PERF_RECORD_MISC_EXACT_IP>"
4579 msgstr ""
4580
4581 #. type: Plain text
4582 #: build/C/man2/perf_event_open.2:1585
4583 msgid ""
4584 "This indicates that the content of B<PERF_SAMPLE_IP> points to the actual "
4585 "instruction that triggered the event.  See also "
4586 "I<perf_event_attr.precise_ip>."
4587 msgstr ""
4588
4589 #. type: TP
4590 #: build/C/man2/perf_event_open.2:1585
4591 #, no-wrap
4592 msgid "B<PERF_RECORD_MISC_EXT_RESERVED>"
4593 msgstr ""
4594
4595 #. type: Plain text
4596 #: build/C/man2/perf_event_open.2:1588
4597 msgid "This indicates there is extended data available (currently not used)."
4598 msgstr ""
4599
4600 #. type: Plain text
4601 #: build/C/man2/perf_event_open.2:1591
4602 msgid "This indicates the size of the record."
4603 msgstr ""
4604
4605 #. type: SS
4606 #: build/C/man2/perf_event_open.2:1592
4607 #, no-wrap
4608 msgid "Signal overflow"
4609 msgstr ""
4610
4611 #. type: Plain text
4612 #: build/C/man2/perf_event_open.2:1601
4613 msgid ""
4614 "Events can be set to deliver a signal when a threshold is crossed.  The "
4615 "signal handler is set up using the B<poll>(2), B<select>(2), B<epoll>(2)  "
4616 "and B<fcntl>(2), system calls."
4617 msgstr ""
4618
4619 #. type: Plain text
4620 #: build/C/man2/perf_event_open.2:1605
4621 msgid ""
4622 "To generate signals, sampling must be enabled (I<sample_period> must have a "
4623 "non-zero value)."
4624 msgstr ""
4625
4626 #. type: Plain text
4627 #: build/C/man2/perf_event_open.2:1607
4628 msgid "There are two ways to generate signals."
4629 msgstr ""
4630
4631 #. type: Plain text
4632 #: build/C/man2/perf_event_open.2:1617
4633 msgid ""
4634 "The first is to set a I<wakeup_events> or I<wakeup_watermark> value that "
4635 "will generate a signal if a certain number of samples or bytes have been "
4636 "written to the mmap ring buffer.  In this case a signal of type B<POLL_IN> "
4637 "is sent."
4638 msgstr ""
4639
4640 #. type: Plain text
4641 #: build/C/man2/perf_event_open.2:1629
4642 msgid ""
4643 "The other way is by use of the B<PERF_EVENT_IOC_REFRESH> ioctl.  This ioctl "
4644 "adds to a counter that decrements each time the event overflows.  When "
4645 "non-zero, a B<POLL_IN> signal is sent on overflow, but once the value "
4646 "reaches 0, a signal is sent of type B<POLL_HUP> and the underlying event is "
4647 "disabled."
4648 msgstr ""
4649
4650 #.  FIXME(Vince) : Find out when this was introduced
4651 #. type: Plain text
4652 #: build/C/man2/perf_event_open.2:1635
4653 msgid ""
4654 "Note: on newer kernels (definitely noticed with 3.2)  a signal is provided "
4655 "for every overflow, even if I<wakeup_events> is not set."
4656 msgstr ""
4657
4658 #. type: SS
4659 #: build/C/man2/perf_event_open.2:1635
4660 #, no-wrap
4661 msgid "rdpmc instruction"
4662 msgstr ""
4663
4664 #. type: Plain text
4665 #: build/C/man2/perf_event_open.2:1642
4666 msgid ""
4667 "Starting with Linux 3.4 on x86, you can use the I<rdpmc> instruction to get "
4668 "low-latency reads without having to enter the kernel.  Note that using "
4669 "I<rdpmc> is not necessarily faster than other methods for reading event "
4670 "values."
4671 msgstr ""
4672
4673 #. type: Plain text
4674 #: build/C/man2/perf_event_open.2:1647
4675 msgid ""
4676 "Support for this can be detected with the I<cap_usr_rdpmc> field in the mmap "
4677 "page; documentation on how to calculate event values can be found in that "
4678 "section."
4679 msgstr ""
4680
4681 #. type: SS
4682 #: build/C/man2/perf_event_open.2:1647
4683 #, no-wrap
4684 msgid "perf_event ioctl calls"
4685 msgstr ""
4686
4687 #. type: Plain text
4688 #: build/C/man2/perf_event_open.2:1652
4689 msgid "Various ioctls act on B<perf_event_open>()  file descriptors"
4690 msgstr ""
4691
4692 #. type: TP
4693 #: build/C/man2/perf_event_open.2:1652
4694 #, no-wrap
4695 msgid "B<PERF_EVENT_IOC_ENABLE>"
4696 msgstr ""
4697
4698 #. type: Plain text
4699 #: build/C/man2/perf_event_open.2:1656
4700 msgid ""
4701 "Enables the individual event or event group specified by the file descriptor "
4702 "argument."
4703 msgstr ""
4704
4705 #. type: Plain text
4706 #: build/C/man2/perf_event_open.2:1658 build/C/man2/perf_event_open.2:1671 build/C/man2/perf_event_open.2:1699
4707 msgid "The ioctl argument is ignored."
4708 msgstr ""
4709
4710 #. type: TP
4711 #: build/C/man2/perf_event_open.2:1658
4712 #, no-wrap
4713 msgid "B<PERF_EVENT_IOC_DISABLE>"
4714 msgstr ""
4715
4716 #. type: Plain text
4717 #: build/C/man2/perf_event_open.2:1662
4718 msgid ""
4719 "Disables the individual counter or event group specified by the file "
4720 "descriptor argument."
4721 msgstr ""
4722
4723 #. type: Plain text
4724 #: build/C/man2/perf_event_open.2:1669
4725 msgid ""
4726 "Enabling or disabling the leader of a group enables or disables the entire "
4727 "group; that is, while the group leader is disabled, none of the counters in "
4728 "the group will count.  Enabling or disabling a member of a group other than "
4729 "the leader only affects that counter; disabling a non-leader stops that "
4730 "counter from counting but doesn't affect any other counter."
4731 msgstr ""
4732
4733 #. type: TP
4734 #: build/C/man2/perf_event_open.2:1671
4735 #, no-wrap
4736 msgid "B<PERF_EVENT_IOC_REFRESH>"
4737 msgstr ""
4738
4739 #. type: Plain text
4740 #: build/C/man2/perf_event_open.2:1685
4741 msgid ""
4742 "Non-inherited overflow counters can use this to enable a counter for a "
4743 "number of overflows specified by the argument, after which it is disabled.  "
4744 "Subsequent calls of this ioctl add the argument value to the current count.  "
4745 "A signal with B<POLL_IN> set will happen on each overflow until the count "
4746 "reaches 0; when that happens a signal with POLL_HUP set is sent and the "
4747 "event is disabled.  Using an argument of 0 is considered undefined behavior."
4748 msgstr ""
4749
4750 #. type: TP
4751 #: build/C/man2/perf_event_open.2:1685
4752 #, no-wrap
4753 msgid "B<PERF_EVENT_IOC_RESET>"
4754 msgstr ""
4755
4756 #. type: Plain text
4757 #: build/C/man2/perf_event_open.2:1697
4758 msgid ""
4759 "Reset the event count specified by the file descriptor argumentto zero.  "
4760 "This only resets the counts; there is no way to reset the multiplexing "
4761 "I<time_enabled> or I<time_running> values.  When sent to a group leader, "
4762 "only the leader is reset (child events are not)."
4763 msgstr ""
4764
4765 #. type: TP
4766 #: build/C/man2/perf_event_open.2:1699
4767 #, no-wrap
4768 msgid "B<PERF_EVENT_IOC_PERIOD>"
4769 msgstr ""
4770
4771 #. type: Plain text
4772 #: build/C/man2/perf_event_open.2:1703
4773 msgid ""
4774 "IOC_PERIOD is the command to update the period; it does not update the "
4775 "current period but instead defers until next."
4776 msgstr ""
4777
4778 #. type: Plain text
4779 #: build/C/man2/perf_event_open.2:1706
4780 msgid ""
4781 "The argument is a pointer to a 64-bit value containing the desired new "
4782 "period."
4783 msgstr ""
4784
4785 #. type: TP
4786 #: build/C/man2/perf_event_open.2:1706
4787 #, no-wrap
4788 msgid "B<PERF_EVENT_IOC_SET_OUTPUT>"
4789 msgstr ""
4790
4791 #. type: Plain text
4792 #: build/C/man2/perf_event_open.2:1711
4793 msgid ""
4794 "This tells the kernel to report event notifications to the specified file "
4795 "descriptor rather than the default one.  The file descriptors must all be on "
4796 "the same CPU."
4797 msgstr ""
4798
4799 #. type: Plain text
4800 #: build/C/man2/perf_event_open.2:1714
4801 msgid ""
4802 "The argument specifies the desired file descriptor, or -1 if output should "
4803 "be ignored."
4804 msgstr ""
4805
4806 #. type: TP
4807 #: build/C/man2/perf_event_open.2:1714
4808 #, no-wrap
4809 msgid "B<PERF_EVENT_IOC_SET_FILTER> (Since Linux 2.6.33)"
4810 msgstr ""
4811
4812 #. type: Plain text
4813 #: build/C/man2/perf_event_open.2:1717
4814 msgid "This adds an ftrace filter to this event."
4815 msgstr ""
4816
4817 #. type: Plain text
4818 #: build/C/man2/perf_event_open.2:1719
4819 msgid "The argument is a pointer to the desired ftrace filter."
4820 msgstr ""
4821
4822 #. type: SS
4823 #: build/C/man2/perf_event_open.2:1719
4824 #, no-wrap
4825 msgid "Using prctl"
4826 msgstr ""
4827
4828 #. type: Plain text
4829 #: build/C/man2/perf_event_open.2:1732
4830 msgid ""
4831 "A process can enable or disable all the event groups that are attached to it "
4832 "using the B<prctl>(2)  B<PR_TASK_PERF_EVENTS_ENABLE> and "
4833 "B<PR_TASK_PERF_EVENTS_DISABLE> operations.  This applies to all counters on "
4834 "the current process, whether created by this process or by another, and does "
4835 "not affect any counters that this process has created on other processes.  "
4836 "It only enables or disables the group leaders, not any other members in the "
4837 "groups."
4838 msgstr ""
4839
4840 #. type: SS
4841 #: build/C/man2/perf_event_open.2:1732
4842 #, no-wrap
4843 msgid "perf_event related configuration files"
4844 msgstr ""
4845
4846 #. type: Plain text
4847 #: build/C/man2/perf_event_open.2:1735
4848 msgid "Files in I</proc/sys/kernel/>"
4849 msgstr ""
4850
4851 #. type: TP
4852 #: build/C/man2/perf_event_open.2:1736
4853 #, no-wrap
4854 msgid "I</proc/sys/kernel/perf_event_paranoid>"
4855 msgstr ""
4856
4857 #. type: Plain text
4858 #: build/C/man2/perf_event_open.2:1742
4859 msgid ""
4860 "The I<perf_event_paranoid> file can be set to restrict access to the "
4861 "performance counters."
4862 msgstr ""
4863
4864 #. type: Plain text
4865 #: build/C/man2/perf_event_open.2:1744
4866 msgid "2 - only allow user-space measurements"
4867 msgstr ""
4868
4869 #. type: Plain text
4870 #: build/C/man2/perf_event_open.2:1746
4871 msgid "1 - (default) allow both kernel and user measurements"
4872 msgstr ""
4873
4874 #. type: Plain text
4875 #: build/C/man2/perf_event_open.2:1748
4876 msgid "0 - allow access to CPU-specific data but not raw tracepoint samples"
4877 msgstr ""
4878
4879 #. type: Plain text
4880 #: build/C/man2/perf_event_open.2:1750
4881 msgid "-1 - no restrictions"
4882 msgstr ""
4883
4884 #. type: Plain text
4885 #: build/C/man2/perf_event_open.2:1755
4886 msgid ""
4887 "The existence of the I<perf_event_paranoid> file is the official method for "
4888 "determining if a kernel supports B<perf_event_open>()."
4889 msgstr ""
4890
4891 #. type: TP
4892 #: build/C/man2/perf_event_open.2:1755
4893 #, no-wrap
4894 msgid "I</proc/sys/kernel/perf_event_max_sample_rate>"
4895 msgstr ""
4896
4897 #. type: Plain text
4898 #: build/C/man2/perf_event_open.2:1764
4899 msgid ""
4900 "This sets the maximum sample rate.  Setting this too high can allow users to "
4901 "sample at a rate that impacts overall machine performance and potentially "
4902 "lock up the machine.  The default value is 100000 (samples per second)."
4903 msgstr ""
4904
4905 #. type: TP
4906 #: build/C/man2/perf_event_open.2:1764
4907 #, no-wrap
4908 msgid "I</proc/sys/kernel/perf_event_mlock_kb>"
4909 msgstr ""
4910
4911 #. type: Plain text
4912 #: build/C/man2/perf_event_open.2:1769
4913 msgid ""
4914 "Maximum number of pages an unprivileged user can mlock (2) .  The default is "
4915 "516 (kB)."
4916 msgstr ""
4917
4918 #. type: Plain text
4919 #: build/C/man2/perf_event_open.2:1772
4920 msgid "Files in I</sys/bus/event_source/devices/>"
4921 msgstr ""
4922
4923 #. type: Plain text
4924 #: build/C/man2/perf_event_open.2:1778
4925 msgid ""
4926 "Since Linux 2.6.34 the kernel supports having multiple PMUs available for "
4927 "monitoring.  Information on how to program these PMUs can be found under "
4928 "I</sys/bus/event_source/devices/>.  Each subdirectory corresponds to a "
4929 "different PMU."
4930 msgstr ""
4931
4932 #. type: TP
4933 #: build/C/man2/perf_event_open.2:1778
4934 #, no-wrap
4935 msgid "I</sys/bus/event_source/devices/*/type>"
4936 msgstr ""
4937
4938 #. type: Plain text
4939 #: build/C/man2/perf_event_open.2:1783
4940 msgid ""
4941 "This contains an integer that can be used in the I<type> field of "
4942 "perf_event_attr to indicate you wish to use this PMU."
4943 msgstr ""
4944
4945 #. type: TP
4946 #: build/C/man2/perf_event_open.2:1783
4947 #, no-wrap
4948 msgid "I</sys/bus/event_source/devices/*/rdpmc>"
4949 msgstr ""
4950
4951 #. type: TP
4952 #: build/C/man2/perf_event_open.2:1786
4953 #, no-wrap
4954 msgid "I</sys/bus/event_source/devices/*/format/>"
4955 msgstr ""
4956
4957 #. type: Plain text
4958 #: build/C/man2/perf_event_open.2:1791
4959 msgid ""
4960 "This sub-directory contains information on what bits in the I<config> field "
4961 "of perf_event_attr correspond to."
4962 msgstr ""
4963
4964 #. type: TP
4965 #: build/C/man2/perf_event_open.2:1791
4966 #, no-wrap
4967 msgid "I</sys/bus/event_source/devices/*/events/>"
4968 msgstr ""
4969
4970 #. type: Plain text
4971 #: build/C/man2/perf_event_open.2:1800
4972 msgid ""
4973 "This sub-directory contains files with pre-defined events.  The contents are "
4974 "strings describing the event settings expressed in terms of the fields found "
4975 "in the I<./format/> directory.  These are not necessarily complete lists of "
4976 "all events supported by a PMU, but usually a subset of events deemed useful "
4977 "or interesting."
4978 msgstr ""
4979
4980 #. type: TP
4981 #: build/C/man2/perf_event_open.2:1800
4982 #, no-wrap
4983 msgid "I</sys/bus/event_source/devices/*/uevent>"
4984 msgstr ""
4985
4986 #. type: Plain text
4987 #: build/C/man2/perf_event_open.2:1810
4988 msgid ""
4989 "B<perf_event_open>()  returns the new file descriptor, or -1 if an error "
4990 "occurred (in which case, I<errno> is set appropriately)."
4991 msgstr ""
4992
4993 #. type: Plain text
4994 #: build/C/man2/perf_event_open.2:1814
4995 msgid "Returned if the specified event is not available."
4996 msgstr ""
4997
4998 #. type: TP
4999 #: build/C/man2/perf_event_open.2:1814
5000 #, no-wrap
5001 msgid "B<ENOSPC>"
5002 msgstr ""
5003
5004 #. type: Plain text
5005 #: build/C/man2/perf_event_open.2:1824
5006 msgid ""
5007 "Prior to Linux 3.3, if there was not enough room for the event, B<ENOSPC> "
5008 "was returned.  Linus did not like this, and this was changed to B<EINVAL>.  "
5009 "B<ENOSPC> is still returned if you try to read results into too small of a "
5010 "buffer."
5011 msgstr ""
5012
5013 #. type: SH
5014 #: build/C/man2/perf_event_open.2:1824
5015 #, no-wrap
5016 msgid "VERSION"
5017 msgstr ""
5018
5019 #. type: Plain text
5020 #: build/C/man2/perf_event_open.2:1829
5021 msgid ""
5022 "B<perf_event_open>()  was introduced in Linux 2.6.31 but was called "
5023 "B<perf_counter_open>()B<.> It was renamed in Linux 2.6.32."
5024 msgstr ""
5025
5026 #. type: Plain text
5027 #: build/C/man2/perf_event_open.2:1834
5028 msgid ""
5029 "This B<perf_event_open>()  system call Linux- specific and should not be "
5030 "used in programs intended to be portable."
5031 msgstr ""
5032
5033 #. type: Plain text
5034 #: build/C/man2/perf_event_open.2:1838
5035 msgid ""
5036 "Glibc does not provide a wrapper for this system call; call it using "
5037 "B<syscall>(2).  See the example below."
5038 msgstr ""
5039
5040 #. type: Plain text
5041 #: build/C/man2/perf_event_open.2:1844
5042 msgid ""
5043 "The official way of knowing if B<perf_event_open>()  support is enabled is "
5044 "checking for the existence of the file "
5045 "I</proc/sys/kernel/perf_event_paranoid>."
5046 msgstr ""
5047
5048 #. type: SH
5049 #: build/C/man2/perf_event_open.2:1844 build/C/man2/pivot_root.2:134 build/C/man2/ptrace.2:1810
5050 #, no-wrap
5051 msgid "BUGS"
5052 msgstr ""
5053
5054 #. type: Plain text
5055 #: build/C/man2/perf_event_open.2:1851
5056 msgid ""
5057 "The B<F_SETOWN_EX> option to B<fcntl>(2)  is needed to properly get overflow "
5058 "signals in threads.  This was introduced in Linux 2.6.32."
5059 msgstr ""
5060
5061 #. type: Plain text
5062 #: build/C/man2/perf_event_open.2:1859
5063 msgid ""
5064 "Prior to Linux 2.6.33 (at least for x86) the kernel did not check if events "
5065 "could be scheduled together until read time.  The same happens on all known "
5066 "kernels if the NMI watchdog is enabled.  This means to see if a given set of "
5067 "events works you have to B<perf_event_open>(), start, then read before you "
5068 "know for sure you can get valid measurements."
5069 msgstr ""
5070
5071 #. type: Plain text
5072 #: build/C/man2/perf_event_open.2:1863
5073 msgid ""
5074 "Prior to Linux 2.6.34 event constraints were not enforced by the kernel.  In "
5075 "that case, some events would silently return \"0\" if the kernel scheduled "
5076 "them in an improper counter slot."
5077 msgstr ""
5078
5079 #. type: Plain text
5080 #: build/C/man2/perf_event_open.2:1866
5081 msgid ""
5082 "Prior to Linux 2.6.34 there was a bug when multiplexing where the wrong "
5083 "results could be returned."
5084 msgstr ""
5085
5086 #. type: Plain text
5087 #: build/C/man2/perf_event_open.2:1869
5088 msgid ""
5089 "Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "
5090 "\"inherit\" is enabled and many threads are started."
5091 msgstr ""
5092
5093 #. type: Plain text
5094 #: build/C/man2/perf_event_open.2:1873
5095 msgid ""
5096 "Prior to Linux 2.6.35, B<PERF_FORMAT_GROUP> did not work with attached "
5097 "processes."
5098 msgstr ""
5099
5100 #. type: Plain text
5101 #: build/C/man2/perf_event_open.2:1878
5102 msgid ""
5103 "In older Linux 2.6 versions, refreshing an event group leader refreshed all "
5104 "siblings, and refreshing with a parameter of 0 enabled infinite refresh.  "
5105 "This behavior is unsupported and should not be relied on."
5106 msgstr ""
5107
5108 #. type: Plain text
5109 #: build/C/man2/perf_event_open.2:1884
5110 msgid ""
5111 "There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that "
5112 "ignores the \"watermark\" field and acts as if a wakeup_event was chosen if "
5113 "the union has a non-zero value in it."
5114 msgstr ""
5115
5116 #. type: Plain text
5117 #: build/C/man2/perf_event_open.2:1889
5118 msgid ""
5119 "Always double-check your results! Various generalized events have had wrong "
5120 "values.  For example, retired branches measured the wrong thing on AMD "
5121 "machines until Linux 2.6.35."
5122 msgstr ""
5123
5124 #. type: SH
5125 #: build/C/man2/perf_event_open.2:1889 build/C/man2/process_vm_readv.2:295 build/C/man2/splice.2:223 build/C/man2/tee.2:130
5126 #, no-wrap
5127 msgid "EXAMPLE"
5128 msgstr ""
5129
5130 #. type: Plain text
5131 #: build/C/man2/perf_event_open.2:1893
5132 msgid ""
5133 "The following is a short example that measures the total instruction count "
5134 "of a call to B<printf>(3)."
5135 msgstr ""
5136
5137 #. type: Plain text
5138 #: build/C/man2/perf_event_open.2:1902
5139 #, no-wrap
5140 msgid ""
5141 "#include E<lt>stdlib.hE<gt>\n"
5142 "#include E<lt>stdio.hE<gt>\n"
5143 "#include E<lt>unistd.hE<gt>\n"
5144 "#include E<lt>string.hE<gt>\n"
5145 "#include E<lt>sys/ioctl.hE<gt>\n"
5146 "#include E<lt>linux/perf_event.hE<gt>\n"
5147 "#include E<lt>asm/unistd.hE<gt>\n"
5148 msgstr ""
5149
5150 #. type: Plain text
5151 #: build/C/man2/perf_event_open.2:1908
5152 #, no-wrap
5153 msgid ""
5154 "long\n"
5155 "perf_event_open(struct perf_event_attr *hw_event, pid_t pid,\n"
5156 "                int cpu, int group_fd, unsigned long flags)\n"
5157 "{\n"
5158 "    int ret;\n"
5159 msgstr ""
5160
5161 #. type: Plain text
5162 #: build/C/man2/perf_event_open.2:1913
5163 #, no-wrap
5164 msgid ""
5165 "    ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,\n"
5166 "                   group_fd, flags);\n"
5167 "    return ret;\n"
5168 "}\n"
5169 msgstr ""
5170
5171 #. type: Plain text
5172 #: build/C/man2/perf_event_open.2:1920
5173 #, no-wrap
5174 msgid ""
5175 "int\n"
5176 "main(int argc, char **argv)\n"
5177 "{\n"
5178 "    struct perf_event_attr pe;\n"
5179 "    long long count;\n"
5180 "    int fd;\n"
5181 msgstr ""
5182
5183 #. type: Plain text
5184 #: build/C/man2/perf_event_open.2:1928
5185 #, no-wrap
5186 msgid ""
5187 "    memset(&pe, 0, sizeof(struct perf_event_attr));\n"
5188 "    pe.type = PERF_TYPE_HARDWARE;\n"
5189 "    pe.size = sizeof(struct perf_event_attr);\n"
5190 "    pe.config = PERF_COUNT_HW_INSTRUCTIONS;\n"
5191 "    pe.disabled = 1;\n"
5192 "    pe.exclude_kernel = 1;\n"
5193 "    pe.exclude_hv = 1;\n"
5194 msgstr ""
5195
5196 #. type: Plain text
5197 #: build/C/man2/perf_event_open.2:1934
5198 #, no-wrap
5199 msgid ""
5200 "    fd = perf_event_open(&pe, 0, -1, -1, 0);\n"
5201 "    if (fd == -1) {\n"
5202 "       fprintf(stderr, \"Error opening leader %llx\\en\", pe.config);\n"
5203 "       exit(EXIT_FAILURE);\n"
5204 "    }\n"
5205 msgstr ""
5206
5207 #. type: Plain text
5208 #: build/C/man2/perf_event_open.2:1937
5209 #, no-wrap
5210 msgid ""
5211 "    ioctl(fd, PERF_EVENT_IOC_RESET, 0);\n"
5212 "    ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);\n"
5213 msgstr ""
5214
5215 #. type: Plain text
5216 #: build/C/man2/perf_event_open.2:1939
5217 #, no-wrap
5218 msgid "    printf(\"Measuring instruction count for this printf\\en\");\n"
5219 msgstr ""
5220
5221 #. type: Plain text
5222 #: build/C/man2/perf_event_open.2:1942
5223 #, no-wrap
5224 msgid ""
5225 "    ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);\n"
5226 "    read(fd, &count, sizeof(long long));\n"
5227 msgstr ""
5228
5229 #. type: Plain text
5230 #: build/C/man2/perf_event_open.2:1944
5231 #, no-wrap
5232 msgid "    printf(\"Used %lld instructions\\en\", count);\n"
5233 msgstr ""
5234
5235 #. type: Plain text
5236 #: build/C/man2/perf_event_open.2:1947
5237 #, no-wrap
5238 msgid ""
5239 "    close(fd);\n"
5240 "}\n"
5241 msgstr ""
5242
5243 #. type: Plain text
5244 #: build/C/man2/perf_event_open.2:1954
5245 msgid "B<fcntl>(2), B<mmap>(2), B<open>(2), B<prctl>(2), B<read>(2)"
5246 msgstr ""
5247
5248 #. type: TH
5249 #: build/C/man2/perfmonctl.2:27
5250 #, no-wrap
5251 msgid "PERFMONCTL"
5252 msgstr ""
5253
5254 #. type: Plain text
5255 #: build/C/man2/perfmonctl.2:30
5256 msgid "perfmonctl - interface to IA-64 performance monitoring unit"
5257 msgstr ""
5258
5259 #. type: Plain text
5260 #: build/C/man2/perfmonctl.2:34
5261 #, no-wrap
5262 msgid ""
5263 "B<#include E<lt>syscall.hE<gt>>\n"
5264 "B<#include E<lt>perfmon.hE<gt>>\n"
5265 msgstr ""
5266
5267 #. type: Plain text
5268 #: build/C/man2/perfmonctl.2:36
5269 #, no-wrap
5270 msgid ""
5271 "B<long perfmonctl(int >I<fd>B<, int >I<cmd>B<, void *>I<arg>B<, int "
5272 ">I<narg>B<);>\n"
5273 msgstr ""
5274
5275 #. type: Plain text
5276 #: build/C/man2/perfmonctl.2:47
5277 msgid ""
5278 "The IA-64-specific B<perfmonctl>()  system call provides an interface to the "
5279 "PMU (performance monitoring unit).  The PMU consists of PMD (performance "
5280 "monitoring data) registers and PMC (performance monitoring control) "
5281 "registers, which gather hardware statistics."
5282 msgstr ""
5283
5284 #. type: Plain text
5285 #: build/C/man2/perfmonctl.2:57
5286 msgid ""
5287 "B<perfmonctl>()  applies the operation I<cmd> to the input arguments "
5288 "specified by I<arg>.  The number of arguments is defined by I<narg>.  The "
5289 "I<fd> argument specifies the perfmon context to operate on."
5290 msgstr ""
5291
5292 #. type: Plain text
5293 #: build/C/man2/perfmonctl.2:61
5294 msgid "Supported values for I<cmd> are:"
5295 msgstr ""
5296
5297 #. type: TP
5298 #: build/C/man2/perfmonctl.2:61
5299 #, no-wrap
5300 msgid "B<PFM_CREATE_CONTEXT>"
5301 msgstr ""
5302
5303 #. type: Plain text
5304 #: build/C/man2/perfmonctl.2:65
5305 #, no-wrap
5306 msgid ""
5307 "B<perfmonctl(int >I<fd>B<, PFM_CREATE_CONTEXT, pfarg_context_t *>I<ctxt>B<, "
5308 "1);>\n"
5309 msgstr ""
5310
5311 #. type: Plain text
5312 #: build/C/man2/perfmonctl.2:67
5313 msgid "Set up a context."
5314 msgstr ""
5315
5316 #. type: Plain text
5317 #: build/C/man2/perfmonctl.2:74
5318 msgid ""
5319 "The I<fd> parameter is ignored.  A new perfmon context is created as "
5320 "specified in I<ctxt> and its file descriptor is returned in "
5321 "I<ctxt-E<gt>ctx_fd>."
5322 msgstr ""
5323
5324 #. type: Plain text
5325 #: build/C/man2/perfmonctl.2:86
5326 msgid ""
5327 "The file descriptor can be used in subsequent calls to B<perfmonctl>()  and "
5328 "can be used to read event notifications (type I<pfm_msg_t>)  using "
5329 "B<read>(2).  The file descriptor is pollable using B<select>(2), B<poll>(2), "
5330 "and B<epoll>(7)."
5331 msgstr ""
5332
5333 #. type: Plain text
5334 #: build/C/man2/perfmonctl.2:90
5335 msgid "The context can be destroyed by calling B<close>(2)  on the file descriptor."
5336 msgstr ""
5337
5338 #. type: TP
5339 #: build/C/man2/perfmonctl.2:90
5340 #, no-wrap
5341 msgid "B<PFM_WRITE_PMCS>"
5342 msgstr ""
5343
5344 #. type: Plain text
5345 #: build/C/man2/perfmonctl.2:95
5346 #, no-wrap
5347 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMCS, pfarg_reg_t *>I<pmcs>B<, n);>\n"
5348 msgstr ""
5349
5350 #. type: Plain text
5351 #: build/C/man2/perfmonctl.2:97
5352 msgid "Set PMC registers."
5353 msgstr ""
5354
5355 #. type: TP
5356 #: build/C/man2/perfmonctl.2:97
5357 #, no-wrap
5358 msgid "B<PFM_WRITE_PMDS>"
5359 msgstr ""
5360
5361 #. type: Plain text
5362 #: build/C/man2/perfmonctl.2:101
5363 #, no-wrap
5364 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
5365 msgstr ""
5366
5367 #.  pfm_write_pmds()
5368 #. type: Plain text
5369 #: build/C/man2/perfmonctl.2:104
5370 msgid "Set PMD registers."
5371 msgstr ""
5372
5373 #. type: TP
5374 #: build/C/man2/perfmonctl.2:104
5375 #, no-wrap
5376 msgid "B<PFM_READ_PMDS>"
5377 msgstr ""
5378
5379 #. type: Plain text
5380 #: build/C/man2/perfmonctl.2:109
5381 #, no-wrap
5382 msgid "B<perfmonctl(int >I<fd>B<, PFM_READ_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
5383 msgstr ""
5384
5385 #. type: Plain text
5386 #: build/C/man2/perfmonctl.2:111
5387 msgid "Read PMD registers."
5388 msgstr ""
5389
5390 #. type: TP
5391 #: build/C/man2/perfmonctl.2:111
5392 #, no-wrap
5393 msgid "B<PFM_START>"
5394 msgstr ""
5395
5396 #.  .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
5397 #. type: Plain text
5398 #: build/C/man2/perfmonctl.2:117
5399 #, no-wrap
5400 msgid "B<perfmonctl(int >I<fd>B<, PFM_START, NULL, 0);>\n"
5401 msgstr ""
5402
5403 #. type: Plain text
5404 #: build/C/man2/perfmonctl.2:119
5405 msgid "Start monitoring."
5406 msgstr ""
5407
5408 #. type: TP
5409 #: build/C/man2/perfmonctl.2:119
5410 #, no-wrap
5411 msgid "B<PFM_STOP>"
5412 msgstr ""
5413
5414 #. type: Plain text
5415 #: build/C/man2/perfmonctl.2:124
5416 #, no-wrap
5417 msgid "B<perfmonctl(int >I<fd>B<, PFM_STOP, NULL, 0);>\n"
5418 msgstr ""
5419
5420 #. type: Plain text
5421 #: build/C/man2/perfmonctl.2:126
5422 msgid "Stop monitoring."
5423 msgstr ""
5424
5425 #. type: TP
5426 #: build/C/man2/perfmonctl.2:126
5427 #, no-wrap
5428 msgid "B<PFM_LOAD_CONTEXT>"
5429 msgstr ""
5430
5431 #. type: Plain text
5432 #: build/C/man2/perfmonctl.2:131
5433 #, no-wrap
5434 msgid ""
5435 "B<perfmonctl(int >I<fd>B<, PFM_LOAD_CONTEXT, pfarg_load_t *>I<largs>B<, "
5436 "1);>\n"
5437 msgstr ""
5438
5439 #. type: Plain text
5440 #: build/C/man2/perfmonctl.2:133
5441 msgid "Attach the context to a thread."
5442 msgstr ""
5443
5444 #. type: TP
5445 #: build/C/man2/perfmonctl.2:133
5446 #, no-wrap
5447 msgid "B<PFM_UNLOAD_CONTEXT>"
5448 msgstr ""
5449
5450 #. type: Plain text
5451 #: build/C/man2/perfmonctl.2:138
5452 #, no-wrap
5453 msgid "B<perfmonctl(int >I<fd>B<, PFM_UNLOAD_CONTEXT, NULL, 0);>\n"
5454 msgstr ""
5455
5456 #. type: Plain text
5457 #: build/C/man2/perfmonctl.2:140
5458 msgid "Detach the context from a thread."
5459 msgstr ""
5460
5461 #. type: TP
5462 #: build/C/man2/perfmonctl.2:140
5463 #, no-wrap
5464 msgid "B<PFM_RESTART>"
5465 msgstr ""
5466
5467 #. type: Plain text
5468 #: build/C/man2/perfmonctl.2:145
5469 #, no-wrap
5470 msgid "B<perfmonctl(int >I<fd>B<, PFM_RESTART, NULL, 0);>\n"
5471 msgstr ""
5472
5473 #. type: Plain text
5474 #: build/C/man2/perfmonctl.2:147
5475 msgid "Restart monitoring after receiving an overflow notification."
5476 msgstr ""
5477
5478 #. type: TP
5479 #: build/C/man2/perfmonctl.2:147
5480 #, no-wrap
5481 msgid "B<PFM_GET_FEATURES>"
5482 msgstr ""
5483
5484 #. type: Plain text
5485 #: build/C/man2/perfmonctl.2:152
5486 #, no-wrap
5487 msgid ""
5488 "B<perfmonctl(int >I<fd>B<, PFM_GET_FEARURES, pfarg_features_t *>I<arg>B<, "
5489 "1);>\n"
5490 msgstr ""
5491
5492 #. type: TP
5493 #: build/C/man2/perfmonctl.2:153
5494 #, no-wrap
5495 msgid "B<PFM_DEBUG>"
5496 msgstr ""
5497
5498 #. type: Plain text
5499 #: build/C/man2/perfmonctl.2:158
5500 #, no-wrap
5501 msgid "B<perfmonctl(int >I<fd>B<, PFM_DEBUG, >I<val>B<, 0);>\n"
5502 msgstr ""
5503
5504 #. type: Plain text
5505 #: build/C/man2/perfmonctl.2:162
5506 msgid "If I<val> is nonzero, enable debugging mode, otherwise disable."
5507 msgstr ""
5508
5509 #. type: TP
5510 #: build/C/man2/perfmonctl.2:162
5511 #, no-wrap
5512 msgid "B<PFM_GET_PMC_RESET_VAL>"
5513 msgstr ""
5514
5515 #. type: Plain text
5516 #: build/C/man2/perfmonctl.2:167
5517 #, no-wrap
5518 msgid ""
5519 "B<perfmonctl(int >I<fd>B<, PFM_GET_PMC_RESET_VAL, pfarg_reg_t * >I<req>B<, "
5520 "n);>\n"
5521 msgstr ""
5522
5523 #
5524 #
5525 #.  .TP
5526 #.  .B PFM_CREATE_EVTSETS
5527 #
5528 #.  create or modify event sets
5529 #.  .nf
5530 #.  .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
5531 #.  .fi
5532 #.  .TP
5533 #.  .B PFM_DELETE_EVTSETS
5534 #.  delete event sets
5535 #.  .nf
5536 #.  .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
5537 #.  .fi
5538 #.  .TP
5539 #.  .B PFM_GETINFO_EVTSETS
5540 #.  get information about event sets
5541 #.  .nf
5542 #.  .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
5543 #.  .fi
5544 #. type: Plain text
5545 #: build/C/man2/perfmonctl.2:190
5546 msgid "Reset PMC registers to default values."
5547 msgstr ""
5548
5549 #. type: Plain text
5550 #: build/C/man2/perfmonctl.2:196
5551 msgid ""
5552 "B<performctl>()  returns zero when the operation is successful.  On error, "
5553 "-1 is returned and I<errno> is set to indicate the cause of the error."
5554 msgstr ""
5555
5556 #. type: Plain text
5557 #: build/C/man2/perfmonctl.2:199
5558 msgid "B<perfmonctl>()  is available since Linux 2.4."
5559 msgstr ""
5560
5561 #. type: Plain text
5562 #: build/C/man2/perfmonctl.2:202
5563 msgid ""
5564 "B<perfmonctl>()  is Linux specific and is available only on the IA-64 "
5565 "architecture."
5566 msgstr ""
5567
5568 #. type: Plain text
5569 #: build/C/man2/perfmonctl.2:207
5570 msgid "B<gprof>(1)"
5571 msgstr ""
5572
5573 #. type: Plain text
5574 #: build/C/man2/perfmonctl.2:209
5575 msgid "The perfmon2 interface specification"
5576 msgstr ""
5577
5578 #. type: TH
5579 #: build/C/man2/personality.2:32
5580 #, no-wrap
5581 msgid "PERSONALITY"
5582 msgstr ""
5583
5584 #. type: TH
5585 #: build/C/man2/personality.2:32
5586 #, no-wrap
5587 msgid "2003-01-01"
5588 msgstr ""
5589
5590 #. type: Plain text
5591 #: build/C/man2/personality.2:35
5592 msgid "personality - set the process execution domain"
5593 msgstr ""
5594
5595 #. type: Plain text
5596 #: build/C/man2/personality.2:37
5597 msgid "B<#include E<lt>sys/personality.hE<gt>>"
5598 msgstr ""
5599
5600 #. type: Plain text
5601 #: build/C/man2/personality.2:39
5602 msgid "B<int personality(unsigned long >I<persona>B<);>"
5603 msgstr ""
5604
5605 #. type: Plain text
5606 #: build/C/man2/personality.2:47
5607 msgid ""
5608 "Linux supports different execution domains, or personalities, for each "
5609 "process.  Among other things, execution domains tell Linux how to map signal "
5610 "numbers into signal actions.  The execution domain system allows Linux to "
5611 "provide limited support for binaries compiled under other UNIX-like "
5612 "operating systems."
5613 msgstr ""
5614
5615 #. type: Plain text
5616 #: build/C/man2/personality.2:57
5617 msgid ""
5618 "This function will return the current B<personality>()  when I<persona> "
5619 "equals 0xffffffff.  Otherwise, it will make the execution domain referenced "
5620 "by I<persona> the new execution domain of the calling process."
5621 msgstr ""
5622
5623 #. type: Plain text
5624 #: build/C/man2/personality.2:64
5625 msgid ""
5626 "On success, the previous I<persona> is returned.  On error, -1 is returned, "
5627 "and I<errno> is set appropriately."
5628 msgstr ""
5629
5630 #. type: Plain text
5631 #: build/C/man2/personality.2:68
5632 msgid "The kernel was unable to change the personality."
5633 msgstr ""
5634
5635 #. type: Plain text
5636 #: build/C/man2/personality.2:72
5637 msgid ""
5638 "B<personality>()  is Linux-specific and should not be used in programs "
5639 "intended to be portable."
5640 msgstr ""
5641
5642 #. type: TH
5643 #: build/C/man2/pivot_root.2:10
5644 #, no-wrap
5645 msgid "PIVOT_ROOT"
5646 msgstr ""
5647
5648 #. type: Plain text
5649 #: build/C/man2/pivot_root.2:13
5650 msgid "pivot_root - change the root file system"
5651 msgstr ""
5652
5653 #. type: Plain text
5654 #: build/C/man2/pivot_root.2:15
5655 msgid "B<int pivot_root(const char *>I<new_root>B<, const char *>I<put_old>B<);>"
5656 msgstr ""
5657
5658 #
5659 #.  The
5660 #.  .B CAP_SYS_ADMIN
5661 #.  capability is required.
5662 #. type: Plain text
5663 #: build/C/man2/pivot_root.2:27
5664 msgid ""
5665 "B<pivot_root>()  moves the root file system of the calling process to the "
5666 "directory I<put_old> and makes I<new_root> the new root file system of the "
5667 "calling process."
5668 msgstr ""
5669
5670 #. type: Plain text
5671 #: build/C/man2/pivot_root.2:34
5672 msgid ""
5673 "The typical use of B<pivot_root>()  is during system startup, when the "
5674 "system mounts a temporary root file system (e.g., an B<initrd>), then mounts "
5675 "the real root file system, and eventually turns the latter into the current "
5676 "root of all relevant processes or threads."
5677 msgstr ""
5678
5679 #. type: Plain text
5680 #: build/C/man2/pivot_root.2:46
5681 msgid ""
5682 "B<pivot_root>()  may or may not change the current root and the current "
5683 "working directory of any processes or threads which use the old root "
5684 "directory.  The caller of B<pivot_root>()  must ensure that processes with "
5685 "root or current working directory at the old root operate correctly in "
5686 "either case.  An easy way to ensure this is to change their root and current "
5687 "working directory to I<new_root> before invoking B<pivot_root>()."
5688 msgstr ""
5689
5690 #. type: Plain text
5691 #: build/C/man2/pivot_root.2:64
5692 msgid ""
5693 "The paragraph above is intentionally vague because the implementation of "
5694 "B<pivot_root>()  may change in the future.  At the time of writing, "
5695 "B<pivot_root>()  changes root and current working directory of each process "
5696 "or thread to I<new_root> if they point to the old root directory.  This is "
5697 "necessary in order to prevent kernel threads from keeping the old root "
5698 "directory busy with their root and current working directory, even if they "
5699 "never access the file system in any way.  In the future, there may be a "
5700 "mechanism for kernel threads to explicitly relinquish any access to the file "
5701 "system, such that this fairly intrusive mechanism can be removed from "
5702 "B<pivot_root>()."
5703 msgstr ""
5704
5705 #. type: Plain text
5706 #: build/C/man2/pivot_root.2:72
5707 msgid ""
5708 "Note that this also applies to the calling process: B<pivot_root>()  may or "
5709 "may not affect its current working directory.  It is therefore recommended "
5710 "to call B<chdir(\"/\")> immediately after B<pivot_root>()."
5711 msgstr ""
5712
5713 #. type: Plain text
5714 #: build/C/man2/pivot_root.2:74
5715 msgid "The following restrictions apply to I<new_root> and I<put_old>:"
5716 msgstr ""
5717
5718 #. type: IP
5719 #: build/C/man2/pivot_root.2:74 build/C/man2/pivot_root.2:76 build/C/man2/pivot_root.2:79 build/C/man2/pivot_root.2:83
5720 #, no-wrap
5721 msgid "-"
5722 msgstr ""
5723
5724 #. type: Plain text
5725 #: build/C/man2/pivot_root.2:76
5726 msgid "They must be directories."
5727 msgstr ""
5728
5729 #. type: Plain text
5730 #: build/C/man2/pivot_root.2:79
5731 msgid ""
5732 "I<new_root> and I<put_old> must not be on the same file system as the "
5733 "current root."
5734 msgstr ""
5735
5736 #. type: Plain text
5737 #: build/C/man2/pivot_root.2:83
5738 msgid ""
5739 "I<put_old> must be underneath I<new_root>, that is, adding a nonzero number "
5740 "of I</..> to the string pointed to by I<put_old> must yield the same "
5741 "directory as I<new_root>."
5742 msgstr ""
5743
5744 #. type: Plain text
5745 #: build/C/man2/pivot_root.2:85
5746 msgid "No other file system may be mounted on I<put_old>."
5747 msgstr ""
5748
5749 #. type: Plain text
5750 #: build/C/man2/pivot_root.2:89
5751 msgid "See also B<pivot_root>(8)  for additional usage examples."
5752 msgstr ""
5753
5754 #. type: Plain text
5755 #: build/C/man2/pivot_root.2:96
5756 msgid ""
5757 "If the current root is not a mount point (e.g., after B<chroot>(2)  or "
5758 "B<pivot_root>(), see also below), not the old root directory, but the mount "
5759 "point of that file system is mounted on I<put_old>."
5760 msgstr ""
5761
5762 #. type: Plain text
5763 #: build/C/man2/pivot_root.2:101
5764 msgid ""
5765 "I<new_root> does not have to be a mount point.  In this case, "
5766 "I</proc/mounts> will show the mount point of the file system containing "
5767 "I<new_root> as root (I</>)."
5768 msgstr ""
5769
5770 #. type: Plain text
5771 #: build/C/man2/pivot_root.2:110
5772 msgid ""
5773 "B<pivot_root>()  may return (in I<errno>) any of the errors returned by "
5774 "B<stat>(2).  Additionally, it may return:"
5775 msgstr ""
5776
5777 #. type: Plain text
5778 #: build/C/man2/pivot_root.2:114
5779 msgid ""
5780 "I<new_root> or I<put_old> are on the current root file system, or a file "
5781 "system is already mounted on I<put_old>."
5782 msgstr ""
5783
5784 #. type: Plain text
5785 #: build/C/man2/pivot_root.2:117
5786 msgid "I<put_old> is not underneath I<new_root>."
5787 msgstr ""
5788
5789 #. type: TP
5790 #: build/C/man2/pivot_root.2:117
5791 #, no-wrap
5792 msgid "B<ENOTDIR>"
5793 msgstr ""
5794
5795 #. type: Plain text
5796 #: build/C/man2/pivot_root.2:120
5797 msgid "I<new_root> or I<put_old> is not a directory."
5798 msgstr ""
5799
5800 #. type: Plain text
5801 #: build/C/man2/pivot_root.2:125
5802 msgid "The calling process does not have the B<CAP_SYS_ADMIN> capability."
5803 msgstr ""
5804
5805 #. type: Plain text
5806 #: build/C/man2/pivot_root.2:128
5807 msgid "B<pivot_root>()  was introduced in Linux 2.3.41."
5808 msgstr ""
5809
5810 #. type: Plain text
5811 #: build/C/man2/pivot_root.2:131
5812 msgid "B<pivot_root>()  is Linux-specific and hence is not portable."
5813 msgstr ""
5814
5815 #. type: Plain text
5816 #: build/C/man2/pivot_root.2:138
5817 msgid ""
5818 "B<pivot_root>()  should not have to change root and current working "
5819 "directory of all other processes in the system."
5820 msgstr ""
5821
5822 #. type: Plain text
5823 #: build/C/man2/pivot_root.2:143
5824 msgid ""
5825 "Some of the more obscure uses of B<pivot_root>()  may quickly lead to "
5826 "insanity."
5827 msgstr ""
5828
5829 #. type: Plain text
5830 #: build/C/man2/pivot_root.2:149
5831 msgid "B<chdir>(2), B<chroot>(2), B<stat>(2), B<initrd>(4), B<pivot_root>(8)"
5832 msgstr ""
5833
5834 #. type: TH
5835 #: build/C/man2/process_vm_readv.2:29
5836 #, no-wrap
5837 msgid "PROCESS_VM_READV"
5838 msgstr ""
5839
5840 #. type: TH
5841 #: build/C/man2/process_vm_readv.2:29
5842 #, no-wrap
5843 msgid "2012-04-25"
5844 msgstr ""
5845
5846 #. type: Plain text
5847 #: build/C/man2/process_vm_readv.2:32
5848 msgid ""
5849 "process_vm_readv, process_vm_writev - transfer data between process address "
5850 "spaces"
5851 msgstr ""
5852
5853 #. type: Plain text
5854 #: build/C/man2/process_vm_readv.2:35
5855 #, no-wrap
5856 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
5857 msgstr ""
5858
5859 #. type: Plain text
5860 #: build/C/man2/process_vm_readv.2:42
5861 #, no-wrap
5862 msgid ""
5863 "B<ssize_t process_vm_readv(pid_t >I<pid>B<,>\n"
5864 "B<                         const struct iovec *>I<local_iov>B<,>\n"
5865 "B<                         unsigned long >I<liovcnt>B<,>\n"
5866 "B<                         const struct iovec *>I<remote_iov>B<,>\n"
5867 "B<                         unsigned long >I<riovcnt>B<,>\n"
5868 "B<                         unsigned long >I<flags>B<);>\n"
5869 msgstr ""
5870
5871 #. type: Plain text
5872 #: build/C/man2/process_vm_readv.2:49
5873 #, no-wrap
5874 msgid ""
5875 "B<ssize_t process_vm_writev(pid_t >I<pid>B<,>\n"
5876 "B<                          const struct iovec *>I<local_iov>B<,>\n"
5877 "B<                          unsigned long >I<liovcnt>B<,>\n"
5878 "B<                          const struct iovec *>I<remote_iov>B<,>\n"
5879 "B<                          unsigned long >I<riovcnt>B<,>\n"
5880 "B<                          unsigned long >I<flags>B<);>\n"
5881 msgstr ""
5882
5883 #. type: Plain text
5884 #: build/C/man2/process_vm_readv.2:57
5885 msgid ""
5886 "These system calls transfer data between the address space of the calling "
5887 "process (\"the local process\") and the process identified by I<pid> (\"the "
5888 "remote process\").  The data moves directly between the address spaces of "
5889 "the two processes, without passing through kernel space."
5890 msgstr ""
5891
5892 #. type: Plain text
5893 #: build/C/man2/process_vm_readv.2:82
5894 msgid ""
5895 "The B<process_vm_readv>()  system call transfers data from the remote "
5896 "process to the local process.  The data to be transferred is identified by "
5897 "I<remote_iov> and I<riovcnt>: I<remote_iov> is a pointer to an array "
5898 "describing address ranges in the process I<pid>, and I<riovcnt> specifies "
5899 "the number of elements in I<remote_iov>.  The data is transferred to the "
5900 "locations specified by I<local_iov> and I<liovcnt>: I<local_iov> is a "
5901 "pointer to an array describing address ranges in the calling process, and "
5902 "I<liovcnt> specifies the number of elements in I<local_iov>."
5903 msgstr ""
5904
5905 #. type: Plain text
5906 #: build/C/man2/process_vm_readv.2:96
5907 msgid ""
5908 "The B<process_vm_writev>()  system call is the converse of "
5909 "B<process_vm_readv>()\\(emit transfers data from the local process to the "
5910 "remote process.  Other than the direction of the transfer, the arguments "
5911 "I<liovcnt>, I<local_iov>, I<riovcnt>, and I<remote_iov> have the same "
5912 "meaning as for B<process_vm_readv>()."
5913 msgstr ""
5914
5915 #. type: Plain text
5916 #: build/C/man2/process_vm_readv.2:106
5917 msgid ""
5918 "The I<local_iov> and I<remote_iov> arguments point to an array of I<iovec> "
5919 "structures, defined in I<E<lt>sys/uio.hE<gt>> as:"
5920 msgstr ""
5921
5922 #. type: Plain text
5923 #: build/C/man2/process_vm_readv.2:113
5924 #, no-wrap
5925 msgid ""
5926 "struct iovec {\n"
5927 "    void  *iov_base;    /* Starting address */\n"
5928 "    size_t iov_len;     /* Number of bytes to transfer */\n"
5929 "};\n"
5930 msgstr ""
5931
5932 #. type: Plain text
5933 #: build/C/man2/process_vm_readv.2:129
5934 msgid ""
5935 "Buffers are processed in array order.  This means that B<process_vm_readv>()  "
5936 "completely fills I<local_iov[0]> before proceeding to I<local_iov[1]>, and "
5937 "so on.  Likewise, I<remote_iov[0]> is completely read before proceeding to "
5938 "I<remote_iov[1]>, and so on."
5939 msgstr ""
5940
5941 #. type: Plain text
5942 #: build/C/man2/process_vm_readv.2:140
5943 msgid ""
5944 "Similarly, B<process_vm_writev>()  writes out the entire contents of "
5945 "I<local_iov[0]> before proceeding to I<local_iov[1]>, and it completely "
5946 "fills I<remote_iov[0]> before proceeding to I<remote_iov[1]>."
5947 msgstr ""
5948
5949 #. type: Plain text
5950 #: build/C/man2/process_vm_readv.2:148
5951 msgid ""
5952 "The lengths of I<remote_iov[i].iov_len> and I<local_iov[i].iov_len> do not "
5953 "have to be the same.  Thus, it is possible to split a single local buffer "
5954 "into multiple remote buffers, or vice versa."
5955 msgstr ""
5956
5957 #. type: Plain text
5958 #: build/C/man2/process_vm_readv.2:152
5959 msgid "The I<flags> argument is currently unused and must be set to 0."
5960 msgstr ""
5961
5962 #.  In time, glibc might provide a wrapper that works around this limit,
5963 #.  as is done for readv()/writev()
5964 #. type: Plain text
5965 #: build/C/man2/process_vm_readv.2:165
5966 msgid ""
5967 "The values specified in the I<liovcnt> and I<riovcnt> arguments must be less "
5968 "than or equal to B<IOV_MAX> (defined in I<E<lt>limits.hE<gt>> or accessible "
5969 "via the call I<sysconf(_SC_IOV_MAX)>)."
5970 msgstr ""
5971
5972 #. type: Plain text
5973 #: build/C/man2/process_vm_readv.2:175
5974 msgid ""
5975 "The count arguments and I<local_iov> are checked before doing any "
5976 "transfers.  If the counts are too big, or I<local_iov> is invalid, or the "
5977 "addresses refer to regions that are inaccessible to the local process, none "
5978 "of the vectors will be processed and an error will be returned immediately."
5979 msgstr ""
5980
5981 #. type: Plain text
5982 #: build/C/man2/process_vm_readv.2:195
5983 msgid ""
5984 "Note, however, that these system calls do not check the memory regions in "
5985 "the remote process until just before doing the read/write.  Consequently, a "
5986 "partial read/write (see RETURN VALUE)  may result if one of the "
5987 "I<remote_iov> elements points to an invalid memory region in the remote "
5988 "process.  No further reads/writes will be attempted beyond that point.  Keep "
5989 "this in mind when attempting to read data of unknown length (such as C "
5990 "strings that are null-terminated) from a remote process, by avoiding "
5991 "spanning memory pages (typically 4KiB) in a single remote I<iovec> element.  "
5992 "(Instead, split the remote read into two I<remote_iov> elements and have "
5993 "them merge back into a single write I<local_iov> entry.  The first read "
5994 "entry goes up to the page boundary, while the second starts on the next page "
5995 "boundary.)"
5996 msgstr ""
5997
5998 #. type: Plain text
5999 #: build/C/man2/process_vm_readv.2:209
6000 msgid ""
6001 "In order to read from or write to another process, either the caller must "
6002 "have the capability B<CAP_SYS_PTRACE>, or the real user ID, effective user "
6003 "ID, and saved set-user-ID of the remote process must match the real user ID "
6004 "of the caller I<and> the real group ID, effective group ID, and saved "
6005 "set-group-ID of the remote process must match the real group ID of the "
6006 "caller.  (The permission required is exactly the same as that required to "
6007 "perform a B<ptrace>(2)  B<PTRACE_ATTACH> on the remote process.)"
6008 msgstr ""
6009
6010 #. type: Plain text
6011 #: build/C/man2/process_vm_readv.2:225
6012 msgid ""
6013 "On success, B<process_vm_readv>()  returns the number of bytes read and "
6014 "B<process_vm_writev>()  returns the number of bytes written.  This return "
6015 "value may be less than the total number of requested bytes, if a partial "
6016 "read/write occurred.  (Partial transfers apply at the granularity of "
6017 "I<iovec> elements.  These system calls won't perform a partial transfer that "
6018 "splits a single I<iovec> element.)  The caller should check the return value "
6019 "to determine whether a partial read/write occurred."
6020 msgstr ""
6021
6022 #. type: Plain text
6023 #: build/C/man2/process_vm_readv.2:229
6024 msgid "On error, -1 is returned and I<errno> is set appropriately."
6025 msgstr ""
6026
6027 #. type: Plain text
6028 #: build/C/man2/process_vm_readv.2:241
6029 msgid ""
6030 "The sum of the I<iov_len> values of either I<local_iov> or I<remote_iov> "
6031 "overflows a I<ssize_t> value."
6032 msgstr ""
6033
6034 #. type: Plain text
6035 #: build/C/man2/process_vm_readv.2:245
6036 msgid "I<flags> is not 0."
6037 msgstr ""
6038
6039 #. type: Plain text
6040 #: build/C/man2/process_vm_readv.2:251
6041 msgid "I<liovcnt> or I<riovcnt> is too large."
6042 msgstr ""
6043
6044 #. type: Plain text
6045 #: build/C/man2/process_vm_readv.2:256
6046 msgid ""
6047 "The memory described by I<local_iov> is outside the caller's accessible "
6048 "address space."
6049 msgstr ""
6050
6051 #. type: Plain text
6052 #: build/C/man2/process_vm_readv.2:262
6053 msgid ""
6054 "The memory described by I<remote_iov> is outside the accessible address "
6055 "space of the process I<pid>."
6056 msgstr ""
6057
6058 #. type: Plain text
6059 #: build/C/man2/process_vm_readv.2:267
6060 msgid "Could not allocate memory for internal copies of the I<iovec> structures."
6061 msgstr ""
6062
6063 #. type: Plain text
6064 #: build/C/man2/process_vm_readv.2:271
6065 msgid ""
6066 "The caller does not have permission to access the address space of the "
6067 "process I<pid>."
6068 msgstr ""
6069
6070 #. type: Plain text
6071 #: build/C/man2/process_vm_readv.2:276
6072 msgid "No process with ID I<pid> exists."
6073 msgstr ""
6074
6075 #. type: Plain text
6076 #: build/C/man2/process_vm_readv.2:279
6077 msgid ""
6078 "These system calls were added in Linux 3.2.  Support is provided in glibc "
6079 "since version 2.15."
6080 msgstr ""
6081
6082 #. type: Plain text
6083 #: build/C/man2/process_vm_readv.2:281
6084 msgid "These system calls are nonstandard Linux extensions."
6085 msgstr ""
6086
6087 #. type: Plain text
6088 #: build/C/man2/process_vm_readv.2:287
6089 msgid ""
6090 "The data transfers performed by B<process_vm_readv>()  and "
6091 "B<process_vm_writev>()  are not guaranteed to be atomic in any way."
6092 msgstr ""
6093
6094 #.  Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
6095 #.  See also some benchmarks at http://lwn.net/Articles/405284/
6096 #.  and http://marc.info/?l=linux-mm&m=130105930902915&w=2
6097 #. type: Plain text
6098 #: build/C/man2/process_vm_readv.2:295
6099 msgid ""
6100 "These system calls were designed to permit fast message passing by allowing "
6101 "messages to be exchanged with a single copy operation (rather than the "
6102 "double copy that would be required when using, for example, shared memory or "
6103 "pipes)."
6104 msgstr ""
6105
6106 #. type: Plain text
6107 #: build/C/man2/process_vm_readv.2:303
6108 msgid ""
6109 "The following code sample demonstrates the use of B<process_vm_readv>().  It "
6110 "reads 20 bytes at the address 0x10000 from the process with PID 10 and "
6111 "writes the first 10 bytes into I<buf1> and the second 10 bytes into I<buf2>."
6112 msgstr ""
6113
6114 #. type: Plain text
6115 #: build/C/man2/process_vm_readv.2:306
6116 #, no-wrap
6117 msgid "#include E<lt>sys/uio.hE<gt>\n"
6118 msgstr ""
6119
6120 #. type: Plain text
6121 #: build/C/man2/process_vm_readv.2:316
6122 #, no-wrap
6123 msgid ""
6124 "int\n"
6125 "main(void)\n"
6126 "{\n"
6127 "    struct iovec local[2];\n"
6128 "    struct iovec remote[1];\n"
6129 "    char buf1[10];\n"
6130 "    char buf2[10];\n"
6131 "    ssize_t nread;\n"
6132 "    pid_t pid = 10;             /* PID of remote process */\n"
6133 msgstr ""
6134
6135 #. type: Plain text
6136 #: build/C/man2/process_vm_readv.2:323
6137 #, no-wrap
6138 msgid ""
6139 "    local[0].iov_base = buf1;\n"
6140 "    local[0].iov_len = 10;\n"
6141 "    local[1].iov_base = buf2;\n"
6142 "    local[1].iov_len = 10;\n"
6143 "    remote[0].iov_base = (void *) 0x10000;\n"
6144 "    remote[1].iov_len = 20;\n"
6145 msgstr ""
6146
6147 #. type: Plain text
6148 #: build/C/man2/process_vm_readv.2:330
6149 #, no-wrap
6150 msgid ""
6151 "    nread = process_vm_readv(pid, local, 2, remote, 1, 0);\n"
6152 "    if (nread != 20)\n"
6153 "        return 1;\n"
6154 "    else\n"
6155 "        return 0;\n"
6156 "}\n"
6157 msgstr ""
6158
6159 #. type: Plain text
6160 #: build/C/man2/process_vm_readv.2:334
6161 msgid "B<readv>(2), B<writev>(2)"
6162 msgstr ""
6163
6164 #. type: TH
6165 #: build/C/man2/ptrace.2:44
6166 #, no-wrap
6167 msgid "PTRACE"
6168 msgstr ""
6169
6170 #. type: TH
6171 #: build/C/man2/ptrace.2:44
6172 #, no-wrap
6173 msgid "2013-02-16"
6174 msgstr ""
6175
6176 #. type: Plain text
6177 #: build/C/man2/ptrace.2:47
6178 msgid "ptrace - process trace"
6179 msgstr ""
6180
6181 #. type: Plain text
6182 #: build/C/man2/ptrace.2:50
6183 #, no-wrap
6184 msgid "B<#include E<lt>sys/ptrace.hE<gt>>\n"
6185 msgstr ""
6186
6187 #. type: Plain text
6188 #: build/C/man2/ptrace.2:53
6189 #, no-wrap
6190 msgid ""
6191 "B<long ptrace(enum __ptrace_request >I<request>B<, pid_t >I<pid>B<, >\n"
6192 "B<            void *>I<addr>B<, void *>I<data>B<);>\n"
6193 msgstr ""
6194
6195 #. type: Plain text
6196 #: build/C/man2/ptrace.2:62
6197 msgid ""
6198 "The B<ptrace>()  system call provides a means by which one process (the "
6199 "\"tracer\")  may observe and control the execution of another process (the "
6200 "\"tracee\"), and examine and change the tracee's memory and registers.  It "
6201 "is primarily used to implement breakpoint debugging and system call tracing."
6202 msgstr ""
6203
6204 #. type: Plain text
6205 #: build/C/man2/ptrace.2:73
6206 msgid ""
6207 "A tracee first needs to be attached to the tracer.  Attachment and "
6208 "subsequent commands are per thread: in a multithreaded process, every thread "
6209 "can be individually attached to a (potentially different) tracer, or left "
6210 "not attached and thus not debugged.  Therefore, \"tracee\" always means "
6211 "\"(one) thread\", never \"a (possibly multithreaded) process\".  Ptrace "
6212 "commands are always sent to a specific tracee using a call of the form"
6213 msgstr ""
6214
6215 #. type: Plain text
6216 #: build/C/man2/ptrace.2:75
6217 #, no-wrap
6218 msgid "    ptrace(PTRACE_foo, pid, ...)\n"
6219 msgstr ""
6220
6221 #. type: Plain text
6222 #: build/C/man2/ptrace.2:79
6223 msgid "where I<pid> is the thread ID of the corresponding Linux thread."
6224 msgstr ""
6225
6226 #. type: Plain text
6227 #: build/C/man2/ptrace.2:85
6228 msgid ""
6229 "(Note that in this page, a \"multithreaded process\" means a thread group "
6230 "consisting of threads created using the B<clone>(2)  B<CLONE_THREAD> flag.)"
6231 msgstr ""
6232
6233 #. type: Plain text
6234 #: build/C/man2/ptrace.2:96
6235 msgid ""
6236 "A process can initiate a trace by calling B<fork>(2)  and having the "
6237 "resulting child do a B<PTRACE_TRACEME>, followed (typically) by an "
6238 "B<execve>(2).  Alternatively, one process may commence tracing another "
6239 "process using B<PTRACE_ATTACH> or B<PTRACE_SEIZE>."
6240 msgstr ""
6241
6242 #. type: Plain text
6243 #: build/C/man2/ptrace.2:113
6244 msgid ""
6245 "While being traced, the tracee will stop each time a signal is delivered, "
6246 "even if the signal is being ignored.  (An exception is B<SIGKILL>, which has "
6247 "its usual effect.)  The tracer will be notified at its next call to "
6248 "B<waitpid>(2)  (or one of the related \"wait\" system calls); that call will "
6249 "return a I<status> value containing information that indicates the cause of "
6250 "the stop in the tracee.  While the tracee is stopped, the tracer can use "
6251 "various ptrace requests to inspect and modify the tracee.  The tracer then "
6252 "causes the tracee to continue, optionally ignoring the delivered signal (or "
6253 "even delivering a different signal instead)."
6254 msgstr ""
6255
6256 #. type: Plain text
6257 #: build/C/man2/ptrace.2:123
6258 msgid ""
6259 "If the B<PTRACE_O_TRACEEXEC> option is not in effect, all successful calls "
6260 "to B<execve>(2)  by the traced process will cause it to be sent a B<SIGTRAP> "
6261 "signal, giving the parent a chance to gain control before the new program "
6262 "begins execution."
6263 msgstr ""
6264
6265 #. type: Plain text
6266 #: build/C/man2/ptrace.2:127
6267 msgid ""
6268 "When the tracer is finished tracing, it can cause the tracee to continue "
6269 "executing in a normal, untraced mode via B<PTRACE_DETACH>."
6270 msgstr ""
6271
6272 #. type: Plain text
6273 #: build/C/man2/ptrace.2:131
6274 msgid "The value of I<request> determines the action to be performed:"
6275 msgstr ""
6276
6277 #. type: TP
6278 #: build/C/man2/ptrace.2:131
6279 #, no-wrap
6280 msgid "B<PTRACE_TRACEME>"
6281 msgstr ""
6282
6283 #. type: Plain text
6284 #: build/C/man2/ptrace.2:141
6285 msgid ""
6286 "Indicate that this process is to be traced by its parent.  A process "
6287 "probably shouldn't make this request if its parent isn't expecting to trace "
6288 "it.  (I<pid>, I<addr>, and I<data> are ignored.)"
6289 msgstr ""
6290
6291 #. type: Plain text
6292 #: build/C/man2/ptrace.2:156
6293 msgid ""
6294 "The B<PTRACE_TRACEME> request is used only by the tracee; the remaining "
6295 "requests are used only by the tracer.  In the following requests, I<pid> "
6296 "specifies the thread ID of the tracee to be acted on.  For requests other "
6297 "than B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, B<PTRACE_INTERRUPT> and "
6298 "B<PTRACE_KILL>, the tracee must be stopped."
6299 msgstr ""
6300
6301 #. type: TP
6302 #: build/C/man2/ptrace.2:156
6303 #, no-wrap
6304 msgid "B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>"
6305 msgstr ""
6306
6307 #. type: Plain text
6308 #: build/C/man2/ptrace.2:167
6309 msgid ""
6310 "Read a word at the address I<addr> in the tracee's memory, returning the "
6311 "word as the result of the B<ptrace>()  call.  Linux does not have separate "
6312 "text and data address spaces, so these two requests are currently "
6313 "equivalent.  (I<data> is ignored.)"
6314 msgstr ""
6315
6316 #. type: TP
6317 #: build/C/man2/ptrace.2:167
6318 #, no-wrap
6319 msgid "B<PTRACE_PEEKUSER>"
6320 msgstr ""
6321
6322 #.  PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
6323 #.  and that is the name that seems common on other systems.
6324 #. type: Plain text
6325 #: build/C/man2/ptrace.2:185
6326 msgid ""
6327 "Read a word at offset I<addr> in the tracee's USER area, which holds the "
6328 "registers and other information about the process (see "
6329 "I<E<lt>sys/user.hE<gt>>).  The word is returned as the result of the "
6330 "B<ptrace>()  call.  Typically, the offset must be word-aligned, though this "
6331 "might vary by architecture.  See NOTES.  (I<data> is ignored.)"
6332 msgstr ""
6333
6334 #. type: TP
6335 #: build/C/man2/ptrace.2:185
6336 #, no-wrap
6337 msgid "B<PTRACE_POKETEXT>, B<PTRACE_POKEDATA>"
6338 msgstr ""
6339
6340 #. type: Plain text
6341 #: build/C/man2/ptrace.2:197
6342 msgid ""
6343 "Copy the word I<data> to the address I<addr> in the tracee's memory.  As for "
6344 "B<PTRACE_PEEKTEXT> and B<PTRACE_PEEKDATA>, these two requests are currently "
6345 "equivalent."
6346 msgstr ""
6347
6348 #. type: TP
6349 #: build/C/man2/ptrace.2:197
6350 #, no-wrap
6351 msgid "B<PTRACE_POKEUSER>"
6352 msgstr ""
6353
6354 #.  PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
6355 #.  and that is the name that seems common on other systems.
6356 #.  FIXME In the preceding sentence, which modifications are disallowed,
6357 #.  and when they are disallowed, how does user space discover that fact?
6358 #. type: Plain text
6359 #: build/C/man2/ptrace.2:213
6360 msgid ""
6361 "Copy the word I<data> to offset I<addr> in the tracee's USER area.  As for "
6362 "B<PTRACE_PEEKUSER>, the offset must typically be word-aligned.  In order to "
6363 "maintain the integrity of the kernel, some modifications to the USER area "
6364 "are disallowed."
6365 msgstr ""
6366
6367 #. type: TP
6368 #: build/C/man2/ptrace.2:213
6369 #, no-wrap
6370 msgid "B<PTRACE_GETREGS>, B<PTRACE_GETFPREGS>"
6371 msgstr ""
6372
6373 #. type: Plain text
6374 #: build/C/man2/ptrace.2:236
6375 msgid ""
6376 "Copy the tracee's general-purpose or floating-point registers, respectively, "
6377 "to the address I<data> in the tracer.  See I<E<lt>sys/user.hE<gt>> for "
6378 "information on the format of this data.  (I<addr> is ignored.)  Note that "
6379 "SPARC systems have the meaning of I<data> and I<addr> reversed; that is, "
6380 "I<data> is ignored and the registers are copied to the address I<addr>.  "
6381 "B<PTRACE_GETREGS> and B<PTRACE_GETFPREGS> are not present on all "
6382 "architectures."
6383 msgstr ""
6384
6385 #. type: TP
6386 #: build/C/man2/ptrace.2:236
6387 #, no-wrap
6388 msgid "B<PTRACE_GETREGSET> (since Linux 2.6.34)"
6389 msgstr ""
6390
6391 #. type: Plain text
6392 #: build/C/man2/ptrace.2:257
6393 msgid ""
6394 "Read the tracee's registers.  I<addr> specifies, in an "
6395 "architecture-dependent way, the type of registers to be read.  "
6396 "B<NT_PRSTATUS> (with numerical value 1)  usually results in reading of "
6397 "general-purpose registers.  If the CPU has, for example, floating-point "
6398 "and/or vector registers, they can be retrieved by setting I<addr> to the "
6399 "corresponding B<NT_foo> constant.  I<data> points to a B<struct iovec>, "
6400 "which describes the destination buffer's location and length.  On return, "
6401 "the kernel modifies B<iov.len> to indicate the actual number of bytes "
6402 "returned."
6403 msgstr ""
6404
6405 #. type: TP
6406 #: build/C/man2/ptrace.2:257
6407 #, no-wrap
6408 msgid "B<PTRACE_GETSIGINFO> (since Linux 2.3.99-pre6)"
6409 msgstr ""
6410
6411 #. type: Plain text
6412 #: build/C/man2/ptrace.2:269
6413 msgid ""
6414 "Retrieve information about the signal that caused the stop.  Copy a "
6415 "I<siginfo_t> structure (see B<sigaction>(2))  from the tracee to the address "
6416 "I<data> in the tracer.  (I<addr> is ignored.)"
6417 msgstr ""
6418
6419 #. type: TP
6420 #: build/C/man2/ptrace.2:269
6421 #, no-wrap
6422 msgid "B<PTRACE_SETREGS>, B<PTRACE_SETFPREGS>"
6423 msgstr ""
6424
6425 #.  FIXME In the preceding sentence, which modifications are disallowed,
6426 #.  and when they are disallowed, how does user space discover that fact?
6427 #. type: Plain text
6428 #: build/C/man2/ptrace.2:294
6429 msgid ""
6430 "Modify the tracee's general-purpose or floating-point registers, "
6431 "respectively, from the address I<data> in the tracer.  As for "
6432 "B<PTRACE_POKEUSER>, some general-purpose register modifications may be "
6433 "disallowed.  (I<addr> is ignored.)  Note that SPARC systems have the meaning "
6434 "of I<data> and I<addr> reversed; that is, I<data> is ignored and the "
6435 "registers are copied from the address I<addr>.  B<PTRACE_SETREGS> and "
6436 "B<PTRACE_SETFPREGS> are not present on all architectures."
6437 msgstr ""
6438
6439 #. type: TP
6440 #: build/C/man2/ptrace.2:294
6441 #, no-wrap
6442 msgid "B<PTRACE_SETREGSET> (since Linux 2.6.34)"
6443 msgstr ""
6444
6445 #. type: Plain text
6446 #: build/C/man2/ptrace.2:303
6447 msgid ""
6448 "Modify the tracee's registers.  The meaning of I<addr> and I<data> is "
6449 "analogous to B<PTRACE_GETREGSET>."
6450 msgstr ""
6451
6452 #. type: TP
6453 #: build/C/man2/ptrace.2:303
6454 #, no-wrap
6455 msgid "B<PTRACE_SETSIGINFO> (since Linux 2.3.99-pre6)"
6456 msgstr ""
6457
6458 #. type: Plain text
6459 #: build/C/man2/ptrace.2:319
6460 msgid ""
6461 "Set signal information: copy a I<siginfo_t> structure from the address "
6462 "I<data> in the tracer to the tracee.  This will affect only signals that "
6463 "would normally be delivered to the tracee and were caught by the tracer.  It "
6464 "may be difficult to tell these normal signals from synthetic signals "
6465 "generated by B<ptrace>()  itself.  (I<addr> is ignored.)"
6466 msgstr ""
6467
6468 #. type: TP
6469 #: build/C/man2/ptrace.2:319
6470 #, no-wrap
6471 msgid "B<PTRACE_SETOPTIONS> (since Linux 2.4.6; see BUGS for caveats)"
6472 msgstr ""
6473
6474 #. type: Plain text
6475 #: build/C/man2/ptrace.2:328
6476 msgid ""
6477 "Set ptrace options from I<data>.  (I<addr> is ignored.)  I<data> is "
6478 "interpreted as a bit mask of options, which are specified by the following "
6479 "flags:"
6480 msgstr ""
6481
6482 #. type: TP
6483 #: build/C/man2/ptrace.2:329
6484 #, no-wrap
6485 msgid "B<PTRACE_O_EXITKILL> (since Linux 3.8)"
6486 msgstr ""
6487
6488 #.  commit 992fb6e170639b0849bace8e49bf31bd37c4123
6489 #. type: Plain text
6490 #: build/C/man2/ptrace.2:337
6491 msgid ""
6492 "If a tracer sets this flag, a B<SIGKILL> signal will be sent to every tracee "
6493 "if the tracer exits.  This option is useful for ptrace jailers that want to "
6494 "ensure that tracees can never escape the tracer's control."
6495 msgstr ""
6496
6497 #. type: TP
6498 #: build/C/man2/ptrace.2:337
6499 #, no-wrap
6500 msgid "B<PTRACE_O_TRACECLONE> (since Linux 2.5.46)"
6501 msgstr ""
6502
6503 #. type: Plain text
6504 #: build/C/man2/ptrace.2:349
6505 msgid ""
6506 "Stop the tracee at the next B<clone>(2)  and automatically start tracing the "
6507 "newly cloned process, which will start with a B<SIGSTOP>.  A B<waitpid>(2)  "
6508 "by the tracer will return a I<status> value such that"
6509 msgstr ""
6510
6511 #. type: Plain text
6512 #: build/C/man2/ptrace.2:352
6513 #, no-wrap
6514 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_CLONEE<lt>E<lt>8))\n"
6515 msgstr ""
6516
6517 #. type: Plain text
6518 #: build/C/man2/ptrace.2:356 build/C/man2/ptrace.2:437 build/C/man2/ptrace.2:465
6519 msgid "The PID of the new process can be retrieved with B<PTRACE_GETEVENTMSG>."
6520 msgstr ""
6521
6522 #. type: Plain text
6523 #: build/C/man2/ptrace.2:377
6524 msgid ""
6525 "This option may not catch B<clone>(2)  calls in all cases.  If the tracee "
6526 "calls B<clone>(2)  with the B<CLONE_VFORK> flag, B<PTRACE_EVENT_VFORK> will "
6527 "be delivered instead if B<PTRACE_O_TRACEVFORK> is set; otherwise if the "
6528 "tracee calls B<clone>(2)  with the exit signal set to B<SIGCHLD>, "
6529 "B<PTRACE_EVENT_FORK> will be delivered if B<PTRACE_O_TRACEFORK> is set."
6530 msgstr ""
6531
6532 #. type: TP
6533 #: build/C/man2/ptrace.2:377
6534 #, no-wrap
6535 msgid "B<PTRACE_O_TRACEEXEC> (since Linux 2.5.46)"
6536 msgstr ""
6537
6538 #. type: Plain text
6539 #: build/C/man2/ptrace.2:386
6540 msgid ""
6541 "Stop the tracee at the next B<execve>(2).  A B<waitpid>(2)  by the tracer "
6542 "will return a I<status> value such that"
6543 msgstr ""
6544
6545 #. type: Plain text
6546 #: build/C/man2/ptrace.2:389
6547 #, no-wrap
6548 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXECE<lt>E<lt>8))\n"
6549 msgstr ""
6550
6551 #. type: Plain text
6552 #: build/C/man2/ptrace.2:395
6553 msgid ""
6554 "If the execing thread is not a thread group leader, the thread ID is reset "
6555 "to thread group leader's ID before this stop.  Since Linux 3.0, the former "
6556 "thread ID can be retrieved with B<PTRACE_GETEVENTMSG>."
6557 msgstr ""
6558
6559 #. type: TP
6560 #: build/C/man2/ptrace.2:395
6561 #, no-wrap
6562 msgid "B<PTRACE_O_TRACEEXIT> (since Linux 2.5.60)"
6563 msgstr ""
6564
6565 #. type: Plain text
6566 #: build/C/man2/ptrace.2:403
6567 msgid ""
6568 "Stop the tracee at exit.  A B<waitpid>(2)  by the tracer will return a "
6569 "I<status> value such that"
6570 msgstr ""
6571
6572 #. type: Plain text
6573 #: build/C/man2/ptrace.2:406
6574 #, no-wrap
6575 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXITE<lt>E<lt>8))\n"
6576 msgstr ""
6577
6578 #. type: Plain text
6579 #: build/C/man2/ptrace.2:410
6580 msgid "The tracee's exit status can be retrieved with B<PTRACE_GETEVENTMSG>."
6581 msgstr ""
6582
6583 #. type: Plain text
6584 #: build/C/man2/ptrace.2:418
6585 msgid ""
6586 "The tracee is stopped early during process exit, when registers are still "
6587 "available, allowing the tracer to see where the exit occurred, whereas the "
6588 "normal exit notification is done after the process is finished exiting.  "
6589 "Even though context is available, the tracer cannot prevent the exit from "
6590 "happening at this point."
6591 msgstr ""
6592
6593 #. type: TP
6594 #: build/C/man2/ptrace.2:418
6595 #, no-wrap
6596 msgid "B<PTRACE_O_TRACEFORK> (since Linux 2.5.46)"
6597 msgstr ""
6598
6599 #. type: Plain text
6600 #: build/C/man2/ptrace.2:430
6601 msgid ""
6602 "Stop the tracee at the next B<fork>(2)  and automatically start tracing the "
6603 "newly forked process, which will start with a B<SIGSTOP>.  A B<waitpid>(2)  "
6604 "by the tracer will return a I<status> value such that"
6605 msgstr ""
6606
6607 #. type: Plain text
6608 #: build/C/man2/ptrace.2:433
6609 #, no-wrap
6610 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_FORKE<lt>E<lt>8))\n"
6611 msgstr ""
6612
6613 #. type: TP
6614 #: build/C/man2/ptrace.2:437
6615 #, no-wrap
6616 msgid "B<PTRACE_O_TRACESYSGOOD> (since Linux 2.4.6)"
6617 msgstr ""
6618
6619 #. type: Plain text
6620 #: build/C/man2/ptrace.2:446
6621 msgid ""
6622 "When delivering system call traps, set bit 7 in the signal number (i.e., "
6623 "deliver I<SIGTRAP|0x80>).  This makes it easy for the tracer to distinguish "
6624 "normal traps from those caused by a system call.  (B<PTRACE_O_TRACESYSGOOD> "
6625 "may not work on all architectures.)"
6626 msgstr ""
6627
6628 #. type: TP
6629 #: build/C/man2/ptrace.2:446
6630 #, no-wrap
6631 msgid "B<PTRACE_O_TRACEVFORK> (since Linux 2.5.46)"
6632 msgstr ""
6633
6634 #. type: Plain text
6635 #: build/C/man2/ptrace.2:458
6636 msgid ""
6637 "Stop the tracee at the next B<vfork>(2)  and automatically start tracing the "
6638 "newly vforked process, which will start with a B<SIGSTOP>.  A B<waitpid>(2)  "
6639 "by the tracer will return a I<status> value such that"
6640 msgstr ""
6641
6642 #. type: Plain text
6643 #: build/C/man2/ptrace.2:461
6644 #, no-wrap
6645 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORKE<lt>E<lt>8))\n"
6646 msgstr ""
6647
6648 #. type: TP
6649 #: build/C/man2/ptrace.2:465
6650 #, no-wrap
6651 msgid "B<PTRACE_O_TRACEVFORKDONE> (since Linux 2.5.60)"
6652 msgstr ""
6653
6654 #. type: Plain text
6655 #: build/C/man2/ptrace.2:474
6656 msgid ""
6657 "Stop the tracee at the completion of the next B<vfork>(2).  A B<waitpid>(2)  "
6658 "by the tracer will return a I<status> value such that"
6659 msgstr ""
6660
6661 #. type: Plain text
6662 #: build/C/man2/ptrace.2:477
6663 #, no-wrap
6664 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONEE<lt>E<lt>8))\n"
6665 msgstr ""
6666
6667 #. type: Plain text
6668 #: build/C/man2/ptrace.2:481
6669 msgid ""
6670 "The PID of the new process can (since Linux 2.6.18) be retrieved with "
6671 "B<PTRACE_GETEVENTMSG>."
6672 msgstr ""
6673
6674 #. type: TP
6675 #: build/C/man2/ptrace.2:482
6676 #, no-wrap
6677 msgid "B<PTRACE_GETEVENTMSG> (since Linux 2.5.46)"
6678 msgstr ""
6679
6680 #. type: Plain text
6681 #: build/C/man2/ptrace.2:502
6682 msgid ""
6683 "Retrieve a message (as an I<unsigned long>)  about the ptrace event that "
6684 "just happened, placing it at the address I<data> in the tracer.  For "
6685 "B<PTRACE_EVENT_EXIT>, this is the tracee's exit status.  For "
6686 "B<PTRACE_EVENT_FORK>, B<PTRACE_EVENT_VFORK>, B<PTRACE_EVENT_VFORK_DONE>, and "
6687 "B<PTRACE_EVENT_CLONE>, this is the PID of the new process.  (I<addr> is "
6688 "ignored.)"
6689 msgstr ""
6690
6691 #. type: TP
6692 #: build/C/man2/ptrace.2:502
6693 #, no-wrap
6694 msgid "B<PTRACE_CONT>"
6695 msgstr ""
6696
6697 #. type: Plain text
6698 #: build/C/man2/ptrace.2:514
6699 msgid ""
6700 "Restart the stopped tracee process.  If I<data> is nonzero, it is "
6701 "interpreted as the number of a signal to be delivered to the tracee; "
6702 "otherwise, no signal is delivered.  Thus, for example, the tracer can "
6703 "control whether a signal sent to the tracee is delivered or not.  (I<addr> "
6704 "is ignored.)"
6705 msgstr ""
6706
6707 #. type: TP
6708 #: build/C/man2/ptrace.2:514
6709 #, no-wrap
6710 msgid "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>"
6711 msgstr ""
6712
6713 #. type: Plain text
6714 #: build/C/man2/ptrace.2:538
6715 msgid ""
6716 "Restart the stopped tracee as for B<PTRACE_CONT>, but arrange for the tracee "
6717 "to be stopped at the next entry to or exit from a system call, or after "
6718 "execution of a single instruction, respectively.  (The tracee will also, as "
6719 "usual, be stopped upon receipt of a signal.)  From the tracer's perspective, "
6720 "the tracee will appear to have been stopped by receipt of a B<SIGTRAP>.  So, "
6721 "for B<PTRACE_SYSCALL>, for example, the idea is to inspect the arguments to "
6722 "the system call at the first stop, then do another B<PTRACE_SYSCALL> and "
6723 "inspect the return value of the system call at the second stop.  The I<data> "
6724 "argument is treated as for B<PTRACE_CONT>.  (I<addr> is ignored.)"
6725 msgstr ""
6726
6727 #. type: TP
6728 #: build/C/man2/ptrace.2:538
6729 #, no-wrap
6730 msgid "B<PTRACE_SYSEMU>, B<PTRACE_SYSEMU_SINGLESTEP> (since Linux 2.6.14)"
6731 msgstr ""
6732
6733 #.  As at 3.7
6734 #. type: Plain text
6735 #: build/C/man2/ptrace.2:559
6736 msgid ""
6737 "For B<PTRACE_SYSEMU>, continue and stop on entry to the next system call, "
6738 "which will not be executed.  For B<PTRACE_SYSEMU_SINGLESTEP>, do the same "
6739 "but also singlestep if not a system call.  This call is used by programs "
6740 "like User Mode Linux that want to emulate all the tracee's system calls.  "
6741 "The I<data> argument is treated as for B<PTRACE_CONT>.  The I<addr> argument "
6742 "is ignored.  These requests are currently supported only on x86."
6743 msgstr ""
6744
6745 #. type: TP
6746 #: build/C/man2/ptrace.2:559
6747 #, no-wrap
6748 msgid "B<PTRACE_LISTEN> (since Linux 3.4)"
6749 msgstr ""
6750
6751 #. type: Plain text
6752 #: build/C/man2/ptrace.2:570
6753 msgid ""
6754 "Restart the stopped tracee, but prevent it from executing.  The resulting "
6755 "state of the tracee is similar to a process which has been stopped by a "
6756 "B<SIGSTOP> (or other stopping signal).  See the \"group-stop\" subsection "
6757 "for additional information.  B<PTRACE_LISTEN> only works on tracees attached "
6758 "by B<PTRACE_SEIZE>."
6759 msgstr ""
6760
6761 #. type: TP
6762 #: build/C/man2/ptrace.2:570
6763 #, no-wrap
6764 msgid "B<PTRACE_KILL>"
6765 msgstr ""
6766
6767 #. type: Plain text
6768 #: build/C/man2/ptrace.2:579
6769 msgid ""
6770 "Send the tracee a B<SIGKILL> to terminate it.  (I<addr> and I<data> are "
6771 "ignored.)"
6772 msgstr ""
6773
6774 #.  [Note from Denys Vlasenko:
6775 #.      deprecation suggested by Oleg Nesterov. He prefers to deprecate it
6776 #.      instead of describing (and needing to support) PTRACE_KILL's quirks.]
6777 #. type: Plain text
6778 #: build/C/man2/ptrace.2:598
6779 msgid ""
6780 "I<This operation is deprecated; do not use it!> Instead, send a B<SIGKILL> "
6781 "directly using B<kill>(2)  or B<tgkill>(2).  The problem with B<PTRACE_KILL> "
6782 "is that it requires the tracee to be in signal-delivery-stop, otherwise it "
6783 "may not work (i.e., may complete successfully but won't kill the tracee).  "
6784 "By contrast, sending a B<SIGKILL> directly has no such limitation."
6785 msgstr ""
6786
6787 #. type: TP
6788 #: build/C/man2/ptrace.2:598
6789 #, no-wrap
6790 msgid "B<PTRACE_INTERRUPT> (since Linux 3.4)"
6791 msgstr ""
6792
6793 #. type: Plain text
6794 #: build/C/man2/ptrace.2:612
6795 msgid ""
6796 "Stop a tracee.  If the tracee is running, it will stop with "
6797 "B<PTRACE_EVENT_STOP>.  If the tracee is already stopped by a signal, or "
6798 "receives a signal in parallel with B<PTRACE_INTERRUPT>, it may report a "
6799 "group-stop or a signal-delivery-stop instead of B<PTRACE_EVENT_STOP>.  "
6800 "B<PTRACE_INTERRUPT> only works on tracees attached by B<PTRACE_SEIZE>."
6801 msgstr ""
6802
6803 #. type: TP
6804 #: build/C/man2/ptrace.2:612
6805 #, no-wrap
6806 msgid "B<PTRACE_ATTACH>"
6807 msgstr ""
6808
6809 #.  No longer true (removed by Denys Vlasenko, 2011, who remarks:
6810 #.         "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
6811 #.          Basically, it's not true for any Linux in practical use.
6812 #.  ; the behavior of the tracee is as if it had done a
6813 #.  .BR PTRACE_TRACEME .
6814 #.  The calling process actually becomes the parent of the tracee
6815 #.  process for most purposes (e.g., it will receive
6816 #.  notification of tracee events and appears in
6817 #.  .BR ps (1)
6818 #.  output as the tracee's parent), but a
6819 #.  .BR getppid (2)
6820 #.  by the tracee will still return the PID of the original parent.
6821 #. type: Plain text
6822 #: build/C/man2/ptrace.2:640
6823 msgid ""
6824 "Attach to the process specified in I<pid>, making it a tracee of the calling "
6825 "process.  The tracee is sent a B<SIGSTOP>, but will not necessarily have "
6826 "stopped by the completion of this call; use B<waitpid>(2)  to wait for the "
6827 "tracee to stop.  See the \"Attaching and detaching\" subsection for "
6828 "additional information.  (I<addr> and I<data> are ignored.)"
6829 msgstr ""
6830
6831 #. type: TP
6832 #: build/C/man2/ptrace.2:640
6833 #, no-wrap
6834 msgid "B<PTRACE_SEIZE> (since Linux 3.4)"
6835 msgstr ""
6836
6837 #. type: Plain text
6838 #: build/C/man2/ptrace.2:660
6839 msgid ""
6840 "Attach to the process specified in I<pid>, making it a tracee of the calling "
6841 "process.  Unlike B<PTRACE_ATTACH>, B<PTRACE_SEIZE> does not stop the "
6842 "process.  Only a B<PTRACE_SEIZE>d process can accept B<PTRACE_INTERRUPT> and "
6843 "B<PTRACE_LISTEN> commands.  I<addr> must be zero.  I<data> contains a bit "
6844 "mask of ptrace options to activate immediately."
6845 msgstr ""
6846
6847 #. type: TP
6848 #: build/C/man2/ptrace.2:660
6849 #, no-wrap
6850 msgid "B<PTRACE_DETACH>"
6851 msgstr ""
6852
6853 #. type: Plain text
6854 #: build/C/man2/ptrace.2:669
6855 msgid ""
6856 "Restart the stopped tracee as for B<PTRACE_CONT>, but first detach from it.  "
6857 "Under Linux, a tracee can be detached in this way regardless of which method "
6858 "was used to initiate tracing.  (I<addr> is ignored.)"
6859 msgstr ""
6860
6861 #. type: SS
6862 #: build/C/man2/ptrace.2:669
6863 #, no-wrap
6864 msgid "Death under ptrace"
6865 msgstr ""
6866
6867 #. type: Plain text
6868 #: build/C/man2/ptrace.2:678
6869 msgid ""
6870 "When a (possibly multithreaded) process receives a killing signal (one whose "
6871 "disposition is set to B<SIG_DFL> and whose default action is to kill the "
6872 "process), all threads exit.  Tracees report their death to their tracer(s).  "
6873 "Notification of this event is delivered via B<waitpid>(2)."
6874 msgstr ""
6875
6876 #. type: Plain text
6877 #: build/C/man2/ptrace.2:687
6878 msgid ""
6879 "Note that the killing signal will first cause signal-delivery-stop (on one "
6880 "tracee only), and only after it is injected by the tracer (or after it was "
6881 "dispatched to a thread which isn't traced), will death from the signal "
6882 "happen on I<all> tracees within a multithreaded process.  (The term "
6883 "\"signal-delivery-stop\" is explained below.)"
6884 msgstr ""
6885
6886 #. type: Plain text
6887 #: build/C/man2/ptrace.2:699
6888 msgid ""
6889 "B<SIGKILL> does not generate signal-delivery-stop and therefore the tracer "
6890 "can't suppress it.  B<SIGKILL> kills even within system calls "
6891 "(syscall-exit-stop is not generated prior to death by B<SIGKILL>).  The net "
6892 "effect is that B<SIGKILL> always kills the process (all its threads), even "
6893 "if some threads of the process are ptraced."
6894 msgstr ""
6895
6896 #. type: Plain text
6897 #: build/C/man2/ptrace.2:704
6898 msgid ""
6899 "When the tracee calls B<_exit>(2), it reports its death to its tracer.  "
6900 "Other threads are not affected."
6901 msgstr ""
6902
6903 #. type: Plain text
6904 #: build/C/man2/ptrace.2:708
6905 msgid ""
6906 "When any thread executes B<exit_group>(2), every tracee in its thread group "
6907 "reports its death to its tracer."
6908 msgstr ""
6909
6910 #. type: Plain text
6911 #: build/C/man2/ptrace.2:722
6912 msgid ""
6913 "If the B<PTRACE_O_TRACEEXIT> option is on, B<PTRACE_EVENT_EXIT> will happen "
6914 "before actual death.  This applies to exits via B<exit>(2), "
6915 "B<exit_group>(2), and signal deaths (except B<SIGKILL>), and when threads "
6916 "are torn down on B<execve>(2)  in a multithreaded process."
6917 msgstr ""
6918
6919 #. type: Plain text
6920 #: build/C/man2/ptrace.2:747
6921 msgid ""
6922 "The tracer cannot assume that the ptrace-stopped tracee exists.  There are "
6923 "many scenarios when the tracee may die while stopped (such as B<SIGKILL>).  "
6924 "Therefore, the tracer must be prepared to handle an B<ESRCH> error on any "
6925 "ptrace operation.  Unfortunately, the same error is returned if the tracee "
6926 "exists but is not ptrace-stopped (for commands which require a stopped "
6927 "tracee), or if it is not traced by the process which issued the ptrace "
6928 "call.  The tracer needs to keep track of the stopped/running state of the "
6929 "tracee, and interpret B<ESRCH> as \"tracee died unexpectedly\" only if it "
6930 "knows that the tracee has been observed to enter ptrace-stop.  Note that "
6931 "there is no guarantee that I<waitpid(WNOHANG)> will reliably report the "
6932 "tracee's death status if a ptrace operation returned B<ESRCH>.  "
6933 "I<waitpid(WNOHANG)> may return 0 instead.  In other words, the tracee may be "
6934 "\"not yet fully dead\", but already refusing ptrace requests."
6935 msgstr ""
6936
6937 #. type: Plain text
6938 #: build/C/man2/ptrace.2:761
6939 msgid ""
6940 "The tracer can't assume that the tracee I<always> ends its life by reporting "
6941 "I<WIFEXITED(status)> or I<WIFSIGNALED(status)>; there are cases where this "
6942 "does not occur.  For example, if a thread other than thread group leader "
6943 "does an B<execve>(2), it disappears; its PID will never be seen again, and "
6944 "any subsequent ptrace stops will be reported under the thread group leader's "
6945 "PID."
6946 msgstr ""
6947
6948 #. type: SS
6949 #: build/C/man2/ptrace.2:761
6950 #, no-wrap
6951 msgid "Stopped states"
6952 msgstr ""
6953
6954 #. type: Plain text
6955 #: build/C/man2/ptrace.2:763
6956 msgid "A tracee can be in two states: running or stopped."
6957 msgstr ""
6958
6959 #. type: Plain text
6960 #: build/C/man2/ptrace.2:767
6961 msgid ""
6962 "There are many kinds of states when the tracee is stopped, and in ptrace "
6963 "discussions they are often conflated.  Therefore, it is important to use "
6964 "precise terms."
6965 msgstr ""
6966
6967 #. type: Plain text
6968 #: build/C/man2/ptrace.2:778
6969 msgid ""
6970 "In this manual page, any stopped state in which the tracee is ready to "
6971 "accept ptrace commands from the tracer is called I<ptrace-stop>.  "
6972 "Ptrace-stops can be further subdivided into I<signal-delivery-stop>, "
6973 "I<group-stop>, I<syscall-stop>, and so on.  These stopped states are "
6974 "described in detail below."
6975 msgstr ""
6976
6977 #. type: Plain text
6978 #: build/C/man2/ptrace.2:783
6979 msgid ""
6980 "When the running tracee enters ptrace-stop, it notifies its tracer using "
6981 "B<waitpid>(2)  (or one of the other \"wait\" system calls).  Most of this "
6982 "manual page assumes that the tracer waits with:"
6983 msgstr ""
6984
6985 #. type: Plain text
6986 #: build/C/man2/ptrace.2:785
6987 #, no-wrap
6988 msgid "    pid = waitpid(pid_or_minus_1, &status, __WALL);\n"
6989 msgstr ""
6990
6991 #.  Denys Vlasenko:
6992 #.      Do we require __WALL usage, or will just using 0 be ok? (With 0,
6993 #.      I am not 100% sure there aren't ugly corner cases.) Are the
6994 #.      rules different if user wants to use waitid? Will waitid require
6995 #.      WEXITED?
6996 #. type: Plain text
6997 #: build/C/man2/ptrace.2:797
6998 msgid ""
6999 "Ptrace-stopped tracees are reported as returns with I<pid> greater than 0 "
7000 "and I<WIFSTOPPED(status)> true."
7001 msgstr ""
7002
7003 #. type: Plain text
7004 #: build/C/man2/ptrace.2:805
7005 msgid ""
7006 "The B<__WALL> flag does not include the B<WSTOPPED> and B<WEXITED> flags, "
7007 "but implies their functionality."
7008 msgstr ""
7009
7010 #. type: Plain text
7011 #: build/C/man2/ptrace.2:812
7012 msgid ""
7013 "Setting the B<WCONTINUED> flag when calling B<waitpid>(2)  is not "
7014 "recommended: the \"continued\" state is per-process and consuming it can "
7015 "confuse the real parent of the tracee."
7016 msgstr ""
7017
7018 #. type: Plain text
7019 #: build/C/man2/ptrace.2:820
7020 msgid ""
7021 "Use of the B<WNOHANG> flag may cause B<waitpid>(2)  to return 0 (\"no wait "
7022 "results available yet\")  even if the tracer knows there should be a "
7023 "notification.  Example:"
7024 msgstr ""
7025
7026 #. type: Plain text
7027 #: build/C/man2/ptrace.2:829
7028 #, no-wrap
7029 msgid ""
7030 "    errno = 0;\n"
7031 "    ptrace(PTRACE_CONT, pid, 0L, 0L);\n"
7032 "    if (errno == ESRCH) {\n"
7033 "        /* tracee is dead */\n"
7034 "        r = waitpid(tracee, &status, __WALL | WNOHANG);\n"
7035 "        /* r can still be 0 here! */\n"
7036 "    }\n"
7037 msgstr ""
7038
7039 #. type: Plain text
7040 #: build/C/man2/ptrace.2:852
7041 msgid ""
7042 "The following kinds of ptrace-stops exist: signal-delivery-stops, "
7043 "group-stops, B<PTRACE_EVENT> stops, syscall-stops.  They all are reported by "
7044 "B<waitpid>(2)  with I<WIFSTOPPED(status)> true.  They may be differentiated "
7045 "by examining the value I<statusE<gt>E<gt>8>, and if there is ambiguity in "
7046 "that value, by querying B<PTRACE_GETSIGINFO>.  (Note: the "
7047 "I<WSTOPSIG(status)> macro can't be used to perform this examination, because "
7048 "it returns the value I<(statusE<gt>E<gt>8)\\ &\\ 0xff>.)"
7049 msgstr ""
7050
7051 #. type: SS
7052 #: build/C/man2/ptrace.2:852
7053 #, no-wrap
7054 msgid "Signal-delivery-stop"
7055 msgstr ""
7056
7057 #. type: Plain text
7058 #: build/C/man2/ptrace.2:872
7059 msgid ""
7060 "When a (possibly multithreaded) process receives any signal except "
7061 "B<SIGKILL>, the kernel selects an arbitrary thread which handles the "
7062 "signal.  (If the signal is generated with B<tgkill>(2), the target thread "
7063 "can be explicitly selected by the caller.)  If the selected thread is "
7064 "traced, it enters signal-delivery-stop.  At this point, the signal is not "
7065 "yet delivered to the process, and can be suppressed by the tracer.  If the "
7066 "tracer doesn't suppress the signal, it passes the signal to the tracee in "
7067 "the next ptrace restart request.  This second step of signal delivery is "
7068 "called I<signal injection> in this manual page.  Note that if the signal is "
7069 "blocked, signal-delivery-stop doesn't happen until the signal is unblocked, "
7070 "with the usual exception that B<SIGSTOP> can't be blocked."
7071 msgstr ""
7072
7073 #. type: Plain text
7074 #: build/C/man2/ptrace.2:886
7075 msgid ""
7076 "Signal-delivery-stop is observed by the tracer as B<waitpid>(2)  returning "
7077 "with I<WIFSTOPPED(status)> true, with the signal returned by "
7078 "I<WSTOPSIG(status)>.  If the signal is B<SIGTRAP>, this may be a different "
7079 "kind of ptrace-stop; see the \"Syscall-stops\" and \"execve\" sections below "
7080 "for details.  If I<WSTOPSIG(status)> returns a stopping signal, this may be "
7081 "a group-stop; see below."
7082 msgstr ""
7083
7084 #. type: SS
7085 #: build/C/man2/ptrace.2:886
7086 #, no-wrap
7087 msgid "Signal injection and suppression"
7088 msgstr ""
7089
7090 #. type: Plain text
7091 #: build/C/man2/ptrace.2:889
7092 msgid ""
7093 "After signal-delivery-stop is observed by the tracer, the tracer should "
7094 "restart the tracee with the call"
7095 msgstr ""
7096
7097 #. type: Plain text
7098 #: build/C/man2/ptrace.2:891
7099 #, no-wrap
7100 msgid "    ptrace(PTRACE_restart, pid, 0, sig)\n"
7101 msgstr ""
7102
7103 #. type: Plain text
7104 #: build/C/man2/ptrace.2:904
7105 msgid ""
7106 "where B<PTRACE_restart> is one of the restarting ptrace requests.  If I<sig> "
7107 "is 0, then a signal is not delivered.  Otherwise, the signal I<sig> is "
7108 "delivered.  This operation is called I<signal injection> in this manual "
7109 "page, to distinguish it from signal-delivery-stop."
7110 msgstr ""
7111
7112 #. type: Plain text
7113 #: build/C/man2/ptrace.2:910
7114 msgid ""
7115 "The I<sig> value may be different from the I<WSTOPSIG(status)> value: the "
7116 "tracer can cause a different signal to be injected."
7117 msgstr ""
7118
7119 #. type: Plain text
7120 #: build/C/man2/ptrace.2:926
7121 msgid ""
7122 "Note that a suppressed signal still causes system calls to return "
7123 "prematurely.  In this case system calls will be restarted: the tracer will "
7124 "observe the tracee to reexecute the interrupted system call (or "
7125 "B<restart_syscall>(2)  system call for a few syscalls which use a different "
7126 "mechanism for restarting) if the tracer uses B<PTRACE_SYSCALL>.  Even system "
7127 "calls (such as B<poll>(2))  which are not restartable after signal are "
7128 "restarted after signal is suppressed; however, kernel bugs exist which cause "
7129 "some syscalls to fail with B<EINTR> even though no observable signal is "
7130 "injected to the tracee."
7131 msgstr ""
7132
7133 #. type: Plain text
7134 #: build/C/man2/ptrace.2:937
7135 msgid ""
7136 "Restarting ptrace commands issued in ptrace-stops other than "
7137 "signal-delivery-stop are not guaranteed to inject a signal, even if I<sig> "
7138 "is nonzero.  No error is reported; a nonzero I<sig> may simply be ignored.  "
7139 "Ptrace users should not try to \"create a new signal\" this way: use "
7140 "B<tgkill>(2)  instead."
7141 msgstr ""
7142
7143 #. type: Plain text
7144 #: build/C/man2/ptrace.2:944
7145 msgid ""
7146 "The fact that signal injection requests may be ignored when restarting the "
7147 "tracee after ptrace stops that are not signal-delivery-stops is a cause of "
7148 "confusion among ptrace users.  One typical scenario is that the tracer "
7149 "observes group-stop, mistakes it for signal-delivery-stop, restarts the "
7150 "tracee with"
7151 msgstr ""
7152
7153 #. type: Plain text
7154 #: build/C/man2/ptrace.2:946
7155 #, no-wrap
7156 msgid "    ptrace(PTRACE_restart, pid, 0, stopsig)\n"
7157 msgstr ""
7158
7159 #. type: Plain text
7160 #: build/C/man2/ptrace.2:952
7161 msgid ""
7162 "with the intention of injecting I<stopsig>, but I<stopsig> gets ignored and "
7163 "the tracee continues to run."
7164 msgstr ""
7165
7166 #. type: Plain text
7167 #: build/C/man2/ptrace.2:972
7168 msgid ""
7169 "The B<SIGCONT> signal has a side effect of waking up (all threads of)  a "
7170 "group-stopped process.  This side effect happens before "
7171 "signal-delivery-stop.  The tracer can't suppress this side effect (it can "
7172 "only suppress signal injection, which only causes the B<SIGCONT> handler to "
7173 "not be executed in the tracee, if such a handler is installed).  In fact, "
7174 "waking up from group-stop may be followed by signal-delivery-stop for "
7175 "signal(s)  I<other than> B<SIGCONT>, if they were pending when B<SIGCONT> "
7176 "was delivered.  In other words, B<SIGCONT> may be not the first signal "
7177 "observed by the tracee after it was sent."
7178 msgstr ""
7179
7180 #. type: Plain text
7181 #: build/C/man2/ptrace.2:976
7182 msgid ""
7183 "Stopping signals cause (all threads of) a process to enter group-stop.  This "
7184 "side effect happens after signal injection, and therefore can be suppressed "
7185 "by the tracer."
7186 msgstr ""
7187
7188 #.  In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
7189 #.  there is:
7190 #
7191 #.              /* The debugger continued.  Ignore SIGSTOP.  */
7192 #.              if (signr == SIGSTOP)
7193 #.                      continue;
7194 #. type: Plain text
7195 #: build/C/man2/ptrace.2:986
7196 msgid "In Linux 2.4 and earlier, the B<SIGSTOP> signal can't be injected."
7197 msgstr ""
7198
7199 #. type: Plain text
7200 #: build/C/man2/ptrace.2:1003
7201 msgid ""
7202 "B<PTRACE_GETSIGINFO> can be used to retrieve a I<siginfo_t> structure which "
7203 "corresponds to the delivered signal.  B<PTRACE_SETSIGINFO> may be used to "
7204 "modify it.  If B<PTRACE_SETSIGINFO> has been used to alter I<siginfo_t>, the "
7205 "I<si_signo> field and the I<sig> parameter in the restarting command must "
7206 "match, otherwise the result is undefined."
7207 msgstr ""
7208
7209 #. type: SS
7210 #: build/C/man2/ptrace.2:1003
7211 #, no-wrap
7212 msgid "Group-stop"
7213 msgstr ""
7214
7215 #. type: Plain text
7216 #: build/C/man2/ptrace.2:1015
7217 msgid ""
7218 "When a (possibly multithreaded) process receives a stopping signal, all "
7219 "threads stop.  If some threads are traced, they enter a group-stop.  Note "
7220 "that the stopping signal will first cause signal-delivery-stop (on one "
7221 "tracee only), and only after it is injected by the tracer (or after it was "
7222 "dispatched to a thread which isn't traced), will group-stop be initiated on "
7223 "I<all> tracees within the multithreaded process.  As usual, every tracee "
7224 "reports its group-stop separately to the corresponding tracer."
7225 msgstr ""
7226
7227 #. type: Plain text
7228 #: build/C/man2/ptrace.2:1024
7229 msgid ""
7230 "Group-stop is observed by the tracer as B<waitpid>(2)  returning with "
7231 "I<WIFSTOPPED(status)> true, with the stopping signal available via "
7232 "I<WSTOPSIG(status)>.  The same result is returned by some other classes of "
7233 "ptrace-stops, therefore the recommended practice is to perform the call"
7234 msgstr ""
7235
7236 #. type: Plain text
7237 #: build/C/man2/ptrace.2:1026
7238 #, no-wrap
7239 msgid "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)\n"
7240 msgstr ""
7241
7242 #. type: Plain text
7243 #: build/C/man2/ptrace.2:1047
7244 msgid ""
7245 "The call can be avoided if the signal is not B<SIGSTOP>, B<SIGTSTP>, "
7246 "B<SIGTTIN>, or B<SIGTTOU>; only these four signals are stopping signals.  If "
7247 "the tracer sees something else, it can't be a group-stop.  Otherwise, the "
7248 "tracer needs to call B<PTRACE_GETSIGINFO>.  If B<PTRACE_GETSIGINFO> fails "
7249 "with B<EINVAL>, then it is definitely a group-stop.  (Other failure codes "
7250 "are possible, such as B<ESRCH> (\"no such process\") if a B<SIGKILL> killed "
7251 "the tracee.)"
7252 msgstr ""
7253
7254 #. type: Plain text
7255 #: build/C/man2/ptrace.2:1056
7256 msgid ""
7257 "As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until "
7258 "it restarts or kills it, the tracee will not run, and will not send "
7259 "notifications (except B<SIGKILL> death) to the tracer, even if the tracer "
7260 "enters into another B<waitpid>(2)  call."
7261 msgstr ""
7262
7263 #. type: Plain text
7264 #: build/C/man2/ptrace.2:1070
7265 msgid ""
7266 "The kernel behavior described in the previous paragraph causes a problem "
7267 "with transparent handling of stopping signals.  If the tracer restarts the "
7268 "tracee after group-stop, the stopping signal is effectively ignored\\(emthe "
7269 "tracee doesn't remain stopped, it runs.  If the tracer doesn't restart the "
7270 "tracee before entering into the next B<waitpid>(2), future B<SIGCONT> "
7271 "signals will not be reported to the tracer; this would cause the B<SIGCONT> "
7272 "signals to have no effect on the tracee."
7273 msgstr ""
7274
7275 #. type: Plain text
7276 #: build/C/man2/ptrace.2:1081
7277 msgid ""
7278 "Since Linux 3.4, there is a method to overcome this problem: instead of "
7279 "B<PTRACE_CONT>, a B<PTRACE_LISTEN> command can be used to restart a tracee "
7280 "in a way where it does not execute, but waits for a new event which it can "
7281 "report via B<waitpid>(2)  (such as when it is restarted by a B<SIGCONT>)."
7282 msgstr ""
7283
7284 #. type: SS
7285 #: build/C/man2/ptrace.2:1081
7286 #, no-wrap
7287 msgid "PTRACE_EVENT stops"
7288 msgstr ""
7289
7290 #. type: Plain text
7291 #: build/C/man2/ptrace.2:1087
7292 msgid ""
7293 "If the tracer sets B<PTRACE_O_TRACE_*> options, the tracee will enter "
7294 "ptrace-stops called B<PTRACE_EVENT> stops."
7295 msgstr ""
7296
7297 #. type: Plain text
7298 #: build/C/man2/ptrace.2:1101
7299 msgid ""
7300 "B<PTRACE_EVENT> stops are observed by the tracer as B<waitpid>(2)  returning "
7301 "with I<WIFSTOPPED(status)>, and I<WSTOPSIG(status)> returns B<SIGTRAP>.  An "
7302 "additional bit is set in the higher byte of the status word: the value "
7303 "I<statusE<gt>E<gt>8> will be"
7304 msgstr ""
7305
7306 #. type: Plain text
7307 #: build/C/man2/ptrace.2:1103
7308 #, no-wrap
7309 msgid "    (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
7310 msgstr ""
7311
7312 #. type: Plain text
7313 #: build/C/man2/ptrace.2:1105
7314 msgid "The following events exist:"
7315 msgstr ""
7316
7317 #. type: TP
7318 #: build/C/man2/ptrace.2:1105
7319 #, no-wrap
7320 msgid "B<PTRACE_EVENT_VFORK>"
7321 msgstr ""
7322
7323 #. type: Plain text
7324 #: build/C/man2/ptrace.2:1118
7325 msgid ""
7326 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
7327 "flag.  When the tracee is continued after this stop, it will wait for child "
7328 "to exit/exec before continuing its execution (in other words, the usual "
7329 "behavior on B<vfork>(2))."
7330 msgstr ""
7331
7332 #. type: TP
7333 #: build/C/man2/ptrace.2:1118
7334 #, no-wrap
7335 msgid "B<PTRACE_EVENT_FORK>"
7336 msgstr ""
7337
7338 #. type: Plain text
7339 #: build/C/man2/ptrace.2:1126
7340 msgid ""
7341 "Stop before return from B<fork>(2)  or B<clone>(2)  with the exit signal set "
7342 "to B<SIGCHLD>."
7343 msgstr ""
7344
7345 #. type: TP
7346 #: build/C/man2/ptrace.2:1126
7347 #, no-wrap
7348 msgid "B<PTRACE_EVENT_CLONE>"
7349 msgstr ""
7350
7351 #. type: Plain text
7352 #: build/C/man2/ptrace.2:1130
7353 msgid "Stop before return from B<clone>(2)."
7354 msgstr ""
7355
7356 #. type: TP
7357 #: build/C/man2/ptrace.2:1130
7358 #, no-wrap
7359 msgid "B<PTRACE_EVENT_VFORK_DONE>"
7360 msgstr ""
7361
7362 #. type: Plain text
7363 #: build/C/man2/ptrace.2:1140
7364 msgid ""
7365 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
7366 "flag, but after the child unblocked this tracee by exiting or execing."
7367 msgstr ""
7368
7369 #. type: Plain text
7370 #: build/C/man2/ptrace.2:1146
7371 msgid ""
7372 "For all four stops described above, the stop occurs in the parent (i.e., the "
7373 "tracee), not in the newly created thread.  B<PTRACE_GETEVENTMSG> can be used "
7374 "to retrieve the new thread's ID."
7375 msgstr ""
7376
7377 #. type: TP
7378 #: build/C/man2/ptrace.2:1146
7379 #, no-wrap
7380 msgid "B<PTRACE_EVENT_EXEC>"
7381 msgstr ""
7382
7383 #. type: Plain text
7384 #: build/C/man2/ptrace.2:1153
7385 msgid ""
7386 "Stop before return from B<execve>(2).  Since Linux 3.0, "
7387 "B<PTRACE_GETEVENTMSG> returns the former thread ID."
7388 msgstr ""
7389
7390 #. type: TP
7391 #: build/C/man2/ptrace.2:1153
7392 #, no-wrap
7393 msgid "B<PTRACE_EVENT_EXIT>"
7394 msgstr ""
7395
7396 #. type: Plain text
7397 #: build/C/man2/ptrace.2:1169
7398 msgid ""
7399 "Stop before exit (including death from B<exit_group>(2)), signal death, or "
7400 "exit caused by B<execve>(2)  in a multithreaded process.  "
7401 "B<PTRACE_GETEVENTMSG> returns the exit status.  Registers can be examined "
7402 "(unlike when \"real\" exit happens).  The tracee is still alive; it needs to "
7403 "be B<PTRACE_CONT>ed or B<PTRACE_DETACH>ed to finish exiting."
7404 msgstr ""
7405
7406 #. type: TP
7407 #: build/C/man2/ptrace.2:1169
7408 #, no-wrap
7409 msgid "B<PTRACE_EVENT_STOP>"
7410 msgstr ""
7411
7412 #. type: Plain text
7413 #: build/C/man2/ptrace.2:1174
7414 msgid "Stop induced by B<PTRACE_INTERRUPT> command."
7415 msgstr ""
7416
7417 #. type: Plain text
7418 #: build/C/man2/ptrace.2:1186
7419 msgid ""
7420 "B<PTRACE_GETSIGINFO> on B<PTRACE_EVENT> stops returns B<SIGTRAP> in "
7421 "I<si_signo>, with I<si_code> set to I<(eventE<lt>E<lt>8)\\ |\\ SIGTRAP>."
7422 msgstr ""
7423
7424 #. type: SS
7425 #: build/C/man2/ptrace.2:1186
7426 #, no-wrap
7427 msgid "Syscall-stops"
7428 msgstr ""
7429
7430 #. type: Plain text
7431 #: build/C/man2/ptrace.2:1199
7432 msgid ""
7433 "If the tracee was restarted by B<PTRACE_SYSCALL>, the tracee enters "
7434 "syscall-enter-stop just prior to entering any system call.  If the tracer "
7435 "restarts the tracee with B<PTRACE_SYSCALL>, the tracee enters "
7436 "syscall-exit-stop when the system call is finished, or if it is interrupted "
7437 "by a signal.  (That is, signal-delivery-stop never happens between "
7438 "syscall-enter-stop and syscall-exit-stop; it happens I<after> "
7439 "syscall-exit-stop.)"
7440 msgstr ""
7441
7442 #. type: Plain text
7443 #: build/C/man2/ptrace.2:1213
7444 msgid ""
7445 "Other possibilities are that the tracee may stop in a B<PTRACE_EVENT> stop, "
7446 "exit (if it entered B<_exit>(2)  or B<exit_group>(2)), be killed by "
7447 "B<SIGKILL>, or die silently (if it is a thread group leader, the "
7448 "B<execve>(2)  happened in another thread, and that thread is not traced by "
7449 "the same tracer; this situation is discussed later)."
7450 msgstr ""
7451
7452 #. type: Plain text
7453 #: build/C/man2/ptrace.2:1228
7454 msgid ""
7455 "Syscall-enter-stop and syscall-exit-stop are observed by the tracer as "
7456 "B<waitpid>(2)  returning with I<WIFSTOPPED(status)> true, and "
7457 "I<WSTOPSIG(status)> giving B<SIGTRAP>.  If the B<PTRACE_O_TRACESYSGOOD> "
7458 "option was set by the tracer, then I<WSTOPSIG(status)> will give the value "
7459 "I<(SIGTRAP\\ |\\ 0x80)>."
7460 msgstr ""
7461
7462 #. type: Plain text
7463 #: build/C/man2/ptrace.2:1234
7464 msgid ""
7465 "Syscall-stops can be distinguished from signal-delivery-stop with B<SIGTRAP> "
7466 "by querying B<PTRACE_GETSIGINFO> for the following cases:"
7467 msgstr ""
7468
7469 #. type: TP
7470 #: build/C/man2/ptrace.2:1234
7471 #, no-wrap
7472 msgid "I<si_code> E<lt>= 0"
7473 msgstr ""
7474
7475 #. type: Plain text
7476 #: build/C/man2/ptrace.2:1246
7477 msgid ""
7478 "B<SIGTRAP> was delivered as a result of a user-space action, for example, a "
7479 "system call (B<tgkill>(2), B<kill>(2), B<sigqueue>(3), etc.), expiration of "
7480 "a POSIX timer, change of state on a POSIX message queue, or completion of an "
7481 "asynchronous I/O request."
7482 msgstr ""
7483
7484 #. type: TP
7485 #: build/C/man2/ptrace.2:1246
7486 #, no-wrap
7487 msgid "I<si_code> == SI_KERNEL (0x80)"
7488 msgstr ""
7489
7490 #. type: Plain text
7491 #: build/C/man2/ptrace.2:1250
7492 msgid "B<SIGTRAP> was sent by the kernel."
7493 msgstr ""
7494
7495 #. type: TP
7496 #: build/C/man2/ptrace.2:1250
7497 #, no-wrap
7498 msgid "I<si_code> == SIGTRAP or I<si_code> == (SIGTRAP|0x80)"
7499 msgstr ""
7500
7501 #. type: Plain text
7502 #: build/C/man2/ptrace.2:1253
7503 msgid "This is a syscall-stop."
7504 msgstr ""
7505
7506 #. type: Plain text
7507 #: build/C/man2/ptrace.2:1258
7508 msgid ""
7509 "However, syscall-stops happen very often (twice per system call), and "
7510 "performing B<PTRACE_GETSIGINFO> for every syscall-stop may be somewhat "
7511 "expensive."
7512 msgstr ""
7513
7514 #. type: Plain text
7515 #: build/C/man2/ptrace.2:1281
7516 msgid ""
7517 "Some architectures allow the cases to be distinguished by examining "
7518 "registers.  For example, on x86, I<rax> == -B<ENOSYS> in "
7519 "syscall-enter-stop.  Since B<SIGTRAP> (like any other signal) always happens "
7520 "I<after> syscall-exit-stop, and at this point I<rax> almost never contains "
7521 "-B<ENOSYS>, the B<SIGTRAP> looks like \"syscall-stop which is not "
7522 "syscall-enter-stop\"; in other words, it looks like a \"stray "
7523 "syscall-exit-stop\" and can be detected this way.  But such detection is "
7524 "fragile and is best avoided."
7525 msgstr ""
7526
7527 #. type: Plain text
7528 #: build/C/man2/ptrace.2:1287
7529 msgid ""
7530 "Using the B<PTRACE_O_TRACESYSGOOD> option is the recommended method to "
7531 "distinguish syscall-stops from other kinds of ptrace-stops, since it is "
7532 "reliable and does not incur a performance penalty."
7533 msgstr ""
7534
7535 #. type: Plain text
7536 #: build/C/man2/ptrace.2:1298
7537 msgid ""
7538 "Syscall-enter-stop and syscall-exit-stop are indistinguishable from each "
7539 "other by the tracer.  The tracer needs to keep track of the sequence of "
7540 "ptrace-stops in order to not misinterpret syscall-enter-stop as "
7541 "syscall-exit-stop or vice versa.  The rule is that syscall-enter-stop is "
7542 "always followed by syscall-exit-stop, B<PTRACE_EVENT> stop or the tracee's "
7543 "death; no other kinds of ptrace-stop can occur in between."
7544 msgstr ""
7545
7546 #. type: Plain text
7547 #: build/C/man2/ptrace.2:1303
7548 msgid ""
7549 "If after syscall-enter-stop, the tracer uses a restarting command other than "
7550 "B<PTRACE_SYSCALL>, syscall-exit-stop is not generated."
7551 msgstr ""
7552
7553 #. type: Plain text
7554 #: build/C/man2/ptrace.2:1315
7555 msgid ""
7556 "B<PTRACE_GETSIGINFO> on syscall-stops returns B<SIGTRAP> in I<si_signo>, "
7557 "with I<si_code> set to B<SIGTRAP> or I<(SIGTRAP|0x80)>."
7558 msgstr ""
7559
7560 #. type: SS
7561 #: build/C/man2/ptrace.2:1315
7562 #, no-wrap
7563 msgid "PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops"
7564 msgstr ""
7565
7566 #
7567 #.  FIXME
7568 #.  document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
7569 #.  PTRACE_SYSEMU_SINGLESTEP
7570 #. type: Plain text
7571 #: build/C/man2/ptrace.2:1321
7572 msgid "[Details of these kinds of stops are yet to be documented.]"
7573 msgstr ""
7574
7575 #. type: SS
7576 #: build/C/man2/ptrace.2:1321
7577 #, no-wrap
7578 msgid "Informational and restarting ptrace commands"
7579 msgstr ""
7580
7581 #. type: Plain text
7582 #: build/C/man2/ptrace.2:1331
7583 msgid ""
7584 "Most ptrace commands (all except B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, "
7585 "B<PTRACE_TRACEME>, B<PTRACE_INTERRUPT>, and B<PTRACE_KILL>)  require the "
7586 "tracee to be in a ptrace-stop, otherwise they fail with B<ESRCH>."
7587 msgstr ""
7588
7589 #. type: Plain text
7590 #: build/C/man2/ptrace.2:1336
7591 msgid ""
7592 "When the tracee is in ptrace-stop, the tracer can read and write data to the "
7593 "tracee using informational commands.  These commands leave the tracee in "
7594 "ptrace-stopped state:"
7595 msgstr ""
7596
7597 #. type: Plain text
7598 #: build/C/man2/ptrace.2:1348
7599 #, no-wrap
7600 msgid ""
7601 "    ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);\n"
7602 "    ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);\n"
7603 "    ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);\n"
7604 "    ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);\n"
7605 "    ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);\n"
7606 "    ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);\n"
7607 "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);\n"
7608 "    ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);\n"
7609 "    ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);\n"
7610 "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
7611 msgstr ""
7612
7613 #. type: Plain text
7614 #: build/C/man2/ptrace.2:1360
7615 msgid ""
7616 "Note that some errors are not reported.  For example, setting signal "
7617 "information (I<siginfo>)  may have no effect in some ptrace-stops, yet the "
7618 "call may succeed (return 0 and not set I<errno>); querying "
7619 "B<PTRACE_GETEVENTMSG> may succeed and return some random value if current "
7620 "ptrace-stop is not documented as returning a meaningful event message."
7621 msgstr ""
7622
7623 #. type: Plain text
7624 #: build/C/man2/ptrace.2:1362
7625 msgid "The call"
7626 msgstr ""
7627
7628 #. type: Plain text
7629 #: build/C/man2/ptrace.2:1364
7630 #, no-wrap
7631 msgid "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
7632 msgstr ""
7633
7634 #. type: Plain text
7635 #: build/C/man2/ptrace.2:1373
7636 msgid ""
7637 "affects one tracee.  The tracee's current flags are replaced.  Flags are "
7638 "inherited by new tracees created and \"auto-attached\" via active "
7639 "B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or B<PTRACE_O_TRACECLONE> "
7640 "options."
7641 msgstr ""
7642
7643 #. type: Plain text
7644 #: build/C/man2/ptrace.2:1376
7645 msgid ""
7646 "Another group of commands makes the ptrace-stopped tracee run.  They have "
7647 "the form:"
7648 msgstr ""
7649
7650 #. type: Plain text
7651 #: build/C/man2/ptrace.2:1378
7652 #, no-wrap
7653 msgid "    ptrace(cmd, pid, 0, sig);\n"
7654 msgstr ""
7655
7656 #. type: Plain text
7657 #: build/C/man2/ptrace.2:1399
7658 msgid ""
7659 "where I<cmd> is B<PTRACE_CONT>, B<PTRACE_LISTEN>, B<PTRACE_DETACH>, "
7660 "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>, B<PTRACE_SYSEMU>, or "
7661 "B<PTRACE_SYSEMU_SINGLESTEP>.  If the tracee is in signal-delivery-stop, "
7662 "I<sig> is the signal to be injected (if it is nonzero).  Otherwise, I<sig> "
7663 "may be ignored.  (When restarting a tracee from a ptrace-stop other than "
7664 "signal-delivery-stop, recommended practice is to always pass 0 in I<sig>.)"
7665 msgstr ""
7666
7667 #. type: SS
7668 #: build/C/man2/ptrace.2:1399
7669 #, no-wrap
7670 msgid "Attaching and detaching"
7671 msgstr ""
7672
7673 #. type: Plain text
7674 #: build/C/man2/ptrace.2:1401
7675 msgid "A thread can be attached to the tracer using the call"
7676 msgstr ""
7677
7678 #. type: Plain text
7679 #: build/C/man2/ptrace.2:1403
7680 #, no-wrap
7681 msgid "    ptrace(PTRACE_ATTACH, pid, 0, 0);\n"
7682 msgstr ""
7683
7684 #. type: Plain text
7685 #: build/C/man2/ptrace.2:1405 build/C/man2/ptrace.2:1894
7686 msgid "or"
7687 msgstr ""
7688
7689 #. type: Plain text
7690 #: build/C/man2/ptrace.2:1407
7691 #, no-wrap
7692 msgid "    ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);\n"
7693 msgstr ""
7694
7695 #
7696 #.  FIXME: Describe how to attach to a thread which is already
7697 #.         group-stopped.
7698 #. type: Plain text
7699 #: build/C/man2/ptrace.2:1432
7700 msgid ""
7701 "B<PTRACE_ATTACH> sends B<SIGSTOP> to this thread.  If the tracer wants this "
7702 "B<SIGSTOP> to have no effect, it needs to suppress it.  Note that if other "
7703 "signals are concurrently sent to this thread during attach, the tracer may "
7704 "see the tracee enter signal-delivery-stop with other signal(s) first! The "
7705 "usual practice is to reinject these signals until B<SIGSTOP> is seen, then "
7706 "suppress B<SIGSTOP> injection.  The design bug here is that a ptrace attach "
7707 "and a concurrently delivered B<SIGSTOP> may race and the concurrent "
7708 "B<SIGSTOP> may be lost."
7709 msgstr ""
7710
7711 #. type: Plain text
7712 #: build/C/man2/ptrace.2:1439
7713 msgid ""
7714 "Since attaching sends B<SIGSTOP> and the tracer usually suppresses it, this "
7715 "may cause a stray B<EINTR> return from the currently executing system call "
7716 "in the tracee, as described in the \"Signal injection and suppression\" "
7717 "section."
7718 msgstr ""
7719
7720 #. type: Plain text
7721 #: build/C/man2/ptrace.2:1450
7722 msgid ""
7723 "Since Linux 3.4, B<PTRACE_SEIZE> can be used instead of B<PTRACE_ATTACH>.  "
7724 "B<PTRACE_SEIZE> does not stop the attached process. If you need to stop it "
7725 "after attach (or at any other time) without sending it any signals, use "
7726 "B<PTRACE_INTERRUPT> command."
7727 msgstr ""
7728
7729 #. type: Plain text
7730 #: build/C/man2/ptrace.2:1452
7731 msgid "The request"
7732 msgstr ""
7733
7734 #. type: Plain text
7735 #: build/C/man2/ptrace.2:1454
7736 #, no-wrap
7737 msgid "    ptrace(PTRACE_TRACEME, 0, 0, 0);\n"
7738 msgstr ""
7739
7740 #. type: Plain text
7741 #: build/C/man2/ptrace.2:1460
7742 msgid ""
7743 "turns the calling thread into a tracee.  The thread continues to run "
7744 "(doesn't enter ptrace-stop).  A common practice is to follow the "
7745 "B<PTRACE_TRACEME> with"
7746 msgstr ""
7747
7748 #. type: Plain text
7749 #: build/C/man2/ptrace.2:1462
7750 #, no-wrap
7751 msgid "    raise(SIGSTOP);\n"
7752 msgstr ""
7753
7754 #. type: Plain text
7755 #: build/C/man2/ptrace.2:1465
7756 msgid ""
7757 "and allow the parent (which is our tracer now) to observe our "
7758 "signal-delivery-stop."
7759 msgstr ""
7760
7761 #. type: Plain text
7762 #: build/C/man2/ptrace.2:1489
7763 msgid ""
7764 "If the B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or "
7765 "B<PTRACE_O_TRACECLONE> options are in effect, then children created by, "
7766 "respectively, B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> flag, "
7767 "B<fork>(2)  or B<clone>(2)  with the exit signal set to B<SIGCHLD>, and "
7768 "other kinds of B<clone>(2), are automatically attached to the same tracer "
7769 "which traced their parent.  B<SIGSTOP> is delivered to the children, causing "
7770 "them to enter signal-delivery-stop after they exit the system call which "
7771 "created them."
7772 msgstr ""
7773
7774 #. type: Plain text
7775 #: build/C/man2/ptrace.2:1491
7776 msgid "Detaching of the tracee is performed by:"
7777 msgstr ""
7778
7779 #. type: Plain text
7780 #: build/C/man2/ptrace.2:1493
7781 #, no-wrap
7782 msgid "    ptrace(PTRACE_DETACH, pid, 0, sig);\n"
7783 msgstr ""
7784
7785 #. type: Plain text
7786 #: build/C/man2/ptrace.2:1501
7787 msgid ""
7788 "B<PTRACE_DETACH> is a restarting operation; therefore it requires the tracee "
7789 "to be in ptrace-stop.  If the tracee is in signal-delivery-stop, a signal "
7790 "can be injected.  Otherwise, the I<sig> parameter may be silently ignored."
7791 msgstr ""
7792
7793 #.  FIXME: Describe how to detach from a group-stopped tracee so that it
7794 #.         doesn't run, but continues to wait for SIGCONT.
7795 #. type: Plain text
7796 #: build/C/man2/ptrace.2:1525
7797 msgid ""
7798 "If the tracee is running when the tracer wants to detach it, the usual "
7799 "solution is to send B<SIGSTOP> (using B<tgkill>(2), to make sure it goes to "
7800 "the correct thread), wait for the tracee to stop in signal-delivery-stop for "
7801 "B<SIGSTOP> and then detach it (suppressing B<SIGSTOP> injection).  A design "
7802 "bug is that this can race with concurrent B<SIGSTOP>s.  Another complication "
7803 "is that the tracee may enter other ptrace-stops and needs to be restarted "
7804 "and waited for again, until B<SIGSTOP> is seen.  Yet another complication is "
7805 "to be sure that the tracee is not already ptrace-stopped, because no signal "
7806 "delivery happens while it is\\(emnot even B<SIGSTOP>."
7807 msgstr ""
7808
7809 #. type: Plain text
7810 #: build/C/man2/ptrace.2:1533
7811 msgid ""
7812 "If the tracer dies, all tracees are automatically detached and restarted, "
7813 "unless they were in group-stop.  Handling of restart from group-stop is "
7814 "currently buggy, but the \"as planned\" behavior is to leave tracee stopped "
7815 "and waiting for B<SIGCONT>.  If the tracee is restarted from "
7816 "signal-delivery-stop, the pending signal is injected."
7817 msgstr ""
7818
7819 #. type: SS
7820 #: build/C/man2/ptrace.2:1533
7821 #, no-wrap
7822 msgid "execve(2) under ptrace"
7823 msgstr ""
7824
7825 #.  clone(2) CLONE_THREAD says:
7826 #.      If  any  of the threads in a thread group performs an execve(2),
7827 #.      then all threads other than the thread group leader are terminated,
7828 #.      and the new program is executed in the thread group leader.
7829 #
7830 #.  In kernel 3.1 sources, see fs/exec.c::de_thread()
7831 #. type: Plain text
7832 #: build/C/man2/ptrace.2:1552
7833 msgid ""
7834 "When one thread in a multithreaded process calls B<execve>(2), the kernel "
7835 "destroys all other threads in the process, and resets the thread ID of the "
7836 "execing thread to the thread group ID (process ID).  (Or, to put things "
7837 "another way, when a multithreaded process does an B<execve>(2), at "
7838 "completion of the call, it appears as though the B<execve>(2)  occurred in "
7839 "the thread group leader, regardless of which thread did the B<execve>(2).)  "
7840 "This resetting of the thread ID looks very confusing to tracers:"
7841 msgstr ""
7842
7843 #. type: Plain text
7844 #: build/C/man2/ptrace.2:1562
7845 msgid ""
7846 "All other threads stop in B<PTRACE_EVENT_EXIT> stop, if the "
7847 "B<PTRACE_O_TRACEEXIT> option was turned on.  Then all other threads except "
7848 "the thread group leader report death as if they exited via B<_exit>(2)  with "
7849 "exit code 0."
7850 msgstr ""
7851
7852 #. type: Plain text
7853 #: build/C/man2/ptrace.2:1570
7854 msgid ""
7855 "The execing tracee changes its thread ID while it is in the B<execve>(2).  "
7856 "(Remember, under ptrace, the \"pid\" returned from B<waitpid>(2), or fed "
7857 "into ptrace calls, is the tracee's thread ID.)  That is, the tracee's thread "
7858 "ID is reset to be the same as its process ID, which is the same as the "
7859 "thread group leader's thread ID."
7860 msgstr ""
7861
7862 #. type: Plain text
7863 #: build/C/man2/ptrace.2:1576
7864 msgid ""
7865 "Then a B<PTRACE_EVENT_EXEC> stop happens, if the B<PTRACE_O_TRACEEXEC> "
7866 "option was turned on."
7867 msgstr ""
7868
7869 #. type: Plain text
7870 #: build/C/man2/ptrace.2:1597
7871 msgid ""
7872 "If the thread group leader has reported its B<PTRACE_EVENT_EXIT> stop by "
7873 "this time, it appears to the tracer that the dead thread leader \"reappears "
7874 "from nowhere\".  (Note: the thread group leader does not report death via "
7875 "I<WIFEXITED(status)> until there is at least one other live thread.  This "
7876 "eliminates the possibility that the tracer will see it dying and then "
7877 "reappearing.)  If the thread group leader was still alive, for the tracer "
7878 "this may look as if thread group leader returns from a different system call "
7879 "than it entered, or even \"returned from a system call even though it was "
7880 "not in any system call\".  If the thread group leader was not traced (or was "
7881 "traced by a different tracer), then during B<execve>(2)  it will appear as "
7882 "if it has become a tracee of the tracer of the execing tracee."
7883 msgstr ""
7884
7885 #. type: Plain text
7886 #: build/C/man2/ptrace.2:1600
7887 msgid ""
7888 "All of the above effects are the artifacts of the thread ID change in the "
7889 "tracee."
7890 msgstr ""
7891
7892 #. type: Plain text
7893 #: build/C/man2/ptrace.2:1620
7894 msgid ""
7895 "The B<PTRACE_O_TRACEEXEC> option is the recommended tool for dealing with "
7896 "this situation.  First, it enables B<PTRACE_EVENT_EXEC> stop, which occurs "
7897 "before B<execve>(2)  returns.  In this stop, the tracer can use "
7898 "B<PTRACE_GETEVENTMSG> to retrieve the tracee's former thread ID.  (This "
7899 "feature was introduced in Linux 3.0).  Second, the B<PTRACE_O_TRACEEXEC> "
7900 "option disables legacy B<SIGTRAP> generation on B<execve>(2)."
7901 msgstr ""
7902
7903 #. type: Plain text
7904 #: build/C/man2/ptrace.2:1626
7905 msgid ""
7906 "When the tracer receives B<PTRACE_EVENT_EXEC> stop notification, it is "
7907 "guaranteed that except this tracee and the thread group leader, no other "
7908 "threads from the process are alive."
7909 msgstr ""
7910
7911 #. type: Plain text
7912 #: build/C/man2/ptrace.2:1634
7913 msgid ""
7914 "On receiving the B<PTRACE_EVENT_EXEC> stop notification, the tracer should "
7915 "clean up all its internal data structures describing the threads of this "
7916 "process, and retain only one data structure\\(emone which describes the "
7917 "single still running tracee, with"
7918 msgstr ""
7919
7920 #. type: Plain text
7921 #: build/C/man2/ptrace.2:1636
7922 #, no-wrap
7923 msgid "    thread ID == thread group ID == process ID.\n"
7924 msgstr ""
7925
7926 #. type: Plain text
7927 #: build/C/man2/ptrace.2:1640
7928 msgid "Example: two threads call B<execve>(2)  at the same time:"
7929 msgstr ""
7930
7931 #. type: Plain text
7932 #: build/C/man2/ptrace.2:1651
7933 #, no-wrap
7934 msgid ""
7935 "*** we get syscall-enter-stop in thread 1: **\n"
7936 "PID1 execve(\"/bin/foo\", \"foo\" E<lt>unfinished ...E<gt>\n"
7937 "*** we issue PTRACE_SYSCALL for thread 1 **\n"
7938 "*** we get syscall-enter-stop in thread 2: **\n"
7939 "PID2 execve(\"/bin/bar\", \"bar\" E<lt>unfinished ...E<gt>\n"
7940 "*** we issue PTRACE_SYSCALL for thread 2 **\n"
7941 "*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **\n"
7942 "*** we get syscall-exit-stop for PID0: **\n"
7943 "PID0 E<lt>... execve resumedE<gt> )             = 0\n"
7944 msgstr ""
7945
7946 #. type: Plain text
7947 #: build/C/man2/ptrace.2:1674
7948 msgid ""
7949 "If the B<PTRACE_O_TRACEEXEC> option is I<not> in effect for the execing "
7950 "tracee, the kernel delivers an extra B<SIGTRAP> to the tracee after "
7951 "B<execve>(2)  returns.  This is an ordinary signal (similar to one which can "
7952 "be generated by I<kill -TRAP>), not a special kind of ptrace-stop.  "
7953 "Employing B<PTRACE_GETSIGINFO> for this signal returns I<si_code> set to 0 "
7954 "(I<SI_USER>).  This signal may be blocked by signal mask, and thus may be "
7955 "delivered (much) later."
7956 msgstr ""
7957
7958 #. type: Plain text
7959 #: build/C/man2/ptrace.2:1693
7960 msgid ""
7961 "Usually, the tracer (for example, B<strace>(1))  would not want to show this "
7962 "extra post-execve B<SIGTRAP> signal to the user, and would suppress its "
7963 "delivery to the tracee (if B<SIGTRAP> is set to B<SIG_DFL>, it is a killing "
7964 "signal).  However, determining I<which> B<SIGTRAP> to suppress is not easy.  "
7965 "Setting the B<PTRACE_O_TRACEEXEC> option and thus suppressing this extra "
7966 "B<SIGTRAP> is the recommended approach."
7967 msgstr ""
7968
7969 #. type: SS
7970 #: build/C/man2/ptrace.2:1693
7971 #, no-wrap
7972 msgid "Real parent"
7973 msgstr ""
7974
7975 #. type: Plain text
7976 #: build/C/man2/ptrace.2:1700
7977 msgid ""
7978 "The ptrace API (ab)uses the standard UNIX parent/child signaling over "
7979 "B<waitpid>(2).  This used to cause the real parent of the process to stop "
7980 "receiving several kinds of B<waitpid>(2)  notifications when the child "
7981 "process is traced by some other process."
7982 msgstr ""
7983
7984 #. type: Plain text
7985 #: build/C/man2/ptrace.2:1703
7986 msgid ""
7987 "Many of these bugs have been fixed, but as of Linux 2.6.38 several still "
7988 "exist; see BUGS below."
7989 msgstr ""
7990
7991 #. type: Plain text
7992 #: build/C/man2/ptrace.2:1705
7993 msgid "As of Linux 2.6.38, the following is believed to work correctly:"
7994 msgstr ""
7995
7996 #. type: Plain text
7997 #: build/C/man2/ptrace.2:1713
7998 msgid ""
7999 "exit/death by signal is reported first to the tracer, then, when the tracer "
8000 "consumes the B<waitpid>(2)  result, to the real parent (to the real parent "
8001 "only when the whole multithreaded process exits).  If the tracer and the "
8002 "real parent are the same process, the report is sent only once."
8003 msgstr ""
8004
8005 #. type: Plain text
8006 #: build/C/man2/ptrace.2:1727
8007 msgid ""
8008 "On success, B<PTRACE_PEEK*> requests return the requested data, while other "
8009 "requests return zero.  On error, all requests return -1, and I<errno> is set "
8010 "appropriately.  Since the value returned by a successful B<PTRACE_PEEK*> "
8011 "request may be -1, the caller must clear I<errno> before the call, and then "
8012 "check it afterward to determine whether or not an error occurred."
8013 msgstr ""
8014
8015 #. type: Plain text
8016 #: build/C/man2/ptrace.2:1731
8017 msgid "(i386 only) There was an error with allocating or freeing a debug register."
8018 msgstr ""
8019
8020 #. type: Plain text
8021 #: build/C/man2/ptrace.2:1742
8022 msgid ""
8023 "There was an attempt to read from or write to an invalid area in the "
8024 "tracer's or the tracee's memory, probably because the area wasn't mapped or "
8025 "accessible.  Unfortunately, under Linux, different variations of this fault "
8026 "will return B<EIO> or B<EFAULT> more or less arbitrarily."
8027 msgstr ""
8028
8029 #. type: Plain text
8030 #: build/C/man2/ptrace.2:1745
8031 msgid "An attempt was made to set an invalid option."
8032 msgstr ""
8033
8034 #. type: Plain text
8035 #: build/C/man2/ptrace.2:1752
8036 msgid ""
8037 "I<request> is invalid, or an attempt was made to read from or write to an "
8038 "invalid area in the tracer's or the tracee's memory, or there was a "
8039 "word-alignment violation, or an invalid signal was specified during a "
8040 "restart request."
8041 msgstr ""
8042
8043 #. type: Plain text
8044 #: build/C/man2/ptrace.2:1765
8045 msgid ""
8046 "The specified process cannot be traced.  This could be because the tracer "
8047 "has insufficient privileges (the required capability is B<CAP_SYS_PTRACE>); "
8048 "unprivileged processes cannot trace processes that they cannot send signals "
8049 "to or those running set-user-ID/set-group-ID programs, for obvious reasons.  "
8050 "Alternatively, the process may already be being traced, or (on kernels "
8051 "before 2.6.26) be B<init>(8)  (PID 1)."
8052 msgstr ""
8053
8054 #. type: Plain text
8055 #: build/C/man2/ptrace.2:1770
8056 msgid ""
8057 "The specified process does not exist, or is not currently being traced by "
8058 "the caller, or is not stopped (for requests that require a stopped tracee)."
8059 msgstr ""
8060
8061 #. type: Plain text
8062 #: build/C/man2/ptrace.2:1772
8063 msgid "SVr4, 4.3BSD."
8064 msgstr ""
8065
8066 #. type: Plain text
8067 #: build/C/man2/ptrace.2:1787
8068 msgid ""
8069 "Although arguments to B<ptrace>()  are interpreted according to the "
8070 "prototype given, glibc currently declares B<ptrace>()  as a variadic "
8071 "function with only the I<request> argument fixed.  It is recommended to "
8072 "always supply four arguments, even if the requested operation does not use "
8073 "them, setting unused/ignored arguments to I<0L> or I<(void\\ *)\\ 0>."
8074 msgstr ""
8075
8076 #.  See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
8077 #. type: Plain text
8078 #: build/C/man2/ptrace.2:1792
8079 msgid ""
8080 "In Linux kernels before 2.6.26, B<init>(8), the process with PID 1, may not "
8081 "be traced."
8082 msgstr ""
8083
8084 #.  See http://lkml.org/lkml/2008/5/8/375
8085 #. type: Plain text
8086 #: build/C/man2/ptrace.2:1799
8087 msgid ""
8088 "The layout of the contents of memory and the USER area are quite "
8089 "operating-system- and architecture-specific.  The offset supplied, and the "
8090 "data returned, might not entirely match with the definition of I<struct "
8091 "user>."
8092 msgstr ""
8093
8094 #. type: Plain text
8095 #: build/C/man2/ptrace.2:1802
8096 msgid ""
8097 "The size of a \"word\" is determined by the operating-system variant (e.g., "
8098 "for 32-bit Linux it is 32 bits)."
8099 msgstr ""
8100
8101 #. type: Plain text
8102 #: build/C/man2/ptrace.2:1810
8103 msgid ""
8104 "This page documents the way the B<ptrace>()  call works currently in Linux.  "
8105 "Its behavior differs noticeably on other flavors of UNIX.  In any case, use "
8106 "of B<ptrace>()  is highly specific to the operating system and architecture."
8107 msgstr ""
8108
8109 #. type: Plain text
8110 #: build/C/man2/ptrace.2:1821
8111 msgid ""
8112 "On hosts with 2.6 kernel headers, B<PTRACE_SETOPTIONS> is declared with a "
8113 "different value than the one for 2.4.  This leads to applications compiled "
8114 "with 2.6 kernel headers failing when run on 2.4 kernels.  This can be worked "
8115 "around by redefining B<PTRACE_SETOPTIONS> to B<PTRACE_OLDSETOPTIONS>, if "
8116 "that is defined."
8117 msgstr ""
8118
8119 #. type: Plain text
8120 #: build/C/man2/ptrace.2:1824
8121 msgid ""
8122 "Group-stop notifications are sent to the tracer, but not to real parent.  "
8123 "Last confirmed on 2.6.38.6."
8124 msgstr ""
8125
8126 #.  Note from Denys Vlasenko:
8127 #.      Here "exits" means any kind of death - _exit, exit_group,
8128 #.      signal death. Signal death and exit_group cases are trivial,
8129 #.      though: since signal death and exit_group kill all other threads
8130 #.      too, "until all other threads exit" thing happens rather soon
8131 #.      in these cases. Therefore, only _exit presents observably
8132 #.      puzzling behavior to ptrace users: thread leader _exit's,
8133 #.      but WIFEXITED isn't reported! We are trying to explain here
8134 #.      why it is so.
8135 #.   FIXME: ^^^ need to test/verify this scenario
8136 #. type: Plain text
8137 #: build/C/man2/ptrace.2:1855
8138 msgid ""
8139 "If a thread group leader is traced and exits by calling B<_exit>(2), a "
8140 "B<PTRACE_EVENT_EXIT> stop will happen for it (if requested), but the "
8141 "subsequent B<WIFEXITED> notification will not be delivered until all other "
8142 "threads exit.  As explained above, if one of other threads calls "
8143 "B<execve>(2), the death of the thread group leader will I<never> be "
8144 "reported.  If the execed thread is not traced by this tracer, the tracer "
8145 "will never know that B<execve>(2)  happened.  One possible workaround is to "
8146 "B<PTRACE_DETACH> the thread group leader instead of restarting it in this "
8147 "case.  Last confirmed on 2.6.38.6."
8148 msgstr ""
8149
8150 #. type: Plain text
8151 #: build/C/man2/ptrace.2:1865
8152 msgid ""
8153 "A B<SIGKILL> signal may still cause a B<PTRACE_EVENT_EXIT> stop before "
8154 "actual signal death.  This may be changed in the future; B<SIGKILL> is meant "
8155 "to always immediately kill tasks even under ptrace.  Last confirmed on "
8156 "2.6.38.6."
8157 msgstr ""
8158
8159 #. type: Plain text
8160 #: build/C/man2/ptrace.2:1883
8161 msgid ""
8162 "Some system calls return with B<EINTR> if a signal was sent to a tracee, but "
8163 "delivery was suppressed by the tracer.  (This is very typical operation: it "
8164 "is usually done by debuggers on every attach, in order to not introduce a "
8165 "bogus B<SIGSTOP>).  As of Linux 3.2.9, the following system calls are "
8166 "affected (this list is likely incomplete): B<epoll_wait>(2), and B<read>(2)  "
8167 "from an B<inotify>(7)  file descriptor.  The usual symptom of this bug is "
8168 "that when you attach to a quiescent process with the command"
8169 msgstr ""
8170
8171 #. type: Plain text
8172 #: build/C/man2/ptrace.2:1885
8173 #, no-wrap
8174 msgid "    strace -p E<lt>process-IDE<gt>\n"
8175 msgstr ""
8176
8177 #. type: Plain text
8178 #: build/C/man2/ptrace.2:1888
8179 msgid "then, instead of the usual and expected one-line output such as"
8180 msgstr ""
8181
8182 #. type: Plain text
8183 #: build/C/man2/ptrace.2:1891
8184 #, no-wrap
8185 msgid "    restart_syscall(E<lt>... resuming interrupted call ...E<gt>_\n"
8186 msgstr ""
8187
8188 #. type: Plain text
8189 #: build/C/man2/ptrace.2:1897
8190 #, no-wrap
8191 msgid "    select(6, [5], NULL, [5], NULL_\n"
8192 msgstr ""
8193
8194 #. type: Plain text
8195 #: build/C/man2/ptrace.2:1901
8196 msgid ""
8197 "('_' denotes the cursor position), you observe more than one line.  For "
8198 "example:"
8199 msgstr ""
8200
8201 #. type: Plain text
8202 #: build/C/man2/ptrace.2:1905
8203 #, no-wrap
8204 msgid ""
8205 "    clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0\n"
8206 "    epoll_wait(4,_\n"
8207 msgstr ""
8208
8209 #. type: Plain text
8210 #: build/C/man2/ptrace.2:1926
8211 msgid ""
8212 "What is not visible here is that the process was blocked in B<epoll_wait>(2)  "
8213 "before B<strace>(1)  has attached to it.  Attaching caused B<epoll_wait>(2)  "
8214 "to return to user space with the error B<EINTR>.  In this particular case, "
8215 "the program reacted to B<EINTR> by checking the current time, and then "
8216 "executing B<epoll_wait>(2)  again.  (Programs which do not expect such "
8217 "\"stray\" B<EINTR> errors may behave in an unintended way upon an "
8218 "B<strace>(1)  attach.)"
8219 msgstr ""
8220
8221 #. type: Plain text
8222 #: build/C/man2/ptrace.2:1940
8223 msgid ""
8224 "B<gdb>(1), B<strace>(1), B<clone>(2), B<execve>(2), B<fork>(2), "
8225 "B<gettid>(2), B<sigaction>(2), B<tgkill>(2), B<vfork>(2), B<waitpid>(2), "
8226 "B<exec>(3), B<capabilities>(7), B<signal>(7)"
8227 msgstr ""
8228
8229 #. type: TH
8230 #: build/C/man2/quotactl.2:27
8231 #, no-wrap
8232 msgid "QUOTACTL"
8233 msgstr ""
8234
8235 #. type: TH
8236 #: build/C/man2/quotactl.2:27
8237 #, no-wrap
8238 msgid "2010-06-16"
8239 msgstr ""
8240
8241 #. type: Plain text
8242 #: build/C/man2/quotactl.2:30
8243 msgid "quotactl - manipulate disk quotas"
8244 msgstr ""
8245
8246 #. type: Plain text
8247 #: build/C/man2/quotactl.2:34
8248 #, no-wrap
8249 msgid ""
8250 "B<#include E<lt>sys/quota.hE<gt>>\n"
8251 "B<#include E<lt>xfs/xqm.hE<gt>>\n"
8252 msgstr ""
8253
8254 #. type: Plain text
8255 #: build/C/man2/quotactl.2:37
8256 #, no-wrap
8257 msgid ""
8258 "B<int quotactl(int >I<cmd>B<, const char *>I<special>B<, int >I<id>B<, "
8259 "caddr_t >I<addr>B<);>\n"
8260 msgstr ""
8261
8262 #. type: Plain text
8263 #: build/C/man2/quotactl.2:49
8264 msgid ""
8265 "The quota system can be used to set per-user and per-group limits on the "
8266 "amount of disk space used on a file system.  For each user and/or group, a "
8267 "soft limit and a hard limit can be set for each file system.  The hard limit "
8268 "can't be exceeded.  The soft limit can be exceeded, but warnings will "
8269 "ensue.  Moreover, the user can't exceed the soft limit for more than one "
8270 "week (by default) at a time; after this time, the soft limit counts as a "
8271 "hard limit."
8272 msgstr ""
8273
8274 #. type: Plain text
8275 #: build/C/man2/quotactl.2:74
8276 msgid ""
8277 "The B<quotactl>()  call manipulates disk quotas.  The I<cmd> argument "
8278 "indicates a command to be applied to the user or group ID specified in "
8279 "I<id>.  To initialize the I<cmd> argument, use the I<QCMD(subcmd, type)> "
8280 "macro.  The I<type> value is either B<USRQUOTA>, for user quotas, or "
8281 "B<GRPQUOTA>, for group quotas.  The I<subcmd> value is described below."
8282 msgstr ""
8283
8284 #. type: Plain text
8285 #: build/C/man2/quotactl.2:79
8286 msgid ""
8287 "The I<special> argument is a pointer to a null-terminated string containing "
8288 "the pathname of the (mounted) block special device for the file system being "
8289 "manipulated."
8290 msgstr ""
8291
8292 #. type: Plain text
8293 #: build/C/man2/quotactl.2:87
8294 msgid ""
8295 "The I<addr> argument is the address of an optional, command-specific, data "
8296 "structure that is copied in or out of the system.  The interpretation of "
8297 "I<addr> is given with each command below."
8298 msgstr ""
8299
8300 #. type: Plain text
8301 #: build/C/man2/quotactl.2:91
8302 msgid "The I<subcmd> value is one of the following:"
8303 msgstr ""
8304
8305 #. type: TP
8306 #: build/C/man2/quotactl.2:91
8307 #, no-wrap
8308 msgid "B<Q_QUOTAON>"
8309 msgstr ""
8310
8311 #. type: Plain text
8312 #: build/C/man2/quotactl.2:98
8313 msgid ""
8314 "Turn on quotas for a file system.  The I<id> argument is the identification "
8315 "number of the quota format to be used.  Currently, there are three supported "
8316 "quota formats:"
8317 msgstr ""
8318
8319 #. type: TP
8320 #: build/C/man2/quotactl.2:99
8321 #, no-wrap
8322 msgid "B<QFMT_VFS_OLD>"
8323 msgstr ""
8324
8325 #. type: Plain text
8326 #: build/C/man2/quotactl.2:102
8327 msgid "The original quota format."
8328 msgstr ""
8329
8330 #. type: TP
8331 #: build/C/man2/quotactl.2:102
8332 #, no-wrap
8333 msgid "B<QFMT_VFS_V0>"
8334 msgstr ""
8335
8336 #. type: Plain text
8337 #: build/C/man2/quotactl.2:106
8338 msgid ""
8339 "The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and "
8340 "quota limits up to 2^42 bytes and 2^32 inodes."
8341 msgstr ""
8342
8343 #. type: TP
8344 #: build/C/man2/quotactl.2:106
8345 #, no-wrap
8346 msgid "B<QFMT_VFS_V1>"
8347 msgstr ""
8348
8349 #. type: Plain text
8350 #: build/C/man2/quotactl.2:110
8351 msgid ""
8352 "A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^64 "
8353 "bytes and 2^64 inodes."
8354 msgstr ""
8355
8356 #. type: Plain text
8357 #: build/C/man2/quotactl.2:121
8358 msgid ""
8359 "The I<addr> argument points to the pathname of a file containing the quotas "
8360 "for the file system.  The quota file must exist; it is normally created with "
8361 "the B<quotacheck>(8)  program.  This operation requires privilege "
8362 "(B<CAP_SYS_ADMIN>)."
8363 msgstr ""
8364
8365 #. type: TP
8366 #: build/C/man2/quotactl.2:121
8367 #, no-wrap
8368 msgid "B<Q_QUOTAOFF>"
8369 msgstr ""
8370
8371 #. type: Plain text
8372 #: build/C/man2/quotactl.2:131
8373 msgid ""
8374 "Turn off quotas for a file system.  The I<addr> and I<id> arguments are "
8375 "ignored.  This operation requires privilege (B<CAP_SYS_ADMIN>)."
8376 msgstr ""
8377
8378 #. type: TP
8379 #: build/C/man2/quotactl.2:131
8380 #, no-wrap
8381 msgid "B<Q_GETQUOTA>"
8382 msgstr ""
8383
8384 #. type: Plain text
8385 #: build/C/man2/quotactl.2:142
8386 msgid ""
8387 "Get disk quota limits and current usage for user or group I<id>.  The "
8388 "I<addr> argument is a pointer to a I<dqblk> structure defined in "
8389 "I<E<lt>sys/quota.hE<gt>> as follows:"
8390 msgstr ""
8391
8392 #. type: Plain text
8393 #: build/C/man2/quotactl.2:147 build/C/man2/quotactl.2:234
8394 #, no-wrap
8395 msgid ""
8396 "/* uint64_t is an unsigned 64-bit integer;\n"
8397 "   uint32_t is an unsigned 32-bit integer */\n"
8398 msgstr ""
8399
8400 #. type: Plain text
8401 #: build/C/man2/quotactl.2:167
8402 #, no-wrap
8403 msgid ""
8404 "struct dqblk {          /* Definition since Linux 2.4.22 */\n"
8405 "    uint64_t dqb_bhardlimit;   /* absolute limit on disk\n"
8406 "                                  quota blocks alloc */\n"
8407 "    uint64_t dqb_bsoftlimit;   /* preferred limit on\n"
8408 "                                  disk quota blocks */\n"
8409 "    uint64_t dqb_curspace;     /* current quota block\n"
8410 "                                  count */\n"
8411 "    uint64_t dqb_ihardlimit;   /* maximum number of\n"
8412 "                                  allocated inodes */\n"
8413 "    uint64_t dqb_isoftlimit;   /* preferred inode limit */\n"
8414 "    uint64_t dqb_curinodes;    /* current number of\n"
8415 "                                  allocated inodes */\n"
8416 "    uint64_t dqb_btime;        /* time limit for excessive\n"
8417 "                                  disk use */\n"
8418 "    uint64_t dqb_itime;        /* time limit for excessive\n"
8419 "                                  files */\n"
8420 "    uint32_t dqb_valid;        /* bit mask of QIF_*\n"
8421 "                                  constants */\n"
8422 "};\n"
8423 msgstr ""
8424
8425 #. type: Plain text
8426 #: build/C/man2/quotactl.2:170
8427 #, no-wrap
8428 msgid ""
8429 "/* Flags in dqb_valid that indicate which fields in\n"
8430 "   dqblk structure are valid. */\n"
8431 msgstr ""
8432
8433 #. type: Plain text
8434 #: build/C/man2/quotactl.2:181
8435 #, no-wrap
8436 msgid ""
8437 "#define QIF_BLIMITS   1\n"
8438 "#define QIF_SPACE     2\n"
8439 "#define QIF_ILIMITS   4\n"
8440 "#define QIF_INODES    8\n"
8441 "#define QIF_BTIME     16\n"
8442 "#define QIF_ITIME     32\n"
8443 "#define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)\n"
8444 "#define QIF_USAGE     (QIF_SPACE | QIF_INODES)\n"
8445 "#define QIF_TIMES     (QIF_BTIME | QIF_ITIME)\n"
8446 "#define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)\n"
8447 msgstr ""
8448
8449 #. type: Plain text
8450 #: build/C/man2/quotactl.2:198
8451 msgid ""
8452 "The I<dqb_valid> field is a bit mask that is set to indicate the entries in "
8453 "the I<dqblk> structure that are valid.  Currently, the kernel fills in all "
8454 "entries of the I<dqblk> structure and marks them as valid in the "
8455 "I<dqb_valid> field.  Unprivileged users may retrieve only their own quotas; "
8456 "a privileged user (B<CAP_SYS_ADMIN>)  can retrieve the quotas of any user."
8457 msgstr ""
8458
8459 #. type: TP
8460 #: build/C/man2/quotactl.2:198
8461 #, no-wrap
8462 msgid "B<Q_SETQUOTA>"
8463 msgstr ""
8464
8465 #. type: Plain text
8466 #: build/C/man2/quotactl.2:218
8467 msgid ""
8468 "Set quota information for user or group I<id>, using the information "
8469 "supplied in the I<dqblk> structure pointed to by I<addr>.  The I<dqb_valid> "
8470 "field of the I<dqblk> structure indicates which entries in the structure "
8471 "have been set by the caller.  This operation supersedes the B<Q_SETQLIM> and "
8472 "B<Q_SETUSE> operations in the previous quota interfaces.  This operation "
8473 "requires privilege (B<CAP_SYS_ADMIN>)."
8474 msgstr ""
8475
8476 #. type: TP
8477 #: build/C/man2/quotactl.2:218
8478 #, no-wrap
8479 msgid "B<Q_GETINFO>"
8480 msgstr ""
8481
8482 #. type: Plain text
8483 #: build/C/man2/quotactl.2:229
8484 msgid ""
8485 "Get information (like grace times) about quotafile.  The I<addr> argument "
8486 "should be a pointer to a I<dqinfo> structure.  This structure is defined in "
8487 "I<E<lt>sys/quota.hE<gt>> as follows:"
8488 msgstr ""
8489
8490 #. type: Plain text
8491 #: build/C/man2/quotactl.2:238
8492 #, no-wrap
8493 msgid ""
8494 "struct dqinfo {         /* Defined since kernel 2.4.22 */\n"
8495 "    uint64_t dqi_bgrace;    /* Time before block soft limit\n"
8496 "                               becomes hard limit */\n"
8497 msgstr ""
8498
8499 #. type: Plain text
8500 #: build/C/man2/quotactl.2:245
8501 #, no-wrap
8502 msgid ""
8503 "    uint64_t dqi_igrace;    /* Time before inode soft limit\n"
8504 "                               becomes hard limit */\n"
8505 "    uint32_t dqi_flags;     /* Flags for quotafile\n"
8506 "                               (DQF_*) */\n"
8507 "    uint32_t dqi_valid;\n"
8508 "};\n"
8509 msgstr ""
8510
8511 #. type: Plain text
8512 #: build/C/man2/quotactl.2:247
8513 #, no-wrap
8514 msgid "/* Bits for dqi_flags */\n"
8515 msgstr ""
8516
8517 #. type: Plain text
8518 #: build/C/man2/quotactl.2:249
8519 #, no-wrap
8520 msgid "/* Quota format QFMT_VFS_OLD */\n"
8521 msgstr ""
8522
8523 #. type: Plain text
8524 #: build/C/man2/quotactl.2:251
8525 #, no-wrap
8526 msgid "#define V1_DQF_RSQUASH\t1   /* Root squash enabled */\n"
8527 msgstr ""
8528
8529 #. type: Plain text
8530 #: build/C/man2/quotactl.2:253
8531 #, no-wrap
8532 msgid "/* Other quota formats have no dqi_flags bits defined */\n"
8533 msgstr ""
8534
8535 #. type: Plain text
8536 #: build/C/man2/quotactl.2:256
8537 #, no-wrap
8538 msgid ""
8539 "/* Flags in dqi_valid that indicate which fields in\n"
8540 "   dqinfo structure are valid. */\n"
8541 msgstr ""
8542
8543 #. type: Plain text
8544 #: build/C/man2/quotactl.2:261
8545 #, no-wrap
8546 msgid ""
8547 "# define IIF_BGRACE\t1\n"
8548 "# define IIF_IGRACE\t2\n"
8549 "# define IIF_FLAGS\t4\n"
8550 "# define IIF_ALL\t(IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)\n"
8551 msgstr ""
8552
8553 #. type: Plain text
8554 #: build/C/man2/quotactl.2:277
8555 msgid ""
8556 "The I<dqi_valid> field in the I<dqinfo> structure indicates the entries in "
8557 "the structure that are valid.  Currently, the kernel fills in all entries of "
8558 "the I<dqinfo> structure and marks them all as valid in the I<dqi_valid> "
8559 "field.  The I<id> argument is ignored."
8560 msgstr ""
8561
8562 #. type: TP
8563 #: build/C/man2/quotactl.2:277
8564 #, no-wrap
8565 msgid "B<Q_SETINFO>"
8566 msgstr ""
8567
8568 #. type: Plain text
8569 #: build/C/man2/quotactl.2:301
8570 msgid ""
8571 "Set information about quotafile.  The I<addr> argument should be a pointer "
8572 "to a I<dqinfo> structure.  The I<dqi_valid> field of the I<dqinfo> structure "
8573 "indicates the entries in the structure that have been set by the caller.  "
8574 "This operation supersedes the B<Q_SETGRACE> and B<Q_SETFLAGS> operations in "
8575 "the previous quota interfaces.  The I<id> argument is ignored.  This "
8576 "operation requires privilege (B<CAP_SYS_ADMIN>)."
8577 msgstr ""
8578
8579 #. type: TP
8580 #: build/C/man2/quotactl.2:301
8581 #, no-wrap
8582 msgid "B<Q_GETFMT>"
8583 msgstr ""
8584
8585 #. type: Plain text
8586 #: build/C/man2/quotactl.2:308
8587 msgid ""
8588 "Get quota format used on the specified file system.  The I<addr> argument "
8589 "should be a pointer to a 4-byte buffer where the format number will be "
8590 "stored."
8591 msgstr ""
8592
8593 #. type: TP
8594 #: build/C/man2/quotactl.2:308
8595 #, no-wrap
8596 msgid "B<Q_SYNC>"
8597 msgstr ""
8598
8599 #. type: Plain text
8600 #: build/C/man2/quotactl.2:319
8601 msgid ""
8602 "Update the on-disk copy of quota usages for a file system.  If I<special> is "
8603 "NULL, then all file systems with active quotas are sync'ed.  The I<addr> and "
8604 "I<id> arguments are ignored."
8605 msgstr ""
8606
8607 #. type: TP
8608 #: build/C/man2/quotactl.2:319
8609 #, no-wrap
8610 msgid "B<Q_GETSTATS>"
8611 msgstr ""
8612
8613 #.  Q_GETSTATS was removed in kernel 2.4.22.
8614 #. type: Plain text
8615 #: build/C/man2/quotactl.2:339
8616 msgid ""
8617 "Get statistics and other generic information about the quota subsystem.  The "
8618 "I<addr> argument should be a pointer to a I<dqstats> structure in which data "
8619 "should be stored.  This structure is defined in I<E<lt>sys/quota.hE<gt>.> "
8620 "The I<special> and I<id> arguments are ignored.  This operation is obsolete "
8621 "and not supported by recent kernels.  Files in I</proc/sys/fs/quota/> carry "
8622 "the information instead."
8623 msgstr ""
8624
8625 #. type: Plain text
8626 #: build/C/man2/quotactl.2:342
8627 msgid ""
8628 "For XFS file systems making use of the XFS Quota Manager (XQM), the above "
8629 "commands are bypassed and the following commands are used:"
8630 msgstr ""
8631
8632 #. type: TP
8633 #: build/C/man2/quotactl.2:342
8634 #, no-wrap
8635 msgid "B<Q_XQUOTAON>"
8636 msgstr ""
8637
8638 #. type: Plain text
8639 #: build/C/man2/quotactl.2:363
8640 msgid ""
8641 "Turn on quotas for an XFS file system.  XFS provides the ability to turn "
8642 "on/off quota limit enforcement with quota accounting.  Therefore, XFS "
8643 "expects I<addr> to be a pointer to an I<unsigned int> that contains either "
8644 "the flags B<XFS_QUOTA_UDQ_ACCT> and/or B<XFS_QUOTA_UDQ_ENFD> (for user "
8645 "quota), or B<XFS_QUOTA_GDQ_ACCT> and/or B<XFS_QUOTA_GDQ_ENFD> (for group "
8646 "quota), as defined in I<E<lt>xfs/xqm.hE<gt>>.  This operation requires "
8647 "privilege (B<CAP_SYS_ADMIN>)."
8648 msgstr ""
8649
8650 #. type: TP
8651 #: build/C/man2/quotactl.2:363
8652 #, no-wrap
8653 msgid "B<Q_XQUOTAOFF>"
8654 msgstr ""
8655
8656 #. type: Plain text
8657 #: build/C/man2/quotactl.2:374
8658 msgid ""
8659 "Turn off quotas for an XFS file system.  As with B<Q_QUOTAON>, XFS file "
8660 "systems expect a pointer to an I<unsigned int> that specifies whether quota "
8661 "accounting and/or limit enforcement need to be turned off.  This operation "
8662 "requires privilege (B<CAP_SYS_ADMIN>)."
8663 msgstr ""
8664
8665 #. type: TP
8666 #: build/C/man2/quotactl.2:374
8667 #, no-wrap
8668 msgid "B<Q_XGETQUOTA>"
8669 msgstr ""
8670
8671 #. type: Plain text
8672 #: build/C/man2/quotactl.2:388
8673 msgid ""
8674 "Get disk quota limits and current usage for user I<id>.  The I<addr> "
8675 "argument is a pointer to an I<fs_disk_quota> structure (defined in "
8676 "I<E<lt>xfs/xqm.hE<gt>>).  Unprivileged users may retrieve only their own "
8677 "quotas; a privileged user (B<CAP_SYS_ADMIN>)  may retrieve the quotas of any "
8678 "user."
8679 msgstr ""
8680
8681 #. type: TP
8682 #: build/C/man2/quotactl.2:388
8683 #, no-wrap
8684 msgid "B<Q_XSETQLIM>"
8685 msgstr ""
8686
8687 #. type: Plain text
8688 #: build/C/man2/quotactl.2:400
8689 msgid ""
8690 "Set disk quota limits for user I<id>.  The I<addr> argument is a pointer to "
8691 "an I<fs_disk_quota> structure (defined in I<E<lt>xfs/xqm.hE<gt>>).  This "
8692 "operation requires privilege (B<CAP_SYS_ADMIN>)."
8693 msgstr ""
8694
8695 #. type: TP
8696 #: build/C/man2/quotactl.2:400
8697 #, no-wrap
8698 msgid "B<Q_XGETQSTAT>"
8699 msgstr ""
8700
8701 #. type: Plain text
8702 #: build/C/man2/quotactl.2:408
8703 msgid ""
8704 "Returns an I<fs_quota_stat> structure containing XFS file system specific "
8705 "quota information.  This is useful for finding out how much space is used to "
8706 "store quota information, and also to get quotaon/off status of a given local "
8707 "XFS file system."
8708 msgstr ""
8709
8710 #. type: TP
8711 #: build/C/man2/quotactl.2:408
8712 #, no-wrap
8713 msgid "B<Q_XQUOTARM>"
8714 msgstr ""
8715
8716 #. type: Plain text
8717 #: build/C/man2/quotactl.2:412
8718 msgid ""
8719 "Free the disk space taken by disk quotas.  Quotas must have already been "
8720 "turned off."
8721 msgstr ""
8722
8723 #. type: Plain text
8724 #: build/C/man2/quotactl.2:419
8725 msgid ""
8726 "There is no command equivalent to B<Q_SYNC> for XFS since B<sync>(1)  writes "
8727 "quota information to disk (in addition to the other file system metadata "
8728 "that it writes out)."
8729 msgstr ""
8730
8731 #. type: SH
8732 #: build/C/man2/quotactl.2:419
8733 #, no-wrap
8734 msgid "RETURN VALUES"
8735 msgstr ""
8736
8737 #. type: Plain text
8738 #: build/C/man2/quotactl.2:427
8739 msgid ""
8740 "On success, B<quotactl>()  returns 0; on error -1 is returned, and I<errno> "
8741 "is set to indicate the error."
8742 msgstr ""
8743
8744 #. type: Plain text
8745 #: build/C/man2/quotactl.2:434
8746 msgid "I<addr> or I<special> is invalid."
8747 msgstr ""
8748
8749 #. type: Plain text
8750 #: build/C/man2/quotactl.2:440
8751 msgid "I<cmd> or I<type> is invalid."
8752 msgstr ""
8753
8754 #. type: TP
8755 #: build/C/man2/quotactl.2:440
8756 #, no-wrap
8757 msgid "B<ENOENT>"
8758 msgstr ""
8759
8760 #. type: Plain text
8761 #: build/C/man2/quotactl.2:447
8762 msgid "The file specified by I<special> or I<addr> does not exist."
8763 msgstr ""
8764
8765 #. type: Plain text
8766 #: build/C/man2/quotactl.2:452
8767 msgid "The kernel has not been compiled with the B<CONFIG_QUOTA> option."
8768 msgstr ""
8769
8770 #. type: TP
8771 #: build/C/man2/quotactl.2:452
8772 #, no-wrap
8773 msgid "B<ENOTBLK>"
8774 msgstr ""
8775
8776 #. type: Plain text
8777 #: build/C/man2/quotactl.2:456
8778 msgid "I<special> is not a block device."
8779 msgstr ""
8780
8781 #. type: Plain text
8782 #: build/C/man2/quotactl.2:461
8783 msgid ""
8784 "The caller lacked the required privilege (B<CAP_SYS_ADMIN>)  for the "
8785 "specified operation."
8786 msgstr ""
8787
8788 #. type: Plain text
8789 #: build/C/man2/quotactl.2:465
8790 msgid ""
8791 "No disk quota is found for the indicated user.  Quotas have not been turned "
8792 "on for this file system."
8793 msgstr ""
8794
8795 #. type: Plain text
8796 #: build/C/man2/quotactl.2:474
8797 msgid "If I<cmd> is B<Q_SETQUOTA>, B<quotactl>()  may also set I<errno> to:"
8798 msgstr ""
8799
8800 #. type: Plain text
8801 #: build/C/man2/quotactl.2:477
8802 msgid "Specified limits are out of range allowed by quota format."
8803 msgstr ""
8804
8805 #. type: Plain text
8806 #: build/C/man2/quotactl.2:486
8807 msgid "If I<cmd> is B<Q_QUOTAON>, B<quotactl>()  may also set I<errno> to:"
8808 msgstr ""
8809
8810 #. type: Plain text
8811 #: build/C/man2/quotactl.2:495
8812 msgid ""
8813 "The quota file pointed to by I<addr> exists, but is not a regular file; or, "
8814 "the quota file pointed to by I<addr> exists, but is not on the file system "
8815 "pointed to by I<special>."
8816 msgstr ""
8817
8818 #. type: Plain text
8819 #: build/C/man2/quotactl.2:501
8820 msgid "B<Q_QUOTAON> attempted, but another B<Q_QUOTAON> had already been performed."
8821 msgstr ""
8822
8823 #. type: Plain text
8824 #: build/C/man2/quotactl.2:504
8825 msgid "The quota file is corrupted."
8826 msgstr ""
8827
8828 #. type: Plain text
8829 #: build/C/man2/quotactl.2:507
8830 msgid "Specified quota format was not found."
8831 msgstr ""
8832
8833 #. type: Plain text
8834 #: build/C/man2/quotactl.2:512
8835 msgid "B<quota>(1), B<getrlimit>(2), B<quotacheck>(8), B<quotaon>(8)"
8836 msgstr ""
8837
8838 #. type: TH
8839 #: build/C/man2/sendfile.2:19
8840 #, no-wrap
8841 msgid "SENDFILE"
8842 msgstr ""
8843
8844 #. type: TH
8845 #: build/C/man2/sendfile.2:19
8846 #, no-wrap
8847 msgid "2011-09-14"
8848 msgstr ""
8849
8850 #. type: Plain text
8851 #: build/C/man2/sendfile.2:22
8852 msgid "sendfile - transfer data between file descriptors"
8853 msgstr ""
8854
8855 #. type: Plain text
8856 #: build/C/man2/sendfile.2:24
8857 msgid "B<#include E<lt>sys/sendfile.hE<gt>>"
8858 msgstr ""
8859
8860 #.  The below is too ugly. Comments about glibc versions belong
8861 #.  in the notes, not in the header.
8862 #
8863 #.  .B #include <features.h>
8864 #.  .br
8865 #.  .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
8866 #.  .br
8867 #.  .B #include <sys/sendfile.h>
8868 #.  .br
8869 #.  #else
8870 #.  .br
8871 #.  .B #include <sys/types.h>
8872 #.  .br
8873 #.  .B /* No system prototype before glibc 2.1. */
8874 #.  .br
8875 #.  .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
8876 #.                        offset ", size_t" " count" )
8877 #.  .br
8878 #.  .B #endif
8879 #. type: Plain text
8880 #: build/C/man2/sendfile.2:47
8881 msgid ""
8882 "B<ssize_t sendfile(int>I< out_fd>B<, int>I< in_fd>B<, off_t *>I<offset>B<, "
8883 "size_t>I< count>B<);>"
8884 msgstr ""
8885
8886 #. type: Plain text
8887 #: build/C/man2/sendfile.2:57
8888 msgid ""
8889 "B<sendfile>()  copies data between one file descriptor and another.  Because "
8890 "this copying is done within the kernel, B<sendfile>()  is more efficient "
8891 "than the combination of B<read>(2)  and B<write>(2), which would require "
8892 "transferring data to and from user space."
8893 msgstr ""
8894
8895 #. type: Plain text
8896 #: build/C/man2/sendfile.2:62
8897 msgid ""
8898 "I<in_fd> should be a file descriptor opened for reading and I<out_fd> should "
8899 "be a descriptor opened for writing."
8900 msgstr ""
8901
8902 #. type: Plain text
8903 #: build/C/man2/sendfile.2:83
8904 msgid ""
8905 "If I<offset> is not NULL, then it points to a variable holding the file "
8906 "offset from which B<sendfile>()  will start reading data from I<in_fd>.  "
8907 "When B<sendfile>()  returns, this variable will be set to the offset of the "
8908 "byte following the last byte that was read.  If I<offset> is not NULL, then "
8909 "B<sendfile>()  does not modify the current file offset of I<in_fd>; "
8910 "otherwise the current file offset is adjusted to reflect the number of bytes "
8911 "read from I<in_fd>."
8912 msgstr ""
8913
8914 #. type: Plain text
8915 #: build/C/man2/sendfile.2:90
8916 msgid ""
8917 "If I<offset> is NULL, then data will be read from I<in_fd> starting at the "
8918 "current file offset, and the file offset will be updated by the call."
8919 msgstr ""
8920
8921 #. type: Plain text
8922 #: build/C/man2/sendfile.2:93
8923 msgid "I<count> is the number of bytes to copy between the file descriptors."
8924 msgstr ""
8925
8926 #. type: Plain text
8927 #: build/C/man2/sendfile.2:100
8928 msgid ""
8929 "The I<in_fd> argument must correspond to a file which supports "
8930 "B<mmap>(2)-like operations (i.e., it cannot be a socket)."
8931 msgstr ""
8932
8933 #. type: Plain text
8934 #: build/C/man2/sendfile.2:108
8935 msgid ""
8936 "In Linux kernels before 2.6.33, I<out_fd> must refer to a socket.  Since "
8937 "Linux 2.6.33 it can be any file.  If it is a regular file, then "
8938 "B<sendfile>()  changes the file offset appropriately."
8939 msgstr ""
8940
8941 #. type: Plain text
8942 #: build/C/man2/sendfile.2:115
8943 msgid ""
8944 "If the transfer was successful, the number of bytes written to I<out_fd> is "
8945 "returned.  On error, -1 is returned, and I<errno> is set appropriately."
8946 msgstr ""
8947
8948 #. type: Plain text
8949 #: build/C/man2/sendfile.2:121
8950 msgid ""
8951 "Nonblocking I/O has been selected using B<O_NONBLOCK> and the write would "
8952 "block."
8953 msgstr ""
8954
8955 #. type: TP
8956 #: build/C/man2/sendfile.2:121 build/C/man2/splice.2:143 build/C/man2/vmsplice.2:123
8957 #, no-wrap
8958 msgid "B<EBADF>"
8959 msgstr ""
8960
8961 #. type: Plain text
8962 #: build/C/man2/sendfile.2:125
8963 msgid ""
8964 "The input file was not opened for reading or the output file was not opened "
8965 "for writing."
8966 msgstr ""
8967
8968 #. type: Plain text
8969 #: build/C/man2/sendfile.2:128
8970 msgid "Bad address."
8971 msgstr ""
8972
8973 #. type: Plain text
8974 #: build/C/man2/sendfile.2:134
8975 msgid ""
8976 "Descriptor is not valid or locked, or an B<mmap>(2)-like operation is not "
8977 "available for I<in_fd>."
8978 msgstr ""
8979
8980 #. type: Plain text
8981 #: build/C/man2/sendfile.2:138
8982 msgid "Unspecified error while reading from I<in_fd>."
8983 msgstr ""
8984
8985 #. type: Plain text
8986 #: build/C/man2/sendfile.2:142
8987 msgid "Insufficient memory to read from I<in_fd>."
8988 msgstr ""
8989
8990 #. type: Plain text
8991 #: build/C/man2/sendfile.2:148
8992 msgid ""
8993 "B<sendfile>()  is a new feature in Linux 2.2.  The include file "
8994 "I<E<lt>sys/sendfile.hE<gt>> is present since glibc 2.1."
8995 msgstr ""
8996
8997 #. type: Plain text
8998 #: build/C/man2/sendfile.2:150
8999 msgid "Not specified in POSIX.1-2001, or other standards."
9000 msgstr ""
9001
9002 #. type: Plain text
9003 #: build/C/man2/sendfile.2:155
9004 msgid ""
9005 "Other UNIX systems implement B<sendfile>()  with different semantics and "
9006 "prototypes.  It should not be used in portable programs."
9007 msgstr ""
9008
9009 #. type: Plain text
9010 #: build/C/man2/sendfile.2:165
9011 msgid ""
9012 "If you plan to use B<sendfile>()  for sending files to a TCP socket, but "
9013 "need to send some header data in front of the file contents, you will find "
9014 "it useful to employ the B<TCP_CORK> option, described in B<tcp>(7), to "
9015 "minimize the number of packets and to tune performance."
9016 msgstr ""
9017
9018 #. type: Plain text
9019 #: build/C/man2/sendfile.2:171
9020 msgid ""
9021 "In Linux 2.4 and earlier, I<out_fd> could also refer to a regular file, and "
9022 "B<sendfile>()  changed the current offset of that file."
9023 msgstr ""
9024
9025 #. type: Plain text
9026 #: build/C/man2/sendfile.2:183
9027 msgid ""
9028 "The original Linux B<sendfile>()  system call was not designed to handle "
9029 "large file offsets.  Consequently, Linux 2.4 added B<sendfile64>(), with a "
9030 "wider type for the I<offset> argument.  The glibc B<sendfile>()  wrapper "
9031 "function transparently deals with the kernel differences."
9032 msgstr ""
9033
9034 #. type: Plain text
9035 #: build/C/man2/sendfile.2:192
9036 msgid ""
9037 "Applications may wish to fall back to B<read>(2)/B<write>(2)  in the case "
9038 "where B<sendfile>()  fails with B<EINVAL> or B<ENOSYS>."
9039 msgstr ""
9040
9041 #. type: Plain text
9042 #: build/C/man2/sendfile.2:197
9043 msgid ""
9044 "The Linux-specific B<splice>(2)  call supports transferring data between "
9045 "arbitrary files (e.g., a pair of sockets)."
9046 msgstr ""
9047
9048 #. type: Plain text
9049 #: build/C/man2/sendfile.2:202
9050 msgid "B<mmap>(2), B<open>(2), B<socket>(2), B<splice>(2)"
9051 msgstr ""
9052
9053 #. type: TH
9054 #: build/C/man2/set_tid_address.2:25
9055 #, no-wrap
9056 msgid "SET_TID_ADDRESS"
9057 msgstr ""
9058
9059 #. type: TH
9060 #: build/C/man2/set_tid_address.2:25
9061 #, no-wrap
9062 msgid "2012-07-19"
9063 msgstr ""
9064
9065 #. type: Plain text
9066 #: build/C/man2/set_tid_address.2:28
9067 msgid "set_tid_address - set pointer to thread ID"
9068 msgstr ""
9069
9070 #. type: Plain text
9071 #: build/C/man2/set_tid_address.2:31
9072 #, no-wrap
9073 msgid "B<#include E<lt>linux/unistd.hE<gt>>\n"
9074 msgstr ""
9075
9076 #. type: Plain text
9077 #: build/C/man2/set_tid_address.2:33
9078 #, no-wrap
9079 msgid "B<long set_tid_address(int *>I<tidptr>B<);>\n"
9080 msgstr ""
9081
9082 #. type: Plain text
9083 #: build/C/man2/set_tid_address.2:40
9084 msgid ""
9085 "For each process, the kernel maintains two attributes (addresses) called "
9086 "I<set_child_tid> and I<clear_child_tid>.  These two attributes contain the "
9087 "value NULL by default."
9088 msgstr ""
9089
9090 #. type: TP
9091 #: build/C/man2/set_tid_address.2:40
9092 #, no-wrap
9093 msgid "I<set_child_tid>"
9094 msgstr ""
9095
9096 #. type: Plain text
9097 #: build/C/man2/set_tid_address.2:51
9098 msgid ""
9099 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_SETTID> "
9100 "flag, I<set_child_tid> is set to the value passed in the I<ctid> argument of "
9101 "that system call."
9102 msgstr ""
9103
9104 #. type: Plain text
9105 #: build/C/man2/set_tid_address.2:56
9106 msgid ""
9107 "When I<set_child_tid> is set, the very first thing the new process does is "
9108 "writing its PID at this address."
9109 msgstr ""
9110
9111 #. type: TP
9112 #: build/C/man2/set_tid_address.2:56
9113 #, no-wrap
9114 msgid "I<clear_child_tid>"
9115 msgstr ""
9116
9117 #. type: Plain text
9118 #: build/C/man2/set_tid_address.2:67
9119 msgid ""
9120 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_CLEARTID> "
9121 "flag, I<clear_child_tid> is set to the value passed in the I<ctid> argument "
9122 "of that system call."
9123 msgstr ""
9124
9125 #. type: Plain text
9126 #: build/C/man2/set_tid_address.2:74
9127 msgid ""
9128 "The system call B<set_tid_address>()  sets the I<clear_child_tid> value for "
9129 "the calling process to I<tidptr>."
9130 msgstr ""
9131
9132 #. type: Plain text
9133 #: build/C/man2/set_tid_address.2:82
9134 msgid ""
9135 "When a process whose I<clear_child_tid> is not NULL terminates, then, if the "
9136 "process is sharing memory with other processes or threads, then 0 is written "
9137 "at the address specified in I<clear_child_tid> and the kernel performs the "
9138 "following operation:"
9139 msgstr ""
9140
9141 #. type: Plain text
9142 #: build/C/man2/set_tid_address.2:84
9143 #, no-wrap
9144 msgid "    futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);\n"
9145 msgstr ""
9146
9147 #. type: Plain text
9148 #: build/C/man2/set_tid_address.2:88
9149 msgid ""
9150 "The effect of this operation is to wake a single process that is performing "
9151 "a futex wait on the memory location.  Errors from the futex wake operation "
9152 "are ignored."
9153 msgstr ""
9154
9155 #. type: Plain text
9156 #: build/C/man2/set_tid_address.2:91
9157 msgid "B<set_tid_address>()  always returns the PID of the calling process."
9158 msgstr ""
9159
9160 #. type: Plain text
9161 #: build/C/man2/set_tid_address.2:94
9162 msgid "B<set_tid_address>()  always succeeds."
9163 msgstr ""
9164
9165 #. type: Plain text
9166 #: build/C/man2/set_tid_address.2:97
9167 msgid ""
9168 "This call is present since Linux 2.5.48.  Details as given here are valid "
9169 "since Linux 2.5.49."
9170 msgstr ""
9171
9172 #. type: Plain text
9173 #: build/C/man2/set_tid_address.2:102
9174 msgid "B<clone>(2), B<futex>(2)"
9175 msgstr ""
9176
9177 #. type: TH
9178 #: build/C/man2/splice.2:26
9179 #, no-wrap
9180 msgid "SPLICE"
9181 msgstr ""
9182
9183 #. type: TH
9184 #: build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vmsplice.2:26
9185 #, no-wrap
9186 msgid "2012-05-04"
9187 msgstr ""
9188
9189 #. type: Plain text
9190 #: build/C/man2/splice.2:29
9191 msgid "splice - splice data to/from a pipe"
9192 msgstr ""
9193
9194 #. type: Plain text
9195 #: build/C/man2/splice.2:33 build/C/man2/tee.2:33
9196 #, no-wrap
9197 msgid ""
9198 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
9199 "B<#include E<lt>fcntl.hE<gt>>\n"
9200 msgstr ""
9201
9202 #.  Return type was long before glibc 2.7
9203 #. type: Plain text
9204 #: build/C/man2/splice.2:38
9205 #, no-wrap
9206 msgid ""
9207 "B<ssize_t splice(int >I<fd_in>B<, loff_t *>I<off_in>B<, int >I<fd_out>B<,>\n"
9208 "B<               loff_t *>I<off_out>B<, size_t >I<len>B<, unsigned int "
9209 ">I<flags>B<);>\n"
9210 msgstr ""
9211
9212 #. type: Plain text
9213 #: build/C/man2/splice.2:50
9214 msgid ""
9215 "B<splice>()  moves data between two file descriptors without copying between "
9216 "kernel address space and user address space.  It transfers up to I<len> "
9217 "bytes of data from the file descriptor I<fd_in> to the file descriptor "
9218 "I<fd_out>, where one of the descriptors must refer to a pipe."
9219 msgstr ""
9220
9221 #. type: Plain text
9222 #: build/C/man2/splice.2:80
9223 msgid ""
9224 "If I<fd_in> refers to a pipe, then I<off_in> must be NULL.  If I<fd_in> does "
9225 "not refer to a pipe and I<off_in> is NULL, then bytes are read from I<fd_in> "
9226 "starting from the current file offset, and the current file offset is "
9227 "adjusted appropriately.  If I<fd_in> does not refer to a pipe and I<off_in> "
9228 "is not NULL, then I<off_in> must point to a buffer which specifies the "
9229 "starting offset from which bytes will be read from I<fd_in>; in this case, "
9230 "the current file offset of I<fd_in> is not changed.  Analogous statements "
9231 "apply for I<fd_out> and I<off_out>."
9232 msgstr ""
9233
9234 #. type: Plain text
9235 #: build/C/man2/splice.2:85 build/C/man2/vmsplice.2:78
9236 msgid ""
9237 "The I<flags> argument is a bit mask that is composed by ORing together zero "
9238 "or more of the following values:"
9239 msgstr ""
9240
9241 #. type: TP
9242 #: build/C/man2/splice.2:85 build/C/man2/tee.2:62 build/C/man2/vmsplice.2:78
9243 #, no-wrap
9244 msgid "B<SPLICE_F_MOVE>"
9245 msgstr ""
9246
9247 #. type: Plain text
9248 #: build/C/man2/splice.2:98
9249 msgid ""
9250 "Attempt to move pages instead of copying.  This is only a hint to the "
9251 "kernel: pages may still be copied if the kernel cannot move the pages from "
9252 "the pipe, or if the pipe buffers don't refer to full pages.  The initial "
9253 "implementation of this flag was buggy: therefore starting in Linux 2.6.21 it "
9254 "is a no-op (but is still permitted in a B<splice>()  call); in the future, a "
9255 "correct implementation may be restored."
9256 msgstr ""
9257
9258 #. type: TP
9259 #: build/C/man2/splice.2:98 build/C/man2/tee.2:68 build/C/man2/vmsplice.2:84
9260 #, no-wrap
9261 msgid "B<SPLICE_F_NONBLOCK>"
9262 msgstr ""
9263
9264 #. type: Plain text
9265 #: build/C/man2/splice.2:107
9266 msgid ""
9267 "Do not block on I/O.  This makes the splice pipe operations nonblocking, but "
9268 "B<splice>()  may nevertheless block because the file descriptors that are "
9269 "spliced to/from may block (unless they have the B<O_NONBLOCK> flag set)."
9270 msgstr ""
9271
9272 #. type: TP
9273 #: build/C/man2/splice.2:107 build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
9274 #, no-wrap
9275 msgid "B<SPLICE_F_MORE>"
9276 msgstr ""
9277
9278 #. type: Plain text
9279 #: build/C/man2/splice.2:121
9280 msgid ""
9281 "More data will be coming in a subsequent splice.  This is a helpful hint "
9282 "when the I<fd_out> refers to a socket (see also the description of "
9283 "B<MSG_MORE> in B<send>(2), and the description of B<TCP_CORK> in B<tcp>(7))"
9284 msgstr ""
9285
9286 #. type: TP
9287 #: build/C/man2/splice.2:121 build/C/man2/tee.2:79 build/C/man2/vmsplice.2:97
9288 #, no-wrap
9289 msgid "B<SPLICE_F_GIFT>"
9290 msgstr ""
9291
9292 #. type: Plain text
9293 #: build/C/man2/splice.2:127
9294 msgid "Unused for B<splice>(); see B<vmsplice>(2)."
9295 msgstr ""
9296
9297 #. type: Plain text
9298 #: build/C/man2/splice.2:136
9299 msgid ""
9300 "Upon successful completion, B<splice>()  returns the number of bytes spliced "
9301 "to or from the pipe.  A return value of 0 means that there was no data to "
9302 "transfer, and it would not make sense to block, because there are no writers "
9303 "connected to the write end of the pipe referred to by I<fd_in>."
9304 msgstr ""
9305
9306 #. type: Plain text
9307 #: build/C/man2/splice.2:142
9308 msgid "On error, B<splice>()  returns -1 and I<errno> is set to indicate the error."
9309 msgstr ""
9310
9311 #. type: Plain text
9312 #: build/C/man2/splice.2:147
9313 msgid ""
9314 "One or both file descriptors are not valid, or do not have proper read-write "
9315 "mode."
9316 msgstr ""
9317
9318 #.  The append-mode error is given since 2.6.27; in earlier kernels,
9319 #.  splice() in append mode was broken
9320 #. type: Plain text
9321 #: build/C/man2/splice.2:155
9322 msgid ""
9323 "Target file system doesn't support splicing; target file is opened in append "
9324 "mode; neither of the descriptors refers to a pipe; or offset given for "
9325 "nonseekable device."
9326 msgstr ""
9327
9328 #. type: Plain text
9329 #: build/C/man2/splice.2:158 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
9330 msgid "Out of memory."
9331 msgstr ""
9332
9333 #. type: TP
9334 #: build/C/man2/splice.2:158
9335 #, no-wrap
9336 msgid "B<ESPIPE>"
9337 msgstr ""
9338
9339 #. type: Plain text
9340 #: build/C/man2/splice.2:165
9341 msgid ""
9342 "Either I<off_in> or I<off_out> was not NULL, but the corresponding file "
9343 "descriptor refers to a pipe."
9344 msgstr ""
9345
9346 #. type: Plain text
9347 #: build/C/man2/splice.2:170
9348 msgid ""
9349 "The B<splice>()  system call first appeared in Linux 2.6.17; library support "
9350 "was added to glibc in version 2.5."
9351 msgstr ""
9352
9353 #. type: Plain text
9354 #: build/C/man2/splice.2:182
9355 msgid ""
9356 "The three system calls B<splice>(), B<vmsplice>(2), and B<tee>(2), provide "
9357 "user-space programs with full control over an arbitrary kernel buffer, "
9358 "implemented within the kernel using the same type of buffer that is used for "
9359 "a pipe.  In overview, these system calls perform the following tasks:"
9360 msgstr ""
9361
9362 #. type: TP
9363 #: build/C/man2/splice.2:182
9364 #, no-wrap
9365 msgid "B<splice>()"
9366 msgstr ""
9367
9368 #. type: Plain text
9369 #: build/C/man2/splice.2:186
9370 msgid ""
9371 "moves data from the buffer to an arbitrary file descriptor, or vice versa, "
9372 "or from one buffer to another."
9373 msgstr ""
9374
9375 #. type: TP
9376 #: build/C/man2/splice.2:186
9377 #, no-wrap
9378 msgid "B<tee>(2)"
9379 msgstr ""
9380
9381 #. type: Plain text
9382 #: build/C/man2/splice.2:189
9383 msgid "\"copies\" the data from one buffer to another."
9384 msgstr ""
9385
9386 #. type: TP
9387 #: build/C/man2/splice.2:189
9388 #, no-wrap
9389 msgid "B<vmsplice>(2)"
9390 msgstr ""
9391
9392 #. type: Plain text
9393 #: build/C/man2/splice.2:192
9394 msgid "\"copies\" data from user space into the buffer."
9395 msgstr ""
9396
9397 #
9398 #.  Linus: Now, imagine using the above in a media server, for example.
9399 #.  Let's say that a year or two has passed, so that the video drivers
9400 #.  have been updated to be able to do the splice thing, and what can
9401 #.  you do? You can:
9402 #
9403 #.  - splice from the (mpeg or whatever - let's just assume that the video
9404 #.    input is either digital or does the encoding on its own - like they
9405 #.    pretty much all do) video input into a pipe (remember: no copies - the
9406 #.    video input will just DMA directly into memory, and splice will just
9407 #.    set up the pages in the pipe buffer)
9408 #.  - tee that pipe to split it up
9409 #.  - splice one end to a file (ie "save the compressed stream to disk")
9410 #.  - splice the other end to a real-time video decoder window for your
9411 #.    real-time viewing pleasure.
9412 #
9413 #.  Linus: Now, the advantage of splice()/tee() is that you can
9414 #.  do zero-copy movement of data, and unlike sendfile() you can
9415 #.  do it on _arbitrary_ data (and, as shown by "tee()", it's more
9416 #.  than just sending the data to somebody else: you can duplicate
9417 #.  the data and choose to forward it to two or more different
9418 #.  users - for things like logging etc.).
9419 #. type: Plain text
9420 #: build/C/man2/splice.2:223
9421 msgid ""
9422 "Though we talk of copying, actual copies are generally avoided.  The kernel "
9423 "does this by implementing a pipe buffer as a set of reference-counted "
9424 "pointers to pages of kernel memory.  The kernel creates \"copies\" of pages "
9425 "in a buffer by creating new pointers (for the output buffer) referring to "
9426 "the pages, and increasing the reference counts for the pages: only pointers "
9427 "are copied, not the pages of the buffer."
9428 msgstr ""
9429
9430 #. type: Plain text
9431 #: build/C/man2/splice.2:226
9432 msgid "See B<tee>(2)."
9433 msgstr ""
9434
9435 #. type: Plain text
9436 #: build/C/man2/splice.2:230
9437 msgid "B<sendfile>(2), B<tee>(2), B<vmsplice>(2)"
9438 msgstr ""
9439
9440 #. type: TH
9441 #: build/C/man2/tee.2:26
9442 #, no-wrap
9443 msgid "TEE"
9444 msgstr ""
9445
9446 #. type: Plain text
9447 #: build/C/man2/tee.2:29
9448 msgid "tee - duplicating pipe content"
9449 msgstr ""
9450
9451 #. type: Plain text
9452 #: build/C/man2/tee.2:36
9453 #, no-wrap
9454 msgid ""
9455 "B<ssize_t tee(int >I<fd_in>B<, int >I<fd_out>B<, size_t >I<len>B<, unsigned "
9456 "int >I<flags>B<);>\n"
9457 msgstr ""
9458
9459 #.  Example programs http://brick.kernel.dk/snaps
9460 #
9461 #
9462 #.  add a "tee(in, out1, out2)" system call that duplicates the pages
9463 #.  (again, incrementing their reference count, not copying the data) from
9464 #.  one pipe to two other pipes.
9465 #. type: Plain text
9466 #: build/C/man2/tee.2:56
9467 msgid ""
9468 "B<tee>()  duplicates up to I<len> bytes of data from the pipe referred to by "
9469 "the file descriptor I<fd_in> to the pipe referred to by the file descriptor "
9470 "I<fd_out>.  It does not consume the data that is duplicated from I<fd_in>; "
9471 "therefore, that data can be copied by a subsequent B<splice>(2)."
9472 msgstr ""
9473
9474 #. type: Plain text
9475 #: build/C/man2/tee.2:62
9476 msgid ""
9477 "I<flags> is a series of modifier flags, which share the name space with "
9478 "B<splice>(2)  and B<vmsplice>(2):"
9479 msgstr ""
9480
9481 #. type: Plain text
9482 #: build/C/man2/tee.2:68
9483 msgid "Currently has no effect for B<tee>(); see B<splice>(2)."
9484 msgstr ""
9485
9486 #.  Not used for vmsplice
9487 #.  May be in the future -- therefore EAGAIN
9488 #. type: Plain text
9489 #: build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
9490 msgid "Do not block on I/O; see B<splice>(2)  for further details."
9491 msgstr ""
9492
9493 #. type: Plain text
9494 #: build/C/man2/tee.2:79
9495 msgid ""
9496 "Currently has no effect for B<tee>(), but may be implemented in the future; "
9497 "see B<splice>(2)."
9498 msgstr ""
9499
9500 #. type: Plain text
9501 #: build/C/man2/tee.2:85
9502 msgid "Unused for B<tee>(); see B<vmsplice>(2)."
9503 msgstr ""
9504
9505 #. type: Plain text
9506 #: build/C/man2/tee.2:94
9507 msgid ""
9508 "Upon successful completion, B<tee>()  returns the number of bytes that were "
9509 "duplicated between the input and output.  A return value of 0 means that "
9510 "there was no data to transfer, and it would not make sense to block, because "
9511 "there are no writers connected to the write end of the pipe referred to by "
9512 "I<fd_in>."
9513 msgstr ""
9514
9515 #. type: Plain text
9516 #: build/C/man2/tee.2:100
9517 msgid "On error, B<tee>()  returns -1 and I<errno> is set to indicate the error."
9518 msgstr ""
9519
9520 #. type: Plain text
9521 #: build/C/man2/tee.2:111
9522 msgid ""
9523 "I<fd_in> or I<fd_out> does not refer to a pipe; or I<fd_in> and I<fd_out> "
9524 "refer to the same pipe."
9525 msgstr ""
9526
9527 #. type: Plain text
9528 #: build/C/man2/tee.2:119
9529 msgid ""
9530 "The B<tee>()  system call first appeared in Linux 2.6.17; library support "
9531 "was added to glibc in version 2.5."
9532 msgstr ""
9533
9534 #. type: Plain text
9535 #: build/C/man2/tee.2:130
9536 msgid ""
9537 "Conceptually, B<tee>()  copies the data between the two pipes.  In reality "
9538 "no real data copying takes place though: under the covers, B<tee>()  assigns "
9539 "data in the output by merely grabbing a reference to the input."
9540 msgstr ""
9541
9542 #. type: Plain text
9543 #: build/C/man2/tee.2:136
9544 msgid ""
9545 "The following example implements a basic B<tee>(1)  program using the "
9546 "B<tee>()  system call."
9547 msgstr ""
9548
9549 #. type: Plain text
9550 #: build/C/man2/tee.2:145
9551 #, no-wrap
9552 msgid ""
9553 "#define _GNU_SOURCE\n"
9554 "#include E<lt>fcntl.hE<gt>\n"
9555 "#include E<lt>stdio.hE<gt>\n"
9556 "#include E<lt>stdlib.hE<gt>\n"
9557 "#include E<lt>unistd.hE<gt>\n"
9558 "#include E<lt>errno.hE<gt>\n"
9559 "#include E<lt>limits.hE<gt>\n"
9560 msgstr ""
9561
9562 #. type: Plain text
9563 #: build/C/man2/tee.2:151
9564 #, no-wrap
9565 msgid ""
9566 "int\n"
9567 "main(int argc, char *argv[])\n"
9568 "{\n"
9569 "    int fd;\n"
9570 "    int len, slen;\n"
9571 msgstr ""
9572
9573 #. type: Plain text
9574 #: build/C/man2/tee.2:156
9575 #, no-wrap
9576 msgid ""
9577 "    if (argc != 2) {\n"
9578 "        fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
9579 "        exit(EXIT_FAILURE);\n"
9580 "    }\n"
9581 msgstr ""
9582
9583 #. type: Plain text
9584 #: build/C/man2/tee.2:162
9585 #, no-wrap
9586 msgid ""
9587 "    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);\n"
9588 "    if (fd == -1) {\n"
9589 "        perror(\"open\");\n"
9590 "        exit(EXIT_FAILURE);\n"
9591 "    }\n"
9592 msgstr ""
9593
9594 #. type: Plain text
9595 #: build/C/man2/tee.2:169
9596 #, no-wrap
9597 msgid ""
9598 "    do {\n"
9599 "        /*\n"
9600 "         * tee stdin to stdout.\n"
9601 "         */\n"
9602 "        len = tee(STDIN_FILENO, STDOUT_FILENO,\n"
9603 "                  INT_MAX, SPLICE_F_NONBLOCK);\n"
9604 msgstr ""
9605
9606 #. type: Plain text
9607 #: build/C/man2/tee.2:178
9608 #, no-wrap
9609 msgid ""
9610 "        if (len E<lt> 0) {\n"
9611 "            if (errno == EAGAIN)\n"
9612 "                continue;\n"
9613 "            perror(\"tee\");\n"
9614 "            exit(EXIT_FAILURE);\n"
9615 "        } else\n"
9616 "            if (len == 0)\n"
9617 "                break;\n"
9618 msgstr ""
9619
9620 #. type: Plain text
9621 #: build/C/man2/tee.2:192
9622 #, no-wrap
9623 msgid ""
9624 "        /*\n"
9625 "         * Consume stdin by splicing it to a file.\n"
9626 "         */\n"
9627 "        while (len E<gt> 0) {\n"
9628 "            slen = splice(STDIN_FILENO, NULL, fd, NULL,\n"
9629 "                          len, SPLICE_F_MOVE);\n"
9630 "            if (slen E<lt> 0) {\n"
9631 "                perror(\"splice\");\n"
9632 "                break;\n"
9633 "            }\n"
9634 "            len -= slen;\n"
9635 "        }\n"
9636 "    } while (1);\n"
9637 msgstr ""
9638
9639 #. type: Plain text
9640 #: build/C/man2/tee.2:196
9641 #, no-wrap
9642 msgid ""
9643 "    close(fd);\n"
9644 "    exit(EXIT_SUCCESS);\n"
9645 "}\n"
9646 msgstr ""
9647
9648 #. type: Plain text
9649 #: build/C/man2/tee.2:200
9650 msgid "B<splice>(2), B<vmsplice>(2)"
9651 msgstr ""
9652
9653 #. type: TH
9654 #: build/C/man2/vm86.2:26
9655 #, no-wrap
9656 msgid "VM86"
9657 msgstr ""
9658
9659 #. type: TH
9660 #: build/C/man2/vm86.2:26
9661 #, no-wrap
9662 msgid "2009-02-20"
9663 msgstr ""
9664
9665 #. type: Plain text
9666 #: build/C/man2/vm86.2:29
9667 msgid "vm86old, vm86 - enter virtual 8086 mode"
9668 msgstr ""
9669
9670 #. type: Plain text
9671 #: build/C/man2/vm86.2:31
9672 msgid "B<#include E<lt>sys/vm86.hE<gt>>"
9673 msgstr ""
9674
9675 #. type: Plain text
9676 #: build/C/man2/vm86.2:33
9677 msgid "B<int vm86old(struct vm86_struct *>I<info>B<);>"
9678 msgstr ""
9679
9680 #. type: Plain text
9681 #: build/C/man2/vm86.2:35
9682 msgid "B<int vm86(unsigned long >I<fn>B<, struct vm86plus_struct *>I<v86>B<);>"
9683 msgstr ""
9684
9685 #. type: Plain text
9686 #: build/C/man2/vm86.2:46
9687 msgid ""
9688 "The system call B<vm86>()  was introduced in Linux 0.97p2.  In Linux 2.1.15 "
9689 "and 2.0.28 it was renamed to B<vm86old>(), and a new B<vm86>()  was "
9690 "introduced.  The definition of I<struct vm86_struct> was changed in 1.1.8 "
9691 "and 1.1.9."
9692 msgstr ""
9693
9694 #. type: Plain text
9695 #: build/C/man2/vm86.2:50
9696 msgid ""
9697 "These calls cause the process to enter VM86 mode (virtual-8086 in Intel "
9698 "literature), and are used by B<dosemu>."
9699 msgstr ""
9700
9701 #. type: Plain text
9702 #: build/C/man2/vm86.2:52
9703 msgid "VM86 mode is an emulation of real mode within a protected mode task."
9704 msgstr ""
9705
9706 #. type: Plain text
9707 #: build/C/man2/vm86.2:62
9708 msgid ""
9709 "This return value is specific to i386 and indicates a problem with getting "
9710 "user-space data."
9711 msgstr ""
9712
9713 #. type: Plain text
9714 #: build/C/man2/vm86.2:66
9715 msgid ""
9716 "This return value indicates the call is not implemented on the present "
9717 "architecture."
9718 msgstr ""
9719
9720 #. type: Plain text
9721 #: build/C/man2/vm86.2:71
9722 msgid ""
9723 "Saved kernel stack exists.  (This is a kernel sanity check; the saved stack "
9724 "should only exist within vm86 mode itself.)"
9725 msgstr ""
9726
9727 #. type: Plain text
9728 #: build/C/man2/vm86.2:74
9729 msgid ""
9730 "This call is specific to Linux on 32-bit Intel processors, and should not be "
9731 "used in programs intended to be portable."
9732 msgstr ""
9733
9734 #. type: TH
9735 #: build/C/man2/vmsplice.2:26
9736 #, no-wrap
9737 msgid "VMSPLICE"
9738 msgstr ""
9739
9740 #. type: Plain text
9741 #: build/C/man2/vmsplice.2:29
9742 msgid "vmsplice - splice user pages into a pipe"
9743 msgstr ""
9744
9745 #. type: Plain text
9746 #: build/C/man2/vmsplice.2:34
9747 #, no-wrap
9748 msgid ""
9749 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
9750 "B<#include E<lt>fcntl.hE<gt>>\n"
9751 "B<#include E<lt>sys/uio.hE<gt>>\n"
9752 msgstr ""
9753
9754 #. type: Plain text
9755 #: build/C/man2/vmsplice.2:37
9756 #, no-wrap
9757 msgid ""
9758 "B<ssize_t vmsplice(int >I<fd>B<, const struct iovec *>I<iov>B<,>\n"
9759 "B<                 unsigned long >I<nr_segs>B<, unsigned int "
9760 ">I<flags>B<);>\n"
9761 msgstr ""
9762
9763 #.  Linus: vmsplice() system call to basically do a "write to
9764 #.  the buffer", but using the reference counting and VM traversal
9765 #.  to actually fill the buffer. This means that the user needs to
9766 #.  be careful not to reuse the user-space buffer it spliced into
9767 #.  the kernel-space one (contrast this to "write()", which copies
9768 #.  the actual data, and you can thus reuse the buffer immediately
9769 #.  after a successful write), but that is often easy to do.
9770 #. type: Plain text
9771 #: build/C/man2/vmsplice.2:57
9772 msgid ""
9773 "The B<vmsplice>()  system call maps I<nr_segs> ranges of user memory "
9774 "described by I<iov> into a pipe.  The file descriptor I<fd> must refer to a "
9775 "pipe."
9776 msgstr ""
9777
9778 #. type: Plain text
9779 #: build/C/man2/vmsplice.2:64
9780 msgid ""
9781 "The pointer I<iov> points to an array of I<iovec> structures as defined in "
9782 "I<E<lt>sys/uio.hE<gt>>:"
9783 msgstr ""
9784
9785 #. type: Plain text
9786 #: build/C/man2/vmsplice.2:71
9787 #, no-wrap
9788 msgid ""
9789 "struct iovec {\n"
9790 "    void  *iov_base;            /* Starting address */\n"
9791 "    size_t iov_len;             /* Number of bytes */\n"
9792 "};\n"
9793 msgstr ""
9794
9795 #. type: Plain text
9796 #: build/C/man2/vmsplice.2:84
9797 msgid "Unused for B<vmsplice>(); see B<splice>(2)."
9798 msgstr ""
9799
9800 #. type: Plain text
9801 #: build/C/man2/vmsplice.2:97
9802 msgid ""
9803 "Currently has no effect for B<vmsplice>(), but may be implemented in the "
9804 "future; see B<splice>(2)."
9805 msgstr ""
9806
9807 #.  FIXME Explain the following line in a little more detail:
9808 #.  .... if we expect to later SPLICE_F_MOVE to the cache.
9809 #. type: Plain text
9810 #: build/C/man2/vmsplice.2:113
9811 msgid ""
9812 "The user pages are a gift to the kernel.  The application may not modify "
9813 "this memory ever, or page cache and on-disk data may differ.  Gifting pages "
9814 "to the kernel means that a subsequent B<splice>(2)  B<SPLICE_F_MOVE> can "
9815 "successfully move the pages; if this flag is not specified, then a "
9816 "subsequent B<splice>(2)  B<SPLICE_F_MOVE> must copy the pages.  Data must "
9817 "also be properly page aligned, both in memory and length."
9818 msgstr ""
9819
9820 #. type: Plain text
9821 #: build/C/man2/vmsplice.2:122
9822 msgid ""
9823 "Upon successful completion, B<vmsplice>()  returns the number of bytes "
9824 "transferred to the pipe.  On error, B<vmsplice>()  returns -1 and I<errno> "
9825 "is set to indicate the error."
9826 msgstr ""
9827
9828 #. type: Plain text
9829 #: build/C/man2/vmsplice.2:127
9830 msgid "I<fd> either not valid, or doesn't refer to a pipe."
9831 msgstr ""
9832
9833 #. type: Plain text
9834 #: build/C/man2/vmsplice.2:135
9835 msgid ""
9836 "I<nr_segs> is 0 or greater than B<IOV_MAX>; or memory not aligned if "
9837 "B<SPLICE_F_GIFT> set."
9838 msgstr ""
9839
9840 #. type: Plain text
9841 #: build/C/man2/vmsplice.2:143
9842 msgid ""
9843 "The B<vmsplice>()  system call first appeared in Linux 2.6.17; library "
9844 "support was added to glibc in version 2.5."
9845 msgstr ""
9846
9847 #. type: Plain text
9848 #: build/C/man2/vmsplice.2:154
9849 msgid ""
9850 "B<vmsplice>()  follows the other vectorized read/write type functions when "
9851 "it comes to limitations on number of segments being passed in.  This limit "
9852 "is B<IOV_MAX> as defined in I<E<lt>limits.hE<gt>>.  At the time of this "
9853 "writing, that limit is 1024."
9854 msgstr ""
9855
9856 #. type: Plain text
9857 #: build/C/man2/vmsplice.2:157
9858 msgid "B<splice>(2), B<tee>(2)"
9859 msgstr ""