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: 2014-04-24 00:51+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=UTF-8\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 "Subfunctions 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:214 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:53 build/C/man2/pciconfig_read.2:50 build/C/man2/perf_event_open.2:2371 build/C/man2/perfmonctl.2:190 build/C/man2/personality.2:62 build/C/man2/pivot_root.2:101 build/C/man2/process_vm_readv.2:209 build/C/man2/ptrace.2:1853 build/C/man2/quotactl.2:419 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:54 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:239 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:2377 build/C/man2/personality.2:69 build/C/man2/pivot_root.2:105 build/C/man2/process_vm_readv.2:229 build/C/man2/ptrace.2:1868 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:59 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:254 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/perf_event_open.2:2423 build/C/man2/process_vm_readv.2:251 build/C/man2/process_vm_readv.2:256 build/C/man2/ptrace.2:1872 build/C/man2/quotactl.2:428 build/C/man2/sendfile.2:125 build/C/man2/vm86.2:60
 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:266 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:2428 build/C/man2/personality.2:70 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:1883 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/perf_event_open.2:2495 build/C/man2/pivot_root.2:120 build/C/man2/process_vm_readv.2:267 build/C/man2/ptrace.2:1893 build/C/man2/quotactl.2:456 build/C/man2/vm86.2:68
 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:301 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:58 build/C/man2/outb.2:87 build/C/man2/pciconfig_read.2:112 build/C/man2/perf_event_open.2:2516 build/C/man2/perfmonctl.2:199 build/C/man2/personality.2:73 build/C/man2/pivot_root.2:128 build/C/man2/process_vm_readv.2:279 build/C/man2/ptrace.2:1911 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:73 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:303 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:2521 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:1913 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 supported only 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 needed only 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:317 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:114 build/C/man2/perf_event_open.2:2652 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:2079 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:331 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:60 build/C/man2/outb.2:99 build/C/man2/pciconfig_read.2:116 build/C/man2/perf_event_open.2:2658 build/C/man2/perfmonctl.2:209 build/C/man2/personality.2:77 build/C/man2/pivot_root.2:149 build/C/man2/process_vm_readv.2:334 build/C/man2/ptrace.2:2093 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:76 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:338 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:67 build/C/man2/outb.2:106 build/C/man2/pciconfig_read.2:123 build/C/man2/perf_event_open.2:2665 build/C/man2/perfmonctl.2:216 build/C/man2/personality.2:84 build/C/man2/pivot_root.2:156 build/C/man2/process_vm_readv.2:341 build/C/man2/ptrace.2:2100 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:83 build/C/man2/vmsplice.2:164
 289 msgid ""
 290 "This page is part of release 3.65 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-12-12"
 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:221
 380 #, no-wrap
 381 msgid "B<FUTEX_WAIT>"
 382 msgstr ""
 383
 384 #. type: Plain text
 385 #: build/C/man2/futex.2:131
 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 specify the "
 390 "duration of the wait.  (This interval will be rounded up to the system clock "
 391 "granularity, and kernel scheduling delays mean that the blocking interval "
 392 "may overrun by a small amount.)  If I<timeout> is NULL, the call blocks "
 393 "indefinitely.  The arguments I<uaddr2> and I<val3> are ignored."
 394 msgstr ""
 395
 396 #. type: Plain text
 397 #: build/C/man2/futex.2:139
 398 msgid ""
 399 "For B<futex>(7), this call is executed if decrementing the count gave a "
 400 "negative value (indicating contention), and will sleep until another process "
 401 "releases the futex and executes the B<FUTEX_WAKE> operation."
 402 msgstr ""
 403
 404 #. type: TP
 405 #: build/C/man2/futex.2:139 build/C/man2/futex.2:227
 406 #, no-wrap
 407 msgid "B<FUTEX_WAKE>"
 408 msgstr ""
 409
 410 #. type: Plain text
 411 #: build/C/man2/futex.2:150
 412 msgid ""
 413 "This operation wakes at most I<val> processes waiting on this futex address "
 414 "(i.e., inside B<FUTEX_WAIT>).  The arguments I<timeout>, I<uaddr2> and "
 415 "I<val3> are ignored."
 416 msgstr ""
 417
 418 #. type: Plain text
 419 #: build/C/man2/futex.2:156
 420 msgid ""
 421 "For B<futex>(7), this is executed if incrementing the count showed that "
 422 "there were waiters, once the futex value has been set to 1 (indicating that "
 423 "it is available)."
 424 msgstr ""
 425
 426 #. type: TP
 427 #: build/C/man2/futex.2:156
 428 #, no-wrap
 429 msgid "B<FUTEX_FD> (present up to and including Linux 2.6.25)"
 430 msgstr ""
 431
 432 #.  , suitable for .BR poll (2).
 433 #. type: Plain text
 434 #: build/C/man2/futex.2:172
 435 msgid ""
 436 "To support asynchronous wakeups, this operation associates a file descriptor "
 437 "with a futex.  If another process executes a B<FUTEX_WAKE>, the process will "
 438 "receive the signal number that was passed in I<val>.  The calling process "
 439 "must close the returned file descriptor after use.  The arguments "
 440 "I<timeout>, I<uaddr2> and I<val3> are ignored."
 441 msgstr ""
 442
 443 #. type: Plain text
 444 #: build/C/man2/futex.2:177
 445 msgid ""
 446 "To prevent race conditions, the caller should test if the futex has been "
 447 "upped after B<FUTEX_FD> returns."
 448 msgstr ""
 449
 450 #. type: Plain text
 451 #: build/C/man2/futex.2:181
 452 msgid ""
 453 "Because it was inherently racy, B<FUTEX_FD> has been removed from Linux "
 454 "2.6.26 onward."
 455 msgstr ""
 456
 457 #. type: TP
 458 #: build/C/man2/futex.2:181
 459 #, no-wrap
 460 msgid "B<FUTEX_REQUEUE> (since Linux 2.5.70)"
 461 msgstr ""
 462
 463 #. type: Plain text
 464 #: build/C/man2/futex.2:196
 465 msgid ""
 466 "This operation was introduced in order to avoid a \"thundering herd\" effect "
 467 "when B<FUTEX_WAKE> is used and all processes woken up need to acquire "
 468 "another futex.  This call wakes up I<val> processes, and requeues all other "
 469 "waiters on the futex at address I<uaddr2>.  The arguments I<timeout> and "
 470 "I<val3> are ignored."
 471 msgstr ""
 472
 473 #. type: TP
 474 #: build/C/man2/futex.2:196
 475 #, no-wrap
 476 msgid "B<FUTEX_CMP_REQUEUE> (since Linux 2.6.7)"
 477 msgstr ""
 478
 479 #. type: Plain text
 480 #: build/C/man2/futex.2:214
 481 msgid ""
 482 "There was a race in the intended use of B<FUTEX_REQUEUE>, so "
 483 "B<FUTEX_CMP_REQUEUE> was introduced.  This is similar to B<FUTEX_REQUEUE>, "
 484 "but first checks whether the location I<uaddr> still contains the value "
 485 "I<val3>.  If not, the operation fails with the error B<EAGAIN>.  The "
 486 "argument I<timeout> is ignored."
 487 msgstr ""
 488
 489 #. type: Plain text
 490 #: build/C/man2/futex.2:221
 491 msgid ""
 492 "In the event of an error, all operations return -1, and set I<errno> to "
 493 "indicate the error.  The return value on success depends on the operation, "
 494 "as described in the following list:"
 495 msgstr ""
 496
 497 #. type: Plain text
 498 #: build/C/man2/futex.2:227
 499 msgid ""
 500 "Returns 0 if the process was woken by a B<FUTEX_WAKE> call.  See ERRORS for "
 501 "the various possible error returns."
 502 msgstr ""
 503
 504 #. type: Plain text
 505 #: build/C/man2/futex.2:230 build/C/man2/futex.2:236 build/C/man2/futex.2:239
 506 msgid "Returns the number of processes woken up."
 507 msgstr ""
 508
 509 #. type: TP
 510 #: build/C/man2/futex.2:230
 511 #, no-wrap
 512 msgid "B<FUTEX_FD>"
 513 msgstr ""
 514
 515 #. type: Plain text
 516 #: build/C/man2/futex.2:233
 517 msgid "Returns the new file descriptor associated with the futex."
 518 msgstr ""
 519
 520 #. type: TP
 521 #: build/C/man2/futex.2:233
 522 #, no-wrap
 523 msgid "B<FUTEX_REQUEUE>"
 524 msgstr ""
 525
 526 #. type: TP
 527 #: build/C/man2/futex.2:236
 528 #, no-wrap
 529 msgid "B<FUTEX_CMP_REQUEUE>"
 530 msgstr ""
 531
 532 #. type: TP
 533 #: build/C/man2/futex.2:240 build/C/man2/perf_event_open.2:2399 build/C/man2/quotactl.2:486
 534 #, no-wrap
 535 msgid "B<EACCES>"
 536 msgstr ""
 537
 538 #. type: Plain text
 539 #: build/C/man2/futex.2:243
 540 msgid "No read access to futex memory."
 541 msgstr ""
 542
 543 #. type: TP
 544 #: build/C/man2/futex.2:243 build/C/man2/sendfile.2:116
 545 #, no-wrap
 546 msgid "B<EAGAIN>"
 547 msgstr ""
 548
 549 #. type: Plain text
 550 #: build/C/man2/futex.2:254
 551 msgid ""
 552 "B<FUTEX_CMP_REQUEUE> detected that the value pointed to by I<uaddr> is not "
 553 "equal to the expected value I<val3>.  (This probably indicates a race; use "
 554 "the safe B<FUTEX_WAKE> now.)"
 555 msgstr ""
 556
 557 #. type: Plain text
 558 #: build/C/man2/futex.2:259
 559 msgid "Error retrieving I<timeout> information from user space."
 560 msgstr ""
 561
 562 #. type: TP
 563 #: build/C/man2/futex.2:259
 564 #, no-wrap
 565 msgid "B<EINTR>"
 566 msgstr ""
 567
 568 #. type: Plain text
 569 #: build/C/man2/futex.2:266
 570 msgid ""
 571 "A B<FUTEX_WAIT> operation was interrupted by a signal (see B<signal>(7))  or "
 572 "a spurious wakeup."
 573 msgstr ""
 574
 575 #. type: Plain text
 576 #: build/C/man2/futex.2:269
 577 msgid "Invalid argument."
 578 msgstr ""
 579
 580 #. type: TP
 581 #: build/C/man2/futex.2:269
 582 #, no-wrap
 583 msgid "B<ENFILE>"
 584 msgstr ""
 585
 586 #. type: Plain text
 587 #: build/C/man2/futex.2:272
 588 msgid "The system limit on the total number of open files has been reached."
 589 msgstr ""
 590
 591 #. type: TP
 592 #: build/C/man2/futex.2:272 build/C/man2/modify_ldt.2:126 build/C/man2/pciconfig_read.2:93 build/C/man2/perf_event_open.2:2481 build/C/man2/quotactl.2:447 build/C/man2/vm86.2:64
 593 #, no-wrap
 594 msgid "B<ENOSYS>"
 595 msgstr ""
 596
 597 #. type: Plain text
 598 #: build/C/man2/futex.2:276
 599 msgid "Invalid operation specified in I<op>."
 600 msgstr ""
 601
 602 #. type: TP
 603 #: build/C/man2/futex.2:276
 604 #, no-wrap
 605 msgid "B<ETIMEDOUT>"
 606 msgstr ""
 607
 608 #. type: Plain text
 609 #: build/C/man2/futex.2:281
 610 msgid "Timeout during the B<FUTEX_WAIT> operation."
 611 msgstr ""
 612
 613 #. type: TP
 614 #: build/C/man2/futex.2:281
 615 #, no-wrap
 616 msgid "B<EWOULDBLOCK>"
 617 msgstr ""
 618
 619 #. type: Plain text
 620 #: build/C/man2/futex.2:291
 621 msgid ""
 622 "I<op> was B<FUTEX_WAIT> and the value pointed to by I<uaddr> was not equal "
 623 "to the expected value I<val> at the time of the call."
 624 msgstr ""
 625
 626 #. type: SH
 627 #: build/C/man2/futex.2:291 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
 628 #, no-wrap
 629 msgid "VERSIONS"
 630 msgstr ""
 631
 632 #. type: Plain text
 633 #: build/C/man2/futex.2:301
 634 msgid ""
 635 "Initial futex support was merged in Linux 2.5.7 but with different semantics "
 636 "from what was described above.  A 4-argument system call with the semantics "
 637 "described in this page was introduced in Linux 2.5.40.  In Linux 2.5.70 one "
 638 "argument was added.  In Linux 2.6.7 a sixth argument was added\\(emmessy, "
 639 "especially on the s390 architecture."
 640 msgstr ""
 641
 642 #. type: Plain text
 643 #: build/C/man2/futex.2:303 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
 644 msgid "This system call is Linux-specific."
 645 msgstr ""
 646
 647 #.  .SH "AUTHORS"
 648 #.  .PP
 649 #.  Futexes were designed and worked on by
 650 #.  Hubertus Franke (IBM Thomas J. Watson Research Center),
 651 #.  Matthew Kirkwood, Ingo Molnar (Red Hat)
 652 #.  and Rusty Russell (IBM Linux Technology Center).
 653 #.  This page written by bert hubert.
 654 #. type: Plain text
 655 #: build/C/man2/futex.2:317
 656 msgid ""
 657 "To reiterate, bare futexes are not intended as an easy-to-use abstraction "
 658 "for end-users.  (There is no wrapper function for this system call in "
 659 "glibc.)  Implementors are expected to be assembly literate and to have read "
 660 "the sources of the futex user-space library referenced below."
 661 msgstr ""
 662
 663 #. type: Plain text
 664 #: build/C/man2/futex.2:320
 665 msgid "B<restart_syscall>(2), B<futex>(7)"
 666 msgstr ""
 667
 668 #. type: Plain text
 669 #: build/C/man2/futex.2:323
 670 msgid ""
 671 "I<Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux> (proceedings "
 672 "of the Ottawa Linux Symposium 2002), online at"
 673 msgstr ""
 674
 675 #. type: Plain text
 676 #: build/C/man2/futex.2:326
 677 msgid ""
 678 "E<.UR http://kernel.org\\:/doc\\:/ols\\:/2002\\:/ols2002-pages-479-495.pdf> "
 679 "E<.UE>"
 680 msgstr ""
 681
 682 #. type: Plain text
 683 #: build/C/man2/futex.2:328
 684 msgid "Futex example library, futex-*.tar.bz2 at"
 685 msgstr ""
 686
 687 #. type: Plain text
 688 #: build/C/man2/futex.2:331
 689 msgid ""
 690 "E<.UR ftp://ftp.kernel.org\\:/pub\\:/linux\\:/kernel\\:/people\\:/rusty/> "
 691 "E<.UE>"
 692 msgstr ""
 693
 694 #. type: TH
 695 #: build/C/man2/get_robust_list.2:29
 696 #, no-wrap
 697 msgid "GET_ROBUST_LIST"
 698 msgstr ""
 699
 700 #. type: TH
 701 #: 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
 702 #, no-wrap
 703 msgid "2012-07-13"
 704 msgstr ""
 705
 706 #. type: TH
 707 #: build/C/man2/get_robust_list.2:29
 708 #, no-wrap
 709 msgid "Linux System Calls"
 710 msgstr ""
 711
 712 #. type: Plain text
 713 #: build/C/man2/get_robust_list.2:32
 714 msgid "get_robust_list, set_robust_list - get/set list of robust futexes"
 715 msgstr ""
 716
 717 #. type: Plain text
 718 #: build/C/man2/get_robust_list.2:36
 719 #, no-wrap
 720 msgid ""
 721 "B<#include E<lt>linux/futex.hE<gt>>\n"
 722 "B<#include E<lt>syscall.hE<gt>>\n"
 723 msgstr ""
 724
 725 #. type: Plain text
 726 #: build/C/man2/get_robust_list.2:40
 727 #, no-wrap
 728 msgid ""
 729 "B<long get_robust_list(int >I<pid>B<, struct robust_list_head "
 730 "**>I<head_ptr>B<,>\n"
 731 "B<                     size_t *>I<len_ptr>B<);>\n"
 732 "B<long set_robust_list(struct robust_list_head *>I<head>B<, size_t "
 733 ">I<len>B<);>\n"
 734 msgstr ""
 735
 736 #. type: Plain text
 737 #: build/C/man2/get_robust_list.2:44
 738 msgid "I<Note>: There are no glibc wrappers for these system calls; see NOTES."
 739 msgstr ""
 740
 741 #. type: Plain text
 742 #: build/C/man2/get_robust_list.2:49
 743 msgid ""
 744 "The robust futex implementation needs to maintain per-thread lists of robust "
 745 "futexes which are unlocked when the thread exits.  These lists are managed "
 746 "in user space; the kernel is notified about only the location of the head of "
 747 "the list."
 748 msgstr ""
 749
 750 #. type: Plain text
 751 #: build/C/man2/get_robust_list.2:65
 752 msgid ""
 753 "The B<get_robust_list>()  system call returns the head of the robust futex "
 754 "list of the thread whose thread ID is specified in I<pid>.  If I<pid> is 0, "
 755 "the head of the list for the calling thread is returned.  The list head is "
 756 "stored in the location pointed to by I<head_ptr>.  The size of the object "
 757 "pointed to by I<**head_ptr> is stored in I<len_ptr>."
 758 msgstr ""
 759
 760 #. type: Plain text
 761 #: build/C/man2/get_robust_list.2:77
 762 msgid ""
 763 "The B<set_robust_list>()  system call requests the kernel to record the head "
 764 "of the list of robust futexes owned by the calling thread.  The I<head> "
 765 "argument is the list head to record.  The I<len> argument should be "
 766 "I<sizeof(*head)>."
 767 msgstr ""
 768
 769 #. type: Plain text
 770 #: build/C/man2/get_robust_list.2:84
 771 msgid ""
 772 "The B<set_robust_list>()  and B<get_robust_list>()  system calls return zero "
 773 "when the operation is successful, an error code otherwise."
 774 msgstr ""
 775
 776 #. type: Plain text
 777 #: build/C/man2/get_robust_list.2:88
 778 msgid "The B<set_robust_list>()  system call can fail with the following error:"
 779 msgstr ""
 780
 781 #. type: Plain text
 782 #: build/C/man2/get_robust_list.2:94
 783 msgid ""
 784 "I<len> does not match the size of structure B<struct robust_list_head> "
 785 "expected by kernel."
 786 msgstr ""
 787
 788 #. type: Plain text
 789 #: build/C/man2/get_robust_list.2:98
 790 msgid "The B<get_robust_list>()  system call can fail with the following errors:"
 791 msgstr ""
 792
 793 #. type: Plain text
 794 #: build/C/man2/get_robust_list.2:106
 795 msgid ""
 796 "The calling process does not have permission to see the robust futex list of "
 797 "the thread with the thread ID I<pid>, and does not have the "
 798 "B<CAP_SYS_PTRACE> capability."
 799 msgstr ""
 800
 801 #. type: TP
 802 #: build/C/man2/get_robust_list.2:106 build/C/man2/perf_event_open.2:2508 build/C/man2/process_vm_readv.2:271 build/C/man2/ptrace.2:1906 build/C/man2/quotactl.2:461 build/C/man2/quotactl.2:504
 803 #, no-wrap
 804 msgid "B<ESRCH>"
 805 msgstr ""
 806
 807 #. type: Plain text
 808 #: build/C/man2/get_robust_list.2:111
 809 msgid "No thread with the thread ID I<pid> could be found."
 810 msgstr ""
 811
 812 #. type: Plain text
 813 #: build/C/man2/get_robust_list.2:115
 814 msgid "The head of the robust futex list can't be stored at the location I<head>."
 815 msgstr ""
 816
 817 #. type: Plain text
 818 #: build/C/man2/get_robust_list.2:119
 819 msgid ""
 820 "These system calls were added in Linux 2.6.17.  No library support is "
 821 "provided; use B<syscall>(2)."
 822 msgstr ""
 823
 824 #. type: Plain text
 825 #: build/C/man2/get_robust_list.2:124
 826 msgid ""
 827 "These system calls are not needed by normal applications.  No support for "
 828 "them is provided in glibc.  In the unlikely event that you want to call them "
 829 "directly, use B<syscall>(2)."
 830 msgstr ""
 831
 832 #. type: Plain text
 833 #: build/C/man2/get_robust_list.2:128
 834 msgid ""
 835 "A thread can have only one robust futex list; therefore applications that "
 836 "wish to use this functionality should use the robust mutexes provided by "
 837 "glibc."
 838 msgstr ""
 839
 840 #.  .BR pthread_mutexattr_setrobust_np (3)
 841 #. type: Plain text
 842 #: build/C/man2/get_robust_list.2:131
 843 msgid "B<futex>(2)"
 844 msgstr ""
 845
 846 #.  http://lwn.net/Articles/172149/
 847 #. type: Plain text
 848 #: build/C/man2/get_robust_list.2:137
 849 msgid ""
 850 "I<Documentation/robust-futexes.txt> and "
 851 "I<Documentation/robust-futex-ABI.txt> in the Linux kernel source tree"
 852 msgstr ""
 853
 854 #. type: TH
 855 #: build/C/man2/getunwind.2:27
 856 #, no-wrap
 857 msgid "GETUNWIND"
 858 msgstr ""
 859
 860 #. type: TH
 861 #: build/C/man2/getunwind.2:27 build/C/man2/perfmonctl.2:27
 862 #, no-wrap
 863 msgid "2013-02-13"
 864 msgstr ""
 865
 866 #. type: Plain text
 867 #: build/C/man2/getunwind.2:30
 868 msgid "getunwind - copy the unwind data to caller's buffer"
 869 msgstr ""
 870
 871 #. type: Plain text
 872 #: build/C/man2/getunwind.2:34
 873 #, no-wrap
 874 msgid ""
 875 "B<#include E<lt>syscall.hE<gt>>\n"
 876 "B<#include E<lt>linux/unwind.hE<gt>>\n"
 877 msgstr ""
 878
 879 #. type: Plain text
 880 #: build/C/man2/getunwind.2:36
 881 #, no-wrap
 882 msgid "B<long getunwind(void >I<*buf>B<, size_t >I<buf_size>B<);>\n"
 883 msgstr ""
 884
 885 #. type: Plain text
 886 #: 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
 887 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
 888 msgstr ""
 889
 890 #. type: Plain text
 891 #: build/C/man2/getunwind.2:42
 892 msgid "I<Note: this function is obsolete.>"
 893 msgstr ""
 894
 895 #. type: Plain text
 896 #: build/C/man2/getunwind.2:52
 897 msgid ""
 898 "The IA-64-specific B<getunwind>()  system call copies the kernel's call "
 899 "frame unwind data into the buffer pointed to by I<buf> and returns the size "
 900 "of the unwind data; this data describes the gate page (kernel code that is "
 901 "mapped into user space)."
 902 msgstr ""
 903
 904 #. type: Plain text
 905 #: build/C/man2/getunwind.2:64
 906 msgid ""
 907 "The size of the buffer I<buf> is specified in I<buf_size>.  The data is "
 908 "copied only if I<buf_size> is greater than or equal to the size of the "
 909 "unwind data and I<buf> is not NULL; otherwise, no data is copied, and the "
 910 "call succeeds, returning the size that would be needed to store the unwind "
 911 "data."
 912 msgstr ""
 913
 914 #. type: Plain text
 915 #: build/C/man2/getunwind.2:68
 916 msgid ""
 917 "The first part of the unwind data contains an unwind table.  The rest "
 918 "contains the associated unwind information, in no particular order.  The "
 919 "unwind table contains entries of the following form:"
 920 msgstr ""
 921
 922 #. type: Plain text
 923 #: build/C/man2/getunwind.2:73
 924 #, no-wrap
 925 msgid ""
 926 "    u64 start;      (64-bit address of start of function)\n"
 927 "    u64 end;        (64-bit address of end of function)\n"
 928 "    u64 info;       (BUF-relative offset to unwind info)\n"
 929 msgstr ""
 930
 931 #. type: Plain text
 932 #: build/C/man2/getunwind.2:81
 933 msgid ""
 934 "An entry whose I<start> value is zero indicates the end of the table.  For "
 935 "more information about the format, see the I<IA-64 Software Conventions and "
 936 "Runtime Architecture> manual."
 937 msgstr ""
 938
 939 #. type: Plain text
 940 #: build/C/man2/getunwind.2:88
 941 msgid ""
 942 "On success, B<getunwind>()  returns the size of unwind table.  On error, -1 "
 943 "is returned and I<errno> is set to indicate the error."
 944 msgstr ""
 945
 946 #. type: Plain text
 947 #: build/C/man2/getunwind.2:94
 948 msgid ""
 949 "B<getunwind>()  fails with the error B<EFAULT> if the unwind info can't be "
 950 "stored in the space specified by I<buf>."
 951 msgstr ""
 952
 953 #. type: Plain text
 954 #: build/C/man2/getunwind.2:96
 955 msgid "This system call is available since Linux 2.4."
 956 msgstr ""
 957
 958 #. type: Plain text
 959 #: build/C/man2/getunwind.2:99
 960 msgid ""
 961 "This system call is Linux-specific, and is available only on the IA-64 "
 962 "architecture."
 963 msgstr ""
 964
 965 #. type: Plain text
 966 #: build/C/man2/getunwind.2:107
 967 msgid ""
 968 "This system call has been deprecated.  The modern way to obtain the kernel's "
 969 "unwind data is via the gate DSO.  The address of the ELF header for this DSO "
 970 "is passed to user level via B<AT_SYSINFO_EHDR> (see B<getauxval>(3))."
 971 msgstr ""
 972
 973 #. type: Plain text
 974 #: build/C/man2/getunwind.2:111
 975 msgid ""
 976 "Glibc does not provide a wrapper for this system call; in the unlikely event "
 977 "that you want to call it, use B<syscall>(2)."
 978 msgstr ""
 979
 980 #. type: Plain text
 981 #: build/C/man2/getunwind.2:113
 982 msgid "B<getauxval>(3)"
 983 msgstr ""
 984
 985 #. type: TH
 986 #: build/C/man2/kexec_load.2:26
 987 #, no-wrap
 988 msgid "KEXEC_LOAD"
 989 msgstr ""
 990
 991 #. type: Plain text
 992 #: build/C/man2/kexec_load.2:29
 993 msgid "kexec_load - load a new kernel for later execution"
 994 msgstr ""
 995
 996 #. type: Plain text
 997 #: build/C/man2/kexec_load.2:31
 998 msgid "B<#include E<lt>linux/kexec.hE<gt>>"
 999 msgstr ""
1000
1001 #. type: Plain text
1002 #: build/C/man2/kexec_load.2:33
1003 msgid ""
1004 "B<long kexec_load(unsigned long >I<entry>B<, unsigned long "
1005 ">I<nr_segments>B<,>"
1006 msgstr ""
1007
1008 #. type: Plain text
1009 #: build/C/man2/kexec_load.2:36
1010 msgid "B< struct kexec_segment *>I<segments>B<, unsigned long >I<flags>B<);>"
1011 msgstr ""
1012
1013 #. type: Plain text
1014 #: build/C/man2/kexec_load.2:44
1015 msgid ""
1016 "The B<kexec_load>()  system call loads a new kernel that can be executed "
1017 "later by B<reboot>(2)."
1018 msgstr ""
1019
1020 #. type: Plain text
1021 #: build/C/man2/kexec_load.2:50
1022 msgid ""
1023 "The I<flags> argument is a mask whose high-order bits control the operation "
1024 "of the call.  The following values can be specified in I<flags>:"
1025 msgstr ""
1026
1027 #. type: TP
1028 #: build/C/man2/kexec_load.2:50
1029 #, no-wrap
1030 msgid "B<KEXEC_ON_CRASH> (since Linux 2.6.13)"
1031 msgstr ""
1032
1033 #.  FIXME figure out how this is really used
1034 #. type: Plain text
1035 #: build/C/man2/kexec_load.2:54
1036 msgid "Execute the new kernel automatically on a system crash."
1037 msgstr ""
1038
1039 #. type: TP
1040 #: build/C/man2/kexec_load.2:54
1041 #, no-wrap
1042 msgid "B<KEXEC_PRESERVE_CONTEXT> (since Linux 2.6.27)"
1043 msgstr ""
1044
1045 #. type: Plain text
1046 #: build/C/man2/kexec_load.2:64
1047 msgid ""
1048 "Preserve the system hardware and software states before executing the new "
1049 "kernel.  This could be used for system suspend.  This flag is available only "
1050 "if the kernel was configured with B<CONFIG_KEXEC_JUMP>, and is effective "
1051 "only if I<nr_segments> is greater than 0."
1052 msgstr ""
1053
1054 #. type: Plain text
1055 #: build/C/man2/kexec_load.2:84
1056 msgid ""
1057 "The low-order bits of I<flags> contain the architecture of the "
1058 "to-be-executed kernel.  Specify (OR) the constant B<KEXEC_ARCH_DEFAULT> to "
1059 "use the current architecture, or one of the following architecture constants "
1060 "B<KEXEC_ARCH_386>, B<KEXEC_ARCH_X86_64>, B<KEXEC_ARCH_PPC>, "
1061 "B<KEXEC_ARCH_PPC64>, B<KEXEC_ARCH_IA_64>, B<KEXEC_ARCH_ARM>, "
1062 "B<KEXEC_ARCH_S390>, B<KEXEC_ARCH_SH>, B<KEXEC_ARCH_MIPS>, and "
1063 "B<KEXEC_ARCH_MIPS_LE>.  The architecture must be executable on the CPU of "
1064 "the system."
1065 msgstr ""
1066
1067 #. type: Plain text
1068 #: build/C/man2/kexec_load.2:98
1069 msgid ""
1070 "The I<entry> argument is the physical entry address in the kernel image.  "
1071 "The I<nr_segments> argument is the number of segments pointed to by the "
1072 "I<segments> pointer.  The I<segments> argument is an array of "
1073 "I<kexec_segment> structures which define the kernel layout:"
1074 msgstr ""
1075
1076 #. type: Plain text
1077 #: build/C/man2/kexec_load.2:107
1078 #, no-wrap
1079 msgid ""
1080 "struct kexec_segment {\n"
1081 "    void   *buf;        /* Buffer in user space */\n"
1082 "    size_t  bufsz;      /* Buffer length in user space */\n"
1083 "    void   *mem;        /* Physical address of kernel */\n"
1084 "    size_t  memsz;      /* Physical address length */\n"
1085 "};\n"
1086 msgstr ""
1087
1088 #.  FIXME elaborate on the following:
1089 #. type: Plain text
1090 #: build/C/man2/kexec_load.2:114
1091 msgid ""
1092 "The kernel image defined by I<segments> is copied from the calling process "
1093 "into previously reserved memory."
1094 msgstr ""
1095
1096 #. type: Plain text
1097 #: build/C/man2/kexec_load.2:121
1098 msgid ""
1099 "On success, B<kexec_load>()  returns 0.  On error, -1 is returned and "
1100 "I<errno> is set to indicate the error."
1101 msgstr ""
1102
1103 #. type: TP
1104 #: build/C/man2/kexec_load.2:122 build/C/man2/pivot_root.2:110 build/C/man2/ptrace.2:1869 build/C/man2/quotactl.2:495
1105 #, no-wrap
1106 msgid "B<EBUSY>"
1107 msgstr ""
1108
1109 #. type: Plain text
1110 #: build/C/man2/kexec_load.2:126
1111 msgid ""
1112 "Another crash kernel is already being loaded or a crash kernel is already in "
1113 "use."
1114 msgstr ""
1115
1116 #.  KEXEC_SEGMENT_MAX == 16
1117 #. type: Plain text
1118 #: build/C/man2/kexec_load.2:133
1119 msgid "I<flags> is invalid; or I<nr_segments> is too large"
1120 msgstr ""
1121
1122 #. type: Plain text
1123 #: build/C/man2/kexec_load.2:138
1124 msgid "The caller does not have the B<CAP_SYS_BOOT> capability."
1125 msgstr ""
1126
1127 #. type: Plain text
1128 #: build/C/man2/kexec_load.2:142
1129 msgid "The B<kexec_load>()  system call first appeared in Linux 2.6.13."
1130 msgstr ""
1131
1132 #. type: Plain text
1133 #: build/C/man2/kexec_load.2:149
1134 msgid ""
1135 "Currently, there is no glibc support for B<kexec_load>().  Call it using "
1136 "B<syscall>(2)."
1137 msgstr ""
1138
1139 #.  FIXME Andi submitted a patch for this.
1140 #.  Check if it got accepted later.
1141 #. type: Plain text
1142 #: build/C/man2/kexec_load.2:156
1143 msgid ""
1144 "The required constants are in the Linux kernel source file I<linux/kexec.h>, "
1145 "which is not currently exported to glibc.  Therefore, these constants must "
1146 "be defined manually."
1147 msgstr ""
1148
1149 #. type: Plain text
1150 #: build/C/man2/kexec_load.2:159
1151 msgid ""
1152 "This system call is available only if the kernel was configured with "
1153 "B<CONFIG_KEXEC>."
1154 msgstr ""
1155
1156 #. type: Plain text
1157 #: build/C/man2/kexec_load.2:162
1158 msgid "B<reboot>(2), B<syscall>(2)"
1159 msgstr ""
1160
1161 #. type: TH
1162 #: build/C/man2/lookup_dcookie.2:27
1163 #, no-wrap
1164 msgid "LOOKUP_DCOOKIE"
1165 msgstr ""
1166
1167 #. type: TH
1168 #: build/C/man2/lookup_dcookie.2:27
1169 #, no-wrap
1170 msgid "2004-06-17"
1171 msgstr ""
1172
1173 #. type: Plain text
1174 #: build/C/man2/lookup_dcookie.2:30
1175 msgid "lookup_dcookie - return a directory entry's path"
1176 msgstr ""
1177
1178 #. type: Plain text
1179 #: build/C/man2/lookup_dcookie.2:32
1180 msgid ""
1181 "B<int lookup_dcookie(u64 >I<cookie>B<, char *>I<buffer>B<, size_t "
1182 ">I<len>B<);>"
1183 msgstr ""
1184
1185 #. type: Plain text
1186 #: build/C/man2/lookup_dcookie.2:38
1187 msgid ""
1188 "Look up the full path of the directory entry specified by the value "
1189 "I<cookie>.  The cookie is an opaque identifier uniquely identifying a "
1190 "particular directory entry.  The buffer given is filled in with the full "
1191 "path of the directory entry."
1192 msgstr ""
1193
1194 #. type: Plain text
1195 #: build/C/man2/lookup_dcookie.2:43
1196 msgid ""
1197 "For B<lookup_dcookie>()  to return successfully, the kernel must still hold "
1198 "a cookie reference to the directory entry."
1199 msgstr ""
1200
1201 #. type: Plain text
1202 #: build/C/man2/lookup_dcookie.2:50
1203 msgid ""
1204 "On success, B<lookup_dcookie>()  returns the length of the path string "
1205 "copied into the buffer.  On error, -1 is returned, and I<errno> is set "
1206 "appropriately."
1207 msgstr ""
1208
1209 #. type: Plain text
1210 #: build/C/man2/lookup_dcookie.2:54
1211 msgid "The buffer was not valid."
1212 msgstr ""
1213
1214 #. type: Plain text
1215 #: build/C/man2/lookup_dcookie.2:58
1216 msgid ""
1217 "The kernel has no registered cookie/directory entry mappings at the time of "
1218 "lookup, or the cookie does not refer to a valid directory entry."
1219 msgstr ""
1220
1221 #. type: TP
1222 #: build/C/man2/lookup_dcookie.2:58
1223 #, no-wrap
1224 msgid "B<ENAMETOOLONG>"
1225 msgstr ""
1226
1227 #. type: Plain text
1228 #: build/C/man2/lookup_dcookie.2:61
1229 msgid "The name could not fit in the buffer."
1230 msgstr ""
1231
1232 #. type: TP
1233 #: 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
1234 #, no-wrap
1235 msgid "B<ENOMEM>"
1236 msgstr ""
1237
1238 #. type: Plain text
1239 #: build/C/man2/lookup_dcookie.2:65
1240 msgid ""
1241 "The kernel could not allocate memory for the temporary buffer holding the "
1242 "path."
1243 msgstr ""
1244
1245 #. type: Plain text
1246 #: build/C/man2/lookup_dcookie.2:70
1247 msgid ""
1248 "The process does not have the capability B<CAP_SYS_ADMIN> required to look "
1249 "up cookie values."
1250 msgstr ""
1251
1252 #. type: TP
1253 #: build/C/man2/lookup_dcookie.2:70 build/C/man2/quotactl.2:474
1254 #, no-wrap
1255 msgid "B<ERANGE>"
1256 msgstr ""
1257
1258 #. type: Plain text
1259 #: build/C/man2/lookup_dcookie.2:73
1260 msgid "The buffer was not large enough to hold the path of the directory entry."
1261 msgstr ""
1262
1263 #. type: Plain text
1264 #: build/C/man2/lookup_dcookie.2:78
1265 msgid ""
1266 "Available since Linux 2.5.43.  The B<ENAMETOOLONG> error return was added in "
1267 "2.5.70."
1268 msgstr ""
1269
1270 #. type: Plain text
1271 #: build/C/man2/lookup_dcookie.2:81
1272 msgid "B<lookup_dcookie>()  is Linux-specific."
1273 msgstr ""
1274
1275 #. type: Plain text
1276 #: build/C/man2/lookup_dcookie.2:85
1277 msgid ""
1278 "B<lookup_dcookie>()  is a special-purpose system call, currently used only "
1279 "by the oprofile profiler.  It relies on a kernel driver to register cookies "
1280 "for directory entries."
1281 msgstr ""
1282
1283 #. type: Plain text
1284 #: build/C/man2/lookup_dcookie.2:88
1285 msgid ""
1286 "The path returned may be suffixed by the string \" (deleted)\" if the "
1287 "directory entry has been removed."
1288 msgstr ""
1289
1290 #. type: TH
1291 #: build/C/man2/modify_ldt.2:24
1292 #, no-wrap
1293 msgid "MODIFY_LDT"
1294 msgstr ""
1295
1296 #. type: Plain text
1297 #: build/C/man2/modify_ldt.2:27
1298 msgid "modify_ldt - get or set ldt"
1299 msgstr ""
1300
1301 #. type: Plain text
1302 #: build/C/man2/modify_ldt.2:30
1303 #, no-wrap
1304 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
1305 msgstr ""
1306
1307 #. type: Plain text
1308 #: build/C/man2/modify_ldt.2:32
1309 #, no-wrap
1310 msgid ""
1311 "B<int modify_ldt(int >I<func>B<, void *>I<ptr>B<, unsigned long "
1312 ">I<bytecount>B<);>\n"
1313 msgstr ""
1314
1315 #. type: Plain text
1316 #: build/C/man2/modify_ldt.2:41
1317 msgid ""
1318 "B<modify_ldt>()  reads or writes the local descriptor table (ldt) for a "
1319 "process.  The ldt is a per-process memory management table used by the i386 "
1320 "processor.  For more information on this table, see an Intel 386 processor "
1321 "handbook."
1322 msgstr ""
1323
1324 #. type: Plain text
1325 #: build/C/man2/modify_ldt.2:51
1326 msgid ""
1327 "When I<func> is 0, B<modify_ldt>()  reads the ldt into the memory pointed to "
1328 "by I<ptr>.  The number of bytes read is the smaller of I<bytecount> and the "
1329 "actual size of the ldt."
1330 msgstr ""
1331
1332 #
1333 #.  FIXME ? say something about func == 2 and func == 0x11?
1334 #.  In Linux 2.4, func == 2 returned "the default ldt"
1335 #.  In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
1336 #.  Linux 2.4 and 2.6 implement an operation for func == 0x11
1337 #. type: Plain text
1338 #: build/C/man2/modify_ldt.2:69
1339 msgid ""
1340 "When I<func> is 1, B<modify_ldt>()  modifies one ldt entry.  I<ptr> points "
1341 "to a I<user_desc> structure and I<bytecount> must equal the size of this "
1342 "structure."
1343 msgstr ""
1344
1345 #. type: Plain text
1346 #: build/C/man2/modify_ldt.2:73
1347 msgid "The I<user_desc> structure is defined in I<E<lt>asm/ldt.hE<gt>> as:"
1348 msgstr ""
1349
1350 #. type: Plain text
1351 #: build/C/man2/modify_ldt.2:87
1352 #, no-wrap
1353 msgid ""
1354 "struct user_desc {\n"
1355 "    unsigned int  entry_number;\n"
1356 "    unsigned long base_addr;\n"
1357 "    unsigned int  limit;\n"
1358 "    unsigned int  seg_32bit:1;\n"
1359 "    unsigned int  contents:2;\n"
1360 "    unsigned int  read_exec_only:1;\n"
1361 "    unsigned int  limit_in_pages:1;\n"
1362 "    unsigned int  seg_not_present:1;\n"
1363 "    unsigned int  useable:1;\n"
1364 "};\n"
1365 msgstr ""
1366
1367 #.  .PP
1368 #.  The ldt is specific for the calling process. Any attempts to change
1369 #.  the ldt to include the address space of another process or the kernel
1370 #.  will result in a segmentation violation when trying to access the memory
1371 #.  outside of the process address space. The memory protection is enforced
1372 #.  at the paging layer.
1373 #. type: Plain text
1374 #: build/C/man2/modify_ldt.2:98
1375 msgid "In Linux 2.4 and earlier, this structure was named I<modify_ldt_ldt_s>."
1376 msgstr ""
1377
1378 #. type: Plain text
1379 #: build/C/man2/modify_ldt.2:108
1380 msgid ""
1381 "On success, B<modify_ldt>()  returns either the actual number of bytes read "
1382 "(for reading)  or 0 (for writing).  On failure, B<modify_ldt>()  returns -1 "
1383 "and sets I<errno> to indicate the error."
1384 msgstr ""
1385
1386 #. type: Plain text
1387 #: build/C/man2/modify_ldt.2:113
1388 msgid "I<ptr> points outside the address space."
1389 msgstr ""
1390
1391 #. type: Plain text
1392 #: build/C/man2/modify_ldt.2:126
1393 msgid ""
1394 "I<ptr> is 0, or I<func> is 1 and I<bytecount> is not equal to the size of "
1395 "the structure I<modify_ldt_ldt_s>, or I<func> is 1 and the new ldt entry has "
1396 "invalid values."
1397 msgstr ""
1398
1399 #. type: Plain text
1400 #: build/C/man2/modify_ldt.2:130
1401 msgid "I<func> is neither 0 nor 1."
1402 msgstr ""
1403
1404 #. type: Plain text
1405 #: build/C/man2/modify_ldt.2:133
1406 msgid ""
1407 "This call is Linux-specific and should not be used in programs intended to "
1408 "be portable."
1409 msgstr ""
1410
1411 #. type: Plain text
1412 #: build/C/man2/modify_ldt.2:136 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:134
1413 msgid ""
1414 "Glibc does not provide a wrapper for this system call; call it using "
1415 "B<syscall>(2)."
1416 msgstr ""
1417
1418 #. type: Plain text
1419 #: build/C/man2/modify_ldt.2:138
1420 msgid "B<vm86>(2)"
1421 msgstr ""
1422
1423 #. type: TH
1424 #: build/C/man2/nfsservctl.2:8
1425 #, no-wrap
1426 msgid "NFSSERVCTL"
1427 msgstr ""
1428
1429 #. type: TH
1430 #: build/C/man2/nfsservctl.2:8
1431 #, no-wrap
1432 msgid "2013-09-17"
1433 msgstr ""
1434
1435 #. type: Plain text
1436 #: build/C/man2/nfsservctl.2:11
1437 msgid "nfsservctl - syscall interface to kernel nfs daemon"
1438 msgstr ""
1439
1440 #. type: Plain text
1441 #: build/C/man2/nfsservctl.2:14
1442 #, no-wrap
1443 msgid "B<#include E<lt>linux/nfsd/syscall.hE<gt>>\n"
1444 msgstr ""
1445
1446 #. type: Plain text
1447 #: build/C/man2/nfsservctl.2:17
1448 #, no-wrap
1449 msgid ""
1450 "B<long nfsservctl(int >I<cmd>B<, struct nfsctl_arg *>I<argp>B<,>\n"
1451 "B<                union nfsctl_res *>I<resp>B<);>\n"
1452 msgstr ""
1453
1454 #. type: Plain text
1455 #: build/C/man2/nfsservctl.2:21
1456 msgid "I<Note>: Since Linux 3.1, this system call no longer exists."
1457 msgstr ""
1458
1459 #. type: Plain text
1460 #: build/C/man2/nfsservctl.2:35
1461 #, no-wrap
1462 msgid ""
1463 "/*\n"
1464 " * These are the commands understood by nfsctl().\n"
1465 " */\n"
1466 "#define NFSCTL_SVC          0    /* This is a server process. */\n"
1467 "#define NFSCTL_ADDCLIENT    1    /* Add an NFS client. */\n"
1468 "#define NFSCTL_DELCLIENT    2    /* Remove an NFS client. */\n"
1469 "#define NFSCTL_EXPORT       3    /* Export a filesystem. */\n"
1470 "#define NFSCTL_UNEXPORT     4    /* Unexport a filesystem. */\n"
1471 "#define NFSCTL_UGIDUPDATE   5    /* Update a client's UID/GID map\n"
1472 "                                    (only in Linux 2.4.x and earlier). */\n"
1473 "#define NFSCTL_GETFH        6    /* Get a file handle (used by mountd)\n"
1474 "                                    (only in Linux 2.4.x and earlier). */\n"
1475 msgstr ""
1476
1477 #. type: Plain text
1478 #: build/C/man2/nfsservctl.2:47
1479 #, no-wrap
1480 msgid ""
1481 "struct nfsctl_arg {\n"
1482 "    int                       ca_version;     /* safeguard */\n"
1483 "    union {\n"
1484 "        struct nfsctl_svc     u_svc;\n"
1485 "        struct nfsctl_client  u_client;\n"
1486 "        struct nfsctl_export  u_export;\n"
1487 "        struct nfsctl_uidmap  u_umap;\n"
1488 "        struct nfsctl_fhparm  u_getfh;\n"
1489 "        unsigned int          u_debug;\n"
1490 "    } u;\n"
1491 "}\n"
1492 msgstr ""
1493
1494 #. type: Plain text
1495 #: build/C/man2/nfsservctl.2:52
1496 #, no-wrap
1497 msgid ""
1498 "union nfsctl_res {\n"
1499 "        struct knfs_fh          cr_getfh;\n"
1500 "        unsigned int            cr_debug;\n"
1501 "};\n"
1502 msgstr ""
1503
1504 #. type: Plain text
1505 #: build/C/man2/nfsservctl.2:58 build/C/man2/pivot_root.2:105 build/C/man2/vm86.2:59
1506 msgid ""
1507 "On success, zero is returned.  On error, -1 is returned, and I<errno> is set "
1508 "appropriately."
1509 msgstr ""
1510
1511 #. type: Plain text
1512 #: build/C/man2/nfsservctl.2:60
1513 msgid "This call is Linux-specific."
1514 msgstr ""
1515
1516 #. type: TH
1517 #: build/C/man2/outb.2:26
1518 #, no-wrap
1519 msgid "OUTB"
1520 msgstr ""
1521
1522 #. type: TH
1523 #: build/C/man2/outb.2:26
1524 #, no-wrap
1525 msgid "2012-12-31"
1526 msgstr ""
1527
1528 #. type: Plain text
1529 #: build/C/man2/outb.2:31
1530 msgid ""
1531 "outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, "
1532 "outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O"
1533 msgstr ""
1534
1535 #. type: Plain text
1536 #: build/C/man2/outb.2:34
1537 #, no-wrap
1538 msgid "B<#include E<lt>sys/io.hE<gt>>\n"
1539 msgstr ""
1540
1541 #. type: Plain text
1542 #: build/C/man2/outb.2:41
1543 #, no-wrap
1544 msgid ""
1545 "B<unsigned char inb(unsigned short int >I<port>B<);>\n"
1546 "B<unsigned char inb_p(unsigned short int >I<port>B<);>\n"
1547 "B<unsigned short int inw(unsigned short int >I<port>B<);>\n"
1548 "B<unsigned short int inw_p(unsigned short int >I<port>B<);>\n"
1549 "B<unsigned int inl(unsigned short int >I<port>B<);>\n"
1550 "B<unsigned int inl_p(unsigned short int >I<port>B<);>\n"
1551 msgstr ""
1552
1553 #. type: Plain text
1554 #: build/C/man2/outb.2:48
1555 #, no-wrap
1556 msgid ""
1557 "B<void outb(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1558 "B<void outb_p(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1559 "B<void outw(unsigned short int >I<value>B<, unsigned short int "
1560 ">I<port>B<);>\n"
1561 "B<void outw_p(unsigned short int >I<value>B<, unsigned short int "
1562 ">I<port>B<);>\n"
1563 "B<void outl(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1564 "B<void outl_p(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1565 msgstr ""
1566
1567 #. type: Plain text
1568 #: build/C/man2/outb.2:61
1569 #, no-wrap
1570 msgid ""
1571 "B<void insb(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1572 "B<           unsigned long int >I<count>B<);>\n"
1573 "B<void insw(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1574 "B<           unsigned long int >I<count>B<);>\n"
1575 "B<void insl(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1576 "B<           unsigned long int >I<count>B<);>\n"
1577 "B<void outsb(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1578 "B<           unsigned long int >I<count>B<);>\n"
1579 "B<void outsw(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1580 "B<           unsigned long int >I<count>B<);>\n"
1581 "B<void outsl(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1582 "B<           unsigned long int >I<count>B<);>\n"
1583 msgstr ""
1584
1585 #. type: Plain text
1586 #: build/C/man2/outb.2:67
1587 msgid ""
1588 "This family of functions is used to do low-level port input and output.  The "
1589 "out* functions do port output, the in* functions do port input; the b-suffix "
1590 "functions are byte-width and the w-suffix functions word-width; the "
1591 "_p-suffix functions pause until the I/O completes."
1592 msgstr ""
1593
1594 #.  , given the following information
1595 #.  in addition to that given in
1596 #.  .BR outb (9).
1597 #. type: Plain text
1598 #: build/C/man2/outb.2:73
1599 msgid ""
1600 "They are primarily designed for internal kernel use, but can be used from "
1601 "user space."
1602 msgstr ""
1603
1604 #. type: Plain text
1605 #: build/C/man2/outb.2:78
1606 msgid ""
1607 "You must compile with B<-O> or B<-O2> or similar.  The functions are defined "
1608 "as inline macros, and will not be substituted in without optimization "
1609 "enabled, causing unresolved references at link time."
1610 msgstr ""
1611
1612 #. type: Plain text
1613 #: build/C/man2/outb.2:87
1614 msgid ""
1615 "You use B<ioperm>(2)  or alternatively B<iopl>(2)  to tell the kernel to "
1616 "allow the user space application to access the I/O ports in question.  "
1617 "Failure to do this will cause the application to receive a segmentation "
1618 "fault."
1619 msgstr ""
1620
1621 #. type: Plain text
1622 #: build/C/man2/outb.2:96
1623 msgid ""
1624 "B<outb>()  and friends are hardware-specific.  The I<value> argument is "
1625 "passed first and the I<port> argument is passed second, which is the "
1626 "opposite order from most DOS implementations."
1627 msgstr ""
1628
1629 #. type: Plain text
1630 #: build/C/man2/outb.2:99
1631 msgid "B<ioperm>(2), B<iopl>(2)"
1632 msgstr ""
1633
1634 #. type: TH
1635 #: build/C/man2/pciconfig_read.2:8
1636 #, no-wrap
1637 msgid "PCICONFIG_READ"
1638 msgstr ""
1639
1640 #. type: TH
1641 #: build/C/man2/pciconfig_read.2:8
1642 #, no-wrap
1643 msgid "2003-07-14"
1644 msgstr ""
1645
1646 #. type: Plain text
1647 #: build/C/man2/pciconfig_read.2:11
1648 msgid ""
1649 "pciconfig_read, pciconfig_write, pciconfig_iobase - pci device information "
1650 "handling"
1651 msgstr ""
1652
1653 #. type: Plain text
1654 #: build/C/man2/pciconfig_read.2:14
1655 #, no-wrap
1656 msgid "B<#include E<lt>pci.hE<gt>>\n"
1657 msgstr ""
1658
1659 #. type: Plain text
1660 #: build/C/man2/pciconfig_read.2:21
1661 #, no-wrap
1662 msgid ""
1663 "B<int pciconfig_read(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1664 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1665 "*>I<buf>B<);>\n"
1666 "B<int pciconfig_write(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1667 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1668 "*>I<buf>B<);>\n"
1669 "B<int pciconfig_iobase(long >I<which>B<, unsigned long >I<bus>B<,>\n"
1670 "B<          unsigned long >I<devfn>B<);>\n"
1671 msgstr ""
1672
1673 #. type: Plain text
1674 #: build/C/man2/pciconfig_read.2:27
1675 msgid ""
1676 "Most of the interaction with PCI devices is already handled by the kernel "
1677 "PCI layer, and thus these calls should not normally need to be accessed from "
1678 "user space."
1679 msgstr ""
1680
1681 #. type: TP
1682 #: build/C/man2/pciconfig_read.2:27 build/C/man2/pciconfig_read.2:51
1683 #, no-wrap
1684 msgid "B<pciconfig_read>()"
1685 msgstr ""
1686
1687 #. type: Plain text
1688 #: build/C/man2/pciconfig_read.2:36
1689 msgid "Reads to I<buf> from device I<dev> at offset I<off> value."
1690 msgstr ""
1691
1692 #. type: TP
1693 #: build/C/man2/pciconfig_read.2:36 build/C/man2/pciconfig_read.2:57
1694 #, no-wrap
1695 msgid "B<pciconfig_write>()"
1696 msgstr ""
1697
1698 #. type: Plain text
1699 #: build/C/man2/pciconfig_read.2:45
1700 msgid "Writes from I<buf> to device I<dev> at offset I<off> value."
1701 msgstr ""
1702
1703 #. type: TP
1704 #: build/C/man2/pciconfig_read.2:45 build/C/man2/pciconfig_read.2:63
1705 #, no-wrap
1706 msgid "B<pciconfig_iobase>()"
1707 msgstr ""
1708
1709 #. type: Plain text
1710 #: build/C/man2/pciconfig_read.2:50
1711 msgid ""
1712 "You pass it a bus/devfn pair and get a physical address for either the "
1713 "memory offset (for things like prep, this is 0xc0000000), the IO base for "
1714 "PIO cycles, or the ISA holes if any."
1715 msgstr ""
1716
1717 #. type: Plain text
1718 #: build/C/man2/pciconfig_read.2:57 build/C/man2/pciconfig_read.2:63
1719 msgid ""
1720 "On success zero is returned.  On error, -1 is returned and I<errno> is set "
1721 "appropriately."
1722 msgstr ""
1723
1724 #. type: Plain text
1725 #: build/C/man2/pciconfig_read.2:77
1726 msgid ""
1727 "Returns information on locations of various I/O regions in physical memory "
1728 "according to the I<which> value.  Values for I<which> are: "
1729 "B<IOBASE_BRIDGE_NUMBER>, B<IOBASE_MEMORY>, B<IOBASE_IO>, B<IOBASE_ISA_IO>, "
1730 "B<IOBASE_ISA_MEM>."
1731 msgstr ""
1732
1733 #. type: Plain text
1734 #: build/C/man2/pciconfig_read.2:84
1735 msgid "I<len> value is invalid.  This does not apply to B<pciconfig_iobase>()."
1736 msgstr ""
1737
1738 #. type: TP
1739 #: build/C/man2/pciconfig_read.2:84 build/C/man2/ptrace.2:1886 build/C/man2/sendfile.2:134
1740 #, no-wrap
1741 msgid "B<EIO>"
1742 msgstr ""
1743
1744 #. type: Plain text
1745 #: build/C/man2/pciconfig_read.2:87
1746 msgid "I/O error."
1747 msgstr ""
1748
1749 #. type: TP
1750 #: build/C/man2/pciconfig_read.2:87 build/C/man2/perf_event_open.2:2460
1751 #, no-wrap
1752 msgid "B<ENODEV>"
1753 msgstr ""
1754
1755 #. type: Plain text
1756 #: build/C/man2/pciconfig_read.2:93
1757 msgid ""
1758 "For B<pciconfig_iobase>(), \"hose\" value is NULL.  For the other calls, "
1759 "could not find a slot."
1760 msgstr ""
1761
1762 #. type: Plain text
1763 #: build/C/man2/pciconfig_read.2:98
1764 msgid "The system has not implemented these calls (B<CONFIG_PCI> not defined)."
1765 msgstr ""
1766
1767 #. type: TP
1768 #: build/C/man2/pciconfig_read.2:98 build/C/man2/perf_event_open.2:2488
1769 #, no-wrap
1770 msgid "B<EOPNOTSUPP>"
1771 msgstr ""
1772
1773 #. type: Plain text
1774 #: build/C/man2/pciconfig_read.2:105
1775 msgid ""
1776 "This return value is valid only for B<pciconfig_iobase>().  It is returned "
1777 "if the value for I<which> is invalid."
1778 msgstr ""
1779
1780 #. type: Plain text
1781 #: build/C/man2/pciconfig_read.2:112
1782 msgid ""
1783 "User does not have the B<CAP_SYS_ADMIN> capability.  This does not apply to "
1784 "B<pciconfig_iobase>()."
1785 msgstr ""
1786
1787 #. type: Plain text
1788 #: build/C/man2/pciconfig_read.2:114
1789 msgid "These calls are Linux-specific, available since Linux 2.0.26/2.1.11."
1790 msgstr ""
1791
1792 #. type: Plain text
1793 #: build/C/man2/pciconfig_read.2:116
1794 msgid "B<capabilities>(7)"
1795 msgstr ""
1796
1797 #. type: TH
1798 #: build/C/man2/perf_event_open.2:27
1799 #, no-wrap
1800 msgid "PERF_EVENT_OPEN"
1801 msgstr ""
1802
1803 #. type: TH
1804 #: build/C/man2/perf_event_open.2:27
1805 #, no-wrap
1806 msgid "2014-04-17"
1807 msgstr ""
1808
1809 #. type: Plain text
1810 #: build/C/man2/perf_event_open.2:30
1811 msgid "perf_event_open - set up performance monitoring"
1812 msgstr ""
1813
1814 #. type: Plain text
1815 #: build/C/man2/perf_event_open.2:34
1816 #, no-wrap
1817 msgid ""
1818 "B<#include E<lt>linux/perf_event.hE<gt>>\n"
1819 "B<#include E<lt>linux/hw_breakpoint.hE<gt>>\n"
1820 msgstr ""
1821
1822 #. type: Plain text
1823 #: build/C/man2/perf_event_open.2:38
1824 #, no-wrap
1825 msgid ""
1826 "B<int perf_event_open(struct perf_event_attr *>I<attr>B<,>\n"
1827 "B<                    pid_t >I<pid>B<, int >I<cpu>B<, int >I<group_fd>B<,>\n"
1828 "B<                    unsigned long >I<flags>B<);>\n"
1829 msgstr ""
1830
1831 #. type: Plain text
1832 #: build/C/man2/perf_event_open.2:47
1833 msgid ""
1834 "Given a list of parameters, B<perf_event_open>()  returns a file descriptor, "
1835 "for use in subsequent system calls (B<read>(2), B<mmap>(2), B<prctl>(2), "
1836 "B<fcntl>(2), etc.)."
1837 msgstr ""
1838
1839 #. type: Plain text
1840 #: build/C/man2/perf_event_open.2:55
1841 msgid ""
1842 "A call to B<perf_event_open>()  creates a file descriptor that allows "
1843 "measuring performance information.  Each file descriptor corresponds to one "
1844 "event that is measured; these can be grouped together to measure multiple "
1845 "events simultaneously."
1846 msgstr ""
1847
1848 #. type: Plain text
1849 #: build/C/man2/perf_event_open.2:62
1850 msgid ""
1851 "Events can be enabled and disabled in two ways: via B<ioctl>(2)  and via "
1852 "B<prctl>(2).  When an event is disabled it does not count or generate "
1853 "overflows but does continue to exist and maintain its count value."
1854 msgstr ""
1855
1856 #. type: Plain text
1857 #: build/C/man2/perf_event_open.2:76
1858 msgid ""
1859 "Events come in two flavors: counting and sampled.  A I<counting> event is "
1860 "one that is used for counting the aggregate number of events that occur.  In "
1861 "general, counting event results are gathered with a B<read>(2)  call.  A "
1862 "I<sampling> event periodically writes measurements to a buffer that can then "
1863 "be accessed via B<mmap>(2)."
1864 msgstr ""
1865
1866 #. type: SS
1867 #: build/C/man2/perf_event_open.2:76
1868 #, no-wrap
1869 msgid "Arguments"
1870 msgstr ""
1871
1872 #. type: Plain text
1873 #: build/C/man2/perf_event_open.2:83
1874 msgid ""
1875 "The I<pid> and I<cpu> arguments allow specifying which process and CPU to "
1876 "monitor:"
1877 msgstr ""
1878
1879 #. type: TP
1880 #: build/C/man2/perf_event_open.2:83
1881 #, no-wrap
1882 msgid "B<pid == 0> and B<cpu == -1>"
1883 msgstr ""
1884
1885 #. type: Plain text
1886 #: build/C/man2/perf_event_open.2:86
1887 msgid "This measures the calling process/thread on any CPU."
1888 msgstr ""
1889
1890 #. type: TP
1891 #: build/C/man2/perf_event_open.2:86
1892 #, no-wrap
1893 msgid "B<pid == 0> and B<cpu E<gt>= 0>"
1894 msgstr ""
1895
1896 #. type: Plain text
1897 #: build/C/man2/perf_event_open.2:90
1898 msgid ""
1899 "This measures the calling process/thread only when running on the specified "
1900 "CPU."
1901 msgstr ""
1902
1903 #. type: TP
1904 #: build/C/man2/perf_event_open.2:90
1905 #, no-wrap
1906 msgid "B<pid E<gt> 0> and B<cpu == -1>"
1907 msgstr ""
1908
1909 #. type: Plain text
1910 #: build/C/man2/perf_event_open.2:93
1911 msgid "This measures the specified process/thread on any CPU."
1912 msgstr ""
1913
1914 #. type: TP
1915 #: build/C/man2/perf_event_open.2:93
1916 #, no-wrap
1917 msgid "B<pid E<gt> 0> and B<cpu E<gt>= 0>"
1918 msgstr ""
1919
1920 #. type: Plain text
1921 #: build/C/man2/perf_event_open.2:97
1922 msgid ""
1923 "This measures the specified process/thread only when running on the "
1924 "specified CPU."
1925 msgstr ""
1926
1927 #. type: TP
1928 #: build/C/man2/perf_event_open.2:97
1929 #, no-wrap
1930 msgid "B<pid == -1> and B<cpu E<gt>= 0>"
1931 msgstr ""
1932
1933 #. type: Plain text
1934 #: build/C/man2/perf_event_open.2:105
1935 msgid ""
1936 "This measures all processes/threads on the specified CPU.  This requires "
1937 "B<CAP_SYS_ADMIN> capability or a I</proc/sys/kernel/perf_event_paranoid> "
1938 "value of less than 1."
1939 msgstr ""
1940
1941 #. type: TP
1942 #: build/C/man2/perf_event_open.2:105
1943 #, no-wrap
1944 msgid "B<pid == -1> and B<cpu == -1>"
1945 msgstr ""
1946
1947 #. type: Plain text
1948 #: build/C/man2/perf_event_open.2:108
1949 msgid "This setting is invalid and will return an error."
1950 msgstr ""
1951
1952 #. type: Plain text
1953 #: build/C/man2/perf_event_open.2:130
1954 msgid ""
1955 "The I<group_fd> argument allows event groups to be created.  An event group "
1956 "has one event which is the group leader.  The leader is created first, with "
1957 "I<group_fd> = -1.  The rest of the group members are created with subsequent "
1958 "B<perf_event_open>()  calls with I<group_fd> being set to the file "
1959 "descriptor of the group leader.  (A single event on its own is created with "
1960 "I<group_fd> = -1 and is considered to be a group with only 1 member.)  An "
1961 "event group is scheduled onto the CPU as a unit: it will be put onto the CPU "
1962 "only if all of the events in the group can be put onto the CPU.  This means "
1963 "that the values of the member events can be meaningfully compared\\(emadded, "
1964 "divided (to get ratios), and so on\\(emwith each other, since they have "
1965 "counted events for the same set of executed instructions."
1966 msgstr ""
1967
1968 #. type: Plain text
1969 #: build/C/man2/perf_event_open.2:134
1970 msgid ""
1971 "The I<flags> argument is formed by ORing together zero or more of the "
1972 "following values:"
1973 msgstr ""
1974
1975 #. type: TP
1976 #: build/C/man2/perf_event_open.2:134
1977 #, no-wrap
1978 msgid "B<PERF_FLAG_FD_CLOEXEC> (since Linux 3.14)."
1979 msgstr ""
1980
1981 #. type: Plain text
1982 #: build/C/man2/perf_event_open.2:150
1983 msgid ""
1984 "This flag enables the close-on-exec flag for the created event file "
1985 "descriptor, so that the file descriptor is automatically closed on "
1986 "B<execve>(2).  Setting the close-on-exec flags at creation time, rather than "
1987 "later with B<fcntl>(2), avoids potential race conditions where the calling "
1988 "thread invokes B<perf_event_open>()  and B<fcntl>(2)  at the same time as "
1989 "another thread calls B<fork>(2)  then B<execve>(2)."
1990 msgstr ""
1991
1992 #. type: TP
1993 #: build/C/man2/perf_event_open.2:150
1994 #, no-wrap
1995 msgid "B<PERF_FLAG_FD_NO_GROUP>"
1996 msgstr ""
1997
1998 #.  FIXME The following sentence is unclear
1999 #.  FIXME So, why is it useful?
2000 #. type: Plain text
2001 #: build/C/man2/perf_event_open.2:157
2002 msgid ""
2003 "This flag allows creating an event as part of an event group but having no "
2004 "group leader.  It is unclear why this is useful."
2005 msgstr ""
2006
2007 #. type: TP
2008 #: build/C/man2/perf_event_open.2:157
2009 #, no-wrap
2010 msgid "B<PERF_FLAG_FD_OUTPUT>"
2011 msgstr ""
2012
2013 #. type: Plain text
2014 #: build/C/man2/perf_event_open.2:160
2015 msgid "This flag reroutes the output from an event to the group leader."
2016 msgstr ""
2017
2018 #. type: TP
2019 #: build/C/man2/perf_event_open.2:160
2020 #, no-wrap
2021 msgid "B<PERF_FLAG_PID_CGROUP> (since Linux 2.6.39)."
2022 msgstr ""
2023
2024 #. type: Plain text
2025 #: build/C/man2/perf_event_open.2:183
2026 msgid ""
2027 "This flag activates per-container system-wide monitoring.  A container is an "
2028 "abstraction that isolates a set of resources for finer-grained control "
2029 "(CPUs, memory, etc.).  In this mode, the event is measured only if the "
2030 "thread running on the monitored CPU belongs to the designated container "
2031 "(cgroup).  The cgroup is identified by passing a file descriptor opened on "
2032 "its directory in the cgroupfs filesystem.  For instance, if the cgroup to "
2033 "monitor is called I<test>, then a file descriptor opened on "
2034 "I</dev/cgroup/test> (assuming cgroupfs is mounted on I</dev/cgroup>)  must "
2035 "be passed as the I<pid> parameter.  cgroup monitoring is available only for "
2036 "system-wide events and may therefore require extra permissions."
2037 msgstr ""
2038
2039 #. type: Plain text
2040 #: build/C/man2/perf_event_open.2:188
2041 msgid ""
2042 "The I<perf_event_attr> structure provides detailed configuration information "
2043 "for the event being created."
2044 msgstr ""
2045
2046 #. type: Plain text
2047 #: build/C/man2/perf_event_open.2:195
2048 #, no-wrap
2049 msgid ""
2050 "struct perf_event_attr {\n"
2051 "    __u32 type;         /* Type of event */\n"
2052 "    __u32 size;         /* Size of attribute structure */\n"
2053 "    __u64 config;       /* Type-specific configuration */\n"
2054 msgstr ""
2055
2056 #. type: Plain text
2057 #: build/C/man2/perf_event_open.2:200
2058 #, no-wrap
2059 msgid ""
2060 "    union {\n"
2061 "        __u64 sample_period;    /* Period of sampling */\n"
2062 "        __u64 sample_freq;      /* Frequency of sampling */\n"
2063 "    };\n"
2064 msgstr ""
2065
2066 #. type: Plain text
2067 #: build/C/man2/perf_event_open.2:203
2068 #, no-wrap
2069 msgid ""
2070 "    __u64 sample_type;  /* Specifies values included in sample */\n"
2071 "    __u64 read_format;  /* Specifies values returned in read */\n"
2072 msgstr ""
2073
2074 #. type: Plain text
2075 #: build/C/man2/perf_event_open.2:229
2076 #, no-wrap
2077 msgid ""
2078 "    __u64 disabled       : 1,   /* off by default */\n"
2079 "          inherit        : 1,   /* children inherit it */\n"
2080 "          pinned         : 1,   /* must always be on PMU */\n"
2081 "          exclusive      : 1,   /* only group on PMU */\n"
2082 "          exclude_user   : 1,   /* don't count user */\n"
2083 "          exclude_kernel : 1,   /* don't count kernel */\n"
2084 "          exclude_hv     : 1,   /* don't count hypervisor */\n"
2085 "          exclude_idle   : 1,   /* don't count when idle */\n"
2086 "          mmap           : 1,   /* include mmap data */\n"
2087 "          comm           : 1,   /* include comm data */\n"
2088 "          freq           : 1,   /* use freq, not period */\n"
2089 "          inherit_stat   : 1,   /* per task counts */\n"
2090 "          enable_on_exec : 1,   /* next exec enables */\n"
2091 "          task           : 1,   /* trace fork/exit */\n"
2092 "          watermark      : 1,   /* wakeup_watermark */\n"
2093 "          precise_ip     : 2,   /* skid constraint */\n"
2094 "          mmap_data      : 1,   /* non-exec mmap data */\n"
2095 "          sample_id_all  : 1,   /* sample_type all events */\n"
2096 "          exclude_host   : 1,   /* don't count in host */\n"
2097 "          exclude_guest  : 1,   /* don't count in guest */\n"
2098 "          exclude_callchain_kernel : 1,\n"
2099 "                                /* exclude kernel callchains */\n"
2100 "          exclude_callchain_user   : 1,\n"
2101 "                                /* exclude user callchains */\n"
2102 "          __reserved_1   : 41;\n"
2103 msgstr ""
2104
2105 #. type: Plain text
2106 #: build/C/man2/perf_event_open.2:234
2107 #, no-wrap
2108 msgid ""
2109 "    union {\n"
2110 "        __u32 wakeup_events;    /* wakeup every n events */\n"
2111 "        __u32 wakeup_watermark; /* bytes before wakeup */\n"
2112 "    };\n"
2113 msgstr ""
2114
2115 #. type: Plain text
2116 #: build/C/man2/perf_event_open.2:236
2117 #, no-wrap
2118 msgid "    __u32     bp_type;          /* breakpoint type */\n"
2119 msgstr ""
2120
2121 #. type: Plain text
2122 #: build/C/man2/perf_event_open.2:241
2123 #, no-wrap
2124 msgid ""
2125 "    union {\n"
2126 "        __u64 bp_addr;          /* breakpoint address */\n"
2127 "        __u64 config1;          /* extension of config */\n"
2128 "    };\n"
2129 msgstr ""
2130
2131 #. type: Plain text
2132 #: build/C/man2/perf_event_open.2:251
2133 #, no-wrap
2134 msgid ""
2135 "    union {\n"
2136 "        __u64 bp_len;           /* breakpoint length */\n"
2137 "        __u64 config2;          /* extension of config1 */\n"
2138 "    };\n"
2139 "    __u64 branch_sample_type;   /* enum perf_branch_sample_type */\n"
2140 "    __u64 sample_regs_user;     /* user regs to dump on samples */\n"
2141 "    __u32 sample_stack_user;    /* size of stack to dump on\n"
2142 "                                   samples */\n"
2143 "    __u32 __reserved_2;         /* Align to u64 */\n"
2144 msgstr ""
2145
2146 #. type: Plain text
2147 #: build/C/man2/perf_event_open.2:253
2148 #, no-wrap
2149 msgid "};\n"
2150 msgstr ""
2151
2152 #. type: Plain text
2153 #: build/C/man2/perf_event_open.2:259
2154 msgid ""
2155 "The fields of the I<perf_event_attr> structure are described in more detail "
2156 "below:"
2157 msgstr ""
2158
2159 #. type: TP
2160 #: build/C/man2/perf_event_open.2:259 build/C/man2/perf_event_open.2:1556
2161 #, no-wrap
2162 msgid "I<type>"
2163 msgstr ""
2164
2165 #. type: Plain text
2166 #: build/C/man2/perf_event_open.2:263
2167 msgid ""
2168 "This field specifies the overall event type.  It has one of the following "
2169 "values:"
2170 msgstr ""
2171
2172 #. type: TP
2173 #: build/C/man2/perf_event_open.2:264
2174 #, no-wrap
2175 msgid "B<PERF_TYPE_HARDWARE>"
2176 msgstr ""
2177
2178 #. type: Plain text
2179 #: build/C/man2/perf_event_open.2:271
2180 msgid ""
2181 "This indicates one of the \"generalized\" hardware events provided by the "
2182 "kernel.  See the I<config> field definition for more details."
2183 msgstr ""
2184
2185 #. type: TP
2186 #: build/C/man2/perf_event_open.2:271
2187 #, no-wrap
2188 msgid "B<PERF_TYPE_SOFTWARE>"
2189 msgstr ""
2190
2191 #. type: Plain text
2192 #: build/C/man2/perf_event_open.2:275
2193 msgid ""
2194 "This indicates one of the software-defined events provided by the kernel "
2195 "(even if no hardware support is available)."
2196 msgstr ""
2197
2198 #. type: TP
2199 #: build/C/man2/perf_event_open.2:275
2200 #, no-wrap
2201 msgid "B<PERF_TYPE_TRACEPOINT>"
2202 msgstr ""
2203
2204 #. type: Plain text
2205 #: build/C/man2/perf_event_open.2:279
2206 msgid ""
2207 "This indicates a tracepoint provided by the kernel tracepoint "
2208 "infrastructure."
2209 msgstr ""
2210
2211 #. type: TP
2212 #: build/C/man2/perf_event_open.2:279
2213 #, no-wrap
2214 msgid "B<PERF_TYPE_HW_CACHE>"
2215 msgstr ""
2216
2217 #. type: Plain text
2218 #: build/C/man2/perf_event_open.2:285
2219 msgid ""
2220 "This indicates a hardware cache event.  This has a special encoding, "
2221 "described in the I<config> field definition."
2222 msgstr ""
2223
2224 #. type: TP
2225 #: build/C/man2/perf_event_open.2:285
2226 #, no-wrap
2227 msgid "B<PERF_TYPE_RAW>"
2228 msgstr ""
2229
2230 #. type: Plain text
2231 #: build/C/man2/perf_event_open.2:289
2232 msgid ""
2233 "This indicates a \"raw\" implementation-specific event in the I<config> "
2234 "field."
2235 msgstr ""
2236
2237 #. type: TP
2238 #: build/C/man2/perf_event_open.2:289
2239 #, no-wrap
2240 msgid "B<PERF_TYPE_BREAKPOINT> (since Linux 2.6.33)"
2241 msgstr ""
2242
2243 #. type: Plain text
2244 #: build/C/man2/perf_event_open.2:294
2245 msgid ""
2246 "This indicates a hardware breakpoint as provided by the CPU.  Breakpoints "
2247 "can be read/write accesses to an address as well as execution of an "
2248 "instruction address."
2249 msgstr ""
2250
2251 #. type: TP
2252 #: build/C/man2/perf_event_open.2:294
2253 #, no-wrap
2254 msgid "dynamic PMU"
2255 msgstr ""
2256
2257 #. type: Plain text
2258 #: build/C/man2/perf_event_open.2:313
2259 msgid ""
2260 "Since Linux 2.6.39, B<perf_event_open>()  can support multiple PMUs.  To "
2261 "enable this, a value exported by the kernel can be used in the I<type> field "
2262 "to indicate which PMU to use.  The value to use can be found in the sysfs "
2263 "filesystem: there is a subdirectory per PMU instance under "
2264 "I</sys/bus/event_source/devices>.  In each subdirectory there is a I<type> "
2265 "file whose content is an integer that can be used in the I<type> field.  For "
2266 "instance, I</sys/bus/event_source/devices/cpu/type> contains the value for "
2267 "the core CPU PMU, which is usually 4."
2268 msgstr ""
2269
2270 #. type: TP
2271 #: build/C/man2/perf_event_open.2:314 build/C/man2/perf_event_open.2:1504
2272 #, no-wrap
2273 msgid "I<size>"
2274 msgstr ""
2275
2276 #. type: Plain text
2277 #: build/C/man2/perf_event_open.2:323
2278 msgid ""
2279 "The size of the I<perf_event_attr> structure for forward/backward "
2280 "compatibility.  Set this using I<sizeof(struct perf_event_attr)> to allow "
2281 "the kernel to see the struct size at the time of compilation."
2282 msgstr ""
2283
2284 #. type: Plain text
2285 #: build/C/man2/perf_event_open.2:338
2286 msgid ""
2287 "The related define B<PERF_ATTR_SIZE_VER0> is set to 64; this was the size of "
2288 "the first published struct.  B<PERF_ATTR_SIZE_VER1> is 72, corresponding to "
2289 "the addition of breakpoints in Linux 2.6.33.  B<PERF_ATTR_SIZE_VER2> is 80 "
2290 "corresponding to the addition of branch sampling in Linux 3.4.  "
2291 "B<PERF_ATR_SIZE_VER3> is 96 corresponding to the addition of "
2292 "I<sample_regs_user> and I<sample_stack_user> in Linux 3.7."
2293 msgstr ""
2294
2295 #. type: TP
2296 #: build/C/man2/perf_event_open.2:338
2297 #, no-wrap
2298 msgid "I<config>"
2299 msgstr ""
2300
2301 #. type: Plain text
2302 #: build/C/man2/perf_event_open.2:349
2303 msgid ""
2304 "This specifies which event you want, in conjunction with the I<type> field.  "
2305 "The I<config1> and I<config2> fields are also taken into account in cases "
2306 "where 64 bits is not enough to fully specify the event.  The encoding of "
2307 "these fields are event dependent."
2308 msgstr ""
2309
2310 #. type: Plain text
2311 #: build/C/man2/perf_event_open.2:355
2312 msgid ""
2313 "The most significant bit (bit 63) of I<config> signifies CPU-specific (raw) "
2314 "counter configuration data; if the most significant bit is unset, the next 7 "
2315 "bits are an event type and the rest of the bits are the event identifier."
2316 msgstr ""
2317
2318 #. type: Plain text
2319 #: build/C/man2/perf_event_open.2:366
2320 msgid ""
2321 "There are various ways to set the I<config> field that are dependent on the "
2322 "value of the previously described I<type> field.  What follows are various "
2323 "possible settings for I<config> separated out by I<type>."
2324 msgstr ""
2325
2326 #. type: Plain text
2327 #: build/C/man2/perf_event_open.2:376
2328 msgid ""
2329 "If I<type> is B<PERF_TYPE_HARDWARE>, we are measuring one of the generalized "
2330 "hardware CPU events.  Not all of these are available on all platforms.  Set "
2331 "I<config> to one of the following:"
2332 msgstr ""
2333
2334 #. type: TP
2335 #: build/C/man2/perf_event_open.2:377
2336 #, no-wrap
2337 msgid "B<PERF_COUNT_HW_CPU_CYCLES>"
2338 msgstr ""
2339
2340 #. type: Plain text
2341 #: build/C/man2/perf_event_open.2:381
2342 msgid "Total cycles.  Be wary of what happens during CPU frequency scaling."
2343 msgstr ""
2344
2345 #. type: TP
2346 #: build/C/man2/perf_event_open.2:381
2347 #, no-wrap
2348 msgid "B<PERF_COUNT_HW_INSTRUCTIONS>"
2349 msgstr ""
2350
2351 #. type: Plain text
2352 #: build/C/man2/perf_event_open.2:386
2353 msgid ""
2354 "Retired instructions.  Be careful, these can be affected by various issues, "
2355 "most notably hardware interrupt counts."
2356 msgstr ""
2357
2358 #. type: TP
2359 #: build/C/man2/perf_event_open.2:386
2360 #, no-wrap
2361 msgid "B<PERF_COUNT_HW_CACHE_REFERENCES>"
2362 msgstr ""
2363
2364 #. type: Plain text
2365 #: build/C/man2/perf_event_open.2:393
2366 msgid ""
2367 "Cache accesses.  Usually this indicates Last Level Cache accesses but this "
2368 "may vary depending on your CPU.  This may include prefetches and coherency "
2369 "messages; again this depends on the design of your CPU."
2370 msgstr ""
2371
2372 #. type: TP
2373 #: build/C/man2/perf_event_open.2:393
2374 #, no-wrap
2375 msgid "B<PERF_COUNT_HW_CACHE_MISSES>"
2376 msgstr ""
2377
2378 #. type: Plain text
2379 #: build/C/man2/perf_event_open.2:400
2380 msgid ""
2381 "Cache misses.  Usually this indicates Last Level Cache misses; this is "
2382 "intended to be used in conjunction with the "
2383 "B<PERF_COUNT_HW_CACHE_REFERENCES> event to calculate cache miss rates."
2384 msgstr ""
2385
2386 #. type: TP
2387 #: build/C/man2/perf_event_open.2:400
2388 #, no-wrap
2389 msgid "B<PERF_COUNT_HW_BRANCH_INSTRUCTIONS>"
2390 msgstr ""
2391
2392 #. type: Plain text
2393 #: build/C/man2/perf_event_open.2:405
2394 msgid ""
2395 "Retired branch instructions.  Prior to Linux 2.6.34, this used the wrong "
2396 "event on AMD processors."
2397 msgstr ""
2398
2399 #. type: TP
2400 #: build/C/man2/perf_event_open.2:405
2401 #, no-wrap
2402 msgid "B<PERF_COUNT_HW_BRANCH_MISSES>"
2403 msgstr ""
2404
2405 #. type: Plain text
2406 #: build/C/man2/perf_event_open.2:408
2407 msgid "Mispredicted branch instructions."
2408 msgstr ""
2409
2410 #. type: TP
2411 #: build/C/man2/perf_event_open.2:408
2412 #, no-wrap
2413 msgid "B<PERF_COUNT_HW_BUS_CYCLES>"
2414 msgstr ""
2415
2416 #. type: Plain text
2417 #: build/C/man2/perf_event_open.2:411
2418 msgid "Bus cycles, which can be different from total cycles."
2419 msgstr ""
2420
2421 #. type: TP
2422 #: build/C/man2/perf_event_open.2:411
2423 #, no-wrap
2424 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_FRONTEND> (since Linux 3.0)"
2425 msgstr ""
2426
2427 #. type: Plain text
2428 #: build/C/man2/perf_event_open.2:414
2429 msgid "Stalled cycles during issue."
2430 msgstr ""
2431
2432 #. type: TP
2433 #: build/C/man2/perf_event_open.2:414
2434 #, no-wrap
2435 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_BACKEND> (since Linux 3.0)"
2436 msgstr ""
2437
2438 #. type: Plain text
2439 #: build/C/man2/perf_event_open.2:417
2440 msgid "Stalled cycles during retirement."
2441 msgstr ""
2442
2443 #. type: TP
2444 #: build/C/man2/perf_event_open.2:417
2445 #, no-wrap
2446 msgid "B<PERF_COUNT_HW_REF_CPU_CYCLES> (since Linux 3.3)"
2447 msgstr ""
2448
2449 #. type: Plain text
2450 #: build/C/man2/perf_event_open.2:420
2451 msgid "Total cycles; not affected by CPU frequency scaling."
2452 msgstr ""
2453
2454 #. type: Plain text
2455 #: build/C/man2/perf_event_open.2:430
2456 msgid ""
2457 "If I<type> is B<PERF_TYPE_SOFTWARE>, we are measuring software events "
2458 "provided by the kernel.  Set I<config> to one of the following:"
2459 msgstr ""
2460
2461 #. type: TP
2462 #: build/C/man2/perf_event_open.2:431
2463 #, no-wrap
2464 msgid "B<PERF_COUNT_SW_CPU_CLOCK>"
2465 msgstr ""
2466
2467 #. type: Plain text
2468 #: build/C/man2/perf_event_open.2:434
2469 msgid "This reports the CPU clock, a high-resolution per-CPU timer."
2470 msgstr ""
2471
2472 #. type: TP
2473 #: build/C/man2/perf_event_open.2:434
2474 #, no-wrap
2475 msgid "B<PERF_COUNT_SW_TASK_CLOCK>"
2476 msgstr ""
2477
2478 #. type: Plain text
2479 #: build/C/man2/perf_event_open.2:437
2480 msgid "This reports a clock count specific to the task that is running."
2481 msgstr ""
2482
2483 #. type: TP
2484 #: build/C/man2/perf_event_open.2:437
2485 #, no-wrap
2486 msgid "B<PERF_COUNT_SW_PAGE_FAULTS>"
2487 msgstr ""
2488
2489 #. type: Plain text
2490 #: build/C/man2/perf_event_open.2:440
2491 msgid "This reports the number of page faults."
2492 msgstr ""
2493
2494 #. type: TP
2495 #: build/C/man2/perf_event_open.2:440
2496 #, no-wrap
2497 msgid "B<PERF_COUNT_SW_CONTEXT_SWITCHES>"
2498 msgstr ""
2499
2500 #. type: Plain text
2501 #: build/C/man2/perf_event_open.2:445
2502 msgid ""
2503 "This counts context switches.  Until Linux 2.6.34, these were all reported "
2504 "as user-space events, after that they are reported as happening in the "
2505 "kernel."
2506 msgstr ""
2507
2508 #. type: TP
2509 #: build/C/man2/perf_event_open.2:445
2510 #, no-wrap
2511 msgid "B<PERF_COUNT_SW_CPU_MIGRATIONS>"
2512 msgstr ""
2513
2514 #. type: Plain text
2515 #: build/C/man2/perf_event_open.2:449
2516 msgid "This reports the number of times the process has migrated to a new CPU."
2517 msgstr ""
2518
2519 #. type: TP
2520 #: build/C/man2/perf_event_open.2:449
2521 #, no-wrap
2522 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MIN>"
2523 msgstr ""
2524
2525 #. type: Plain text
2526 #: build/C/man2/perf_event_open.2:453
2527 msgid ""
2528 "This counts the number of minor page faults.  These did not require disk I/O "
2529 "to handle."
2530 msgstr ""
2531
2532 #. type: TP
2533 #: build/C/man2/perf_event_open.2:453
2534 #, no-wrap
2535 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MAJ>"
2536 msgstr ""
2537
2538 #. type: Plain text
2539 #: build/C/man2/perf_event_open.2:457
2540 msgid ""
2541 "This counts the number of major page faults.  These required disk I/O to "
2542 "handle."
2543 msgstr ""
2544
2545 #. type: TP
2546 #: build/C/man2/perf_event_open.2:457
2547 #, no-wrap
2548 msgid "B<PERF_COUNT_SW_ALIGNMENT_FAULTS> (since Linux 2.6.33)"
2549 msgstr ""
2550
2551 #. type: Plain text
2552 #: build/C/man2/perf_event_open.2:463
2553 msgid ""
2554 "This counts the number of alignment faults.  These happen when unaligned "
2555 "memory accesses happen; the kernel can handle these but it reduces "
2556 "performance.  This happens only on some architectures (never on x86)."
2557 msgstr ""
2558
2559 #. type: TP
2560 #: build/C/man2/perf_event_open.2:463
2561 #, no-wrap
2562 msgid "B<PERF_COUNT_SW_EMULATION_FAULTS> (since Linux 2.6.33)"
2563 msgstr ""
2564
2565 #. type: Plain text
2566 #: build/C/man2/perf_event_open.2:469
2567 msgid ""
2568 "This counts the number of emulation faults.  The kernel sometimes traps on "
2569 "unimplemented instructions and emulates them for user space.  This can "
2570 "negatively impact performance."
2571 msgstr ""
2572
2573 #. type: TP
2574 #: build/C/man2/perf_event_open.2:469
2575 #, no-wrap
2576 msgid "B<PERF_COUNT_SW_DUMMY> (since Linux 3.12)"
2577 msgstr ""
2578
2579 #. type: Plain text
2580 #: build/C/man2/perf_event_open.2:476
2581 msgid ""
2582 "This is a placeholder event that counts nothing.  Informational sample "
2583 "record types such as mmap or comm must be associated with an active event.  "
2584 "This dummy event allows gathering such records without requiring a counting "
2585 "event."
2586 msgstr ""
2587
2588 #. type: Plain text
2589 #: build/C/man2/perf_event_open.2:489
2590 msgid ""
2591 "If I<type> is B<PERF_TYPE_TRACEPOINT>, then we are measuring kernel "
2592 "tracepoints.  The value to use in I<config> can be obtained from under "
2593 "debugfs I<tracing/events/*/*/id> if ftrace is enabled in the kernel."
2594 msgstr ""
2595
2596 #. type: Plain text
2597 #: build/C/man2/perf_event_open.2:500
2598 msgid ""
2599 "If I<type> is B<PERF_TYPE_HW_CACHE>, then we are measuring a hardware CPU "
2600 "cache event.  To calculate the appropriate I<config> value use the following "
2601 "equation:"
2602 msgstr ""
2603
2604 #. type: Plain text
2605 #: build/C/man2/perf_event_open.2:505
2606 #, no-wrap
2607 msgid ""
2608 "    (perf_hw_cache_id) | (perf_hw_cache_op_id E<lt>E<lt> 8) |\n"
2609 "    (perf_hw_cache_op_result_id E<lt>E<lt> 16)\n"
2610 msgstr ""
2611
2612 #. type: Plain text
2613 #: build/C/man2/perf_event_open.2:510
2614 msgid "where I<perf_hw_cache_id> is one of:"
2615 msgstr ""
2616
2617 #. type: TP
2618 #: build/C/man2/perf_event_open.2:511
2619 #, no-wrap
2620 msgid "B<PERF_COUNT_HW_CACHE_L1D>"
2621 msgstr ""
2622
2623 #. type: Plain text
2624 #: build/C/man2/perf_event_open.2:514
2625 msgid "for measuring Level 1 Data Cache"
2626 msgstr ""
2627
2628 #. type: TP
2629 #: build/C/man2/perf_event_open.2:514
2630 #, no-wrap
2631 msgid "B<PERF_COUNT_HW_CACHE_L1I>"
2632 msgstr ""
2633
2634 #. type: Plain text
2635 #: build/C/man2/perf_event_open.2:517
2636 msgid "for measuring Level 1 Instruction Cache"
2637 msgstr ""
2638
2639 #. type: TP
2640 #: build/C/man2/perf_event_open.2:517
2641 #, no-wrap
2642 msgid "B<PERF_COUNT_HW_CACHE_LL>"
2643 msgstr ""
2644
2645 #. type: Plain text
2646 #: build/C/man2/perf_event_open.2:520
2647 msgid "for measuring Last-Level Cache"
2648 msgstr ""
2649
2650 #. type: TP
2651 #: build/C/man2/perf_event_open.2:520
2652 #, no-wrap
2653 msgid "B<PERF_COUNT_HW_CACHE_DTLB>"
2654 msgstr ""
2655
2656 #. type: Plain text
2657 #: build/C/man2/perf_event_open.2:523
2658 msgid "for measuring the Data TLB"
2659 msgstr ""
2660
2661 #. type: TP
2662 #: build/C/man2/perf_event_open.2:523
2663 #, no-wrap
2664 msgid "B<PERF_COUNT_HW_CACHE_ITLB>"
2665 msgstr ""
2666
2667 #. type: Plain text
2668 #: build/C/man2/perf_event_open.2:526
2669 msgid "for measuring the Instruction TLB"
2670 msgstr ""
2671
2672 #. type: TP
2673 #: build/C/man2/perf_event_open.2:526
2674 #, no-wrap
2675 msgid "B<PERF_COUNT_HW_CACHE_BPU>"
2676 msgstr ""
2677
2678 #. type: Plain text
2679 #: build/C/man2/perf_event_open.2:529
2680 msgid "for measuring the branch prediction unit"
2681 msgstr ""
2682
2683 #. type: TP
2684 #: build/C/man2/perf_event_open.2:529
2685 #, no-wrap
2686 msgid "B<PERF_COUNT_HW_CACHE_NODE> (since Linux 3.0)"
2687 msgstr ""
2688
2689 #. type: Plain text
2690 #: build/C/man2/perf_event_open.2:532
2691 msgid "for measuring local memory accesses"
2692 msgstr ""
2693
2694 #. type: Plain text
2695 #: build/C/man2/perf_event_open.2:537
2696 msgid "and I<perf_hw_cache_op_id> is one of"
2697 msgstr ""
2698
2699 #. type: TP
2700 #: build/C/man2/perf_event_open.2:538
2701 #, no-wrap
2702 msgid "B<PERF_COUNT_HW_CACHE_OP_READ>"
2703 msgstr ""
2704
2705 #. type: Plain text
2706 #: build/C/man2/perf_event_open.2:541
2707 msgid "for read accesses"
2708 msgstr ""
2709
2710 #. type: TP
2711 #: build/C/man2/perf_event_open.2:541
2712 #, no-wrap
2713 msgid "B<PERF_COUNT_HW_CACHE_OP_WRITE>"
2714 msgstr ""
2715
2716 #. type: Plain text
2717 #: build/C/man2/perf_event_open.2:544
2718 msgid "for write accesses"
2719 msgstr ""
2720
2721 #. type: TP
2722 #: build/C/man2/perf_event_open.2:544
2723 #, no-wrap
2724 msgid "B<PERF_COUNT_HW_CACHE_OP_PREFETCH>"
2725 msgstr ""
2726
2727 #. type: Plain text
2728 #: build/C/man2/perf_event_open.2:547
2729 msgid "for prefetch accesses"
2730 msgstr ""
2731
2732 #. type: Plain text
2733 #: build/C/man2/perf_event_open.2:552
2734 msgid "and I<perf_hw_cache_op_result_id> is one of"
2735 msgstr ""
2736
2737 #. type: TP
2738 #: build/C/man2/perf_event_open.2:553
2739 #, no-wrap
2740 msgid "B<PERF_COUNT_HW_CACHE_RESULT_ACCESS>"
2741 msgstr ""
2742
2743 #. type: Plain text
2744 #: build/C/man2/perf_event_open.2:556
2745 msgid "to measure accesses"
2746 msgstr ""
2747
2748 #. type: TP
2749 #: build/C/man2/perf_event_open.2:556
2750 #, no-wrap
2751 msgid "B<PERF_COUNT_HW_CACHE_RESULT_MISS>"
2752 msgstr ""
2753
2754 #. type: Plain text
2755 #: build/C/man2/perf_event_open.2:559
2756 msgid "to measure misses"
2757 msgstr ""
2758
2759 #. type: Plain text
2760 #: build/C/man2/perf_event_open.2:577
2761 msgid ""
2762 "If I<type> is B<PERF_TYPE_RAW>, then a custom \"raw\" I<config> value is "
2763 "needed.  Most CPUs support events that are not covered by the "
2764 "\"generalized\" events.  These are implementation defined; see your CPU "
2765 "manual (for example the Intel Volume 3B documentation or the AMD BIOS and "
2766 "Kernel Developer Guide).  The libpfm4 library can be used to translate from "
2767 "the name in the architectural manuals to the raw hex value "
2768 "B<perf_event_open>()  expects in this field."
2769 msgstr ""
2770
2771 #. type: Plain text
2772 #: build/C/man2/perf_event_open.2:586
2773 msgid ""
2774 "If I<type> is B<PERF_TYPE_BREAKPOINT>, then leave I<config> set to zero.  "
2775 "Its parameters are set in other places."
2776 msgstr ""
2777
2778 #. type: TP
2779 #: build/C/man2/perf_event_open.2:587
2780 #, no-wrap
2781 msgid "I<sample_period>, I<sample_freq>"
2782 msgstr ""
2783
2784 #. type: Plain text
2785 #: build/C/man2/perf_event_open.2:599
2786 msgid ""
2787 "A \"sampling\" counter is one that generates an interrupt every N events, "
2788 "where N is given by I<sample_period>.  A sampling counter has "
2789 "I<sample_period> E<gt> 0.  When an overflow interrupt occurs, requested data "
2790 "is recorded in the mmap buffer.  The I<sample_type> field controls what data "
2791 "is recorded on each interrupt."
2792 msgstr ""
2793
2794 #. type: Plain text
2795 #: build/C/man2/perf_event_open.2:609
2796 msgid ""
2797 "I<sample_freq> can be used if you wish to use frequency rather than period.  "
2798 "In this case, you set the I<freq> flag.  The kernel will adjust the sampling "
2799 "period to try and achieve the desired rate.  The rate of adjustment is a "
2800 "timer tick."
2801 msgstr ""
2802
2803 #. type: TP
2804 #: build/C/man2/perf_event_open.2:609
2805 #, no-wrap
2806 msgid "I<sample_type>"
2807 msgstr ""
2808
2809 #. type: Plain text
2810 #: build/C/man2/perf_event_open.2:621
2811 msgid ""
2812 "The various bits in this field specify which values to include in the "
2813 "sample.  They will be recorded in a ring-buffer, which is available to user "
2814 "space using B<mmap>(2).  The order in which the values are saved in the "
2815 "sample are documented in the MMAP Layout subsection below; it is not the "
2816 "I<enum perf_event_sample_format> order."
2817 msgstr ""
2818
2819 #. type: TP
2820 #: build/C/man2/perf_event_open.2:622
2821 #, no-wrap
2822 msgid "B<PERF_SAMPLE_IP>"
2823 msgstr ""
2824
2825 #. type: Plain text
2826 #: build/C/man2/perf_event_open.2:625
2827 msgid "Records instruction pointer."
2828 msgstr ""
2829
2830 #. type: TP
2831 #: build/C/man2/perf_event_open.2:625
2832 #, no-wrap
2833 msgid "B<PERF_SAMPLE_TID>"
2834 msgstr ""
2835
2836 #. type: Plain text
2837 #: build/C/man2/perf_event_open.2:628
2838 msgid "Records the process and thread IDs."
2839 msgstr ""
2840
2841 #. type: TP
2842 #: build/C/man2/perf_event_open.2:628
2843 #, no-wrap
2844 msgid "B<PERF_SAMPLE_TIME>"
2845 msgstr ""
2846
2847 #. type: Plain text
2848 #: build/C/man2/perf_event_open.2:631
2849 msgid "Records a timestamp."
2850 msgstr ""
2851
2852 #. type: TP
2853 #: build/C/man2/perf_event_open.2:631
2854 #, no-wrap
2855 msgid "B<PERF_SAMPLE_ADDR>"
2856 msgstr ""
2857
2858 #. type: Plain text
2859 #: build/C/man2/perf_event_open.2:634
2860 msgid "Records an address, if applicable."
2861 msgstr ""
2862
2863 #. type: TP
2864 #: build/C/man2/perf_event_open.2:634
2865 #, no-wrap
2866 msgid "B<PERF_SAMPLE_READ>"
2867 msgstr ""
2868
2869 #. type: Plain text
2870 #: build/C/man2/perf_event_open.2:637
2871 msgid "Record counter values for all events in a group, not just the group leader."
2872 msgstr ""
2873
2874 #. type: TP
2875 #: build/C/man2/perf_event_open.2:637
2876 #, no-wrap
2877 msgid "B<PERF_SAMPLE_CALLCHAIN>"
2878 msgstr ""
2879
2880 #. type: Plain text
2881 #: build/C/man2/perf_event_open.2:640
2882 msgid "Records the callchain (stack backtrace)."
2883 msgstr ""
2884
2885 #. type: TP
2886 #: build/C/man2/perf_event_open.2:640
2887 #, no-wrap
2888 msgid "B<PERF_SAMPLE_ID>"
2889 msgstr ""
2890
2891 #. type: Plain text
2892 #: build/C/man2/perf_event_open.2:643
2893 msgid "Records a unique ID for the opened event's group leader."
2894 msgstr ""
2895
2896 #. type: TP
2897 #: build/C/man2/perf_event_open.2:643
2898 #, no-wrap
2899 msgid "B<PERF_SAMPLE_CPU>"
2900 msgstr ""
2901
2902 #. type: Plain text
2903 #: build/C/man2/perf_event_open.2:646
2904 msgid "Records CPU number."
2905 msgstr ""
2906
2907 #. type: TP
2908 #: build/C/man2/perf_event_open.2:646
2909 #, no-wrap
2910 msgid "B<PERF_SAMPLE_PERIOD>"
2911 msgstr ""
2912
2913 #. type: Plain text
2914 #: build/C/man2/perf_event_open.2:649
2915 msgid "Records the current sampling period."
2916 msgstr ""
2917
2918 #. type: TP
2919 #: build/C/man2/perf_event_open.2:649
2920 #, no-wrap
2921 msgid "B<PERF_SAMPLE_STREAM_ID>"
2922 msgstr ""
2923
2924 #. type: Plain text
2925 #: build/C/man2/perf_event_open.2:657
2926 msgid ""
2927 "Records a unique ID for the opened event.  Unlike B<PERF_SAMPLE_ID> the "
2928 "actual ID is returned, not the group leader.  This ID is the same as the one "
2929 "returned by B<PERF_FORMAT_ID>."
2930 msgstr ""
2931
2932 #. type: TP
2933 #: build/C/man2/perf_event_open.2:657
2934 #, no-wrap
2935 msgid "B<PERF_SAMPLE_RAW>"
2936 msgstr ""
2937
2938 #. type: Plain text
2939 #: build/C/man2/perf_event_open.2:661
2940 msgid ""
2941 "Records additional data, if applicable.  Usually returned by tracepoint "
2942 "events."
2943 msgstr ""
2944
2945 #. type: TP
2946 #: build/C/man2/perf_event_open.2:661
2947 #, no-wrap
2948 msgid "B<PERF_SAMPLE_BRANCH_STACK> (since Linux 3.4)"
2949 msgstr ""
2950
2951 #. type: Plain text
2952 #: build/C/man2/perf_event_open.2:666
2953 msgid ""
2954 "This provides a record of recent branches, as provided by CPU branch "
2955 "sampling hardware (such as Intel Last Branch Record).  Not all hardware "
2956 "supports this feature."
2957 msgstr ""
2958
2959 #. type: Plain text
2960 #: build/C/man2/perf_event_open.2:670
2961 msgid ""
2962 "See the I<branch_sample_type> field for how to filter which branches are "
2963 "reported."
2964 msgstr ""
2965
2966 #. type: TP
2967 #: build/C/man2/perf_event_open.2:670
2968 #, no-wrap
2969 msgid "B<PERF_SAMPLE_REGS_USER> (since Linux 3.7)"
2970 msgstr ""
2971
2972 #. type: Plain text
2973 #: build/C/man2/perf_event_open.2:674
2974 msgid ""
2975 "Records the current user-level CPU register state (the values in the process "
2976 "before the kernel was called)."
2977 msgstr ""
2978
2979 #. type: TP
2980 #: build/C/man2/perf_event_open.2:674
2981 #, no-wrap
2982 msgid "B<PERF_SAMPLE_STACK_USER> (since Linux 3.7)"
2983 msgstr ""
2984
2985 #. type: Plain text
2986 #: build/C/man2/perf_event_open.2:677
2987 msgid "Records the user level stack, allowing stack unwinding."
2988 msgstr ""
2989
2990 #. type: TP
2991 #: build/C/man2/perf_event_open.2:677
2992 #, no-wrap
2993 msgid "B<PERF_SAMPLE_WEIGHT> (since Linux 3.10)"
2994 msgstr ""
2995
2996 #. type: Plain text
2997 #: build/C/man2/perf_event_open.2:683
2998 msgid ""
2999 "Records a hardware provided weight value that expresses how costly the "
3000 "sampled event was.  This allows the hardware to highlight expensive events "
3001 "in a profile."
3002 msgstr ""
3003
3004 #. type: TP
3005 #: build/C/man2/perf_event_open.2:683
3006 #, no-wrap
3007 msgid "B<PERF_SAMPLE_DATA_SRC> (since Linux 3.10)"
3008 msgstr ""
3009
3010 #. type: Plain text
3011 #: build/C/man2/perf_event_open.2:689
3012 msgid ""
3013 "Records the data source: where in the memory hierarchy the data associated "
3014 "with the sampled instruction came from.  This is only available if the "
3015 "underlying hardware supports this feature."
3016 msgstr ""
3017
3018 #. type: TP
3019 #: build/C/man2/perf_event_open.2:689
3020 #, no-wrap
3021 msgid "B<PERF_SAMPLE_IDENTIFIER> (since Linux 3.12)"
3022 msgstr ""
3023
3024 #. type: Plain text
3025 #: build/C/man2/perf_event_open.2:696
3026 msgid ""
3027 "Places the B<SAMPLE_ID> value in a fixed position in the record, either at "
3028 "the beginning (for sample events) or at the end (if a non-sample event)."
3029 msgstr ""
3030
3031 #. type: Plain text
3032 #: build/C/man2/perf_event_open.2:708
3033 msgid ""
3034 "This was necessary because a sample stream may have records from various "
3035 "different event sources with different I<sample_type> settings.  Parsing the "
3036 "event stream properly was not possible because the format of the record was "
3037 "needed to find B<SAMPLE_ID>, but the format could not be found without "
3038 "knowing what event the sample belonged to (causing a circular dependency)."
3039 msgstr ""
3040
3041 #. type: Plain text
3042 #: build/C/man2/perf_event_open.2:718
3043 msgid ""
3044 "This new B<PERF_SAMPLE_IDENTIFIER> setting makes the event stream always "
3045 "parsable by putting B<SAMPLE_ID> in a fixed location, even though it means "
3046 "having duplicate B<SAMPLE_ID> values in records."
3047 msgstr ""
3048
3049 #. type: TP
3050 #: build/C/man2/perf_event_open.2:718
3051 #, no-wrap
3052 msgid "B<PERF_SAMPLE_TRANSACTION> (Since Linux 3.13)"
3053 msgstr ""
3054
3055 #. type: Plain text
3056 #: build/C/man2/perf_event_open.2:722
3057 msgid ""
3058 "Records reasons for transactional memory abort events (for example, from "
3059 "Intel TSX transactional memory support)."
3060 msgstr ""
3061
3062 #. type: Plain text
3063 #: build/C/man2/perf_event_open.2:730
3064 msgid ""
3065 "The I<precise_ip> setting must be greater than 0 and a transactional memory "
3066 "abort event must be measured or no values will be recorded.  Also note that "
3067 "some perf_event measurements, such as sampled cycle counting, may cause "
3068 "extraneous aborts (by causing an interrupt during a transaction)."
3069 msgstr ""
3070
3071 #. type: TP
3072 #: build/C/man2/perf_event_open.2:731
3073 #, no-wrap
3074 msgid "I<read_format>"
3075 msgstr ""
3076
3077 #. type: Plain text
3078 #: build/C/man2/perf_event_open.2:738
3079 msgid ""
3080 "This field specifies the format of the data returned by B<read>(2)  on a "
3081 "B<perf_event_open>()  file descriptor."
3082 msgstr ""
3083
3084 #. type: TP
3085 #: build/C/man2/perf_event_open.2:739
3086 #, no-wrap
3087 msgid "B<PERF_FORMAT_TOTAL_TIME_ENABLED>"
3088 msgstr ""
3089
3090 #. type: Plain text
3091 #: build/C/man2/perf_event_open.2:746
3092 msgid ""
3093 "Adds the 64-bit I<time_enabled> field.  This can be used to calculate "
3094 "estimated totals if the PMU is overcommitted and multiplexing is happening."
3095 msgstr ""
3096
3097 #. type: TP
3098 #: build/C/man2/perf_event_open.2:746
3099 #, no-wrap
3100 msgid "B<PERF_FORMAT_TOTAL_TIME_RUNNING>"
3101 msgstr ""
3102
3103 #. type: Plain text
3104 #: build/C/man2/perf_event_open.2:753
3105 msgid ""
3106 "Adds the 64-bit I<time_running> field.  This can be used to calculate "
3107 "estimated totals if the PMU is overcommitted and multiplexing is happening."
3108 msgstr ""
3109
3110 #. type: TP
3111 #: build/C/man2/perf_event_open.2:753
3112 #, no-wrap
3113 msgid "B<PERF_FORMAT_ID>"
3114 msgstr ""
3115
3116 #. type: Plain text
3117 #: build/C/man2/perf_event_open.2:756
3118 msgid "Adds a 64-bit unique value that corresponds to the event group."
3119 msgstr ""
3120
3121 #. type: TP
3122 #: build/C/man2/perf_event_open.2:756
3123 #, no-wrap
3124 msgid "B<PERF_FORMAT_GROUP>"
3125 msgstr ""
3126
3127 #. type: Plain text
3128 #: build/C/man2/perf_event_open.2:759
3129 msgid "Allows all counter values in an event group to be read with one read."
3130 msgstr ""
3131
3132 #. type: TP
3133 #: build/C/man2/perf_event_open.2:760
3134 #, no-wrap
3135 msgid "I<disabled>"
3136 msgstr ""
3137
3138 #. type: Plain text
3139 #: build/C/man2/perf_event_open.2:770
3140 msgid ""
3141 "The I<disabled> bit specifies whether the counter starts out disabled or "
3142 "enabled.  If disabled, the event can later be enabled by B<ioctl>(2), "
3143 "B<prctl>(2), or I<enable_on_exec>."
3144 msgstr ""
3145
3146 #. type: Plain text
3147 #: build/C/man2/perf_event_open.2:781
3148 msgid ""
3149 "When creating an event group, typically the group leader is initialized with "
3150 "I<disabled> set to 1 and any child events are initialized with I<disabled> "
3151 "set to 0.  Despite I<disabled> being 0, the child events will not start "
3152 "until the group leader is enabled."
3153 msgstr ""
3154
3155 #. type: TP
3156 #: build/C/man2/perf_event_open.2:781
3157 #, no-wrap
3158 msgid "I<inherit>"
3159 msgstr ""
3160
3161 #. type: Plain text
3162 #: build/C/man2/perf_event_open.2:790
3163 msgid ""
3164 "The I<inherit> bit specifies that this counter should count events of child "
3165 "tasks as well as the task specified.  This applies only to new children, not "
3166 "to any existing children at the time the counter is created (nor to any new "
3167 "children of existing children)."
3168 msgstr ""
3169
3170 #. type: Plain text
3171 #: build/C/man2/perf_event_open.2:795
3172 msgid ""
3173 "Inherit does not work for some combinations of I<read_format>s, such as "
3174 "B<PERF_FORMAT_GROUP>."
3175 msgstr ""
3176
3177 #. type: TP
3178 #: build/C/man2/perf_event_open.2:795
3179 #, no-wrap
3180 msgid "I<pinned>"
3181 msgstr ""
3182
3183 #. type: Plain text
3184 #: build/C/man2/perf_event_open.2:808
3185 msgid ""
3186 "The I<pinned> bit specifies that the counter should always be on the CPU if "
3187 "at all possible.  It applies only to hardware counters and only to group "
3188 "leaders.  If a pinned counter cannot be put onto the CPU (e.g., because "
3189 "there are not enough hardware counters or because of a conflict with some "
3190 "other event), then the counter goes into an 'error' state, where reads "
3191 "return end-of-file (i.e., B<read>(2)  returns 0) until the counter is "
3192 "subsequently enabled or disabled."
3193 msgstr ""
3194
3195 #. type: TP
3196 #: build/C/man2/perf_event_open.2:808
3197 #, no-wrap
3198 msgid "I<exclusive>"
3199 msgstr ""
3200
3201 #. type: Plain text
3202 #: build/C/man2/perf_event_open.2:817
3203 msgid ""
3204 "The I<exclusive> bit specifies that when this counter's group is on the CPU, "
3205 "it should be the only group using the CPU's counters.  In the future this "
3206 "may allow monitoring programs to support PMU features that need to run alone "
3207 "so that they do not disrupt other hardware counters."
3208 msgstr ""
3209
3210 #. type: Plain text
3211 #: build/C/man2/perf_event_open.2:824
3212 msgid ""
3213 "Note that many unexpected situations may prevent events with the "
3214 "I<exclusive> bit set from ever running.  This includes any users running a "
3215 "system-wide measurement as well as any kernel use of the performance "
3216 "counters (including the commonly enabled NMI Watchdog Timer interface)."
3217 msgstr ""
3218
3219 #. type: TP
3220 #: build/C/man2/perf_event_open.2:824
3221 #, no-wrap
3222 msgid "I<exclude_user>"
3223 msgstr ""
3224
3225 #. type: Plain text
3226 #: build/C/man2/perf_event_open.2:827
3227 msgid "If this bit is set, the count excludes events that happen in user space."
3228 msgstr ""
3229
3230 #. type: TP
3231 #: build/C/man2/perf_event_open.2:827
3232 #, no-wrap
3233 msgid "I<exclude_kernel>"
3234 msgstr ""
3235
3236 #. type: Plain text
3237 #: build/C/man2/perf_event_open.2:830
3238 msgid "If this bit is set, the count excludes events that happen in kernel-space."
3239 msgstr ""
3240
3241 #. type: TP
3242 #: build/C/man2/perf_event_open.2:830
3243 #, no-wrap
3244 msgid "I<exclude_hv>"
3245 msgstr ""
3246
3247 #. type: Plain text
3248 #: build/C/man2/perf_event_open.2:838
3249 msgid ""
3250 "If this bit is set, the count excludes events that happen in the "
3251 "hypervisor.  This is mainly for PMUs that have built-in support for handling "
3252 "this (such as POWER).  Extra support is needed for handling hypervisor "
3253 "measurements on most machines."
3254 msgstr ""
3255
3256 #. type: TP
3257 #: build/C/man2/perf_event_open.2:838
3258 #, no-wrap
3259 msgid "I<exclude_idle>"
3260 msgstr ""
3261
3262 #. type: Plain text
3263 #: build/C/man2/perf_event_open.2:841
3264 msgid "If set, don't count when the CPU is idle."
3265 msgstr ""
3266
3267 #. type: TP
3268 #: build/C/man2/perf_event_open.2:841
3269 #, no-wrap
3270 msgid "I<mmap>"
3271 msgstr ""
3272
3273 #. type: Plain text
3274 #: build/C/man2/perf_event_open.2:855
3275 msgid ""
3276 "The I<mmap> bit enables generation of B<PERF_RECORD_MMAP> samples for every "
3277 "B<mmap>(2)  call that has B<PROT_EXEC> set.  This allows tools to notice new "
3278 "executable code being mapped into a program (dynamic shared libraries for "
3279 "example)  so that addresses can be mapped back to the original code."
3280 msgstr ""
3281
3282 #. type: TP
3283 #: build/C/man2/perf_event_open.2:855
3284 #, no-wrap
3285 msgid "I<comm>"
3286 msgstr ""
3287
3288 #. type: Plain text
3289 #: build/C/man2/perf_event_open.2:866
3290 msgid ""
3291 "The I<comm> bit enables tracking of process command name as modified by the "
3292 "B<exec>(2)  and B<prctl>(PR_SET_NAME)  system calls.  Unfortunately for "
3293 "tools, there is no way to distinguish one system call versus the other."
3294 msgstr ""
3295
3296 #. type: TP
3297 #: build/C/man2/perf_event_open.2:866
3298 #, no-wrap
3299 msgid "I<freq>"
3300 msgstr ""
3301
3302 #. type: Plain text
3303 #: build/C/man2/perf_event_open.2:873
3304 msgid ""
3305 "If this bit is set, then I<sample_frequency> not I<sample_period> is used "
3306 "when setting up the sampling interval."
3307 msgstr ""
3308
3309 #. type: TP
3310 #: build/C/man2/perf_event_open.2:873
3311 #, no-wrap
3312 msgid "I<inherit_stat>"
3313 msgstr ""
3314
3315 #. type: Plain text
3316 #: build/C/man2/perf_event_open.2:880
3317 msgid ""
3318 "This bit enables saving of event counts on context switch for inherited "
3319 "tasks.  This is meaningful only if the I<inherit> field is set."
3320 msgstr ""
3321
3322 #. type: TP
3323 #: build/C/man2/perf_event_open.2:880
3324 #, no-wrap
3325 msgid "I<enable_on_exec>"
3326 msgstr ""
3327
3328 #. type: Plain text
3329 #: build/C/man2/perf_event_open.2:885
3330 msgid ""
3331 "If this bit is set, a counter is automatically enabled after a call to "
3332 "B<exec>(2)."
3333 msgstr ""
3334
3335 #. type: TP
3336 #: build/C/man2/perf_event_open.2:885
3337 #, no-wrap
3338 msgid "I<task>"
3339 msgstr ""
3340
3341 #. type: Plain text
3342 #: build/C/man2/perf_event_open.2:889
3343 msgid ""
3344 "If this bit is set, then fork/exit notifications are included in the ring "
3345 "buffer."
3346 msgstr ""
3347
3348 #. type: TP
3349 #: build/C/man2/perf_event_open.2:889
3350 #, no-wrap
3351 msgid "I<watermark>"
3352 msgstr ""
3353
3354 #. type: Plain text
3355 #: build/C/man2/perf_event_open.2:897
3356 msgid ""
3357 "If set, have a sampling interrupt happen when we cross the "
3358 "I<wakeup_watermark> boundary.  Otherwise interrupts happen after "
3359 "I<wakeup_events> samples."
3360 msgstr ""
3361
3362 #. type: TP
3363 #: build/C/man2/perf_event_open.2:897
3364 #, no-wrap
3365 msgid "I<precise_ip> (since Linux 2.6.35)"
3366 msgstr ""
3367
3368 #. type: Plain text
3369 #: build/C/man2/perf_event_open.2:907
3370 msgid ""
3371 "This controls the amount of skid.  Skid is how many instructions execute "
3372 "between an event of interest happening and the kernel being able to stop and "
3373 "record the event.  Smaller skid is better and allows more accurate reporting "
3374 "of which events correspond to which instructions, but hardware is often "
3375 "limited with how small this can be."
3376 msgstr ""
3377
3378 #. type: Plain text
3379 #: build/C/man2/perf_event_open.2:909
3380 msgid "The values of this are the following:"
3381 msgstr ""
3382
3383 #. type: TP
3384 #: build/C/man2/perf_event_open.2:910
3385 #, no-wrap
3386 msgid "0 -"
3387 msgstr ""
3388
3389 #. type: Plain text
3390 #: build/C/man2/perf_event_open.2:914
3391 msgid "B<SAMPLE_IP> can have arbitrary skid."
3392 msgstr ""
3393
3394 #. type: TP
3395 #: build/C/man2/perf_event_open.2:914
3396 #, no-wrap
3397 msgid "1 -"
3398 msgstr ""
3399
3400 #. type: Plain text
3401 #: build/C/man2/perf_event_open.2:918
3402 msgid "B<SAMPLE_IP> must have constant skid."
3403 msgstr ""
3404
3405 #. type: TP
3406 #: build/C/man2/perf_event_open.2:918
3407 #, no-wrap
3408 msgid "2 -"
3409 msgstr ""
3410
3411 #. type: Plain text
3412 #: build/C/man2/perf_event_open.2:922
3413 msgid "B<SAMPLE_IP> requested to have 0 skid."
3414 msgstr ""
3415
3416 #. type: TP
3417 #: build/C/man2/perf_event_open.2:922
3418 #, no-wrap
3419 msgid "3 -"
3420 msgstr ""
3421
3422 #. type: Plain text
3423 #: build/C/man2/perf_event_open.2:928
3424 msgid "B<SAMPLE_IP> must have 0 skid.  See also B<PERF_RECORD_MISC_EXACT_IP>."
3425 msgstr ""
3426
3427 #. type: TP
3428 #: build/C/man2/perf_event_open.2:929
3429 #, no-wrap
3430 msgid "I<mmap_data> (since Linux 2.6.36)"
3431 msgstr ""
3432
3433 #. type: Plain text
3434 #: build/C/man2/perf_event_open.2:941
3435 msgid ""
3436 "The counterpart of the I<mmap> field.  This enables generation of "
3437 "B<PERF_RECORD_MMAP> samples for B<mmap>(2)  calls that do not have "
3438 "B<PROT_EXEC> set (for example data and SysV shared memory)."
3439 msgstr ""
3440
3441 #. type: TP
3442 #: build/C/man2/perf_event_open.2:941
3443 #, no-wrap
3444 msgid "I<sample_id_all> (since Linux 2.6.38)"
3445 msgstr ""
3446
3447 #. type: Plain text
3448 #: build/C/man2/perf_event_open.2:949
3449 msgid ""
3450 "If set, then TID, TIME, ID, STREAM_ID, and CPU can additionally be included "
3451 "in non-B<PERF_RECORD_SAMPLE>s if the corresponding I<sample_type> is "
3452 "selected."
3453 msgstr ""
3454
3455 #. type: Plain text
3456 #: build/C/man2/perf_event_open.2:957
3457 msgid ""
3458 "If B<PERF_SAMPLE_IDENTIFIER> is specified, then an additional ID value is "
3459 "included as the last value to ease parsing the record stream.  This may lead "
3460 "to the I<id> value appearing twice."
3461 msgstr ""
3462
3463 #. type: Plain text
3464 #: build/C/man2/perf_event_open.2:959
3465 msgid "The layout is described by this pseudo-structure:"
3466 msgstr ""
3467
3468 #. type: Plain text
3469 #: build/C/man2/perf_event_open.2:969
3470 #, no-wrap
3471 msgid ""
3472 "struct sample_id {\n"
3473 "    { u32 pid, tid; } /* if PERF_SAMPLE_TID set        */\n"
3474 "    { u64 time;     } /* if PERF_SAMPLE_TIME set       */\n"
3475 "    { u64 id;       } /* if PERF_SAMPLE_ID set         */\n"
3476 "    { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set  */\n"
3477 "    { u32 cpu, res; } /* if PERF_SAMPLE_CPU set        */\n"
3478 "    { u64 id;       } /* if PERF_SAMPLE_IDENTIFIER set */\n"
3479 "};\n"
3480 msgstr ""
3481
3482 #. type: TP
3483 #: build/C/man2/perf_event_open.2:970
3484 #, no-wrap
3485 msgid "I<exclude_host> (since Linux 3.2)"
3486 msgstr ""
3487
3488 #. type: Plain text
3489 #: build/C/man2/perf_event_open.2:973
3490 msgid "Do not measure time spent in VM host."
3491 msgstr ""
3492
3493 #. type: TP
3494 #: build/C/man2/perf_event_open.2:973
3495 #, no-wrap
3496 msgid "I<exclude_guest> (since Linux 3.2)"
3497 msgstr ""
3498
3499 #. type: Plain text
3500 #: build/C/man2/perf_event_open.2:976
3501 msgid "Do not measure time spent in VM guest."
3502 msgstr ""
3503
3504 #. type: TP
3505 #: build/C/man2/perf_event_open.2:976
3506 #, no-wrap
3507 msgid "I<exclude_callchain_kernel> (since Linux 3.7)"
3508 msgstr ""
3509
3510 #. type: Plain text
3511 #: build/C/man2/perf_event_open.2:979
3512 msgid "Do not include kernel callchains."
3513 msgstr ""
3514
3515 #. type: TP
3516 #: build/C/man2/perf_event_open.2:979
3517 #, no-wrap
3518 msgid "I<exclude_callchain_user> (since Linux 3.7)"
3519 msgstr ""
3520
3521 #. type: Plain text
3522 #: build/C/man2/perf_event_open.2:982
3523 msgid "Do not include user callchains."
3524 msgstr ""
3525
3526 #. type: TP
3527 #: build/C/man2/perf_event_open.2:982
3528 #, no-wrap
3529 msgid "I<wakeup_events>, I<wakeup_watermark>"
3530 msgstr ""
3531
3532 #. type: Plain text
3533 #: build/C/man2/perf_event_open.2:992
3534 msgid ""
3535 "This union sets how many samples (I<wakeup_events>)  or bytes "
3536 "(I<wakeup_watermark>)  happen before an overflow signal happens.  Which one "
3537 "is used is selected by the I<watermark> bitflag."
3538 msgstr ""
3539
3540 #. type: Plain text
3541 #: build/C/man2/perf_event_open.2:1002
3542 msgid ""
3543 "I<wakeup_events> only counts B<PERF_RECORD_SAMPLE> record types.  To receive "
3544 "a signal for every incoming B<PERF_RECORD> type set I<wakeup_watermark> to "
3545 "1."
3546 msgstr ""
3547
3548 #. type: TP
3549 #: build/C/man2/perf_event_open.2:1002
3550 #, no-wrap
3551 msgid "I<bp_type> (since Linux 2.6.33)"
3552 msgstr ""
3553
3554 #. type: Plain text
3555 #: build/C/man2/perf_event_open.2:1006
3556 msgid "This chooses the breakpoint type.  It is one of:"
3557 msgstr ""
3558
3559 #. type: TP
3560 #: build/C/man2/perf_event_open.2:1007
3561 #, no-wrap
3562 msgid "B<HW_BREAKPOINT_EMPTY>"
3563 msgstr ""
3564
3565 #. type: Plain text
3566 #: build/C/man2/perf_event_open.2:1010
3567 msgid "No breakpoint."
3568 msgstr ""
3569
3570 #. type: TP
3571 #: build/C/man2/perf_event_open.2:1010
3572 #, no-wrap
3573 msgid "B<HW_BREAKPOINT_R>"
3574 msgstr ""
3575
3576 #. type: Plain text
3577 #: build/C/man2/perf_event_open.2:1013
3578 msgid "Count when we read the memory location."
3579 msgstr ""
3580
3581 #. type: TP
3582 #: build/C/man2/perf_event_open.2:1013
3583 #, no-wrap
3584 msgid "B<HW_BREAKPOINT_W>"
3585 msgstr ""
3586
3587 #. type: Plain text
3588 #: build/C/man2/perf_event_open.2:1016
3589 msgid "Count when we write the memory location."
3590 msgstr ""
3591
3592 #. type: TP
3593 #: build/C/man2/perf_event_open.2:1016
3594 #, no-wrap
3595 msgid "B<HW_BREAKPOINT_RW>"
3596 msgstr ""
3597
3598 #. type: Plain text
3599 #: build/C/man2/perf_event_open.2:1019
3600 msgid "Count when we read or write the memory location."
3601 msgstr ""
3602
3603 #. type: TP
3604 #: build/C/man2/perf_event_open.2:1019
3605 #, no-wrap
3606 msgid "B<HW_BREAKPOINT_X>"
3607 msgstr ""
3608
3609 #. type: Plain text
3610 #: build/C/man2/perf_event_open.2:1022
3611 msgid "Count when we execute code at the memory location."
3612 msgstr ""
3613
3614 #. type: Plain text
3615 #: build/C/man2/perf_event_open.2:1031
3616 msgid ""
3617 "The values can be combined via a bitwise or, but the combination of "
3618 "B<HW_BREAKPOINT_R> or B<HW_BREAKPOINT_W> with B<HW_BREAKPOINT_X> is not "
3619 "allowed."
3620 msgstr ""
3621
3622 #. type: TP
3623 #: build/C/man2/perf_event_open.2:1032
3624 #, no-wrap
3625 msgid "I<bp_addr> (since Linux 2.6.33)"
3626 msgstr ""
3627
3628 #. type: Plain text
3629 #: build/C/man2/perf_event_open.2:1039
3630 msgid ""
3631 "I<bp_addr> address of the breakpoint.  For execution breakpoints this is the "
3632 "memory address of the instruction of interest; for read and write "
3633 "breakpoints it is the memory address of the memory location of interest."
3634 msgstr ""
3635
3636 #. type: TP
3637 #: build/C/man2/perf_event_open.2:1039
3638 #, no-wrap
3639 msgid "I<config1> (since Linux 2.6.39)"
3640 msgstr ""
3641
3642 #. type: Plain text
3643 #: build/C/man2/perf_event_open.2:1046
3644 msgid ""
3645 "I<config1> is used for setting events that need an extra register or "
3646 "otherwise do not fit in the regular config field.  Raw OFFCORE_EVENTS on "
3647 "Nehalem/Westmere/SandyBridge use this field on 3.3 and later kernels."
3648 msgstr ""
3649
3650 #. type: TP
3651 #: build/C/man2/perf_event_open.2:1046
3652 #, no-wrap
3653 msgid "I<bp_len> (since Linux 2.6.33)"
3654 msgstr ""
3655
3656 #. type: Plain text
3657 #: build/C/man2/perf_event_open.2:1060
3658 msgid ""
3659 "I<bp_len> is the length of the breakpoint being measured if I<type> is "
3660 "B<PERF_TYPE_BREAKPOINT>.  Options are B<HW_BREAKPOINT_LEN_1>, "
3661 "B<HW_BREAKPOINT_LEN_2>, B<HW_BREAKPOINT_LEN_4>, B<HW_BREAKPOINT_LEN_8>.  For "
3662 "an execution breakpoint, set this to I<sizeof(long)>."
3663 msgstr ""
3664
3665 #. type: TP
3666 #: build/C/man2/perf_event_open.2:1060
3667 #, no-wrap
3668 msgid "I<config2> (since Linux 2.6.39)"
3669 msgstr ""
3670
3671 #. type: Plain text
3672 #: build/C/man2/perf_event_open.2:1067
3673 msgid "I<config2> is a further extension of the I<config1> field."
3674 msgstr ""
3675
3676 #. type: TP
3677 #: build/C/man2/perf_event_open.2:1067
3678 #, no-wrap
3679 msgid "I<branch_sample_type> (since Linux 3.4)"
3680 msgstr ""
3681
3682 #. type: Plain text
3683 #: build/C/man2/perf_event_open.2:1073
3684 msgid ""
3685 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then this specifies what branches "
3686 "to include in the branch record."
3687 msgstr ""
3688
3689 #. type: Plain text
3690 #: build/C/man2/perf_event_open.2:1079
3691 msgid ""
3692 "The first part of the value is the privilege level, which is a combination "
3693 "of one of the following values.  If the user does not set privilege level "
3694 "explicitly, the kernel will use the event's privilege level.  Event and "
3695 "branch privilege levels do not have to match."
3696 msgstr ""
3697
3698 #. type: TP
3699 #: build/C/man2/perf_event_open.2:1080
3700 #, no-wrap
3701 msgid "B<PERF_SAMPLE_BRANCH_USER>"
3702 msgstr ""
3703
3704 #. type: Plain text
3705 #: build/C/man2/perf_event_open.2:1083
3706 msgid "Branch target is in user space."
3707 msgstr ""
3708
3709 #. type: TP
3710 #: build/C/man2/perf_event_open.2:1083
3711 #, no-wrap
3712 msgid "B<PERF_SAMPLE_BRANCH_KERNEL>"
3713 msgstr ""
3714
3715 #. type: Plain text
3716 #: build/C/man2/perf_event_open.2:1086
3717 msgid "Branch target is in kernel space."
3718 msgstr ""
3719
3720 #. type: TP
3721 #: build/C/man2/perf_event_open.2:1086
3722 #, no-wrap
3723 msgid "B<PERF_SAMPLE_BRANCH_HV>"
3724 msgstr ""
3725
3726 #. type: Plain text
3727 #: build/C/man2/perf_event_open.2:1089
3728 msgid "Branch target is in hypervisor."
3729 msgstr ""
3730
3731 #. type: TP
3732 #: build/C/man2/perf_event_open.2:1089
3733 #, no-wrap
3734 msgid "B<PERF_SAMPLE_BRANCH_PLM_ALL>"
3735 msgstr ""
3736
3737 #. type: Plain text
3738 #: build/C/man2/perf_event_open.2:1092
3739 msgid "A convenience value that is the three preceding values ORed together."
3740 msgstr ""
3741
3742 #. type: Plain text
3743 #: build/C/man2/perf_event_open.2:1096
3744 msgid ""
3745 "In addition to the privilege value, at least one or more of the following "
3746 "bits must be set."
3747 msgstr ""
3748
3749 #. type: TP
3750 #: build/C/man2/perf_event_open.2:1097
3751 #, no-wrap
3752 msgid "B<PERF_SAMPLE_BRANCH_ANY>"
3753 msgstr ""
3754
3755 #. type: Plain text
3756 #: build/C/man2/perf_event_open.2:1100
3757 msgid "Any branch type."
3758 msgstr ""
3759
3760 #. type: TP
3761 #: build/C/man2/perf_event_open.2:1100
3762 #, no-wrap
3763 msgid "B<PERF_SAMPLE_BRANCH_ANY_CALL>"
3764 msgstr ""
3765
3766 #. type: Plain text
3767 #: build/C/man2/perf_event_open.2:1103
3768 msgid "Any call branch."
3769 msgstr ""
3770
3771 #. type: TP
3772 #: build/C/man2/perf_event_open.2:1103
3773 #, no-wrap
3774 msgid "B<PERF_SAMPLE_BRANCH_ANY_RETURN>"
3775 msgstr ""
3776
3777 #. type: Plain text
3778 #: build/C/man2/perf_event_open.2:1106
3779 msgid "Any return branch."
3780 msgstr ""
3781
3782 #. type: TP
3783 #: build/C/man2/perf_event_open.2:1106
3784 #, no-wrap
3785 msgid "B<PERF_SAMPLE_BRANCH_IND_CALL>"
3786 msgstr ""
3787
3788 #. type: Plain text
3789 #: build/C/man2/perf_event_open.2:1109
3790 msgid "Indirect calls."
3791 msgstr ""
3792
3793 #. type: TP
3794 #: build/C/man2/perf_event_open.2:1109
3795 #, no-wrap
3796 msgid "B<PERF_SAMPLE_BRANCH_ABORT_TX> (since Linux 3.11)"
3797 msgstr ""
3798
3799 #. type: Plain text
3800 #: build/C/man2/perf_event_open.2:1112
3801 msgid "Transactional memory aborts."
3802 msgstr ""
3803
3804 #. type: TP
3805 #: build/C/man2/perf_event_open.2:1112
3806 #, no-wrap
3807 msgid "B<PERF_SAMPLE_BRANCH_IN_TX> (since Linux 3.11)"
3808 msgstr ""
3809
3810 #. type: Plain text
3811 #: build/C/man2/perf_event_open.2:1115
3812 msgid "Branch in transactional memory transaction."
3813 msgstr ""
3814
3815 #. type: TP
3816 #: build/C/man2/perf_event_open.2:1115
3817 #, no-wrap
3818 msgid "B<PERF_SAMPLE_BRANCH_NO_TX> (since Linux 3.11)"
3819 msgstr ""
3820
3821 #. type: Plain text
3822 #: build/C/man2/perf_event_open.2:1118
3823 msgid "Branch not in transactional memory transaction."
3824 msgstr ""
3825
3826 #. type: TP
3827 #: build/C/man2/perf_event_open.2:1120
3828 #, no-wrap
3829 msgid "I<sample_regs_user> (since Linux 3.7)"
3830 msgstr ""
3831
3832 #. type: Plain text
3833 #: build/C/man2/perf_event_open.2:1126
3834 msgid ""
3835 "This bit mask defines the set of user CPU registers to dump on samples.  The "
3836 "layout of the register mask is architecture-specific and described in the "
3837 "kernel header I<arch/ARCH/include/uapi/asm/perf_regs.h>."
3838 msgstr ""
3839
3840 #. type: TP
3841 #: build/C/man2/perf_event_open.2:1126
3842 #, no-wrap
3843 msgid "I<sample_stack_user> (since Linux 3.7)"
3844 msgstr ""
3845
3846 #. type: Plain text
3847 #: build/C/man2/perf_event_open.2:1131
3848 msgid ""
3849 "This defines the size of the user stack to dump if B<PERF_SAMPLE_STACK_USER> "
3850 "is specified."
3851 msgstr ""
3852
3853 #. type: SS
3854 #: build/C/man2/perf_event_open.2:1131
3855 #, no-wrap
3856 msgid "Reading results"
3857 msgstr ""
3858
3859 #. type: Plain text
3860 #: build/C/man2/perf_event_open.2:1141
3861 msgid ""
3862 "Once a B<perf_event_open>()  file descriptor has been opened, the values of "
3863 "the events can be read from the file descriptor.  The values that are there "
3864 "are specified by the I<read_format> field in the I<attr> structure at open "
3865 "time."
3866 msgstr ""
3867
3868 #. type: Plain text
3869 #: build/C/man2/perf_event_open.2:1146
3870 msgid ""
3871 "If you attempt to read into a buffer that is not big enough to hold the data "
3872 "B<ENOSPC> is returned"
3873 msgstr ""
3874
3875 #. type: Plain text
3876 #: build/C/man2/perf_event_open.2:1148
3877 msgid "Here is the layout of the data returned by a read:"
3878 msgstr ""
3879
3880 #. type: IP
3881 #: build/C/man2/perf_event_open.2:1148 build/C/man2/perf_event_open.2:1166 build/C/man2/ptrace.2:1692 build/C/man2/ptrace.2:1702 build/C/man2/ptrace.2:1710 build/C/man2/ptrace.2:1716 build/C/man2/ptrace.2:1845
3882 #, no-wrap
3883 msgid "*"
3884 msgstr ""
3885
3886 #. type: Plain text
3887 #: build/C/man2/perf_event_open.2:1152
3888 msgid ""
3889 "If B<PERF_FORMAT_GROUP> was specified to allow reading all events in a group "
3890 "at once:"
3891 msgstr ""
3892
3893 #. type: Plain text
3894 #: build/C/man2/perf_event_open.2:1164
3895 #, no-wrap
3896 msgid ""
3897 "struct read_format {\n"
3898 "    u64 nr;            /* The number of events */\n"
3899 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3900 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3901 "    struct\n"
3902 "        u64 value;     /* The value of the event */\n"
3903 "        u64 id;        /* if PERF_FORMAT_ID */\n"
3904 "    } values[nr];\n"
3905 "};\n"
3906 msgstr ""
3907
3908 #. type: Plain text
3909 #: build/C/man2/perf_event_open.2:1172
3910 msgid "If B<PERF_FORMAT_GROUP> was I<not> specified:"
3911 msgstr ""
3912
3913 #. type: Plain text
3914 #: build/C/man2/perf_event_open.2:1181
3915 #, no-wrap
3916 msgid ""
3917 "struct read_format {\n"
3918 "    u64 value;         /* The value of the event */\n"
3919 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3920 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3921 "    u64 id;            /* if PERF_FORMAT_ID */\n"
3922 "};\n"
3923 msgstr ""
3924
3925 #. type: Plain text
3926 #: build/C/man2/perf_event_open.2:1185
3927 msgid "The values read are as follows:"
3928 msgstr ""
3929
3930 #. type: TP
3931 #: build/C/man2/perf_event_open.2:1185
3932 #, no-wrap
3933 msgid "I<nr>"
3934 msgstr ""
3935
3936 #. type: Plain text
3937 #: build/C/man2/perf_event_open.2:1191
3938 msgid ""
3939 "The number of events in this file descriptor.  Only available if "
3940 "B<PERF_FORMAT_GROUP> was specified."
3941 msgstr ""
3942
3943 #. type: TP
3944 #: build/C/man2/perf_event_open.2:1191
3945 #, no-wrap
3946 msgid "I<time_enabled>, I<time_running>"
3947 msgstr ""
3948
3949 #. type: Plain text
3950 #: build/C/man2/perf_event_open.2:1203
3951 msgid ""
3952 "Total time the event was enabled and running.  Normally these are the same.  "
3953 "If more events are started, then available counter slots on the PMU, then "
3954 "multiplexing happens and events run only part of the time.  In that case, "
3955 "the I<time_enabled> and I<time running> values can be used to scale an "
3956 "estimated value for the count."
3957 msgstr ""
3958
3959 #. type: TP
3960 #: build/C/man2/perf_event_open.2:1203
3961 #, no-wrap
3962 msgid "I<value>"
3963 msgstr ""
3964
3965 #. type: Plain text
3966 #: build/C/man2/perf_event_open.2:1206
3967 msgid "An unsigned 64-bit value containing the counter result."
3968 msgstr ""
3969
3970 #. type: TP
3971 #: build/C/man2/perf_event_open.2:1206 build/C/man2/perf_event_open.2:1602 build/C/man2/perf_event_open.2:1756
3972 #, no-wrap
3973 msgid "I<id>"
3974 msgstr ""
3975
3976 #. type: Plain text
3977 #: build/C/man2/perf_event_open.2:1212
3978 msgid ""
3979 "A globally unique value for this particular event, only there if "
3980 "B<PERF_FORMAT_ID> was specified in I<read_format>."
3981 msgstr ""
3982
3983 #. type: SS
3984 #: build/C/man2/perf_event_open.2:1212
3985 #, no-wrap
3986 msgid "MMAP layout"
3987 msgstr ""
3988
3989 #. type: Plain text
3990 #: build/C/man2/perf_event_open.2:1222
3991 msgid ""
3992 "When using B<perf_event_open>()  in sampled mode, asynchronous events (like "
3993 "counter overflow or B<PROT_EXEC> mmap tracking)  are logged into a "
3994 "ring-buffer.  This ring-buffer is created and accessed through B<mmap>(2)."
3995 msgstr ""
3996
3997 #. type: Plain text
3998 #: build/C/man2/perf_event_open.2:1228
3999 msgid ""
4000 "The mmap size should be 1+2^n pages, where the first page is a metadata page "
4001 "(I<struct perf_event_mmap_page>)  that contains various bits of information "
4002 "such as where the ring-buffer head is."
4003 msgstr ""
4004
4005 #. type: Plain text
4006 #: build/C/man2/perf_event_open.2:1231
4007 msgid ""
4008 "Before kernel 2.6.39, there is a bug that means you must allocate a mmap "
4009 "ring buffer when sampling even if you do not plan to access it."
4010 msgstr ""
4011
4012 #. type: Plain text
4013 #: build/C/man2/perf_event_open.2:1233
4014 msgid "The structure of the first metadata mmap page is as follows:"
4015 msgstr ""
4016
4017 #. type: Plain text
4018 #: build/C/man2/perf_event_open.2:1262
4019 #, no-wrap
4020 msgid ""
4021 "struct perf_event_mmap_page {\n"
4022 "    __u32 version;        /* version number of this structure */\n"
4023 "    __u32 compat_version; /* lowest version this is compat with */\n"
4024 "    __u32 lock;           /* seqlock for synchronization */\n"
4025 "    __u32 index;          /* hardware counter identifier */\n"
4026 "    __s64 offset;         /* add to hardware counter value */\n"
4027 "    __u64 time_enabled;   /* time event active */\n"
4028 "    __u64 time_running;   /* time event on CPU */\n"
4029 "    union {\n"
4030 "        __u64   capabilities;\n"
4031 "        struct {\n"
4032 "            __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,\n"
4033 "                  cap_bit0_is_deprecated : 1,\n"
4034 "                  cap_user_rdpmc         : 1,\n"
4035 "                  cap_user_time          : 1,\n"
4036 "                  cap_user_time_zero     : 1,\n"
4037 "        };\n"
4038 "    };\n"
4039 "    __u16 pmc_width;\n"
4040 "    __u16 time_shift;\n"
4041 "    __u32 time_mult;\n"
4042 "    __u64 time_offset;\n"
4043 "    __u64 __reserved[120];   /* Pad to 1k */\n"
4044 "    __u64 data_head;         /* head in the data section */\n"
4045 "    __u64 data_tail;         /* user-space written tail */\n"
4046 "}\n"
4047 msgstr ""
4048
4049 #. type: Plain text
4050 #: build/C/man2/perf_event_open.2:1268
4051 msgid ""
4052 "The following list describes the fields in the I<perf_event_mmap_page> "
4053 "structure in more detail:"
4054 msgstr ""
4055
4056 #. type: TP
4057 #: build/C/man2/perf_event_open.2:1268
4058 #, no-wrap
4059 msgid "I<version>"
4060 msgstr ""
4061
4062 #. type: Plain text
4063 #: build/C/man2/perf_event_open.2:1271
4064 msgid "Version number of this structure."
4065 msgstr ""
4066
4067 #. type: TP
4068 #: build/C/man2/perf_event_open.2:1271
4069 #, no-wrap
4070 msgid "I<compat_version>"
4071 msgstr ""
4072
4073 #. type: Plain text
4074 #: build/C/man2/perf_event_open.2:1274
4075 msgid "The lowest version this is compatible with."
4076 msgstr ""
4077
4078 #. type: TP
4079 #: build/C/man2/perf_event_open.2:1274
4080 #, no-wrap
4081 msgid "I<lock>"
4082 msgstr ""
4083
4084 #. type: Plain text
4085 #: build/C/man2/perf_event_open.2:1277
4086 msgid "A seqlock for synchronization."
4087 msgstr ""
4088
4089 #. type: TP
4090 #: build/C/man2/perf_event_open.2:1277
4091 #, no-wrap
4092 msgid "I<index>"
4093 msgstr ""
4094
4095 #. type: Plain text
4096 #: build/C/man2/perf_event_open.2:1280
4097 msgid "A unique hardware counter identifier."
4098 msgstr ""
4099
4100 #. type: TP
4101 #: build/C/man2/perf_event_open.2:1280
4102 #, no-wrap
4103 msgid "I<offset>"
4104 msgstr ""
4105
4106 #. type: Plain text
4107 #: build/C/man2/perf_event_open.2:1285
4108 msgid ""
4109 "When using rdpmc for reads this offset value must be added to the one "
4110 "returned by rdpmc to get the current total event count."
4111 msgstr ""
4112
4113 #. type: TP
4114 #: build/C/man2/perf_event_open.2:1285
4115 #, no-wrap
4116 msgid "I<time_enabled>"
4117 msgstr ""
4118
4119 #. type: Plain text
4120 #: build/C/man2/perf_event_open.2:1288
4121 msgid "Time the event was active."
4122 msgstr ""
4123
4124 #. type: TP
4125 #: build/C/man2/perf_event_open.2:1288
4126 #, no-wrap
4127 msgid "I<time_running>"
4128 msgstr ""
4129
4130 #. type: Plain text
4131 #: build/C/man2/perf_event_open.2:1291
4132 msgid "Time the event was running."
4133 msgstr ""
4134
4135 #. type: TP
4136 #: build/C/man2/perf_event_open.2:1291
4137 #, no-wrap
4138 msgid "I<cap_usr_time> / I<cap_usr_rdpmc> / I<cap_bit0> (since Linux 3.4)"
4139 msgstr ""
4140
4141 #. type: Plain text
4142 #: build/C/man2/perf_event_open.2:1304
4143 msgid ""
4144 "There was a bug in the definition of I<cap_usr_time> and I<cap_usr_rdpmc> "
4145 "from Linux 3.4 until Linux 3.11.  Both bits were defined to point to the "
4146 "same location, so it was impossible to know if I<cap_usr_time> or "
4147 "I<cap_usr_rdpmc> were actually set."
4148 msgstr ""
4149
4150 #. type: Plain text
4151 #: build/C/man2/perf_event_open.2:1312
4152 msgid ""
4153 "Starting with 3.12 these are renamed to I<cap_bit0> and you should use the "
4154 "new I<cap_user_time> and I<cap_user_rdpmc> fields instead."
4155 msgstr ""
4156
4157 #. type: TP
4158 #: build/C/man2/perf_event_open.2:1313
4159 #, no-wrap
4160 msgid "I<cap_bit0_is_deprecated> (since Linux 3.12)"
4161 msgstr ""
4162
4163 #. type: Plain text
4164 #: build/C/man2/perf_event_open.2:1321
4165 msgid ""
4166 "If set, this bit indicates that the kernel supports the properly separated "
4167 "I<cap_user_time> and I<cap_user_rdpmc> bits."
4168 msgstr ""
4169
4170 #. type: Plain text
4171 #: build/C/man2/perf_event_open.2:1328
4172 msgid ""
4173 "If not-set, it indicates an older kernel where I<cap_usr_time> and "
4174 "I<cap_usr_rdpmc> map to the same bit and thus both features should be used "
4175 "with caution."
4176 msgstr ""
4177
4178 #. type: TP
4179 #: build/C/man2/perf_event_open.2:1329
4180 #, no-wrap
4181 msgid "I<cap_user_rdpmc> (since Linux 3.12)"
4182 msgstr ""
4183
4184 #. type: Plain text
4185 #: build/C/man2/perf_event_open.2:1334
4186 msgid ""
4187 "If the hardware supports user-space read of performance counters without "
4188 "syscall (this is the \"rdpmc\" instruction on x86), then the following code "
4189 "can be used to do a read:"
4190 msgstr ""
4191
4192 #. type: Plain text
4193 #: build/C/man2/perf_event_open.2:1340
4194 #, no-wrap
4195 msgid ""
4196 "u32 seq, time_mult, time_shift, idx, width;\n"
4197 "u64 count, enabled, running;\n"
4198 "u64 cyc, time_offset;\n"
4199 msgstr ""
4200
4201 #. type: Plain text
4202 #: build/C/man2/perf_event_open.2:1346
4203 #, no-wrap
4204 msgid ""
4205 "do {\n"
4206 "    seq = pc-E<gt>lock;\n"
4207 "    barrier();\n"
4208 "    enabled = pc-E<gt>time_enabled;\n"
4209 "    running = pc-E<gt>time_running;\n"
4210 msgstr ""
4211
4212 #. type: Plain text
4213 #: build/C/man2/perf_event_open.2:1353
4214 #, no-wrap
4215 msgid ""
4216 "    if (pc-E<gt>cap_usr_time && enabled != running) {\n"
4217 "        cyc = rdtsc();\n"
4218 "        time_offset = pc-E<gt>time_offset;\n"
4219 "        time_mult   = pc-E<gt>time_mult;\n"
4220 "        time_shift  = pc-E<gt>time_shift;\n"
4221 "    }\n"
4222 msgstr ""
4223
4224 #. type: Plain text
4225 #: build/C/man2/perf_event_open.2:1356
4226 #, no-wrap
4227 msgid ""
4228 "    idx = pc-E<gt>index;\n"
4229 "    count = pc-E<gt>offset;\n"
4230 msgstr ""
4231
4232 #. type: Plain text
4233 #: build/C/man2/perf_event_open.2:1361
4234 #, no-wrap
4235 msgid ""
4236 "    if (pc-E<gt>cap_usr_rdpmc && idx) {\n"
4237 "        width = pc-E<gt>pmc_width;\n"
4238 "        count += rdpmc(idx - 1);\n"
4239 "    }\n"
4240 msgstr ""
4241
4242 #. type: Plain text
4243 #: build/C/man2/perf_event_open.2:1364
4244 #, no-wrap
4245 msgid ""
4246 "    barrier();\n"
4247 "} while (pc-E<gt>lock != seq);\n"
4248 msgstr ""
4249
4250 #. type: TP
4251 #: build/C/man2/perf_event_open.2:1366
4252 #, no-wrap
4253 msgid "I<cap_user_time  (since Linux 3.12)>"
4254 msgstr ""
4255
4256 #. type: Plain text
4257 #: build/C/man2/perf_event_open.2:1370
4258 msgid ""
4259 "This bit indicates the hardware has a constant, nonstop timestamp counter "
4260 "(TSC on x86)."
4261 msgstr ""
4262
4263 #. type: TP
4264 #: build/C/man2/perf_event_open.2:1370
4265 #, no-wrap
4266 msgid "I<cap_user_time_zero> (since Linux 3.12)"
4267 msgstr ""
4268
4269 #. type: Plain text
4270 #: build/C/man2/perf_event_open.2:1376
4271 msgid ""
4272 "Indicates the presence of I<time_zero> which allows mapping timestamp values "
4273 "to the hardware clock."
4274 msgstr ""
4275
4276 #. type: TP
4277 #: build/C/man2/perf_event_open.2:1376
4278 #, no-wrap
4279 msgid "I<pmc_width>"
4280 msgstr ""
4281
4282 #. type: Plain text
4283 #: build/C/man2/perf_event_open.2:1383
4284 msgid ""
4285 "If I<cap_usr_rdpmc>, this field provides the bit-width of the value read "
4286 "using the rdpmc or equivalent instruction.  This can be used to sign extend "
4287 "the result like:"
4288 msgstr ""
4289
4290 #. type: Plain text
4291 #: build/C/man2/perf_event_open.2:1389
4292 #, no-wrap
4293 msgid ""
4294 "pmc E<lt>E<lt>= 64 - pmc_width;\n"
4295 "pmc E<gt>E<gt>= 64 - pmc_width; // signed shift right\n"
4296 "count += pmc;\n"
4297 msgstr ""
4298
4299 #. type: TP
4300 #: build/C/man2/perf_event_open.2:1391
4301 #, no-wrap
4302 msgid "I<time_shift>, I<time_mult>, I<time_offset>"
4303 msgstr ""
4304
4305 #. type: Plain text
4306 #: build/C/man2/perf_event_open.2:1398
4307 msgid ""
4308 "If I<cap_usr_time>, these fields can be used to compute the time delta since "
4309 "time_enabled (in nanoseconds) using rdtsc or similar."
4310 msgstr ""
4311
4312 #. type: Plain text
4313 #: build/C/man2/perf_event_open.2:1406
4314 #, no-wrap
4315 msgid ""
4316 "    u64 quot, rem;\n"
4317 "    u64 delta;\n"
4318 "    quot = (cyc E<gt>E<gt> time_shift);\n"
4319 "    rem = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
4320 "    delta = time_offset + quot * time_mult +\n"
4321 "            ((rem * time_mult) E<gt>E<gt> time_shift);\n"
4322 msgstr ""
4323
4324 #. type: Plain text
4325 #: build/C/man2/perf_event_open.2:1418
4326 msgid ""
4327 "Where I<time_offset>, I<time_mult>, I<time_shift>, and I<cyc> are read in "
4328 "the seqcount loop described above.  This delta can then be added to enabled "
4329 "and possible running (if idx), improving the scaling:"
4330 msgstr ""
4331
4332 #. type: Plain text
4333 #: build/C/man2/perf_event_open.2:1426
4334 #, no-wrap
4335 msgid ""
4336 "    enabled += delta;\n"
4337 "    if (idx)\n"
4338 "        running += delta;\n"
4339 "    quot = count / running;\n"
4340 "    rem  = count % running;\n"
4341 "    count = quot * enabled + (rem * enabled) / running;\n"
4342 msgstr ""
4343
4344 #. type: TP
4345 #: build/C/man2/perf_event_open.2:1427
4346 #, no-wrap
4347 msgid "I<time_zero> (since Linux 3.12)"
4348 msgstr ""
4349
4350 #. type: Plain text
4351 #: build/C/man2/perf_event_open.2:1435
4352 msgid ""
4353 "If I<cap_usr_time_zero> is set, then the hardware clock (the TSC timestamp "
4354 "counter on x86)  can be calculated from the I<time_zero>, I<time_mult>, and "
4355 "I<time_shift> values:"
4356 msgstr ""
4357
4358 #. type: Plain text
4359 #: build/C/man2/perf_event_open.2:1441
4360 #, no-wrap
4361 msgid ""
4362 "    time = timestamp - time_zero;\n"
4363 "    quot = time / time_mult;\n"
4364 "    rem  = time % time_mult;\n"
4365 "    cyc = (quot E<lt>E<lt> time_shift) + (rem E<lt>E<lt> time_shift) / "
4366 "time_mult;\n"
4367 msgstr ""
4368
4369 #. type: Plain text
4370 #: build/C/man2/perf_event_open.2:1444
4371 msgid "And vice versa:"
4372 msgstr ""
4373
4374 #. type: Plain text
4375 #: build/C/man2/perf_event_open.2:1450
4376 #, no-wrap
4377 msgid ""
4378 "    quot = cyc E<gt>E<gt> time_shift;\n"
4379 "    rem  = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
4380 "    timestamp = time_zero + quot * time_mult +\n"
4381 "        ((rem * time_mult) E<gt>E<gt> time_shift);\n"
4382 msgstr ""
4383
4384 #. type: TP
4385 #: build/C/man2/perf_event_open.2:1451
4386 #, no-wrap
4387 msgid "I<data_head>"
4388 msgstr ""
4389
4390 #. type: Plain text
4391 #: build/C/man2/perf_event_open.2:1457
4392 msgid ""
4393 "This points to the head of the data section.  The value continuously "
4394 "increases, it does not wrap.  The value needs to be manually wrapped by the "
4395 "size of the mmap buffer before accessing the samples."
4396 msgstr ""
4397
4398 #. type: Plain text
4399 #: build/C/man2/perf_event_open.2:1462
4400 msgid ""
4401 "On SMP-capable platforms, after reading the I<data_head> value, user space "
4402 "should issue an rmb()."
4403 msgstr ""
4404
4405 #. type: TP
4406 #: build/C/man2/perf_event_open.2:1462
4407 #, no-wrap
4408 msgid "I<data_tail>"
4409 msgstr ""
4410
4411 #. type: Plain text
4412 #: build/C/man2/perf_event_open.2:1470
4413 msgid ""
4414 "When the mapping is B<PROT_WRITE>, the I<data_tail> value should be written "
4415 "by user space to reflect the last read data.  In this case, the kernel will "
4416 "not overwrite unread data."
4417 msgstr ""
4418
4419 #. type: Plain text
4420 #: build/C/man2/perf_event_open.2:1472
4421 msgid "The following 2^n ring-buffer pages have the layout described below."
4422 msgstr ""
4423
4424 #. type: Plain text
4425 #: build/C/man2/perf_event_open.2:1486
4426 msgid ""
4427 "If I<perf_event_attr.sample_id_all> is set, then all event types will have "
4428 "the sample_type selected fields related to where/when (identity)  an event "
4429 "took place (TID, TIME, ID, CPU, STREAM_ID) described in "
4430 "B<PERF_RECORD_SAMPLE> below, it will be stashed just after the "
4431 "I<perf_event_header> and the fields already present for the existing fields, "
4432 "that is, at the end of the payload.  That way a newer perf.data file will be "
4433 "supported by older perf tools, with these new optional fields being ignored."
4434 msgstr ""
4435
4436 #. type: Plain text
4437 #: build/C/man2/perf_event_open.2:1488
4438 msgid "The mmap values start with a header:"
4439 msgstr ""
4440
4441 #. type: Plain text
4442 #: build/C/man2/perf_event_open.2:1496
4443 #, no-wrap
4444 msgid ""
4445 "struct perf_event_header {\n"
4446 "    __u32   type;\n"
4447 "    __u16   misc;\n"
4448 "    __u16   size;\n"
4449 "};\n"
4450 msgstr ""
4451
4452 #. type: Plain text
4453 #: build/C/man2/perf_event_open.2:1504
4454 msgid ""
4455 "Below, we describe the I<perf_event_header> fields in more detail.  For ease "
4456 "of reading, the fields with shorter descriptions are presented first."
4457 msgstr ""
4458
4459 #. type: Plain text
4460 #: build/C/man2/perf_event_open.2:1507
4461 msgid "This indicates the size of the record."
4462 msgstr ""
4463
4464 #. type: TP
4465 #: build/C/man2/perf_event_open.2:1507
4466 #, no-wrap
4467 msgid "I<misc>"
4468 msgstr ""
4469
4470 #. type: Plain text
4471 #: build/C/man2/perf_event_open.2:1512
4472 msgid "The I<misc> field contains additional information about the sample."
4473 msgstr ""
4474
4475 #. type: Plain text
4476 #: build/C/man2/perf_event_open.2:1517
4477 msgid ""
4478 "The CPU mode can be determined from this value by masking with "
4479 "B<PERF_RECORD_MISC_CPUMODE_MASK> and looking for one of the following (note "
4480 "these are not bit masks, only one can be set at a time):"
4481 msgstr ""
4482
4483 #. type: TP
4484 #: build/C/man2/perf_event_open.2:1518
4485 #, no-wrap
4486 msgid "B<PERF_RECORD_MISC_CPUMODE_UNKNOWN>"
4487 msgstr ""
4488
4489 #. type: Plain text
4490 #: build/C/man2/perf_event_open.2:1521
4491 msgid "Unknown CPU mode."
4492 msgstr ""
4493
4494 #. type: TP
4495 #: build/C/man2/perf_event_open.2:1521
4496 #, no-wrap
4497 msgid "B<PERF_RECORD_MISC_KERNEL>"
4498 msgstr ""
4499
4500 #. type: Plain text
4501 #: build/C/man2/perf_event_open.2:1524
4502 msgid "Sample happened in the kernel."
4503 msgstr ""
4504
4505 #. type: TP
4506 #: build/C/man2/perf_event_open.2:1524
4507 #, no-wrap
4508 msgid "B<PERF_RECORD_MISC_USER>"
4509 msgstr ""
4510
4511 #. type: Plain text
4512 #: build/C/man2/perf_event_open.2:1527
4513 msgid "Sample happened in user code."
4514 msgstr ""
4515
4516 #. type: TP
4517 #: build/C/man2/perf_event_open.2:1527
4518 #, no-wrap
4519 msgid "B<PERF_RECORD_MISC_HYPERVISOR>"
4520 msgstr ""
4521
4522 #. type: Plain text
4523 #: build/C/man2/perf_event_open.2:1530
4524 msgid "Sample happened in the hypervisor."
4525 msgstr ""
4526
4527 #. type: TP
4528 #: build/C/man2/perf_event_open.2:1530
4529 #, no-wrap
4530 msgid "B<PERF_RECORD_MISC_GUEST_KERNEL>"
4531 msgstr ""
4532
4533 #. type: Plain text
4534 #: build/C/man2/perf_event_open.2:1533
4535 msgid "Sample happened in the guest kernel."
4536 msgstr ""
4537
4538 #. type: TP
4539 #: build/C/man2/perf_event_open.2:1533
4540 #, no-wrap
4541 msgid "B<PERF_RECORD_MISC_GUEST_USER>"
4542 msgstr ""
4543
4544 #. type: Plain text
4545 #: build/C/man2/perf_event_open.2:1536
4546 msgid "Sample happened in guest user code."
4547 msgstr ""
4548
4549 #. type: Plain text
4550 #: build/C/man2/perf_event_open.2:1540
4551 msgid "In addition, one of the following bits can be set:"
4552 msgstr ""
4553
4554 #. type: TP
4555 #: build/C/man2/perf_event_open.2:1540
4556 #, no-wrap
4557 msgid "B<PERF_RECORD_MISC_MMAP_DATA>"
4558 msgstr ""
4559
4560 #. type: Plain text
4561 #: build/C/man2/perf_event_open.2:1544
4562 msgid ""
4563 "This is set when the mapping is not executable; otherwise the mapping is "
4564 "executable."
4565 msgstr ""
4566
4567 #. type: TP
4568 #: build/C/man2/perf_event_open.2:1544
4569 #, no-wrap
4570 msgid "B<PERF_RECORD_MISC_EXACT_IP>"
4571 msgstr ""
4572
4573 #. type: Plain text
4574 #: build/C/man2/perf_event_open.2:1552
4575 msgid ""
4576 "This indicates that the content of B<PERF_SAMPLE_IP> points to the actual "
4577 "instruction that triggered the event.  See also "
4578 "I<perf_event_attr.precise_ip>."
4579 msgstr ""
4580
4581 #. type: TP
4582 #: build/C/man2/perf_event_open.2:1552
4583 #, no-wrap
4584 msgid "B<PERF_RECORD_MISC_EXT_RESERVED>"
4585 msgstr ""
4586
4587 #. type: Plain text
4588 #: build/C/man2/perf_event_open.2:1555
4589 msgid "This indicates there is extended data available (currently not used)."
4590 msgstr ""
4591
4592 #. type: Plain text
4593 #: build/C/man2/perf_event_open.2:1565
4594 msgid ""
4595 "The I<type> value is one of the below.  The values in the corresponding "
4596 "record (that follows the header)  depend on the I<type> selected as shown."
4597 msgstr ""
4598
4599 #. type: TP
4600 #: build/C/man2/perf_event_open.2:1567
4601 #, no-wrap
4602 msgid "B<PERF_RECORD_MMAP>"
4603 msgstr ""
4604
4605 #. type: Plain text
4606 #: build/C/man2/perf_event_open.2:1574
4607 msgid ""
4608 "The MMAP events record the B<PROT_EXEC> mappings so that we can correlate "
4609 "user-space IPs to code.  They have the following structure:"
4610 msgstr ""
4611
4612 #. type: Plain text
4613 #: build/C/man2/perf_event_open.2:1585
4614 #, no-wrap
4615 msgid ""
4616 "struct {\n"
4617 "    struct perf_event_header header;\n"
4618 "    u32    pid, tid;\n"
4619 "    u64    addr;\n"
4620 "    u64    len;\n"
4621 "    u64    pgoff;\n"
4622 "    char   filename[];\n"
4623 "};\n"
4624 msgstr ""
4625
4626 #. type: TP
4627 #: build/C/man2/perf_event_open.2:1587
4628 #, no-wrap
4629 msgid "B<PERF_RECORD_LOST>"
4630 msgstr ""
4631
4632 #. type: Plain text
4633 #: build/C/man2/perf_event_open.2:1590
4634 msgid "This record indicates when events are lost."
4635 msgstr ""
4636
4637 #. type: Plain text
4638 #: build/C/man2/perf_event_open.2:1599
4639 #, no-wrap
4640 msgid ""
4641 "struct {\n"
4642 "    struct perf_event_header header;\n"
4643 "    u64 id;\n"
4644 "    u64 lost;\n"
4645 "    struct sample_id sample_id;\n"
4646 "};\n"
4647 msgstr ""
4648
4649 #. type: Plain text
4650 #: build/C/man2/perf_event_open.2:1605
4651 msgid "is the unique event ID for the samples that were lost."
4652 msgstr ""
4653
4654 #. type: TP
4655 #: build/C/man2/perf_event_open.2:1605
4656 #, no-wrap
4657 msgid "I<lost>"
4658 msgstr ""
4659
4660 #. type: Plain text
4661 #: build/C/man2/perf_event_open.2:1608
4662 msgid "is the number of events that were lost."
4663 msgstr ""
4664
4665 #. type: TP
4666 #: build/C/man2/perf_event_open.2:1609
4667 #, no-wrap
4668 msgid "B<PERF_RECORD_COMM>"
4669 msgstr ""
4670
4671 #. type: Plain text
4672 #: build/C/man2/perf_event_open.2:1612
4673 msgid "This record indicates a change in the process name."
4674 msgstr ""
4675
4676 #. type: Plain text
4677 #: build/C/man2/perf_event_open.2:1621
4678 #, no-wrap
4679 msgid ""
4680 "struct {\n"
4681 "    struct perf_event_header header;\n"
4682 "    u32 pid, tid;\n"
4683 "    char comm[];\n"
4684 "    struct sample_id sample_id;\n"
4685 "};\n"
4686 msgstr ""
4687
4688 #. type: TP
4689 #: build/C/man2/perf_event_open.2:1623
4690 #, no-wrap
4691 msgid "B<PERF_RECORD_EXIT>"
4692 msgstr ""
4693
4694 #. type: Plain text
4695 #: build/C/man2/perf_event_open.2:1626
4696 msgid "This record indicates a process exit event."
4697 msgstr ""
4698
4699 #. type: Plain text
4700 #: build/C/man2/perf_event_open.2:1636 build/C/man2/perf_event_open.2:1666
4701 #, no-wrap
4702 msgid ""
4703 "struct {\n"
4704 "    struct perf_event_header header;\n"
4705 "    u32 pid, ppid;\n"
4706 "    u32 tid, ptid;\n"
4707 "    u64 time;\n"
4708 "    struct sample_id sample_id;\n"
4709 "};\n"
4710 msgstr ""
4711
4712 #. type: TP
4713 #: build/C/man2/perf_event_open.2:1638
4714 #, no-wrap
4715 msgid "B<PERF_RECORD_THROTTLE>, B<PERF_RECORD_UNTHROTTLE>"
4716 msgstr ""
4717
4718 #. type: Plain text
4719 #: build/C/man2/perf_event_open.2:1641
4720 msgid "This record indicates a throttle/unthrottle event."
4721 msgstr ""
4722
4723 #. type: Plain text
4724 #: build/C/man2/perf_event_open.2:1651
4725 #, no-wrap
4726 msgid ""
4727 "struct {\n"
4728 "    struct perf_event_header header;\n"
4729 "    u64 time;\n"
4730 "    u64 id;\n"
4731 "    u64 stream_id;\n"
4732 "    struct sample_id sample_id;\n"
4733 "};\n"
4734 msgstr ""
4735
4736 #. type: TP
4737 #: build/C/man2/perf_event_open.2:1653
4738 #, no-wrap
4739 msgid "B<PERF_RECORD_FORK>"
4740 msgstr ""
4741
4742 #. type: Plain text
4743 #: build/C/man2/perf_event_open.2:1656
4744 msgid "This record indicates a fork event."
4745 msgstr ""
4746
4747 #. type: TP
4748 #: build/C/man2/perf_event_open.2:1668
4749 #, no-wrap
4750 msgid "B<PERF_RECORD_READ>"
4751 msgstr ""
4752
4753 #. type: Plain text
4754 #: build/C/man2/perf_event_open.2:1671
4755 msgid "This record indicates a read event."
4756 msgstr ""
4757
4758 #. type: Plain text
4759 #: build/C/man2/perf_event_open.2:1680
4760 #, no-wrap
4761 msgid ""
4762 "struct {\n"
4763 "    struct perf_event_header header;\n"
4764 "    u32 pid, tid;\n"
4765 "    struct read_format values;\n"
4766 "    struct sample_id sample_id;\n"
4767 "};\n"
4768 msgstr ""
4769
4770 #. type: TP
4771 #: build/C/man2/perf_event_open.2:1682
4772 #, no-wrap
4773 msgid "B<PERF_RECORD_SAMPLE>"
4774 msgstr ""
4775
4776 #. type: Plain text
4777 #: build/C/man2/perf_event_open.2:1685
4778 msgid "This record indicates a sample."
4779 msgstr ""
4780
4781 #. type: Plain text
4782 #: build/C/man2/perf_event_open.2:1717
4783 #, no-wrap
4784 msgid ""
4785 "struct {\n"
4786 "    struct perf_event_header header;\n"
4787 "    u64   sample_id;  /* if PERF_SAMPLE_IDENTIFIER */\n"
4788 "    u64   ip;         /* if PERF_SAMPLE_IP */\n"
4789 "    u32   pid, tid;   /* if PERF_SAMPLE_TID */\n"
4790 "    u64   time;       /* if PERF_SAMPLE_TIME */\n"
4791 "    u64   addr;       /* if PERF_SAMPLE_ADDR */\n"
4792 "    u64   id;         /* if PERF_SAMPLE_ID */\n"
4793 "    u64   stream_id;  /* if PERF_SAMPLE_STREAM_ID */\n"
4794 "    u32   cpu, res;   /* if PERF_SAMPLE_CPU */\n"
4795 "    u64   period;     /* if PERF_SAMPLE_PERIOD */\n"
4796 "    struct read_format v; /* if PERF_SAMPLE_READ */\n"
4797 "    u64   nr;         /* if PERF_SAMPLE_CALLCHAIN */\n"
4798 "    u64   ips[nr];    /* if PERF_SAMPLE_CALLCHAIN */\n"
4799 "    u32   size;       /* if PERF_SAMPLE_RAW */\n"
4800 "    char  data[size]; /* if PERF_SAMPLE_RAW */\n"
4801 "    u64   bnr;        /* if PERF_SAMPLE_BRANCH_STACK */\n"
4802 "    struct perf_branch_entry lbr[bnr];\n"
4803 "                      /* if PERF_SAMPLE_BRANCH_STACK */\n"
4804 "    u64   abi;        /* if PERF_SAMPLE_REGS_USER */\n"
4805 "    u64   regs[weight(mask)];\n"
4806 "                      /* if PERF_SAMPLE_REGS_USER */\n"
4807 "    u64   size;       /* if PERF_SAMPLE_STACK_USER */\n"
4808 "    char  data[size]; /* if PERF_SAMPLE_STACK_USER */\n"
4809 "    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */\n"
4810 "    u64   weight;     /* if PERF_SAMPLE_WEIGHT */\n"
4811 "    u64   data_src;   /* if PERF_SAMPLE_DATA_SRC */\n"
4812 "    u64   transaction;/* if PERF_SAMPLE_TRANSACTION */\n"
4813 "};\n"
4814 msgstr ""
4815
4816 #. type: TP
4817 #: build/C/man2/perf_event_open.2:1719
4818 #, no-wrap
4819 msgid "I<sample_id>"
4820 msgstr ""
4821
4822 #. type: Plain text
4823 #: build/C/man2/perf_event_open.2:1729
4824 msgid ""
4825 "If B<PERF_SAMPLE_IDENTIFIER> is enabled, a 64-bit unique ID is included.  "
4826 "This is a duplication of the B<PERF_SAMPLE_ID> I<id> value, but included at "
4827 "the beginning of the sample so parsers can easily obtain the value."
4828 msgstr ""
4829
4830 #. type: TP
4831 #: build/C/man2/perf_event_open.2:1729
4832 #, no-wrap
4833 msgid "I<ip>"
4834 msgstr ""
4835
4836 #. type: Plain text
4837 #: build/C/man2/perf_event_open.2:1735
4838 msgid ""
4839 "If B<PERF_SAMPLE_IP> is enabled, then a 64-bit instruction pointer value is "
4840 "included."
4841 msgstr ""
4842
4843 #. type: TP
4844 #: build/C/man2/perf_event_open.2:1735
4845 #, no-wrap
4846 msgid "I<pid>, I<tid>"
4847 msgstr ""
4848
4849 #. type: Plain text
4850 #: build/C/man2/perf_event_open.2:1741
4851 msgid ""
4852 "If B<PERF_SAMPLE_TID> is enabled, then a 32-bit process ID and 32-bit thread "
4853 "ID are included."
4854 msgstr ""
4855
4856 #. type: TP
4857 #: build/C/man2/perf_event_open.2:1741
4858 #, no-wrap
4859 msgid "I<time>"
4860 msgstr ""
4861
4862 #. type: Plain text
4863 #: build/C/man2/perf_event_open.2:1749
4864 msgid ""
4865 "If B<PERF_SAMPLE_TIME> is enabled, then a 64-bit timestamp is included.  "
4866 "This is obtained via local_clock() which is a hardware timestamp if "
4867 "available and the jiffies value if not."
4868 msgstr ""
4869
4870 #. type: TP
4871 #: build/C/man2/perf_event_open.2:1749
4872 #, no-wrap
4873 msgid "I<addr>"
4874 msgstr ""
4875
4876 #. type: Plain text
4877 #: build/C/man2/perf_event_open.2:1756
4878 msgid ""
4879 "If B<PERF_SAMPLE_ADDR> is enabled, then a 64-bit address is included.  This "
4880 "is usually the address of a tracepoint, breakpoint, or software event; "
4881 "otherwise the value is 0."
4882 msgstr ""
4883
4884 #. type: Plain text
4885 #: build/C/man2/perf_event_open.2:1764
4886 msgid ""
4887 "If B<PERF_SAMPLE_ID> is enabled, a 64-bit unique ID is included.  If the "
4888 "event is a member of an event group, the group leader ID is returned.  This "
4889 "ID is the same as the one returned by B<PERF_FORMAT_ID>."
4890 msgstr ""
4891
4892 #. type: TP
4893 #: build/C/man2/perf_event_open.2:1764
4894 #, no-wrap
4895 msgid "I<stream_id>"
4896 msgstr ""
4897
4898 #. type: Plain text
4899 #: build/C/man2/perf_event_open.2:1774
4900 msgid ""
4901 "If B<PERF_SAMPLE_STREAM_ID> is enabled, a 64-bit unique ID is included.  "
4902 "Unlike B<PERF_SAMPLE_ID> the actual ID is returned, not the group leader.  "
4903 "This ID is the same as the one returned by B<PERF_FORMAT_ID>."
4904 msgstr ""
4905
4906 #. type: TP
4907 #: build/C/man2/perf_event_open.2:1774
4908 #, no-wrap
4909 msgid "I<cpu>, I<res>"
4910 msgstr ""
4911
4912 #. type: Plain text
4913 #: build/C/man2/perf_event_open.2:1781
4914 msgid ""
4915 "If B<PERF_SAMPLE_CPU> is enabled, this is a 32-bit value indicating which "
4916 "CPU was being used, in addition to a reserved (unused)  32-bit value."
4917 msgstr ""
4918
4919 #. type: TP
4920 #: build/C/man2/perf_event_open.2:1781
4921 #, no-wrap
4922 msgid "I<period>"
4923 msgstr ""
4924
4925 #. type: Plain text
4926 #: build/C/man2/perf_event_open.2:1787
4927 msgid ""
4928 "If B<PERF_SAMPLE_PERIOD> is enabled, a 64-bit value indicating the current "
4929 "sampling period is written."
4930 msgstr ""
4931
4932 #. type: TP
4933 #: build/C/man2/perf_event_open.2:1787
4934 #, no-wrap
4935 msgid "I<v>"
4936 msgstr ""
4937
4938 #. type: Plain text
4939 #: build/C/man2/perf_event_open.2:1798
4940 msgid ""
4941 "If B<PERF_SAMPLE_READ> is enabled, a structure of type read_format is "
4942 "included which has values for all events in the event group.  The values "
4943 "included depend on the I<read_format> value used at B<perf_event_open>()  "
4944 "time."
4945 msgstr ""
4946
4947 #. type: TP
4948 #: build/C/man2/perf_event_open.2:1798
4949 #, no-wrap
4950 msgid "I<nr>, I<ips[nr]>"
4951 msgstr ""
4952
4953 #. type: Plain text
4954 #: build/C/man2/perf_event_open.2:1806
4955 msgid ""
4956 "If B<PERF_SAMPLE_CALLCHAIN> is enabled, then a 64-bit number is included "
4957 "which indicates how many following 64-bit instruction pointers will follow.  "
4958 "This is the current callchain."
4959 msgstr ""
4960
4961 #. type: TP
4962 #: build/C/man2/perf_event_open.2:1806
4963 #, no-wrap
4964 msgid "I<size>, I<data[size]>"
4965 msgstr ""
4966
4967 #. type: Plain text
4968 #: build/C/man2/perf_event_open.2:1813
4969 msgid ""
4970 "If B<PERF_SAMPLE_RAW> is enabled, then a 32-bit value indicating size is "
4971 "included followed by an array of 8-bit values of length size.  The values "
4972 "are padded with 0 to have 64-bit alignment."
4973 msgstr ""
4974
4975 #. type: Plain text
4976 #: build/C/man2/perf_event_open.2:1818
4977 msgid ""
4978 "This RAW record data is opaque with respect to the ABI.  The ABI doesn't "
4979 "make any promises with respect to the stability of its content, it may vary "
4980 "depending on event, hardware, and kernel version."
4981 msgstr ""
4982
4983 #. type: TP
4984 #: build/C/man2/perf_event_open.2:1818
4985 #, no-wrap
4986 msgid "I<bnr>, I<lbr[bnr]>"
4987 msgstr ""
4988
4989 #. type: Plain text
4990 #: build/C/man2/perf_event_open.2:1827
4991 msgid ""
4992 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then a 64-bit value indicating "
4993 "the number of records is included, followed by I<bnr> I<perf_branch_entry> "
4994 "structures which each include the fields:"
4995 msgstr ""
4996
4997 #. type: TP
4998 #: build/C/man2/perf_event_open.2:1828
4999 #, no-wrap
5000 msgid "I<from>"
5001 msgstr ""
5002
5003 #. type: Plain text
5004 #: build/C/man2/perf_event_open.2:1831
5005 msgid "This indicates the source instruction (may not be a branch)."
5006 msgstr ""
5007
5008 #. type: TP
5009 #: build/C/man2/perf_event_open.2:1831
5010 #, no-wrap
5011 msgid "I<to>"
5012 msgstr ""
5013
5014 #. type: Plain text
5015 #: build/C/man2/perf_event_open.2:1834
5016 msgid "The branch target."
5017 msgstr ""
5018
5019 #. type: TP
5020 #: build/C/man2/perf_event_open.2:1834
5021 #, no-wrap
5022 msgid "I<mispred>"
5023 msgstr ""
5024
5025 #. type: Plain text
5026 #: build/C/man2/perf_event_open.2:1837
5027 msgid "The branch target was mispredicted."
5028 msgstr ""
5029
5030 #. type: TP
5031 #: build/C/man2/perf_event_open.2:1837
5032 #, no-wrap
5033 msgid "I<predicted>"
5034 msgstr ""
5035
5036 #. type: Plain text
5037 #: build/C/man2/perf_event_open.2:1840
5038 msgid "The branch target was predicted."
5039 msgstr ""
5040
5041 #. type: TP
5042 #: build/C/man2/perf_event_open.2:1840
5043 #, no-wrap
5044 msgid "I<in_tx> (since Linux 3.11)"
5045 msgstr ""
5046
5047 #. type: Plain text
5048 #: build/C/man2/perf_event_open.2:1843
5049 msgid "The branch was in a transactional memory transaction."
5050 msgstr ""
5051
5052 #. type: TP
5053 #: build/C/man2/perf_event_open.2:1843
5054 #, no-wrap
5055 msgid "I<abort> (since Linux 3.11)"
5056 msgstr ""
5057
5058 #. type: Plain text
5059 #: build/C/man2/perf_event_open.2:1846
5060 msgid "The branch was in an aborted transactional memory transaction."
5061 msgstr ""
5062
5063 #. type: Plain text
5064 #: build/C/man2/perf_event_open.2:1850
5065 msgid ""
5066 "The entries are from most to least recent, so the first entry has the most "
5067 "recent branch."
5068 msgstr ""
5069
5070 #. type: Plain text
5071 #: build/C/man2/perf_event_open.2:1857
5072 msgid ""
5073 "Support for I<mispred> and I<predicted> is optional; if not supported, both "
5074 "values will be 0."
5075 msgstr ""
5076
5077 #. type: Plain text
5078 #: build/C/man2/perf_event_open.2:1861
5079 msgid ""
5080 "The type of branches recorded is specified by the I<branch_sample_type> "
5081 "field."
5082 msgstr ""
5083
5084 #. type: TP
5085 #: build/C/man2/perf_event_open.2:1863
5086 #, no-wrap
5087 msgid "I<abi>, I<regs[weight(mask)]>"
5088 msgstr ""
5089
5090 #. type: Plain text
5091 #: build/C/man2/perf_event_open.2:1868
5092 msgid ""
5093 "If B<PERF_SAMPLE_REGS_USER> is enabled, then the user CPU registers are "
5094 "recorded."
5095 msgstr ""
5096
5097 #. type: Plain text
5098 #: build/C/man2/perf_event_open.2:1874
5099 msgid ""
5100 "The I<abi> field is one of B<PERF_SAMPLE_REGS_ABI_NONE>, "
5101 "B<PERF_SAMPLE_REGS_ABI_32> or B<PERF_SAMPLE_REGS_ABI_64>."
5102 msgstr ""
5103
5104 #. type: Plain text
5105 #: build/C/man2/perf_event_open.2:1884
5106 msgid ""
5107 "The I<regs> field is an array of the CPU registers that were specified by "
5108 "the I<sample_regs_user> attr field.  The number of values is the number of "
5109 "bits set in the I<sample_regs_user> bit mask."
5110 msgstr ""
5111
5112 #. type: TP
5113 #: build/C/man2/perf_event_open.2:1884
5114 #, no-wrap
5115 msgid "I<size>, I<data[size]>, I<dyn_size>"
5116 msgstr ""
5117
5118 #. type: Plain text
5119 #: build/C/man2/perf_event_open.2:1898
5120 msgid ""
5121 "If B<PERF_SAMPLE_STACK_USER> is enabled, then record the user stack to "
5122 "enable backtracing.  I<size> is the size requested by the user in "
5123 "I<stack_user_size> or else the maximum record size.  I<data> is the stack "
5124 "data.  I<dyn_size> is the amount of data actually dumped (can be less than "
5125 "I<size>)."
5126 msgstr ""
5127
5128 #. type: TP
5129 #: build/C/man2/perf_event_open.2:1898
5130 #, no-wrap
5131 msgid "I<weight>"
5132 msgstr ""
5133
5134 #. type: Plain text
5135 #: build/C/man2/perf_event_open.2:1906
5136 msgid ""
5137 "If B<PERF_SAMPLE_WEIGHT> is enabled, then a 64-bit value provided by the "
5138 "hardware is recorded that indicates how costly the event was.  This allows "
5139 "expensive events to stand out more clearly in profiles."
5140 msgstr ""
5141
5142 #. type: TP
5143 #: build/C/man2/perf_event_open.2:1906
5144 #, no-wrap
5145 msgid "I<data_src>"
5146 msgstr ""
5147
5148 #. type: Plain text
5149 #: build/C/man2/perf_event_open.2:1912
5150 msgid ""
5151 "If B<PERF_SAMPLE_DATA_SRC> is enabled, then a 64-bit value is recorded that "
5152 "is made up of the following fields:"
5153 msgstr ""
5154
5155 #. type: TP
5156 #: build/C/man2/perf_event_open.2:1913
5157 #, no-wrap
5158 msgid "I<mem_op>"
5159 msgstr ""
5160
5161 #. type: Plain text
5162 #: build/C/man2/perf_event_open.2:1916
5163 msgid "Type of opcode, a bitwise combination of:"
5164 msgstr ""
5165
5166 #. type: TP
5167 #: build/C/man2/perf_event_open.2:1919
5168 #, no-wrap
5169 msgid "B<PERF_MEM_OP_NA>"
5170 msgstr ""
5171
5172 #. type: Plain text
5173 #: build/C/man2/perf_event_open.2:1922 build/C/man2/perf_event_open.2:1945 build/C/man2/perf_event_open.2:1995 build/C/man2/perf_event_open.2:2018 build/C/man2/perf_event_open.2:2032
5174 msgid "Not available"
5175 msgstr ""
5176
5177 #. type: TP
5178 #: build/C/man2/perf_event_open.2:1922
5179 #, no-wrap
5180 msgid "B<PERF_MEM_OP_LOAD>"
5181 msgstr ""
5182
5183 #. type: Plain text
5184 #: build/C/man2/perf_event_open.2:1925
5185 msgid "Load instruction"
5186 msgstr ""
5187
5188 #. type: TP
5189 #: build/C/man2/perf_event_open.2:1925
5190 #, no-wrap
5191 msgid "B<PERF_MEM_OP_STORE>"
5192 msgstr ""
5193
5194 #. type: Plain text
5195 #: build/C/man2/perf_event_open.2:1928
5196 msgid "Store instruction"
5197 msgstr ""
5198
5199 #. type: TP
5200 #: build/C/man2/perf_event_open.2:1928
5201 #, no-wrap
5202 msgid "B<PERF_MEM_OP_PFETCH>"
5203 msgstr ""
5204
5205 #. type: Plain text
5206 #: build/C/man2/perf_event_open.2:1931
5207 msgid "Prefetch"
5208 msgstr ""
5209
5210 #. type: TP
5211 #: build/C/man2/perf_event_open.2:1931
5212 #, no-wrap
5213 msgid "B<PERF_MEM_OP_EXEC>"
5214 msgstr ""
5215
5216 #. type: Plain text
5217 #: build/C/man2/perf_event_open.2:1934
5218 msgid "Executable code"
5219 msgstr ""
5220
5221 #. type: TP
5222 #: build/C/man2/perf_event_open.2:1936
5223 #, no-wrap
5224 msgid "I<mem_lvl>"
5225 msgstr ""
5226
5227 #. type: Plain text
5228 #: build/C/man2/perf_event_open.2:1939
5229 msgid "Memory hierarchy level hit or miss, a bitwise combination of:"
5230 msgstr ""
5231
5232 #. type: TP
5233 #: build/C/man2/perf_event_open.2:1942
5234 #, no-wrap
5235 msgid "B<PERF_MEM_LVL_NA>"
5236 msgstr ""
5237
5238 #. type: TP
5239 #: build/C/man2/perf_event_open.2:1945
5240 #, no-wrap
5241 msgid "B<PERF_MEM_LVL_HIT>"
5242 msgstr ""
5243
5244 #. type: Plain text
5245 #: build/C/man2/perf_event_open.2:1948 build/C/man2/perf_event_open.2:2035
5246 msgid "Hit"
5247 msgstr ""
5248
5249 #. type: TP
5250 #: build/C/man2/perf_event_open.2:1948
5251 #, no-wrap
5252 msgid "B<PERF_MEM_LVL_MISS>"
5253 msgstr ""
5254
5255 #. type: Plain text
5256 #: build/C/man2/perf_event_open.2:1951 build/C/man2/perf_event_open.2:2038
5257 msgid "Miss"
5258 msgstr ""
5259
5260 #. type: TP
5261 #: build/C/man2/perf_event_open.2:1951
5262 #, no-wrap
5263 msgid "B<PERF_MEM_LVL_L1>"
5264 msgstr ""
5265
5266 #. type: Plain text
5267 #: build/C/man2/perf_event_open.2:1954
5268 msgid "Level 1 cache"
5269 msgstr ""
5270
5271 #. type: TP
5272 #: build/C/man2/perf_event_open.2:1954
5273 #, no-wrap
5274 msgid "B<PERF_MEM_LVL_LFB>"
5275 msgstr ""
5276
5277 #. type: Plain text
5278 #: build/C/man2/perf_event_open.2:1957
5279 msgid "Line fill buffer"
5280 msgstr ""
5281
5282 #. type: TP
5283 #: build/C/man2/perf_event_open.2:1957
5284 #, no-wrap
5285 msgid "B<PERF_MEM_LVL_L2>"
5286 msgstr ""
5287
5288 #. type: Plain text
5289 #: build/C/man2/perf_event_open.2:1960
5290 msgid "Level 2 cache"
5291 msgstr ""
5292
5293 #. type: TP
5294 #: build/C/man2/perf_event_open.2:1960
5295 #, no-wrap
5296 msgid "B<PERF_MEM_LVL_L3>"
5297 msgstr ""
5298
5299 #. type: Plain text
5300 #: build/C/man2/perf_event_open.2:1963
5301 msgid "Level 3 cache"
5302 msgstr ""
5303
5304 #. type: TP
5305 #: build/C/man2/perf_event_open.2:1963
5306 #, no-wrap
5307 msgid "B<PERF_MEM_LVL_LOC_RAM>"
5308 msgstr ""
5309
5310 #. type: Plain text
5311 #: build/C/man2/perf_event_open.2:1966
5312 msgid "Local DRAM"
5313 msgstr ""
5314
5315 #. type: TP
5316 #: build/C/man2/perf_event_open.2:1966
5317 #, no-wrap
5318 msgid "B<PERF_MEM_LVL_REM_RAM1>"
5319 msgstr ""
5320
5321 #. type: Plain text
5322 #: build/C/man2/perf_event_open.2:1969
5323 msgid "Remote DRAM 1 hop"
5324 msgstr ""
5325
5326 #. type: TP
5327 #: build/C/man2/perf_event_open.2:1969
5328 #, no-wrap
5329 msgid "B<PERF_MEM_LVL_REM_RAM2>"
5330 msgstr ""
5331
5332 #. type: Plain text
5333 #: build/C/man2/perf_event_open.2:1972
5334 msgid "Remote DRAM 2 hops"
5335 msgstr ""
5336
5337 #. type: TP
5338 #: build/C/man2/perf_event_open.2:1972
5339 #, no-wrap
5340 msgid "B<PERF_MEM_LVL_REM_CCE1>"
5341 msgstr ""
5342
5343 #. type: Plain text
5344 #: build/C/man2/perf_event_open.2:1975
5345 msgid "Remote cache 1 hop"
5346 msgstr ""
5347
5348 #. type: TP
5349 #: build/C/man2/perf_event_open.2:1975
5350 #, no-wrap
5351 msgid "B<PERF_MEM_LVL_REM_CCE2>"
5352 msgstr ""
5353
5354 #. type: Plain text
5355 #: build/C/man2/perf_event_open.2:1978
5356 msgid "Remote cache 2 hops"
5357 msgstr ""
5358
5359 #. type: TP
5360 #: build/C/man2/perf_event_open.2:1978
5361 #, no-wrap
5362 msgid "B<PERF_MEM_LVL_IO>"
5363 msgstr ""
5364
5365 #. type: Plain text
5366 #: build/C/man2/perf_event_open.2:1981
5367 msgid "I/O memory"
5368 msgstr ""
5369
5370 #. type: TP
5371 #: build/C/man2/perf_event_open.2:1981
5372 #, no-wrap
5373 msgid "B<PERF_MEM_LVL_UNC>"
5374 msgstr ""
5375
5376 #. type: Plain text
5377 #: build/C/man2/perf_event_open.2:1984
5378 msgid "Uncached memory"
5379 msgstr ""
5380
5381 #. type: TP
5382 #: build/C/man2/perf_event_open.2:1986
5383 #, no-wrap
5384 msgid "I<mem_snoop>"
5385 msgstr ""
5386
5387 #. type: Plain text
5388 #: build/C/man2/perf_event_open.2:1989
5389 msgid "Snoop mode, a bitwise combination of:"
5390 msgstr ""
5391
5392 #. type: TP
5393 #: build/C/man2/perf_event_open.2:1992
5394 #, no-wrap
5395 msgid "B<PERF_MEM_SNOOP_NA>"
5396 msgstr ""
5397
5398 #. type: TP
5399 #: build/C/man2/perf_event_open.2:1995
5400 #, no-wrap
5401 msgid "B<PERF_MEM_SNOOP_NONE>"
5402 msgstr ""
5403
5404 #. type: Plain text
5405 #: build/C/man2/perf_event_open.2:1998
5406 msgid "No snoop"
5407 msgstr ""
5408
5409 #. type: TP
5410 #: build/C/man2/perf_event_open.2:1998
5411 #, no-wrap
5412 msgid "B<PERF_MEM_SNOOP_HIT>"
5413 msgstr ""
5414
5415 #. type: Plain text
5416 #: build/C/man2/perf_event_open.2:2001
5417 msgid "Snoop hit"
5418 msgstr ""
5419
5420 #. type: TP
5421 #: build/C/man2/perf_event_open.2:2001
5422 #, no-wrap
5423 msgid "B<PERF_MEM_SNOOP_MISS>"
5424 msgstr ""
5425
5426 #. type: Plain text
5427 #: build/C/man2/perf_event_open.2:2004
5428 msgid "Snoop miss"
5429 msgstr ""
5430
5431 #. type: TP
5432 #: build/C/man2/perf_event_open.2:2004
5433 #, no-wrap
5434 msgid "B<PERF_MEM_SNOOP_HITM>"
5435 msgstr ""
5436
5437 #. type: Plain text
5438 #: build/C/man2/perf_event_open.2:2007
5439 msgid "Snoop hit modified"
5440 msgstr ""
5441
5442 #. type: TP
5443 #: build/C/man2/perf_event_open.2:2009
5444 #, no-wrap
5445 msgid "I<mem_lock>"
5446 msgstr ""
5447
5448 #. type: Plain text
5449 #: build/C/man2/perf_event_open.2:2012
5450 msgid "Lock instruction, a bitwise combination of:"
5451 msgstr ""
5452
5453 #. type: TP
5454 #: build/C/man2/perf_event_open.2:2015
5455 #, no-wrap
5456 msgid "B<PERF_MEM_LOCK_NA>"
5457 msgstr ""
5458
5459 #. type: TP
5460 #: build/C/man2/perf_event_open.2:2018
5461 #, no-wrap
5462 msgid "B<PERF_MEM_LOCK_LOCKED>"
5463 msgstr ""
5464
5465 #. type: Plain text
5466 #: build/C/man2/perf_event_open.2:2021
5467 msgid "Locked transaction"
5468 msgstr ""
5469
5470 #. type: TP
5471 #: build/C/man2/perf_event_open.2:2023
5472 #, no-wrap
5473 msgid "I<mem_dtlb>"
5474 msgstr ""
5475
5476 #. type: Plain text
5477 #: build/C/man2/perf_event_open.2:2026
5478 msgid "TLB access hit or miss, a bitwise combination of:"
5479 msgstr ""
5480
5481 #. type: TP
5482 #: build/C/man2/perf_event_open.2:2029
5483 #, no-wrap
5484 msgid "B<PERF_MEM_TLB_NA>"
5485 msgstr ""
5486
5487 #. type: TP
5488 #: build/C/man2/perf_event_open.2:2032
5489 #, no-wrap
5490 msgid "B<PERF_MEM_TLB_HIT>"
5491 msgstr ""
5492
5493 #. type: TP
5494 #: build/C/man2/perf_event_open.2:2035
5495 #, no-wrap
5496 msgid "B<PERF_MEM_TLB_MISS>"
5497 msgstr ""
5498
5499 #. type: TP
5500 #: build/C/man2/perf_event_open.2:2038
5501 #, no-wrap
5502 msgid "B<PERF_MEM_TLB_L1>"
5503 msgstr ""
5504
5505 #. type: Plain text
5506 #: build/C/man2/perf_event_open.2:2041
5507 msgid "Level 1 TLB"
5508 msgstr ""
5509
5510 #. type: TP
5511 #: build/C/man2/perf_event_open.2:2041
5512 #, no-wrap
5513 msgid "B<PERF_MEM_TLB_L2>"
5514 msgstr ""
5515
5516 #. type: Plain text
5517 #: build/C/man2/perf_event_open.2:2044
5518 msgid "Level 2 TLB"
5519 msgstr ""
5520
5521 #. type: TP
5522 #: build/C/man2/perf_event_open.2:2044
5523 #, no-wrap
5524 msgid "B<PERF_MEM_TLB_WK>"
5525 msgstr ""
5526
5527 #. type: Plain text
5528 #: build/C/man2/perf_event_open.2:2047
5529 msgid "Hardware walker"
5530 msgstr ""
5531
5532 #. type: TP
5533 #: build/C/man2/perf_event_open.2:2047
5534 #, no-wrap
5535 msgid "B<PERF_MEM_TLB_OS>"
5536 msgstr ""
5537
5538 #. type: Plain text
5539 #: build/C/man2/perf_event_open.2:2050
5540 msgid "OS fault handler"
5541 msgstr ""
5542
5543 #. type: TP
5544 #: build/C/man2/perf_event_open.2:2053
5545 #, no-wrap
5546 msgid "I<transaction>"
5547 msgstr ""
5548
5549 #. type: Plain text
5550 #: build/C/man2/perf_event_open.2:2059
5551 msgid ""
5552 "If the B<PERF_SAMPLE_TRANSACTION> flag is set, then a 64-bit field is "
5553 "recorded describing the sources of any transactional memory aborts."
5554 msgstr ""
5555
5556 #. type: Plain text
5557 #: build/C/man2/perf_event_open.2:2061
5558 msgid "The field is a bitwise combination of the following values:"
5559 msgstr ""
5560
5561 #. type: TP
5562 #: build/C/man2/perf_event_open.2:2062
5563 #, no-wrap
5564 msgid "B<PERF_TXN_ELISION>"
5565 msgstr ""
5566
5567 #. type: Plain text
5568 #: build/C/man2/perf_event_open.2:2065
5569 msgid "Abort from an elision type transaction (Intel-CPU-specific)."
5570 msgstr ""
5571
5572 #. type: TP
5573 #: build/C/man2/perf_event_open.2:2065
5574 #, no-wrap
5575 msgid "B<PERF_TXN_TRANSACTION>"
5576 msgstr ""
5577
5578 #. type: Plain text
5579 #: build/C/man2/perf_event_open.2:2068
5580 msgid "Abort from a generic transaction."
5581 msgstr ""
5582
5583 #. type: TP
5584 #: build/C/man2/perf_event_open.2:2068
5585 #, no-wrap
5586 msgid "B<PERF_TXN_SYNC>"
5587 msgstr ""
5588
5589 #. type: Plain text
5590 #: build/C/man2/perf_event_open.2:2071
5591 msgid "Synchronous abort (related to the reported instruction)."
5592 msgstr ""
5593
5594 #. type: TP
5595 #: build/C/man2/perf_event_open.2:2071
5596 #, no-wrap
5597 msgid "B<PERF_TXN_ASYNC>"
5598 msgstr ""
5599
5600 #. type: Plain text
5601 #: build/C/man2/perf_event_open.2:2074
5602 msgid "Asynchronous abort (not related to the reported instruction)."
5603 msgstr ""
5604
5605 #. type: TP
5606 #: build/C/man2/perf_event_open.2:2074
5607 #, no-wrap
5608 msgid "B<PERF_TXN_RETRY>"
5609 msgstr ""
5610
5611 #. type: Plain text
5612 #: build/C/man2/perf_event_open.2:2077
5613 msgid "Retryable abort (retrying the transaction may have succeeded)."
5614 msgstr ""
5615
5616 #. type: TP
5617 #: build/C/man2/perf_event_open.2:2077
5618 #, no-wrap
5619 msgid "B<PERF_TXN_CONFLICT>"
5620 msgstr ""
5621
5622 #. type: Plain text
5623 #: build/C/man2/perf_event_open.2:2080
5624 msgid "Abort due to memory conflicts with other threads."
5625 msgstr ""
5626
5627 #. type: TP
5628 #: build/C/man2/perf_event_open.2:2080
5629 #, no-wrap
5630 msgid "B<PERF_TXN_CAPACITY_WRITE>"
5631 msgstr ""
5632
5633 #. type: Plain text
5634 #: build/C/man2/perf_event_open.2:2083
5635 msgid "Abort due to write capacity overflow."
5636 msgstr ""
5637
5638 #. type: TP
5639 #: build/C/man2/perf_event_open.2:2083
5640 #, no-wrap
5641 msgid "B<PERF_TXN_CAPACITY_READ>"
5642 msgstr ""
5643
5644 #. type: Plain text
5645 #: build/C/man2/perf_event_open.2:2086
5646 msgid "Abort due to read capacity overflow."
5647 msgstr ""
5648
5649 #. type: Plain text
5650 #: build/C/man2/perf_event_open.2:2093
5651 msgid ""
5652 "In addition, a user-specified abort code can be obtained from the high 32 "
5653 "bits of the field by shifting right by B<PERF_TXN_ABORT_SHIFT> and masking "
5654 "with B<PERF_TXN_ABORT_MASK>."
5655 msgstr ""
5656
5657 #. type: SS
5658 #: build/C/man2/perf_event_open.2:2095
5659 #, no-wrap
5660 msgid "Signal overflow"
5661 msgstr ""
5662
5663 #. type: Plain text
5664 #: build/C/man2/perf_event_open.2:2104
5665 msgid ""
5666 "Events can be set to deliver a signal when a threshold is crossed.  The "
5667 "signal handler is set up using the B<poll>(2), B<select>(2), B<epoll>(2)  "
5668 "and B<fcntl>(2), system calls."
5669 msgstr ""
5670
5671 #. type: Plain text
5672 #: build/C/man2/perf_event_open.2:2108
5673 msgid ""
5674 "To generate signals, sampling must be enabled (I<sample_period> must have a "
5675 "nonzero value)."
5676 msgstr ""
5677
5678 #. type: Plain text
5679 #: build/C/man2/perf_event_open.2:2110
5680 msgid "There are two ways to generate signals."
5681 msgstr ""
5682
5683 #. type: Plain text
5684 #: build/C/man2/perf_event_open.2:2120
5685 msgid ""
5686 "The first is to set a I<wakeup_events> or I<wakeup_watermark> value that "
5687 "will generate a signal if a certain number of samples or bytes have been "
5688 "written to the mmap ring buffer.  In this case, a signal of type B<POLL_IN> "
5689 "is sent."
5690 msgstr ""
5691
5692 #. type: Plain text
5693 #: build/C/man2/perf_event_open.2:2132
5694 msgid ""
5695 "The other way is by use of the B<PERF_EVENT_IOC_REFRESH> ioctl.  This ioctl "
5696 "adds to a counter that decrements each time the event overflows.  When "
5697 "nonzero, a B<POLL_IN> signal is sent on overflow, but once the value reaches "
5698 "0, a signal is sent of type B<POLL_HUP> and the underlying event is "
5699 "disabled."
5700 msgstr ""
5701
5702 #.  FIXME(Vince) : Find out when this was introduced
5703 #. type: Plain text
5704 #: build/C/man2/perf_event_open.2:2138
5705 msgid ""
5706 "Note: on newer kernels (definitely noticed with 3.2)  a signal is provided "
5707 "for every overflow, even if I<wakeup_events> is not set."
5708 msgstr ""
5709
5710 #. type: SS
5711 #: build/C/man2/perf_event_open.2:2138
5712 #, no-wrap
5713 msgid "rdpmc instruction"
5714 msgstr ""
5715
5716 #. type: Plain text
5717 #: build/C/man2/perf_event_open.2:2145
5718 msgid ""
5719 "Starting with Linux 3.4 on x86, you can use the I<rdpmc> instruction to get "
5720 "low-latency reads without having to enter the kernel.  Note that using "
5721 "I<rdpmc> is not necessarily faster than other methods for reading event "
5722 "values."
5723 msgstr ""
5724
5725 #. type: Plain text
5726 #: build/C/man2/perf_event_open.2:2150
5727 msgid ""
5728 "Support for this can be detected with the I<cap_usr_rdpmc> field in the mmap "
5729 "page; documentation on how to calculate event values can be found in that "
5730 "section."
5731 msgstr ""
5732
5733 #. type: SS
5734 #: build/C/man2/perf_event_open.2:2150
5735 #, no-wrap
5736 msgid "perf_event ioctl calls"
5737 msgstr ""
5738
5739 #. type: Plain text
5740 #: build/C/man2/perf_event_open.2:2155
5741 msgid "Various ioctls act on B<perf_event_open>()  file descriptors:"
5742 msgstr ""
5743
5744 #. type: TP
5745 #: build/C/man2/perf_event_open.2:2155
5746 #, no-wrap
5747 msgid "B<PERF_EVENT_IOC_ENABLE>"
5748 msgstr ""
5749
5750 #. type: Plain text
5751 #: build/C/man2/perf_event_open.2:2159
5752 msgid ""
5753 "This enables the individual event or event group specified by the file "
5754 "descriptor argument."
5755 msgstr ""
5756
5757 #. type: Plain text
5758 #: build/C/man2/perf_event_open.2:2165
5759 msgid ""
5760 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5761 "events in a group are enabled, even if the event specified is not the group "
5762 "leader (but see BUGS)."
5763 msgstr ""
5764
5765 #. type: TP
5766 #: build/C/man2/perf_event_open.2:2165
5767 #, no-wrap
5768 msgid "B<PERF_EVENT_IOC_DISABLE>"
5769 msgstr ""
5770
5771 #. type: Plain text
5772 #: build/C/man2/perf_event_open.2:2169
5773 msgid ""
5774 "This disables the individual counter or event group specified by the file "
5775 "descriptor argument."
5776 msgstr ""
5777
5778 #. type: Plain text
5779 #: build/C/man2/perf_event_open.2:2176
5780 msgid ""
5781 "Enabling or disabling the leader of a group enables or disables the entire "
5782 "group; that is, while the group leader is disabled, none of the counters in "
5783 "the group will count.  Enabling or disabling a member of a group other than "
5784 "the leader affects only that counter; disabling a non-leader stops that "
5785 "counter from counting but doesn't affect any other counter."
5786 msgstr ""
5787
5788 #. type: Plain text
5789 #: build/C/man2/perf_event_open.2:2182
5790 msgid ""
5791 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5792 "events in a group are disabled, even if the event specified is not the group "
5793 "leader (but see BUGS)."
5794 msgstr ""
5795
5796 #. type: TP
5797 #: build/C/man2/perf_event_open.2:2182
5798 #, no-wrap
5799 msgid "B<PERF_EVENT_IOC_REFRESH>"
5800 msgstr ""
5801
5802 #. type: Plain text
5803 #: build/C/man2/perf_event_open.2:2196
5804 msgid ""
5805 "Non-inherited overflow counters can use this to enable a counter for a "
5806 "number of overflows specified by the argument, after which it is disabled.  "
5807 "Subsequent calls of this ioctl add the argument value to the current count.  "
5808 "A signal with B<POLL_IN> set will happen on each overflow until the count "
5809 "reaches 0; when that happens a signal with POLL_HUP set is sent and the "
5810 "event is disabled.  Using an argument of 0 is considered undefined behavior."
5811 msgstr ""
5812
5813 #. type: TP
5814 #: build/C/man2/perf_event_open.2:2196
5815 #, no-wrap
5816 msgid "B<PERF_EVENT_IOC_RESET>"
5817 msgstr ""
5818
5819 #. type: Plain text
5820 #: build/C/man2/perf_event_open.2:2206
5821 msgid ""
5822 "Reset the event count specified by the file descriptor argument to zero.  "
5823 "This resets only the counts; there is no way to reset the multiplexing "
5824 "I<time_enabled> or I<time_running> values."
5825 msgstr ""
5826
5827 #. type: Plain text
5828 #: build/C/man2/perf_event_open.2:2212
5829 msgid ""
5830 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5831 "events in a group are reset, even if the event specified is not the group "
5832 "leader (but see BUGS)."
5833 msgstr ""
5834
5835 #. type: TP
5836 #: build/C/man2/perf_event_open.2:2212
5837 #, no-wrap
5838 msgid "B<PERF_EVENT_IOC_PERIOD>"
5839 msgstr ""
5840
5841 #. type: Plain text
5842 #: build/C/man2/perf_event_open.2:2215
5843 msgid "This updates the overflow period for the event."
5844 msgstr ""
5845
5846 #. type: Plain text
5847 #: build/C/man2/perf_event_open.2:2220
5848 msgid ""
5849 "Since Linux 3.7 (on ARM) and Linux 3.14 (all other architectures), the new "
5850 "period takes effect immediately.  On older kernels, the new period did not "
5851 "take effect until after the next overflow."
5852 msgstr ""
5853
5854 #. type: Plain text
5855 #: build/C/man2/perf_event_open.2:2223
5856 msgid ""
5857 "The argument is a pointer to a 64-bit value containing the desired new "
5858 "period."
5859 msgstr ""
5860
5861 #. type: Plain text
5862 #: build/C/man2/perf_event_open.2:2226
5863 msgid "Prior to Linux 2.6.36 this ioctl always failed due to a bug in the kernel."
5864 msgstr ""
5865
5866 #. type: TP
5867 #: build/C/man2/perf_event_open.2:2227
5868 #, no-wrap
5869 msgid "B<PERF_EVENT_IOC_SET_OUTPUT>"
5870 msgstr ""
5871
5872 #. type: Plain text
5873 #: build/C/man2/perf_event_open.2:2232
5874 msgid ""
5875 "This tells the kernel to report event notifications to the specified file "
5876 "descriptor rather than the default one.  The file descriptors must all be on "
5877 "the same CPU."
5878 msgstr ""
5879
5880 #. type: Plain text
5881 #: build/C/man2/perf_event_open.2:2235
5882 msgid ""
5883 "The argument specifies the desired file descriptor, or -1 if output should "
5884 "be ignored."
5885 msgstr ""
5886
5887 #. type: TP
5888 #: build/C/man2/perf_event_open.2:2235
5889 #, no-wrap
5890 msgid "B<PERF_EVENT_IOC_SET_FILTER> (since Linux 2.6.33)"
5891 msgstr ""
5892
5893 #. type: Plain text
5894 #: build/C/man2/perf_event_open.2:2238
5895 msgid "This adds an ftrace filter to this event."
5896 msgstr ""
5897
5898 #. type: Plain text
5899 #: build/C/man2/perf_event_open.2:2240
5900 msgid "The argument is a pointer to the desired ftrace filter."
5901 msgstr ""
5902
5903 #. type: TP
5904 #: build/C/man2/perf_event_open.2:2240
5905 #, no-wrap
5906 msgid "B<PERF_EVENT_IOC_ID> (since Linux 3.12)"
5907 msgstr ""
5908
5909 #. type: Plain text
5910 #: build/C/man2/perf_event_open.2:2243
5911 msgid "This returns the event ID value for the given event file descriptor."
5912 msgstr ""
5913
5914 #. type: Plain text
5915 #: build/C/man2/perf_event_open.2:2246
5916 msgid "The argument is a pointer to a 64-bit unsigned integer to hold the result."
5917 msgstr ""
5918
5919 #. type: SS
5920 #: build/C/man2/perf_event_open.2:2246
5921 #, no-wrap
5922 msgid "Using prctl"
5923 msgstr ""
5924
5925 #. type: Plain text
5926 #: build/C/man2/perf_event_open.2:2259
5927 msgid ""
5928 "A process can enable or disable all the event groups that are attached to it "
5929 "using the B<prctl>(2)  B<PR_TASK_PERF_EVENTS_ENABLE> and "
5930 "B<PR_TASK_PERF_EVENTS_DISABLE> operations.  This applies to all counters on "
5931 "the calling process, whether created by this process or by another, and does "
5932 "not affect any counters that this process has created on other processes.  "
5933 "It enables or disables only the group leaders, not any other members in the "
5934 "groups."
5935 msgstr ""
5936
5937 #. type: SS
5938 #: build/C/man2/perf_event_open.2:2259
5939 #, no-wrap
5940 msgid "perf_event related configuration files"
5941 msgstr ""
5942
5943 #. type: Plain text
5944 #: build/C/man2/perf_event_open.2:2262
5945 msgid "Files in I</proc/sys/kernel/>"
5946 msgstr ""
5947
5948 #. type: TP
5949 #: build/C/man2/perf_event_open.2:2263
5950 #, no-wrap
5951 msgid "I</proc/sys/kernel/perf_event_paranoid>"
5952 msgstr ""
5953
5954 #. type: Plain text
5955 #: build/C/man2/perf_event_open.2:2269
5956 msgid ""
5957 "The I<perf_event_paranoid> file can be set to restrict access to the "
5958 "performance counters."
5959 msgstr ""
5960
5961 #. type: IP
5962 #: build/C/man2/perf_event_open.2:2270
5963 #, no-wrap
5964 msgid "2"
5965 msgstr ""
5966
5967 #. type: Plain text
5968 #: build/C/man2/perf_event_open.2:2272
5969 msgid "only allow user-space measurements."
5970 msgstr ""
5971
5972 #. type: IP
5973 #: build/C/man2/perf_event_open.2:2272
5974 #, no-wrap
5975 msgid "1"
5976 msgstr ""
5977
5978 #. type: Plain text
5979 #: build/C/man2/perf_event_open.2:2274
5980 msgid "allow both kernel and user measurements (default)."
5981 msgstr ""
5982
5983 #. type: IP
5984 #: build/C/man2/perf_event_open.2:2274
5985 #, no-wrap
5986 msgid "0"
5987 msgstr ""
5988
5989 #. type: Plain text
5990 #: build/C/man2/perf_event_open.2:2276
5991 msgid "allow access to CPU-specific data but not raw tracepoint samples."
5992 msgstr ""
5993
5994 #. type: IP
5995 #: build/C/man2/perf_event_open.2:2276
5996 #, no-wrap
5997 msgid "-1"
5998 msgstr ""
5999
6000 #. type: Plain text
6001 #: build/C/man2/perf_event_open.2:2278
6002 msgid "no restrictions."
6003 msgstr ""
6004
6005 #. type: Plain text
6006 #: build/C/man2/perf_event_open.2:2284
6007 msgid ""
6008 "The existence of the I<perf_event_paranoid> file is the official method for "
6009 "determining if a kernel supports B<perf_event_open>()."
6010 msgstr ""
6011
6012 #. type: TP
6013 #: build/C/man2/perf_event_open.2:2284
6014 #, no-wrap
6015 msgid "I</proc/sys/kernel/perf_event_max_sample_rate>"
6016 msgstr ""
6017
6018 #. type: Plain text
6019 #: build/C/man2/perf_event_open.2:2293
6020 msgid ""
6021 "This sets the maximum sample rate.  Setting this too high can allow users to "
6022 "sample at a rate that impacts overall machine performance and potentially "
6023 "lock up the machine.  The default value is 100000 (samples per second)."
6024 msgstr ""
6025
6026 #. type: TP
6027 #: build/C/man2/perf_event_open.2:2293
6028 #, no-wrap
6029 msgid "I</proc/sys/kernel/perf_event_mlock_kb>"
6030 msgstr ""
6031
6032 #. type: Plain text
6033 #: build/C/man2/perf_event_open.2:2299
6034 msgid ""
6035 "Maximum number of pages an unprivileged user can B<mlock>(2).  The default "
6036 "is 516 (kB)."
6037 msgstr ""
6038
6039 #. type: Plain text
6040 #: build/C/man2/perf_event_open.2:2303
6041 msgid "Files in I</sys/bus/event_source/devices/>"
6042 msgstr ""
6043
6044 #. type: Plain text
6045 #: build/C/man2/perf_event_open.2:2309
6046 msgid ""
6047 "Since Linux 2.6.34, the kernel supports having multiple PMUs available for "
6048 "monitoring.  Information on how to program these PMUs can be found under "
6049 "I</sys/bus/event_source/devices/>.  Each subdirectory corresponds to a "
6050 "different PMU."
6051 msgstr ""
6052
6053 #. type: TP
6054 #: build/C/man2/perf_event_open.2:2309
6055 #, no-wrap
6056 msgid "I</sys/bus/event_source/devices/*/type> (since Linux 2.6.38)"
6057 msgstr ""
6058
6059 #. type: Plain text
6060 #: build/C/man2/perf_event_open.2:2316
6061 msgid ""
6062 "This contains an integer that can be used in the I<type> field of "
6063 "I<perf_event_attr> to indicate that you wish to use this PMU."
6064 msgstr ""
6065
6066 #. type: TP
6067 #: build/C/man2/perf_event_open.2:2316
6068 #, no-wrap
6069 msgid "I</sys/bus/event_source/devices/*/rdpmc> (since Linux 3.4)"
6070 msgstr ""
6071
6072 #. type: Plain text
6073 #: build/C/man2/perf_event_open.2:2321
6074 msgid ""
6075 "If this file is 1, then direct user-space access to the performance counter "
6076 "registers is allowed via the rdpmc instruction.  This can be disabled by "
6077 "echoing 0 to the file."
6078 msgstr ""
6079
6080 #. type: TP
6081 #: build/C/man2/perf_event_open.2:2321
6082 #, no-wrap
6083 msgid "I</sys/bus/event_source/devices/*/format/> (since Linux 3.4)"
6084 msgstr ""
6085
6086 #. type: Plain text
6087 #: build/C/man2/perf_event_open.2:2329
6088 msgid ""
6089 "This subdirectory contains information on the architecture-specific "
6090 "subfields available for programming the various I<config> fields in the "
6091 "I<perf_event_attr> struct."
6092 msgstr ""
6093
6094 #. type: Plain text
6095 #: build/C/man2/perf_event_open.2:2340
6096 msgid ""
6097 "The content of each file is the name of the config field, followed by a "
6098 "colon, followed by a series of integer bit ranges separated by commas.  For "
6099 "example, the file I<event> may contain the value I<config1:1,6-10,44> which "
6100 "indicates that event is an attribute that occupies bits 1,6-10, and 44 of "
6101 "I<perf_event_attr::config1>."
6102 msgstr ""
6103
6104 #. type: TP
6105 #: build/C/man2/perf_event_open.2:2340
6106 #, no-wrap
6107 msgid "I</sys/bus/event_source/devices/*/events/> (since Linux 3.4)"
6108 msgstr ""
6109
6110 #. type: Plain text
6111 #: build/C/man2/perf_event_open.2:2349
6112 msgid ""
6113 "This subdirectory contains files with predefined events.  The contents are "
6114 "strings describing the event settings expressed in terms of the fields found "
6115 "in the previously mentioned I<./format/> directory.  These are not "
6116 "necessarily complete lists of all events supported by a PMU, but usually a "
6117 "subset of events deemed useful or interesting."
6118 msgstr ""
6119
6120 #. type: Plain text
6121 #: build/C/man2/perf_event_open.2:2357
6122 msgid ""
6123 "The content of each file is a list of attribute names separated by commas.  "
6124 "Each entry has an optional value (either hex or decimal).  If no value is "
6125 "specified, then it is assumed to be a single-bit field with a value of 1.  "
6126 "An example entry may look like this: I<event=0x2,inv,ldlat=3>."
6127 msgstr ""
6128
6129 #. type: TP
6130 #: build/C/man2/perf_event_open.2:2357
6131 #, no-wrap
6132 msgid "I</sys/bus/event_source/devices/*/uevent>"
6133 msgstr ""
6134
6135 #. type: Plain text
6136 #: build/C/man2/perf_event_open.2:2361
6137 msgid ""
6138 "This file is the standard kernel device interface for injecting hotplug "
6139 "events."
6140 msgstr ""
6141
6142 #. type: TP
6143 #: build/C/man2/perf_event_open.2:2361
6144 #, no-wrap
6145 msgid "I</sys/bus/event_source/devices/*/cpumask> (since Linux 3.7)"
6146 msgstr ""
6147
6148 #. type: Plain text
6149 #: build/C/man2/perf_event_open.2:2370
6150 msgid ""
6151 "The I<cpumask> file contains a comma-separated list of integers that "
6152 "indicate a representative CPU number for each socket (package)  on the "
6153 "motherboard.  This is needed when setting up uncore or northbridge events, "
6154 "as those PMUs present socket-wide events."
6155 msgstr ""
6156
6157 #. type: Plain text
6158 #: build/C/man2/perf_event_open.2:2377
6159 msgid ""
6160 "B<perf_event_open>()  returns the new file descriptor, or -1 if an error "
6161 "occurred (in which case, I<errno> is set appropriately)."
6162 msgstr ""
6163
6164 #. type: Plain text
6165 #: build/C/man2/perf_event_open.2:2382
6166 msgid ""
6167 "The errors returned by B<perf_event_open>()  can be inconsistent, and may "
6168 "vary across processor architectures and performance monitoring units."
6169 msgstr ""
6170
6171 #. type: TP
6172 #: build/C/man2/perf_event_open.2:2382
6173 #, no-wrap
6174 msgid "B<E2BIG>"
6175 msgstr ""
6176
6177 #. type: Plain text
6178 #: build/C/man2/perf_event_open.2:2399
6179 msgid ""
6180 "Returned if the I<perf_event_attr> I<size> value is too small (smaller than "
6181 "B<PERF_ATTR_SIZE_VER0>), too big (larger than the page size), or larger than "
6182 "the kernel supports and the extra bytes are not zero.  When B<E2BIG> is "
6183 "returned, the I<perf_event_attr> I<size> field is overwritten by the kernel "
6184 "to be the size of the structure it was expecting."
6185 msgstr ""
6186
6187 #. type: Plain text
6188 #: build/C/man2/perf_event_open.2:2413
6189 msgid ""
6190 "Returned when the requested event requires B<CAP_SYS_ADMIN> permissions (or "
6191 "a more permissive perf_event paranoid setting).  Some common cases where an "
6192 "unprivileged process may encounter this error: attaching to a process owned "
6193 "by a different user; monitoring all processes on a given CPU (i.e., "
6194 "specifying the I<pid> argument as -1); and not setting I<exclude_kernel> "
6195 "when the paranoid setting requires it."
6196 msgstr ""
6197
6198 #. type: TP
6199 #: build/C/man2/perf_event_open.2:2413 build/C/man2/sendfile.2:121 build/C/man2/splice.2:143 build/C/man2/vmsplice.2:123
6200 #, no-wrap
6201 msgid "B<EBADF>"
6202 msgstr ""
6203
6204 #. type: Plain text
6205 #: build/C/man2/perf_event_open.2:2423
6206 msgid ""
6207 "Returned if the I<group_fd> file descriptor is not valid, or, if "
6208 "B<PERF_FLAG_PID_CGROUP> is set, the cgroup file descriptor in I<pid> is not "
6209 "valid."
6210 msgstr ""
6211
6212 #. type: Plain text
6213 #: build/C/man2/perf_event_open.2:2428
6214 msgid "Returned if the I<attr> pointer points at an invalid memory address."
6215 msgstr ""
6216
6217 #. type: Plain text
6218 #: build/C/man2/perf_event_open.2:2454
6219 msgid ""
6220 "Returned if the specified event is invalid.  There are many possible reasons "
6221 "for this.  A not-exhaustive list: I<sample_freq> is higher than the maximum "
6222 "setting; the I<cpu> to monitor does not exist; I<read_format> is out of "
6223 "range; I<sample_type> is out of range; the I<flags> value is out of range; "
6224 "I<exclusive> or I<pinned> set and the event is not a group leader; the event "
6225 "I<config> values are out of range or set reserved bits; the generic event "
6226 "selected is not supported; or there is not enough room to add the selected "
6227 "event."
6228 msgstr ""
6229
6230 #. type: TP
6231 #: build/C/man2/perf_event_open.2:2454
6232 #, no-wrap
6233 msgid "B<EMFILE>"
6234 msgstr ""
6235
6236 #. type: Plain text
6237 #: build/C/man2/perf_event_open.2:2460
6238 msgid ""
6239 "Each opened event uses one file descriptor.  If a large number of events are "
6240 "opened the per-user file descriptor limit (often 1024) will be hit and no "
6241 "more events can be created."
6242 msgstr ""
6243
6244 #. type: Plain text
6245 #: build/C/man2/perf_event_open.2:2464
6246 msgid "Returned when the event involves a feature not supported by the current CPU."
6247 msgstr ""
6248
6249 #. type: TP
6250 #: build/C/man2/perf_event_open.2:2464 build/C/man2/quotactl.2:440
6251 #, no-wrap
6252 msgid "B<ENOENT>"
6253 msgstr ""
6254
6255 #. type: Plain text
6256 #: build/C/man2/perf_event_open.2:2471
6257 msgid ""
6258 "Returned if the I<type> setting is not valid.  This error is also returned "
6259 "for some unsupported generic events."
6260 msgstr ""
6261
6262 #. type: TP
6263 #: build/C/man2/perf_event_open.2:2471
6264 #, no-wrap
6265 msgid "B<ENOSPC>"
6266 msgstr ""
6267
6268 #. type: Plain text
6269 #: build/C/man2/perf_event_open.2:2481
6270 msgid ""
6271 "Prior to Linux 3.3, if there was not enough room for the event, B<ENOSPC> "
6272 "was returned.  In Linux 3.3, this was changed to B<EINVAL>.  B<ENOSPC> is "
6273 "still returned if you try to add more breakpoint events than supported by "
6274 "the hardware."
6275 msgstr ""
6276
6277 #. type: Plain text
6278 #: build/C/man2/perf_event_open.2:2488
6279 msgid ""
6280 "Returned if B<PERF_SAMPLE_STACK_USER> is set in I<sample_type> and it is not "
6281 "supported by hardware."
6282 msgstr ""
6283
6284 #. type: Plain text
6285 #: build/C/man2/perf_event_open.2:2495
6286 msgid ""
6287 "Returned if an event requiring a specific hardware feature is requested but "
6288 "there is no hardware support.  This includes requesting low-skid events if "
6289 "not supported, branch tracing if it is not available, sampling if no PMU "
6290 "interrupt is available, and branch stacks for software events."
6291 msgstr ""
6292
6293 #. type: Plain text
6294 #: build/C/man2/perf_event_open.2:2500
6295 msgid ""
6296 "Returned on many (but not all) architectures when an unsupported "
6297 "I<exclude_hv>, I<exclude_idle>, I<exclude_user>, or I<exclude_kernel> "
6298 "setting is specified."
6299 msgstr ""
6300
6301 #. type: Plain text
6302 #: build/C/man2/perf_event_open.2:2508
6303 msgid ""
6304 "It can also happen, as with B<EACCES>, when the requested event requires "
6305 "B<CAP_SYS_ADMIN> permissions (or a more permissive perf_event paranoid "
6306 "setting).  This includes setting a breakpoint on a kernel address, and "
6307 "(since Linux 3.13) setting a kernel function-trace tracepoint."
6308 msgstr ""
6309
6310 #. type: Plain text
6311 #: build/C/man2/perf_event_open.2:2511
6312 msgid "Returned if attempting to attach to a process that does not exist."
6313 msgstr ""
6314
6315 #. type: SH
6316 #: build/C/man2/perf_event_open.2:2511
6317 #, no-wrap
6318 msgid "VERSION"
6319 msgstr ""
6320
6321 #. type: Plain text
6322 #: build/C/man2/perf_event_open.2:2516
6323 msgid ""
6324 "B<perf_event_open>()  was introduced in Linux 2.6.31 but was called "
6325 "B<perf_counter_open>().  It was renamed in Linux 2.6.32."
6326 msgstr ""
6327
6328 #. type: Plain text
6329 #: build/C/man2/perf_event_open.2:2521
6330 msgid ""
6331 "This B<perf_event_open>()  system call Linux- specific and should not be "
6332 "used in programs intended to be portable."
6333 msgstr ""
6334
6335 #. type: Plain text
6336 #: build/C/man2/perf_event_open.2:2525
6337 msgid ""
6338 "Glibc does not provide a wrapper for this system call; call it using "
6339 "B<syscall>(2).  See the example below."
6340 msgstr ""
6341
6342 #. type: Plain text
6343 #: build/C/man2/perf_event_open.2:2531
6344 msgid ""
6345 "The official way of knowing if B<perf_event_open>()  support is enabled is "
6346 "checking for the existence of the file "
6347 "I</proc/sys/kernel/perf_event_paranoid>."
6348 msgstr ""
6349
6350 #. type: SH
6351 #: build/C/man2/perf_event_open.2:2531 build/C/man2/pivot_root.2:134 build/C/man2/ptrace.2:1963
6352 #, no-wrap
6353 msgid "BUGS"
6354 msgstr ""
6355
6356 #. type: Plain text
6357 #: build/C/man2/perf_event_open.2:2538
6358 msgid ""
6359 "The B<F_SETOWN_EX> option to B<fcntl>(2)  is needed to properly get overflow "
6360 "signals in threads.  This was introduced in Linux 2.6.32."
6361 msgstr ""
6362
6363 #. type: Plain text
6364 #: build/C/man2/perf_event_open.2:2546
6365 msgid ""
6366 "Prior to Linux 2.6.33 (at least for x86), the kernel did not check if events "
6367 "could be scheduled together until read time.  The same happens on all known "
6368 "kernels if the NMI watchdog is enabled.  This means to see if a given set of "
6369 "events works you have to B<perf_event_open>(), start, then read before you "
6370 "know for sure you can get valid measurements."
6371 msgstr ""
6372
6373 #. type: Plain text
6374 #: build/C/man2/perf_event_open.2:2550
6375 msgid ""
6376 "Prior to Linux 2.6.34, event constraints were not enforced by the kernel.  "
6377 "In that case, some events would silently return \"0\" if the kernel "
6378 "scheduled them in an improper counter slot."
6379 msgstr ""
6380
6381 #. type: Plain text
6382 #: build/C/man2/perf_event_open.2:2553
6383 msgid ""
6384 "Prior to Linux 2.6.34, there was a bug when multiplexing where the wrong "
6385 "results could be returned."
6386 msgstr ""
6387
6388 #. type: Plain text
6389 #: build/C/man2/perf_event_open.2:2556
6390 msgid ""
6391 "Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "
6392 "\"inherit\" is enabled and many threads are started."
6393 msgstr ""
6394
6395 #. type: Plain text
6396 #: build/C/man2/perf_event_open.2:2560
6397 msgid ""
6398 "Prior to Linux 2.6.35, B<PERF_FORMAT_GROUP> did not work with attached "
6399 "processes."
6400 msgstr ""
6401
6402 #. type: Plain text
6403 #: build/C/man2/perf_event_open.2:2565
6404 msgid ""
6405 "In older Linux 2.6 versions, refreshing an event group leader refreshed all "
6406 "siblings, and refreshing with a parameter of 0 enabled infinite refresh.  "
6407 "This behavior is unsupported and should not be relied on."
6408 msgstr ""
6409
6410 #. type: Plain text
6411 #: build/C/man2/perf_event_open.2:2571
6412 msgid ""
6413 "There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that "
6414 "ignores the \"watermark\" field and acts as if a wakeup_event was chosen if "
6415 "the union has a nonzero value in it."
6416 msgstr ""
6417
6418 #. type: Plain text
6419 #: build/C/man2/perf_event_open.2:2577
6420 msgid ""
6421 "From Linux 2.6.31 to Linux 3.4, the B<PERF_IOC_FLAG_GROUP> ioctl argument "
6422 "was broken and would repeatedly operate on the event specified rather than "
6423 "iterating across all sibling events in a group."
6424 msgstr ""
6425
6426 #. type: Plain text
6427 #: build/C/man2/perf_event_open.2:2588
6428 msgid ""
6429 "From Linux 3.4 to Linux 3.11, the mmap I<cap_usr_rdpmc> and I<cap_usr_time> "
6430 "bits mapped to the same location.  Code should migrate to the new "
6431 "I<cap_user_rdpmc> and I<cap_user_time> fields instead."
6432 msgstr ""
6433
6434 #. type: Plain text
6435 #: build/C/man2/perf_event_open.2:2593
6436 msgid ""
6437 "Always double-check your results! Various generalized events have had wrong "
6438 "values.  For example, retired branches measured the wrong thing on AMD "
6439 "machines until Linux 2.6.35."
6440 msgstr ""
6441
6442 #. type: SH
6443 #: build/C/man2/perf_event_open.2:2593 build/C/man2/process_vm_readv.2:295 build/C/man2/splice.2:223 build/C/man2/tee.2:130
6444 #, no-wrap
6445 msgid "EXAMPLE"
6446 msgstr ""
6447
6448 #. type: Plain text
6449 #: build/C/man2/perf_event_open.2:2597
6450 msgid ""
6451 "The following is a short example that measures the total instruction count "
6452 "of a call to B<printf>(3)."
6453 msgstr ""
6454
6455 #. type: Plain text
6456 #: build/C/man2/perf_event_open.2:2606
6457 #, no-wrap
6458 msgid ""
6459 "#include E<lt>stdlib.hE<gt>\n"
6460 "#include E<lt>stdio.hE<gt>\n"
6461 "#include E<lt>unistd.hE<gt>\n"
6462 "#include E<lt>string.hE<gt>\n"
6463 "#include E<lt>sys/ioctl.hE<gt>\n"
6464 "#include E<lt>linux/perf_event.hE<gt>\n"
6465 "#include E<lt>asm/unistd.hE<gt>\n"
6466 msgstr ""
6467
6468 #. type: Plain text
6469 #: build/C/man2/perf_event_open.2:2612
6470 #, no-wrap
6471 msgid ""
6472 "static long\n"
6473 "perf_event_open(struct perf_event_attr *hw_event, pid_t pid,\n"
6474 "                int cpu, int group_fd, unsigned long flags)\n"
6475 "{\n"
6476 "    int ret;\n"
6477 msgstr ""
6478
6479 #. type: Plain text
6480 #: build/C/man2/perf_event_open.2:2617
6481 #, no-wrap
6482 msgid ""
6483 "    ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,\n"
6484 "                   group_fd, flags);\n"
6485 "    return ret;\n"
6486 "}\n"
6487 msgstr ""
6488
6489 #. type: Plain text
6490 #: build/C/man2/perf_event_open.2:2624
6491 #, no-wrap
6492 msgid ""
6493 "int\n"
6494 "main(int argc, char **argv)\n"
6495 "{\n"
6496 "    struct perf_event_attr pe;\n"
6497 "    long long count;\n"
6498 "    int fd;\n"
6499 msgstr ""
6500
6501 #. type: Plain text
6502 #: build/C/man2/perf_event_open.2:2632
6503 #, no-wrap
6504 msgid ""
6505 "    memset(&pe, 0, sizeof(struct perf_event_attr));\n"
6506 "    pe.type = PERF_TYPE_HARDWARE;\n"
6507 "    pe.size = sizeof(struct perf_event_attr);\n"
6508 "    pe.config = PERF_COUNT_HW_INSTRUCTIONS;\n"
6509 "    pe.disabled = 1;\n"
6510 "    pe.exclude_kernel = 1;\n"
6511 "    pe.exclude_hv = 1;\n"
6512 msgstr ""
6513
6514 #. type: Plain text
6515 #: build/C/man2/perf_event_open.2:2638
6516 #, no-wrap
6517 msgid ""
6518 "    fd = perf_event_open(&pe, 0, -1, -1, 0);\n"
6519 "    if (fd == -1) {\n"
6520 "       fprintf(stderr, \"Error opening leader %llx\\en\", pe.config);\n"
6521 "       exit(EXIT_FAILURE);\n"
6522 "    }\n"
6523 msgstr ""
6524
6525 #. type: Plain text
6526 #: build/C/man2/perf_event_open.2:2641
6527 #, no-wrap
6528 msgid ""
6529 "    ioctl(fd, PERF_EVENT_IOC_RESET, 0);\n"
6530 "    ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);\n"
6531 msgstr ""
6532
6533 #. type: Plain text
6534 #: build/C/man2/perf_event_open.2:2643
6535 #, no-wrap
6536 msgid "    printf(\"Measuring instruction count for this printf\\en\");\n"
6537 msgstr ""
6538
6539 #. type: Plain text
6540 #: build/C/man2/perf_event_open.2:2646
6541 #, no-wrap
6542 msgid ""
6543 "    ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);\n"
6544 "    read(fd, &count, sizeof(long long));\n"
6545 msgstr ""
6546
6547 #. type: Plain text
6548 #: build/C/man2/perf_event_open.2:2648
6549 #, no-wrap
6550 msgid "    printf(\"Used %lld instructions\\en\", count);\n"
6551 msgstr ""
6552
6553 #. type: Plain text
6554 #: build/C/man2/perf_event_open.2:2651
6555 #, no-wrap
6556 msgid ""
6557 "    close(fd);\n"
6558 "}\n"
6559 msgstr ""
6560
6561 #. type: Plain text
6562 #: build/C/man2/perf_event_open.2:2658
6563 msgid "B<fcntl>(2), B<mmap>(2), B<open>(2), B<prctl>(2), B<read>(2)"
6564 msgstr ""
6565
6566 #. type: TH
6567 #: build/C/man2/perfmonctl.2:27
6568 #, no-wrap
6569 msgid "PERFMONCTL"
6570 msgstr ""
6571
6572 #. type: Plain text
6573 #: build/C/man2/perfmonctl.2:30
6574 msgid "perfmonctl - interface to IA-64 performance monitoring unit"
6575 msgstr ""
6576
6577 #. type: Plain text
6578 #: build/C/man2/perfmonctl.2:34
6579 #, no-wrap
6580 msgid ""
6581 "B<#include E<lt>syscall.hE<gt>>\n"
6582 "B<#include E<lt>perfmon.hE<gt>>\n"
6583 msgstr ""
6584
6585 #. type: Plain text
6586 #: build/C/man2/perfmonctl.2:36
6587 #, no-wrap
6588 msgid ""
6589 "B<long perfmonctl(int >I<fd>B<, int >I<cmd>B<, void *>I<arg>B<, int "
6590 ">I<narg>B<);>\n"
6591 msgstr ""
6592
6593 #. type: Plain text
6594 #: build/C/man2/perfmonctl.2:47
6595 msgid ""
6596 "The IA-64-specific B<perfmonctl>()  system call provides an interface to the "
6597 "PMU (performance monitoring unit).  The PMU consists of PMD (performance "
6598 "monitoring data) registers and PMC (performance monitoring control) "
6599 "registers, which gather hardware statistics."
6600 msgstr ""
6601
6602 #. type: Plain text
6603 #: build/C/man2/perfmonctl.2:57
6604 msgid ""
6605 "B<perfmonctl>()  applies the operation I<cmd> to the input arguments "
6606 "specified by I<arg>.  The number of arguments is defined by I<narg>.  The "
6607 "I<fd> argument specifies the perfmon context to operate on."
6608 msgstr ""
6609
6610 #. type: Plain text
6611 #: build/C/man2/perfmonctl.2:61
6612 msgid "Supported values for I<cmd> are:"
6613 msgstr ""
6614
6615 #. type: TP
6616 #: build/C/man2/perfmonctl.2:61
6617 #, no-wrap
6618 msgid "B<PFM_CREATE_CONTEXT>"
6619 msgstr ""
6620
6621 #. type: Plain text
6622 #: build/C/man2/perfmonctl.2:65
6623 #, no-wrap
6624 msgid ""
6625 "B<perfmonctl(int >I<fd>B<, PFM_CREATE_CONTEXT, pfarg_context_t *>I<ctxt>B<, "
6626 "1);>\n"
6627 msgstr ""
6628
6629 #. type: Plain text
6630 #: build/C/man2/perfmonctl.2:67
6631 msgid "Set up a context."
6632 msgstr ""
6633
6634 #. type: Plain text
6635 #: build/C/man2/perfmonctl.2:74
6636 msgid ""
6637 "The I<fd> parameter is ignored.  A new perfmon context is created as "
6638 "specified in I<ctxt> and its file descriptor is returned in "
6639 "I<ctxt-E<gt>ctx_fd>."
6640 msgstr ""
6641
6642 #. type: Plain text
6643 #: build/C/man2/perfmonctl.2:86
6644 msgid ""
6645 "The file descriptor can be used in subsequent calls to B<perfmonctl>()  and "
6646 "can be used to read event notifications (type I<pfm_msg_t>)  using "
6647 "B<read>(2).  The file descriptor is pollable using B<select>(2), B<poll>(2), "
6648 "and B<epoll>(7)."
6649 msgstr ""
6650
6651 #. type: Plain text
6652 #: build/C/man2/perfmonctl.2:90
6653 msgid "The context can be destroyed by calling B<close>(2)  on the file descriptor."
6654 msgstr ""
6655
6656 #. type: TP
6657 #: build/C/man2/perfmonctl.2:90
6658 #, no-wrap
6659 msgid "B<PFM_WRITE_PMCS>"
6660 msgstr ""
6661
6662 #. type: Plain text
6663 #: build/C/man2/perfmonctl.2:95
6664 #, no-wrap
6665 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMCS, pfarg_reg_t *>I<pmcs>B<, n);>\n"
6666 msgstr ""
6667
6668 #. type: Plain text
6669 #: build/C/man2/perfmonctl.2:97
6670 msgid "Set PMC registers."
6671 msgstr ""
6672
6673 #. type: TP
6674 #: build/C/man2/perfmonctl.2:97
6675 #, no-wrap
6676 msgid "B<PFM_WRITE_PMDS>"
6677 msgstr ""
6678
6679 #. type: Plain text
6680 #: build/C/man2/perfmonctl.2:101
6681 #, no-wrap
6682 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6683 msgstr ""
6684
6685 #.  pfm_write_pmds()
6686 #. type: Plain text
6687 #: build/C/man2/perfmonctl.2:104
6688 msgid "Set PMD registers."
6689 msgstr ""
6690
6691 #. type: TP
6692 #: build/C/man2/perfmonctl.2:104
6693 #, no-wrap
6694 msgid "B<PFM_READ_PMDS>"
6695 msgstr ""
6696
6697 #. type: Plain text
6698 #: build/C/man2/perfmonctl.2:109
6699 #, no-wrap
6700 msgid "B<perfmonctl(int >I<fd>B<, PFM_READ_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6701 msgstr ""
6702
6703 #. type: Plain text
6704 #: build/C/man2/perfmonctl.2:111
6705 msgid "Read PMD registers."
6706 msgstr ""
6707
6708 #. type: TP
6709 #: build/C/man2/perfmonctl.2:111
6710 #, no-wrap
6711 msgid "B<PFM_START>"
6712 msgstr ""
6713
6714 #.  .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
6715 #. type: Plain text
6716 #: build/C/man2/perfmonctl.2:117
6717 #, no-wrap
6718 msgid "B<perfmonctl(int >I<fd>B<, PFM_START, NULL, 0);>\n"
6719 msgstr ""
6720
6721 #. type: Plain text
6722 #: build/C/man2/perfmonctl.2:119
6723 msgid "Start monitoring."
6724 msgstr ""
6725
6726 #. type: TP
6727 #: build/C/man2/perfmonctl.2:119
6728 #, no-wrap
6729 msgid "B<PFM_STOP>"
6730 msgstr ""
6731
6732 #. type: Plain text
6733 #: build/C/man2/perfmonctl.2:124
6734 #, no-wrap
6735 msgid "B<perfmonctl(int >I<fd>B<, PFM_STOP, NULL, 0);>\n"
6736 msgstr ""
6737
6738 #. type: Plain text
6739 #: build/C/man2/perfmonctl.2:126
6740 msgid "Stop monitoring."
6741 msgstr ""
6742
6743 #. type: TP
6744 #: build/C/man2/perfmonctl.2:126
6745 #, no-wrap
6746 msgid "B<PFM_LOAD_CONTEXT>"
6747 msgstr ""
6748
6749 #. type: Plain text
6750 #: build/C/man2/perfmonctl.2:131
6751 #, no-wrap
6752 msgid ""
6753 "B<perfmonctl(int >I<fd>B<, PFM_LOAD_CONTEXT, pfarg_load_t *>I<largs>B<, "
6754 "1);>\n"
6755 msgstr ""
6756
6757 #. type: Plain text
6758 #: build/C/man2/perfmonctl.2:133
6759 msgid "Attach the context to a thread."
6760 msgstr ""
6761
6762 #. type: TP
6763 #: build/C/man2/perfmonctl.2:133
6764 #, no-wrap
6765 msgid "B<PFM_UNLOAD_CONTEXT>"
6766 msgstr ""
6767
6768 #. type: Plain text
6769 #: build/C/man2/perfmonctl.2:138
6770 #, no-wrap
6771 msgid "B<perfmonctl(int >I<fd>B<, PFM_UNLOAD_CONTEXT, NULL, 0);>\n"
6772 msgstr ""
6773
6774 #. type: Plain text
6775 #: build/C/man2/perfmonctl.2:140
6776 msgid "Detach the context from a thread."
6777 msgstr ""
6778
6779 #. type: TP
6780 #: build/C/man2/perfmonctl.2:140
6781 #, no-wrap
6782 msgid "B<PFM_RESTART>"
6783 msgstr ""
6784
6785 #. type: Plain text
6786 #: build/C/man2/perfmonctl.2:145
6787 #, no-wrap
6788 msgid "B<perfmonctl(int >I<fd>B<, PFM_RESTART, NULL, 0);>\n"
6789 msgstr ""
6790
6791 #. type: Plain text
6792 #: build/C/man2/perfmonctl.2:147
6793 msgid "Restart monitoring after receiving an overflow notification."
6794 msgstr ""
6795
6796 #. type: TP
6797 #: build/C/man2/perfmonctl.2:147
6798 #, no-wrap
6799 msgid "B<PFM_GET_FEATURES>"
6800 msgstr ""
6801
6802 #. type: Plain text
6803 #: build/C/man2/perfmonctl.2:152
6804 #, no-wrap
6805 msgid ""
6806 "B<perfmonctl(int >I<fd>B<, PFM_GET_FEARURES, pfarg_features_t *>I<arg>B<, "
6807 "1);>\n"
6808 msgstr ""
6809
6810 #. type: TP
6811 #: build/C/man2/perfmonctl.2:153
6812 #, no-wrap
6813 msgid "B<PFM_DEBUG>"
6814 msgstr ""
6815
6816 #. type: Plain text
6817 #: build/C/man2/perfmonctl.2:158
6818 #, no-wrap
6819 msgid "B<perfmonctl(int >I<fd>B<, PFM_DEBUG, >I<val>B<, 0);>\n"
6820 msgstr ""
6821
6822 #. type: Plain text
6823 #: build/C/man2/perfmonctl.2:162
6824 msgid "If I<val> is nonzero, enable debugging mode, otherwise disable."
6825 msgstr ""
6826
6827 #. type: TP
6828 #: build/C/man2/perfmonctl.2:162
6829 #, no-wrap
6830 msgid "B<PFM_GET_PMC_RESET_VAL>"
6831 msgstr ""
6832
6833 #. type: Plain text
6834 #: build/C/man2/perfmonctl.2:167
6835 #, no-wrap
6836 msgid ""
6837 "B<perfmonctl(int >I<fd>B<, PFM_GET_PMC_RESET_VAL, pfarg_reg_t * >I<req>B<, "
6838 "n);>\n"
6839 msgstr ""
6840
6841 #
6842 #
6843 #.  .TP
6844 #.  .B PFM_CREATE_EVTSETS
6845 #
6846 #.  create or modify event sets
6847 #.  .nf
6848 #.  .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
6849 #.  .fi
6850 #.  .TP
6851 #.  .B PFM_DELETE_EVTSETS
6852 #.  delete event sets
6853 #.  .nf
6854 #.  .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
6855 #.  .fi
6856 #.  .TP
6857 #.  .B PFM_GETINFO_EVTSETS
6858 #.  get information about event sets
6859 #.  .nf
6860 #.  .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
6861 #.  .fi
6862 #. type: Plain text
6863 #: build/C/man2/perfmonctl.2:190
6864 msgid "Reset PMC registers to default values."
6865 msgstr ""
6866
6867 #. type: Plain text
6868 #: build/C/man2/perfmonctl.2:196
6869 msgid ""
6870 "B<perfmonctl>()  returns zero when the operation is successful.  On error, "
6871 "-1 is returned and I<errno> is set to indicate the cause of the error."
6872 msgstr ""
6873
6874 #. type: Plain text
6875 #: build/C/man2/perfmonctl.2:199
6876 msgid "B<perfmonctl>()  is available since Linux 2.4."
6877 msgstr ""
6878
6879 #. type: Plain text
6880 #: build/C/man2/perfmonctl.2:202
6881 msgid ""
6882 "B<perfmonctl>()  is Linux-specific and is available only on the IA-64 "
6883 "architecture."
6884 msgstr ""
6885
6886 #. type: Plain text
6887 #: build/C/man2/perfmonctl.2:207
6888 msgid "B<gprof>(1)"
6889 msgstr ""
6890
6891 #. type: Plain text
6892 #: build/C/man2/perfmonctl.2:209
6893 msgid "The perfmon2 interface specification"
6894 msgstr ""
6895
6896 #. type: TH
6897 #: build/C/man2/personality.2:32
6898 #, no-wrap
6899 msgid "PERSONALITY"
6900 msgstr ""
6901
6902 #. type: TH
6903 #: build/C/man2/personality.2:32
6904 #, no-wrap
6905 msgid "2014-04-15"
6906 msgstr ""
6907
6908 #. type: Plain text
6909 #: build/C/man2/personality.2:35
6910 msgid "personality - set the process execution domain"
6911 msgstr ""
6912
6913 #. type: Plain text
6914 #: build/C/man2/personality.2:37
6915 msgid "B<#include E<lt>sys/personality.hE<gt>>"
6916 msgstr ""
6917
6918 #. type: Plain text
6919 #: build/C/man2/personality.2:39
6920 msgid "B<int personality(unsigned long >I<persona>B<);>"
6921 msgstr ""
6922
6923 #. type: Plain text
6924 #: build/C/man2/personality.2:47
6925 msgid ""
6926 "Linux supports different execution domains, or personalities, for each "
6927 "process.  Among other things, execution domains tell Linux how to map signal "
6928 "numbers into signal actions.  The execution domain system allows Linux to "
6929 "provide limited support for binaries compiled under other UNIX-like "
6930 "operating systems."
6931 msgstr ""
6932
6933 #. type: Plain text
6934 #: build/C/man2/personality.2:59
6935 msgid ""
6936 "If I<persona> is not 0xffffffff, then B<personality>()  sets the caller's "
6937 "execution domain to the value specified by I<persona>.  Specifying "
6938 "I<persona> as 0xffffffff provides a way of retrieving the current persona "
6939 "without changing it."
6940 msgstr ""
6941
6942 #. type: Plain text
6943 #: build/C/man2/personality.2:62
6944 msgid ""
6945 "A list of the available execution domains can be found in "
6946 "I<E<lt>sys/personality.hE<gt>>."
6947 msgstr ""
6948
6949 #. type: Plain text
6950 #: build/C/man2/personality.2:69
6951 msgid ""
6952 "On success, the previous I<persona> is returned.  On error, -1 is returned, "
6953 "and I<errno> is set appropriately."
6954 msgstr ""
6955
6956 #. type: Plain text
6957 #: build/C/man2/personality.2:73
6958 msgid "The kernel was unable to change the personality."
6959 msgstr ""
6960
6961 #. type: Plain text
6962 #: build/C/man2/personality.2:77
6963 msgid ""
6964 "B<personality>()  is Linux-specific and should not be used in programs "
6965 "intended to be portable."
6966 msgstr ""
6967
6968 #. type: TH
6969 #: build/C/man2/pivot_root.2:10
6970 #, no-wrap
6971 msgid "PIVOT_ROOT"
6972 msgstr ""
6973
6974 #. type: Plain text
6975 #: build/C/man2/pivot_root.2:13
6976 msgid "pivot_root - change the root filesystem"
6977 msgstr ""
6978
6979 #. type: Plain text
6980 #: build/C/man2/pivot_root.2:15
6981 msgid "B<int pivot_root(const char *>I<new_root>B<, const char *>I<put_old>B<);>"
6982 msgstr ""
6983
6984 #
6985 #.  The
6986 #.  .B CAP_SYS_ADMIN
6987 #.  capability is required.
6988 #. type: Plain text
6989 #: build/C/man2/pivot_root.2:27
6990 msgid ""
6991 "B<pivot_root>()  moves the root filesystem of the calling process to the "
6992 "directory I<put_old> and makes I<new_root> the new root filesystem of the "
6993 "calling process."
6994 msgstr ""
6995
6996 #. type: Plain text
6997 #: build/C/man2/pivot_root.2:34
6998 msgid ""
6999 "The typical use of B<pivot_root>()  is during system startup, when the "
7000 "system mounts a temporary root filesystem (e.g., an B<initrd>), then mounts "
7001 "the real root filesystem, and eventually turns the latter into the current "
7002 "root of all relevant processes or threads."
7003 msgstr ""
7004
7005 #. type: Plain text
7006 #: build/C/man2/pivot_root.2:46
7007 msgid ""
7008 "B<pivot_root>()  may or may not change the current root and the current "
7009 "working directory of any processes or threads which use the old root "
7010 "directory.  The caller of B<pivot_root>()  must ensure that processes with "
7011 "root or current working directory at the old root operate correctly in "
7012 "either case.  An easy way to ensure this is to change their root and current "
7013 "working directory to I<new_root> before invoking B<pivot_root>()."
7014 msgstr ""
7015
7016 #. type: Plain text
7017 #: build/C/man2/pivot_root.2:64
7018 msgid ""
7019 "The paragraph above is intentionally vague because the implementation of "
7020 "B<pivot_root>()  may change in the future.  At the time of writing, "
7021 "B<pivot_root>()  changes root and current working directory of each process "
7022 "or thread to I<new_root> if they point to the old root directory.  This is "
7023 "necessary in order to prevent kernel threads from keeping the old root "
7024 "directory busy with their root and current working directory, even if they "
7025 "never access the filesystem in any way.  In the future, there may be a "
7026 "mechanism for kernel threads to explicitly relinquish any access to the "
7027 "filesystem, such that this fairly intrusive mechanism can be removed from "
7028 "B<pivot_root>()."
7029 msgstr ""
7030
7031 #. type: Plain text
7032 #: build/C/man2/pivot_root.2:72
7033 msgid ""
7034 "Note that this also applies to the calling process: B<pivot_root>()  may or "
7035 "may not affect its current working directory.  It is therefore recommended "
7036 "to call B<chdir(\"/\")> immediately after B<pivot_root>()."
7037 msgstr ""
7038
7039 #. type: Plain text
7040 #: build/C/man2/pivot_root.2:74
7041 msgid "The following restrictions apply to I<new_root> and I<put_old>:"
7042 msgstr ""
7043
7044 #. type: IP
7045 #: 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
7046 #, no-wrap
7047 msgid "-"
7048 msgstr ""
7049
7050 #. type: Plain text
7051 #: build/C/man2/pivot_root.2:76
7052 msgid "They must be directories."
7053 msgstr ""
7054
7055 #. type: Plain text
7056 #: build/C/man2/pivot_root.2:79
7057 msgid ""
7058 "I<new_root> and I<put_old> must not be on the same filesystem as the current "
7059 "root."
7060 msgstr ""
7061
7062 #. type: Plain text
7063 #: build/C/man2/pivot_root.2:83
7064 msgid ""
7065 "I<put_old> must be underneath I<new_root>, that is, adding a nonzero number "
7066 "of I</..> to the string pointed to by I<put_old> must yield the same "
7067 "directory as I<new_root>."
7068 msgstr ""
7069
7070 #. type: Plain text
7071 #: build/C/man2/pivot_root.2:85
7072 msgid "No other filesystem may be mounted on I<put_old>."
7073 msgstr ""
7074
7075 #. type: Plain text
7076 #: build/C/man2/pivot_root.2:89
7077 msgid "See also B<pivot_root>(8)  for additional usage examples."
7078 msgstr ""
7079
7080 #. type: Plain text
7081 #: build/C/man2/pivot_root.2:96
7082 msgid ""
7083 "If the current root is not a mount point (e.g., after B<chroot>(2)  or "
7084 "B<pivot_root>(), see also below), not the old root directory, but the mount "
7085 "point of that filesystem is mounted on I<put_old>."
7086 msgstr ""
7087
7088 #. type: Plain text
7089 #: build/C/man2/pivot_root.2:101
7090 msgid ""
7091 "I<new_root> does not have to be a mount point.  In this case, "
7092 "I</proc/mounts> will show the mount point of the filesystem containing "
7093 "I<new_root> as root (I</>)."
7094 msgstr ""
7095
7096 #. type: Plain text
7097 #: build/C/man2/pivot_root.2:110
7098 msgid ""
7099 "B<pivot_root>()  may return (in I<errno>) any of the errors returned by "
7100 "B<stat>(2).  Additionally, it may return:"
7101 msgstr ""
7102
7103 #. type: Plain text
7104 #: build/C/man2/pivot_root.2:114
7105 msgid ""
7106 "I<new_root> or I<put_old> are on the current root filesystem, or a "
7107 "filesystem is already mounted on I<put_old>."
7108 msgstr ""
7109
7110 #. type: Plain text
7111 #: build/C/man2/pivot_root.2:117
7112 msgid "I<put_old> is not underneath I<new_root>."
7113 msgstr ""
7114
7115 #. type: TP
7116 #: build/C/man2/pivot_root.2:117
7117 #, no-wrap
7118 msgid "B<ENOTDIR>"
7119 msgstr ""
7120
7121 #. type: Plain text
7122 #: build/C/man2/pivot_root.2:120
7123 msgid "I<new_root> or I<put_old> is not a directory."
7124 msgstr ""
7125
7126 #. type: Plain text
7127 #: build/C/man2/pivot_root.2:125
7128 msgid "The calling process does not have the B<CAP_SYS_ADMIN> capability."
7129 msgstr ""
7130
7131 #. type: Plain text
7132 #: build/C/man2/pivot_root.2:128
7133 msgid "B<pivot_root>()  was introduced in Linux 2.3.41."
7134 msgstr ""
7135
7136 #. type: Plain text
7137 #: build/C/man2/pivot_root.2:131
7138 msgid "B<pivot_root>()  is Linux-specific and hence is not portable."
7139 msgstr ""
7140
7141 #. type: Plain text
7142 #: build/C/man2/pivot_root.2:138
7143 msgid ""
7144 "B<pivot_root>()  should not have to change root and current working "
7145 "directory of all other processes in the system."
7146 msgstr ""
7147
7148 #. type: Plain text
7149 #: build/C/man2/pivot_root.2:143
7150 msgid ""
7151 "Some of the more obscure uses of B<pivot_root>()  may quickly lead to "
7152 "insanity."
7153 msgstr ""
7154
7155 #. type: Plain text
7156 #: build/C/man2/pivot_root.2:149
7157 msgid "B<chdir>(2), B<chroot>(2), B<stat>(2), B<initrd>(4), B<pivot_root>(8)"
7158 msgstr ""
7159
7160 #. type: TH
7161 #: build/C/man2/process_vm_readv.2:29
7162 #, no-wrap
7163 msgid "PROCESS_VM_READV"
7164 msgstr ""
7165
7166 #. type: TH
7167 #: build/C/man2/process_vm_readv.2:29
7168 #, no-wrap
7169 msgid "2012-04-25"
7170 msgstr ""
7171
7172 #. type: Plain text
7173 #: build/C/man2/process_vm_readv.2:32
7174 msgid ""
7175 "process_vm_readv, process_vm_writev - transfer data between process address "
7176 "spaces"
7177 msgstr ""
7178
7179 #. type: Plain text
7180 #: build/C/man2/process_vm_readv.2:35
7181 #, no-wrap
7182 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
7183 msgstr ""
7184
7185 #. type: Plain text
7186 #: build/C/man2/process_vm_readv.2:42
7187 #, no-wrap
7188 msgid ""
7189 "B<ssize_t process_vm_readv(pid_t >I<pid>B<,>\n"
7190 "B<                         const struct iovec *>I<local_iov>B<,>\n"
7191 "B<                         unsigned long >I<liovcnt>B<,>\n"
7192 "B<                         const struct iovec *>I<remote_iov>B<,>\n"
7193 "B<                         unsigned long >I<riovcnt>B<,>\n"
7194 "B<                         unsigned long >I<flags>B<);>\n"
7195 msgstr ""
7196
7197 #. type: Plain text
7198 #: build/C/man2/process_vm_readv.2:49
7199 #, no-wrap
7200 msgid ""
7201 "B<ssize_t process_vm_writev(pid_t >I<pid>B<,>\n"
7202 "B<                          const struct iovec *>I<local_iov>B<,>\n"
7203 "B<                          unsigned long >I<liovcnt>B<,>\n"
7204 "B<                          const struct iovec *>I<remote_iov>B<,>\n"
7205 "B<                          unsigned long >I<riovcnt>B<,>\n"
7206 "B<                          unsigned long >I<flags>B<);>\n"
7207 msgstr ""
7208
7209 #. type: Plain text
7210 #: build/C/man2/process_vm_readv.2:57
7211 msgid ""
7212 "These system calls transfer data between the address space of the calling "
7213 "process (\"the local process\") and the process identified by I<pid> (\"the "
7214 "remote process\").  The data moves directly between the address spaces of "
7215 "the two processes, without passing through kernel space."
7216 msgstr ""
7217
7218 #. type: Plain text
7219 #: build/C/man2/process_vm_readv.2:82
7220 msgid ""
7221 "The B<process_vm_readv>()  system call transfers data from the remote "
7222 "process to the local process.  The data to be transferred is identified by "
7223 "I<remote_iov> and I<riovcnt>: I<remote_iov> is a pointer to an array "
7224 "describing address ranges in the process I<pid>, and I<riovcnt> specifies "
7225 "the number of elements in I<remote_iov>.  The data is transferred to the "
7226 "locations specified by I<local_iov> and I<liovcnt>: I<local_iov> is a "
7227 "pointer to an array describing address ranges in the calling process, and "
7228 "I<liovcnt> specifies the number of elements in I<local_iov>."
7229 msgstr ""
7230
7231 #. type: Plain text
7232 #: build/C/man2/process_vm_readv.2:96
7233 msgid ""
7234 "The B<process_vm_writev>()  system call is the converse of "
7235 "B<process_vm_readv>()\\(emit transfers data from the local process to the "
7236 "remote process.  Other than the direction of the transfer, the arguments "
7237 "I<liovcnt>, I<local_iov>, I<riovcnt>, and I<remote_iov> have the same "
7238 "meaning as for B<process_vm_readv>()."
7239 msgstr ""
7240
7241 #. type: Plain text
7242 #: build/C/man2/process_vm_readv.2:106
7243 msgid ""
7244 "The I<local_iov> and I<remote_iov> arguments point to an array of I<iovec> "
7245 "structures, defined in I<E<lt>sys/uio.hE<gt>> as:"
7246 msgstr ""
7247
7248 #. type: Plain text
7249 #: build/C/man2/process_vm_readv.2:113
7250 #, no-wrap
7251 msgid ""
7252 "struct iovec {\n"
7253 "    void  *iov_base;    /* Starting address */\n"
7254 "    size_t iov_len;     /* Number of bytes to transfer */\n"
7255 "};\n"
7256 msgstr ""
7257
7258 #. type: Plain text
7259 #: build/C/man2/process_vm_readv.2:129
7260 msgid ""
7261 "Buffers are processed in array order.  This means that B<process_vm_readv>()  "
7262 "completely fills I<local_iov[0]> before proceeding to I<local_iov[1]>, and "
7263 "so on.  Likewise, I<remote_iov[0]> is completely read before proceeding to "
7264 "I<remote_iov[1]>, and so on."
7265 msgstr ""
7266
7267 #. type: Plain text
7268 #: build/C/man2/process_vm_readv.2:140
7269 msgid ""
7270 "Similarly, B<process_vm_writev>()  writes out the entire contents of "
7271 "I<local_iov[0]> before proceeding to I<local_iov[1]>, and it completely "
7272 "fills I<remote_iov[0]> before proceeding to I<remote_iov[1]>."
7273 msgstr ""
7274
7275 #. type: Plain text
7276 #: build/C/man2/process_vm_readv.2:148
7277 msgid ""
7278 "The lengths of I<remote_iov[i].iov_len> and I<local_iov[i].iov_len> do not "
7279 "have to be the same.  Thus, it is possible to split a single local buffer "
7280 "into multiple remote buffers, or vice versa."
7281 msgstr ""
7282
7283 #. type: Plain text
7284 #: build/C/man2/process_vm_readv.2:152
7285 msgid "The I<flags> argument is currently unused and must be set to 0."
7286 msgstr ""
7287
7288 #.  In time, glibc might provide a wrapper that works around this limit,
7289 #.  as is done for readv()/writev()
7290 #. type: Plain text
7291 #: build/C/man2/process_vm_readv.2:165
7292 msgid ""
7293 "The values specified in the I<liovcnt> and I<riovcnt> arguments must be less "
7294 "than or equal to B<IOV_MAX> (defined in I<E<lt>limits.hE<gt>> or accessible "
7295 "via the call I<sysconf(_SC_IOV_MAX)>)."
7296 msgstr ""
7297
7298 #. type: Plain text
7299 #: build/C/man2/process_vm_readv.2:175
7300 msgid ""
7301 "The count arguments and I<local_iov> are checked before doing any "
7302 "transfers.  If the counts are too big, or I<local_iov> is invalid, or the "
7303 "addresses refer to regions that are inaccessible to the local process, none "
7304 "of the vectors will be processed and an error will be returned immediately."
7305 msgstr ""
7306
7307 #. type: Plain text
7308 #: build/C/man2/process_vm_readv.2:195
7309 msgid ""
7310 "Note, however, that these system calls do not check the memory regions in "
7311 "the remote process until just before doing the read/write.  Consequently, a "
7312 "partial read/write (see RETURN VALUE)  may result if one of the "
7313 "I<remote_iov> elements points to an invalid memory region in the remote "
7314 "process.  No further reads/writes will be attempted beyond that point.  Keep "
7315 "this in mind when attempting to read data of unknown length (such as C "
7316 "strings that are null-terminated) from a remote process, by avoiding "
7317 "spanning memory pages (typically 4KiB) in a single remote I<iovec> element.  "
7318 "(Instead, split the remote read into two I<remote_iov> elements and have "
7319 "them merge back into a single write I<local_iov> entry.  The first read "
7320 "entry goes up to the page boundary, while the second starts on the next page "
7321 "boundary.)"
7322 msgstr ""
7323
7324 #. type: Plain text
7325 #: build/C/man2/process_vm_readv.2:209
7326 msgid ""
7327 "In order to read from or write to another process, either the caller must "
7328 "have the capability B<CAP_SYS_PTRACE>, or the real user ID, effective user "
7329 "ID, and saved set-user-ID of the remote process must match the real user ID "
7330 "of the caller I<and> the real group ID, effective group ID, and saved "
7331 "set-group-ID of the remote process must match the real group ID of the "
7332 "caller.  (The permission required is exactly the same as that required to "
7333 "perform a B<ptrace>(2)  B<PTRACE_ATTACH> on the remote process.)"
7334 msgstr ""
7335
7336 #. type: Plain text
7337 #: build/C/man2/process_vm_readv.2:225
7338 msgid ""
7339 "On success, B<process_vm_readv>()  returns the number of bytes read and "
7340 "B<process_vm_writev>()  returns the number of bytes written.  This return "
7341 "value may be less than the total number of requested bytes, if a partial "
7342 "read/write occurred.  (Partial transfers apply at the granularity of "
7343 "I<iovec> elements.  These system calls won't perform a partial transfer that "
7344 "splits a single I<iovec> element.)  The caller should check the return value "
7345 "to determine whether a partial read/write occurred."
7346 msgstr ""
7347
7348 #. type: Plain text
7349 #: build/C/man2/process_vm_readv.2:229
7350 msgid "On error, -1 is returned and I<errno> is set appropriately."
7351 msgstr ""
7352
7353 #. type: Plain text
7354 #: build/C/man2/process_vm_readv.2:241
7355 msgid ""
7356 "The sum of the I<iov_len> values of either I<local_iov> or I<remote_iov> "
7357 "overflows a I<ssize_t> value."
7358 msgstr ""
7359
7360 #. type: Plain text
7361 #: build/C/man2/process_vm_readv.2:245
7362 msgid "I<flags> is not 0."
7363 msgstr ""
7364
7365 #. type: Plain text
7366 #: build/C/man2/process_vm_readv.2:251
7367 msgid "I<liovcnt> or I<riovcnt> is too large."
7368 msgstr ""
7369
7370 #. type: Plain text
7371 #: build/C/man2/process_vm_readv.2:256
7372 msgid ""
7373 "The memory described by I<local_iov> is outside the caller's accessible "
7374 "address space."
7375 msgstr ""
7376
7377 #. type: Plain text
7378 #: build/C/man2/process_vm_readv.2:262
7379 msgid ""
7380 "The memory described by I<remote_iov> is outside the accessible address "
7381 "space of the process I<pid>."
7382 msgstr ""
7383
7384 #. type: Plain text
7385 #: build/C/man2/process_vm_readv.2:267
7386 msgid "Could not allocate memory for internal copies of the I<iovec> structures."
7387 msgstr ""
7388
7389 #. type: Plain text
7390 #: build/C/man2/process_vm_readv.2:271
7391 msgid ""
7392 "The caller does not have permission to access the address space of the "
7393 "process I<pid>."
7394 msgstr ""
7395
7396 #. type: Plain text
7397 #: build/C/man2/process_vm_readv.2:276
7398 msgid "No process with ID I<pid> exists."
7399 msgstr ""
7400
7401 #. type: Plain text
7402 #: build/C/man2/process_vm_readv.2:279
7403 msgid ""
7404 "These system calls were added in Linux 3.2.  Support is provided in glibc "
7405 "since version 2.15."
7406 msgstr ""
7407
7408 #. type: Plain text
7409 #: build/C/man2/process_vm_readv.2:281
7410 msgid "These system calls are nonstandard Linux extensions."
7411 msgstr ""
7412
7413 #. type: Plain text
7414 #: build/C/man2/process_vm_readv.2:287
7415 msgid ""
7416 "The data transfers performed by B<process_vm_readv>()  and "
7417 "B<process_vm_writev>()  are not guaranteed to be atomic in any way."
7418 msgstr ""
7419
7420 #.  Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
7421 #.  See also some benchmarks at http://lwn.net/Articles/405284/
7422 #.  and http://marc.info/?l=linux-mm&m=130105930902915&w=2
7423 #. type: Plain text
7424 #: build/C/man2/process_vm_readv.2:295
7425 msgid ""
7426 "These system calls were designed to permit fast message passing by allowing "
7427 "messages to be exchanged with a single copy operation (rather than the "
7428 "double copy that would be required when using, for example, shared memory or "
7429 "pipes)."
7430 msgstr ""
7431
7432 #. type: Plain text
7433 #: build/C/man2/process_vm_readv.2:303
7434 msgid ""
7435 "The following code sample demonstrates the use of B<process_vm_readv>().  It "
7436 "reads 20 bytes at the address 0x10000 from the process with PID 10 and "
7437 "writes the first 10 bytes into I<buf1> and the second 10 bytes into I<buf2>."
7438 msgstr ""
7439
7440 #. type: Plain text
7441 #: build/C/man2/process_vm_readv.2:306
7442 #, no-wrap
7443 msgid "#include E<lt>sys/uio.hE<gt>\n"
7444 msgstr ""
7445
7446 #. type: Plain text
7447 #: build/C/man2/process_vm_readv.2:316
7448 #, no-wrap
7449 msgid ""
7450 "int\n"
7451 "main(void)\n"
7452 "{\n"
7453 "    struct iovec local[2];\n"
7454 "    struct iovec remote[1];\n"
7455 "    char buf1[10];\n"
7456 "    char buf2[10];\n"
7457 "    ssize_t nread;\n"
7458 "    pid_t pid = 10;             /* PID of remote process */\n"
7459 msgstr ""
7460
7461 #. type: Plain text
7462 #: build/C/man2/process_vm_readv.2:323
7463 #, no-wrap
7464 msgid ""
7465 "    local[0].iov_base = buf1;\n"
7466 "    local[0].iov_len = 10;\n"
7467 "    local[1].iov_base = buf2;\n"
7468 "    local[1].iov_len = 10;\n"
7469 "    remote[0].iov_base = (void *) 0x10000;\n"
7470 "    remote[1].iov_len = 20;\n"
7471 msgstr ""
7472
7473 #. type: Plain text
7474 #: build/C/man2/process_vm_readv.2:330
7475 #, no-wrap
7476 msgid ""
7477 "    nread = process_vm_readv(pid, local, 2, remote, 1, 0);\n"
7478 "    if (nread != 20)\n"
7479 "        return 1;\n"
7480 "    else\n"
7481 "        return 0;\n"
7482 "}\n"
7483 msgstr ""
7484
7485 #. type: Plain text
7486 #: build/C/man2/process_vm_readv.2:334
7487 msgid "B<readv>(2), B<writev>(2)"
7488 msgstr ""
7489
7490 #. type: TH
7491 #: build/C/man2/ptrace.2:44
7492 #, no-wrap
7493 msgid "PTRACE"
7494 msgstr ""
7495
7496 #. type: TH
7497 #: build/C/man2/ptrace.2:44
7498 #, no-wrap
7499 msgid "2014-02-20"
7500 msgstr ""
7501
7502 #. type: Plain text
7503 #: build/C/man2/ptrace.2:47
7504 msgid "ptrace - process trace"
7505 msgstr ""
7506
7507 #. type: Plain text
7508 #: build/C/man2/ptrace.2:50
7509 #, no-wrap
7510 msgid "B<#include E<lt>sys/ptrace.hE<gt>>\n"
7511 msgstr ""
7512
7513 #. type: Plain text
7514 #: build/C/man2/ptrace.2:53
7515 #, no-wrap
7516 msgid ""
7517 "B<long ptrace(enum __ptrace_request >I<request>B<, pid_t >I<pid>B<, >\n"
7518 "B<            void *>I<addr>B<, void *>I<data>B<);>\n"
7519 msgstr ""
7520
7521 #. type: Plain text
7522 #: build/C/man2/ptrace.2:62
7523 msgid ""
7524 "The B<ptrace>()  system call provides a means by which one process (the "
7525 "\"tracer\")  may observe and control the execution of another process (the "
7526 "\"tracee\"), and examine and change the tracee's memory and registers.  It "
7527 "is primarily used to implement breakpoint debugging and system call tracing."
7528 msgstr ""
7529
7530 #. type: Plain text
7531 #: build/C/man2/ptrace.2:73
7532 msgid ""
7533 "A tracee first needs to be attached to the tracer.  Attachment and "
7534 "subsequent commands are per thread: in a multithreaded process, every thread "
7535 "can be individually attached to a (potentially different) tracer, or left "
7536 "not attached and thus not debugged.  Therefore, \"tracee\" always means "
7537 "\"(one) thread\", never \"a (possibly multithreaded) process\".  Ptrace "
7538 "commands are always sent to a specific tracee using a call of the form"
7539 msgstr ""
7540
7541 #. type: Plain text
7542 #: build/C/man2/ptrace.2:75
7543 #, no-wrap
7544 msgid "    ptrace(PTRACE_foo, pid, ...)\n"
7545 msgstr ""
7546
7547 #. type: Plain text
7548 #: build/C/man2/ptrace.2:79
7549 msgid "where I<pid> is the thread ID of the corresponding Linux thread."
7550 msgstr ""
7551
7552 #. type: Plain text
7553 #: build/C/man2/ptrace.2:85
7554 msgid ""
7555 "(Note that in this page, a \"multithreaded process\" means a thread group "
7556 "consisting of threads created using the B<clone>(2)  B<CLONE_THREAD> flag.)"
7557 msgstr ""
7558
7559 #. type: Plain text
7560 #: build/C/man2/ptrace.2:96
7561 msgid ""
7562 "A process can initiate a trace by calling B<fork>(2)  and having the "
7563 "resulting child do a B<PTRACE_TRACEME>, followed (typically) by an "
7564 "B<execve>(2).  Alternatively, one process may commence tracing another "
7565 "process using B<PTRACE_ATTACH> or B<PTRACE_SEIZE>."
7566 msgstr ""
7567
7568 #. type: Plain text
7569 #: build/C/man2/ptrace.2:113
7570 msgid ""
7571 "While being traced, the tracee will stop each time a signal is delivered, "
7572 "even if the signal is being ignored.  (An exception is B<SIGKILL>, which has "
7573 "its usual effect.)  The tracer will be notified at its next call to "
7574 "B<waitpid>(2)  (or one of the related \"wait\" system calls); that call will "
7575 "return a I<status> value containing information that indicates the cause of "
7576 "the stop in the tracee.  While the tracee is stopped, the tracer can use "
7577 "various ptrace requests to inspect and modify the tracee.  The tracer then "
7578 "causes the tracee to continue, optionally ignoring the delivered signal (or "
7579 "even delivering a different signal instead)."
7580 msgstr ""
7581
7582 #. type: Plain text
7583 #: build/C/man2/ptrace.2:123
7584 msgid ""
7585 "If the B<PTRACE_O_TRACEEXEC> option is not in effect, all successful calls "
7586 "to B<execve>(2)  by the traced process will cause it to be sent a B<SIGTRAP> "
7587 "signal, giving the parent a chance to gain control before the new program "
7588 "begins execution."
7589 msgstr ""
7590
7591 #. type: Plain text
7592 #: build/C/man2/ptrace.2:127
7593 msgid ""
7594 "When the tracer is finished tracing, it can cause the tracee to continue "
7595 "executing in a normal, untraced mode via B<PTRACE_DETACH>."
7596 msgstr ""
7597
7598 #. type: Plain text
7599 #: build/C/man2/ptrace.2:131
7600 msgid "The value of I<request> determines the action to be performed:"
7601 msgstr ""
7602
7603 #. type: TP
7604 #: build/C/man2/ptrace.2:131
7605 #, no-wrap
7606 msgid "B<PTRACE_TRACEME>"
7607 msgstr ""
7608
7609 #. type: Plain text
7610 #: build/C/man2/ptrace.2:141
7611 msgid ""
7612 "Indicate that this process is to be traced by its parent.  A process "
7613 "probably shouldn't make this request if its parent isn't expecting to trace "
7614 "it.  (I<pid>, I<addr>, and I<data> are ignored.)"
7615 msgstr ""
7616
7617 #. type: Plain text
7618 #: build/C/man2/ptrace.2:156
7619 msgid ""
7620 "The B<PTRACE_TRACEME> request is used only by the tracee; the remaining "
7621 "requests are used only by the tracer.  In the following requests, I<pid> "
7622 "specifies the thread ID of the tracee to be acted on.  For requests other "
7623 "than B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, B<PTRACE_INTERRUPT>, and "
7624 "B<PTRACE_KILL>, the tracee must be stopped."
7625 msgstr ""
7626
7627 #. type: TP
7628 #: build/C/man2/ptrace.2:156
7629 #, no-wrap
7630 msgid "B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>"
7631 msgstr ""
7632
7633 #. type: Plain text
7634 #: build/C/man2/ptrace.2:167
7635 msgid ""
7636 "Read a word at the address I<addr> in the tracee's memory, returning the "
7637 "word as the result of the B<ptrace>()  call.  Linux does not have separate "
7638 "text and data address spaces, so these two requests are currently "
7639 "equivalent.  (I<data> is ignored; but see NOTES.)"
7640 msgstr ""
7641
7642 #. type: TP
7643 #: build/C/man2/ptrace.2:167
7644 #, no-wrap
7645 msgid "B<PTRACE_PEEKUSER>"
7646 msgstr ""
7647
7648 #.  PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
7649 #.  and that is the name that seems common on other systems.
7650 #. type: Plain text
7651 #: build/C/man2/ptrace.2:185
7652 msgid ""
7653 "Read a word at offset I<addr> in the tracee's USER area, which holds the "
7654 "registers and other information about the process (see "
7655 "I<E<lt>sys/user.hE<gt>>).  The word is returned as the result of the "
7656 "B<ptrace>()  call.  Typically, the offset must be word-aligned, though this "
7657 "might vary by architecture.  See NOTES.  (I<data> is ignored; but see "
7658 "NOTES.)"
7659 msgstr ""
7660
7661 #. type: TP
7662 #: build/C/man2/ptrace.2:185
7663 #, no-wrap
7664 msgid "B<PTRACE_POKETEXT>, B<PTRACE_POKEDATA>"
7665 msgstr ""
7666
7667 #. type: Plain text
7668 #: build/C/man2/ptrace.2:197
7669 msgid ""
7670 "Copy the word I<data> to the address I<addr> in the tracee's memory.  As for "
7671 "B<PTRACE_PEEKTEXT> and B<PTRACE_PEEKDATA>, these two requests are currently "
7672 "equivalent."
7673 msgstr ""
7674
7675 #. type: TP
7676 #: build/C/man2/ptrace.2:197
7677 #, no-wrap
7678 msgid "B<PTRACE_POKEUSER>"
7679 msgstr ""
7680
7681 #.  PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
7682 #.  and that is the name that seems common on other systems.
7683 #.  FIXME In the preceding sentence, which modifications are disallowed,
7684 #.  and when they are disallowed, how does user space discover that fact?
7685 #. type: Plain text
7686 #: build/C/man2/ptrace.2:213
7687 msgid ""
7688 "Copy the word I<data> to offset I<addr> in the tracee's USER area.  As for "
7689 "B<PTRACE_PEEKUSER>, the offset must typically be word-aligned.  In order to "
7690 "maintain the integrity of the kernel, some modifications to the USER area "
7691 "are disallowed."
7692 msgstr ""
7693
7694 #. type: TP
7695 #: build/C/man2/ptrace.2:213
7696 #, no-wrap
7697 msgid "B<PTRACE_GETREGS>, B<PTRACE_GETFPREGS>"
7698 msgstr ""
7699
7700 #. type: Plain text
7701 #: build/C/man2/ptrace.2:236
7702 msgid ""
7703 "Copy the tracee's general-purpose or floating-point registers, respectively, "
7704 "to the address I<data> in the tracer.  See I<E<lt>sys/user.hE<gt>> for "
7705 "information on the format of this data.  (I<addr> is ignored.)  Note that "
7706 "SPARC systems have the meaning of I<data> and I<addr> reversed; that is, "
7707 "I<data> is ignored and the registers are copied to the address I<addr>.  "
7708 "B<PTRACE_GETREGS> and B<PTRACE_GETFPREGS> are not present on all "
7709 "architectures."
7710 msgstr ""
7711
7712 #. type: TP
7713 #: build/C/man2/ptrace.2:236
7714 #, no-wrap
7715 msgid "B<PTRACE_GETREGSET> (since Linux 2.6.34)"
7716 msgstr ""
7717
7718 #. type: Plain text
7719 #: build/C/man2/ptrace.2:257
7720 msgid ""
7721 "Read the tracee's registers.  I<addr> specifies, in an "
7722 "architecture-dependent way, the type of registers to be read.  "
7723 "B<NT_PRSTATUS> (with numerical value 1)  usually results in reading of "
7724 "general-purpose registers.  If the CPU has, for example, floating-point "
7725 "and/or vector registers, they can be retrieved by setting I<addr> to the "
7726 "corresponding B<NT_foo> constant.  I<data> points to a B<struct iovec>, "
7727 "which describes the destination buffer's location and length.  On return, "
7728 "the kernel modifies B<iov.len> to indicate the actual number of bytes "
7729 "returned."
7730 msgstr ""
7731
7732 #. type: TP
7733 #: build/C/man2/ptrace.2:257
7734 #, no-wrap
7735 msgid "B<PTRACE_SETREGS>, B<PTRACE_SETFPREGS>"
7736 msgstr ""
7737
7738 #.  FIXME In the preceding sentence, which modifications are disallowed,
7739 #.  and when they are disallowed, how does user space discover that fact?
7740 #. type: Plain text
7741 #: build/C/man2/ptrace.2:282
7742 msgid ""
7743 "Modify the tracee's general-purpose or floating-point registers, "
7744 "respectively, from the address I<data> in the tracer.  As for "
7745 "B<PTRACE_POKEUSER>, some general-purpose register modifications may be "
7746 "disallowed.  (I<addr> is ignored.)  Note that SPARC systems have the meaning "
7747 "of I<data> and I<addr> reversed; that is, I<data> is ignored and the "
7748 "registers are copied from the address I<addr>.  B<PTRACE_SETREGS> and "
7749 "B<PTRACE_SETFPREGS> are not present on all architectures."
7750 msgstr ""
7751
7752 #. type: TP
7753 #: build/C/man2/ptrace.2:282
7754 #, no-wrap
7755 msgid "B<PTRACE_SETREGSET> (since Linux 2.6.34)"
7756 msgstr ""
7757
7758 #. type: Plain text
7759 #: build/C/man2/ptrace.2:291
7760 msgid ""
7761 "Modify the tracee's registers.  The meaning of I<addr> and I<data> is "
7762 "analogous to B<PTRACE_GETREGSET>."
7763 msgstr ""
7764
7765 #. type: TP
7766 #: build/C/man2/ptrace.2:291
7767 #, no-wrap
7768 msgid "B<PTRACE_GETSIGINFO> (since Linux 2.3.99-pre6)"
7769 msgstr ""
7770
7771 #. type: Plain text
7772 #: build/C/man2/ptrace.2:303
7773 msgid ""
7774 "Retrieve information about the signal that caused the stop.  Copy a "
7775 "I<siginfo_t> structure (see B<sigaction>(2))  from the tracee to the address "
7776 "I<data> in the tracer.  (I<addr> is ignored.)"
7777 msgstr ""
7778
7779 #. type: TP
7780 #: build/C/man2/ptrace.2:303
7781 #, no-wrap
7782 msgid "B<PTRACE_SETSIGINFO> (since Linux 2.3.99-pre6)"
7783 msgstr ""
7784
7785 #. type: Plain text
7786 #: build/C/man2/ptrace.2:319
7787 msgid ""
7788 "Set signal information: copy a I<siginfo_t> structure from the address "
7789 "I<data> in the tracer to the tracee.  This will affect only signals that "
7790 "would normally be delivered to the tracee and were caught by the tracer.  It "
7791 "may be difficult to tell these normal signals from synthetic signals "
7792 "generated by B<ptrace>()  itself.  (I<addr> is ignored.)"
7793 msgstr ""
7794
7795 #. type: TP
7796 #: build/C/man2/ptrace.2:319
7797 #, no-wrap
7798 msgid "B<PTRACE_PEEKSIGINFO> (since Linux 3.10)"
7799 msgstr ""
7800
7801 #.  commit 84c751bd4aebbaae995fe32279d3dba48327bad4
7802 #. type: Plain text
7803 #: build/C/man2/ptrace.2:345
7804 msgid ""
7805 "Retrieve I<siginfo_t> structures without removing signals from a queue.  "
7806 "I<addr> points to a I<ptrace_peeksiginfo_args> structure that specifies the "
7807 "ordinal position from which copying of signals should start, and the number "
7808 "of signals to copy.  I<siginfo_t> structures are copied into the buffer "
7809 "pointed to by I<data>.  The return value contains the number of copied "
7810 "signals (zero indicates that there is no signal corresponding to the "
7811 "specified ordinal position).  Within the returned I<siginfo> structures, the "
7812 "I<si_code> field includes information (B<__SI_CHLD>, B<__SI_FAULT>, etc.) "
7813 "that are not otherwise exposed to user space."
7814 msgstr ""
7815
7816 #. type: Plain text
7817 #: build/C/man2/ptrace.2:354
7818 #, no-wrap
7819 msgid ""
7820 "struct ptrace_peeksiginfo_args {\n"
7821 "    u64 off;    /* Ordinal position in queue at which\n"
7822 "                   to start copying signals */\n"
7823 "    u32 flags;  /* PTRACE_PEEKSIGINFO_SHARED or 0 */\n"
7824 "    s32 nr;     /* Number of signals to copy */\n"
7825 "};\n"
7826 msgstr ""
7827
7828 #. type: Plain text
7829 #: build/C/man2/ptrace.2:361
7830 msgid ""
7831 "Currently, there is only one flag, B<PTRACE_PEEKSIGINFO_SHARED>, for dumping "
7832 "signals from the process-wide signal queue.  If this flag is not set, "
7833 "signals are read from the per-thread queue of the specified thread."
7834 msgstr ""
7835
7836 #. type: TP
7837 #: build/C/man2/ptrace.2:363
7838 #, no-wrap
7839 msgid "B<PTRACE_GETSIGMASK> (since Linux 3.11)"
7840 msgstr ""
7841
7842 #.  commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
7843 #. type: Plain text
7844 #: build/C/man2/ptrace.2:378
7845 msgid ""
7846 "Place a copy of the mask of blocked signals (see B<sigprocmask>(2))  in the "
7847 "buffer pointed to by I<data>, which should be a pointer to a buffer of type "
7848 "I<sigset_t>.  The I<addr> argument contains the size of the buffer pointed "
7849 "to by I<data> (i.e., I<sizeof(sigset_t)>)."
7850 msgstr ""
7851
7852 #. type: TP
7853 #: build/C/man2/ptrace.2:378
7854 #, no-wrap
7855 msgid "B<PTRACE_SETSIGMASK> (since Linux 3.11)"
7856 msgstr ""
7857
7858 #. type: Plain text
7859 #: build/C/man2/ptrace.2:392
7860 msgid ""
7861 "Change the mask of blocked signals (see B<sigprocmask>(2))  to the value "
7862 "specified in the buffer pointed to by I<data>, which should be a pointer to "
7863 "a buffer of type I<sigset_t>.  The I<addr> argument contains the size of the "
7864 "buffer pointed to by I<data> (i.e., I<sizeof(sigset_t)>)."
7865 msgstr ""
7866
7867 #. type: TP
7868 #: build/C/man2/ptrace.2:392
7869 #, no-wrap
7870 msgid "B<PTRACE_SETOPTIONS> (since Linux 2.4.6; see BUGS for caveats)"
7871 msgstr ""
7872
7873 #. type: Plain text
7874 #: build/C/man2/ptrace.2:401
7875 msgid ""
7876 "Set ptrace options from I<data>.  (I<addr> is ignored.)  I<data> is "
7877 "interpreted as a bit mask of options, which are specified by the following "
7878 "flags:"
7879 msgstr ""
7880
7881 #. type: TP
7882 #: build/C/man2/ptrace.2:402
7883 #, no-wrap
7884 msgid "B<PTRACE_O_EXITKILL> (since Linux 3.8)"
7885 msgstr ""
7886
7887 #.  commit 992fb6e170639b0849bace8e49bf31bd37c4123
7888 #. type: Plain text
7889 #: build/C/man2/ptrace.2:410
7890 msgid ""
7891 "If a tracer sets this flag, a B<SIGKILL> signal will be sent to every tracee "
7892 "if the tracer exits.  This option is useful for ptrace jailers that want to "
7893 "ensure that tracees can never escape the tracer's control."
7894 msgstr ""
7895
7896 #. type: TP
7897 #: build/C/man2/ptrace.2:410
7898 #, no-wrap
7899 msgid "B<PTRACE_O_TRACECLONE> (since Linux 2.5.46)"
7900 msgstr ""
7901
7902 #. type: Plain text
7903 #: build/C/man2/ptrace.2:427
7904 msgid ""
7905 "Stop the tracee at the next B<clone>(2)  and automatically start tracing the "
7906 "newly cloned process, which will start with a B<SIGSTOP>, or "
7907 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
7908 "tracer will return a I<status> value such that"
7909 msgstr ""
7910
7911 #. type: Plain text
7912 #: build/C/man2/ptrace.2:430
7913 #, no-wrap
7914 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_CLONEE<lt>E<lt>8))\n"
7915 msgstr ""
7916
7917 #. type: Plain text
7918 #: build/C/man2/ptrace.2:434 build/C/man2/ptrace.2:520 build/C/man2/ptrace.2:553
7919 msgid "The PID of the new process can be retrieved with B<PTRACE_GETEVENTMSG>."
7920 msgstr ""
7921
7922 #. type: Plain text
7923 #: build/C/man2/ptrace.2:455
7924 msgid ""
7925 "This option may not catch B<clone>(2)  calls in all cases.  If the tracee "
7926 "calls B<clone>(2)  with the B<CLONE_VFORK> flag, B<PTRACE_EVENT_VFORK> will "
7927 "be delivered instead if B<PTRACE_O_TRACEVFORK> is set; otherwise if the "
7928 "tracee calls B<clone>(2)  with the exit signal set to B<SIGCHLD>, "
7929 "B<PTRACE_EVENT_FORK> will be delivered if B<PTRACE_O_TRACEFORK> is set."
7930 msgstr ""
7931
7932 #. type: TP
7933 #: build/C/man2/ptrace.2:455
7934 #, no-wrap
7935 msgid "B<PTRACE_O_TRACEEXEC> (since Linux 2.5.46)"
7936 msgstr ""
7937
7938 #. type: Plain text
7939 #: build/C/man2/ptrace.2:464
7940 msgid ""
7941 "Stop the tracee at the next B<execve>(2).  A B<waitpid>(2)  by the tracer "
7942 "will return a I<status> value such that"
7943 msgstr ""
7944
7945 #. type: Plain text
7946 #: build/C/man2/ptrace.2:467
7947 #, no-wrap
7948 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXECE<lt>E<lt>8))\n"
7949 msgstr ""
7950
7951 #. type: Plain text
7952 #: build/C/man2/ptrace.2:473
7953 msgid ""
7954 "If the execing thread is not a thread group leader, the thread ID is reset "
7955 "to thread group leader's ID before this stop.  Since Linux 3.0, the former "
7956 "thread ID can be retrieved with B<PTRACE_GETEVENTMSG>."
7957 msgstr ""
7958
7959 #. type: TP
7960 #: build/C/man2/ptrace.2:473
7961 #, no-wrap
7962 msgid "B<PTRACE_O_TRACEEXIT> (since Linux 2.5.60)"
7963 msgstr ""
7964
7965 #. type: Plain text
7966 #: build/C/man2/ptrace.2:481
7967 msgid ""
7968 "Stop the tracee at exit.  A B<waitpid>(2)  by the tracer will return a "
7969 "I<status> value such that"
7970 msgstr ""
7971
7972 #. type: Plain text
7973 #: build/C/man2/ptrace.2:484
7974 #, no-wrap
7975 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXITE<lt>E<lt>8))\n"
7976 msgstr ""
7977
7978 #. type: Plain text
7979 #: build/C/man2/ptrace.2:488
7980 msgid "The tracee's exit status can be retrieved with B<PTRACE_GETEVENTMSG>."
7981 msgstr ""
7982
7983 #. type: Plain text
7984 #: build/C/man2/ptrace.2:496
7985 msgid ""
7986 "The tracee is stopped early during process exit, when registers are still "
7987 "available, allowing the tracer to see where the exit occurred, whereas the "
7988 "normal exit notification is done after the process is finished exiting.  "
7989 "Even though context is available, the tracer cannot prevent the exit from "
7990 "happening at this point."
7991 msgstr ""
7992
7993 #. type: TP
7994 #: build/C/man2/ptrace.2:496
7995 #, no-wrap
7996 msgid "B<PTRACE_O_TRACEFORK> (since Linux 2.5.46)"
7997 msgstr ""
7998
7999 #. type: Plain text
8000 #: build/C/man2/ptrace.2:513
8001 msgid ""
8002 "Stop the tracee at the next B<fork>(2)  and automatically start tracing the "
8003 "newly forked process, which will start with a B<SIGSTOP>, or "
8004 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
8005 "tracer will return a I<status> value such that"
8006 msgstr ""
8007
8008 #. type: Plain text
8009 #: build/C/man2/ptrace.2:516
8010 #, no-wrap
8011 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_FORKE<lt>E<lt>8))\n"
8012 msgstr ""
8013
8014 #. type: TP
8015 #: build/C/man2/ptrace.2:520
8016 #, no-wrap
8017 msgid "B<PTRACE_O_TRACESYSGOOD> (since Linux 2.4.6)"
8018 msgstr ""
8019
8020 #. type: Plain text
8021 #: build/C/man2/ptrace.2:529
8022 msgid ""
8023 "When delivering system call traps, set bit 7 in the signal number (i.e., "
8024 "deliver I<SIGTRAP|0x80>).  This makes it easy for the tracer to distinguish "
8025 "normal traps from those caused by a system call.  (B<PTRACE_O_TRACESYSGOOD> "
8026 "may not work on all architectures.)"
8027 msgstr ""
8028
8029 #. type: TP
8030 #: build/C/man2/ptrace.2:529
8031 #, no-wrap
8032 msgid "B<PTRACE_O_TRACEVFORK> (since Linux 2.5.46)"
8033 msgstr ""
8034
8035 #. type: Plain text
8036 #: build/C/man2/ptrace.2:546
8037 msgid ""
8038 "Stop the tracee at the next B<vfork>(2)  and automatically start tracing the "
8039 "newly vforked process, which will start with a B<SIGSTOP>, or "
8040 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
8041 "tracer will return a I<status> value such that"
8042 msgstr ""
8043
8044 #. type: Plain text
8045 #: build/C/man2/ptrace.2:549
8046 #, no-wrap
8047 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORKE<lt>E<lt>8))\n"
8048 msgstr ""
8049
8050 #. type: TP
8051 #: build/C/man2/ptrace.2:553
8052 #, no-wrap
8053 msgid "B<PTRACE_O_TRACEVFORKDONE> (since Linux 2.5.60)"
8054 msgstr ""
8055
8056 #. type: Plain text
8057 #: build/C/man2/ptrace.2:562
8058 msgid ""
8059 "Stop the tracee at the completion of the next B<vfork>(2).  A B<waitpid>(2)  "
8060 "by the tracer will return a I<status> value such that"
8061 msgstr ""
8062
8063 #. type: Plain text
8064 #: build/C/man2/ptrace.2:565
8065 #, no-wrap
8066 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONEE<lt>E<lt>8))\n"
8067 msgstr ""
8068
8069 #. type: Plain text
8070 #: build/C/man2/ptrace.2:569
8071 msgid ""
8072 "The PID of the new process can (since Linux 2.6.18) be retrieved with "
8073 "B<PTRACE_GETEVENTMSG>."
8074 msgstr ""
8075
8076 #. type: TP
8077 #: build/C/man2/ptrace.2:570
8078 #, no-wrap
8079 msgid "B<PTRACE_GETEVENTMSG> (since Linux 2.5.46)"
8080 msgstr ""
8081
8082 #. type: Plain text
8083 #: build/C/man2/ptrace.2:590
8084 msgid ""
8085 "Retrieve a message (as an I<unsigned long>)  about the ptrace event that "
8086 "just happened, placing it at the address I<data> in the tracer.  For "
8087 "B<PTRACE_EVENT_EXIT>, this is the tracee's exit status.  For "
8088 "B<PTRACE_EVENT_FORK>, B<PTRACE_EVENT_VFORK>, B<PTRACE_EVENT_VFORK_DONE>, and "
8089 "B<PTRACE_EVENT_CLONE>, this is the PID of the new process.  (I<addr> is "
8090 "ignored.)"
8091 msgstr ""
8092
8093 #. type: TP
8094 #: build/C/man2/ptrace.2:590
8095 #, no-wrap
8096 msgid "B<PTRACE_CONT>"
8097 msgstr ""
8098
8099 #. type: Plain text
8100 #: build/C/man2/ptrace.2:602
8101 msgid ""
8102 "Restart the stopped tracee process.  If I<data> is nonzero, it is "
8103 "interpreted as the number of a signal to be delivered to the tracee; "
8104 "otherwise, no signal is delivered.  Thus, for example, the tracer can "
8105 "control whether a signal sent to the tracee is delivered or not.  (I<addr> "
8106 "is ignored.)"
8107 msgstr ""
8108
8109 #. type: TP
8110 #: build/C/man2/ptrace.2:602
8111 #, no-wrap
8112 msgid "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>"
8113 msgstr ""
8114
8115 #. type: Plain text
8116 #: build/C/man2/ptrace.2:626
8117 msgid ""
8118 "Restart the stopped tracee as for B<PTRACE_CONT>, but arrange for the tracee "
8119 "to be stopped at the next entry to or exit from a system call, or after "
8120 "execution of a single instruction, respectively.  (The tracee will also, as "
8121 "usual, be stopped upon receipt of a signal.)  From the tracer's perspective, "
8122 "the tracee will appear to have been stopped by receipt of a B<SIGTRAP>.  So, "
8123 "for B<PTRACE_SYSCALL>, for example, the idea is to inspect the arguments to "
8124 "the system call at the first stop, then do another B<PTRACE_SYSCALL> and "
8125 "inspect the return value of the system call at the second stop.  The I<data> "
8126 "argument is treated as for B<PTRACE_CONT>.  (I<addr> is ignored.)"
8127 msgstr ""
8128
8129 #. type: TP
8130 #: build/C/man2/ptrace.2:626
8131 #, no-wrap
8132 msgid "B<PTRACE_SYSEMU>, B<PTRACE_SYSEMU_SINGLESTEP> (since Linux 2.6.14)"
8133 msgstr ""
8134
8135 #.  As at 3.7
8136 #. type: Plain text
8137 #: build/C/man2/ptrace.2:647
8138 msgid ""
8139 "For B<PTRACE_SYSEMU>, continue and stop on entry to the next system call, "
8140 "which will not be executed.  For B<PTRACE_SYSEMU_SINGLESTEP>, do the same "
8141 "but also singlestep if not a system call.  This call is used by programs "
8142 "like User Mode Linux that want to emulate all the tracee's system calls.  "
8143 "The I<data> argument is treated as for B<PTRACE_CONT>.  The I<addr> argument "
8144 "is ignored.  These requests are currently supported only on x86."
8145 msgstr ""
8146
8147 #. type: TP
8148 #: build/C/man2/ptrace.2:647
8149 #, no-wrap
8150 msgid "B<PTRACE_LISTEN> (since Linux 3.4)"
8151 msgstr ""
8152
8153 #. type: Plain text
8154 #: build/C/man2/ptrace.2:658
8155 msgid ""
8156 "Restart the stopped tracee, but prevent it from executing.  The resulting "
8157 "state of the tracee is similar to a process which has been stopped by a "
8158 "B<SIGSTOP> (or other stopping signal).  See the \"group-stop\" subsection "
8159 "for additional information.  B<PTRACE_LISTEN> works only on tracees attached "
8160 "by B<PTRACE_SEIZE>."
8161 msgstr ""
8162
8163 #. type: TP
8164 #: build/C/man2/ptrace.2:658
8165 #, no-wrap
8166 msgid "B<PTRACE_KILL>"
8167 msgstr ""
8168
8169 #. type: Plain text
8170 #: build/C/man2/ptrace.2:667
8171 msgid ""
8172 "Send the tracee a B<SIGKILL> to terminate it.  (I<addr> and I<data> are "
8173 "ignored.)"
8174 msgstr ""
8175
8176 #.  [Note from Denys Vlasenko:
8177 #.      deprecation suggested by Oleg Nesterov. He prefers to deprecate it
8178 #.      instead of describing (and needing to support) PTRACE_KILL's quirks.]
8179 #. type: Plain text
8180 #: build/C/man2/ptrace.2:686
8181 msgid ""
8182 "I<This operation is deprecated; do not use it!> Instead, send a B<SIGKILL> "
8183 "directly using B<kill>(2)  or B<tgkill>(2).  The problem with B<PTRACE_KILL> "
8184 "is that it requires the tracee to be in signal-delivery-stop, otherwise it "
8185 "may not work (i.e., may complete successfully but won't kill the tracee).  "
8186 "By contrast, sending a B<SIGKILL> directly has no such limitation."
8187 msgstr ""
8188
8189 #. type: TP
8190 #: build/C/man2/ptrace.2:686
8191 #, no-wrap
8192 msgid "B<PTRACE_INTERRUPT> (since Linux 3.4)"
8193 msgstr ""
8194
8195 #. type: Plain text
8196 #: build/C/man2/ptrace.2:714
8197 msgid ""
8198 "Stop a tracee.  If the tracee is running or sleeping in kernel space and "
8199 "B<PTRACE_SYSCALL> is in effect, the system call is interrupted and "
8200 "syscall-exit-stop is reported.  (The interrupted system call is restarted "
8201 "when the tracee is restarted.)  If the tracee was already stopped by a "
8202 "signal and B<PTRACE_LISTEN> was sent to it, the tracee stops with "
8203 "B<PTRACE_EVENT_STOP> and I<WSTOPSIG(status)> returns the stop signal.  If "
8204 "any other ptrace-stop is generated at the same time (for example, if a "
8205 "signal is sent to the tracee), this ptrace-stop happens.  If none of the "
8206 "above applies (for example, if the tracee is running in user space), it "
8207 "stops with B<PTRACE_EVENT_STOP> with I<WSTOPSIG(status)> == B<SIGTRAP>.  "
8208 "B<PTRACE_INTERRUPT> only works on tracees attached by B<PTRACE_SEIZE>."
8209 msgstr ""
8210
8211 #. type: TP
8212 #: build/C/man2/ptrace.2:714
8213 #, no-wrap
8214 msgid "B<PTRACE_ATTACH>"
8215 msgstr ""
8216
8217 #.  No longer true (removed by Denys Vlasenko, 2011, who remarks:
8218 #.         "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
8219 #.          Basically, it's not true for any Linux in practical use.
8220 #.  ; the behavior of the tracee is as if it had done a
8221 #.  .BR PTRACE_TRACEME .
8222 #.  The calling process actually becomes the parent of the tracee
8223 #.  process for most purposes (e.g., it will receive
8224 #.  notification of tracee events and appears in
8225 #.  .BR ps (1)
8226 #.  output as the tracee's parent), but a
8227 #.  .BR getppid (2)
8228 #.  by the tracee will still return the PID of the original parent.
8229 #. type: Plain text
8230 #: build/C/man2/ptrace.2:742
8231 msgid ""
8232 "Attach to the process specified in I<pid>, making it a tracee of the calling "
8233 "process.  The tracee is sent a B<SIGSTOP>, but will not necessarily have "
8234 "stopped by the completion of this call; use B<waitpid>(2)  to wait for the "
8235 "tracee to stop.  See the \"Attaching and detaching\" subsection for "
8236 "additional information.  (I<addr> and I<data> are ignored.)"
8237 msgstr ""
8238
8239 #. type: TP
8240 #: build/C/man2/ptrace.2:742
8241 #, no-wrap
8242 msgid "B<PTRACE_SEIZE> (since Linux 3.4)"
8243 msgstr ""
8244
8245 #. type: Plain text
8246 #: build/C/man2/ptrace.2:762
8247 msgid ""
8248 "Attach to the process specified in I<pid>, making it a tracee of the calling "
8249 "process.  Unlike B<PTRACE_ATTACH>, B<PTRACE_SEIZE> does not stop the "
8250 "process.  Only a B<PTRACE_SEIZE>d process can accept B<PTRACE_INTERRUPT> and "
8251 "B<PTRACE_LISTEN> commands.  I<addr> must be zero.  I<data> contains a bit "
8252 "mask of ptrace options to activate immediately."
8253 msgstr ""
8254
8255 #. type: TP
8256 #: build/C/man2/ptrace.2:762
8257 #, no-wrap
8258 msgid "B<PTRACE_DETACH>"
8259 msgstr ""
8260
8261 #. type: Plain text
8262 #: build/C/man2/ptrace.2:771
8263 msgid ""
8264 "Restart the stopped tracee as for B<PTRACE_CONT>, but first detach from it.  "
8265 "Under Linux, a tracee can be detached in this way regardless of which method "
8266 "was used to initiate tracing.  (I<addr> is ignored.)"
8267 msgstr ""
8268
8269 #. type: SS
8270 #: build/C/man2/ptrace.2:771
8271 #, no-wrap
8272 msgid "Death under ptrace"
8273 msgstr ""
8274
8275 #. type: Plain text
8276 #: build/C/man2/ptrace.2:780
8277 msgid ""
8278 "When a (possibly multithreaded) process receives a killing signal (one whose "
8279 "disposition is set to B<SIG_DFL> and whose default action is to kill the "
8280 "process), all threads exit.  Tracees report their death to their tracer(s).  "
8281 "Notification of this event is delivered via B<waitpid>(2)."
8282 msgstr ""
8283
8284 #. type: Plain text
8285 #: build/C/man2/ptrace.2:789
8286 msgid ""
8287 "Note that the killing signal will first cause signal-delivery-stop (on one "
8288 "tracee only), and only after it is injected by the tracer (or after it was "
8289 "dispatched to a thread which isn't traced), will death from the signal "
8290 "happen on I<all> tracees within a multithreaded process.  (The term "
8291 "\"signal-delivery-stop\" is explained below.)"
8292 msgstr ""
8293
8294 #. type: Plain text
8295 #: build/C/man2/ptrace.2:801
8296 msgid ""
8297 "B<SIGKILL> does not generate signal-delivery-stop and therefore the tracer "
8298 "can't suppress it.  B<SIGKILL> kills even within system calls "
8299 "(syscall-exit-stop is not generated prior to death by B<SIGKILL>).  The net "
8300 "effect is that B<SIGKILL> always kills the process (all its threads), even "
8301 "if some threads of the process are ptraced."
8302 msgstr ""
8303
8304 #. type: Plain text
8305 #: build/C/man2/ptrace.2:806
8306 msgid ""
8307 "When the tracee calls B<_exit>(2), it reports its death to its tracer.  "
8308 "Other threads are not affected."
8309 msgstr ""
8310
8311 #. type: Plain text
8312 #: build/C/man2/ptrace.2:810
8313 msgid ""
8314 "When any thread executes B<exit_group>(2), every tracee in its thread group "
8315 "reports its death to its tracer."
8316 msgstr ""
8317
8318 #. type: Plain text
8319 #: build/C/man2/ptrace.2:824
8320 msgid ""
8321 "If the B<PTRACE_O_TRACEEXIT> option is on, B<PTRACE_EVENT_EXIT> will happen "
8322 "before actual death.  This applies to exits via B<exit>(2), "
8323 "B<exit_group>(2), and signal deaths (except B<SIGKILL>), and when threads "
8324 "are torn down on B<execve>(2)  in a multithreaded process."
8325 msgstr ""
8326
8327 #. type: Plain text
8328 #: build/C/man2/ptrace.2:849
8329 msgid ""
8330 "The tracer cannot assume that the ptrace-stopped tracee exists.  There are "
8331 "many scenarios when the tracee may die while stopped (such as B<SIGKILL>).  "
8332 "Therefore, the tracer must be prepared to handle an B<ESRCH> error on any "
8333 "ptrace operation.  Unfortunately, the same error is returned if the tracee "
8334 "exists but is not ptrace-stopped (for commands which require a stopped "
8335 "tracee), or if it is not traced by the process which issued the ptrace "
8336 "call.  The tracer needs to keep track of the stopped/running state of the "
8337 "tracee, and interpret B<ESRCH> as \"tracee died unexpectedly\" only if it "
8338 "knows that the tracee has been observed to enter ptrace-stop.  Note that "
8339 "there is no guarantee that I<waitpid(WNOHANG)> will reliably report the "
8340 "tracee's death status if a ptrace operation returned B<ESRCH>.  "
8341 "I<waitpid(WNOHANG)> may return 0 instead.  In other words, the tracee may be "
8342 "\"not yet fully dead\", but already refusing ptrace requests."
8343 msgstr ""
8344
8345 #. type: Plain text
8346 #: build/C/man2/ptrace.2:863
8347 msgid ""
8348 "The tracer can't assume that the tracee I<always> ends its life by reporting "
8349 "I<WIFEXITED(status)> or I<WIFSIGNALED(status)>; there are cases where this "
8350 "does not occur.  For example, if a thread other than thread group leader "
8351 "does an B<execve>(2), it disappears; its PID will never be seen again, and "
8352 "any subsequent ptrace stops will be reported under the thread group leader's "
8353 "PID."
8354 msgstr ""
8355
8356 #. type: SS
8357 #: build/C/man2/ptrace.2:863
8358 #, no-wrap
8359 msgid "Stopped states"
8360 msgstr ""
8361
8362 #. type: Plain text
8363 #: build/C/man2/ptrace.2:885
8364 msgid ""
8365 "A tracee can be in two states: running or stopped.  For the purposes of "
8366 "ptrace, a tracee which is blocked in a system call (such as B<read>(2), "
8367 "B<pause>(2), etc.)  is nevertheless considered to be running, even if the "
8368 "tracee is blocked for a long time.  The state of the tracee after "
8369 "B<PTRACE_LISTEN> is somewhat of a gray area: it is not in any ptrace-stop "
8370 "(ptrace commands won't work on it, and it will deliver B<waitpid>(2)  "
8371 "notifications), but it also may be considered \"stopped\" because it is not "
8372 "executing instructions (is not scheduled), and if it was in group-stop "
8373 "before B<PTRACE_LISTEN>, it will not respond to signals until B<SIGCONT> is "
8374 "received."
8375 msgstr ""
8376
8377 #. type: Plain text
8378 #: build/C/man2/ptrace.2:889
8379 msgid ""
8380 "There are many kinds of states when the tracee is stopped, and in ptrace "
8381 "discussions they are often conflated.  Therefore, it is important to use "
8382 "precise terms."
8383 msgstr ""
8384
8385 #. type: Plain text
8386 #: build/C/man2/ptrace.2:900
8387 msgid ""
8388 "In this manual page, any stopped state in which the tracee is ready to "
8389 "accept ptrace commands from the tracer is called I<ptrace-stop>.  "
8390 "Ptrace-stops can be further subdivided into I<signal-delivery-stop>, "
8391 "I<group-stop>, I<syscall-stop>, and so on.  These stopped states are "
8392 "described in detail below."
8393 msgstr ""
8394
8395 #. type: Plain text
8396 #: build/C/man2/ptrace.2:905
8397 msgid ""
8398 "When the running tracee enters ptrace-stop, it notifies its tracer using "
8399 "B<waitpid>(2)  (or one of the other \"wait\" system calls).  Most of this "
8400 "manual page assumes that the tracer waits with:"
8401 msgstr ""
8402
8403 #. type: Plain text
8404 #: build/C/man2/ptrace.2:907
8405 #, no-wrap
8406 msgid "    pid = waitpid(pid_or_minus_1, &status, __WALL);\n"
8407 msgstr ""
8408
8409 #.  Denys Vlasenko:
8410 #.      Do we require __WALL usage, or will just using 0 be ok? (With 0,
8411 #.      I am not 100% sure there aren't ugly corner cases.) Are the
8412 #.      rules different if user wants to use waitid? Will waitid require
8413 #.      WEXITED?
8414 #. type: Plain text
8415 #: build/C/man2/ptrace.2:919
8416 msgid ""
8417 "Ptrace-stopped tracees are reported as returns with I<pid> greater than 0 "
8418 "and I<WIFSTOPPED(status)> true."
8419 msgstr ""
8420
8421 #. type: Plain text
8422 #: build/C/man2/ptrace.2:927
8423 msgid ""
8424 "The B<__WALL> flag does not include the B<WSTOPPED> and B<WEXITED> flags, "
8425 "but implies their functionality."
8426 msgstr ""
8427
8428 #. type: Plain text
8429 #: build/C/man2/ptrace.2:934
8430 msgid ""
8431 "Setting the B<WCONTINUED> flag when calling B<waitpid>(2)  is not "
8432 "recommended: the \"continued\" state is per-process and consuming it can "
8433 "confuse the real parent of the tracee."
8434 msgstr ""
8435
8436 #. type: Plain text
8437 #: build/C/man2/ptrace.2:942
8438 msgid ""
8439 "Use of the B<WNOHANG> flag may cause B<waitpid>(2)  to return 0 (\"no wait "
8440 "results available yet\")  even if the tracer knows there should be a "
8441 "notification.  Example:"
8442 msgstr ""
8443
8444 #. type: Plain text
8445 #: build/C/man2/ptrace.2:951
8446 #, no-wrap
8447 msgid ""
8448 "    errno = 0;\n"
8449 "    ptrace(PTRACE_CONT, pid, 0L, 0L);\n"
8450 "    if (errno == ESRCH) {\n"
8451 "        /* tracee is dead */\n"
8452 "        r = waitpid(tracee, &status, __WALL | WNOHANG);\n"
8453 "        /* r can still be 0 here! */\n"
8454 "    }\n"
8455 msgstr ""
8456
8457 #. type: Plain text
8458 #: build/C/man2/ptrace.2:974
8459 msgid ""
8460 "The following kinds of ptrace-stops exist: signal-delivery-stops, "
8461 "group-stops, B<PTRACE_EVENT> stops, syscall-stops.  They all are reported by "
8462 "B<waitpid>(2)  with I<WIFSTOPPED(status)> true.  They may be differentiated "
8463 "by examining the value I<statusE<gt>E<gt>8>, and if there is ambiguity in "
8464 "that value, by querying B<PTRACE_GETSIGINFO>.  (Note: the "
8465 "I<WSTOPSIG(status)> macro can't be used to perform this examination, because "
8466 "it returns the value I<(statusE<gt>E<gt>8)\\ &\\ 0xff>.)"
8467 msgstr ""
8468
8469 #. type: SS
8470 #: build/C/man2/ptrace.2:974
8471 #, no-wrap
8472 msgid "Signal-delivery-stop"
8473 msgstr ""
8474
8475 #. type: Plain text
8476 #: build/C/man2/ptrace.2:994
8477 msgid ""
8478 "When a (possibly multithreaded) process receives any signal except "
8479 "B<SIGKILL>, the kernel selects an arbitrary thread which handles the "
8480 "signal.  (If the signal is generated with B<tgkill>(2), the target thread "
8481 "can be explicitly selected by the caller.)  If the selected thread is "
8482 "traced, it enters signal-delivery-stop.  At this point, the signal is not "
8483 "yet delivered to the process, and can be suppressed by the tracer.  If the "
8484 "tracer doesn't suppress the signal, it passes the signal to the tracee in "
8485 "the next ptrace restart request.  This second step of signal delivery is "
8486 "called I<signal injection> in this manual page.  Note that if the signal is "
8487 "blocked, signal-delivery-stop doesn't happen until the signal is unblocked, "
8488 "with the usual exception that B<SIGSTOP> can't be blocked."
8489 msgstr ""
8490
8491 #. type: Plain text
8492 #: build/C/man2/ptrace.2:1008
8493 msgid ""
8494 "Signal-delivery-stop is observed by the tracer as B<waitpid>(2)  returning "
8495 "with I<WIFSTOPPED(status)> true, with the signal returned by "
8496 "I<WSTOPSIG(status)>.  If the signal is B<SIGTRAP>, this may be a different "
8497 "kind of ptrace-stop; see the \"Syscall-stops\" and \"execve\" sections below "
8498 "for details.  If I<WSTOPSIG(status)> returns a stopping signal, this may be "
8499 "a group-stop; see below."
8500 msgstr ""
8501
8502 #. type: SS
8503 #: build/C/man2/ptrace.2:1008
8504 #, no-wrap
8505 msgid "Signal injection and suppression"
8506 msgstr ""
8507
8508 #. type: Plain text
8509 #: build/C/man2/ptrace.2:1011
8510 msgid ""
8511 "After signal-delivery-stop is observed by the tracer, the tracer should "
8512 "restart the tracee with the call"
8513 msgstr ""
8514
8515 #. type: Plain text
8516 #: build/C/man2/ptrace.2:1013
8517 #, no-wrap
8518 msgid "    ptrace(PTRACE_restart, pid, 0, sig)\n"
8519 msgstr ""
8520
8521 #. type: Plain text
8522 #: build/C/man2/ptrace.2:1026
8523 msgid ""
8524 "where B<PTRACE_restart> is one of the restarting ptrace requests.  If I<sig> "
8525 "is 0, then a signal is not delivered.  Otherwise, the signal I<sig> is "
8526 "delivered.  This operation is called I<signal injection> in this manual "
8527 "page, to distinguish it from signal-delivery-stop."
8528 msgstr ""
8529
8530 #. type: Plain text
8531 #: build/C/man2/ptrace.2:1032
8532 msgid ""
8533 "The I<sig> value may be different from the I<WSTOPSIG(status)> value: the "
8534 "tracer can cause a different signal to be injected."
8535 msgstr ""
8536
8537 #. type: Plain text
8538 #: build/C/man2/ptrace.2:1048
8539 msgid ""
8540 "Note that a suppressed signal still causes system calls to return "
8541 "prematurely.  In this case, system calls will be restarted: the tracer will "
8542 "observe the tracee to reexecute the interrupted system call (or "
8543 "B<restart_syscall>(2)  system call for a few syscalls which use a different "
8544 "mechanism for restarting) if the tracer uses B<PTRACE_SYSCALL>.  Even system "
8545 "calls (such as B<poll>(2))  which are not restartable after signal are "
8546 "restarted after signal is suppressed; however, kernel bugs exist which cause "
8547 "some syscalls to fail with B<EINTR> even though no observable signal is "
8548 "injected to the tracee."
8549 msgstr ""
8550
8551 #. type: Plain text
8552 #: build/C/man2/ptrace.2:1059
8553 msgid ""
8554 "Restarting ptrace commands issued in ptrace-stops other than "
8555 "signal-delivery-stop are not guaranteed to inject a signal, even if I<sig> "
8556 "is nonzero.  No error is reported; a nonzero I<sig> may simply be ignored.  "
8557 "Ptrace users should not try to \"create a new signal\" this way: use "
8558 "B<tgkill>(2)  instead."
8559 msgstr ""
8560
8561 #. type: Plain text
8562 #: build/C/man2/ptrace.2:1066
8563 msgid ""
8564 "The fact that signal injection requests may be ignored when restarting the "
8565 "tracee after ptrace stops that are not signal-delivery-stops is a cause of "
8566 "confusion among ptrace users.  One typical scenario is that the tracer "
8567 "observes group-stop, mistakes it for signal-delivery-stop, restarts the "
8568 "tracee with"
8569 msgstr ""
8570
8571 #. type: Plain text
8572 #: build/C/man2/ptrace.2:1068
8573 #, no-wrap
8574 msgid "    ptrace(PTRACE_restart, pid, 0, stopsig)\n"
8575 msgstr ""
8576
8577 #. type: Plain text
8578 #: build/C/man2/ptrace.2:1074
8579 msgid ""
8580 "with the intention of injecting I<stopsig>, but I<stopsig> gets ignored and "
8581 "the tracee continues to run."
8582 msgstr ""
8583
8584 #. type: Plain text
8585 #: build/C/man2/ptrace.2:1094
8586 msgid ""
8587 "The B<SIGCONT> signal has a side effect of waking up (all threads of)  a "
8588 "group-stopped process.  This side effect happens before "
8589 "signal-delivery-stop.  The tracer can't suppress this side effect (it can "
8590 "only suppress signal injection, which only causes the B<SIGCONT> handler to "
8591 "not be executed in the tracee, if such a handler is installed).  In fact, "
8592 "waking up from group-stop may be followed by signal-delivery-stop for "
8593 "signal(s)  I<other than> B<SIGCONT>, if they were pending when B<SIGCONT> "
8594 "was delivered.  In other words, B<SIGCONT> may be not the first signal "
8595 "observed by the tracee after it was sent."
8596 msgstr ""
8597
8598 #. type: Plain text
8599 #: build/C/man2/ptrace.2:1098
8600 msgid ""
8601 "Stopping signals cause (all threads of) a process to enter group-stop.  This "
8602 "side effect happens after signal injection, and therefore can be suppressed "
8603 "by the tracer."
8604 msgstr ""
8605
8606 #.  In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
8607 #.  there is:
8608 #
8609 #.              /* The debugger continued.  Ignore SIGSTOP.  */
8610 #.              if (signr == SIGSTOP)
8611 #.                      continue;
8612 #. type: Plain text
8613 #: build/C/man2/ptrace.2:1108
8614 msgid "In Linux 2.4 and earlier, the B<SIGSTOP> signal can't be injected."
8615 msgstr ""
8616
8617 #. type: Plain text
8618 #: build/C/man2/ptrace.2:1125
8619 msgid ""
8620 "B<PTRACE_GETSIGINFO> can be used to retrieve a I<siginfo_t> structure which "
8621 "corresponds to the delivered signal.  B<PTRACE_SETSIGINFO> may be used to "
8622 "modify it.  If B<PTRACE_SETSIGINFO> has been used to alter I<siginfo_t>, the "
8623 "I<si_signo> field and the I<sig> parameter in the restarting command must "
8624 "match, otherwise the result is undefined."
8625 msgstr ""
8626
8627 #. type: SS
8628 #: build/C/man2/ptrace.2:1125
8629 #, no-wrap
8630 msgid "Group-stop"
8631 msgstr ""
8632
8633 #. type: Plain text
8634 #: build/C/man2/ptrace.2:1137
8635 msgid ""
8636 "When a (possibly multithreaded) process receives a stopping signal, all "
8637 "threads stop.  If some threads are traced, they enter a group-stop.  Note "
8638 "that the stopping signal will first cause signal-delivery-stop (on one "
8639 "tracee only), and only after it is injected by the tracer (or after it was "
8640 "dispatched to a thread which isn't traced), will group-stop be initiated on "
8641 "I<all> tracees within the multithreaded process.  As usual, every tracee "
8642 "reports its group-stop separately to the corresponding tracer."
8643 msgstr ""
8644
8645 #. type: Plain text
8646 #: build/C/man2/ptrace.2:1146
8647 msgid ""
8648 "Group-stop is observed by the tracer as B<waitpid>(2)  returning with "
8649 "I<WIFSTOPPED(status)> true, with the stopping signal available via "
8650 "I<WSTOPSIG(status)>.  The same result is returned by some other classes of "
8651 "ptrace-stops, therefore the recommended practice is to perform the call"
8652 msgstr ""
8653
8654 #. type: Plain text
8655 #: build/C/man2/ptrace.2:1148
8656 #, no-wrap
8657 msgid "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)\n"
8658 msgstr ""
8659
8660 #. type: Plain text
8661 #: build/C/man2/ptrace.2:1169
8662 msgid ""
8663 "The call can be avoided if the signal is not B<SIGSTOP>, B<SIGTSTP>, "
8664 "B<SIGTTIN>, or B<SIGTTOU>; only these four signals are stopping signals.  If "
8665 "the tracer sees something else, it can't be a group-stop.  Otherwise, the "
8666 "tracer needs to call B<PTRACE_GETSIGINFO>.  If B<PTRACE_GETSIGINFO> fails "
8667 "with B<EINVAL>, then it is definitely a group-stop.  (Other failure codes "
8668 "are possible, such as B<ESRCH> (\"no such process\") if a B<SIGKILL> killed "
8669 "the tracee.)"
8670 msgstr ""
8671
8672 #. type: Plain text
8673 #: build/C/man2/ptrace.2:1179
8674 msgid ""
8675 "If tracee was attached using B<PTRACE_SEIZE>, group-stop is indicated by "
8676 "B<PTRACE_EVENT_STOP>: I<statusE<gt>E<gt>16 == PTRACE_EVENT_STOP>.  This "
8677 "allows detection of group-stops without requiring an extra "
8678 "B<PTRACE_GETSIGINFO> call."
8679 msgstr ""
8680
8681 #. type: Plain text
8682 #: build/C/man2/ptrace.2:1188
8683 msgid ""
8684 "As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until "
8685 "it restarts or kills it, the tracee will not run, and will not send "
8686 "notifications (except B<SIGKILL> death) to the tracer, even if the tracer "
8687 "enters into another B<waitpid>(2)  call."
8688 msgstr ""
8689
8690 #. type: Plain text
8691 #: build/C/man2/ptrace.2:1202
8692 msgid ""
8693 "The kernel behavior described in the previous paragraph causes a problem "
8694 "with transparent handling of stopping signals.  If the tracer restarts the "
8695 "tracee after group-stop, the stopping signal is effectively ignored\\(emthe "
8696 "tracee doesn't remain stopped, it runs.  If the tracer doesn't restart the "
8697 "tracee before entering into the next B<waitpid>(2), future B<SIGCONT> "
8698 "signals will not be reported to the tracer; this would cause the B<SIGCONT> "
8699 "signals to have no effect on the tracee."
8700 msgstr ""
8701
8702 #. type: Plain text
8703 #: build/C/man2/ptrace.2:1213
8704 msgid ""
8705 "Since Linux 3.4, there is a method to overcome this problem: instead of "
8706 "B<PTRACE_CONT>, a B<PTRACE_LISTEN> command can be used to restart a tracee "
8707 "in a way where it does not execute, but waits for a new event which it can "
8708 "report via B<waitpid>(2)  (such as when it is restarted by a B<SIGCONT>)."
8709 msgstr ""
8710
8711 #. type: SS
8712 #: build/C/man2/ptrace.2:1213
8713 #, no-wrap
8714 msgid "PTRACE_EVENT stops"
8715 msgstr ""
8716
8717 #. type: Plain text
8718 #: build/C/man2/ptrace.2:1219
8719 msgid ""
8720 "If the tracer sets B<PTRACE_O_TRACE_*> options, the tracee will enter "
8721 "ptrace-stops called B<PTRACE_EVENT> stops."
8722 msgstr ""
8723
8724 #. type: Plain text
8725 #: build/C/man2/ptrace.2:1233
8726 msgid ""
8727 "B<PTRACE_EVENT> stops are observed by the tracer as B<waitpid>(2)  returning "
8728 "with I<WIFSTOPPED(status)>, and I<WSTOPSIG(status)> returns B<SIGTRAP>.  An "
8729 "additional bit is set in the higher byte of the status word: the value "
8730 "I<statusE<gt>E<gt>8> will be"
8731 msgstr ""
8732
8733 #. type: Plain text
8734 #: build/C/man2/ptrace.2:1235
8735 #, no-wrap
8736 msgid "    (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
8737 msgstr ""
8738
8739 #. type: Plain text
8740 #: build/C/man2/ptrace.2:1237
8741 msgid "The following events exist:"
8742 msgstr ""
8743
8744 #. type: TP
8745 #: build/C/man2/ptrace.2:1237
8746 #, no-wrap
8747 msgid "B<PTRACE_EVENT_VFORK>"
8748 msgstr ""
8749
8750 #. type: Plain text
8751 #: build/C/man2/ptrace.2:1250
8752 msgid ""
8753 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8754 "flag.  When the tracee is continued after this stop, it will wait for child "
8755 "to exit/exec before continuing its execution (in other words, the usual "
8756 "behavior on B<vfork>(2))."
8757 msgstr ""
8758
8759 #. type: TP
8760 #: build/C/man2/ptrace.2:1250
8761 #, no-wrap
8762 msgid "B<PTRACE_EVENT_FORK>"
8763 msgstr ""
8764
8765 #. type: Plain text
8766 #: build/C/man2/ptrace.2:1258
8767 msgid ""
8768 "Stop before return from B<fork>(2)  or B<clone>(2)  with the exit signal set "
8769 "to B<SIGCHLD>."
8770 msgstr ""
8771
8772 #. type: TP
8773 #: build/C/man2/ptrace.2:1258
8774 #, no-wrap
8775 msgid "B<PTRACE_EVENT_CLONE>"
8776 msgstr ""
8777
8778 #. type: Plain text
8779 #: build/C/man2/ptrace.2:1262
8780 msgid "Stop before return from B<clone>(2)."
8781 msgstr ""
8782
8783 #. type: TP
8784 #: build/C/man2/ptrace.2:1262
8785 #, no-wrap
8786 msgid "B<PTRACE_EVENT_VFORK_DONE>"
8787 msgstr ""
8788
8789 #. type: Plain text
8790 #: build/C/man2/ptrace.2:1272
8791 msgid ""
8792 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8793 "flag, but after the child unblocked this tracee by exiting or execing."
8794 msgstr ""
8795
8796 #. type: Plain text
8797 #: build/C/man2/ptrace.2:1278
8798 msgid ""
8799 "For all four stops described above, the stop occurs in the parent (i.e., the "
8800 "tracee), not in the newly created thread.  B<PTRACE_GETEVENTMSG> can be used "
8801 "to retrieve the new thread's ID."
8802 msgstr ""
8803
8804 #. type: TP
8805 #: build/C/man2/ptrace.2:1278
8806 #, no-wrap
8807 msgid "B<PTRACE_EVENT_EXEC>"
8808 msgstr ""
8809
8810 #. type: Plain text
8811 #: build/C/man2/ptrace.2:1285
8812 msgid ""
8813 "Stop before return from B<execve>(2).  Since Linux 3.0, "
8814 "B<PTRACE_GETEVENTMSG> returns the former thread ID."
8815 msgstr ""
8816
8817 #. type: TP
8818 #: build/C/man2/ptrace.2:1285
8819 #, no-wrap
8820 msgid "B<PTRACE_EVENT_EXIT>"
8821 msgstr ""
8822
8823 #. type: Plain text
8824 #: build/C/man2/ptrace.2:1301
8825 msgid ""
8826 "Stop before exit (including death from B<exit_group>(2)), signal death, or "
8827 "exit caused by B<execve>(2)  in a multithreaded process.  "
8828 "B<PTRACE_GETEVENTMSG> returns the exit status.  Registers can be examined "
8829 "(unlike when \"real\" exit happens).  The tracee is still alive; it needs to "
8830 "be B<PTRACE_CONT>ed or B<PTRACE_DETACH>ed to finish exiting."
8831 msgstr ""
8832
8833 #. type: TP
8834 #: build/C/man2/ptrace.2:1301
8835 #, no-wrap
8836 msgid "B<PTRACE_EVENT_STOP>"
8837 msgstr ""
8838
8839 #. type: Plain text
8840 #: build/C/man2/ptrace.2:1313
8841 msgid ""
8842 "Stop induced by B<PTRACE_INTERRUPT> command, or group-stop, or initial "
8843 "ptrace-stop when a new child is attached (only if attached using "
8844 "B<PTRACE_SEIZE>), or B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used."
8845 msgstr ""
8846
8847 #. type: Plain text
8848 #: build/C/man2/ptrace.2:1325
8849 msgid ""
8850 "B<PTRACE_GETSIGINFO> on B<PTRACE_EVENT> stops returns B<SIGTRAP> in "
8851 "I<si_signo>, with I<si_code> set to I<(eventE<lt>E<lt>8)\\ |\\ SIGTRAP>."
8852 msgstr ""
8853
8854 #. type: SS
8855 #: build/C/man2/ptrace.2:1325
8856 #, no-wrap
8857 msgid "Syscall-stops"
8858 msgstr ""
8859
8860 #. type: Plain text
8861 #: build/C/man2/ptrace.2:1338
8862 msgid ""
8863 "If the tracee was restarted by B<PTRACE_SYSCALL>, the tracee enters "
8864 "syscall-enter-stop just prior to entering any system call.  If the tracer "
8865 "restarts the tracee with B<PTRACE_SYSCALL>, the tracee enters "
8866 "syscall-exit-stop when the system call is finished, or if it is interrupted "
8867 "by a signal.  (That is, signal-delivery-stop never happens between "
8868 "syscall-enter-stop and syscall-exit-stop; it happens I<after> "
8869 "syscall-exit-stop.)"
8870 msgstr ""
8871
8872 #. type: Plain text
8873 #: build/C/man2/ptrace.2:1352
8874 msgid ""
8875 "Other possibilities are that the tracee may stop in a B<PTRACE_EVENT> stop, "
8876 "exit (if it entered B<_exit>(2)  or B<exit_group>(2)), be killed by "
8877 "B<SIGKILL>, or die silently (if it is a thread group leader, the "
8878 "B<execve>(2)  happened in another thread, and that thread is not traced by "
8879 "the same tracer; this situation is discussed later)."
8880 msgstr ""
8881
8882 #. type: Plain text
8883 #: build/C/man2/ptrace.2:1367
8884 msgid ""
8885 "Syscall-enter-stop and syscall-exit-stop are observed by the tracer as "
8886 "B<waitpid>(2)  returning with I<WIFSTOPPED(status)> true, and "
8887 "I<WSTOPSIG(status)> giving B<SIGTRAP>.  If the B<PTRACE_O_TRACESYSGOOD> "
8888 "option was set by the tracer, then I<WSTOPSIG(status)> will give the value "
8889 "I<(SIGTRAP\\ |\\ 0x80)>."
8890 msgstr ""
8891
8892 #. type: Plain text
8893 #: build/C/man2/ptrace.2:1373
8894 msgid ""
8895 "Syscall-stops can be distinguished from signal-delivery-stop with B<SIGTRAP> "
8896 "by querying B<PTRACE_GETSIGINFO> for the following cases:"
8897 msgstr ""
8898
8899 #. type: TP
8900 #: build/C/man2/ptrace.2:1373
8901 #, no-wrap
8902 msgid "I<si_code> E<lt>= 0"
8903 msgstr ""
8904
8905 #. type: Plain text
8906 #: build/C/man2/ptrace.2:1385
8907 msgid ""
8908 "B<SIGTRAP> was delivered as a result of a user-space action, for example, a "
8909 "system call (B<tgkill>(2), B<kill>(2), B<sigqueue>(3), etc.), expiration of "
8910 "a POSIX timer, change of state on a POSIX message queue, or completion of an "
8911 "asynchronous I/O request."
8912 msgstr ""
8913
8914 #. type: TP
8915 #: build/C/man2/ptrace.2:1385
8916 #, no-wrap
8917 msgid "I<si_code> == SI_KERNEL (0x80)"
8918 msgstr ""
8919
8920 #. type: Plain text
8921 #: build/C/man2/ptrace.2:1389
8922 msgid "B<SIGTRAP> was sent by the kernel."
8923 msgstr ""
8924
8925 #. type: TP
8926 #: build/C/man2/ptrace.2:1389
8927 #, no-wrap
8928 msgid "I<si_code> == SIGTRAP or I<si_code> == (SIGTRAP|0x80)"
8929 msgstr ""
8930
8931 #. type: Plain text
8932 #: build/C/man2/ptrace.2:1392
8933 msgid "This is a syscall-stop."
8934 msgstr ""
8935
8936 #. type: Plain text
8937 #: build/C/man2/ptrace.2:1397
8938 msgid ""
8939 "However, syscall-stops happen very often (twice per system call), and "
8940 "performing B<PTRACE_GETSIGINFO> for every syscall-stop may be somewhat "
8941 "expensive."
8942 msgstr ""
8943
8944 #. type: Plain text
8945 #: build/C/man2/ptrace.2:1420
8946 msgid ""
8947 "Some architectures allow the cases to be distinguished by examining "
8948 "registers.  For example, on x86, I<rax> == -B<ENOSYS> in "
8949 "syscall-enter-stop.  Since B<SIGTRAP> (like any other signal) always happens "
8950 "I<after> syscall-exit-stop, and at this point I<rax> almost never contains "
8951 "-B<ENOSYS>, the B<SIGTRAP> looks like \"syscall-stop which is not "
8952 "syscall-enter-stop\"; in other words, it looks like a \"stray "
8953 "syscall-exit-stop\" and can be detected this way.  But such detection is "
8954 "fragile and is best avoided."
8955 msgstr ""
8956
8957 #. type: Plain text
8958 #: build/C/man2/ptrace.2:1426
8959 msgid ""
8960 "Using the B<PTRACE_O_TRACESYSGOOD> option is the recommended method to "
8961 "distinguish syscall-stops from other kinds of ptrace-stops, since it is "
8962 "reliable and does not incur a performance penalty."
8963 msgstr ""
8964
8965 #. type: Plain text
8966 #: build/C/man2/ptrace.2:1437
8967 msgid ""
8968 "Syscall-enter-stop and syscall-exit-stop are indistinguishable from each "
8969 "other by the tracer.  The tracer needs to keep track of the sequence of "
8970 "ptrace-stops in order to not misinterpret syscall-enter-stop as "
8971 "syscall-exit-stop or vice versa.  The rule is that syscall-enter-stop is "
8972 "always followed by syscall-exit-stop, B<PTRACE_EVENT> stop or the tracee's "
8973 "death; no other kinds of ptrace-stop can occur in between."
8974 msgstr ""
8975
8976 #. type: Plain text
8977 #: build/C/man2/ptrace.2:1442
8978 msgid ""
8979 "If after syscall-enter-stop, the tracer uses a restarting command other than "
8980 "B<PTRACE_SYSCALL>, syscall-exit-stop is not generated."
8981 msgstr ""
8982
8983 #. type: Plain text
8984 #: build/C/man2/ptrace.2:1454
8985 msgid ""
8986 "B<PTRACE_GETSIGINFO> on syscall-stops returns B<SIGTRAP> in I<si_signo>, "
8987 "with I<si_code> set to B<SIGTRAP> or I<(SIGTRAP|0x80)>."
8988 msgstr ""
8989
8990 #. type: SS
8991 #: build/C/man2/ptrace.2:1454
8992 #, no-wrap
8993 msgid "PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops"
8994 msgstr ""
8995
8996 #
8997 #.  FIXME
8998 #.  document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
8999 #.  PTRACE_SYSEMU_SINGLESTEP
9000 #. type: Plain text
9001 #: build/C/man2/ptrace.2:1460
9002 msgid "[Details of these kinds of stops are yet to be documented.]"
9003 msgstr ""
9004
9005 #. type: SS
9006 #: build/C/man2/ptrace.2:1460
9007 #, no-wrap
9008 msgid "Informational and restarting ptrace commands"
9009 msgstr ""
9010
9011 #. type: Plain text
9012 #: build/C/man2/ptrace.2:1470
9013 msgid ""
9014 "Most ptrace commands (all except B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, "
9015 "B<PTRACE_TRACEME>, B<PTRACE_INTERRUPT>, and B<PTRACE_KILL>)  require the "
9016 "tracee to be in a ptrace-stop, otherwise they fail with B<ESRCH>."
9017 msgstr ""
9018
9019 #. type: Plain text
9020 #: build/C/man2/ptrace.2:1475
9021 msgid ""
9022 "When the tracee is in ptrace-stop, the tracer can read and write data to the "
9023 "tracee using informational commands.  These commands leave the tracee in "
9024 "ptrace-stopped state:"
9025 msgstr ""
9026
9027 #. type: Plain text
9028 #: build/C/man2/ptrace.2:1487
9029 #, no-wrap
9030 msgid ""
9031 "    ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);\n"
9032 "    ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);\n"
9033 "    ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);\n"
9034 "    ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);\n"
9035 "    ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);\n"
9036 "    ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);\n"
9037 "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);\n"
9038 "    ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);\n"
9039 "    ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);\n"
9040 "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
9041 msgstr ""
9042
9043 #. type: Plain text
9044 #: build/C/man2/ptrace.2:1499
9045 msgid ""
9046 "Note that some errors are not reported.  For example, setting signal "
9047 "information (I<siginfo>)  may have no effect in some ptrace-stops, yet the "
9048 "call may succeed (return 0 and not set I<errno>); querying "
9049 "B<PTRACE_GETEVENTMSG> may succeed and return some random value if current "
9050 "ptrace-stop is not documented as returning a meaningful event message."
9051 msgstr ""
9052
9053 #. type: Plain text
9054 #: build/C/man2/ptrace.2:1501
9055 msgid "The call"
9056 msgstr ""
9057
9058 #. type: Plain text
9059 #: build/C/man2/ptrace.2:1503
9060 #, no-wrap
9061 msgid "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
9062 msgstr ""
9063
9064 #. type: Plain text
9065 #: build/C/man2/ptrace.2:1512
9066 msgid ""
9067 "affects one tracee.  The tracee's current flags are replaced.  Flags are "
9068 "inherited by new tracees created and \"auto-attached\" via active "
9069 "B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or B<PTRACE_O_TRACECLONE> "
9070 "options."
9071 msgstr ""
9072
9073 #. type: Plain text
9074 #: build/C/man2/ptrace.2:1515
9075 msgid ""
9076 "Another group of commands makes the ptrace-stopped tracee run.  They have "
9077 "the form:"
9078 msgstr ""
9079
9080 #. type: Plain text
9081 #: build/C/man2/ptrace.2:1517
9082 #, no-wrap
9083 msgid "    ptrace(cmd, pid, 0, sig);\n"
9084 msgstr ""
9085
9086 #. type: Plain text
9087 #: build/C/man2/ptrace.2:1538
9088 msgid ""
9089 "where I<cmd> is B<PTRACE_CONT>, B<PTRACE_LISTEN>, B<PTRACE_DETACH>, "
9090 "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>, B<PTRACE_SYSEMU>, or "
9091 "B<PTRACE_SYSEMU_SINGLESTEP>.  If the tracee is in signal-delivery-stop, "
9092 "I<sig> is the signal to be injected (if it is nonzero).  Otherwise, I<sig> "
9093 "may be ignored.  (When restarting a tracee from a ptrace-stop other than "
9094 "signal-delivery-stop, recommended practice is to always pass 0 in I<sig>.)"
9095 msgstr ""
9096
9097 #. type: SS
9098 #: build/C/man2/ptrace.2:1538
9099 #, no-wrap
9100 msgid "Attaching and detaching"
9101 msgstr ""
9102
9103 #. type: Plain text
9104 #: build/C/man2/ptrace.2:1540
9105 msgid "A thread can be attached to the tracer using the call"
9106 msgstr ""
9107
9108 #. type: Plain text
9109 #: build/C/man2/ptrace.2:1542
9110 #, no-wrap
9111 msgid "    ptrace(PTRACE_ATTACH, pid, 0, 0);\n"
9112 msgstr ""
9113
9114 #. type: Plain text
9115 #: build/C/man2/ptrace.2:1544 build/C/man2/ptrace.2:2047
9116 msgid "or"
9117 msgstr ""
9118
9119 #. type: Plain text
9120 #: build/C/man2/ptrace.2:1546
9121 #, no-wrap
9122 msgid "    ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);\n"
9123 msgstr ""
9124
9125 #
9126 #.  FIXME: Describe how to attach to a thread which is already
9127 #.         group-stopped.
9128 #. type: Plain text
9129 #: build/C/man2/ptrace.2:1571
9130 msgid ""
9131 "B<PTRACE_ATTACH> sends B<SIGSTOP> to this thread.  If the tracer wants this "
9132 "B<SIGSTOP> to have no effect, it needs to suppress it.  Note that if other "
9133 "signals are concurrently sent to this thread during attach, the tracer may "
9134 "see the tracee enter signal-delivery-stop with other signal(s) first! The "
9135 "usual practice is to reinject these signals until B<SIGSTOP> is seen, then "
9136 "suppress B<SIGSTOP> injection.  The design bug here is that a ptrace attach "
9137 "and a concurrently delivered B<SIGSTOP> may race and the concurrent "
9138 "B<SIGSTOP> may be lost."
9139 msgstr ""
9140
9141 #. type: Plain text
9142 #: build/C/man2/ptrace.2:1578
9143 msgid ""
9144 "Since attaching sends B<SIGSTOP> and the tracer usually suppresses it, this "
9145 "may cause a stray B<EINTR> return from the currently executing system call "
9146 "in the tracee, as described in the \"Signal injection and suppression\" "
9147 "section."
9148 msgstr ""
9149
9150 #. type: Plain text
9151 #: build/C/man2/ptrace.2:1590
9152 msgid ""
9153 "Since Linux 3.4, B<PTRACE_SEIZE> can be used instead of B<PTRACE_ATTACH>.  "
9154 "B<PTRACE_SEIZE> does not stop the attached process.  If you need to stop it "
9155 "after attach (or at any other time) without sending it any signals, use "
9156 "B<PTRACE_INTERRUPT> command."
9157 msgstr ""
9158
9159 #. type: Plain text
9160 #: build/C/man2/ptrace.2:1592
9161 msgid "The request"
9162 msgstr ""
9163
9164 #. type: Plain text
9165 #: build/C/man2/ptrace.2:1594
9166 #, no-wrap
9167 msgid "    ptrace(PTRACE_TRACEME, 0, 0, 0);\n"
9168 msgstr ""
9169
9170 #. type: Plain text
9171 #: build/C/man2/ptrace.2:1600
9172 msgid ""
9173 "turns the calling thread into a tracee.  The thread continues to run "
9174 "(doesn't enter ptrace-stop).  A common practice is to follow the "
9175 "B<PTRACE_TRACEME> with"
9176 msgstr ""
9177
9178 #. type: Plain text
9179 #: build/C/man2/ptrace.2:1602
9180 #, no-wrap
9181 msgid "    raise(SIGSTOP);\n"
9182 msgstr ""
9183
9184 #. type: Plain text
9185 #: build/C/man2/ptrace.2:1605
9186 msgid ""
9187 "and allow the parent (which is our tracer now) to observe our "
9188 "signal-delivery-stop."
9189 msgstr ""
9190
9191 #. type: Plain text
9192 #: build/C/man2/ptrace.2:1629
9193 msgid ""
9194 "If the B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or "
9195 "B<PTRACE_O_TRACECLONE> options are in effect, then children created by, "
9196 "respectively, B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> flag, "
9197 "B<fork>(2)  or B<clone>(2)  with the exit signal set to B<SIGCHLD>, and "
9198 "other kinds of B<clone>(2), are automatically attached to the same tracer "
9199 "which traced their parent.  B<SIGSTOP> is delivered to the children, causing "
9200 "them to enter signal-delivery-stop after they exit the system call which "
9201 "created them."
9202 msgstr ""
9203
9204 #. type: Plain text
9205 #: build/C/man2/ptrace.2:1631
9206 msgid "Detaching of the tracee is performed by:"
9207 msgstr ""
9208
9209 #. type: Plain text
9210 #: build/C/man2/ptrace.2:1633
9211 #, no-wrap
9212 msgid "    ptrace(PTRACE_DETACH, pid, 0, sig);\n"
9213 msgstr ""
9214
9215 #. type: Plain text
9216 #: build/C/man2/ptrace.2:1641
9217 msgid ""
9218 "B<PTRACE_DETACH> is a restarting operation; therefore it requires the tracee "
9219 "to be in ptrace-stop.  If the tracee is in signal-delivery-stop, a signal "
9220 "can be injected.  Otherwise, the I<sig> parameter may be silently ignored."
9221 msgstr ""
9222
9223 #.  FIXME: Describe how to detach from a group-stopped tracee so that it
9224 #.         doesn't run, but continues to wait for SIGCONT.
9225 #. type: Plain text
9226 #: build/C/man2/ptrace.2:1665
9227 msgid ""
9228 "If the tracee is running when the tracer wants to detach it, the usual "
9229 "solution is to send B<SIGSTOP> (using B<tgkill>(2), to make sure it goes to "
9230 "the correct thread), wait for the tracee to stop in signal-delivery-stop for "
9231 "B<SIGSTOP> and then detach it (suppressing B<SIGSTOP> injection).  A design "
9232 "bug is that this can race with concurrent B<SIGSTOP>s.  Another complication "
9233 "is that the tracee may enter other ptrace-stops and needs to be restarted "
9234 "and waited for again, until B<SIGSTOP> is seen.  Yet another complication is "
9235 "to be sure that the tracee is not already ptrace-stopped, because no signal "
9236 "delivery happens while it is\\(emnot even B<SIGSTOP>."
9237 msgstr ""
9238
9239 #. type: Plain text
9240 #: build/C/man2/ptrace.2:1673
9241 msgid ""
9242 "If the tracer dies, all tracees are automatically detached and restarted, "
9243 "unless they were in group-stop.  Handling of restart from group-stop is "
9244 "currently buggy, but the \"as planned\" behavior is to leave tracee stopped "
9245 "and waiting for B<SIGCONT>.  If the tracee is restarted from "
9246 "signal-delivery-stop, the pending signal is injected."
9247 msgstr ""
9248
9249 #. type: SS
9250 #: build/C/man2/ptrace.2:1673
9251 #, no-wrap
9252 msgid "execve(2) under ptrace"
9253 msgstr ""
9254
9255 #.  clone(2) CLONE_THREAD says:
9256 #.      If  any  of the threads in a thread group performs an execve(2),
9257 #.      then all threads other than the thread group leader are terminated,
9258 #.      and the new program is executed in the thread group leader.
9259 #
9260 #.  In kernel 3.1 sources, see fs/exec.c::de_thread()
9261 #. type: Plain text
9262 #: build/C/man2/ptrace.2:1692
9263 msgid ""
9264 "When one thread in a multithreaded process calls B<execve>(2), the kernel "
9265 "destroys all other threads in the process, and resets the thread ID of the "
9266 "execing thread to the thread group ID (process ID).  (Or, to put things "
9267 "another way, when a multithreaded process does an B<execve>(2), at "
9268 "completion of the call, it appears as though the B<execve>(2)  occurred in "
9269 "the thread group leader, regardless of which thread did the B<execve>(2).)  "
9270 "This resetting of the thread ID looks very confusing to tracers:"
9271 msgstr ""
9272
9273 #. type: Plain text
9274 #: build/C/man2/ptrace.2:1702
9275 msgid ""
9276 "All other threads stop in B<PTRACE_EVENT_EXIT> stop, if the "
9277 "B<PTRACE_O_TRACEEXIT> option was turned on.  Then all other threads except "
9278 "the thread group leader report death as if they exited via B<_exit>(2)  with "
9279 "exit code 0."
9280 msgstr ""
9281
9282 #. type: Plain text
9283 #: build/C/man2/ptrace.2:1710
9284 msgid ""
9285 "The execing tracee changes its thread ID while it is in the B<execve>(2).  "
9286 "(Remember, under ptrace, the \"pid\" returned from B<waitpid>(2), or fed "
9287 "into ptrace calls, is the tracee's thread ID.)  That is, the tracee's thread "
9288 "ID is reset to be the same as its process ID, which is the same as the "
9289 "thread group leader's thread ID."
9290 msgstr ""
9291
9292 #. type: Plain text
9293 #: build/C/man2/ptrace.2:1716
9294 msgid ""
9295 "Then a B<PTRACE_EVENT_EXEC> stop happens, if the B<PTRACE_O_TRACEEXEC> "
9296 "option was turned on."
9297 msgstr ""
9298
9299 #. type: Plain text
9300 #: build/C/man2/ptrace.2:1737
9301 msgid ""
9302 "If the thread group leader has reported its B<PTRACE_EVENT_EXIT> stop by "
9303 "this time, it appears to the tracer that the dead thread leader \"reappears "
9304 "from nowhere\".  (Note: the thread group leader does not report death via "
9305 "I<WIFEXITED(status)> until there is at least one other live thread.  This "
9306 "eliminates the possibility that the tracer will see it dying and then "
9307 "reappearing.)  If the thread group leader was still alive, for the tracer "
9308 "this may look as if thread group leader returns from a different system call "
9309 "than it entered, or even \"returned from a system call even though it was "
9310 "not in any system call\".  If the thread group leader was not traced (or was "
9311 "traced by a different tracer), then during B<execve>(2)  it will appear as "
9312 "if it has become a tracee of the tracer of the execing tracee."
9313 msgstr ""
9314
9315 #. type: Plain text
9316 #: build/C/man2/ptrace.2:1740
9317 msgid ""
9318 "All of the above effects are the artifacts of the thread ID change in the "
9319 "tracee."
9320 msgstr ""
9321
9322 #. type: Plain text
9323 #: build/C/man2/ptrace.2:1760
9324 msgid ""
9325 "The B<PTRACE_O_TRACEEXEC> option is the recommended tool for dealing with "
9326 "this situation.  First, it enables B<PTRACE_EVENT_EXEC> stop, which occurs "
9327 "before B<execve>(2)  returns.  In this stop, the tracer can use "
9328 "B<PTRACE_GETEVENTMSG> to retrieve the tracee's former thread ID.  (This "
9329 "feature was introduced in Linux 3.0).  Second, the B<PTRACE_O_TRACEEXEC> "
9330 "option disables legacy B<SIGTRAP> generation on B<execve>(2)."
9331 msgstr ""
9332
9333 #. type: Plain text
9334 #: build/C/man2/ptrace.2:1766
9335 msgid ""
9336 "When the tracer receives B<PTRACE_EVENT_EXEC> stop notification, it is "
9337 "guaranteed that except this tracee and the thread group leader, no other "
9338 "threads from the process are alive."
9339 msgstr ""
9340
9341 #. type: Plain text
9342 #: build/C/man2/ptrace.2:1774
9343 msgid ""
9344 "On receiving the B<PTRACE_EVENT_EXEC> stop notification, the tracer should "
9345 "clean up all its internal data structures describing the threads of this "
9346 "process, and retain only one data structure\\(emone which describes the "
9347 "single still running tracee, with"
9348 msgstr ""
9349
9350 #. type: Plain text
9351 #: build/C/man2/ptrace.2:1776
9352 #, no-wrap
9353 msgid "    thread ID == thread group ID == process ID.\n"
9354 msgstr ""
9355
9356 #. type: Plain text
9357 #: build/C/man2/ptrace.2:1780
9358 msgid "Example: two threads call B<execve>(2)  at the same time:"
9359 msgstr ""
9360
9361 #. type: Plain text
9362 #: build/C/man2/ptrace.2:1791
9363 #, no-wrap
9364 msgid ""
9365 "*** we get syscall-enter-stop in thread 1: **\n"
9366 "PID1 execve(\"/bin/foo\", \"foo\" E<lt>unfinished ...E<gt>\n"
9367 "*** we issue PTRACE_SYSCALL for thread 1 **\n"
9368 "*** we get syscall-enter-stop in thread 2: **\n"
9369 "PID2 execve(\"/bin/bar\", \"bar\" E<lt>unfinished ...E<gt>\n"
9370 "*** we issue PTRACE_SYSCALL for thread 2 **\n"
9371 "*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **\n"
9372 "*** we get syscall-exit-stop for PID0: **\n"
9373 "PID0 E<lt>... execve resumedE<gt> )             = 0\n"
9374 msgstr ""
9375
9376 #. type: Plain text
9377 #: build/C/man2/ptrace.2:1814
9378 msgid ""
9379 "If the B<PTRACE_O_TRACEEXEC> option is I<not> in effect for the execing "
9380 "tracee, the kernel delivers an extra B<SIGTRAP> to the tracee after "
9381 "B<execve>(2)  returns.  This is an ordinary signal (similar to one which can "
9382 "be generated by I<kill -TRAP>), not a special kind of ptrace-stop.  "
9383 "Employing B<PTRACE_GETSIGINFO> for this signal returns I<si_code> set to 0 "
9384 "(I<SI_USER>).  This signal may be blocked by signal mask, and thus may be "
9385 "delivered (much) later."
9386 msgstr ""
9387
9388 #. type: Plain text
9389 #: build/C/man2/ptrace.2:1833
9390 msgid ""
9391 "Usually, the tracer (for example, B<strace>(1))  would not want to show this "
9392 "extra post-execve B<SIGTRAP> signal to the user, and would suppress its "
9393 "delivery to the tracee (if B<SIGTRAP> is set to B<SIG_DFL>, it is a killing "
9394 "signal).  However, determining I<which> B<SIGTRAP> to suppress is not easy.  "
9395 "Setting the B<PTRACE_O_TRACEEXEC> option and thus suppressing this extra "
9396 "B<SIGTRAP> is the recommended approach."
9397 msgstr ""
9398
9399 #. type: SS
9400 #: build/C/man2/ptrace.2:1833
9401 #, no-wrap
9402 msgid "Real parent"
9403 msgstr ""
9404
9405 #. type: Plain text
9406 #: build/C/man2/ptrace.2:1840
9407 msgid ""
9408 "The ptrace API (ab)uses the standard UNIX parent/child signaling over "
9409 "B<waitpid>(2).  This used to cause the real parent of the process to stop "
9410 "receiving several kinds of B<waitpid>(2)  notifications when the child "
9411 "process is traced by some other process."
9412 msgstr ""
9413
9414 #. type: Plain text
9415 #: build/C/man2/ptrace.2:1843
9416 msgid ""
9417 "Many of these bugs have been fixed, but as of Linux 2.6.38 several still "
9418 "exist; see BUGS below."
9419 msgstr ""
9420
9421 #. type: Plain text
9422 #: build/C/man2/ptrace.2:1845
9423 msgid "As of Linux 2.6.38, the following is believed to work correctly:"
9424 msgstr ""
9425
9426 #. type: Plain text
9427 #: build/C/man2/ptrace.2:1853
9428 msgid ""
9429 "exit/death by signal is reported first to the tracer, then, when the tracer "
9430 "consumes the B<waitpid>(2)  result, to the real parent (to the real parent "
9431 "only when the whole multithreaded process exits).  If the tracer and the "
9432 "real parent are the same process, the report is sent only once."
9433 msgstr ""
9434
9435 #. type: Plain text
9436 #: build/C/man2/ptrace.2:1858
9437 msgid ""
9438 "On success, the B<PTRACE_PEEK*> requests return the requested data (but see "
9439 "NOTES), while other requests return zero."
9440 msgstr ""
9441
9442 #. type: Plain text
9443 #: build/C/man2/ptrace.2:1868
9444 msgid ""
9445 "On error, all requests return -1, and I<errno> is set appropriately.  Since "
9446 "the value returned by a successful B<PTRACE_PEEK*> request may be -1, the "
9447 "caller must clear I<errno> before the call, and then check it afterward to "
9448 "determine whether or not an error occurred."
9449 msgstr ""
9450
9451 #. type: Plain text
9452 #: build/C/man2/ptrace.2:1872
9453 msgid "(i386 only) There was an error with allocating or freeing a debug register."
9454 msgstr ""
9455
9456 #. type: Plain text
9457 #: build/C/man2/ptrace.2:1883
9458 msgid ""
9459 "There was an attempt to read from or write to an invalid area in the "
9460 "tracer's or the tracee's memory, probably because the area wasn't mapped or "
9461 "accessible.  Unfortunately, under Linux, different variations of this fault "
9462 "will return B<EIO> or B<EFAULT> more or less arbitrarily."
9463 msgstr ""
9464
9465 #. type: Plain text
9466 #: build/C/man2/ptrace.2:1886
9467 msgid "An attempt was made to set an invalid option."
9468 msgstr ""
9469
9470 #. type: Plain text
9471 #: build/C/man2/ptrace.2:1893
9472 msgid ""
9473 "I<request> is invalid, or an attempt was made to read from or write to an "
9474 "invalid area in the tracer's or the tracee's memory, or there was a "
9475 "word-alignment violation, or an invalid signal was specified during a "
9476 "restart request."
9477 msgstr ""
9478
9479 #. type: Plain text
9480 #: build/C/man2/ptrace.2:1906
9481 msgid ""
9482 "The specified process cannot be traced.  This could be because the tracer "
9483 "has insufficient privileges (the required capability is B<CAP_SYS_PTRACE>); "
9484 "unprivileged processes cannot trace processes that they cannot send signals "
9485 "to or those running set-user-ID/set-group-ID programs, for obvious reasons.  "
9486 "Alternatively, the process may already be being traced, or (on kernels "
9487 "before 2.6.26) be B<init>(8)  (PID 1)."
9488 msgstr ""
9489
9490 #. type: Plain text
9491 #: build/C/man2/ptrace.2:1911
9492 msgid ""
9493 "The specified process does not exist, or is not currently being traced by "
9494 "the caller, or is not stopped (for requests that require a stopped tracee)."
9495 msgstr ""
9496
9497 #. type: Plain text
9498 #: build/C/man2/ptrace.2:1913
9499 msgid "SVr4, 4.3BSD."
9500 msgstr ""
9501
9502 #. type: Plain text
9503 #: build/C/man2/ptrace.2:1928
9504 msgid ""
9505 "Although arguments to B<ptrace>()  are interpreted according to the "
9506 "prototype given, glibc currently declares B<ptrace>()  as a variadic "
9507 "function with only the I<request> argument fixed.  It is recommended to "
9508 "always supply four arguments, even if the requested operation does not use "
9509 "them, setting unused/ignored arguments to I<0L> or I<(void\\ *)\\ 0>."
9510 msgstr ""
9511
9512 #. type: Plain text
9513 #: build/C/man2/ptrace.2:1940
9514 msgid ""
9515 "At the system call level, the B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>, and "
9516 "B<PTRACE_PEEKUSER> requests have a different API: they store the result at "
9517 "the address specified by the I<data> parameter, and the return value is the "
9518 "error flag.  The glibc wrapper function provides the API given in "
9519 "DESCRIPTION above, with the result being returned via the function return "
9520 "value."
9521 msgstr ""
9522
9523 #.  See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
9524 #. type: Plain text
9525 #: build/C/man2/ptrace.2:1945
9526 msgid ""
9527 "In Linux kernels before 2.6.26, B<init>(8), the process with PID 1, may not "
9528 "be traced."
9529 msgstr ""
9530
9531 #.  See http://lkml.org/lkml/2008/5/8/375
9532 #. type: Plain text
9533 #: build/C/man2/ptrace.2:1952
9534 msgid ""
9535 "The layout of the contents of memory and the USER area are quite "
9536 "operating-system- and architecture-specific.  The offset supplied, and the "
9537 "data returned, might not entirely match with the definition of I<struct "
9538 "user>."
9539 msgstr ""
9540
9541 #. type: Plain text
9542 #: build/C/man2/ptrace.2:1955
9543 msgid ""
9544 "The size of a \"word\" is determined by the operating-system variant (e.g., "
9545 "for 32-bit Linux it is 32 bits)."
9546 msgstr ""
9547
9548 #. type: Plain text
9549 #: build/C/man2/ptrace.2:1963
9550 msgid ""
9551 "This page documents the way the B<ptrace>()  call works currently in Linux.  "
9552 "Its behavior differs noticeably on other flavors of UNIX.  In any case, use "
9553 "of B<ptrace>()  is highly specific to the operating system and architecture."
9554 msgstr ""
9555
9556 #. type: Plain text
9557 #: build/C/man2/ptrace.2:1974
9558 msgid ""
9559 "On hosts with 2.6 kernel headers, B<PTRACE_SETOPTIONS> is declared with a "
9560 "different value than the one for 2.4.  This leads to applications compiled "
9561 "with 2.6 kernel headers failing when run on 2.4 kernels.  This can be worked "
9562 "around by redefining B<PTRACE_SETOPTIONS> to B<PTRACE_OLDSETOPTIONS>, if "
9563 "that is defined."
9564 msgstr ""
9565
9566 #. type: Plain text
9567 #: build/C/man2/ptrace.2:1977
9568 msgid ""
9569 "Group-stop notifications are sent to the tracer, but not to real parent.  "
9570 "Last confirmed on 2.6.38.6."
9571 msgstr ""
9572
9573 #.  Note from Denys Vlasenko:
9574 #.      Here "exits" means any kind of death - _exit, exit_group,
9575 #.      signal death. Signal death and exit_group cases are trivial,
9576 #.      though: since signal death and exit_group kill all other threads
9577 #.      too, "until all other threads exit" thing happens rather soon
9578 #.      in these cases. Therefore, only _exit presents observably
9579 #.      puzzling behavior to ptrace users: thread leader _exit's,
9580 #.      but WIFEXITED isn't reported! We are trying to explain here
9581 #.      why it is so.
9582 #.   FIXME: ^^^ need to test/verify this scenario
9583 #. type: Plain text
9584 #: build/C/man2/ptrace.2:2008
9585 msgid ""
9586 "If a thread group leader is traced and exits by calling B<_exit>(2), a "
9587 "B<PTRACE_EVENT_EXIT> stop will happen for it (if requested), but the "
9588 "subsequent B<WIFEXITED> notification will not be delivered until all other "
9589 "threads exit.  As explained above, if one of other threads calls "
9590 "B<execve>(2), the death of the thread group leader will I<never> be "
9591 "reported.  If the execed thread is not traced by this tracer, the tracer "
9592 "will never know that B<execve>(2)  happened.  One possible workaround is to "
9593 "B<PTRACE_DETACH> the thread group leader instead of restarting it in this "
9594 "case.  Last confirmed on 2.6.38.6."
9595 msgstr ""
9596
9597 #. type: Plain text
9598 #: build/C/man2/ptrace.2:2018
9599 msgid ""
9600 "A B<SIGKILL> signal may still cause a B<PTRACE_EVENT_EXIT> stop before "
9601 "actual signal death.  This may be changed in the future; B<SIGKILL> is meant "
9602 "to always immediately kill tasks even under ptrace.  Last confirmed on "
9603 "2.6.38.6."
9604 msgstr ""
9605
9606 #. type: Plain text
9607 #: build/C/man2/ptrace.2:2036
9608 msgid ""
9609 "Some system calls return with B<EINTR> if a signal was sent to a tracee, but "
9610 "delivery was suppressed by the tracer.  (This is very typical operation: it "
9611 "is usually done by debuggers on every attach, in order to not introduce a "
9612 "bogus B<SIGSTOP>).  As of Linux 3.2.9, the following system calls are "
9613 "affected (this list is likely incomplete): B<epoll_wait>(2), and B<read>(2)  "
9614 "from an B<inotify>(7)  file descriptor.  The usual symptom of this bug is "
9615 "that when you attach to a quiescent process with the command"
9616 msgstr ""
9617
9618 #. type: Plain text
9619 #: build/C/man2/ptrace.2:2038
9620 #, no-wrap
9621 msgid "    strace -p E<lt>process-IDE<gt>\n"
9622 msgstr ""
9623
9624 #. type: Plain text
9625 #: build/C/man2/ptrace.2:2041
9626 msgid "then, instead of the usual and expected one-line output such as"
9627 msgstr ""
9628
9629 #. type: Plain text
9630 #: build/C/man2/ptrace.2:2044
9631 #, no-wrap
9632 msgid "    restart_syscall(E<lt>... resuming interrupted call ...E<gt>_\n"
9633 msgstr ""
9634
9635 #. type: Plain text
9636 #: build/C/man2/ptrace.2:2050
9637 #, no-wrap
9638 msgid "    select(6, [5], NULL, [5], NULL_\n"
9639 msgstr ""
9640
9641 #. type: Plain text
9642 #: build/C/man2/ptrace.2:2054
9643 msgid ""
9644 "('_' denotes the cursor position), you observe more than one line.  For "
9645 "example:"
9646 msgstr ""
9647
9648 #. type: Plain text
9649 #: build/C/man2/ptrace.2:2058
9650 #, no-wrap
9651 msgid ""
9652 "    clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0\n"
9653 "    epoll_wait(4,_\n"
9654 msgstr ""
9655
9656 #. type: Plain text
9657 #: build/C/man2/ptrace.2:2079
9658 msgid ""
9659 "What is not visible here is that the process was blocked in B<epoll_wait>(2)  "
9660 "before B<strace>(1)  has attached to it.  Attaching caused B<epoll_wait>(2)  "
9661 "to return to user space with the error B<EINTR>.  In this particular case, "
9662 "the program reacted to B<EINTR> by checking the current time, and then "
9663 "executing B<epoll_wait>(2)  again.  (Programs which do not expect such "
9664 "\"stray\" B<EINTR> errors may behave in an unintended way upon an "
9665 "B<strace>(1)  attach.)"
9666 msgstr ""
9667
9668 #. type: Plain text
9669 #: build/C/man2/ptrace.2:2093
9670 msgid ""
9671 "B<gdb>(1), B<strace>(1), B<clone>(2), B<execve>(2), B<fork>(2), "
9672 "B<gettid>(2), B<sigaction>(2), B<tgkill>(2), B<vfork>(2), B<waitpid>(2), "
9673 "B<exec>(3), B<capabilities>(7), B<signal>(7)"
9674 msgstr ""
9675
9676 #. type: TH
9677 #: build/C/man2/quotactl.2:27
9678 #, no-wrap
9679 msgid "QUOTACTL"
9680 msgstr ""
9681
9682 #. type: TH
9683 #: build/C/man2/quotactl.2:27
9684 #, no-wrap
9685 msgid "2010-06-16"
9686 msgstr ""
9687
9688 #. type: Plain text
9689 #: build/C/man2/quotactl.2:30
9690 msgid "quotactl - manipulate disk quotas"
9691 msgstr ""
9692
9693 #. type: Plain text
9694 #: build/C/man2/quotactl.2:34
9695 #, no-wrap
9696 msgid ""
9697 "B<#include E<lt>sys/quota.hE<gt>>\n"
9698 "B<#include E<lt>xfs/xqm.hE<gt>>\n"
9699 msgstr ""
9700
9701 #. type: Plain text
9702 #: build/C/man2/quotactl.2:37
9703 #, no-wrap
9704 msgid ""
9705 "B<int quotactl(int >I<cmd>B<, const char *>I<special>B<, int >I<id>B<, "
9706 "caddr_t >I<addr>B<);>\n"
9707 msgstr ""
9708
9709 #. type: Plain text
9710 #: build/C/man2/quotactl.2:49
9711 msgid ""
9712 "The quota system can be used to set per-user and per-group limits on the "
9713 "amount of disk space used on a filesystem.  For each user and/or group, a "
9714 "soft limit and a hard limit can be set for each filesystem.  The hard limit "
9715 "can't be exceeded.  The soft limit can be exceeded, but warnings will "
9716 "ensue.  Moreover, the user can't exceed the soft limit for more than one "
9717 "week (by default) at a time; after this time, the soft limit counts as a "
9718 "hard limit."
9719 msgstr ""
9720
9721 #. type: Plain text
9722 #: build/C/man2/quotactl.2:74
9723 msgid ""
9724 "The B<quotactl>()  call manipulates disk quotas.  The I<cmd> argument "
9725 "indicates a command to be applied to the user or group ID specified in "
9726 "I<id>.  To initialize the I<cmd> argument, use the I<QCMD(subcmd, type)> "
9727 "macro.  The I<type> value is either B<USRQUOTA>, for user quotas, or "
9728 "B<GRPQUOTA>, for group quotas.  The I<subcmd> value is described below."
9729 msgstr ""
9730
9731 #. type: Plain text
9732 #: build/C/man2/quotactl.2:79
9733 msgid ""
9734 "The I<special> argument is a pointer to a null-terminated string containing "
9735 "the pathname of the (mounted) block special device for the filesystem being "
9736 "manipulated."
9737 msgstr ""
9738
9739 #. type: Plain text
9740 #: build/C/man2/quotactl.2:87
9741 msgid ""
9742 "The I<addr> argument is the address of an optional, command-specific, data "
9743 "structure that is copied in or out of the system.  The interpretation of "
9744 "I<addr> is given with each command below."
9745 msgstr ""
9746
9747 #. type: Plain text
9748 #: build/C/man2/quotactl.2:91
9749 msgid "The I<subcmd> value is one of the following:"
9750 msgstr ""
9751
9752 #. type: TP
9753 #: build/C/man2/quotactl.2:91
9754 #, no-wrap
9755 msgid "B<Q_QUOTAON>"
9756 msgstr ""
9757
9758 #. type: Plain text
9759 #: build/C/man2/quotactl.2:98
9760 msgid ""
9761 "Turn on quotas for a filesystem.  The I<id> argument is the identification "
9762 "number of the quota format to be used.  Currently, there are three supported "
9763 "quota formats:"
9764 msgstr ""
9765
9766 #. type: TP
9767 #: build/C/man2/quotactl.2:99
9768 #, no-wrap
9769 msgid "B<QFMT_VFS_OLD>"
9770 msgstr ""
9771
9772 #. type: Plain text
9773 #: build/C/man2/quotactl.2:102
9774 msgid "The original quota format."
9775 msgstr ""
9776
9777 #. type: TP
9778 #: build/C/man2/quotactl.2:102
9779 #, no-wrap
9780 msgid "B<QFMT_VFS_V0>"
9781 msgstr ""
9782
9783 #. type: Plain text
9784 #: build/C/man2/quotactl.2:106
9785 msgid ""
9786 "The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and "
9787 "quota limits up to 2^42 bytes and 2^32 inodes."
9788 msgstr ""
9789
9790 #. type: TP
9791 #: build/C/man2/quotactl.2:106
9792 #, no-wrap
9793 msgid "B<QFMT_VFS_V1>"
9794 msgstr ""
9795
9796 #. type: Plain text
9797 #: build/C/man2/quotactl.2:110
9798 msgid ""
9799 "A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^64 "
9800 "bytes and 2^64 inodes."
9801 msgstr ""
9802
9803 #. type: Plain text
9804 #: build/C/man2/quotactl.2:121
9805 msgid ""
9806 "The I<addr> argument points to the pathname of a file containing the quotas "
9807 "for the filesystem.  The quota file must exist; it is normally created with "
9808 "the B<quotacheck>(8)  program.  This operation requires privilege "
9809 "(B<CAP_SYS_ADMIN>)."
9810 msgstr ""
9811
9812 #. type: TP
9813 #: build/C/man2/quotactl.2:121
9814 #, no-wrap
9815 msgid "B<Q_QUOTAOFF>"
9816 msgstr ""
9817
9818 #. type: Plain text
9819 #: build/C/man2/quotactl.2:131
9820 msgid ""
9821 "Turn off quotas for a filesystem.  The I<addr> and I<id> arguments are "
9822 "ignored.  This operation requires privilege (B<CAP_SYS_ADMIN>)."
9823 msgstr ""
9824
9825 #. type: TP
9826 #: build/C/man2/quotactl.2:131
9827 #, no-wrap
9828 msgid "B<Q_GETQUOTA>"
9829 msgstr ""
9830
9831 #. type: Plain text
9832 #: build/C/man2/quotactl.2:142
9833 msgid ""
9834 "Get disk quota limits and current usage for user or group I<id>.  The "
9835 "I<addr> argument is a pointer to a I<dqblk> structure defined in "
9836 "I<E<lt>sys/quota.hE<gt>> as follows:"
9837 msgstr ""
9838
9839 #. type: Plain text
9840 #: build/C/man2/quotactl.2:147 build/C/man2/quotactl.2:234
9841 #, no-wrap
9842 msgid ""
9843 "/* uint64_t is an unsigned 64-bit integer;\n"
9844 "   uint32_t is an unsigned 32-bit integer */\n"
9845 msgstr ""
9846
9847 #. type: Plain text
9848 #: build/C/man2/quotactl.2:167
9849 #, no-wrap
9850 msgid ""
9851 "struct dqblk {          /* Definition since Linux 2.4.22 */\n"
9852 "    uint64_t dqb_bhardlimit;   /* absolute limit on disk\n"
9853 "                                  quota blocks alloc */\n"
9854 "    uint64_t dqb_bsoftlimit;   /* preferred limit on\n"
9855 "                                  disk quota blocks */\n"
9856 "    uint64_t dqb_curspace;     /* current quota block\n"
9857 "                                  count */\n"
9858 "    uint64_t dqb_ihardlimit;   /* maximum number of\n"
9859 "                                  allocated inodes */\n"
9860 "    uint64_t dqb_isoftlimit;   /* preferred inode limit */\n"
9861 "    uint64_t dqb_curinodes;    /* current number of\n"
9862 "                                  allocated inodes */\n"
9863 "    uint64_t dqb_btime;        /* time limit for excessive\n"
9864 "                                  disk use */\n"
9865 "    uint64_t dqb_itime;        /* time limit for excessive\n"
9866 "                                  files */\n"
9867 "    uint32_t dqb_valid;        /* bit mask of QIF_*\n"
9868 "                                  constants */\n"
9869 "};\n"
9870 msgstr ""
9871
9872 #. type: Plain text
9873 #: build/C/man2/quotactl.2:170
9874 #, no-wrap
9875 msgid ""
9876 "/* Flags in dqb_valid that indicate which fields in\n"
9877 "   dqblk structure are valid. */\n"
9878 msgstr ""
9879
9880 #. type: Plain text
9881 #: build/C/man2/quotactl.2:181
9882 #, no-wrap
9883 msgid ""
9884 "#define QIF_BLIMITS   1\n"
9885 "#define QIF_SPACE     2\n"
9886 "#define QIF_ILIMITS   4\n"
9887 "#define QIF_INODES    8\n"
9888 "#define QIF_BTIME     16\n"
9889 "#define QIF_ITIME     32\n"
9890 "#define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)\n"
9891 "#define QIF_USAGE     (QIF_SPACE | QIF_INODES)\n"
9892 "#define QIF_TIMES     (QIF_BTIME | QIF_ITIME)\n"
9893 "#define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)\n"
9894 msgstr ""
9895
9896 #. type: Plain text
9897 #: build/C/man2/quotactl.2:198
9898 msgid ""
9899 "The I<dqb_valid> field is a bit mask that is set to indicate the entries in "
9900 "the I<dqblk> structure that are valid.  Currently, the kernel fills in all "
9901 "entries of the I<dqblk> structure and marks them as valid in the "
9902 "I<dqb_valid> field.  Unprivileged users may retrieve only their own quotas; "
9903 "a privileged user (B<CAP_SYS_ADMIN>)  can retrieve the quotas of any user."
9904 msgstr ""
9905
9906 #. type: TP
9907 #: build/C/man2/quotactl.2:198
9908 #, no-wrap
9909 msgid "B<Q_SETQUOTA>"
9910 msgstr ""
9911
9912 #. type: Plain text
9913 #: build/C/man2/quotactl.2:218
9914 msgid ""
9915 "Set quota information for user or group I<id>, using the information "
9916 "supplied in the I<dqblk> structure pointed to by I<addr>.  The I<dqb_valid> "
9917 "field of the I<dqblk> structure indicates which entries in the structure "
9918 "have been set by the caller.  This operation supersedes the B<Q_SETQLIM> and "
9919 "B<Q_SETUSE> operations in the previous quota interfaces.  This operation "
9920 "requires privilege (B<CAP_SYS_ADMIN>)."
9921 msgstr ""
9922
9923 #. type: TP
9924 #: build/C/man2/quotactl.2:218
9925 #, no-wrap
9926 msgid "B<Q_GETINFO>"
9927 msgstr ""
9928
9929 #. type: Plain text
9930 #: build/C/man2/quotactl.2:229
9931 msgid ""
9932 "Get information (like grace times) about quotafile.  The I<addr> argument "
9933 "should be a pointer to a I<dqinfo> structure.  This structure is defined in "
9934 "I<E<lt>sys/quota.hE<gt>> as follows:"
9935 msgstr ""
9936
9937 #. type: Plain text
9938 #: build/C/man2/quotactl.2:238
9939 #, no-wrap
9940 msgid ""
9941 "struct dqinfo {         /* Defined since kernel 2.4.22 */\n"
9942 "    uint64_t dqi_bgrace;    /* Time before block soft limit\n"
9943 "                               becomes hard limit */\n"
9944 msgstr ""
9945
9946 #. type: Plain text
9947 #: build/C/man2/quotactl.2:245
9948 #, no-wrap
9949 msgid ""
9950 "    uint64_t dqi_igrace;    /* Time before inode soft limit\n"
9951 "                               becomes hard limit */\n"
9952 "    uint32_t dqi_flags;     /* Flags for quotafile\n"
9953 "                               (DQF_*) */\n"
9954 "    uint32_t dqi_valid;\n"
9955 "};\n"
9956 msgstr ""
9957
9958 #. type: Plain text
9959 #: build/C/man2/quotactl.2:247
9960 #, no-wrap
9961 msgid "/* Bits for dqi_flags */\n"
9962 msgstr ""
9963
9964 #. type: Plain text
9965 #: build/C/man2/quotactl.2:249
9966 #, no-wrap
9967 msgid "/* Quota format QFMT_VFS_OLD */\n"
9968 msgstr ""
9969
9970 #. type: Plain text
9971 #: build/C/man2/quotactl.2:251
9972 #, no-wrap
9973 msgid "#define V1_DQF_RSQUASH\t1   /* Root squash enabled */\n"
9974 msgstr ""
9975
9976 #. type: Plain text
9977 #: build/C/man2/quotactl.2:253
9978 #, no-wrap
9979 msgid "/* Other quota formats have no dqi_flags bits defined */\n"
9980 msgstr ""
9981
9982 #. type: Plain text
9983 #: build/C/man2/quotactl.2:256
9984 #, no-wrap
9985 msgid ""
9986 "/* Flags in dqi_valid that indicate which fields in\n"
9987 "   dqinfo structure are valid. */\n"
9988 msgstr ""
9989
9990 #. type: Plain text
9991 #: build/C/man2/quotactl.2:261
9992 #, no-wrap
9993 msgid ""
9994 "# define IIF_BGRACE\t1\n"
9995 "# define IIF_IGRACE\t2\n"
9996 "# define IIF_FLAGS\t4\n"
9997 "# define IIF_ALL        (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)\n"
9998 msgstr ""
9999
10000 #. type: Plain text
10001 #: build/C/man2/quotactl.2:277
10002 msgid ""
10003 "The I<dqi_valid> field in the I<dqinfo> structure indicates the entries in "
10004 "the structure that are valid.  Currently, the kernel fills in all entries of "
10005 "the I<dqinfo> structure and marks them all as valid in the I<dqi_valid> "
10006 "field.  The I<id> argument is ignored."
10007 msgstr ""
10008
10009 #. type: TP
10010 #: build/C/man2/quotactl.2:277
10011 #, no-wrap
10012 msgid "B<Q_SETINFO>"
10013 msgstr ""
10014
10015 #. type: Plain text
10016 #: build/C/man2/quotactl.2:301
10017 msgid ""
10018 "Set information about quotafile.  The I<addr> argument should be a pointer "
10019 "to a I<dqinfo> structure.  The I<dqi_valid> field of the I<dqinfo> structure "
10020 "indicates the entries in the structure that have been set by the caller.  "
10021 "This operation supersedes the B<Q_SETGRACE> and B<Q_SETFLAGS> operations in "
10022 "the previous quota interfaces.  The I<id> argument is ignored.  This "
10023 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10024 msgstr ""
10025
10026 #. type: TP
10027 #: build/C/man2/quotactl.2:301
10028 #, no-wrap
10029 msgid "B<Q_GETFMT>"
10030 msgstr ""
10031
10032 #. type: Plain text
10033 #: build/C/man2/quotactl.2:308
10034 msgid ""
10035 "Get quota format used on the specified filesystem.  The I<addr> argument "
10036 "should be a pointer to a 4-byte buffer where the format number will be "
10037 "stored."
10038 msgstr ""
10039
10040 #. type: TP
10041 #: build/C/man2/quotactl.2:308
10042 #, no-wrap
10043 msgid "B<Q_SYNC>"
10044 msgstr ""
10045
10046 #. type: Plain text
10047 #: build/C/man2/quotactl.2:319
10048 msgid ""
10049 "Update the on-disk copy of quota usages for a filesystem.  If I<special> is "
10050 "NULL, then all filesystems with active quotas are sync'ed.  The I<addr> and "
10051 "I<id> arguments are ignored."
10052 msgstr ""
10053
10054 #. type: TP
10055 #: build/C/man2/quotactl.2:319
10056 #, no-wrap
10057 msgid "B<Q_GETSTATS>"
10058 msgstr ""
10059
10060 #.  Q_GETSTATS was removed in kernel 2.4.22.
10061 #. type: Plain text
10062 #: build/C/man2/quotactl.2:339
10063 msgid ""
10064 "Get statistics and other generic information about the quota subsystem.  The "
10065 "I<addr> argument should be a pointer to a I<dqstats> structure in which data "
10066 "should be stored.  This structure is defined in I<E<lt>sys/quota.hE<gt>>.  "
10067 "The I<special> and I<id> arguments are ignored.  This operation is obsolete "
10068 "and not supported by recent kernels.  Files in I</proc/sys/fs/quota/> carry "
10069 "the information instead."
10070 msgstr ""
10071
10072 #. type: Plain text
10073 #: build/C/man2/quotactl.2:342
10074 msgid ""
10075 "For XFS filesystems making use of the XFS Quota Manager (XQM), the above "
10076 "commands are bypassed and the following commands are used:"
10077 msgstr ""
10078
10079 #. type: TP
10080 #: build/C/man2/quotactl.2:342
10081 #, no-wrap
10082 msgid "B<Q_XQUOTAON>"
10083 msgstr ""
10084
10085 #. type: Plain text
10086 #: build/C/man2/quotactl.2:363
10087 msgid ""
10088 "Turn on quotas for an XFS filesystem.  XFS provides the ability to turn "
10089 "on/off quota limit enforcement with quota accounting.  Therefore, XFS "
10090 "expects I<addr> to be a pointer to an I<unsigned int> that contains either "
10091 "the flags B<XFS_QUOTA_UDQ_ACCT> and/or B<XFS_QUOTA_UDQ_ENFD> (for user "
10092 "quota), or B<XFS_QUOTA_GDQ_ACCT> and/or B<XFS_QUOTA_GDQ_ENFD> (for group "
10093 "quota), as defined in I<E<lt>xfs/xqm.hE<gt>>.  This operation requires "
10094 "privilege (B<CAP_SYS_ADMIN>)."
10095 msgstr ""
10096
10097 #. type: TP
10098 #: build/C/man2/quotactl.2:363
10099 #, no-wrap
10100 msgid "B<Q_XQUOTAOFF>"
10101 msgstr ""
10102
10103 #. type: Plain text
10104 #: build/C/man2/quotactl.2:374
10105 msgid ""
10106 "Turn off quotas for an XFS filesystem.  As with B<Q_QUOTAON>, XFS "
10107 "filesystems expect a pointer to an I<unsigned int> that specifies whether "
10108 "quota accounting and/or limit enforcement need to be turned off.  This "
10109 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10110 msgstr ""
10111
10112 #. type: TP
10113 #: build/C/man2/quotactl.2:374
10114 #, no-wrap
10115 msgid "B<Q_XGETQUOTA>"
10116 msgstr ""
10117
10118 #. type: Plain text
10119 #: build/C/man2/quotactl.2:388
10120 msgid ""
10121 "Get disk quota limits and current usage for user I<id>.  The I<addr> "
10122 "argument is a pointer to an I<fs_disk_quota> structure (defined in "
10123 "I<E<lt>xfs/xqm.hE<gt>>).  Unprivileged users may retrieve only their own "
10124 "quotas; a privileged user (B<CAP_SYS_ADMIN>)  may retrieve the quotas of any "
10125 "user."
10126 msgstr ""
10127
10128 #. type: TP
10129 #: build/C/man2/quotactl.2:388
10130 #, no-wrap
10131 msgid "B<Q_XSETQLIM>"
10132 msgstr ""
10133
10134 #. type: Plain text
10135 #: build/C/man2/quotactl.2:400
10136 msgid ""
10137 "Set disk quota limits for user I<id>.  The I<addr> argument is a pointer to "
10138 "an I<fs_disk_quota> structure (defined in I<E<lt>xfs/xqm.hE<gt>>).  This "
10139 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10140 msgstr ""
10141
10142 #. type: TP
10143 #: build/C/man2/quotactl.2:400
10144 #, no-wrap
10145 msgid "B<Q_XGETQSTAT>"
10146 msgstr ""
10147
10148 #. type: Plain text
10149 #: build/C/man2/quotactl.2:408
10150 msgid ""
10151 "Returns an I<fs_quota_stat> structure containing XFS filesystem-specific "
10152 "quota information.  This is useful for finding out how much space is used to "
10153 "store quota information, and also to get quotaon/off status of a given local "
10154 "XFS filesystem."
10155 msgstr ""
10156
10157 #. type: TP
10158 #: build/C/man2/quotactl.2:408
10159 #, no-wrap
10160 msgid "B<Q_XQUOTARM>"
10161 msgstr ""
10162
10163 #. type: Plain text
10164 #: build/C/man2/quotactl.2:412
10165 msgid ""
10166 "Free the disk space taken by disk quotas.  Quotas must have already been "
10167 "turned off."
10168 msgstr ""
10169
10170 #. type: Plain text
10171 #: build/C/man2/quotactl.2:419
10172 msgid ""
10173 "There is no command equivalent to B<Q_SYNC> for XFS since B<sync>(1)  writes "
10174 "quota information to disk (in addition to the other filesystem metadata that "
10175 "it writes out)."
10176 msgstr ""
10177
10178 #. type: Plain text
10179 #: build/C/man2/quotactl.2:427
10180 msgid ""
10181 "On success, B<quotactl>()  returns 0; on error -1 is returned, and I<errno> "
10182 "is set to indicate the error."
10183 msgstr ""
10184
10185 #. type: Plain text
10186 #: build/C/man2/quotactl.2:434
10187 msgid "I<addr> or I<special> is invalid."
10188 msgstr ""
10189
10190 #. type: Plain text
10191 #: build/C/man2/quotactl.2:440
10192 msgid "I<cmd> or I<type> is invalid."
10193 msgstr ""
10194
10195 #. type: Plain text
10196 #: build/C/man2/quotactl.2:447
10197 msgid "The file specified by I<special> or I<addr> does not exist."
10198 msgstr ""
10199
10200 #. type: Plain text
10201 #: build/C/man2/quotactl.2:452
10202 msgid "The kernel has not been compiled with the B<CONFIG_QUOTA> option."
10203 msgstr ""
10204
10205 #. type: TP
10206 #: build/C/man2/quotactl.2:452
10207 #, no-wrap
10208 msgid "B<ENOTBLK>"
10209 msgstr ""
10210
10211 #. type: Plain text
10212 #: build/C/man2/quotactl.2:456
10213 msgid "I<special> is not a block device."
10214 msgstr ""
10215
10216 #. type: Plain text
10217 #: build/C/man2/quotactl.2:461
10218 msgid ""
10219 "The caller lacked the required privilege (B<CAP_SYS_ADMIN>)  for the "
10220 "specified operation."
10221 msgstr ""
10222
10223 #. type: Plain text
10224 #: build/C/man2/quotactl.2:465
10225 msgid ""
10226 "No disk quota is found for the indicated user.  Quotas have not been turned "
10227 "on for this filesystem."
10228 msgstr ""
10229
10230 #. type: Plain text
10231 #: build/C/man2/quotactl.2:474
10232 msgid "If I<cmd> is B<Q_SETQUOTA>, B<quotactl>()  may also set I<errno> to:"
10233 msgstr ""
10234
10235 #. type: Plain text
10236 #: build/C/man2/quotactl.2:477
10237 msgid "Specified limits are out of range allowed by quota format."
10238 msgstr ""
10239
10240 #. type: Plain text
10241 #: build/C/man2/quotactl.2:486
10242 msgid "If I<cmd> is B<Q_QUOTAON>, B<quotactl>()  may also set I<errno> to:"
10243 msgstr ""
10244
10245 #. type: Plain text
10246 #: build/C/man2/quotactl.2:495
10247 msgid ""
10248 "The quota file pointed to by I<addr> exists, but is not a regular file; or, "
10249 "the quota file pointed to by I<addr> exists, but is not on the filesystem "
10250 "pointed to by I<special>."
10251 msgstr ""
10252
10253 #. type: Plain text
10254 #: build/C/man2/quotactl.2:501
10255 msgid "B<Q_QUOTAON> attempted, but another B<Q_QUOTAON> had already been performed."
10256 msgstr ""
10257
10258 #. type: Plain text
10259 #: build/C/man2/quotactl.2:504
10260 msgid "The quota file is corrupted."
10261 msgstr ""
10262
10263 #. type: Plain text
10264 #: build/C/man2/quotactl.2:507
10265 msgid "Specified quota format was not found."
10266 msgstr ""
10267
10268 #. type: Plain text
10269 #: build/C/man2/quotactl.2:512
10270 msgid "B<quota>(1), B<getrlimit>(2), B<quotacheck>(8), B<quotaon>(8)"
10271 msgstr ""
10272
10273 #. type: TH
10274 #: build/C/man2/sendfile.2:19
10275 #, no-wrap
10276 msgid "SENDFILE"
10277 msgstr ""
10278
10279 #. type: TH
10280 #: build/C/man2/sendfile.2:19
10281 #, no-wrap
10282 msgid "2011-09-14"
10283 msgstr ""
10284
10285 #. type: Plain text
10286 #: build/C/man2/sendfile.2:22
10287 msgid "sendfile - transfer data between file descriptors"
10288 msgstr ""
10289
10290 #. type: Plain text
10291 #: build/C/man2/sendfile.2:24
10292 msgid "B<#include E<lt>sys/sendfile.hE<gt>>"
10293 msgstr ""
10294
10295 #.  The below is too ugly. Comments about glibc versions belong
10296 #.  in the notes, not in the header.
10297 #
10298 #.  .B #include <features.h>
10299 #.  .br
10300 #.  .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
10301 #.  .br
10302 #.  .B #include <sys/sendfile.h>
10303 #.  .br
10304 #.  #else
10305 #.  .br
10306 #.  .B #include <sys/types.h>
10307 #.  .br
10308 #.  .B /* No system prototype before glibc 2.1. */
10309 #.  .br
10310 #.  .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
10311 #.                        offset ", size_t" " count" )
10312 #.  .br
10313 #.  .B #endif
10314 #. type: Plain text
10315 #: build/C/man2/sendfile.2:47
10316 msgid ""
10317 "B<ssize_t sendfile(int>I< out_fd>B<, int>I< in_fd>B<, off_t *>I<offset>B<, "
10318 "size_t>I< count>B<);>"
10319 msgstr ""
10320
10321 #. type: Plain text
10322 #: build/C/man2/sendfile.2:57
10323 msgid ""
10324 "B<sendfile>()  copies data between one file descriptor and another.  Because "
10325 "this copying is done within the kernel, B<sendfile>()  is more efficient "
10326 "than the combination of B<read>(2)  and B<write>(2), which would require "
10327 "transferring data to and from user space."
10328 msgstr ""
10329
10330 #. type: Plain text
10331 #: build/C/man2/sendfile.2:62
10332 msgid ""
10333 "I<in_fd> should be a file descriptor opened for reading and I<out_fd> should "
10334 "be a descriptor opened for writing."
10335 msgstr ""
10336
10337 #. type: Plain text
10338 #: build/C/man2/sendfile.2:83
10339 msgid ""
10340 "If I<offset> is not NULL, then it points to a variable holding the file "
10341 "offset from which B<sendfile>()  will start reading data from I<in_fd>.  "
10342 "When B<sendfile>()  returns, this variable will be set to the offset of the "
10343 "byte following the last byte that was read.  If I<offset> is not NULL, then "
10344 "B<sendfile>()  does not modify the current file offset of I<in_fd>; "
10345 "otherwise the current file offset is adjusted to reflect the number of bytes "
10346 "read from I<in_fd>."
10347 msgstr ""
10348
10349 #. type: Plain text
10350 #: build/C/man2/sendfile.2:90
10351 msgid ""
10352 "If I<offset> is NULL, then data will be read from I<in_fd> starting at the "
10353 "current file offset, and the file offset will be updated by the call."
10354 msgstr ""
10355
10356 #. type: Plain text
10357 #: build/C/man2/sendfile.2:93
10358 msgid "I<count> is the number of bytes to copy between the file descriptors."
10359 msgstr ""
10360
10361 #. type: Plain text
10362 #: build/C/man2/sendfile.2:100
10363 msgid ""
10364 "The I<in_fd> argument must correspond to a file which supports "
10365 "B<mmap>(2)-like operations (i.e., it cannot be a socket)."
10366 msgstr ""
10367
10368 #. type: Plain text
10369 #: build/C/man2/sendfile.2:108
10370 msgid ""
10371 "In Linux kernels before 2.6.33, I<out_fd> must refer to a socket.  Since "
10372 "Linux 2.6.33 it can be any file.  If it is a regular file, then "
10373 "B<sendfile>()  changes the file offset appropriately."
10374 msgstr ""
10375
10376 #. type: Plain text
10377 #: build/C/man2/sendfile.2:115
10378 msgid ""
10379 "If the transfer was successful, the number of bytes written to I<out_fd> is "
10380 "returned.  On error, -1 is returned, and I<errno> is set appropriately."
10381 msgstr ""
10382
10383 #. type: Plain text
10384 #: build/C/man2/sendfile.2:121
10385 msgid ""
10386 "Nonblocking I/O has been selected using B<O_NONBLOCK> and the write would "
10387 "block."
10388 msgstr ""
10389
10390 #. type: Plain text
10391 #: build/C/man2/sendfile.2:125
10392 msgid ""
10393 "The input file was not opened for reading or the output file was not opened "
10394 "for writing."
10395 msgstr ""
10396
10397 #. type: Plain text
10398 #: build/C/man2/sendfile.2:128
10399 msgid "Bad address."
10400 msgstr ""
10401
10402 #. type: Plain text
10403 #: build/C/man2/sendfile.2:134
10404 msgid ""
10405 "Descriptor is not valid or locked, or an B<mmap>(2)-like operation is not "
10406 "available for I<in_fd>."
10407 msgstr ""
10408
10409 #. type: Plain text
10410 #: build/C/man2/sendfile.2:138
10411 msgid "Unspecified error while reading from I<in_fd>."
10412 msgstr ""
10413
10414 #. type: Plain text
10415 #: build/C/man2/sendfile.2:142
10416 msgid "Insufficient memory to read from I<in_fd>."
10417 msgstr ""
10418
10419 #. type: Plain text
10420 #: build/C/man2/sendfile.2:148
10421 msgid ""
10422 "B<sendfile>()  is a new feature in Linux 2.2.  The include file "
10423 "I<E<lt>sys/sendfile.hE<gt>> is present since glibc 2.1."
10424 msgstr ""
10425
10426 #. type: Plain text
10427 #: build/C/man2/sendfile.2:150
10428 msgid "Not specified in POSIX.1-2001, or other standards."
10429 msgstr ""
10430
10431 #. type: Plain text
10432 #: build/C/man2/sendfile.2:155
10433 msgid ""
10434 "Other UNIX systems implement B<sendfile>()  with different semantics and "
10435 "prototypes.  It should not be used in portable programs."
10436 msgstr ""
10437
10438 #. type: Plain text
10439 #: build/C/man2/sendfile.2:165
10440 msgid ""
10441 "If you plan to use B<sendfile>()  for sending files to a TCP socket, but "
10442 "need to send some header data in front of the file contents, you will find "
10443 "it useful to employ the B<TCP_CORK> option, described in B<tcp>(7), to "
10444 "minimize the number of packets and to tune performance."
10445 msgstr ""
10446
10447 #. type: Plain text
10448 #: build/C/man2/sendfile.2:171
10449 msgid ""
10450 "In Linux 2.4 and earlier, I<out_fd> could also refer to a regular file, and "
10451 "B<sendfile>()  changed the current offset of that file."
10452 msgstr ""
10453
10454 #. type: Plain text
10455 #: build/C/man2/sendfile.2:183
10456 msgid ""
10457 "The original Linux B<sendfile>()  system call was not designed to handle "
10458 "large file offsets.  Consequently, Linux 2.4 added B<sendfile64>(), with a "
10459 "wider type for the I<offset> argument.  The glibc B<sendfile>()  wrapper "
10460 "function transparently deals with the kernel differences."
10461 msgstr ""
10462
10463 #. type: Plain text
10464 #: build/C/man2/sendfile.2:192
10465 msgid ""
10466 "Applications may wish to fall back to B<read>(2)/B<write>(2)  in the case "
10467 "where B<sendfile>()  fails with B<EINVAL> or B<ENOSYS>."
10468 msgstr ""
10469
10470 #. type: Plain text
10471 #: build/C/man2/sendfile.2:197
10472 msgid ""
10473 "The Linux-specific B<splice>(2)  call supports transferring data between "
10474 "arbitrary files (e.g., a pair of sockets)."
10475 msgstr ""
10476
10477 #. type: Plain text
10478 #: build/C/man2/sendfile.2:202
10479 msgid "B<mmap>(2), B<open>(2), B<socket>(2), B<splice>(2)"
10480 msgstr ""
10481
10482 #. type: TH
10483 #: build/C/man2/set_tid_address.2:25
10484 #, no-wrap
10485 msgid "SET_TID_ADDRESS"
10486 msgstr ""
10487
10488 #. type: TH
10489 #: build/C/man2/set_tid_address.2:25
10490 #, no-wrap
10491 msgid "2012-07-19"
10492 msgstr ""
10493
10494 #. type: Plain text
10495 #: build/C/man2/set_tid_address.2:28
10496 msgid "set_tid_address - set pointer to thread ID"
10497 msgstr ""
10498
10499 #. type: Plain text
10500 #: build/C/man2/set_tid_address.2:31
10501 #, no-wrap
10502 msgid "B<#include E<lt>linux/unistd.hE<gt>>\n"
10503 msgstr ""
10504
10505 #. type: Plain text
10506 #: build/C/man2/set_tid_address.2:33
10507 #, no-wrap
10508 msgid "B<long set_tid_address(int *>I<tidptr>B<);>\n"
10509 msgstr ""
10510
10511 #. type: Plain text
10512 #: build/C/man2/set_tid_address.2:40
10513 msgid ""
10514 "For each process, the kernel maintains two attributes (addresses) called "
10515 "I<set_child_tid> and I<clear_child_tid>.  These two attributes contain the "
10516 "value NULL by default."
10517 msgstr ""
10518
10519 #. type: TP
10520 #: build/C/man2/set_tid_address.2:40
10521 #, no-wrap
10522 msgid "I<set_child_tid>"
10523 msgstr ""
10524
10525 #. type: Plain text
10526 #: build/C/man2/set_tid_address.2:51
10527 msgid ""
10528 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_SETTID> "
10529 "flag, I<set_child_tid> is set to the value passed in the I<ctid> argument of "
10530 "that system call."
10531 msgstr ""
10532
10533 #. type: Plain text
10534 #: build/C/man2/set_tid_address.2:56
10535 msgid ""
10536 "When I<set_child_tid> is set, the very first thing the new process does is "
10537 "writing its PID at this address."
10538 msgstr ""
10539
10540 #. type: TP
10541 #: build/C/man2/set_tid_address.2:56
10542 #, no-wrap
10543 msgid "I<clear_child_tid>"
10544 msgstr ""
10545
10546 #. type: Plain text
10547 #: build/C/man2/set_tid_address.2:67
10548 msgid ""
10549 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_CLEARTID> "
10550 "flag, I<clear_child_tid> is set to the value passed in the I<ctid> argument "
10551 "of that system call."
10552 msgstr ""
10553
10554 #. type: Plain text
10555 #: build/C/man2/set_tid_address.2:74
10556 msgid ""
10557 "The system call B<set_tid_address>()  sets the I<clear_child_tid> value for "
10558 "the calling process to I<tidptr>."
10559 msgstr ""
10560
10561 #. type: Plain text
10562 #: build/C/man2/set_tid_address.2:82
10563 msgid ""
10564 "When a process whose I<clear_child_tid> is not NULL terminates, then, if the "
10565 "process is sharing memory with other processes or threads, then 0 is written "
10566 "at the address specified in I<clear_child_tid> and the kernel performs the "
10567 "following operation:"
10568 msgstr ""
10569
10570 #. type: Plain text
10571 #: build/C/man2/set_tid_address.2:84
10572 #, no-wrap
10573 msgid "    futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);\n"
10574 msgstr ""
10575
10576 #. type: Plain text
10577 #: build/C/man2/set_tid_address.2:88
10578 msgid ""
10579 "The effect of this operation is to wake a single process that is performing "
10580 "a futex wait on the memory location.  Errors from the futex wake operation "
10581 "are ignored."
10582 msgstr ""
10583
10584 #. type: Plain text
10585 #: build/C/man2/set_tid_address.2:91
10586 msgid "B<set_tid_address>()  always returns the PID of the calling process."
10587 msgstr ""
10588
10589 #. type: Plain text
10590 #: build/C/man2/set_tid_address.2:94
10591 msgid "B<set_tid_address>()  always succeeds."
10592 msgstr ""
10593
10594 #. type: Plain text
10595 #: build/C/man2/set_tid_address.2:97
10596 msgid ""
10597 "This call is present since Linux 2.5.48.  Details as given here are valid "
10598 "since Linux 2.5.49."
10599 msgstr ""
10600
10601 #. type: Plain text
10602 #: build/C/man2/set_tid_address.2:102
10603 msgid "B<clone>(2), B<futex>(2)"
10604 msgstr ""
10605
10606 #. type: TH
10607 #: build/C/man2/splice.2:26
10608 #, no-wrap
10609 msgid "SPLICE"
10610 msgstr ""
10611
10612 #. type: TH
10613 #: build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vmsplice.2:26
10614 #, no-wrap
10615 msgid "2012-05-04"
10616 msgstr ""
10617
10618 #. type: Plain text
10619 #: build/C/man2/splice.2:29
10620 msgid "splice - splice data to/from a pipe"
10621 msgstr ""
10622
10623 #. type: Plain text
10624 #: build/C/man2/splice.2:33 build/C/man2/tee.2:33
10625 #, no-wrap
10626 msgid ""
10627 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
10628 "B<#include E<lt>fcntl.hE<gt>>\n"
10629 msgstr ""
10630
10631 #.  Return type was long before glibc 2.7
10632 #. type: Plain text
10633 #: build/C/man2/splice.2:38
10634 #, no-wrap
10635 msgid ""
10636 "B<ssize_t splice(int >I<fd_in>B<, loff_t *>I<off_in>B<, int >I<fd_out>B<,>\n"
10637 "B<               loff_t *>I<off_out>B<, size_t >I<len>B<, unsigned int "
10638 ">I<flags>B<);>\n"
10639 msgstr ""
10640
10641 #. type: Plain text
10642 #: build/C/man2/splice.2:50
10643 msgid ""
10644 "B<splice>()  moves data between two file descriptors without copying between "
10645 "kernel address space and user address space.  It transfers up to I<len> "
10646 "bytes of data from the file descriptor I<fd_in> to the file descriptor "
10647 "I<fd_out>, where one of the descriptors must refer to a pipe."
10648 msgstr ""
10649
10650 #. type: Plain text
10651 #: build/C/man2/splice.2:80
10652 msgid ""
10653 "If I<fd_in> refers to a pipe, then I<off_in> must be NULL.  If I<fd_in> does "
10654 "not refer to a pipe and I<off_in> is NULL, then bytes are read from I<fd_in> "
10655 "starting from the current file offset, and the current file offset is "
10656 "adjusted appropriately.  If I<fd_in> does not refer to a pipe and I<off_in> "
10657 "is not NULL, then I<off_in> must point to a buffer which specifies the "
10658 "starting offset from which bytes will be read from I<fd_in>; in this case, "
10659 "the current file offset of I<fd_in> is not changed.  Analogous statements "
10660 "apply for I<fd_out> and I<off_out>."
10661 msgstr ""
10662
10663 #. type: Plain text
10664 #: build/C/man2/splice.2:85 build/C/man2/vmsplice.2:78
10665 msgid ""
10666 "The I<flags> argument is a bit mask that is composed by ORing together zero "
10667 "or more of the following values:"
10668 msgstr ""
10669
10670 #. type: TP
10671 #: build/C/man2/splice.2:85 build/C/man2/tee.2:62 build/C/man2/vmsplice.2:78
10672 #, no-wrap
10673 msgid "B<SPLICE_F_MOVE>"
10674 msgstr ""
10675
10676 #. type: Plain text
10677 #: build/C/man2/splice.2:98
10678 msgid ""
10679 "Attempt to move pages instead of copying.  This is only a hint to the "
10680 "kernel: pages may still be copied if the kernel cannot move the pages from "
10681 "the pipe, or if the pipe buffers don't refer to full pages.  The initial "
10682 "implementation of this flag was buggy: therefore starting in Linux 2.6.21 it "
10683 "is a no-op (but is still permitted in a B<splice>()  call); in the future, a "
10684 "correct implementation may be restored."
10685 msgstr ""
10686
10687 #. type: TP
10688 #: build/C/man2/splice.2:98 build/C/man2/tee.2:68 build/C/man2/vmsplice.2:84
10689 #, no-wrap
10690 msgid "B<SPLICE_F_NONBLOCK>"
10691 msgstr ""
10692
10693 #. type: Plain text
10694 #: build/C/man2/splice.2:107
10695 msgid ""
10696 "Do not block on I/O.  This makes the splice pipe operations nonblocking, but "
10697 "B<splice>()  may nevertheless block because the file descriptors that are "
10698 "spliced to/from may block (unless they have the B<O_NONBLOCK> flag set)."
10699 msgstr ""
10700
10701 #. type: TP
10702 #: build/C/man2/splice.2:107 build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10703 #, no-wrap
10704 msgid "B<SPLICE_F_MORE>"
10705 msgstr ""
10706
10707 #. type: Plain text
10708 #: build/C/man2/splice.2:121
10709 msgid ""
10710 "More data will be coming in a subsequent splice.  This is a helpful hint "
10711 "when the I<fd_out> refers to a socket (see also the description of "
10712 "B<MSG_MORE> in B<send>(2), and the description of B<TCP_CORK> in B<tcp>(7))"
10713 msgstr ""
10714
10715 #. type: TP
10716 #: build/C/man2/splice.2:121 build/C/man2/tee.2:79 build/C/man2/vmsplice.2:97
10717 #, no-wrap
10718 msgid "B<SPLICE_F_GIFT>"
10719 msgstr ""
10720
10721 #. type: Plain text
10722 #: build/C/man2/splice.2:127
10723 msgid "Unused for B<splice>(); see B<vmsplice>(2)."
10724 msgstr ""
10725
10726 #. type: Plain text
10727 #: build/C/man2/splice.2:136
10728 msgid ""
10729 "Upon successful completion, B<splice>()  returns the number of bytes spliced "
10730 "to or from the pipe.  A return value of 0 means that there was no data to "
10731 "transfer, and it would not make sense to block, because there are no writers "
10732 "connected to the write end of the pipe referred to by I<fd_in>."
10733 msgstr ""
10734
10735 #. type: Plain text
10736 #: build/C/man2/splice.2:142
10737 msgid "On error, B<splice>()  returns -1 and I<errno> is set to indicate the error."
10738 msgstr ""
10739
10740 #. type: Plain text
10741 #: build/C/man2/splice.2:147
10742 msgid ""
10743 "One or both file descriptors are not valid, or do not have proper read-write "
10744 "mode."
10745 msgstr ""
10746
10747 #.  The append-mode error is given since 2.6.27; in earlier kernels,
10748 #.  splice() in append mode was broken
10749 #. type: Plain text
10750 #: build/C/man2/splice.2:155
10751 msgid ""
10752 "Target filesystem doesn't support splicing; target file is opened in append "
10753 "mode; neither of the descriptors refers to a pipe; or offset given for "
10754 "nonseekable device."
10755 msgstr ""
10756
10757 #. type: Plain text
10758 #: build/C/man2/splice.2:158 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
10759 msgid "Out of memory."
10760 msgstr ""
10761
10762 #. type: TP
10763 #: build/C/man2/splice.2:158
10764 #, no-wrap
10765 msgid "B<ESPIPE>"
10766 msgstr ""
10767
10768 #. type: Plain text
10769 #: build/C/man2/splice.2:165
10770 msgid ""
10771 "Either I<off_in> or I<off_out> was not NULL, but the corresponding file "
10772 "descriptor refers to a pipe."
10773 msgstr ""
10774
10775 #. type: Plain text
10776 #: build/C/man2/splice.2:170
10777 msgid ""
10778 "The B<splice>()  system call first appeared in Linux 2.6.17; library support "
10779 "was added to glibc in version 2.5."
10780 msgstr ""
10781
10782 #. type: Plain text
10783 #: build/C/man2/splice.2:182
10784 msgid ""
10785 "The three system calls B<splice>(), B<vmsplice>(2), and B<tee>(2), provide "
10786 "user-space programs with full control over an arbitrary kernel buffer, "
10787 "implemented within the kernel using the same type of buffer that is used for "
10788 "a pipe.  In overview, these system calls perform the following tasks:"
10789 msgstr ""
10790
10791 #. type: TP
10792 #: build/C/man2/splice.2:182
10793 #, no-wrap
10794 msgid "B<splice>()"
10795 msgstr ""
10796
10797 #. type: Plain text
10798 #: build/C/man2/splice.2:186
10799 msgid ""
10800 "moves data from the buffer to an arbitrary file descriptor, or vice versa, "
10801 "or from one buffer to another."
10802 msgstr ""
10803
10804 #. type: TP
10805 #: build/C/man2/splice.2:186
10806 #, no-wrap
10807 msgid "B<tee>(2)"
10808 msgstr ""
10809
10810 #. type: Plain text
10811 #: build/C/man2/splice.2:189
10812 msgid "\"copies\" the data from one buffer to another."
10813 msgstr ""
10814
10815 #. type: TP
10816 #: build/C/man2/splice.2:189
10817 #, no-wrap
10818 msgid "B<vmsplice>(2)"
10819 msgstr ""
10820
10821 #. type: Plain text
10822 #: build/C/man2/splice.2:192
10823 msgid "\"copies\" data from user space into the buffer."
10824 msgstr ""
10825
10826 #
10827 #.  Linus: Now, imagine using the above in a media server, for example.
10828 #.  Let's say that a year or two has passed, so that the video drivers
10829 #.  have been updated to be able to do the splice thing, and what can
10830 #.  you do? You can:
10831 #
10832 #.  - splice from the (mpeg or whatever - let's just assume that the video
10833 #.    input is either digital or does the encoding on its own - like they
10834 #.    pretty much all do) video input into a pipe (remember: no copies - the
10835 #.    video input will just DMA directly into memory, and splice will just
10836 #.    set up the pages in the pipe buffer)
10837 #.  - tee that pipe to split it up
10838 #.  - splice one end to a file (ie "save the compressed stream to disk")
10839 #.  - splice the other end to a real-time video decoder window for your
10840 #.    real-time viewing pleasure.
10841 #
10842 #.  Linus: Now, the advantage of splice()/tee() is that you can
10843 #.  do zero-copy movement of data, and unlike sendfile() you can
10844 #.  do it on _arbitrary_ data (and, as shown by "tee()", it's more
10845 #.  than just sending the data to somebody else: you can duplicate
10846 #.  the data and choose to forward it to two or more different
10847 #.  users - for things like logging etc.).
10848 #. type: Plain text
10849 #: build/C/man2/splice.2:223
10850 msgid ""
10851 "Though we talk of copying, actual copies are generally avoided.  The kernel "
10852 "does this by implementing a pipe buffer as a set of reference-counted "
10853 "pointers to pages of kernel memory.  The kernel creates \"copies\" of pages "
10854 "in a buffer by creating new pointers (for the output buffer) referring to "
10855 "the pages, and increasing the reference counts for the pages: only pointers "
10856 "are copied, not the pages of the buffer."
10857 msgstr ""
10858
10859 #. type: Plain text
10860 #: build/C/man2/splice.2:226
10861 msgid "See B<tee>(2)."
10862 msgstr ""
10863
10864 #. type: Plain text
10865 #: build/C/man2/splice.2:230
10866 msgid "B<sendfile>(2), B<tee>(2), B<vmsplice>(2)"
10867 msgstr ""
10868
10869 #. type: TH
10870 #: build/C/man2/tee.2:26
10871 #, no-wrap
10872 msgid "TEE"
10873 msgstr ""
10874
10875 #. type: Plain text
10876 #: build/C/man2/tee.2:29
10877 msgid "tee - duplicating pipe content"
10878 msgstr ""
10879
10880 #. type: Plain text
10881 #: build/C/man2/tee.2:36
10882 #, no-wrap
10883 msgid ""
10884 "B<ssize_t tee(int >I<fd_in>B<, int >I<fd_out>B<, size_t >I<len>B<, unsigned "
10885 "int >I<flags>B<);>\n"
10886 msgstr ""
10887
10888 #.  Example programs http://brick.kernel.dk/snaps
10889 #
10890 #
10891 #.  add a "tee(in, out1, out2)" system call that duplicates the pages
10892 #.  (again, incrementing their reference count, not copying the data) from
10893 #.  one pipe to two other pipes.
10894 #. type: Plain text
10895 #: build/C/man2/tee.2:56
10896 msgid ""
10897 "B<tee>()  duplicates up to I<len> bytes of data from the pipe referred to by "
10898 "the file descriptor I<fd_in> to the pipe referred to by the file descriptor "
10899 "I<fd_out>.  It does not consume the data that is duplicated from I<fd_in>; "
10900 "therefore, that data can be copied by a subsequent B<splice>(2)."
10901 msgstr ""
10902
10903 #. type: Plain text
10904 #: build/C/man2/tee.2:62
10905 msgid ""
10906 "I<flags> is a series of modifier flags, which share the name space with "
10907 "B<splice>(2)  and B<vmsplice>(2):"
10908 msgstr ""
10909
10910 #. type: Plain text
10911 #: build/C/man2/tee.2:68
10912 msgid "Currently has no effect for B<tee>(); see B<splice>(2)."
10913 msgstr ""
10914
10915 #.  Not used for vmsplice
10916 #.  May be in the future -- therefore EAGAIN
10917 #. type: Plain text
10918 #: build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10919 msgid "Do not block on I/O; see B<splice>(2)  for further details."
10920 msgstr ""
10921
10922 #. type: Plain text
10923 #: build/C/man2/tee.2:79
10924 msgid ""
10925 "Currently has no effect for B<tee>(), but may be implemented in the future; "
10926 "see B<splice>(2)."
10927 msgstr ""
10928
10929 #. type: Plain text
10930 #: build/C/man2/tee.2:85
10931 msgid "Unused for B<tee>(); see B<vmsplice>(2)."
10932 msgstr ""
10933
10934 #. type: Plain text
10935 #: build/C/man2/tee.2:94
10936 msgid ""
10937 "Upon successful completion, B<tee>()  returns the number of bytes that were "
10938 "duplicated between the input and output.  A return value of 0 means that "
10939 "there was no data to transfer, and it would not make sense to block, because "
10940 "there are no writers connected to the write end of the pipe referred to by "
10941 "I<fd_in>."
10942 msgstr ""
10943
10944 #. type: Plain text
10945 #: build/C/man2/tee.2:100
10946 msgid "On error, B<tee>()  returns -1 and I<errno> is set to indicate the error."
10947 msgstr ""
10948
10949 #. type: Plain text
10950 #: build/C/man2/tee.2:111
10951 msgid ""
10952 "I<fd_in> or I<fd_out> does not refer to a pipe; or I<fd_in> and I<fd_out> "
10953 "refer to the same pipe."
10954 msgstr ""
10955
10956 #. type: Plain text
10957 #: build/C/man2/tee.2:119
10958 msgid ""
10959 "The B<tee>()  system call first appeared in Linux 2.6.17; library support "
10960 "was added to glibc in version 2.5."
10961 msgstr ""
10962
10963 #. type: Plain text
10964 #: build/C/man2/tee.2:130
10965 msgid ""
10966 "Conceptually, B<tee>()  copies the data between the two pipes.  In reality "
10967 "no real data copying takes place though: under the covers, B<tee>()  assigns "
10968 "data in the output by merely grabbing a reference to the input."
10969 msgstr ""
10970
10971 #. type: Plain text
10972 #: build/C/man2/tee.2:136
10973 msgid ""
10974 "The following example implements a basic B<tee>(1)  program using the "
10975 "B<tee>()  system call."
10976 msgstr ""
10977
10978 #. type: Plain text
10979 #: build/C/man2/tee.2:145
10980 #, no-wrap
10981 msgid ""
10982 "#define _GNU_SOURCE\n"
10983 "#include E<lt>fcntl.hE<gt>\n"
10984 "#include E<lt>stdio.hE<gt>\n"
10985 "#include E<lt>stdlib.hE<gt>\n"
10986 "#include E<lt>unistd.hE<gt>\n"
10987 "#include E<lt>errno.hE<gt>\n"
10988 "#include E<lt>limits.hE<gt>\n"
10989 msgstr ""
10990
10991 #. type: Plain text
10992 #: build/C/man2/tee.2:151
10993 #, no-wrap
10994 msgid ""
10995 "int\n"
10996 "main(int argc, char *argv[])\n"
10997 "{\n"
10998 "    int fd;\n"
10999 "    int len, slen;\n"
11000 msgstr ""
11001
11002 #. type: Plain text
11003 #: build/C/man2/tee.2:156
11004 #, no-wrap
11005 msgid ""
11006 "    if (argc != 2) {\n"
11007 "        fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
11008 "        exit(EXIT_FAILURE);\n"
11009 "    }\n"
11010 msgstr ""
11011
11012 #. type: Plain text
11013 #: build/C/man2/tee.2:162
11014 #, no-wrap
11015 msgid ""
11016 "    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);\n"
11017 "    if (fd == -1) {\n"
11018 "        perror(\"open\");\n"
11019 "        exit(EXIT_FAILURE);\n"
11020 "    }\n"
11021 msgstr ""
11022
11023 #. type: Plain text
11024 #: build/C/man2/tee.2:169
11025 #, no-wrap
11026 msgid ""
11027 "    do {\n"
11028 "        /*\n"
11029 "         * tee stdin to stdout.\n"
11030 "         */\n"
11031 "        len = tee(STDIN_FILENO, STDOUT_FILENO,\n"
11032 "                  INT_MAX, SPLICE_F_NONBLOCK);\n"
11033 msgstr ""
11034
11035 #. type: Plain text
11036 #: build/C/man2/tee.2:178
11037 #, no-wrap
11038 msgid ""
11039 "        if (len E<lt> 0) {\n"
11040 "            if (errno == EAGAIN)\n"
11041 "                continue;\n"
11042 "            perror(\"tee\");\n"
11043 "            exit(EXIT_FAILURE);\n"
11044 "        } else\n"
11045 "            if (len == 0)\n"
11046 "                break;\n"
11047 msgstr ""
11048
11049 #. type: Plain text
11050 #: build/C/man2/tee.2:192
11051 #, no-wrap
11052 msgid ""
11053 "        /*\n"
11054 "         * Consume stdin by splicing it to a file.\n"
11055 "         */\n"
11056 "        while (len E<gt> 0) {\n"
11057 "            slen = splice(STDIN_FILENO, NULL, fd, NULL,\n"
11058 "                          len, SPLICE_F_MOVE);\n"
11059 "            if (slen E<lt> 0) {\n"
11060 "                perror(\"splice\");\n"
11061 "                break;\n"
11062 "            }\n"
11063 "            len -= slen;\n"
11064 "        }\n"
11065 "    } while (1);\n"
11066 msgstr ""
11067
11068 #. type: Plain text
11069 #: build/C/man2/tee.2:196
11070 #, no-wrap
11071 msgid ""
11072 "    close(fd);\n"
11073 "    exit(EXIT_SUCCESS);\n"
11074 "}\n"
11075 msgstr ""
11076
11077 #. type: Plain text
11078 #: build/C/man2/tee.2:200
11079 msgid "B<splice>(2), B<vmsplice>(2)"
11080 msgstr ""
11081
11082 #. type: TH
11083 #: build/C/man2/vm86.2:26
11084 #, no-wrap
11085 msgid "VM86"
11086 msgstr ""
11087
11088 #. type: TH
11089 #: build/C/man2/vm86.2:26
11090 #, no-wrap
11091 msgid "2009-02-20"
11092 msgstr ""
11093
11094 #. type: Plain text
11095 #: build/C/man2/vm86.2:29
11096 msgid "vm86old, vm86 - enter virtual 8086 mode"
11097 msgstr ""
11098
11099 #. type: Plain text
11100 #: build/C/man2/vm86.2:31
11101 msgid "B<#include E<lt>sys/vm86.hE<gt>>"
11102 msgstr ""
11103
11104 #. type: Plain text
11105 #: build/C/man2/vm86.2:33
11106 msgid "B<int vm86old(struct vm86_struct *>I<info>B<);>"
11107 msgstr ""
11108
11109 #. type: Plain text
11110 #: build/C/man2/vm86.2:35
11111 msgid "B<int vm86(unsigned long >I<fn>B<, struct vm86plus_struct *>I<v86>B<);>"
11112 msgstr ""
11113
11114 #. type: Plain text
11115 #: build/C/man2/vm86.2:48
11116 msgid ""
11117 "The system call B<vm86>()  was introduced in Linux 0.97p2.  In Linux 2.1.15 "
11118 "and 2.0.28 it was renamed to B<vm86old>(), and a new B<vm86>()  was "
11119 "introduced.  The definition of I<struct vm86_struct> was changed in 1.1.8 "
11120 "and 1.1.9."
11121 msgstr ""
11122
11123 #. type: Plain text
11124 #: build/C/man2/vm86.2:52
11125 msgid ""
11126 "These calls cause the process to enter VM86 mode (virtual-8086 in Intel "
11127 "literature), and are used by B<dosemu>."
11128 msgstr ""
11129
11130 #. type: Plain text
11131 #: build/C/man2/vm86.2:54
11132 msgid "VM86 mode is an emulation of real mode within a protected mode task."
11133 msgstr ""
11134
11135 #. type: Plain text
11136 #: build/C/man2/vm86.2:64
11137 msgid ""
11138 "This return value is specific to i386 and indicates a problem with getting "
11139 "user-space data."
11140 msgstr ""
11141
11142 #. type: Plain text
11143 #: build/C/man2/vm86.2:68
11144 msgid ""
11145 "This return value indicates the call is not implemented on the present "
11146 "architecture."
11147 msgstr ""
11148
11149 #. type: Plain text
11150 #: build/C/man2/vm86.2:73
11151 msgid ""
11152 "Saved kernel stack exists.  (This is a kernel sanity check; the saved stack "
11153 "should exist only within vm86 mode itself.)"
11154 msgstr ""
11155
11156 #. type: Plain text
11157 #: build/C/man2/vm86.2:76
11158 msgid ""
11159 "This call is specific to Linux on 32-bit Intel processors, and should not be "
11160 "used in programs intended to be portable."
11161 msgstr ""
11162
11163 #. type: TH
11164 #: build/C/man2/vmsplice.2:26
11165 #, no-wrap
11166 msgid "VMSPLICE"
11167 msgstr ""
11168
11169 #. type: Plain text
11170 #: build/C/man2/vmsplice.2:29
11171 msgid "vmsplice - splice user pages into a pipe"
11172 msgstr ""
11173
11174 #. type: Plain text
11175 #: build/C/man2/vmsplice.2:34
11176 #, no-wrap
11177 msgid ""
11178 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
11179 "B<#include E<lt>fcntl.hE<gt>>\n"
11180 "B<#include E<lt>sys/uio.hE<gt>>\n"
11181 msgstr ""
11182
11183 #. type: Plain text
11184 #: build/C/man2/vmsplice.2:37
11185 #, no-wrap
11186 msgid ""
11187 "B<ssize_t vmsplice(int >I<fd>B<, const struct iovec *>I<iov>B<,>\n"
11188 "B<                 unsigned long >I<nr_segs>B<, unsigned int "
11189 ">I<flags>B<);>\n"
11190 msgstr ""
11191
11192 #.  Linus: vmsplice() system call to basically do a "write to
11193 #.  the buffer", but using the reference counting and VM traversal
11194 #.  to actually fill the buffer. This means that the user needs to
11195 #.  be careful not to reuse the user-space buffer it spliced into
11196 #.  the kernel-space one (contrast this to "write()", which copies
11197 #.  the actual data, and you can thus reuse the buffer immediately
11198 #.  after a successful write), but that is often easy to do.
11199 #. type: Plain text
11200 #: build/C/man2/vmsplice.2:57
11201 msgid ""
11202 "The B<vmsplice>()  system call maps I<nr_segs> ranges of user memory "
11203 "described by I<iov> into a pipe.  The file descriptor I<fd> must refer to a "
11204 "pipe."
11205 msgstr ""
11206
11207 #. type: Plain text
11208 #: build/C/man2/vmsplice.2:64
11209 msgid ""
11210 "The pointer I<iov> points to an array of I<iovec> structures as defined in "
11211 "I<E<lt>sys/uio.hE<gt>>:"
11212 msgstr ""
11213
11214 #. type: Plain text
11215 #: build/C/man2/vmsplice.2:71
11216 #, no-wrap
11217 msgid ""
11218 "struct iovec {\n"
11219 "    void  *iov_base;            /* Starting address */\n"
11220 "    size_t iov_len;             /* Number of bytes */\n"
11221 "};\n"
11222 msgstr ""
11223
11224 #. type: Plain text
11225 #: build/C/man2/vmsplice.2:84
11226 msgid "Unused for B<vmsplice>(); see B<splice>(2)."
11227 msgstr ""
11228
11229 #. type: Plain text
11230 #: build/C/man2/vmsplice.2:97
11231 msgid ""
11232 "Currently has no effect for B<vmsplice>(), but may be implemented in the "
11233 "future; see B<splice>(2)."
11234 msgstr ""
11235
11236 #.  FIXME Explain the following line in a little more detail:
11237 #.  .... if we expect to later SPLICE_F_MOVE to the cache.
11238 #. type: Plain text
11239 #: build/C/man2/vmsplice.2:113
11240 msgid ""
11241 "The user pages are a gift to the kernel.  The application may not modify "
11242 "this memory ever, or page cache and on-disk data may differ.  Gifting pages "
11243 "to the kernel means that a subsequent B<splice>(2)  B<SPLICE_F_MOVE> can "
11244 "successfully move the pages; if this flag is not specified, then a "
11245 "subsequent B<splice>(2)  B<SPLICE_F_MOVE> must copy the pages.  Data must "
11246 "also be properly page aligned, both in memory and length."
11247 msgstr ""
11248
11249 #. type: Plain text
11250 #: build/C/man2/vmsplice.2:122
11251 msgid ""
11252 "Upon successful completion, B<vmsplice>()  returns the number of bytes "
11253 "transferred to the pipe.  On error, B<vmsplice>()  returns -1 and I<errno> "
11254 "is set to indicate the error."
11255 msgstr ""
11256
11257 #. type: Plain text
11258 #: build/C/man2/vmsplice.2:127
11259 msgid "I<fd> either not valid, or doesn't refer to a pipe."
11260 msgstr ""
11261
11262 #. type: Plain text
11263 #: build/C/man2/vmsplice.2:135
11264 msgid ""
11265 "I<nr_segs> is 0 or greater than B<IOV_MAX>; or memory not aligned if "
11266 "B<SPLICE_F_GIFT> set."
11267 msgstr ""
11268
11269 #. type: Plain text
11270 #: build/C/man2/vmsplice.2:143
11271 msgid ""
11272 "The B<vmsplice>()  system call first appeared in Linux 2.6.17; library "
11273 "support was added to glibc in version 2.5."
11274 msgstr ""
11275
11276 #. type: Plain text
11277 #: build/C/man2/vmsplice.2:154
11278 msgid ""
11279 "B<vmsplice>()  follows the other vectorized read/write type functions when "
11280 "it comes to limitations on number of segments being passed in.  This limit "
11281 "is B<IOV_MAX> as defined in I<E<lt>limits.hE<gt>>.  At the time of this "
11282 "writing, that limit is 1024."
11283 msgstr ""
11284
11285 #. type: Plain text
11286 #: build/C/man2/vmsplice.2:157
11287 msgid "B<splice>(2), B<tee>(2)"
11288 msgstr ""