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-06-03 01:29+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:70 build/C/man2/get_robust_list.2:45 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:66 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:216 build/C/man2/get_robust_list.2:78 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:225 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:241 build/C/man2/get_robust_list.2:85 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:245 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:256 build/C/man2/get_robust_list.2:112 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:267 build/C/man2/process_vm_readv.2:272 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:268 build/C/man2/get_robust_list.2:89 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:246 build/C/man2/process_vm_readv.2:257 build/C/man2/process_vm_readv.2:261 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:99 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:283 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:303 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:295 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:305 build/C/man2/get_robust_list.2:120 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:297 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:319 build/C/man2/get_robust_list.2:129 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:347 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:333 build/C/man2/get_robust_list.2:138 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:350 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:153 build/C/man2/futex.2:341 build/C/man2/get_robust_list.2:146 build/C/man2/getunwind.2:121 build/C/man2/kexec_load.2:170 build/C/man2/lookup_dcookie.2:96 build/C/man2/modify_ldt.2:146 build/C/man2/nfsservctl.2:68 build/C/man2/outb.2:107 build/C/man2/pciconfig_read.2:124 build/C/man2/perf_event_open.2:2666 build/C/man2/perfmonctl.2:217 build/C/man2/personality.2:85 build/C/man2/pivot_root.2:157 build/C/man2/process_vm_readv.2:358 build/C/man2/ptrace.2:2101 build/C/man2/quotactl.2:520 build/C/man2/sendfile.2:211 build/C/man2/set_tid_address.2:110 build/C/man2/splice.2:238 build/C/man2/tee.2:208 build/C/man2/vm86.2:84 build/C/man2/vmsplice.2:165
 289 msgid ""
 290 "This page is part of release 3.67 of the Linux I<man-pages> project.  A "
 291 "description of the project, information about reporting bugs, and the latest "
 292 "version of this page, can be found at "
 293 "\\%http://www.kernel.org/doc/man-pages/."
 294 msgstr ""
 295
 296 #. type: TH
 297 #: build/C/man2/futex.2:53
 298 #, no-wrap
 299 msgid "FUTEX"
 300 msgstr ""
 301
 302 #. type: TH
 303 #: build/C/man2/futex.2:53
 304 #, no-wrap
 305 msgid "2014-05-21"
 306 msgstr ""
 307
 308 #. type: Plain text
 309 #: build/C/man2/futex.2:56
 310 msgid "futex - fast user-space locking"
 311 msgstr ""
 312
 313 #. type: Plain text
 314 #: build/C/man2/futex.2:61
 315 #, no-wrap
 316 msgid ""
 317 "B<#include E<lt>linux/futex.hE<gt>>\n"
 318 "B<#include E<lt>sys/time.hE<gt>>\n"
 319 msgstr ""
 320
 321 #. type: Plain text
 322 #: build/C/man2/futex.2:64
 323 #, no-wrap
 324 msgid ""
 325 "B<int futex(int *>I<uaddr>B<, int >I<op>B<, int >I<val>B<, const struct "
 326 "timespec *>I<timeout>B<,>\n"
 327 msgstr ""
 328
 329 #.  int *? void *? u32 *?
 330 #. type: Plain text
 331 #: build/C/man2/futex.2:67
 332 #, no-wrap
 333 msgid "B<          int *>I<uaddr2>B<, int >I<val3>B<);>\n"
 334 msgstr ""
 335
 336 #. type: Plain text
 337 #: build/C/man2/futex.2:70 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
 338 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
 339 msgstr ""
 340
 341 #. type: Plain text
 342 #: build/C/man2/futex.2:86
 343 msgid ""
 344 "The B<futex>()  system call provides a method for a program to wait for a "
 345 "value at a given address to change, and a method to wake up anyone waiting "
 346 "on a particular address (while the addresses for the same memory in separate "
 347 "processes may not be equal, the kernel maps them internally so the same "
 348 "memory mapped in different locations will correspond for B<futex>()  "
 349 "calls).  This system call is typically used to implement the contended case "
 350 "of a lock in shared memory, as described in B<futex>(7)."
 351 msgstr ""
 352
 353 #. type: Plain text
 354 #: build/C/man2/futex.2:93
 355 msgid ""
 356 "When a B<futex>(7)  operation did not finish uncontended in user space, a "
 357 "call needs to be made to the kernel to arbitrate.  Arbitration can either "
 358 "mean putting the calling process to sleep or, conversely, waking a waiting "
 359 "process."
 360 msgstr ""
 361
 362 #. type: Plain text
 363 #: build/C/man2/futex.2:100
 364 msgid ""
 365 "Callers of this function are expected to adhere to the semantics as set out "
 366 "in B<futex>(7).  As these semantics involve writing nonportable assembly "
 367 "instructions, this in turn probably means that most users will in fact be "
 368 "library authors and not general application developers."
 369 msgstr ""
 370
 371 #. type: Plain text
 372 #: build/C/man2/futex.2:108
 373 msgid ""
 374 "The I<uaddr> argument needs to point to an aligned integer which stores the "
 375 "counter.  The operation to execute is passed via the I<op> argument, along "
 376 "with a value I<val>."
 377 msgstr ""
 378
 379 #. type: Plain text
 380 #: build/C/man2/futex.2:110
 381 msgid "Five operations are currently defined:"
 382 msgstr ""
 383
 384 #. type: TP
 385 #: build/C/man2/futex.2:110 build/C/man2/futex.2:223
 386 #, no-wrap
 387 msgid "B<FUTEX_WAIT>"
 388 msgstr ""
 389
 390 #. type: Plain text
 391 #: build/C/man2/futex.2:133
 392 msgid ""
 393 "This operation atomically verifies that the futex address I<uaddr> still "
 394 "contains the value I<val>, and sleeps awaiting B<FUTEX_WAKE> on this futex "
 395 "address.  If the I<timeout> argument is non-NULL, its contents specify the "
 396 "duration of the wait.  (This interval will be rounded up to the system clock "
 397 "granularity, and kernel scheduling delays mean that the blocking interval "
 398 "may overrun by a small amount.)  If I<timeout> is NULL, the call blocks "
 399 "indefinitely.  The arguments I<uaddr2> and I<val3> are ignored."
 400 msgstr ""
 401
 402 #. type: Plain text
 403 #: build/C/man2/futex.2:141
 404 msgid ""
 405 "For B<futex>(7), this call is executed if decrementing the count gave a "
 406 "negative value (indicating contention), and will sleep until another process "
 407 "releases the futex and executes the B<FUTEX_WAKE> operation."
 408 msgstr ""
 409
 410 #. type: TP
 411 #: build/C/man2/futex.2:141 build/C/man2/futex.2:229
 412 #, no-wrap
 413 msgid "B<FUTEX_WAKE>"
 414 msgstr ""
 415
 416 #. type: Plain text
 417 #: build/C/man2/futex.2:152
 418 msgid ""
 419 "This operation wakes at most I<val> processes waiting on this futex address "
 420 "(i.e., inside B<FUTEX_WAIT>).  The arguments I<timeout>, I<uaddr2> and "
 421 "I<val3> are ignored."
 422 msgstr ""
 423
 424 #. type: Plain text
 425 #: build/C/man2/futex.2:158
 426 msgid ""
 427 "For B<futex>(7), this is executed if incrementing the count showed that "
 428 "there were waiters, once the futex value has been set to 1 (indicating that "
 429 "it is available)."
 430 msgstr ""
 431
 432 #. type: TP
 433 #: build/C/man2/futex.2:158
 434 #, no-wrap
 435 msgid "B<FUTEX_FD> (present up to and including Linux 2.6.25)"
 436 msgstr ""
 437
 438 #.  , suitable for .BR poll (2).
 439 #. type: Plain text
 440 #: build/C/man2/futex.2:174
 441 msgid ""
 442 "To support asynchronous wakeups, this operation associates a file descriptor "
 443 "with a futex.  If another process executes a B<FUTEX_WAKE>, the process will "
 444 "receive the signal number that was passed in I<val>.  The calling process "
 445 "must close the returned file descriptor after use.  The arguments "
 446 "I<timeout>, I<uaddr2> and I<val3> are ignored."
 447 msgstr ""
 448
 449 #. type: Plain text
 450 #: build/C/man2/futex.2:179
 451 msgid ""
 452 "To prevent race conditions, the caller should test if the futex has been "
 453 "upped after B<FUTEX_FD> returns."
 454 msgstr ""
 455
 456 #. type: Plain text
 457 #: build/C/man2/futex.2:183
 458 msgid ""
 459 "Because it was inherently racy, B<FUTEX_FD> has been removed from Linux "
 460 "2.6.26 onward."
 461 msgstr ""
 462
 463 #. type: TP
 464 #: build/C/man2/futex.2:183
 465 #, no-wrap
 466 msgid "B<FUTEX_REQUEUE> (since Linux 2.5.70)"
 467 msgstr ""
 468
 469 #. type: Plain text
 470 #: build/C/man2/futex.2:198
 471 msgid ""
 472 "This operation was introduced in order to avoid a \"thundering herd\" effect "
 473 "when B<FUTEX_WAKE> is used and all processes woken up need to acquire "
 474 "another futex.  This call wakes up I<val> processes, and requeues all other "
 475 "waiters on the futex at address I<uaddr2>.  The arguments I<timeout> and "
 476 "I<val3> are ignored."
 477 msgstr ""
 478
 479 #. type: TP
 480 #: build/C/man2/futex.2:198
 481 #, no-wrap
 482 msgid "B<FUTEX_CMP_REQUEUE> (since Linux 2.6.7)"
 483 msgstr ""
 484
 485 #. type: Plain text
 486 #: build/C/man2/futex.2:216
 487 msgid ""
 488 "There was a race in the intended use of B<FUTEX_REQUEUE>, so "
 489 "B<FUTEX_CMP_REQUEUE> was introduced.  This is similar to B<FUTEX_REQUEUE>, "
 490 "but first checks whether the location I<uaddr> still contains the value "
 491 "I<val3>.  If not, the operation fails with the error B<EAGAIN>.  The "
 492 "argument I<timeout> is ignored."
 493 msgstr ""
 494
 495 #. type: Plain text
 496 #: build/C/man2/futex.2:223
 497 msgid ""
 498 "In the event of an error, all operations return -1, and set I<errno> to "
 499 "indicate the error.  The return value on success depends on the operation, "
 500 "as described in the following list:"
 501 msgstr ""
 502
 503 #. type: Plain text
 504 #: build/C/man2/futex.2:229
 505 msgid ""
 506 "Returns 0 if the process was woken by a B<FUTEX_WAKE> call.  See ERRORS for "
 507 "the various possible error returns."
 508 msgstr ""
 509
 510 #. type: Plain text
 511 #: build/C/man2/futex.2:232 build/C/man2/futex.2:238 build/C/man2/futex.2:241
 512 msgid "Returns the number of processes woken up."
 513 msgstr ""
 514
 515 #. type: TP
 516 #: build/C/man2/futex.2:232
 517 #, no-wrap
 518 msgid "B<FUTEX_FD>"
 519 msgstr ""
 520
 521 #. type: Plain text
 522 #: build/C/man2/futex.2:235
 523 msgid "Returns the new file descriptor associated with the futex."
 524 msgstr ""
 525
 526 #. type: TP
 527 #: build/C/man2/futex.2:235
 528 #, no-wrap
 529 msgid "B<FUTEX_REQUEUE>"
 530 msgstr ""
 531
 532 #. type: TP
 533 #: build/C/man2/futex.2:238
 534 #, no-wrap
 535 msgid "B<FUTEX_CMP_REQUEUE>"
 536 msgstr ""
 537
 538 #. type: TP
 539 #: build/C/man2/futex.2:242 build/C/man2/perf_event_open.2:2399 build/C/man2/quotactl.2:486
 540 #, no-wrap
 541 msgid "B<EACCES>"
 542 msgstr ""
 543
 544 #. type: Plain text
 545 #: build/C/man2/futex.2:245
 546 msgid "No read access to futex memory."
 547 msgstr ""
 548
 549 #. type: TP
 550 #: build/C/man2/futex.2:245 build/C/man2/sendfile.2:116
 551 #, no-wrap
 552 msgid "B<EAGAIN>"
 553 msgstr ""
 554
 555 #. type: Plain text
 556 #: build/C/man2/futex.2:256
 557 msgid ""
 558 "B<FUTEX_CMP_REQUEUE> detected that the value pointed to by I<uaddr> is not "
 559 "equal to the expected value I<val3>.  (This probably indicates a race; use "
 560 "the safe B<FUTEX_WAKE> now.)"
 561 msgstr ""
 562
 563 #. type: Plain text
 564 #: build/C/man2/futex.2:261
 565 msgid "Error retrieving I<timeout> information from user space."
 566 msgstr ""
 567
 568 #. type: TP
 569 #: build/C/man2/futex.2:261
 570 #, no-wrap
 571 msgid "B<EINTR>"
 572 msgstr ""
 573
 574 #. type: Plain text
 575 #: build/C/man2/futex.2:268
 576 msgid ""
 577 "A B<FUTEX_WAIT> operation was interrupted by a signal (see B<signal>(7))  or "
 578 "a spurious wakeup."
 579 msgstr ""
 580
 581 #. type: Plain text
 582 #: build/C/man2/futex.2:271
 583 msgid "Invalid argument."
 584 msgstr ""
 585
 586 #. type: TP
 587 #: build/C/man2/futex.2:271
 588 #, no-wrap
 589 msgid "B<ENFILE>"
 590 msgstr ""
 591
 592 #. type: Plain text
 593 #: build/C/man2/futex.2:274
 594 msgid "The system limit on the total number of open files has been reached."
 595 msgstr ""
 596
 597 #. type: TP
 598 #: build/C/man2/futex.2:274 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
 599 #, no-wrap
 600 msgid "B<ENOSYS>"
 601 msgstr ""
 602
 603 #. type: Plain text
 604 #: build/C/man2/futex.2:278
 605 msgid "Invalid operation specified in I<op>."
 606 msgstr ""
 607
 608 #. type: TP
 609 #: build/C/man2/futex.2:278
 610 #, no-wrap
 611 msgid "B<ETIMEDOUT>"
 612 msgstr ""
 613
 614 #. type: Plain text
 615 #: build/C/man2/futex.2:283
 616 msgid "Timeout during the B<FUTEX_WAIT> operation."
 617 msgstr ""
 618
 619 #. type: TP
 620 #: build/C/man2/futex.2:283
 621 #, no-wrap
 622 msgid "B<EWOULDBLOCK>"
 623 msgstr ""
 624
 625 #. type: Plain text
 626 #: build/C/man2/futex.2:293
 627 msgid ""
 628 "I<op> was B<FUTEX_WAIT> and the value pointed to by I<uaddr> was not equal "
 629 "to the expected value I<val> at the time of the call."
 630 msgstr ""
 631
 632 #. type: SH
 633 #: build/C/man2/futex.2:293 build/C/man2/get_robust_list.2:116 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:292 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
 634 #, no-wrap
 635 msgid "VERSIONS"
 636 msgstr ""
 637
 638 #. type: Plain text
 639 #: build/C/man2/futex.2:303
 640 msgid ""
 641 "Initial futex support was merged in Linux 2.5.7 but with different semantics "
 642 "from what was described above.  A 4-argument system call with the semantics "
 643 "described in this page was introduced in Linux 2.5.40.  In Linux 2.5.70, one "
 644 "argument was added.  In Linux 2.6.7, a sixth argument was added\\(emmessy, "
 645 "especially on the s390 architecture."
 646 msgstr ""
 647
 648 #. type: Plain text
 649 #: build/C/man2/futex.2:305 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
 650 msgid "This system call is Linux-specific."
 651 msgstr ""
 652
 653 #.  .SH "AUTHORS"
 654 #.  .PP
 655 #.  Futexes were designed and worked on by
 656 #.  Hubertus Franke (IBM Thomas J. Watson Research Center),
 657 #.  Matthew Kirkwood, Ingo Molnar (Red Hat)
 658 #.  and Rusty Russell (IBM Linux Technology Center).
 659 #.  This page written by bert hubert.
 660 #. type: Plain text
 661 #: build/C/man2/futex.2:319
 662 msgid ""
 663 "To reiterate, bare futexes are not intended as an easy-to-use abstraction "
 664 "for end-users.  (There is no wrapper function for this system call in "
 665 "glibc.)  Implementors are expected to be assembly literate and to have read "
 666 "the sources of the futex user-space library referenced below."
 667 msgstr ""
 668
 669 #. type: Plain text
 670 #: build/C/man2/futex.2:322
 671 msgid "B<restart_syscall>(2), B<futex>(7)"
 672 msgstr ""
 673
 674 #. type: Plain text
 675 #: build/C/man2/futex.2:325
 676 msgid ""
 677 "I<Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux> (proceedings "
 678 "of the Ottawa Linux Symposium 2002), online at"
 679 msgstr ""
 680
 681 #. type: Plain text
 682 #: build/C/man2/futex.2:328
 683 msgid ""
 684 "E<.UR http://kernel.org\\:/doc\\:/ols\\:/2002\\:/ols2002-pages-479-495.pdf> "
 685 "E<.UE>"
 686 msgstr ""
 687
 688 #. type: Plain text
 689 #: build/C/man2/futex.2:330
 690 msgid "Futex example library, futex-*.tar.bz2 at"
 691 msgstr ""
 692
 693 #. type: Plain text
 694 #: build/C/man2/futex.2:333
 695 msgid ""
 696 "E<.UR ftp://ftp.kernel.org\\:/pub\\:/linux\\:/kernel\\:/people\\:/rusty/> "
 697 "E<.UE>"
 698 msgstr ""
 699
 700 #. type: TH
 701 #: build/C/man2/get_robust_list.2:29
 702 #, no-wrap
 703 msgid "GET_ROBUST_LIST"
 704 msgstr ""
 705
 706 #. type: TH
 707 #: build/C/man2/get_robust_list.2:29
 708 #, no-wrap
 709 msgid "2014-05-10"
 710 msgstr ""
 711
 712 #. type: TH
 713 #: build/C/man2/get_robust_list.2:29
 714 #, no-wrap
 715 msgid "Linux System Calls"
 716 msgstr ""
 717
 718 #. type: Plain text
 719 #: build/C/man2/get_robust_list.2:32
 720 msgid "get_robust_list, set_robust_list - get/set list of robust futexes"
 721 msgstr ""
 722
 723 #. type: Plain text
 724 #: build/C/man2/get_robust_list.2:37
 725 #, no-wrap
 726 msgid ""
 727 "B<#include E<lt>linux/futex.hE<gt>>\n"
 728 "B<#include E<lt>sys/types.hE<gt>>\n"
 729 "B<#include E<lt>syscall.hE<gt>>\n"
 730 msgstr ""
 731
 732 #. type: Plain text
 733 #: build/C/man2/get_robust_list.2:41
 734 #, no-wrap
 735 msgid ""
 736 "B<long get_robust_list(int >I<pid>B<, struct robust_list_head "
 737 "**>I<head_ptr>B<,>\n"
 738 "B<                     size_t *>I<len_ptr>B<);>\n"
 739 "B<long set_robust_list(struct robust_list_head *>I<head>B<, size_t "
 740 ">I<len>B<);>\n"
 741 msgstr ""
 742
 743 #. type: Plain text
 744 #: build/C/man2/get_robust_list.2:45
 745 msgid "I<Note>: There are no glibc wrappers for these system calls; see NOTES."
 746 msgstr ""
 747
 748 #. type: Plain text
 749 #: build/C/man2/get_robust_list.2:50
 750 msgid ""
 751 "The robust futex implementation needs to maintain per-thread lists of robust "
 752 "futexes which are unlocked when the thread exits.  These lists are managed "
 753 "in user space; the kernel is notified about only the location of the head of "
 754 "the list."
 755 msgstr ""
 756
 757 #. type: Plain text
 758 #: build/C/man2/get_robust_list.2:66
 759 msgid ""
 760 "The B<get_robust_list>()  system call returns the head of the robust futex "
 761 "list of the thread whose thread ID is specified in I<pid>.  If I<pid> is 0, "
 762 "the head of the list for the calling thread is returned.  The list head is "
 763 "stored in the location pointed to by I<head_ptr>.  The size of the object "
 764 "pointed to by I<**head_ptr> is stored in I<len_ptr>."
 765 msgstr ""
 766
 767 #. type: Plain text
 768 #: build/C/man2/get_robust_list.2:78
 769 msgid ""
 770 "The B<set_robust_list>()  system call requests the kernel to record the head "
 771 "of the list of robust futexes owned by the calling thread.  The I<head> "
 772 "argument is the list head to record.  The I<len> argument should be "
 773 "I<sizeof(*head)>."
 774 msgstr ""
 775
 776 #. type: Plain text
 777 #: build/C/man2/get_robust_list.2:85
 778 msgid ""
 779 "The B<set_robust_list>()  and B<get_robust_list>()  system calls return zero "
 780 "when the operation is successful, an error code otherwise."
 781 msgstr ""
 782
 783 #. type: Plain text
 784 #: build/C/man2/get_robust_list.2:89
 785 msgid "The B<set_robust_list>()  system call can fail with the following error:"
 786 msgstr ""
 787
 788 #. type: Plain text
 789 #: build/C/man2/get_robust_list.2:95
 790 msgid ""
 791 "I<len> does not match the size of structure B<struct robust_list_head> "
 792 "expected by kernel."
 793 msgstr ""
 794
 795 #. type: Plain text
 796 #: build/C/man2/get_robust_list.2:99
 797 msgid "The B<get_robust_list>()  system call can fail with the following errors:"
 798 msgstr ""
 799
 800 #. type: Plain text
 801 #: build/C/man2/get_robust_list.2:107
 802 msgid ""
 803 "The calling process does not have permission to see the robust futex list of "
 804 "the thread with the thread ID I<pid>, and does not have the "
 805 "B<CAP_SYS_PTRACE> capability."
 806 msgstr ""
 807
 808 #. type: TP
 809 #: build/C/man2/get_robust_list.2:107 build/C/man2/perf_event_open.2:2508 build/C/man2/process_vm_readv.2:287 build/C/man2/ptrace.2:1906 build/C/man2/quotactl.2:461 build/C/man2/quotactl.2:504
 810 #, no-wrap
 811 msgid "B<ESRCH>"
 812 msgstr ""
 813
 814 #. type: Plain text
 815 #: build/C/man2/get_robust_list.2:112
 816 msgid "No thread with the thread ID I<pid> could be found."
 817 msgstr ""
 818
 819 #. type: Plain text
 820 #: build/C/man2/get_robust_list.2:116
 821 msgid "The head of the robust futex list can't be stored at the location I<head>."
 822 msgstr ""
 823
 824 #. type: Plain text
 825 #: build/C/man2/get_robust_list.2:120
 826 msgid ""
 827 "These system calls were added in Linux 2.6.17.  No library support is "
 828 "provided; use B<syscall>(2)."
 829 msgstr ""
 830
 831 #. type: Plain text
 832 #: build/C/man2/get_robust_list.2:125
 833 msgid ""
 834 "These system calls are not needed by normal applications.  No support for "
 835 "them is provided in glibc.  In the unlikely event that you want to call them "
 836 "directly, use B<syscall>(2)."
 837 msgstr ""
 838
 839 #. type: Plain text
 840 #: build/C/man2/get_robust_list.2:129
 841 msgid ""
 842 "A thread can have only one robust futex list; therefore applications that "
 843 "wish to use this functionality should use the robust mutexes provided by "
 844 "glibc."
 845 msgstr ""
 846
 847 #.  .BR pthread_mutexattr_setrobust_np (3)
 848 #. type: Plain text
 849 #: build/C/man2/get_robust_list.2:132
 850 msgid "B<futex>(2)"
 851 msgstr ""
 852
 853 #.  http://lwn.net/Articles/172149/
 854 #. type: Plain text
 855 #: build/C/man2/get_robust_list.2:138
 856 msgid ""
 857 "I<Documentation/robust-futexes.txt> and "
 858 "I<Documentation/robust-futex-ABI.txt> in the Linux kernel source tree"
 859 msgstr ""
 860
 861 #. type: TH
 862 #: build/C/man2/getunwind.2:27
 863 #, no-wrap
 864 msgid "GETUNWIND"
 865 msgstr ""
 866
 867 #. type: TH
 868 #: build/C/man2/getunwind.2:27 build/C/man2/perfmonctl.2:27
 869 #, no-wrap
 870 msgid "2013-02-13"
 871 msgstr ""
 872
 873 #. type: Plain text
 874 #: build/C/man2/getunwind.2:30
 875 msgid "getunwind - copy the unwind data to caller's buffer"
 876 msgstr ""
 877
 878 #. type: Plain text
 879 #: build/C/man2/getunwind.2:34
 880 #, no-wrap
 881 msgid ""
 882 "B<#include E<lt>syscall.hE<gt>>\n"
 883 "B<#include E<lt>linux/unwind.hE<gt>>\n"
 884 msgstr ""
 885
 886 #. type: Plain text
 887 #: build/C/man2/getunwind.2:36
 888 #, no-wrap
 889 msgid "B<long getunwind(void >I<*buf>B<, size_t >I<buf_size>B<);>\n"
 890 msgstr ""
 891
 892 #. type: Plain text
 893 #: build/C/man2/getunwind.2:42
 894 msgid "I<Note: this function is obsolete.>"
 895 msgstr ""
 896
 897 #. type: Plain text
 898 #: build/C/man2/getunwind.2:52
 899 msgid ""
 900 "The IA-64-specific B<getunwind>()  system call copies the kernel's call "
 901 "frame unwind data into the buffer pointed to by I<buf> and returns the size "
 902 "of the unwind data; this data describes the gate page (kernel code that is "
 903 "mapped into user space)."
 904 msgstr ""
 905
 906 #. type: Plain text
 907 #: build/C/man2/getunwind.2:64
 908 msgid ""
 909 "The size of the buffer I<buf> is specified in I<buf_size>.  The data is "
 910 "copied only if I<buf_size> is greater than or equal to the size of the "
 911 "unwind data and I<buf> is not NULL; otherwise, no data is copied, and the "
 912 "call succeeds, returning the size that would be needed to store the unwind "
 913 "data."
 914 msgstr ""
 915
 916 #. type: Plain text
 917 #: build/C/man2/getunwind.2:68
 918 msgid ""
 919 "The first part of the unwind data contains an unwind table.  The rest "
 920 "contains the associated unwind information, in no particular order.  The "
 921 "unwind table contains entries of the following form:"
 922 msgstr ""
 923
 924 #. type: Plain text
 925 #: build/C/man2/getunwind.2:73
 926 #, no-wrap
 927 msgid ""
 928 "    u64 start;      (64-bit address of start of function)\n"
 929 "    u64 end;        (64-bit address of end of function)\n"
 930 "    u64 info;       (BUF-relative offset to unwind info)\n"
 931 msgstr ""
 932
 933 #. type: Plain text
 934 #: build/C/man2/getunwind.2:81
 935 msgid ""
 936 "An entry whose I<start> value is zero indicates the end of the table.  For "
 937 "more information about the format, see the I<IA-64 Software Conventions and "
 938 "Runtime Architecture> manual."
 939 msgstr ""
 940
 941 #. type: Plain text
 942 #: build/C/man2/getunwind.2:88
 943 msgid ""
 944 "On success, B<getunwind>()  returns the size of unwind table.  On error, -1 "
 945 "is returned and I<errno> is set to indicate the error."
 946 msgstr ""
 947
 948 #. type: Plain text
 949 #: build/C/man2/getunwind.2:94
 950 msgid ""
 951 "B<getunwind>()  fails with the error B<EFAULT> if the unwind info can't be "
 952 "stored in the space specified by I<buf>."
 953 msgstr ""
 954
 955 #. type: Plain text
 956 #: build/C/man2/getunwind.2:96
 957 msgid "This system call is available since Linux 2.4."
 958 msgstr ""
 959
 960 #. type: Plain text
 961 #: build/C/man2/getunwind.2:99
 962 msgid ""
 963 "This system call is Linux-specific, and is available only on the IA-64 "
 964 "architecture."
 965 msgstr ""
 966
 967 #. type: Plain text
 968 #: build/C/man2/getunwind.2:107
 969 msgid ""
 970 "This system call has been deprecated.  The modern way to obtain the kernel's "
 971 "unwind data is via the gate DSO.  The address of the ELF header for this DSO "
 972 "is passed to user level via B<AT_SYSINFO_EHDR> (see B<getauxval>(3))."
 973 msgstr ""
 974
 975 #. type: Plain text
 976 #: build/C/man2/getunwind.2:111
 977 msgid ""
 978 "Glibc does not provide a wrapper for this system call; in the unlikely event "
 979 "that you want to call it, use B<syscall>(2)."
 980 msgstr ""
 981
 982 #. type: Plain text
 983 #: build/C/man2/getunwind.2:113
 984 msgid "B<getauxval>(3)"
 985 msgstr ""
 986
 987 #. type: TH
 988 #: build/C/man2/kexec_load.2:26
 989 #, no-wrap
 990 msgid "KEXEC_LOAD"
 991 msgstr ""
 992
 993 #. type: TH
 994 #: build/C/man2/kexec_load.2:26 build/C/man2/modify_ldt.2:24 build/C/man2/pivot_root.2:10
 995 #, no-wrap
 996 msgid "2012-07-13"
 997 msgstr ""
 998
 999 #. type: Plain text
1000 #: build/C/man2/kexec_load.2:29
1001 msgid "kexec_load - load a new kernel for later execution"
1002 msgstr ""
1003
1004 #. type: Plain text
1005 #: build/C/man2/kexec_load.2:31
1006 msgid "B<#include E<lt>linux/kexec.hE<gt>>"
1007 msgstr ""
1008
1009 #. type: Plain text
1010 #: build/C/man2/kexec_load.2:33
1011 msgid ""
1012 "B<long kexec_load(unsigned long >I<entry>B<, unsigned long "
1013 ">I<nr_segments>B<,>"
1014 msgstr ""
1015
1016 #. type: Plain text
1017 #: build/C/man2/kexec_load.2:36
1018 msgid "B< struct kexec_segment *>I<segments>B<, unsigned long >I<flags>B<);>"
1019 msgstr ""
1020
1021 #. type: Plain text
1022 #: build/C/man2/kexec_load.2:44
1023 msgid ""
1024 "The B<kexec_load>()  system call loads a new kernel that can be executed "
1025 "later by B<reboot>(2)."
1026 msgstr ""
1027
1028 #. type: Plain text
1029 #: build/C/man2/kexec_load.2:50
1030 msgid ""
1031 "The I<flags> argument is a mask whose high-order bits control the operation "
1032 "of the call.  The following values can be specified in I<flags>:"
1033 msgstr ""
1034
1035 #. type: TP
1036 #: build/C/man2/kexec_load.2:50
1037 #, no-wrap
1038 msgid "B<KEXEC_ON_CRASH> (since Linux 2.6.13)"
1039 msgstr ""
1040
1041 #.  FIXME figure out how this is really used
1042 #. type: Plain text
1043 #: build/C/man2/kexec_load.2:54
1044 msgid "Execute the new kernel automatically on a system crash."
1045 msgstr ""
1046
1047 #. type: TP
1048 #: build/C/man2/kexec_load.2:54
1049 #, no-wrap
1050 msgid "B<KEXEC_PRESERVE_CONTEXT> (since Linux 2.6.27)"
1051 msgstr ""
1052
1053 #. type: Plain text
1054 #: build/C/man2/kexec_load.2:64
1055 msgid ""
1056 "Preserve the system hardware and software states before executing the new "
1057 "kernel.  This could be used for system suspend.  This flag is available only "
1058 "if the kernel was configured with B<CONFIG_KEXEC_JUMP>, and is effective "
1059 "only if I<nr_segments> is greater than 0."
1060 msgstr ""
1061
1062 #. type: Plain text
1063 #: build/C/man2/kexec_load.2:84
1064 msgid ""
1065 "The low-order bits of I<flags> contain the architecture of the "
1066 "to-be-executed kernel.  Specify (OR) the constant B<KEXEC_ARCH_DEFAULT> to "
1067 "use the current architecture, or one of the following architecture constants "
1068 "B<KEXEC_ARCH_386>, B<KEXEC_ARCH_X86_64>, B<KEXEC_ARCH_PPC>, "
1069 "B<KEXEC_ARCH_PPC64>, B<KEXEC_ARCH_IA_64>, B<KEXEC_ARCH_ARM>, "
1070 "B<KEXEC_ARCH_S390>, B<KEXEC_ARCH_SH>, B<KEXEC_ARCH_MIPS>, and "
1071 "B<KEXEC_ARCH_MIPS_LE>.  The architecture must be executable on the CPU of "
1072 "the system."
1073 msgstr ""
1074
1075 #. type: Plain text
1076 #: build/C/man2/kexec_load.2:98
1077 msgid ""
1078 "The I<entry> argument is the physical entry address in the kernel image.  "
1079 "The I<nr_segments> argument is the number of segments pointed to by the "
1080 "I<segments> pointer.  The I<segments> argument is an array of "
1081 "I<kexec_segment> structures which define the kernel layout:"
1082 msgstr ""
1083
1084 #. type: Plain text
1085 #: build/C/man2/kexec_load.2:107
1086 #, no-wrap
1087 msgid ""
1088 "struct kexec_segment {\n"
1089 "    void   *buf;        /* Buffer in user space */\n"
1090 "    size_t  bufsz;      /* Buffer length in user space */\n"
1091 "    void   *mem;        /* Physical address of kernel */\n"
1092 "    size_t  memsz;      /* Physical address length */\n"
1093 "};\n"
1094 msgstr ""
1095
1096 #.  FIXME elaborate on the following:
1097 #. type: Plain text
1098 #: build/C/man2/kexec_load.2:114
1099 msgid ""
1100 "The kernel image defined by I<segments> is copied from the calling process "
1101 "into previously reserved memory."
1102 msgstr ""
1103
1104 #. type: Plain text
1105 #: build/C/man2/kexec_load.2:121
1106 msgid ""
1107 "On success, B<kexec_load>()  returns 0.  On error, -1 is returned and "
1108 "I<errno> is set to indicate the error."
1109 msgstr ""
1110
1111 #. type: TP
1112 #: 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
1113 #, no-wrap
1114 msgid "B<EBUSY>"
1115 msgstr ""
1116
1117 #. type: Plain text
1118 #: build/C/man2/kexec_load.2:126
1119 msgid ""
1120 "Another crash kernel is already being loaded or a crash kernel is already in "
1121 "use."
1122 msgstr ""
1123
1124 #.  KEXEC_SEGMENT_MAX == 16
1125 #. type: Plain text
1126 #: build/C/man2/kexec_load.2:133
1127 msgid "I<flags> is invalid; or I<nr_segments> is too large"
1128 msgstr ""
1129
1130 #. type: Plain text
1131 #: build/C/man2/kexec_load.2:138
1132 msgid "The caller does not have the B<CAP_SYS_BOOT> capability."
1133 msgstr ""
1134
1135 #. type: Plain text
1136 #: build/C/man2/kexec_load.2:142
1137 msgid "The B<kexec_load>()  system call first appeared in Linux 2.6.13."
1138 msgstr ""
1139
1140 #. type: Plain text
1141 #: build/C/man2/kexec_load.2:149
1142 msgid ""
1143 "Currently, there is no glibc support for B<kexec_load>().  Call it using "
1144 "B<syscall>(2)."
1145 msgstr ""
1146
1147 #.  FIXME Andi submitted a patch for this.
1148 #.  Check if it got accepted later.
1149 #. type: Plain text
1150 #: build/C/man2/kexec_load.2:156
1151 msgid ""
1152 "The required constants are in the Linux kernel source file I<linux/kexec.h>, "
1153 "which is not currently exported to glibc.  Therefore, these constants must "
1154 "be defined manually."
1155 msgstr ""
1156
1157 #. type: Plain text
1158 #: build/C/man2/kexec_load.2:159
1159 msgid ""
1160 "This system call is available only if the kernel was configured with "
1161 "B<CONFIG_KEXEC>."
1162 msgstr ""
1163
1164 #. type: Plain text
1165 #: build/C/man2/kexec_load.2:162
1166 msgid "B<reboot>(2), B<syscall>(2)"
1167 msgstr ""
1168
1169 #. type: TH
1170 #: build/C/man2/lookup_dcookie.2:27
1171 #, no-wrap
1172 msgid "LOOKUP_DCOOKIE"
1173 msgstr ""
1174
1175 #. type: TH
1176 #: build/C/man2/lookup_dcookie.2:27
1177 #, no-wrap
1178 msgid "2004-06-17"
1179 msgstr ""
1180
1181 #. type: Plain text
1182 #: build/C/man2/lookup_dcookie.2:30
1183 msgid "lookup_dcookie - return a directory entry's path"
1184 msgstr ""
1185
1186 #. type: Plain text
1187 #: build/C/man2/lookup_dcookie.2:32
1188 msgid ""
1189 "B<int lookup_dcookie(u64 >I<cookie>B<, char *>I<buffer>B<, size_t "
1190 ">I<len>B<);>"
1191 msgstr ""
1192
1193 #. type: Plain text
1194 #: build/C/man2/lookup_dcookie.2:38
1195 msgid ""
1196 "Look up the full path of the directory entry specified by the value "
1197 "I<cookie>.  The cookie is an opaque identifier uniquely identifying a "
1198 "particular directory entry.  The buffer given is filled in with the full "
1199 "path of the directory entry."
1200 msgstr ""
1201
1202 #. type: Plain text
1203 #: build/C/man2/lookup_dcookie.2:43
1204 msgid ""
1205 "For B<lookup_dcookie>()  to return successfully, the kernel must still hold "
1206 "a cookie reference to the directory entry."
1207 msgstr ""
1208
1209 #. type: Plain text
1210 #: build/C/man2/lookup_dcookie.2:50
1211 msgid ""
1212 "On success, B<lookup_dcookie>()  returns the length of the path string "
1213 "copied into the buffer.  On error, -1 is returned, and I<errno> is set "
1214 "appropriately."
1215 msgstr ""
1216
1217 #. type: Plain text
1218 #: build/C/man2/lookup_dcookie.2:54
1219 msgid "The buffer was not valid."
1220 msgstr ""
1221
1222 #. type: Plain text
1223 #: build/C/man2/lookup_dcookie.2:58
1224 msgid ""
1225 "The kernel has no registered cookie/directory entry mappings at the time of "
1226 "lookup, or the cookie does not refer to a valid directory entry."
1227 msgstr ""
1228
1229 #. type: TP
1230 #: build/C/man2/lookup_dcookie.2:58
1231 #, no-wrap
1232 msgid "B<ENAMETOOLONG>"
1233 msgstr ""
1234
1235 #. type: Plain text
1236 #: build/C/man2/lookup_dcookie.2:61
1237 msgid "The name could not fit in the buffer."
1238 msgstr ""
1239
1240 #. type: TP
1241 #: build/C/man2/lookup_dcookie.2:61 build/C/man2/process_vm_readv.2:278 build/C/man2/sendfile.2:138 build/C/man2/splice.2:155 build/C/man2/tee.2:111 build/C/man2/vmsplice.2:135
1242 #, no-wrap
1243 msgid "B<ENOMEM>"
1244 msgstr ""
1245
1246 #. type: Plain text
1247 #: build/C/man2/lookup_dcookie.2:65
1248 msgid ""
1249 "The kernel could not allocate memory for the temporary buffer holding the "
1250 "path."
1251 msgstr ""
1252
1253 #. type: Plain text
1254 #: build/C/man2/lookup_dcookie.2:70
1255 msgid ""
1256 "The process does not have the capability B<CAP_SYS_ADMIN> required to look "
1257 "up cookie values."
1258 msgstr ""
1259
1260 #. type: TP
1261 #: build/C/man2/lookup_dcookie.2:70 build/C/man2/quotactl.2:474
1262 #, no-wrap
1263 msgid "B<ERANGE>"
1264 msgstr ""
1265
1266 #. type: Plain text
1267 #: build/C/man2/lookup_dcookie.2:73
1268 msgid "The buffer was not large enough to hold the path of the directory entry."
1269 msgstr ""
1270
1271 #. type: Plain text
1272 #: build/C/man2/lookup_dcookie.2:78
1273 msgid ""
1274 "Available since Linux 2.5.43.  The B<ENAMETOOLONG> error return was added in "
1275 "2.5.70."
1276 msgstr ""
1277
1278 #. type: Plain text
1279 #: build/C/man2/lookup_dcookie.2:81
1280 msgid "B<lookup_dcookie>()  is Linux-specific."
1281 msgstr ""
1282
1283 #. type: Plain text
1284 #: build/C/man2/lookup_dcookie.2:85
1285 msgid ""
1286 "B<lookup_dcookie>()  is a special-purpose system call, currently used only "
1287 "by the oprofile profiler.  It relies on a kernel driver to register cookies "
1288 "for directory entries."
1289 msgstr ""
1290
1291 #. type: Plain text
1292 #: build/C/man2/lookup_dcookie.2:88
1293 msgid ""
1294 "The path returned may be suffixed by the string \" (deleted)\" if the "
1295 "directory entry has been removed."
1296 msgstr ""
1297
1298 #. type: TH
1299 #: build/C/man2/modify_ldt.2:24
1300 #, no-wrap
1301 msgid "MODIFY_LDT"
1302 msgstr ""
1303
1304 #. type: Plain text
1305 #: build/C/man2/modify_ldt.2:27
1306 msgid "modify_ldt - get or set ldt"
1307 msgstr ""
1308
1309 #. type: Plain text
1310 #: build/C/man2/modify_ldt.2:30
1311 #, no-wrap
1312 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
1313 msgstr ""
1314
1315 #. type: Plain text
1316 #: build/C/man2/modify_ldt.2:32
1317 #, no-wrap
1318 msgid ""
1319 "B<int modify_ldt(int >I<func>B<, void *>I<ptr>B<, unsigned long "
1320 ">I<bytecount>B<);>\n"
1321 msgstr ""
1322
1323 #. type: Plain text
1324 #: build/C/man2/modify_ldt.2:41
1325 msgid ""
1326 "B<modify_ldt>()  reads or writes the local descriptor table (ldt) for a "
1327 "process.  The ldt is a per-process memory management table used by the i386 "
1328 "processor.  For more information on this table, see an Intel 386 processor "
1329 "handbook."
1330 msgstr ""
1331
1332 #. type: Plain text
1333 #: build/C/man2/modify_ldt.2:51
1334 msgid ""
1335 "When I<func> is 0, B<modify_ldt>()  reads the ldt into the memory pointed to "
1336 "by I<ptr>.  The number of bytes read is the smaller of I<bytecount> and the "
1337 "actual size of the ldt."
1338 msgstr ""
1339
1340 #
1341 #.  FIXME ? say something about func == 2 and func == 0x11?
1342 #.  In Linux 2.4, func == 2 returned "the default ldt"
1343 #.  In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
1344 #.  Linux 2.4 and 2.6 implement an operation for func == 0x11
1345 #. type: Plain text
1346 #: build/C/man2/modify_ldt.2:69
1347 msgid ""
1348 "When I<func> is 1, B<modify_ldt>()  modifies one ldt entry.  I<ptr> points "
1349 "to a I<user_desc> structure and I<bytecount> must equal the size of this "
1350 "structure."
1351 msgstr ""
1352
1353 #. type: Plain text
1354 #: build/C/man2/modify_ldt.2:73
1355 msgid "The I<user_desc> structure is defined in I<E<lt>asm/ldt.hE<gt>> as:"
1356 msgstr ""
1357
1358 #. type: Plain text
1359 #: build/C/man2/modify_ldt.2:87
1360 #, no-wrap
1361 msgid ""
1362 "struct user_desc {\n"
1363 "    unsigned int  entry_number;\n"
1364 "    unsigned long base_addr;\n"
1365 "    unsigned int  limit;\n"
1366 "    unsigned int  seg_32bit:1;\n"
1367 "    unsigned int  contents:2;\n"
1368 "    unsigned int  read_exec_only:1;\n"
1369 "    unsigned int  limit_in_pages:1;\n"
1370 "    unsigned int  seg_not_present:1;\n"
1371 "    unsigned int  useable:1;\n"
1372 "};\n"
1373 msgstr ""
1374
1375 #.  .PP
1376 #.  The ldt is specific for the calling process. Any attempts to change
1377 #.  the ldt to include the address space of another process or the kernel
1378 #.  will result in a segmentation violation when trying to access the memory
1379 #.  outside of the process address space. The memory protection is enforced
1380 #.  at the paging layer.
1381 #. type: Plain text
1382 #: build/C/man2/modify_ldt.2:98
1383 msgid "In Linux 2.4 and earlier, this structure was named I<modify_ldt_ldt_s>."
1384 msgstr ""
1385
1386 #. type: Plain text
1387 #: build/C/man2/modify_ldt.2:108
1388 msgid ""
1389 "On success, B<modify_ldt>()  returns either the actual number of bytes read "
1390 "(for reading)  or 0 (for writing).  On failure, B<modify_ldt>()  returns -1 "
1391 "and sets I<errno> to indicate the error."
1392 msgstr ""
1393
1394 #. type: Plain text
1395 #: build/C/man2/modify_ldt.2:113
1396 msgid "I<ptr> points outside the address space."
1397 msgstr ""
1398
1399 #. type: Plain text
1400 #: build/C/man2/modify_ldt.2:126
1401 msgid ""
1402 "I<ptr> is 0, or I<func> is 1 and I<bytecount> is not equal to the size of "
1403 "the structure I<modify_ldt_ldt_s>, or I<func> is 1 and the new ldt entry has "
1404 "invalid values."
1405 msgstr ""
1406
1407 #. type: Plain text
1408 #: build/C/man2/modify_ldt.2:130
1409 msgid "I<func> is neither 0 nor 1."
1410 msgstr ""
1411
1412 #. type: Plain text
1413 #: build/C/man2/modify_ldt.2:133
1414 msgid ""
1415 "This call is Linux-specific and should not be used in programs intended to "
1416 "be portable."
1417 msgstr ""
1418
1419 #. type: Plain text
1420 #: build/C/man2/modify_ldt.2:136 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:134
1421 msgid ""
1422 "Glibc does not provide a wrapper for this system call; call it using "
1423 "B<syscall>(2)."
1424 msgstr ""
1425
1426 #. type: Plain text
1427 #: build/C/man2/modify_ldt.2:138
1428 msgid "B<vm86>(2)"
1429 msgstr ""
1430
1431 #. type: TH
1432 #: build/C/man2/nfsservctl.2:8
1433 #, no-wrap
1434 msgid "NFSSERVCTL"
1435 msgstr ""
1436
1437 #. type: TH
1438 #: build/C/man2/nfsservctl.2:8
1439 #, no-wrap
1440 msgid "2013-09-17"
1441 msgstr ""
1442
1443 #. type: Plain text
1444 #: build/C/man2/nfsservctl.2:11
1445 msgid "nfsservctl - syscall interface to kernel nfs daemon"
1446 msgstr ""
1447
1448 #. type: Plain text
1449 #: build/C/man2/nfsservctl.2:14
1450 #, no-wrap
1451 msgid "B<#include E<lt>linux/nfsd/syscall.hE<gt>>\n"
1452 msgstr ""
1453
1454 #. type: Plain text
1455 #: build/C/man2/nfsservctl.2:17
1456 #, no-wrap
1457 msgid ""
1458 "B<long nfsservctl(int >I<cmd>B<, struct nfsctl_arg *>I<argp>B<,>\n"
1459 "B<                union nfsctl_res *>I<resp>B<);>\n"
1460 msgstr ""
1461
1462 #. type: Plain text
1463 #: build/C/man2/nfsservctl.2:21
1464 msgid "I<Note>: Since Linux 3.1, this system call no longer exists."
1465 msgstr ""
1466
1467 #. type: Plain text
1468 #: build/C/man2/nfsservctl.2:35
1469 #, no-wrap
1470 msgid ""
1471 "/*\n"
1472 " * These are the commands understood by nfsctl().\n"
1473 " */\n"
1474 "#define NFSCTL_SVC          0    /* This is a server process. */\n"
1475 "#define NFSCTL_ADDCLIENT    1    /* Add an NFS client. */\n"
1476 "#define NFSCTL_DELCLIENT    2    /* Remove an NFS client. */\n"
1477 "#define NFSCTL_EXPORT       3    /* Export a filesystem. */\n"
1478 "#define NFSCTL_UNEXPORT     4    /* Unexport a filesystem. */\n"
1479 "#define NFSCTL_UGIDUPDATE   5    /* Update a client's UID/GID map\n"
1480 "                                    (only in Linux 2.4.x and earlier). */\n"
1481 "#define NFSCTL_GETFH        6    /* Get a file handle (used by mountd)\n"
1482 "                                    (only in Linux 2.4.x and earlier). */\n"
1483 msgstr ""
1484
1485 #. type: Plain text
1486 #: build/C/man2/nfsservctl.2:47
1487 #, no-wrap
1488 msgid ""
1489 "struct nfsctl_arg {\n"
1490 "    int                       ca_version;     /* safeguard */\n"
1491 "    union {\n"
1492 "        struct nfsctl_svc     u_svc;\n"
1493 "        struct nfsctl_client  u_client;\n"
1494 "        struct nfsctl_export  u_export;\n"
1495 "        struct nfsctl_uidmap  u_umap;\n"
1496 "        struct nfsctl_fhparm  u_getfh;\n"
1497 "        unsigned int          u_debug;\n"
1498 "    } u;\n"
1499 "}\n"
1500 msgstr ""
1501
1502 #. type: Plain text
1503 #: build/C/man2/nfsservctl.2:52
1504 #, no-wrap
1505 msgid ""
1506 "union nfsctl_res {\n"
1507 "        struct knfs_fh          cr_getfh;\n"
1508 "        unsigned int            cr_debug;\n"
1509 "};\n"
1510 msgstr ""
1511
1512 #. type: Plain text
1513 #: build/C/man2/nfsservctl.2:58 build/C/man2/pivot_root.2:105 build/C/man2/vm86.2:59
1514 msgid ""
1515 "On success, zero is returned.  On error, -1 is returned, and I<errno> is set "
1516 "appropriately."
1517 msgstr ""
1518
1519 #. type: Plain text
1520 #: build/C/man2/nfsservctl.2:60
1521 msgid "This call is Linux-specific."
1522 msgstr ""
1523
1524 #. type: TH
1525 #: build/C/man2/outb.2:26
1526 #, no-wrap
1527 msgid "OUTB"
1528 msgstr ""
1529
1530 #. type: TH
1531 #: build/C/man2/outb.2:26
1532 #, no-wrap
1533 msgid "2012-12-31"
1534 msgstr ""
1535
1536 #. type: Plain text
1537 #: build/C/man2/outb.2:31
1538 msgid ""
1539 "outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, "
1540 "outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O"
1541 msgstr ""
1542
1543 #. type: Plain text
1544 #: build/C/man2/outb.2:34
1545 #, no-wrap
1546 msgid "B<#include E<lt>sys/io.hE<gt>>\n"
1547 msgstr ""
1548
1549 #. type: Plain text
1550 #: build/C/man2/outb.2:41
1551 #, no-wrap
1552 msgid ""
1553 "B<unsigned char inb(unsigned short int >I<port>B<);>\n"
1554 "B<unsigned char inb_p(unsigned short int >I<port>B<);>\n"
1555 "B<unsigned short int inw(unsigned short int >I<port>B<);>\n"
1556 "B<unsigned short int inw_p(unsigned short int >I<port>B<);>\n"
1557 "B<unsigned int inl(unsigned short int >I<port>B<);>\n"
1558 "B<unsigned int inl_p(unsigned short int >I<port>B<);>\n"
1559 msgstr ""
1560
1561 #. type: Plain text
1562 #: build/C/man2/outb.2:48
1563 #, no-wrap
1564 msgid ""
1565 "B<void outb(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1566 "B<void outb_p(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1567 "B<void outw(unsigned short int >I<value>B<, unsigned short int "
1568 ">I<port>B<);>\n"
1569 "B<void outw_p(unsigned short int >I<value>B<, unsigned short int "
1570 ">I<port>B<);>\n"
1571 "B<void outl(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1572 "B<void outl_p(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1573 msgstr ""
1574
1575 #. type: Plain text
1576 #: build/C/man2/outb.2:61
1577 #, no-wrap
1578 msgid ""
1579 "B<void insb(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1580 "B<           unsigned long int >I<count>B<);>\n"
1581 "B<void insw(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1582 "B<           unsigned long int >I<count>B<);>\n"
1583 "B<void insl(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1584 "B<           unsigned long int >I<count>B<);>\n"
1585 "B<void outsb(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1586 "B<           unsigned long int >I<count>B<);>\n"
1587 "B<void outsw(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1588 "B<           unsigned long int >I<count>B<);>\n"
1589 "B<void outsl(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1590 "B<           unsigned long int >I<count>B<);>\n"
1591 msgstr ""
1592
1593 #. type: Plain text
1594 #: build/C/man2/outb.2:67
1595 msgid ""
1596 "This family of functions is used to do low-level port input and output.  The "
1597 "out* functions do port output, the in* functions do port input; the b-suffix "
1598 "functions are byte-width and the w-suffix functions word-width; the "
1599 "_p-suffix functions pause until the I/O completes."
1600 msgstr ""
1601
1602 #.  , given the following information
1603 #.  in addition to that given in
1604 #.  .BR outb (9).
1605 #. type: Plain text
1606 #: build/C/man2/outb.2:73
1607 msgid ""
1608 "They are primarily designed for internal kernel use, but can be used from "
1609 "user space."
1610 msgstr ""
1611
1612 #. type: Plain text
1613 #: build/C/man2/outb.2:78
1614 msgid ""
1615 "You must compile with B<-O> or B<-O2> or similar.  The functions are defined "
1616 "as inline macros, and will not be substituted in without optimization "
1617 "enabled, causing unresolved references at link time."
1618 msgstr ""
1619
1620 #. type: Plain text
1621 #: build/C/man2/outb.2:87
1622 msgid ""
1623 "You use B<ioperm>(2)  or alternatively B<iopl>(2)  to tell the kernel to "
1624 "allow the user space application to access the I/O ports in question.  "
1625 "Failure to do this will cause the application to receive a segmentation "
1626 "fault."
1627 msgstr ""
1628
1629 #. type: Plain text
1630 #: build/C/man2/outb.2:96
1631 msgid ""
1632 "B<outb>()  and friends are hardware-specific.  The I<value> argument is "
1633 "passed first and the I<port> argument is passed second, which is the "
1634 "opposite order from most DOS implementations."
1635 msgstr ""
1636
1637 #. type: Plain text
1638 #: build/C/man2/outb.2:99
1639 msgid "B<ioperm>(2), B<iopl>(2)"
1640 msgstr ""
1641
1642 #. type: TH
1643 #: build/C/man2/pciconfig_read.2:8
1644 #, no-wrap
1645 msgid "PCICONFIG_READ"
1646 msgstr ""
1647
1648 #. type: TH
1649 #: build/C/man2/pciconfig_read.2:8
1650 #, no-wrap
1651 msgid "2003-07-14"
1652 msgstr ""
1653
1654 #. type: Plain text
1655 #: build/C/man2/pciconfig_read.2:11
1656 msgid ""
1657 "pciconfig_read, pciconfig_write, pciconfig_iobase - pci device information "
1658 "handling"
1659 msgstr ""
1660
1661 #. type: Plain text
1662 #: build/C/man2/pciconfig_read.2:14
1663 #, no-wrap
1664 msgid "B<#include E<lt>pci.hE<gt>>\n"
1665 msgstr ""
1666
1667 #. type: Plain text
1668 #: build/C/man2/pciconfig_read.2:21
1669 #, no-wrap
1670 msgid ""
1671 "B<int pciconfig_read(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1672 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1673 "*>I<buf>B<);>\n"
1674 "B<int pciconfig_write(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1675 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1676 "*>I<buf>B<);>\n"
1677 "B<int pciconfig_iobase(long >I<which>B<, unsigned long >I<bus>B<,>\n"
1678 "B<          unsigned long >I<devfn>B<);>\n"
1679 msgstr ""
1680
1681 #. type: Plain text
1682 #: build/C/man2/pciconfig_read.2:27
1683 msgid ""
1684 "Most of the interaction with PCI devices is already handled by the kernel "
1685 "PCI layer, and thus these calls should not normally need to be accessed from "
1686 "user space."
1687 msgstr ""
1688
1689 #. type: TP
1690 #: build/C/man2/pciconfig_read.2:27 build/C/man2/pciconfig_read.2:51
1691 #, no-wrap
1692 msgid "B<pciconfig_read>()"
1693 msgstr ""
1694
1695 #. type: Plain text
1696 #: build/C/man2/pciconfig_read.2:36
1697 msgid "Reads to I<buf> from device I<dev> at offset I<off> value."
1698 msgstr ""
1699
1700 #. type: TP
1701 #: build/C/man2/pciconfig_read.2:36 build/C/man2/pciconfig_read.2:57
1702 #, no-wrap
1703 msgid "B<pciconfig_write>()"
1704 msgstr ""
1705
1706 #. type: Plain text
1707 #: build/C/man2/pciconfig_read.2:45
1708 msgid "Writes from I<buf> to device I<dev> at offset I<off> value."
1709 msgstr ""
1710
1711 #. type: TP
1712 #: build/C/man2/pciconfig_read.2:45 build/C/man2/pciconfig_read.2:63
1713 #, no-wrap
1714 msgid "B<pciconfig_iobase>()"
1715 msgstr ""
1716
1717 #. type: Plain text
1718 #: build/C/man2/pciconfig_read.2:50
1719 msgid ""
1720 "You pass it a bus/devfn pair and get a physical address for either the "
1721 "memory offset (for things like prep, this is 0xc0000000), the IO base for "
1722 "PIO cycles, or the ISA holes if any."
1723 msgstr ""
1724
1725 #. type: Plain text
1726 #: build/C/man2/pciconfig_read.2:57 build/C/man2/pciconfig_read.2:63
1727 msgid ""
1728 "On success zero is returned.  On error, -1 is returned and I<errno> is set "
1729 "appropriately."
1730 msgstr ""
1731
1732 #. type: Plain text
1733 #: build/C/man2/pciconfig_read.2:77
1734 msgid ""
1735 "Returns information on locations of various I/O regions in physical memory "
1736 "according to the I<which> value.  Values for I<which> are: "
1737 "B<IOBASE_BRIDGE_NUMBER>, B<IOBASE_MEMORY>, B<IOBASE_IO>, B<IOBASE_ISA_IO>, "
1738 "B<IOBASE_ISA_MEM>."
1739 msgstr ""
1740
1741 #. type: Plain text
1742 #: build/C/man2/pciconfig_read.2:84
1743 msgid "I<len> value is invalid.  This does not apply to B<pciconfig_iobase>()."
1744 msgstr ""
1745
1746 #. type: TP
1747 #: build/C/man2/pciconfig_read.2:84 build/C/man2/ptrace.2:1886 build/C/man2/sendfile.2:134
1748 #, no-wrap
1749 msgid "B<EIO>"
1750 msgstr ""
1751
1752 #. type: Plain text
1753 #: build/C/man2/pciconfig_read.2:87
1754 msgid "I/O error."
1755 msgstr ""
1756
1757 #. type: TP
1758 #: build/C/man2/pciconfig_read.2:87 build/C/man2/perf_event_open.2:2460
1759 #, no-wrap
1760 msgid "B<ENODEV>"
1761 msgstr ""
1762
1763 #. type: Plain text
1764 #: build/C/man2/pciconfig_read.2:93
1765 msgid ""
1766 "For B<pciconfig_iobase>(), \"hose\" value is NULL.  For the other calls, "
1767 "could not find a slot."
1768 msgstr ""
1769
1770 #. type: Plain text
1771 #: build/C/man2/pciconfig_read.2:98
1772 msgid "The system has not implemented these calls (B<CONFIG_PCI> not defined)."
1773 msgstr ""
1774
1775 #. type: TP
1776 #: build/C/man2/pciconfig_read.2:98 build/C/man2/perf_event_open.2:2488
1777 #, no-wrap
1778 msgid "B<EOPNOTSUPP>"
1779 msgstr ""
1780
1781 #. type: Plain text
1782 #: build/C/man2/pciconfig_read.2:105
1783 msgid ""
1784 "This return value is valid only for B<pciconfig_iobase>().  It is returned "
1785 "if the value for I<which> is invalid."
1786 msgstr ""
1787
1788 #. type: Plain text
1789 #: build/C/man2/pciconfig_read.2:112
1790 msgid ""
1791 "User does not have the B<CAP_SYS_ADMIN> capability.  This does not apply to "
1792 "B<pciconfig_iobase>()."
1793 msgstr ""
1794
1795 #. type: Plain text
1796 #: build/C/man2/pciconfig_read.2:114
1797 msgid "These calls are Linux-specific, available since Linux 2.0.26/2.1.11."
1798 msgstr ""
1799
1800 #. type: Plain text
1801 #: build/C/man2/pciconfig_read.2:116
1802 msgid "B<capabilities>(7)"
1803 msgstr ""
1804
1805 #. type: TH
1806 #: build/C/man2/perf_event_open.2:27
1807 #, no-wrap
1808 msgid "PERF_EVENT_OPEN"
1809 msgstr ""
1810
1811 #. type: TH
1812 #: build/C/man2/perf_event_open.2:27
1813 #, no-wrap
1814 msgid "2014-04-17"
1815 msgstr ""
1816
1817 #. type: Plain text
1818 #: build/C/man2/perf_event_open.2:30
1819 msgid "perf_event_open - set up performance monitoring"
1820 msgstr ""
1821
1822 #. type: Plain text
1823 #: build/C/man2/perf_event_open.2:34
1824 #, no-wrap
1825 msgid ""
1826 "B<#include E<lt>linux/perf_event.hE<gt>>\n"
1827 "B<#include E<lt>linux/hw_breakpoint.hE<gt>>\n"
1828 msgstr ""
1829
1830 #. type: Plain text
1831 #: build/C/man2/perf_event_open.2:38
1832 #, no-wrap
1833 msgid ""
1834 "B<int perf_event_open(struct perf_event_attr *>I<attr>B<,>\n"
1835 "B<                    pid_t >I<pid>B<, int >I<cpu>B<, int >I<group_fd>B<,>\n"
1836 "B<                    unsigned long >I<flags>B<);>\n"
1837 msgstr ""
1838
1839 #. type: Plain text
1840 #: build/C/man2/perf_event_open.2:47
1841 msgid ""
1842 "Given a list of parameters, B<perf_event_open>()  returns a file descriptor, "
1843 "for use in subsequent system calls (B<read>(2), B<mmap>(2), B<prctl>(2), "
1844 "B<fcntl>(2), etc.)."
1845 msgstr ""
1846
1847 #. type: Plain text
1848 #: build/C/man2/perf_event_open.2:55
1849 msgid ""
1850 "A call to B<perf_event_open>()  creates a file descriptor that allows "
1851 "measuring performance information.  Each file descriptor corresponds to one "
1852 "event that is measured; these can be grouped together to measure multiple "
1853 "events simultaneously."
1854 msgstr ""
1855
1856 #. type: Plain text
1857 #: build/C/man2/perf_event_open.2:62
1858 msgid ""
1859 "Events can be enabled and disabled in two ways: via B<ioctl>(2)  and via "
1860 "B<prctl>(2).  When an event is disabled it does not count or generate "
1861 "overflows but does continue to exist and maintain its count value."
1862 msgstr ""
1863
1864 #. type: Plain text
1865 #: build/C/man2/perf_event_open.2:76
1866 msgid ""
1867 "Events come in two flavors: counting and sampled.  A I<counting> event is "
1868 "one that is used for counting the aggregate number of events that occur.  In "
1869 "general, counting event results are gathered with a B<read>(2)  call.  A "
1870 "I<sampling> event periodically writes measurements to a buffer that can then "
1871 "be accessed via B<mmap>(2)."
1872 msgstr ""
1873
1874 #. type: SS
1875 #: build/C/man2/perf_event_open.2:76
1876 #, no-wrap
1877 msgid "Arguments"
1878 msgstr ""
1879
1880 #. type: Plain text
1881 #: build/C/man2/perf_event_open.2:83
1882 msgid ""
1883 "The I<pid> and I<cpu> arguments allow specifying which process and CPU to "
1884 "monitor:"
1885 msgstr ""
1886
1887 #. type: TP
1888 #: build/C/man2/perf_event_open.2:83
1889 #, no-wrap
1890 msgid "B<pid == 0> and B<cpu == -1>"
1891 msgstr ""
1892
1893 #. type: Plain text
1894 #: build/C/man2/perf_event_open.2:86
1895 msgid "This measures the calling process/thread on any CPU."
1896 msgstr ""
1897
1898 #. type: TP
1899 #: build/C/man2/perf_event_open.2:86
1900 #, no-wrap
1901 msgid "B<pid == 0> and B<cpu E<gt>= 0>"
1902 msgstr ""
1903
1904 #. type: Plain text
1905 #: build/C/man2/perf_event_open.2:90
1906 msgid ""
1907 "This measures the calling process/thread only when running on the specified "
1908 "CPU."
1909 msgstr ""
1910
1911 #. type: TP
1912 #: build/C/man2/perf_event_open.2:90
1913 #, no-wrap
1914 msgid "B<pid E<gt> 0> and B<cpu == -1>"
1915 msgstr ""
1916
1917 #. type: Plain text
1918 #: build/C/man2/perf_event_open.2:93
1919 msgid "This measures the specified process/thread on any CPU."
1920 msgstr ""
1921
1922 #. type: TP
1923 #: build/C/man2/perf_event_open.2:93
1924 #, no-wrap
1925 msgid "B<pid E<gt> 0> and B<cpu E<gt>= 0>"
1926 msgstr ""
1927
1928 #. type: Plain text
1929 #: build/C/man2/perf_event_open.2:97
1930 msgid ""
1931 "This measures the specified process/thread only when running on the "
1932 "specified CPU."
1933 msgstr ""
1934
1935 #. type: TP
1936 #: build/C/man2/perf_event_open.2:97
1937 #, no-wrap
1938 msgid "B<pid == -1> and B<cpu E<gt>= 0>"
1939 msgstr ""
1940
1941 #. type: Plain text
1942 #: build/C/man2/perf_event_open.2:105
1943 msgid ""
1944 "This measures all processes/threads on the specified CPU.  This requires "
1945 "B<CAP_SYS_ADMIN> capability or a I</proc/sys/kernel/perf_event_paranoid> "
1946 "value of less than 1."
1947 msgstr ""
1948
1949 #. type: TP
1950 #: build/C/man2/perf_event_open.2:105
1951 #, no-wrap
1952 msgid "B<pid == -1> and B<cpu == -1>"
1953 msgstr ""
1954
1955 #. type: Plain text
1956 #: build/C/man2/perf_event_open.2:108
1957 msgid "This setting is invalid and will return an error."
1958 msgstr ""
1959
1960 #. type: Plain text
1961 #: build/C/man2/perf_event_open.2:130
1962 msgid ""
1963 "The I<group_fd> argument allows event groups to be created.  An event group "
1964 "has one event which is the group leader.  The leader is created first, with "
1965 "I<group_fd> = -1.  The rest of the group members are created with subsequent "
1966 "B<perf_event_open>()  calls with I<group_fd> being set to the file "
1967 "descriptor of the group leader.  (A single event on its own is created with "
1968 "I<group_fd> = -1 and is considered to be a group with only 1 member.)  An "
1969 "event group is scheduled onto the CPU as a unit: it will be put onto the CPU "
1970 "only if all of the events in the group can be put onto the CPU.  This means "
1971 "that the values of the member events can be meaningfully compared\\(emadded, "
1972 "divided (to get ratios), and so on\\(emwith each other, since they have "
1973 "counted events for the same set of executed instructions."
1974 msgstr ""
1975
1976 #. type: Plain text
1977 #: build/C/man2/perf_event_open.2:134
1978 msgid ""
1979 "The I<flags> argument is formed by ORing together zero or more of the "
1980 "following values:"
1981 msgstr ""
1982
1983 #. type: TP
1984 #: build/C/man2/perf_event_open.2:134
1985 #, no-wrap
1986 msgid "B<PERF_FLAG_FD_CLOEXEC> (since Linux 3.14)."
1987 msgstr ""
1988
1989 #. type: Plain text
1990 #: build/C/man2/perf_event_open.2:150
1991 msgid ""
1992 "This flag enables the close-on-exec flag for the created event file "
1993 "descriptor, so that the file descriptor is automatically closed on "
1994 "B<execve>(2).  Setting the close-on-exec flags at creation time, rather than "
1995 "later with B<fcntl>(2), avoids potential race conditions where the calling "
1996 "thread invokes B<perf_event_open>()  and B<fcntl>(2)  at the same time as "
1997 "another thread calls B<fork>(2)  then B<execve>(2)."
1998 msgstr ""
1999
2000 #. type: TP
2001 #: build/C/man2/perf_event_open.2:150
2002 #, no-wrap
2003 msgid "B<PERF_FLAG_FD_NO_GROUP>"
2004 msgstr ""
2005
2006 #.  FIXME The following sentence is unclear
2007 #.  FIXME So, why is it useful?
2008 #. type: Plain text
2009 #: build/C/man2/perf_event_open.2:157
2010 msgid ""
2011 "This flag allows creating an event as part of an event group but having no "
2012 "group leader.  It is unclear why this is useful."
2013 msgstr ""
2014
2015 #. type: TP
2016 #: build/C/man2/perf_event_open.2:157
2017 #, no-wrap
2018 msgid "B<PERF_FLAG_FD_OUTPUT>"
2019 msgstr ""
2020
2021 #. type: Plain text
2022 #: build/C/man2/perf_event_open.2:160
2023 msgid "This flag reroutes the output from an event to the group leader."
2024 msgstr ""
2025
2026 #. type: TP
2027 #: build/C/man2/perf_event_open.2:160
2028 #, no-wrap
2029 msgid "B<PERF_FLAG_PID_CGROUP> (since Linux 2.6.39)."
2030 msgstr ""
2031
2032 #. type: Plain text
2033 #: build/C/man2/perf_event_open.2:183
2034 msgid ""
2035 "This flag activates per-container system-wide monitoring.  A container is an "
2036 "abstraction that isolates a set of resources for finer-grained control "
2037 "(CPUs, memory, etc.).  In this mode, the event is measured only if the "
2038 "thread running on the monitored CPU belongs to the designated container "
2039 "(cgroup).  The cgroup is identified by passing a file descriptor opened on "
2040 "its directory in the cgroupfs filesystem.  For instance, if the cgroup to "
2041 "monitor is called I<test>, then a file descriptor opened on "
2042 "I</dev/cgroup/test> (assuming cgroupfs is mounted on I</dev/cgroup>)  must "
2043 "be passed as the I<pid> parameter.  cgroup monitoring is available only for "
2044 "system-wide events and may therefore require extra permissions."
2045 msgstr ""
2046
2047 #. type: Plain text
2048 #: build/C/man2/perf_event_open.2:188
2049 msgid ""
2050 "The I<perf_event_attr> structure provides detailed configuration information "
2051 "for the event being created."
2052 msgstr ""
2053
2054 #. type: Plain text
2055 #: build/C/man2/perf_event_open.2:195
2056 #, no-wrap
2057 msgid ""
2058 "struct perf_event_attr {\n"
2059 "    __u32 type;         /* Type of event */\n"
2060 "    __u32 size;         /* Size of attribute structure */\n"
2061 "    __u64 config;       /* Type-specific configuration */\n"
2062 msgstr ""
2063
2064 #. type: Plain text
2065 #: build/C/man2/perf_event_open.2:200
2066 #, no-wrap
2067 msgid ""
2068 "    union {\n"
2069 "        __u64 sample_period;    /* Period of sampling */\n"
2070 "        __u64 sample_freq;      /* Frequency of sampling */\n"
2071 "    };\n"
2072 msgstr ""
2073
2074 #. type: Plain text
2075 #: build/C/man2/perf_event_open.2:203
2076 #, no-wrap
2077 msgid ""
2078 "    __u64 sample_type;  /* Specifies values included in sample */\n"
2079 "    __u64 read_format;  /* Specifies values returned in read */\n"
2080 msgstr ""
2081
2082 #. type: Plain text
2083 #: build/C/man2/perf_event_open.2:229
2084 #, no-wrap
2085 msgid ""
2086 "    __u64 disabled       : 1,   /* off by default */\n"
2087 "          inherit        : 1,   /* children inherit it */\n"
2088 "          pinned         : 1,   /* must always be on PMU */\n"
2089 "          exclusive      : 1,   /* only group on PMU */\n"
2090 "          exclude_user   : 1,   /* don't count user */\n"
2091 "          exclude_kernel : 1,   /* don't count kernel */\n"
2092 "          exclude_hv     : 1,   /* don't count hypervisor */\n"
2093 "          exclude_idle   : 1,   /* don't count when idle */\n"
2094 "          mmap           : 1,   /* include mmap data */\n"
2095 "          comm           : 1,   /* include comm data */\n"
2096 "          freq           : 1,   /* use freq, not period */\n"
2097 "          inherit_stat   : 1,   /* per task counts */\n"
2098 "          enable_on_exec : 1,   /* next exec enables */\n"
2099 "          task           : 1,   /* trace fork/exit */\n"
2100 "          watermark      : 1,   /* wakeup_watermark */\n"
2101 "          precise_ip     : 2,   /* skid constraint */\n"
2102 "          mmap_data      : 1,   /* non-exec mmap data */\n"
2103 "          sample_id_all  : 1,   /* sample_type all events */\n"
2104 "          exclude_host   : 1,   /* don't count in host */\n"
2105 "          exclude_guest  : 1,   /* don't count in guest */\n"
2106 "          exclude_callchain_kernel : 1,\n"
2107 "                                /* exclude kernel callchains */\n"
2108 "          exclude_callchain_user   : 1,\n"
2109 "                                /* exclude user callchains */\n"
2110 "          __reserved_1   : 41;\n"
2111 msgstr ""
2112
2113 #. type: Plain text
2114 #: build/C/man2/perf_event_open.2:234
2115 #, no-wrap
2116 msgid ""
2117 "    union {\n"
2118 "        __u32 wakeup_events;    /* wakeup every n events */\n"
2119 "        __u32 wakeup_watermark; /* bytes before wakeup */\n"
2120 "    };\n"
2121 msgstr ""
2122
2123 #. type: Plain text
2124 #: build/C/man2/perf_event_open.2:236
2125 #, no-wrap
2126 msgid "    __u32     bp_type;          /* breakpoint type */\n"
2127 msgstr ""
2128
2129 #. type: Plain text
2130 #: build/C/man2/perf_event_open.2:241
2131 #, no-wrap
2132 msgid ""
2133 "    union {\n"
2134 "        __u64 bp_addr;          /* breakpoint address */\n"
2135 "        __u64 config1;          /* extension of config */\n"
2136 "    };\n"
2137 msgstr ""
2138
2139 #. type: Plain text
2140 #: build/C/man2/perf_event_open.2:251
2141 #, no-wrap
2142 msgid ""
2143 "    union {\n"
2144 "        __u64 bp_len;           /* breakpoint length */\n"
2145 "        __u64 config2;          /* extension of config1 */\n"
2146 "    };\n"
2147 "    __u64 branch_sample_type;   /* enum perf_branch_sample_type */\n"
2148 "    __u64 sample_regs_user;     /* user regs to dump on samples */\n"
2149 "    __u32 sample_stack_user;    /* size of stack to dump on\n"
2150 "                                   samples */\n"
2151 "    __u32 __reserved_2;         /* Align to u64 */\n"
2152 msgstr ""
2153
2154 #. type: Plain text
2155 #: build/C/man2/perf_event_open.2:253
2156 #, no-wrap
2157 msgid "};\n"
2158 msgstr ""
2159
2160 #. type: Plain text
2161 #: build/C/man2/perf_event_open.2:259
2162 msgid ""
2163 "The fields of the I<perf_event_attr> structure are described in more detail "
2164 "below:"
2165 msgstr ""
2166
2167 #. type: TP
2168 #: build/C/man2/perf_event_open.2:259 build/C/man2/perf_event_open.2:1556
2169 #, no-wrap
2170 msgid "I<type>"
2171 msgstr ""
2172
2173 #. type: Plain text
2174 #: build/C/man2/perf_event_open.2:263
2175 msgid ""
2176 "This field specifies the overall event type.  It has one of the following "
2177 "values:"
2178 msgstr ""
2179
2180 #. type: TP
2181 #: build/C/man2/perf_event_open.2:264
2182 #, no-wrap
2183 msgid "B<PERF_TYPE_HARDWARE>"
2184 msgstr ""
2185
2186 #. type: Plain text
2187 #: build/C/man2/perf_event_open.2:271
2188 msgid ""
2189 "This indicates one of the \"generalized\" hardware events provided by the "
2190 "kernel.  See the I<config> field definition for more details."
2191 msgstr ""
2192
2193 #. type: TP
2194 #: build/C/man2/perf_event_open.2:271
2195 #, no-wrap
2196 msgid "B<PERF_TYPE_SOFTWARE>"
2197 msgstr ""
2198
2199 #. type: Plain text
2200 #: build/C/man2/perf_event_open.2:275
2201 msgid ""
2202 "This indicates one of the software-defined events provided by the kernel "
2203 "(even if no hardware support is available)."
2204 msgstr ""
2205
2206 #. type: TP
2207 #: build/C/man2/perf_event_open.2:275
2208 #, no-wrap
2209 msgid "B<PERF_TYPE_TRACEPOINT>"
2210 msgstr ""
2211
2212 #. type: Plain text
2213 #: build/C/man2/perf_event_open.2:279
2214 msgid ""
2215 "This indicates a tracepoint provided by the kernel tracepoint "
2216 "infrastructure."
2217 msgstr ""
2218
2219 #. type: TP
2220 #: build/C/man2/perf_event_open.2:279
2221 #, no-wrap
2222 msgid "B<PERF_TYPE_HW_CACHE>"
2223 msgstr ""
2224
2225 #. type: Plain text
2226 #: build/C/man2/perf_event_open.2:285
2227 msgid ""
2228 "This indicates a hardware cache event.  This has a special encoding, "
2229 "described in the I<config> field definition."
2230 msgstr ""
2231
2232 #. type: TP
2233 #: build/C/man2/perf_event_open.2:285
2234 #, no-wrap
2235 msgid "B<PERF_TYPE_RAW>"
2236 msgstr ""
2237
2238 #. type: Plain text
2239 #: build/C/man2/perf_event_open.2:289
2240 msgid ""
2241 "This indicates a \"raw\" implementation-specific event in the I<config> "
2242 "field."
2243 msgstr ""
2244
2245 #. type: TP
2246 #: build/C/man2/perf_event_open.2:289
2247 #, no-wrap
2248 msgid "B<PERF_TYPE_BREAKPOINT> (since Linux 2.6.33)"
2249 msgstr ""
2250
2251 #. type: Plain text
2252 #: build/C/man2/perf_event_open.2:294
2253 msgid ""
2254 "This indicates a hardware breakpoint as provided by the CPU.  Breakpoints "
2255 "can be read/write accesses to an address as well as execution of an "
2256 "instruction address."
2257 msgstr ""
2258
2259 #. type: TP
2260 #: build/C/man2/perf_event_open.2:294
2261 #, no-wrap
2262 msgid "dynamic PMU"
2263 msgstr ""
2264
2265 #. type: Plain text
2266 #: build/C/man2/perf_event_open.2:313
2267 msgid ""
2268 "Since Linux 2.6.39, B<perf_event_open>()  can support multiple PMUs.  To "
2269 "enable this, a value exported by the kernel can be used in the I<type> field "
2270 "to indicate which PMU to use.  The value to use can be found in the sysfs "
2271 "filesystem: there is a subdirectory per PMU instance under "
2272 "I</sys/bus/event_source/devices>.  In each subdirectory there is a I<type> "
2273 "file whose content is an integer that can be used in the I<type> field.  For "
2274 "instance, I</sys/bus/event_source/devices/cpu/type> contains the value for "
2275 "the core CPU PMU, which is usually 4."
2276 msgstr ""
2277
2278 #. type: TP
2279 #: build/C/man2/perf_event_open.2:314 build/C/man2/perf_event_open.2:1504
2280 #, no-wrap
2281 msgid "I<size>"
2282 msgstr ""
2283
2284 #. type: Plain text
2285 #: build/C/man2/perf_event_open.2:323
2286 msgid ""
2287 "The size of the I<perf_event_attr> structure for forward/backward "
2288 "compatibility.  Set this using I<sizeof(struct perf_event_attr)> to allow "
2289 "the kernel to see the struct size at the time of compilation."
2290 msgstr ""
2291
2292 #. type: Plain text
2293 #: build/C/man2/perf_event_open.2:338
2294 msgid ""
2295 "The related define B<PERF_ATTR_SIZE_VER0> is set to 64; this was the size of "
2296 "the first published struct.  B<PERF_ATTR_SIZE_VER1> is 72, corresponding to "
2297 "the addition of breakpoints in Linux 2.6.33.  B<PERF_ATTR_SIZE_VER2> is 80 "
2298 "corresponding to the addition of branch sampling in Linux 3.4.  "
2299 "B<PERF_ATR_SIZE_VER3> is 96 corresponding to the addition of "
2300 "I<sample_regs_user> and I<sample_stack_user> in Linux 3.7."
2301 msgstr ""
2302
2303 #. type: TP
2304 #: build/C/man2/perf_event_open.2:338
2305 #, no-wrap
2306 msgid "I<config>"
2307 msgstr ""
2308
2309 #. type: Plain text
2310 #: build/C/man2/perf_event_open.2:349
2311 msgid ""
2312 "This specifies which event you want, in conjunction with the I<type> field.  "
2313 "The I<config1> and I<config2> fields are also taken into account in cases "
2314 "where 64 bits is not enough to fully specify the event.  The encoding of "
2315 "these fields are event dependent."
2316 msgstr ""
2317
2318 #. type: Plain text
2319 #: build/C/man2/perf_event_open.2:355
2320 msgid ""
2321 "The most significant bit (bit 63) of I<config> signifies CPU-specific (raw) "
2322 "counter configuration data; if the most significant bit is unset, the next 7 "
2323 "bits are an event type and the rest of the bits are the event identifier."
2324 msgstr ""
2325
2326 #. type: Plain text
2327 #: build/C/man2/perf_event_open.2:366
2328 msgid ""
2329 "There are various ways to set the I<config> field that are dependent on the "
2330 "value of the previously described I<type> field.  What follows are various "
2331 "possible settings for I<config> separated out by I<type>."
2332 msgstr ""
2333
2334 #. type: Plain text
2335 #: build/C/man2/perf_event_open.2:376
2336 msgid ""
2337 "If I<type> is B<PERF_TYPE_HARDWARE>, we are measuring one of the generalized "
2338 "hardware CPU events.  Not all of these are available on all platforms.  Set "
2339 "I<config> to one of the following:"
2340 msgstr ""
2341
2342 #. type: TP
2343 #: build/C/man2/perf_event_open.2:377
2344 #, no-wrap
2345 msgid "B<PERF_COUNT_HW_CPU_CYCLES>"
2346 msgstr ""
2347
2348 #. type: Plain text
2349 #: build/C/man2/perf_event_open.2:381
2350 msgid "Total cycles.  Be wary of what happens during CPU frequency scaling."
2351 msgstr ""
2352
2353 #. type: TP
2354 #: build/C/man2/perf_event_open.2:381
2355 #, no-wrap
2356 msgid "B<PERF_COUNT_HW_INSTRUCTIONS>"
2357 msgstr ""
2358
2359 #. type: Plain text
2360 #: build/C/man2/perf_event_open.2:386
2361 msgid ""
2362 "Retired instructions.  Be careful, these can be affected by various issues, "
2363 "most notably hardware interrupt counts."
2364 msgstr ""
2365
2366 #. type: TP
2367 #: build/C/man2/perf_event_open.2:386
2368 #, no-wrap
2369 msgid "B<PERF_COUNT_HW_CACHE_REFERENCES>"
2370 msgstr ""
2371
2372 #. type: Plain text
2373 #: build/C/man2/perf_event_open.2:393
2374 msgid ""
2375 "Cache accesses.  Usually this indicates Last Level Cache accesses but this "
2376 "may vary depending on your CPU.  This may include prefetches and coherency "
2377 "messages; again this depends on the design of your CPU."
2378 msgstr ""
2379
2380 #. type: TP
2381 #: build/C/man2/perf_event_open.2:393
2382 #, no-wrap
2383 msgid "B<PERF_COUNT_HW_CACHE_MISSES>"
2384 msgstr ""
2385
2386 #. type: Plain text
2387 #: build/C/man2/perf_event_open.2:400
2388 msgid ""
2389 "Cache misses.  Usually this indicates Last Level Cache misses; this is "
2390 "intended to be used in conjunction with the "
2391 "B<PERF_COUNT_HW_CACHE_REFERENCES> event to calculate cache miss rates."
2392 msgstr ""
2393
2394 #. type: TP
2395 #: build/C/man2/perf_event_open.2:400
2396 #, no-wrap
2397 msgid "B<PERF_COUNT_HW_BRANCH_INSTRUCTIONS>"
2398 msgstr ""
2399
2400 #. type: Plain text
2401 #: build/C/man2/perf_event_open.2:405
2402 msgid ""
2403 "Retired branch instructions.  Prior to Linux 2.6.34, this used the wrong "
2404 "event on AMD processors."
2405 msgstr ""
2406
2407 #. type: TP
2408 #: build/C/man2/perf_event_open.2:405
2409 #, no-wrap
2410 msgid "B<PERF_COUNT_HW_BRANCH_MISSES>"
2411 msgstr ""
2412
2413 #. type: Plain text
2414 #: build/C/man2/perf_event_open.2:408
2415 msgid "Mispredicted branch instructions."
2416 msgstr ""
2417
2418 #. type: TP
2419 #: build/C/man2/perf_event_open.2:408
2420 #, no-wrap
2421 msgid "B<PERF_COUNT_HW_BUS_CYCLES>"
2422 msgstr ""
2423
2424 #. type: Plain text
2425 #: build/C/man2/perf_event_open.2:411
2426 msgid "Bus cycles, which can be different from total cycles."
2427 msgstr ""
2428
2429 #. type: TP
2430 #: build/C/man2/perf_event_open.2:411
2431 #, no-wrap
2432 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_FRONTEND> (since Linux 3.0)"
2433 msgstr ""
2434
2435 #. type: Plain text
2436 #: build/C/man2/perf_event_open.2:414
2437 msgid "Stalled cycles during issue."
2438 msgstr ""
2439
2440 #. type: TP
2441 #: build/C/man2/perf_event_open.2:414
2442 #, no-wrap
2443 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_BACKEND> (since Linux 3.0)"
2444 msgstr ""
2445
2446 #. type: Plain text
2447 #: build/C/man2/perf_event_open.2:417
2448 msgid "Stalled cycles during retirement."
2449 msgstr ""
2450
2451 #. type: TP
2452 #: build/C/man2/perf_event_open.2:417
2453 #, no-wrap
2454 msgid "B<PERF_COUNT_HW_REF_CPU_CYCLES> (since Linux 3.3)"
2455 msgstr ""
2456
2457 #. type: Plain text
2458 #: build/C/man2/perf_event_open.2:420
2459 msgid "Total cycles; not affected by CPU frequency scaling."
2460 msgstr ""
2461
2462 #. type: Plain text
2463 #: build/C/man2/perf_event_open.2:430
2464 msgid ""
2465 "If I<type> is B<PERF_TYPE_SOFTWARE>, we are measuring software events "
2466 "provided by the kernel.  Set I<config> to one of the following:"
2467 msgstr ""
2468
2469 #. type: TP
2470 #: build/C/man2/perf_event_open.2:431
2471 #, no-wrap
2472 msgid "B<PERF_COUNT_SW_CPU_CLOCK>"
2473 msgstr ""
2474
2475 #. type: Plain text
2476 #: build/C/man2/perf_event_open.2:434
2477 msgid "This reports the CPU clock, a high-resolution per-CPU timer."
2478 msgstr ""
2479
2480 #. type: TP
2481 #: build/C/man2/perf_event_open.2:434
2482 #, no-wrap
2483 msgid "B<PERF_COUNT_SW_TASK_CLOCK>"
2484 msgstr ""
2485
2486 #. type: Plain text
2487 #: build/C/man2/perf_event_open.2:437
2488 msgid "This reports a clock count specific to the task that is running."
2489 msgstr ""
2490
2491 #. type: TP
2492 #: build/C/man2/perf_event_open.2:437
2493 #, no-wrap
2494 msgid "B<PERF_COUNT_SW_PAGE_FAULTS>"
2495 msgstr ""
2496
2497 #. type: Plain text
2498 #: build/C/man2/perf_event_open.2:440
2499 msgid "This reports the number of page faults."
2500 msgstr ""
2501
2502 #. type: TP
2503 #: build/C/man2/perf_event_open.2:440
2504 #, no-wrap
2505 msgid "B<PERF_COUNT_SW_CONTEXT_SWITCHES>"
2506 msgstr ""
2507
2508 #. type: Plain text
2509 #: build/C/man2/perf_event_open.2:445
2510 msgid ""
2511 "This counts context switches.  Until Linux 2.6.34, these were all reported "
2512 "as user-space events, after that they are reported as happening in the "
2513 "kernel."
2514 msgstr ""
2515
2516 #. type: TP
2517 #: build/C/man2/perf_event_open.2:445
2518 #, no-wrap
2519 msgid "B<PERF_COUNT_SW_CPU_MIGRATIONS>"
2520 msgstr ""
2521
2522 #. type: Plain text
2523 #: build/C/man2/perf_event_open.2:449
2524 msgid "This reports the number of times the process has migrated to a new CPU."
2525 msgstr ""
2526
2527 #. type: TP
2528 #: build/C/man2/perf_event_open.2:449
2529 #, no-wrap
2530 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MIN>"
2531 msgstr ""
2532
2533 #. type: Plain text
2534 #: build/C/man2/perf_event_open.2:453
2535 msgid ""
2536 "This counts the number of minor page faults.  These did not require disk I/O "
2537 "to handle."
2538 msgstr ""
2539
2540 #. type: TP
2541 #: build/C/man2/perf_event_open.2:453
2542 #, no-wrap
2543 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MAJ>"
2544 msgstr ""
2545
2546 #. type: Plain text
2547 #: build/C/man2/perf_event_open.2:457
2548 msgid ""
2549 "This counts the number of major page faults.  These required disk I/O to "
2550 "handle."
2551 msgstr ""
2552
2553 #. type: TP
2554 #: build/C/man2/perf_event_open.2:457
2555 #, no-wrap
2556 msgid "B<PERF_COUNT_SW_ALIGNMENT_FAULTS> (since Linux 2.6.33)"
2557 msgstr ""
2558
2559 #. type: Plain text
2560 #: build/C/man2/perf_event_open.2:463
2561 msgid ""
2562 "This counts the number of alignment faults.  These happen when unaligned "
2563 "memory accesses happen; the kernel can handle these but it reduces "
2564 "performance.  This happens only on some architectures (never on x86)."
2565 msgstr ""
2566
2567 #. type: TP
2568 #: build/C/man2/perf_event_open.2:463
2569 #, no-wrap
2570 msgid "B<PERF_COUNT_SW_EMULATION_FAULTS> (since Linux 2.6.33)"
2571 msgstr ""
2572
2573 #. type: Plain text
2574 #: build/C/man2/perf_event_open.2:469
2575 msgid ""
2576 "This counts the number of emulation faults.  The kernel sometimes traps on "
2577 "unimplemented instructions and emulates them for user space.  This can "
2578 "negatively impact performance."
2579 msgstr ""
2580
2581 #. type: TP
2582 #: build/C/man2/perf_event_open.2:469
2583 #, no-wrap
2584 msgid "B<PERF_COUNT_SW_DUMMY> (since Linux 3.12)"
2585 msgstr ""
2586
2587 #. type: Plain text
2588 #: build/C/man2/perf_event_open.2:476
2589 msgid ""
2590 "This is a placeholder event that counts nothing.  Informational sample "
2591 "record types such as mmap or comm must be associated with an active event.  "
2592 "This dummy event allows gathering such records without requiring a counting "
2593 "event."
2594 msgstr ""
2595
2596 #. type: Plain text
2597 #: build/C/man2/perf_event_open.2:489
2598 msgid ""
2599 "If I<type> is B<PERF_TYPE_TRACEPOINT>, then we are measuring kernel "
2600 "tracepoints.  The value to use in I<config> can be obtained from under "
2601 "debugfs I<tracing/events/*/*/id> if ftrace is enabled in the kernel."
2602 msgstr ""
2603
2604 #. type: Plain text
2605 #: build/C/man2/perf_event_open.2:500
2606 msgid ""
2607 "If I<type> is B<PERF_TYPE_HW_CACHE>, then we are measuring a hardware CPU "
2608 "cache event.  To calculate the appropriate I<config> value use the following "
2609 "equation:"
2610 msgstr ""
2611
2612 #. type: Plain text
2613 #: build/C/man2/perf_event_open.2:505
2614 #, no-wrap
2615 msgid ""
2616 "    (perf_hw_cache_id) | (perf_hw_cache_op_id E<lt>E<lt> 8) |\n"
2617 "    (perf_hw_cache_op_result_id E<lt>E<lt> 16)\n"
2618 msgstr ""
2619
2620 #. type: Plain text
2621 #: build/C/man2/perf_event_open.2:510
2622 msgid "where I<perf_hw_cache_id> is one of:"
2623 msgstr ""
2624
2625 #. type: TP
2626 #: build/C/man2/perf_event_open.2:511
2627 #, no-wrap
2628 msgid "B<PERF_COUNT_HW_CACHE_L1D>"
2629 msgstr ""
2630
2631 #. type: Plain text
2632 #: build/C/man2/perf_event_open.2:514
2633 msgid "for measuring Level 1 Data Cache"
2634 msgstr ""
2635
2636 #. type: TP
2637 #: build/C/man2/perf_event_open.2:514
2638 #, no-wrap
2639 msgid "B<PERF_COUNT_HW_CACHE_L1I>"
2640 msgstr ""
2641
2642 #. type: Plain text
2643 #: build/C/man2/perf_event_open.2:517
2644 msgid "for measuring Level 1 Instruction Cache"
2645 msgstr ""
2646
2647 #. type: TP
2648 #: build/C/man2/perf_event_open.2:517
2649 #, no-wrap
2650 msgid "B<PERF_COUNT_HW_CACHE_LL>"
2651 msgstr ""
2652
2653 #. type: Plain text
2654 #: build/C/man2/perf_event_open.2:520
2655 msgid "for measuring Last-Level Cache"
2656 msgstr ""
2657
2658 #. type: TP
2659 #: build/C/man2/perf_event_open.2:520
2660 #, no-wrap
2661 msgid "B<PERF_COUNT_HW_CACHE_DTLB>"
2662 msgstr ""
2663
2664 #. type: Plain text
2665 #: build/C/man2/perf_event_open.2:523
2666 msgid "for measuring the Data TLB"
2667 msgstr ""
2668
2669 #. type: TP
2670 #: build/C/man2/perf_event_open.2:523
2671 #, no-wrap
2672 msgid "B<PERF_COUNT_HW_CACHE_ITLB>"
2673 msgstr ""
2674
2675 #. type: Plain text
2676 #: build/C/man2/perf_event_open.2:526
2677 msgid "for measuring the Instruction TLB"
2678 msgstr ""
2679
2680 #. type: TP
2681 #: build/C/man2/perf_event_open.2:526
2682 #, no-wrap
2683 msgid "B<PERF_COUNT_HW_CACHE_BPU>"
2684 msgstr ""
2685
2686 #. type: Plain text
2687 #: build/C/man2/perf_event_open.2:529
2688 msgid "for measuring the branch prediction unit"
2689 msgstr ""
2690
2691 #. type: TP
2692 #: build/C/man2/perf_event_open.2:529
2693 #, no-wrap
2694 msgid "B<PERF_COUNT_HW_CACHE_NODE> (since Linux 3.0)"
2695 msgstr ""
2696
2697 #. type: Plain text
2698 #: build/C/man2/perf_event_open.2:532
2699 msgid "for measuring local memory accesses"
2700 msgstr ""
2701
2702 #. type: Plain text
2703 #: build/C/man2/perf_event_open.2:537
2704 msgid "and I<perf_hw_cache_op_id> is one of"
2705 msgstr ""
2706
2707 #. type: TP
2708 #: build/C/man2/perf_event_open.2:538
2709 #, no-wrap
2710 msgid "B<PERF_COUNT_HW_CACHE_OP_READ>"
2711 msgstr ""
2712
2713 #. type: Plain text
2714 #: build/C/man2/perf_event_open.2:541
2715 msgid "for read accesses"
2716 msgstr ""
2717
2718 #. type: TP
2719 #: build/C/man2/perf_event_open.2:541
2720 #, no-wrap
2721 msgid "B<PERF_COUNT_HW_CACHE_OP_WRITE>"
2722 msgstr ""
2723
2724 #. type: Plain text
2725 #: build/C/man2/perf_event_open.2:544
2726 msgid "for write accesses"
2727 msgstr ""
2728
2729 #. type: TP
2730 #: build/C/man2/perf_event_open.2:544
2731 #, no-wrap
2732 msgid "B<PERF_COUNT_HW_CACHE_OP_PREFETCH>"
2733 msgstr ""
2734
2735 #. type: Plain text
2736 #: build/C/man2/perf_event_open.2:547
2737 msgid "for prefetch accesses"
2738 msgstr ""
2739
2740 #. type: Plain text
2741 #: build/C/man2/perf_event_open.2:552
2742 msgid "and I<perf_hw_cache_op_result_id> is one of"
2743 msgstr ""
2744
2745 #. type: TP
2746 #: build/C/man2/perf_event_open.2:553
2747 #, no-wrap
2748 msgid "B<PERF_COUNT_HW_CACHE_RESULT_ACCESS>"
2749 msgstr ""
2750
2751 #. type: Plain text
2752 #: build/C/man2/perf_event_open.2:556
2753 msgid "to measure accesses"
2754 msgstr ""
2755
2756 #. type: TP
2757 #: build/C/man2/perf_event_open.2:556
2758 #, no-wrap
2759 msgid "B<PERF_COUNT_HW_CACHE_RESULT_MISS>"
2760 msgstr ""
2761
2762 #. type: Plain text
2763 #: build/C/man2/perf_event_open.2:559
2764 msgid "to measure misses"
2765 msgstr ""
2766
2767 #. type: Plain text
2768 #: build/C/man2/perf_event_open.2:577
2769 msgid ""
2770 "If I<type> is B<PERF_TYPE_RAW>, then a custom \"raw\" I<config> value is "
2771 "needed.  Most CPUs support events that are not covered by the "
2772 "\"generalized\" events.  These are implementation defined; see your CPU "
2773 "manual (for example the Intel Volume 3B documentation or the AMD BIOS and "
2774 "Kernel Developer Guide).  The libpfm4 library can be used to translate from "
2775 "the name in the architectural manuals to the raw hex value "
2776 "B<perf_event_open>()  expects in this field."
2777 msgstr ""
2778
2779 #. type: Plain text
2780 #: build/C/man2/perf_event_open.2:586
2781 msgid ""
2782 "If I<type> is B<PERF_TYPE_BREAKPOINT>, then leave I<config> set to zero.  "
2783 "Its parameters are set in other places."
2784 msgstr ""
2785
2786 #. type: TP
2787 #: build/C/man2/perf_event_open.2:587
2788 #, no-wrap
2789 msgid "I<sample_period>, I<sample_freq>"
2790 msgstr ""
2791
2792 #. type: Plain text
2793 #: build/C/man2/perf_event_open.2:599
2794 msgid ""
2795 "A \"sampling\" counter is one that generates an interrupt every N events, "
2796 "where N is given by I<sample_period>.  A sampling counter has "
2797 "I<sample_period> E<gt> 0.  When an overflow interrupt occurs, requested data "
2798 "is recorded in the mmap buffer.  The I<sample_type> field controls what data "
2799 "is recorded on each interrupt."
2800 msgstr ""
2801
2802 #. type: Plain text
2803 #: build/C/man2/perf_event_open.2:609
2804 msgid ""
2805 "I<sample_freq> can be used if you wish to use frequency rather than period.  "
2806 "In this case, you set the I<freq> flag.  The kernel will adjust the sampling "
2807 "period to try and achieve the desired rate.  The rate of adjustment is a "
2808 "timer tick."
2809 msgstr ""
2810
2811 #. type: TP
2812 #: build/C/man2/perf_event_open.2:609
2813 #, no-wrap
2814 msgid "I<sample_type>"
2815 msgstr ""
2816
2817 #. type: Plain text
2818 #: build/C/man2/perf_event_open.2:621
2819 msgid ""
2820 "The various bits in this field specify which values to include in the "
2821 "sample.  They will be recorded in a ring-buffer, which is available to user "
2822 "space using B<mmap>(2).  The order in which the values are saved in the "
2823 "sample are documented in the MMAP Layout subsection below; it is not the "
2824 "I<enum perf_event_sample_format> order."
2825 msgstr ""
2826
2827 #. type: TP
2828 #: build/C/man2/perf_event_open.2:622
2829 #, no-wrap
2830 msgid "B<PERF_SAMPLE_IP>"
2831 msgstr ""
2832
2833 #. type: Plain text
2834 #: build/C/man2/perf_event_open.2:625
2835 msgid "Records instruction pointer."
2836 msgstr ""
2837
2838 #. type: TP
2839 #: build/C/man2/perf_event_open.2:625
2840 #, no-wrap
2841 msgid "B<PERF_SAMPLE_TID>"
2842 msgstr ""
2843
2844 #. type: Plain text
2845 #: build/C/man2/perf_event_open.2:628
2846 msgid "Records the process and thread IDs."
2847 msgstr ""
2848
2849 #. type: TP
2850 #: build/C/man2/perf_event_open.2:628
2851 #, no-wrap
2852 msgid "B<PERF_SAMPLE_TIME>"
2853 msgstr ""
2854
2855 #. type: Plain text
2856 #: build/C/man2/perf_event_open.2:631
2857 msgid "Records a timestamp."
2858 msgstr ""
2859
2860 #. type: TP
2861 #: build/C/man2/perf_event_open.2:631
2862 #, no-wrap
2863 msgid "B<PERF_SAMPLE_ADDR>"
2864 msgstr ""
2865
2866 #. type: Plain text
2867 #: build/C/man2/perf_event_open.2:634
2868 msgid "Records an address, if applicable."
2869 msgstr ""
2870
2871 #. type: TP
2872 #: build/C/man2/perf_event_open.2:634
2873 #, no-wrap
2874 msgid "B<PERF_SAMPLE_READ>"
2875 msgstr ""
2876
2877 #. type: Plain text
2878 #: build/C/man2/perf_event_open.2:637
2879 msgid "Record counter values for all events in a group, not just the group leader."
2880 msgstr ""
2881
2882 #. type: TP
2883 #: build/C/man2/perf_event_open.2:637
2884 #, no-wrap
2885 msgid "B<PERF_SAMPLE_CALLCHAIN>"
2886 msgstr ""
2887
2888 #. type: Plain text
2889 #: build/C/man2/perf_event_open.2:640
2890 msgid "Records the callchain (stack backtrace)."
2891 msgstr ""
2892
2893 #. type: TP
2894 #: build/C/man2/perf_event_open.2:640
2895 #, no-wrap
2896 msgid "B<PERF_SAMPLE_ID>"
2897 msgstr ""
2898
2899 #. type: Plain text
2900 #: build/C/man2/perf_event_open.2:643
2901 msgid "Records a unique ID for the opened event's group leader."
2902 msgstr ""
2903
2904 #. type: TP
2905 #: build/C/man2/perf_event_open.2:643
2906 #, no-wrap
2907 msgid "B<PERF_SAMPLE_CPU>"
2908 msgstr ""
2909
2910 #. type: Plain text
2911 #: build/C/man2/perf_event_open.2:646
2912 msgid "Records CPU number."
2913 msgstr ""
2914
2915 #. type: TP
2916 #: build/C/man2/perf_event_open.2:646
2917 #, no-wrap
2918 msgid "B<PERF_SAMPLE_PERIOD>"
2919 msgstr ""
2920
2921 #. type: Plain text
2922 #: build/C/man2/perf_event_open.2:649
2923 msgid "Records the current sampling period."
2924 msgstr ""
2925
2926 #. type: TP
2927 #: build/C/man2/perf_event_open.2:649
2928 #, no-wrap
2929 msgid "B<PERF_SAMPLE_STREAM_ID>"
2930 msgstr ""
2931
2932 #. type: Plain text
2933 #: build/C/man2/perf_event_open.2:657
2934 msgid ""
2935 "Records a unique ID for the opened event.  Unlike B<PERF_SAMPLE_ID> the "
2936 "actual ID is returned, not the group leader.  This ID is the same as the one "
2937 "returned by B<PERF_FORMAT_ID>."
2938 msgstr ""
2939
2940 #. type: TP
2941 #: build/C/man2/perf_event_open.2:657
2942 #, no-wrap
2943 msgid "B<PERF_SAMPLE_RAW>"
2944 msgstr ""
2945
2946 #. type: Plain text
2947 #: build/C/man2/perf_event_open.2:661
2948 msgid ""
2949 "Records additional data, if applicable.  Usually returned by tracepoint "
2950 "events."
2951 msgstr ""
2952
2953 #. type: TP
2954 #: build/C/man2/perf_event_open.2:661
2955 #, no-wrap
2956 msgid "B<PERF_SAMPLE_BRANCH_STACK> (since Linux 3.4)"
2957 msgstr ""
2958
2959 #. type: Plain text
2960 #: build/C/man2/perf_event_open.2:666
2961 msgid ""
2962 "This provides a record of recent branches, as provided by CPU branch "
2963 "sampling hardware (such as Intel Last Branch Record).  Not all hardware "
2964 "supports this feature."
2965 msgstr ""
2966
2967 #. type: Plain text
2968 #: build/C/man2/perf_event_open.2:670
2969 msgid ""
2970 "See the I<branch_sample_type> field for how to filter which branches are "
2971 "reported."
2972 msgstr ""
2973
2974 #. type: TP
2975 #: build/C/man2/perf_event_open.2:670
2976 #, no-wrap
2977 msgid "B<PERF_SAMPLE_REGS_USER> (since Linux 3.7)"
2978 msgstr ""
2979
2980 #. type: Plain text
2981 #: build/C/man2/perf_event_open.2:674
2982 msgid ""
2983 "Records the current user-level CPU register state (the values in the process "
2984 "before the kernel was called)."
2985 msgstr ""
2986
2987 #. type: TP
2988 #: build/C/man2/perf_event_open.2:674
2989 #, no-wrap
2990 msgid "B<PERF_SAMPLE_STACK_USER> (since Linux 3.7)"
2991 msgstr ""
2992
2993 #. type: Plain text
2994 #: build/C/man2/perf_event_open.2:677
2995 msgid "Records the user level stack, allowing stack unwinding."
2996 msgstr ""
2997
2998 #. type: TP
2999 #: build/C/man2/perf_event_open.2:677
3000 #, no-wrap
3001 msgid "B<PERF_SAMPLE_WEIGHT> (since Linux 3.10)"
3002 msgstr ""
3003
3004 #. type: Plain text
3005 #: build/C/man2/perf_event_open.2:683
3006 msgid ""
3007 "Records a hardware provided weight value that expresses how costly the "
3008 "sampled event was.  This allows the hardware to highlight expensive events "
3009 "in a profile."
3010 msgstr ""
3011
3012 #. type: TP
3013 #: build/C/man2/perf_event_open.2:683
3014 #, no-wrap
3015 msgid "B<PERF_SAMPLE_DATA_SRC> (since Linux 3.10)"
3016 msgstr ""
3017
3018 #. type: Plain text
3019 #: build/C/man2/perf_event_open.2:689
3020 msgid ""
3021 "Records the data source: where in the memory hierarchy the data associated "
3022 "with the sampled instruction came from.  This is only available if the "
3023 "underlying hardware supports this feature."
3024 msgstr ""
3025
3026 #. type: TP
3027 #: build/C/man2/perf_event_open.2:689
3028 #, no-wrap
3029 msgid "B<PERF_SAMPLE_IDENTIFIER> (since Linux 3.12)"
3030 msgstr ""
3031
3032 #. type: Plain text
3033 #: build/C/man2/perf_event_open.2:696
3034 msgid ""
3035 "Places the B<SAMPLE_ID> value in a fixed position in the record, either at "
3036 "the beginning (for sample events) or at the end (if a non-sample event)."
3037 msgstr ""
3038
3039 #. type: Plain text
3040 #: build/C/man2/perf_event_open.2:708
3041 msgid ""
3042 "This was necessary because a sample stream may have records from various "
3043 "different event sources with different I<sample_type> settings.  Parsing the "
3044 "event stream properly was not possible because the format of the record was "
3045 "needed to find B<SAMPLE_ID>, but the format could not be found without "
3046 "knowing what event the sample belonged to (causing a circular dependency)."
3047 msgstr ""
3048
3049 #. type: Plain text
3050 #: build/C/man2/perf_event_open.2:718
3051 msgid ""
3052 "This new B<PERF_SAMPLE_IDENTIFIER> setting makes the event stream always "
3053 "parsable by putting B<SAMPLE_ID> in a fixed location, even though it means "
3054 "having duplicate B<SAMPLE_ID> values in records."
3055 msgstr ""
3056
3057 #. type: TP
3058 #: build/C/man2/perf_event_open.2:718
3059 #, no-wrap
3060 msgid "B<PERF_SAMPLE_TRANSACTION> (Since Linux 3.13)"
3061 msgstr ""
3062
3063 #. type: Plain text
3064 #: build/C/man2/perf_event_open.2:722
3065 msgid ""
3066 "Records reasons for transactional memory abort events (for example, from "
3067 "Intel TSX transactional memory support)."
3068 msgstr ""
3069
3070 #. type: Plain text
3071 #: build/C/man2/perf_event_open.2:730
3072 msgid ""
3073 "The I<precise_ip> setting must be greater than 0 and a transactional memory "
3074 "abort event must be measured or no values will be recorded.  Also note that "
3075 "some perf_event measurements, such as sampled cycle counting, may cause "
3076 "extraneous aborts (by causing an interrupt during a transaction)."
3077 msgstr ""
3078
3079 #. type: TP
3080 #: build/C/man2/perf_event_open.2:731
3081 #, no-wrap
3082 msgid "I<read_format>"
3083 msgstr ""
3084
3085 #. type: Plain text
3086 #: build/C/man2/perf_event_open.2:738
3087 msgid ""
3088 "This field specifies the format of the data returned by B<read>(2)  on a "
3089 "B<perf_event_open>()  file descriptor."
3090 msgstr ""
3091
3092 #. type: TP
3093 #: build/C/man2/perf_event_open.2:739
3094 #, no-wrap
3095 msgid "B<PERF_FORMAT_TOTAL_TIME_ENABLED>"
3096 msgstr ""
3097
3098 #. type: Plain text
3099 #: build/C/man2/perf_event_open.2:746
3100 msgid ""
3101 "Adds the 64-bit I<time_enabled> field.  This can be used to calculate "
3102 "estimated totals if the PMU is overcommitted and multiplexing is happening."
3103 msgstr ""
3104
3105 #. type: TP
3106 #: build/C/man2/perf_event_open.2:746
3107 #, no-wrap
3108 msgid "B<PERF_FORMAT_TOTAL_TIME_RUNNING>"
3109 msgstr ""
3110
3111 #. type: Plain text
3112 #: build/C/man2/perf_event_open.2:753
3113 msgid ""
3114 "Adds the 64-bit I<time_running> field.  This can be used to calculate "
3115 "estimated totals if the PMU is overcommitted and multiplexing is happening."
3116 msgstr ""
3117
3118 #. type: TP
3119 #: build/C/man2/perf_event_open.2:753
3120 #, no-wrap
3121 msgid "B<PERF_FORMAT_ID>"
3122 msgstr ""
3123
3124 #. type: Plain text
3125 #: build/C/man2/perf_event_open.2:756
3126 msgid "Adds a 64-bit unique value that corresponds to the event group."
3127 msgstr ""
3128
3129 #. type: TP
3130 #: build/C/man2/perf_event_open.2:756
3131 #, no-wrap
3132 msgid "B<PERF_FORMAT_GROUP>"
3133 msgstr ""
3134
3135 #. type: Plain text
3136 #: build/C/man2/perf_event_open.2:759
3137 msgid "Allows all counter values in an event group to be read with one read."
3138 msgstr ""
3139
3140 #. type: TP
3141 #: build/C/man2/perf_event_open.2:760
3142 #, no-wrap
3143 msgid "I<disabled>"
3144 msgstr ""
3145
3146 #. type: Plain text
3147 #: build/C/man2/perf_event_open.2:770
3148 msgid ""
3149 "The I<disabled> bit specifies whether the counter starts out disabled or "
3150 "enabled.  If disabled, the event can later be enabled by B<ioctl>(2), "
3151 "B<prctl>(2), or I<enable_on_exec>."
3152 msgstr ""
3153
3154 #. type: Plain text
3155 #: build/C/man2/perf_event_open.2:781
3156 msgid ""
3157 "When creating an event group, typically the group leader is initialized with "
3158 "I<disabled> set to 1 and any child events are initialized with I<disabled> "
3159 "set to 0.  Despite I<disabled> being 0, the child events will not start "
3160 "until the group leader is enabled."
3161 msgstr ""
3162
3163 #. type: TP
3164 #: build/C/man2/perf_event_open.2:781
3165 #, no-wrap
3166 msgid "I<inherit>"
3167 msgstr ""
3168
3169 #. type: Plain text
3170 #: build/C/man2/perf_event_open.2:790
3171 msgid ""
3172 "The I<inherit> bit specifies that this counter should count events of child "
3173 "tasks as well as the task specified.  This applies only to new children, not "
3174 "to any existing children at the time the counter is created (nor to any new "
3175 "children of existing children)."
3176 msgstr ""
3177
3178 #. type: Plain text
3179 #: build/C/man2/perf_event_open.2:795
3180 msgid ""
3181 "Inherit does not work for some combinations of I<read_format>s, such as "
3182 "B<PERF_FORMAT_GROUP>."
3183 msgstr ""
3184
3185 #. type: TP
3186 #: build/C/man2/perf_event_open.2:795
3187 #, no-wrap
3188 msgid "I<pinned>"
3189 msgstr ""
3190
3191 #. type: Plain text
3192 #: build/C/man2/perf_event_open.2:808
3193 msgid ""
3194 "The I<pinned> bit specifies that the counter should always be on the CPU if "
3195 "at all possible.  It applies only to hardware counters and only to group "
3196 "leaders.  If a pinned counter cannot be put onto the CPU (e.g., because "
3197 "there are not enough hardware counters or because of a conflict with some "
3198 "other event), then the counter goes into an 'error' state, where reads "
3199 "return end-of-file (i.e., B<read>(2)  returns 0) until the counter is "
3200 "subsequently enabled or disabled."
3201 msgstr ""
3202
3203 #. type: TP
3204 #: build/C/man2/perf_event_open.2:808
3205 #, no-wrap
3206 msgid "I<exclusive>"
3207 msgstr ""
3208
3209 #. type: Plain text
3210 #: build/C/man2/perf_event_open.2:817
3211 msgid ""
3212 "The I<exclusive> bit specifies that when this counter's group is on the CPU, "
3213 "it should be the only group using the CPU's counters.  In the future this "
3214 "may allow monitoring programs to support PMU features that need to run alone "
3215 "so that they do not disrupt other hardware counters."
3216 msgstr ""
3217
3218 #. type: Plain text
3219 #: build/C/man2/perf_event_open.2:824
3220 msgid ""
3221 "Note that many unexpected situations may prevent events with the "
3222 "I<exclusive> bit set from ever running.  This includes any users running a "
3223 "system-wide measurement as well as any kernel use of the performance "
3224 "counters (including the commonly enabled NMI Watchdog Timer interface)."
3225 msgstr ""
3226
3227 #. type: TP
3228 #: build/C/man2/perf_event_open.2:824
3229 #, no-wrap
3230 msgid "I<exclude_user>"
3231 msgstr ""
3232
3233 #. type: Plain text
3234 #: build/C/man2/perf_event_open.2:827
3235 msgid "If this bit is set, the count excludes events that happen in user space."
3236 msgstr ""
3237
3238 #. type: TP
3239 #: build/C/man2/perf_event_open.2:827
3240 #, no-wrap
3241 msgid "I<exclude_kernel>"
3242 msgstr ""
3243
3244 #. type: Plain text
3245 #: build/C/man2/perf_event_open.2:830
3246 msgid "If this bit is set, the count excludes events that happen in kernel-space."
3247 msgstr ""
3248
3249 #. type: TP
3250 #: build/C/man2/perf_event_open.2:830
3251 #, no-wrap
3252 msgid "I<exclude_hv>"
3253 msgstr ""
3254
3255 #. type: Plain text
3256 #: build/C/man2/perf_event_open.2:838
3257 msgid ""
3258 "If this bit is set, the count excludes events that happen in the "
3259 "hypervisor.  This is mainly for PMUs that have built-in support for handling "
3260 "this (such as POWER).  Extra support is needed for handling hypervisor "
3261 "measurements on most machines."
3262 msgstr ""
3263
3264 #. type: TP
3265 #: build/C/man2/perf_event_open.2:838
3266 #, no-wrap
3267 msgid "I<exclude_idle>"
3268 msgstr ""
3269
3270 #. type: Plain text
3271 #: build/C/man2/perf_event_open.2:841
3272 msgid "If set, don't count when the CPU is idle."
3273 msgstr ""
3274
3275 #. type: TP
3276 #: build/C/man2/perf_event_open.2:841
3277 #, no-wrap
3278 msgid "I<mmap>"
3279 msgstr ""
3280
3281 #. type: Plain text
3282 #: build/C/man2/perf_event_open.2:855
3283 msgid ""
3284 "The I<mmap> bit enables generation of B<PERF_RECORD_MMAP> samples for every "
3285 "B<mmap>(2)  call that has B<PROT_EXEC> set.  This allows tools to notice new "
3286 "executable code being mapped into a program (dynamic shared libraries for "
3287 "example)  so that addresses can be mapped back to the original code."
3288 msgstr ""
3289
3290 #. type: TP
3291 #: build/C/man2/perf_event_open.2:855
3292 #, no-wrap
3293 msgid "I<comm>"
3294 msgstr ""
3295
3296 #. type: Plain text
3297 #: build/C/man2/perf_event_open.2:866
3298 msgid ""
3299 "The I<comm> bit enables tracking of process command name as modified by the "
3300 "B<exec>(2)  and B<prctl>(PR_SET_NAME)  system calls.  Unfortunately for "
3301 "tools, there is no way to distinguish one system call versus the other."
3302 msgstr ""
3303
3304 #. type: TP
3305 #: build/C/man2/perf_event_open.2:866
3306 #, no-wrap
3307 msgid "I<freq>"
3308 msgstr ""
3309
3310 #. type: Plain text
3311 #: build/C/man2/perf_event_open.2:873
3312 msgid ""
3313 "If this bit is set, then I<sample_frequency> not I<sample_period> is used "
3314 "when setting up the sampling interval."
3315 msgstr ""
3316
3317 #. type: TP
3318 #: build/C/man2/perf_event_open.2:873
3319 #, no-wrap
3320 msgid "I<inherit_stat>"
3321 msgstr ""
3322
3323 #. type: Plain text
3324 #: build/C/man2/perf_event_open.2:880
3325 msgid ""
3326 "This bit enables saving of event counts on context switch for inherited "
3327 "tasks.  This is meaningful only if the I<inherit> field is set."
3328 msgstr ""
3329
3330 #. type: TP
3331 #: build/C/man2/perf_event_open.2:880
3332 #, no-wrap
3333 msgid "I<enable_on_exec>"
3334 msgstr ""
3335
3336 #. type: Plain text
3337 #: build/C/man2/perf_event_open.2:885
3338 msgid ""
3339 "If this bit is set, a counter is automatically enabled after a call to "
3340 "B<exec>(2)."
3341 msgstr ""
3342
3343 #. type: TP
3344 #: build/C/man2/perf_event_open.2:885
3345 #, no-wrap
3346 msgid "I<task>"
3347 msgstr ""
3348
3349 #. type: Plain text
3350 #: build/C/man2/perf_event_open.2:889
3351 msgid ""
3352 "If this bit is set, then fork/exit notifications are included in the ring "
3353 "buffer."
3354 msgstr ""
3355
3356 #. type: TP
3357 #: build/C/man2/perf_event_open.2:889
3358 #, no-wrap
3359 msgid "I<watermark>"
3360 msgstr ""
3361
3362 #. type: Plain text
3363 #: build/C/man2/perf_event_open.2:897
3364 msgid ""
3365 "If set, have a sampling interrupt happen when we cross the "
3366 "I<wakeup_watermark> boundary.  Otherwise, interrupts happen after "
3367 "I<wakeup_events> samples."
3368 msgstr ""
3369
3370 #. type: TP
3371 #: build/C/man2/perf_event_open.2:897
3372 #, no-wrap
3373 msgid "I<precise_ip> (since Linux 2.6.35)"
3374 msgstr ""
3375
3376 #. type: Plain text
3377 #: build/C/man2/perf_event_open.2:907
3378 msgid ""
3379 "This controls the amount of skid.  Skid is how many instructions execute "
3380 "between an event of interest happening and the kernel being able to stop and "
3381 "record the event.  Smaller skid is better and allows more accurate reporting "
3382 "of which events correspond to which instructions, but hardware is often "
3383 "limited with how small this can be."
3384 msgstr ""
3385
3386 #. type: Plain text
3387 #: build/C/man2/perf_event_open.2:909
3388 msgid "The values of this are the following:"
3389 msgstr ""
3390
3391 #. type: TP
3392 #: build/C/man2/perf_event_open.2:910
3393 #, no-wrap
3394 msgid "0 -"
3395 msgstr ""
3396
3397 #. type: Plain text
3398 #: build/C/man2/perf_event_open.2:914
3399 msgid "B<SAMPLE_IP> can have arbitrary skid."
3400 msgstr ""
3401
3402 #. type: TP
3403 #: build/C/man2/perf_event_open.2:914
3404 #, no-wrap
3405 msgid "1 -"
3406 msgstr ""
3407
3408 #. type: Plain text
3409 #: build/C/man2/perf_event_open.2:918
3410 msgid "B<SAMPLE_IP> must have constant skid."
3411 msgstr ""
3412
3413 #. type: TP
3414 #: build/C/man2/perf_event_open.2:918
3415 #, no-wrap
3416 msgid "2 -"
3417 msgstr ""
3418
3419 #. type: Plain text
3420 #: build/C/man2/perf_event_open.2:922
3421 msgid "B<SAMPLE_IP> requested to have 0 skid."
3422 msgstr ""
3423
3424 #. type: TP
3425 #: build/C/man2/perf_event_open.2:922
3426 #, no-wrap
3427 msgid "3 -"
3428 msgstr ""
3429
3430 #. type: Plain text
3431 #: build/C/man2/perf_event_open.2:928
3432 msgid "B<SAMPLE_IP> must have 0 skid.  See also B<PERF_RECORD_MISC_EXACT_IP>."
3433 msgstr ""
3434
3435 #. type: TP
3436 #: build/C/man2/perf_event_open.2:929
3437 #, no-wrap
3438 msgid "I<mmap_data> (since Linux 2.6.36)"
3439 msgstr ""
3440
3441 #. type: Plain text
3442 #: build/C/man2/perf_event_open.2:941
3443 msgid ""
3444 "The counterpart of the I<mmap> field.  This enables generation of "
3445 "B<PERF_RECORD_MMAP> samples for B<mmap>(2)  calls that do not have "
3446 "B<PROT_EXEC> set (for example data and SysV shared memory)."
3447 msgstr ""
3448
3449 #. type: TP
3450 #: build/C/man2/perf_event_open.2:941
3451 #, no-wrap
3452 msgid "I<sample_id_all> (since Linux 2.6.38)"
3453 msgstr ""
3454
3455 #. type: Plain text
3456 #: build/C/man2/perf_event_open.2:949
3457 msgid ""
3458 "If set, then TID, TIME, ID, STREAM_ID, and CPU can additionally be included "
3459 "in non-B<PERF_RECORD_SAMPLE>s if the corresponding I<sample_type> is "
3460 "selected."
3461 msgstr ""
3462
3463 #. type: Plain text
3464 #: build/C/man2/perf_event_open.2:957
3465 msgid ""
3466 "If B<PERF_SAMPLE_IDENTIFIER> is specified, then an additional ID value is "
3467 "included as the last value to ease parsing the record stream.  This may lead "
3468 "to the I<id> value appearing twice."
3469 msgstr ""
3470
3471 #. type: Plain text
3472 #: build/C/man2/perf_event_open.2:959
3473 msgid "The layout is described by this pseudo-structure:"
3474 msgstr ""
3475
3476 #. type: Plain text
3477 #: build/C/man2/perf_event_open.2:969
3478 #, no-wrap
3479 msgid ""
3480 "struct sample_id {\n"
3481 "    { u32 pid, tid; } /* if PERF_SAMPLE_TID set        */\n"
3482 "    { u64 time;     } /* if PERF_SAMPLE_TIME set       */\n"
3483 "    { u64 id;       } /* if PERF_SAMPLE_ID set         */\n"
3484 "    { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set  */\n"
3485 "    { u32 cpu, res; } /* if PERF_SAMPLE_CPU set        */\n"
3486 "    { u64 id;       } /* if PERF_SAMPLE_IDENTIFIER set */\n"
3487 "};\n"
3488 msgstr ""
3489
3490 #. type: TP
3491 #: build/C/man2/perf_event_open.2:970
3492 #, no-wrap
3493 msgid "I<exclude_host> (since Linux 3.2)"
3494 msgstr ""
3495
3496 #. type: Plain text
3497 #: build/C/man2/perf_event_open.2:973
3498 msgid "Do not measure time spent in VM host."
3499 msgstr ""
3500
3501 #. type: TP
3502 #: build/C/man2/perf_event_open.2:973
3503 #, no-wrap
3504 msgid "I<exclude_guest> (since Linux 3.2)"
3505 msgstr ""
3506
3507 #. type: Plain text
3508 #: build/C/man2/perf_event_open.2:976
3509 msgid "Do not measure time spent in VM guest."
3510 msgstr ""
3511
3512 #. type: TP
3513 #: build/C/man2/perf_event_open.2:976
3514 #, no-wrap
3515 msgid "I<exclude_callchain_kernel> (since Linux 3.7)"
3516 msgstr ""
3517
3518 #. type: Plain text
3519 #: build/C/man2/perf_event_open.2:979
3520 msgid "Do not include kernel callchains."
3521 msgstr ""
3522
3523 #. type: TP
3524 #: build/C/man2/perf_event_open.2:979
3525 #, no-wrap
3526 msgid "I<exclude_callchain_user> (since Linux 3.7)"
3527 msgstr ""
3528
3529 #. type: Plain text
3530 #: build/C/man2/perf_event_open.2:982
3531 msgid "Do not include user callchains."
3532 msgstr ""
3533
3534 #. type: TP
3535 #: build/C/man2/perf_event_open.2:982
3536 #, no-wrap
3537 msgid "I<wakeup_events>, I<wakeup_watermark>"
3538 msgstr ""
3539
3540 #. type: Plain text
3541 #: build/C/man2/perf_event_open.2:992
3542 msgid ""
3543 "This union sets how many samples (I<wakeup_events>)  or bytes "
3544 "(I<wakeup_watermark>)  happen before an overflow signal happens.  Which one "
3545 "is used is selected by the I<watermark> bit flag."
3546 msgstr ""
3547
3548 #. type: Plain text
3549 #: build/C/man2/perf_event_open.2:1002
3550 msgid ""
3551 "I<wakeup_events> only counts B<PERF_RECORD_SAMPLE> record types.  To receive "
3552 "a signal for every incoming B<PERF_RECORD> type set I<wakeup_watermark> to "
3553 "1."
3554 msgstr ""
3555
3556 #. type: TP
3557 #: build/C/man2/perf_event_open.2:1002
3558 #, no-wrap
3559 msgid "I<bp_type> (since Linux 2.6.33)"
3560 msgstr ""
3561
3562 #. type: Plain text
3563 #: build/C/man2/perf_event_open.2:1006
3564 msgid "This chooses the breakpoint type.  It is one of:"
3565 msgstr ""
3566
3567 #. type: TP
3568 #: build/C/man2/perf_event_open.2:1007
3569 #, no-wrap
3570 msgid "B<HW_BREAKPOINT_EMPTY>"
3571 msgstr ""
3572
3573 #. type: Plain text
3574 #: build/C/man2/perf_event_open.2:1010
3575 msgid "No breakpoint."
3576 msgstr ""
3577
3578 #. type: TP
3579 #: build/C/man2/perf_event_open.2:1010
3580 #, no-wrap
3581 msgid "B<HW_BREAKPOINT_R>"
3582 msgstr ""
3583
3584 #. type: Plain text
3585 #: build/C/man2/perf_event_open.2:1013
3586 msgid "Count when we read the memory location."
3587 msgstr ""
3588
3589 #. type: TP
3590 #: build/C/man2/perf_event_open.2:1013
3591 #, no-wrap
3592 msgid "B<HW_BREAKPOINT_W>"
3593 msgstr ""
3594
3595 #. type: Plain text
3596 #: build/C/man2/perf_event_open.2:1016
3597 msgid "Count when we write the memory location."
3598 msgstr ""
3599
3600 #. type: TP
3601 #: build/C/man2/perf_event_open.2:1016
3602 #, no-wrap
3603 msgid "B<HW_BREAKPOINT_RW>"
3604 msgstr ""
3605
3606 #. type: Plain text
3607 #: build/C/man2/perf_event_open.2:1019
3608 msgid "Count when we read or write the memory location."
3609 msgstr ""
3610
3611 #. type: TP
3612 #: build/C/man2/perf_event_open.2:1019
3613 #, no-wrap
3614 msgid "B<HW_BREAKPOINT_X>"
3615 msgstr ""
3616
3617 #. type: Plain text
3618 #: build/C/man2/perf_event_open.2:1022
3619 msgid "Count when we execute code at the memory location."
3620 msgstr ""
3621
3622 #. type: Plain text
3623 #: build/C/man2/perf_event_open.2:1031
3624 msgid ""
3625 "The values can be combined via a bitwise or, but the combination of "
3626 "B<HW_BREAKPOINT_R> or B<HW_BREAKPOINT_W> with B<HW_BREAKPOINT_X> is not "
3627 "allowed."
3628 msgstr ""
3629
3630 #. type: TP
3631 #: build/C/man2/perf_event_open.2:1032
3632 #, no-wrap
3633 msgid "I<bp_addr> (since Linux 2.6.33)"
3634 msgstr ""
3635
3636 #. type: Plain text
3637 #: build/C/man2/perf_event_open.2:1039
3638 msgid ""
3639 "I<bp_addr> address of the breakpoint.  For execution breakpoints this is the "
3640 "memory address of the instruction of interest; for read and write "
3641 "breakpoints it is the memory address of the memory location of interest."
3642 msgstr ""
3643
3644 #. type: TP
3645 #: build/C/man2/perf_event_open.2:1039
3646 #, no-wrap
3647 msgid "I<config1> (since Linux 2.6.39)"
3648 msgstr ""
3649
3650 #. type: Plain text
3651 #: build/C/man2/perf_event_open.2:1046
3652 msgid ""
3653 "I<config1> is used for setting events that need an extra register or "
3654 "otherwise do not fit in the regular config field.  Raw OFFCORE_EVENTS on "
3655 "Nehalem/Westmere/SandyBridge use this field on 3.3 and later kernels."
3656 msgstr ""
3657
3658 #. type: TP
3659 #: build/C/man2/perf_event_open.2:1046
3660 #, no-wrap
3661 msgid "I<bp_len> (since Linux 2.6.33)"
3662 msgstr ""
3663
3664 #. type: Plain text
3665 #: build/C/man2/perf_event_open.2:1060
3666 msgid ""
3667 "I<bp_len> is the length of the breakpoint being measured if I<type> is "
3668 "B<PERF_TYPE_BREAKPOINT>.  Options are B<HW_BREAKPOINT_LEN_1>, "
3669 "B<HW_BREAKPOINT_LEN_2>, B<HW_BREAKPOINT_LEN_4>, B<HW_BREAKPOINT_LEN_8>.  For "
3670 "an execution breakpoint, set this to I<sizeof(long)>."
3671 msgstr ""
3672
3673 #. type: TP
3674 #: build/C/man2/perf_event_open.2:1060
3675 #, no-wrap
3676 msgid "I<config2> (since Linux 2.6.39)"
3677 msgstr ""
3678
3679 #. type: Plain text
3680 #: build/C/man2/perf_event_open.2:1067
3681 msgid "I<config2> is a further extension of the I<config1> field."
3682 msgstr ""
3683
3684 #. type: TP
3685 #: build/C/man2/perf_event_open.2:1067
3686 #, no-wrap
3687 msgid "I<branch_sample_type> (since Linux 3.4)"
3688 msgstr ""
3689
3690 #. type: Plain text
3691 #: build/C/man2/perf_event_open.2:1073
3692 msgid ""
3693 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then this specifies what branches "
3694 "to include in the branch record."
3695 msgstr ""
3696
3697 #. type: Plain text
3698 #: build/C/man2/perf_event_open.2:1079
3699 msgid ""
3700 "The first part of the value is the privilege level, which is a combination "
3701 "of one of the following values.  If the user does not set privilege level "
3702 "explicitly, the kernel will use the event's privilege level.  Event and "
3703 "branch privilege levels do not have to match."
3704 msgstr ""
3705
3706 #. type: TP
3707 #: build/C/man2/perf_event_open.2:1080
3708 #, no-wrap
3709 msgid "B<PERF_SAMPLE_BRANCH_USER>"
3710 msgstr ""
3711
3712 #. type: Plain text
3713 #: build/C/man2/perf_event_open.2:1083
3714 msgid "Branch target is in user space."
3715 msgstr ""
3716
3717 #. type: TP
3718 #: build/C/man2/perf_event_open.2:1083
3719 #, no-wrap
3720 msgid "B<PERF_SAMPLE_BRANCH_KERNEL>"
3721 msgstr ""
3722
3723 #. type: Plain text
3724 #: build/C/man2/perf_event_open.2:1086
3725 msgid "Branch target is in kernel space."
3726 msgstr ""
3727
3728 #. type: TP
3729 #: build/C/man2/perf_event_open.2:1086
3730 #, no-wrap
3731 msgid "B<PERF_SAMPLE_BRANCH_HV>"
3732 msgstr ""
3733
3734 #. type: Plain text
3735 #: build/C/man2/perf_event_open.2:1089
3736 msgid "Branch target is in hypervisor."
3737 msgstr ""
3738
3739 #. type: TP
3740 #: build/C/man2/perf_event_open.2:1089
3741 #, no-wrap
3742 msgid "B<PERF_SAMPLE_BRANCH_PLM_ALL>"
3743 msgstr ""
3744
3745 #. type: Plain text
3746 #: build/C/man2/perf_event_open.2:1092
3747 msgid "A convenience value that is the three preceding values ORed together."
3748 msgstr ""
3749
3750 #. type: Plain text
3751 #: build/C/man2/perf_event_open.2:1096
3752 msgid ""
3753 "In addition to the privilege value, at least one or more of the following "
3754 "bits must be set."
3755 msgstr ""
3756
3757 #. type: TP
3758 #: build/C/man2/perf_event_open.2:1097
3759 #, no-wrap
3760 msgid "B<PERF_SAMPLE_BRANCH_ANY>"
3761 msgstr ""
3762
3763 #. type: Plain text
3764 #: build/C/man2/perf_event_open.2:1100
3765 msgid "Any branch type."
3766 msgstr ""
3767
3768 #. type: TP
3769 #: build/C/man2/perf_event_open.2:1100
3770 #, no-wrap
3771 msgid "B<PERF_SAMPLE_BRANCH_ANY_CALL>"
3772 msgstr ""
3773
3774 #. type: Plain text
3775 #: build/C/man2/perf_event_open.2:1103
3776 msgid "Any call branch."
3777 msgstr ""
3778
3779 #. type: TP
3780 #: build/C/man2/perf_event_open.2:1103
3781 #, no-wrap
3782 msgid "B<PERF_SAMPLE_BRANCH_ANY_RETURN>"
3783 msgstr ""
3784
3785 #. type: Plain text
3786 #: build/C/man2/perf_event_open.2:1106
3787 msgid "Any return branch."
3788 msgstr ""
3789
3790 #. type: TP
3791 #: build/C/man2/perf_event_open.2:1106
3792 #, no-wrap
3793 msgid "B<PERF_SAMPLE_BRANCH_IND_CALL>"
3794 msgstr ""
3795
3796 #. type: Plain text
3797 #: build/C/man2/perf_event_open.2:1109
3798 msgid "Indirect calls."
3799 msgstr ""
3800
3801 #. type: TP
3802 #: build/C/man2/perf_event_open.2:1109
3803 #, no-wrap
3804 msgid "B<PERF_SAMPLE_BRANCH_ABORT_TX> (since Linux 3.11)"
3805 msgstr ""
3806
3807 #. type: Plain text
3808 #: build/C/man2/perf_event_open.2:1112
3809 msgid "Transactional memory aborts."
3810 msgstr ""
3811
3812 #. type: TP
3813 #: build/C/man2/perf_event_open.2:1112
3814 #, no-wrap
3815 msgid "B<PERF_SAMPLE_BRANCH_IN_TX> (since Linux 3.11)"
3816 msgstr ""
3817
3818 #. type: Plain text
3819 #: build/C/man2/perf_event_open.2:1115
3820 msgid "Branch in transactional memory transaction."
3821 msgstr ""
3822
3823 #. type: TP
3824 #: build/C/man2/perf_event_open.2:1115
3825 #, no-wrap
3826 msgid "B<PERF_SAMPLE_BRANCH_NO_TX> (since Linux 3.11)"
3827 msgstr ""
3828
3829 #. type: Plain text
3830 #: build/C/man2/perf_event_open.2:1118
3831 msgid "Branch not in transactional memory transaction."
3832 msgstr ""
3833
3834 #. type: TP
3835 #: build/C/man2/perf_event_open.2:1120
3836 #, no-wrap
3837 msgid "I<sample_regs_user> (since Linux 3.7)"
3838 msgstr ""
3839
3840 #. type: Plain text
3841 #: build/C/man2/perf_event_open.2:1126
3842 msgid ""
3843 "This bit mask defines the set of user CPU registers to dump on samples.  The "
3844 "layout of the register mask is architecture-specific and described in the "
3845 "kernel header I<arch/ARCH/include/uapi/asm/perf_regs.h>."
3846 msgstr ""
3847
3848 #. type: TP
3849 #: build/C/man2/perf_event_open.2:1126
3850 #, no-wrap
3851 msgid "I<sample_stack_user> (since Linux 3.7)"
3852 msgstr ""
3853
3854 #. type: Plain text
3855 #: build/C/man2/perf_event_open.2:1131
3856 msgid ""
3857 "This defines the size of the user stack to dump if B<PERF_SAMPLE_STACK_USER> "
3858 "is specified."
3859 msgstr ""
3860
3861 #. type: SS
3862 #: build/C/man2/perf_event_open.2:1131
3863 #, no-wrap
3864 msgid "Reading results"
3865 msgstr ""
3866
3867 #. type: Plain text
3868 #: build/C/man2/perf_event_open.2:1141
3869 msgid ""
3870 "Once a B<perf_event_open>()  file descriptor has been opened, the values of "
3871 "the events can be read from the file descriptor.  The values that are there "
3872 "are specified by the I<read_format> field in the I<attr> structure at open "
3873 "time."
3874 msgstr ""
3875
3876 #. type: Plain text
3877 #: build/C/man2/perf_event_open.2:1146
3878 msgid ""
3879 "If you attempt to read into a buffer that is not big enough to hold the data "
3880 "B<ENOSPC> is returned"
3881 msgstr ""
3882
3883 #. type: Plain text
3884 #: build/C/man2/perf_event_open.2:1148
3885 msgid "Here is the layout of the data returned by a read:"
3886 msgstr ""
3887
3888 #. type: IP
3889 #: 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
3890 #, no-wrap
3891 msgid "*"
3892 msgstr ""
3893
3894 #. type: Plain text
3895 #: build/C/man2/perf_event_open.2:1152
3896 msgid ""
3897 "If B<PERF_FORMAT_GROUP> was specified to allow reading all events in a group "
3898 "at once:"
3899 msgstr ""
3900
3901 #. type: Plain text
3902 #: build/C/man2/perf_event_open.2:1164
3903 #, no-wrap
3904 msgid ""
3905 "struct read_format {\n"
3906 "    u64 nr;            /* The number of events */\n"
3907 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3908 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3909 "    struct\n"
3910 "        u64 value;     /* The value of the event */\n"
3911 "        u64 id;        /* if PERF_FORMAT_ID */\n"
3912 "    } values[nr];\n"
3913 "};\n"
3914 msgstr ""
3915
3916 #. type: Plain text
3917 #: build/C/man2/perf_event_open.2:1172
3918 msgid "If B<PERF_FORMAT_GROUP> was I<not> specified:"
3919 msgstr ""
3920
3921 #. type: Plain text
3922 #: build/C/man2/perf_event_open.2:1181
3923 #, no-wrap
3924 msgid ""
3925 "struct read_format {\n"
3926 "    u64 value;         /* The value of the event */\n"
3927 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3928 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3929 "    u64 id;            /* if PERF_FORMAT_ID */\n"
3930 "};\n"
3931 msgstr ""
3932
3933 #. type: Plain text
3934 #: build/C/man2/perf_event_open.2:1185
3935 msgid "The values read are as follows:"
3936 msgstr ""
3937
3938 #. type: TP
3939 #: build/C/man2/perf_event_open.2:1185
3940 #, no-wrap
3941 msgid "I<nr>"
3942 msgstr ""
3943
3944 #. type: Plain text
3945 #: build/C/man2/perf_event_open.2:1191
3946 msgid ""
3947 "The number of events in this file descriptor.  Only available if "
3948 "B<PERF_FORMAT_GROUP> was specified."
3949 msgstr ""
3950
3951 #. type: TP
3952 #: build/C/man2/perf_event_open.2:1191
3953 #, no-wrap
3954 msgid "I<time_enabled>, I<time_running>"
3955 msgstr ""
3956
3957 #. type: Plain text
3958 #: build/C/man2/perf_event_open.2:1203
3959 msgid ""
3960 "Total time the event was enabled and running.  Normally these are the same.  "
3961 "If more events are started, then available counter slots on the PMU, then "
3962 "multiplexing happens and events run only part of the time.  In that case, "
3963 "the I<time_enabled> and I<time running> values can be used to scale an "
3964 "estimated value for the count."
3965 msgstr ""
3966
3967 #. type: TP
3968 #: build/C/man2/perf_event_open.2:1203
3969 #, no-wrap
3970 msgid "I<value>"
3971 msgstr ""
3972
3973 #. type: Plain text
3974 #: build/C/man2/perf_event_open.2:1206
3975 msgid "An unsigned 64-bit value containing the counter result."
3976 msgstr ""
3977
3978 #. type: TP
3979 #: build/C/man2/perf_event_open.2:1206 build/C/man2/perf_event_open.2:1602 build/C/man2/perf_event_open.2:1756
3980 #, no-wrap
3981 msgid "I<id>"
3982 msgstr ""
3983
3984 #. type: Plain text
3985 #: build/C/man2/perf_event_open.2:1212
3986 msgid ""
3987 "A globally unique value for this particular event, only there if "
3988 "B<PERF_FORMAT_ID> was specified in I<read_format>."
3989 msgstr ""
3990
3991 #. type: SS
3992 #: build/C/man2/perf_event_open.2:1212
3993 #, no-wrap
3994 msgid "MMAP layout"
3995 msgstr ""
3996
3997 #. type: Plain text
3998 #: build/C/man2/perf_event_open.2:1222
3999 msgid ""
4000 "When using B<perf_event_open>()  in sampled mode, asynchronous events (like "
4001 "counter overflow or B<PROT_EXEC> mmap tracking)  are logged into a "
4002 "ring-buffer.  This ring-buffer is created and accessed through B<mmap>(2)."
4003 msgstr ""
4004
4005 #. type: Plain text
4006 #: build/C/man2/perf_event_open.2:1228
4007 msgid ""
4008 "The mmap size should be 1+2^n pages, where the first page is a metadata page "
4009 "(I<struct perf_event_mmap_page>)  that contains various bits of information "
4010 "such as where the ring-buffer head is."
4011 msgstr ""
4012
4013 #. type: Plain text
4014 #: build/C/man2/perf_event_open.2:1231
4015 msgid ""
4016 "Before kernel 2.6.39, there is a bug that means you must allocate a mmap "
4017 "ring buffer when sampling even if you do not plan to access it."
4018 msgstr ""
4019
4020 #. type: Plain text
4021 #: build/C/man2/perf_event_open.2:1233
4022 msgid "The structure of the first metadata mmap page is as follows:"
4023 msgstr ""
4024
4025 #. type: Plain text
4026 #: build/C/man2/perf_event_open.2:1262
4027 #, no-wrap
4028 msgid ""
4029 "struct perf_event_mmap_page {\n"
4030 "    __u32 version;        /* version number of this structure */\n"
4031 "    __u32 compat_version; /* lowest version this is compat with */\n"
4032 "    __u32 lock;           /* seqlock for synchronization */\n"
4033 "    __u32 index;          /* hardware counter identifier */\n"
4034 "    __s64 offset;         /* add to hardware counter value */\n"
4035 "    __u64 time_enabled;   /* time event active */\n"
4036 "    __u64 time_running;   /* time event on CPU */\n"
4037 "    union {\n"
4038 "        __u64   capabilities;\n"
4039 "        struct {\n"
4040 "            __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,\n"
4041 "                  cap_bit0_is_deprecated : 1,\n"
4042 "                  cap_user_rdpmc         : 1,\n"
4043 "                  cap_user_time          : 1,\n"
4044 "                  cap_user_time_zero     : 1,\n"
4045 "        };\n"
4046 "    };\n"
4047 "    __u16 pmc_width;\n"
4048 "    __u16 time_shift;\n"
4049 "    __u32 time_mult;\n"
4050 "    __u64 time_offset;\n"
4051 "    __u64 __reserved[120];   /* Pad to 1k */\n"
4052 "    __u64 data_head;         /* head in the data section */\n"
4053 "    __u64 data_tail;         /* user-space written tail */\n"
4054 "}\n"
4055 msgstr ""
4056
4057 #. type: Plain text
4058 #: build/C/man2/perf_event_open.2:1268
4059 msgid ""
4060 "The following list describes the fields in the I<perf_event_mmap_page> "
4061 "structure in more detail:"
4062 msgstr ""
4063
4064 #. type: TP
4065 #: build/C/man2/perf_event_open.2:1268
4066 #, no-wrap
4067 msgid "I<version>"
4068 msgstr ""
4069
4070 #. type: Plain text
4071 #: build/C/man2/perf_event_open.2:1271
4072 msgid "Version number of this structure."
4073 msgstr ""
4074
4075 #. type: TP
4076 #: build/C/man2/perf_event_open.2:1271
4077 #, no-wrap
4078 msgid "I<compat_version>"
4079 msgstr ""
4080
4081 #. type: Plain text
4082 #: build/C/man2/perf_event_open.2:1274
4083 msgid "The lowest version this is compatible with."
4084 msgstr ""
4085
4086 #. type: TP
4087 #: build/C/man2/perf_event_open.2:1274
4088 #, no-wrap
4089 msgid "I<lock>"
4090 msgstr ""
4091
4092 #. type: Plain text
4093 #: build/C/man2/perf_event_open.2:1277
4094 msgid "A seqlock for synchronization."
4095 msgstr ""
4096
4097 #. type: TP
4098 #: build/C/man2/perf_event_open.2:1277
4099 #, no-wrap
4100 msgid "I<index>"
4101 msgstr ""
4102
4103 #. type: Plain text
4104 #: build/C/man2/perf_event_open.2:1280
4105 msgid "A unique hardware counter identifier."
4106 msgstr ""
4107
4108 #. type: TP
4109 #: build/C/man2/perf_event_open.2:1280
4110 #, no-wrap
4111 msgid "I<offset>"
4112 msgstr ""
4113
4114 #. type: Plain text
4115 #: build/C/man2/perf_event_open.2:1285
4116 msgid ""
4117 "When using rdpmc for reads this offset value must be added to the one "
4118 "returned by rdpmc to get the current total event count."
4119 msgstr ""
4120
4121 #. type: TP
4122 #: build/C/man2/perf_event_open.2:1285
4123 #, no-wrap
4124 msgid "I<time_enabled>"
4125 msgstr ""
4126
4127 #. type: Plain text
4128 #: build/C/man2/perf_event_open.2:1288
4129 msgid "Time the event was active."
4130 msgstr ""
4131
4132 #. type: TP
4133 #: build/C/man2/perf_event_open.2:1288
4134 #, no-wrap
4135 msgid "I<time_running>"
4136 msgstr ""
4137
4138 #. type: Plain text
4139 #: build/C/man2/perf_event_open.2:1291
4140 msgid "Time the event was running."
4141 msgstr ""
4142
4143 #. type: TP
4144 #: build/C/man2/perf_event_open.2:1291
4145 #, no-wrap
4146 msgid "I<cap_usr_time> / I<cap_usr_rdpmc> / I<cap_bit0> (since Linux 3.4)"
4147 msgstr ""
4148
4149 #. type: Plain text
4150 #: build/C/man2/perf_event_open.2:1304
4151 msgid ""
4152 "There was a bug in the definition of I<cap_usr_time> and I<cap_usr_rdpmc> "
4153 "from Linux 3.4 until Linux 3.11.  Both bits were defined to point to the "
4154 "same location, so it was impossible to know if I<cap_usr_time> or "
4155 "I<cap_usr_rdpmc> were actually set."
4156 msgstr ""
4157
4158 #. type: Plain text
4159 #: build/C/man2/perf_event_open.2:1312
4160 msgid ""
4161 "Starting with 3.12 these are renamed to I<cap_bit0> and you should use the "
4162 "new I<cap_user_time> and I<cap_user_rdpmc> fields instead."
4163 msgstr ""
4164
4165 #. type: TP
4166 #: build/C/man2/perf_event_open.2:1313
4167 #, no-wrap
4168 msgid "I<cap_bit0_is_deprecated> (since Linux 3.12)"
4169 msgstr ""
4170
4171 #. type: Plain text
4172 #: build/C/man2/perf_event_open.2:1321
4173 msgid ""
4174 "If set, this bit indicates that the kernel supports the properly separated "
4175 "I<cap_user_time> and I<cap_user_rdpmc> bits."
4176 msgstr ""
4177
4178 #. type: Plain text
4179 #: build/C/man2/perf_event_open.2:1328
4180 msgid ""
4181 "If not-set, it indicates an older kernel where I<cap_usr_time> and "
4182 "I<cap_usr_rdpmc> map to the same bit and thus both features should be used "
4183 "with caution."
4184 msgstr ""
4185
4186 #. type: TP
4187 #: build/C/man2/perf_event_open.2:1329
4188 #, no-wrap
4189 msgid "I<cap_user_rdpmc> (since Linux 3.12)"
4190 msgstr ""
4191
4192 #. type: Plain text
4193 #: build/C/man2/perf_event_open.2:1334
4194 msgid ""
4195 "If the hardware supports user-space read of performance counters without "
4196 "syscall (this is the \"rdpmc\" instruction on x86), then the following code "
4197 "can be used to do a read:"
4198 msgstr ""
4199
4200 #. type: Plain text
4201 #: build/C/man2/perf_event_open.2:1340
4202 #, no-wrap
4203 msgid ""
4204 "u32 seq, time_mult, time_shift, idx, width;\n"
4205 "u64 count, enabled, running;\n"
4206 "u64 cyc, time_offset;\n"
4207 msgstr ""
4208
4209 #. type: Plain text
4210 #: build/C/man2/perf_event_open.2:1346
4211 #, no-wrap
4212 msgid ""
4213 "do {\n"
4214 "    seq = pc-E<gt>lock;\n"
4215 "    barrier();\n"
4216 "    enabled = pc-E<gt>time_enabled;\n"
4217 "    running = pc-E<gt>time_running;\n"
4218 msgstr ""
4219
4220 #. type: Plain text
4221 #: build/C/man2/perf_event_open.2:1353
4222 #, no-wrap
4223 msgid ""
4224 "    if (pc-E<gt>cap_usr_time && enabled != running) {\n"
4225 "        cyc = rdtsc();\n"
4226 "        time_offset = pc-E<gt>time_offset;\n"
4227 "        time_mult   = pc-E<gt>time_mult;\n"
4228 "        time_shift  = pc-E<gt>time_shift;\n"
4229 "    }\n"
4230 msgstr ""
4231
4232 #. type: Plain text
4233 #: build/C/man2/perf_event_open.2:1356
4234 #, no-wrap
4235 msgid ""
4236 "    idx = pc-E<gt>index;\n"
4237 "    count = pc-E<gt>offset;\n"
4238 msgstr ""
4239
4240 #. type: Plain text
4241 #: build/C/man2/perf_event_open.2:1361
4242 #, no-wrap
4243 msgid ""
4244 "    if (pc-E<gt>cap_usr_rdpmc && idx) {\n"
4245 "        width = pc-E<gt>pmc_width;\n"
4246 "        count += rdpmc(idx - 1);\n"
4247 "    }\n"
4248 msgstr ""
4249
4250 #. type: Plain text
4251 #: build/C/man2/perf_event_open.2:1364
4252 #, no-wrap
4253 msgid ""
4254 "    barrier();\n"
4255 "} while (pc-E<gt>lock != seq);\n"
4256 msgstr ""
4257
4258 #. type: TP
4259 #: build/C/man2/perf_event_open.2:1366
4260 #, no-wrap
4261 msgid "I<cap_user_time  (since Linux 3.12)>"
4262 msgstr ""
4263
4264 #. type: Plain text
4265 #: build/C/man2/perf_event_open.2:1370
4266 msgid ""
4267 "This bit indicates the hardware has a constant, nonstop timestamp counter "
4268 "(TSC on x86)."
4269 msgstr ""
4270
4271 #. type: TP
4272 #: build/C/man2/perf_event_open.2:1370
4273 #, no-wrap
4274 msgid "I<cap_user_time_zero> (since Linux 3.12)"
4275 msgstr ""
4276
4277 #. type: Plain text
4278 #: build/C/man2/perf_event_open.2:1376
4279 msgid ""
4280 "Indicates the presence of I<time_zero> which allows mapping timestamp values "
4281 "to the hardware clock."
4282 msgstr ""
4283
4284 #. type: TP
4285 #: build/C/man2/perf_event_open.2:1376
4286 #, no-wrap
4287 msgid "I<pmc_width>"
4288 msgstr ""
4289
4290 #. type: Plain text
4291 #: build/C/man2/perf_event_open.2:1383
4292 msgid ""
4293 "If I<cap_usr_rdpmc>, this field provides the bit-width of the value read "
4294 "using the rdpmc or equivalent instruction.  This can be used to sign extend "
4295 "the result like:"
4296 msgstr ""
4297
4298 #. type: Plain text
4299 #: build/C/man2/perf_event_open.2:1389
4300 #, no-wrap
4301 msgid ""
4302 "pmc E<lt>E<lt>= 64 - pmc_width;\n"
4303 "pmc E<gt>E<gt>= 64 - pmc_width; // signed shift right\n"
4304 "count += pmc;\n"
4305 msgstr ""
4306
4307 #. type: TP
4308 #: build/C/man2/perf_event_open.2:1391
4309 #, no-wrap
4310 msgid "I<time_shift>, I<time_mult>, I<time_offset>"
4311 msgstr ""
4312
4313 #. type: Plain text
4314 #: build/C/man2/perf_event_open.2:1398
4315 msgid ""
4316 "If I<cap_usr_time>, these fields can be used to compute the time delta since "
4317 "time_enabled (in nanoseconds) using rdtsc or similar."
4318 msgstr ""
4319
4320 #. type: Plain text
4321 #: build/C/man2/perf_event_open.2:1406
4322 #, no-wrap
4323 msgid ""
4324 "    u64 quot, rem;\n"
4325 "    u64 delta;\n"
4326 "    quot = (cyc E<gt>E<gt> time_shift);\n"
4327 "    rem = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
4328 "    delta = time_offset + quot * time_mult +\n"
4329 "            ((rem * time_mult) E<gt>E<gt> time_shift);\n"
4330 msgstr ""
4331
4332 #. type: Plain text
4333 #: build/C/man2/perf_event_open.2:1418
4334 msgid ""
4335 "Where I<time_offset>, I<time_mult>, I<time_shift>, and I<cyc> are read in "
4336 "the seqcount loop described above.  This delta can then be added to enabled "
4337 "and possible running (if idx), improving the scaling:"
4338 msgstr ""
4339
4340 #. type: Plain text
4341 #: build/C/man2/perf_event_open.2:1426
4342 #, no-wrap
4343 msgid ""
4344 "    enabled += delta;\n"
4345 "    if (idx)\n"
4346 "        running += delta;\n"
4347 "    quot = count / running;\n"
4348 "    rem  = count % running;\n"
4349 "    count = quot * enabled + (rem * enabled) / running;\n"
4350 msgstr ""
4351
4352 #. type: TP
4353 #: build/C/man2/perf_event_open.2:1427
4354 #, no-wrap
4355 msgid "I<time_zero> (since Linux 3.12)"
4356 msgstr ""
4357
4358 #. type: Plain text
4359 #: build/C/man2/perf_event_open.2:1435
4360 msgid ""
4361 "If I<cap_usr_time_zero> is set, then the hardware clock (the TSC timestamp "
4362 "counter on x86)  can be calculated from the I<time_zero>, I<time_mult>, and "
4363 "I<time_shift> values:"
4364 msgstr ""
4365
4366 #. type: Plain text
4367 #: build/C/man2/perf_event_open.2:1441
4368 #, no-wrap
4369 msgid ""
4370 "    time = timestamp - time_zero;\n"
4371 "    quot = time / time_mult;\n"
4372 "    rem  = time % time_mult;\n"
4373 "    cyc = (quot E<lt>E<lt> time_shift) + (rem E<lt>E<lt> time_shift) / "
4374 "time_mult;\n"
4375 msgstr ""
4376
4377 #. type: Plain text
4378 #: build/C/man2/perf_event_open.2:1444
4379 msgid "And vice versa:"
4380 msgstr ""
4381
4382 #. type: Plain text
4383 #: build/C/man2/perf_event_open.2:1450
4384 #, no-wrap
4385 msgid ""
4386 "    quot = cyc E<gt>E<gt> time_shift;\n"
4387 "    rem  = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
4388 "    timestamp = time_zero + quot * time_mult +\n"
4389 "        ((rem * time_mult) E<gt>E<gt> time_shift);\n"
4390 msgstr ""
4391
4392 #. type: TP
4393 #: build/C/man2/perf_event_open.2:1451
4394 #, no-wrap
4395 msgid "I<data_head>"
4396 msgstr ""
4397
4398 #. type: Plain text
4399 #: build/C/man2/perf_event_open.2:1457
4400 msgid ""
4401 "This points to the head of the data section.  The value continuously "
4402 "increases, it does not wrap.  The value needs to be manually wrapped by the "
4403 "size of the mmap buffer before accessing the samples."
4404 msgstr ""
4405
4406 #. type: Plain text
4407 #: build/C/man2/perf_event_open.2:1462
4408 msgid ""
4409 "On SMP-capable platforms, after reading the I<data_head> value, user space "
4410 "should issue an rmb()."
4411 msgstr ""
4412
4413 #. type: TP
4414 #: build/C/man2/perf_event_open.2:1462
4415 #, no-wrap
4416 msgid "I<data_tail>"
4417 msgstr ""
4418
4419 #. type: Plain text
4420 #: build/C/man2/perf_event_open.2:1470
4421 msgid ""
4422 "When the mapping is B<PROT_WRITE>, the I<data_tail> value should be written "
4423 "by user space to reflect the last read data.  In this case, the kernel will "
4424 "not overwrite unread data."
4425 msgstr ""
4426
4427 #. type: Plain text
4428 #: build/C/man2/perf_event_open.2:1472
4429 msgid "The following 2^n ring-buffer pages have the layout described below."
4430 msgstr ""
4431
4432 #. type: Plain text
4433 #: build/C/man2/perf_event_open.2:1486
4434 msgid ""
4435 "If I<perf_event_attr.sample_id_all> is set, then all event types will have "
4436 "the sample_type selected fields related to where/when (identity)  an event "
4437 "took place (TID, TIME, ID, CPU, STREAM_ID) described in "
4438 "B<PERF_RECORD_SAMPLE> below, it will be stashed just after the "
4439 "I<perf_event_header> and the fields already present for the existing fields, "
4440 "that is, at the end of the payload.  That way a newer perf.data file will be "
4441 "supported by older perf tools, with these new optional fields being ignored."
4442 msgstr ""
4443
4444 #. type: Plain text
4445 #: build/C/man2/perf_event_open.2:1488
4446 msgid "The mmap values start with a header:"
4447 msgstr ""
4448
4449 #. type: Plain text
4450 #: build/C/man2/perf_event_open.2:1496
4451 #, no-wrap
4452 msgid ""
4453 "struct perf_event_header {\n"
4454 "    __u32   type;\n"
4455 "    __u16   misc;\n"
4456 "    __u16   size;\n"
4457 "};\n"
4458 msgstr ""
4459
4460 #. type: Plain text
4461 #: build/C/man2/perf_event_open.2:1504
4462 msgid ""
4463 "Below, we describe the I<perf_event_header> fields in more detail.  For ease "
4464 "of reading, the fields with shorter descriptions are presented first."
4465 msgstr ""
4466
4467 #. type: Plain text
4468 #: build/C/man2/perf_event_open.2:1507
4469 msgid "This indicates the size of the record."
4470 msgstr ""
4471
4472 #. type: TP
4473 #: build/C/man2/perf_event_open.2:1507
4474 #, no-wrap
4475 msgid "I<misc>"
4476 msgstr ""
4477
4478 #. type: Plain text
4479 #: build/C/man2/perf_event_open.2:1512
4480 msgid "The I<misc> field contains additional information about the sample."
4481 msgstr ""
4482
4483 #. type: Plain text
4484 #: build/C/man2/perf_event_open.2:1517
4485 msgid ""
4486 "The CPU mode can be determined from this value by masking with "
4487 "B<PERF_RECORD_MISC_CPUMODE_MASK> and looking for one of the following (note "
4488 "these are not bit masks, only one can be set at a time):"
4489 msgstr ""
4490
4491 #. type: TP
4492 #: build/C/man2/perf_event_open.2:1518
4493 #, no-wrap
4494 msgid "B<PERF_RECORD_MISC_CPUMODE_UNKNOWN>"
4495 msgstr ""
4496
4497 #. type: Plain text
4498 #: build/C/man2/perf_event_open.2:1521
4499 msgid "Unknown CPU mode."
4500 msgstr ""
4501
4502 #. type: TP
4503 #: build/C/man2/perf_event_open.2:1521
4504 #, no-wrap
4505 msgid "B<PERF_RECORD_MISC_KERNEL>"
4506 msgstr ""
4507
4508 #. type: Plain text
4509 #: build/C/man2/perf_event_open.2:1524
4510 msgid "Sample happened in the kernel."
4511 msgstr ""
4512
4513 #. type: TP
4514 #: build/C/man2/perf_event_open.2:1524
4515 #, no-wrap
4516 msgid "B<PERF_RECORD_MISC_USER>"
4517 msgstr ""
4518
4519 #. type: Plain text
4520 #: build/C/man2/perf_event_open.2:1527
4521 msgid "Sample happened in user code."
4522 msgstr ""
4523
4524 #. type: TP
4525 #: build/C/man2/perf_event_open.2:1527
4526 #, no-wrap
4527 msgid "B<PERF_RECORD_MISC_HYPERVISOR>"
4528 msgstr ""
4529
4530 #. type: Plain text
4531 #: build/C/man2/perf_event_open.2:1530
4532 msgid "Sample happened in the hypervisor."
4533 msgstr ""
4534
4535 #. type: TP
4536 #: build/C/man2/perf_event_open.2:1530
4537 #, no-wrap
4538 msgid "B<PERF_RECORD_MISC_GUEST_KERNEL>"
4539 msgstr ""
4540
4541 #. type: Plain text
4542 #: build/C/man2/perf_event_open.2:1533
4543 msgid "Sample happened in the guest kernel."
4544 msgstr ""
4545
4546 #. type: TP
4547 #: build/C/man2/perf_event_open.2:1533
4548 #, no-wrap
4549 msgid "B<PERF_RECORD_MISC_GUEST_USER>"
4550 msgstr ""
4551
4552 #. type: Plain text
4553 #: build/C/man2/perf_event_open.2:1536
4554 msgid "Sample happened in guest user code."
4555 msgstr ""
4556
4557 #. type: Plain text
4558 #: build/C/man2/perf_event_open.2:1540
4559 msgid "In addition, one of the following bits can be set:"
4560 msgstr ""
4561
4562 #. type: TP
4563 #: build/C/man2/perf_event_open.2:1540
4564 #, no-wrap
4565 msgid "B<PERF_RECORD_MISC_MMAP_DATA>"
4566 msgstr ""
4567
4568 #. type: Plain text
4569 #: build/C/man2/perf_event_open.2:1544
4570 msgid ""
4571 "This is set when the mapping is not executable; otherwise the mapping is "
4572 "executable."
4573 msgstr ""
4574
4575 #. type: TP
4576 #: build/C/man2/perf_event_open.2:1544
4577 #, no-wrap
4578 msgid "B<PERF_RECORD_MISC_EXACT_IP>"
4579 msgstr ""
4580
4581 #. type: Plain text
4582 #: build/C/man2/perf_event_open.2:1552
4583 msgid ""
4584 "This indicates that the content of B<PERF_SAMPLE_IP> points to the actual "
4585 "instruction that triggered the event.  See also "
4586 "I<perf_event_attr.precise_ip>."
4587 msgstr ""
4588
4589 #. type: TP
4590 #: build/C/man2/perf_event_open.2:1552
4591 #, no-wrap
4592 msgid "B<PERF_RECORD_MISC_EXT_RESERVED>"
4593 msgstr ""
4594
4595 #. type: Plain text
4596 #: build/C/man2/perf_event_open.2:1555
4597 msgid "This indicates there is extended data available (currently not used)."
4598 msgstr ""
4599
4600 #. type: Plain text
4601 #: build/C/man2/perf_event_open.2:1565
4602 msgid ""
4603 "The I<type> value is one of the below.  The values in the corresponding "
4604 "record (that follows the header)  depend on the I<type> selected as shown."
4605 msgstr ""
4606
4607 #. type: TP
4608 #: build/C/man2/perf_event_open.2:1567
4609 #, no-wrap
4610 msgid "B<PERF_RECORD_MMAP>"
4611 msgstr ""
4612
4613 #. type: Plain text
4614 #: build/C/man2/perf_event_open.2:1574
4615 msgid ""
4616 "The MMAP events record the B<PROT_EXEC> mappings so that we can correlate "
4617 "user-space IPs to code.  They have the following structure:"
4618 msgstr ""
4619
4620 #. type: Plain text
4621 #: build/C/man2/perf_event_open.2:1585
4622 #, no-wrap
4623 msgid ""
4624 "struct {\n"
4625 "    struct perf_event_header header;\n"
4626 "    u32    pid, tid;\n"
4627 "    u64    addr;\n"
4628 "    u64    len;\n"
4629 "    u64    pgoff;\n"
4630 "    char   filename[];\n"
4631 "};\n"
4632 msgstr ""
4633
4634 #. type: TP
4635 #: build/C/man2/perf_event_open.2:1587
4636 #, no-wrap
4637 msgid "B<PERF_RECORD_LOST>"
4638 msgstr ""
4639
4640 #. type: Plain text
4641 #: build/C/man2/perf_event_open.2:1590
4642 msgid "This record indicates when events are lost."
4643 msgstr ""
4644
4645 #. type: Plain text
4646 #: build/C/man2/perf_event_open.2:1599
4647 #, no-wrap
4648 msgid ""
4649 "struct {\n"
4650 "    struct perf_event_header header;\n"
4651 "    u64 id;\n"
4652 "    u64 lost;\n"
4653 "    struct sample_id sample_id;\n"
4654 "};\n"
4655 msgstr ""
4656
4657 #. type: Plain text
4658 #: build/C/man2/perf_event_open.2:1605
4659 msgid "is the unique event ID for the samples that were lost."
4660 msgstr ""
4661
4662 #. type: TP
4663 #: build/C/man2/perf_event_open.2:1605
4664 #, no-wrap
4665 msgid "I<lost>"
4666 msgstr ""
4667
4668 #. type: Plain text
4669 #: build/C/man2/perf_event_open.2:1608
4670 msgid "is the number of events that were lost."
4671 msgstr ""
4672
4673 #. type: TP
4674 #: build/C/man2/perf_event_open.2:1609
4675 #, no-wrap
4676 msgid "B<PERF_RECORD_COMM>"
4677 msgstr ""
4678
4679 #. type: Plain text
4680 #: build/C/man2/perf_event_open.2:1612
4681 msgid "This record indicates a change in the process name."
4682 msgstr ""
4683
4684 #. type: Plain text
4685 #: build/C/man2/perf_event_open.2:1621
4686 #, no-wrap
4687 msgid ""
4688 "struct {\n"
4689 "    struct perf_event_header header;\n"
4690 "    u32 pid, tid;\n"
4691 "    char comm[];\n"
4692 "    struct sample_id sample_id;\n"
4693 "};\n"
4694 msgstr ""
4695
4696 #. type: TP
4697 #: build/C/man2/perf_event_open.2:1623
4698 #, no-wrap
4699 msgid "B<PERF_RECORD_EXIT>"
4700 msgstr ""
4701
4702 #. type: Plain text
4703 #: build/C/man2/perf_event_open.2:1626
4704 msgid "This record indicates a process exit event."
4705 msgstr ""
4706
4707 #. type: Plain text
4708 #: build/C/man2/perf_event_open.2:1636 build/C/man2/perf_event_open.2:1666
4709 #, no-wrap
4710 msgid ""
4711 "struct {\n"
4712 "    struct perf_event_header header;\n"
4713 "    u32 pid, ppid;\n"
4714 "    u32 tid, ptid;\n"
4715 "    u64 time;\n"
4716 "    struct sample_id sample_id;\n"
4717 "};\n"
4718 msgstr ""
4719
4720 #. type: TP
4721 #: build/C/man2/perf_event_open.2:1638
4722 #, no-wrap
4723 msgid "B<PERF_RECORD_THROTTLE>, B<PERF_RECORD_UNTHROTTLE>"
4724 msgstr ""
4725
4726 #. type: Plain text
4727 #: build/C/man2/perf_event_open.2:1641
4728 msgid "This record indicates a throttle/unthrottle event."
4729 msgstr ""
4730
4731 #. type: Plain text
4732 #: build/C/man2/perf_event_open.2:1651
4733 #, no-wrap
4734 msgid ""
4735 "struct {\n"
4736 "    struct perf_event_header header;\n"
4737 "    u64 time;\n"
4738 "    u64 id;\n"
4739 "    u64 stream_id;\n"
4740 "    struct sample_id sample_id;\n"
4741 "};\n"
4742 msgstr ""
4743
4744 #. type: TP
4745 #: build/C/man2/perf_event_open.2:1653
4746 #, no-wrap
4747 msgid "B<PERF_RECORD_FORK>"
4748 msgstr ""
4749
4750 #. type: Plain text
4751 #: build/C/man2/perf_event_open.2:1656
4752 msgid "This record indicates a fork event."
4753 msgstr ""
4754
4755 #. type: TP
4756 #: build/C/man2/perf_event_open.2:1668
4757 #, no-wrap
4758 msgid "B<PERF_RECORD_READ>"
4759 msgstr ""
4760
4761 #. type: Plain text
4762 #: build/C/man2/perf_event_open.2:1671
4763 msgid "This record indicates a read event."
4764 msgstr ""
4765
4766 #. type: Plain text
4767 #: build/C/man2/perf_event_open.2:1680
4768 #, no-wrap
4769 msgid ""
4770 "struct {\n"
4771 "    struct perf_event_header header;\n"
4772 "    u32 pid, tid;\n"
4773 "    struct read_format values;\n"
4774 "    struct sample_id sample_id;\n"
4775 "};\n"
4776 msgstr ""
4777
4778 #. type: TP
4779 #: build/C/man2/perf_event_open.2:1682
4780 #, no-wrap
4781 msgid "B<PERF_RECORD_SAMPLE>"
4782 msgstr ""
4783
4784 #. type: Plain text
4785 #: build/C/man2/perf_event_open.2:1685
4786 msgid "This record indicates a sample."
4787 msgstr ""
4788
4789 #. type: Plain text
4790 #: build/C/man2/perf_event_open.2:1717
4791 #, no-wrap
4792 msgid ""
4793 "struct {\n"
4794 "    struct perf_event_header header;\n"
4795 "    u64   sample_id;  /* if PERF_SAMPLE_IDENTIFIER */\n"
4796 "    u64   ip;         /* if PERF_SAMPLE_IP */\n"
4797 "    u32   pid, tid;   /* if PERF_SAMPLE_TID */\n"
4798 "    u64   time;       /* if PERF_SAMPLE_TIME */\n"
4799 "    u64   addr;       /* if PERF_SAMPLE_ADDR */\n"
4800 "    u64   id;         /* if PERF_SAMPLE_ID */\n"
4801 "    u64   stream_id;  /* if PERF_SAMPLE_STREAM_ID */\n"
4802 "    u32   cpu, res;   /* if PERF_SAMPLE_CPU */\n"
4803 "    u64   period;     /* if PERF_SAMPLE_PERIOD */\n"
4804 "    struct read_format v; /* if PERF_SAMPLE_READ */\n"
4805 "    u64   nr;         /* if PERF_SAMPLE_CALLCHAIN */\n"
4806 "    u64   ips[nr];    /* if PERF_SAMPLE_CALLCHAIN */\n"
4807 "    u32   size;       /* if PERF_SAMPLE_RAW */\n"
4808 "    char  data[size]; /* if PERF_SAMPLE_RAW */\n"
4809 "    u64   bnr;        /* if PERF_SAMPLE_BRANCH_STACK */\n"
4810 "    struct perf_branch_entry lbr[bnr];\n"
4811 "                      /* if PERF_SAMPLE_BRANCH_STACK */\n"
4812 "    u64   abi;        /* if PERF_SAMPLE_REGS_USER */\n"
4813 "    u64   regs[weight(mask)];\n"
4814 "                      /* if PERF_SAMPLE_REGS_USER */\n"
4815 "    u64   size;       /* if PERF_SAMPLE_STACK_USER */\n"
4816 "    char  data[size]; /* if PERF_SAMPLE_STACK_USER */\n"
4817 "    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */\n"
4818 "    u64   weight;     /* if PERF_SAMPLE_WEIGHT */\n"
4819 "    u64   data_src;   /* if PERF_SAMPLE_DATA_SRC */\n"
4820 "    u64   transaction;/* if PERF_SAMPLE_TRANSACTION */\n"
4821 "};\n"
4822 msgstr ""
4823
4824 #. type: TP
4825 #: build/C/man2/perf_event_open.2:1719
4826 #, no-wrap
4827 msgid "I<sample_id>"
4828 msgstr ""
4829
4830 #. type: Plain text
4831 #: build/C/man2/perf_event_open.2:1729
4832 msgid ""
4833 "If B<PERF_SAMPLE_IDENTIFIER> is enabled, a 64-bit unique ID is included.  "
4834 "This is a duplication of the B<PERF_SAMPLE_ID> I<id> value, but included at "
4835 "the beginning of the sample so parsers can easily obtain the value."
4836 msgstr ""
4837
4838 #. type: TP
4839 #: build/C/man2/perf_event_open.2:1729
4840 #, no-wrap
4841 msgid "I<ip>"
4842 msgstr ""
4843
4844 #. type: Plain text
4845 #: build/C/man2/perf_event_open.2:1735
4846 msgid ""
4847 "If B<PERF_SAMPLE_IP> is enabled, then a 64-bit instruction pointer value is "
4848 "included."
4849 msgstr ""
4850
4851 #. type: TP
4852 #: build/C/man2/perf_event_open.2:1735
4853 #, no-wrap
4854 msgid "I<pid>, I<tid>"
4855 msgstr ""
4856
4857 #. type: Plain text
4858 #: build/C/man2/perf_event_open.2:1741
4859 msgid ""
4860 "If B<PERF_SAMPLE_TID> is enabled, then a 32-bit process ID and 32-bit thread "
4861 "ID are included."
4862 msgstr ""
4863
4864 #. type: TP
4865 #: build/C/man2/perf_event_open.2:1741
4866 #, no-wrap
4867 msgid "I<time>"
4868 msgstr ""
4869
4870 #. type: Plain text
4871 #: build/C/man2/perf_event_open.2:1749
4872 msgid ""
4873 "If B<PERF_SAMPLE_TIME> is enabled, then a 64-bit timestamp is included.  "
4874 "This is obtained via local_clock() which is a hardware timestamp if "
4875 "available and the jiffies value if not."
4876 msgstr ""
4877
4878 #. type: TP
4879 #: build/C/man2/perf_event_open.2:1749
4880 #, no-wrap
4881 msgid "I<addr>"
4882 msgstr ""
4883
4884 #. type: Plain text
4885 #: build/C/man2/perf_event_open.2:1756
4886 msgid ""
4887 "If B<PERF_SAMPLE_ADDR> is enabled, then a 64-bit address is included.  This "
4888 "is usually the address of a tracepoint, breakpoint, or software event; "
4889 "otherwise the value is 0."
4890 msgstr ""
4891
4892 #. type: Plain text
4893 #: build/C/man2/perf_event_open.2:1764
4894 msgid ""
4895 "If B<PERF_SAMPLE_ID> is enabled, a 64-bit unique ID is included.  If the "
4896 "event is a member of an event group, the group leader ID is returned.  This "
4897 "ID is the same as the one returned by B<PERF_FORMAT_ID>."
4898 msgstr ""
4899
4900 #. type: TP
4901 #: build/C/man2/perf_event_open.2:1764
4902 #, no-wrap
4903 msgid "I<stream_id>"
4904 msgstr ""
4905
4906 #. type: Plain text
4907 #: build/C/man2/perf_event_open.2:1774
4908 msgid ""
4909 "If B<PERF_SAMPLE_STREAM_ID> is enabled, a 64-bit unique ID is included.  "
4910 "Unlike B<PERF_SAMPLE_ID> the actual ID is returned, not the group leader.  "
4911 "This ID is the same as the one returned by B<PERF_FORMAT_ID>."
4912 msgstr ""
4913
4914 #. type: TP
4915 #: build/C/man2/perf_event_open.2:1774
4916 #, no-wrap
4917 msgid "I<cpu>, I<res>"
4918 msgstr ""
4919
4920 #. type: Plain text
4921 #: build/C/man2/perf_event_open.2:1781
4922 msgid ""
4923 "If B<PERF_SAMPLE_CPU> is enabled, this is a 32-bit value indicating which "
4924 "CPU was being used, in addition to a reserved (unused)  32-bit value."
4925 msgstr ""
4926
4927 #. type: TP
4928 #: build/C/man2/perf_event_open.2:1781
4929 #, no-wrap
4930 msgid "I<period>"
4931 msgstr ""
4932
4933 #. type: Plain text
4934 #: build/C/man2/perf_event_open.2:1787
4935 msgid ""
4936 "If B<PERF_SAMPLE_PERIOD> is enabled, a 64-bit value indicating the current "
4937 "sampling period is written."
4938 msgstr ""
4939
4940 #. type: TP
4941 #: build/C/man2/perf_event_open.2:1787
4942 #, no-wrap
4943 msgid "I<v>"
4944 msgstr ""
4945
4946 #. type: Plain text
4947 #: build/C/man2/perf_event_open.2:1798
4948 msgid ""
4949 "If B<PERF_SAMPLE_READ> is enabled, a structure of type read_format is "
4950 "included which has values for all events in the event group.  The values "
4951 "included depend on the I<read_format> value used at B<perf_event_open>()  "
4952 "time."
4953 msgstr ""
4954
4955 #. type: TP
4956 #: build/C/man2/perf_event_open.2:1798
4957 #, no-wrap
4958 msgid "I<nr>, I<ips[nr]>"
4959 msgstr ""
4960
4961 #. type: Plain text
4962 #: build/C/man2/perf_event_open.2:1806
4963 msgid ""
4964 "If B<PERF_SAMPLE_CALLCHAIN> is enabled, then a 64-bit number is included "
4965 "which indicates how many following 64-bit instruction pointers will follow.  "
4966 "This is the current callchain."
4967 msgstr ""
4968
4969 #. type: TP
4970 #: build/C/man2/perf_event_open.2:1806
4971 #, no-wrap
4972 msgid "I<size>, I<data[size]>"
4973 msgstr ""
4974
4975 #. type: Plain text
4976 #: build/C/man2/perf_event_open.2:1813
4977 msgid ""
4978 "If B<PERF_SAMPLE_RAW> is enabled, then a 32-bit value indicating size is "
4979 "included followed by an array of 8-bit values of length size.  The values "
4980 "are padded with 0 to have 64-bit alignment."
4981 msgstr ""
4982
4983 #. type: Plain text
4984 #: build/C/man2/perf_event_open.2:1818
4985 msgid ""
4986 "This RAW record data is opaque with respect to the ABI.  The ABI doesn't "
4987 "make any promises with respect to the stability of its content, it may vary "
4988 "depending on event, hardware, and kernel version."
4989 msgstr ""
4990
4991 #. type: TP
4992 #: build/C/man2/perf_event_open.2:1818
4993 #, no-wrap
4994 msgid "I<bnr>, I<lbr[bnr]>"
4995 msgstr ""
4996
4997 #. type: Plain text
4998 #: build/C/man2/perf_event_open.2:1827
4999 msgid ""
5000 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then a 64-bit value indicating "
5001 "the number of records is included, followed by I<bnr> I<perf_branch_entry> "
5002 "structures which each include the fields:"
5003 msgstr ""
5004
5005 #. type: TP
5006 #: build/C/man2/perf_event_open.2:1828
5007 #, no-wrap
5008 msgid "I<from>"
5009 msgstr ""
5010
5011 #. type: Plain text
5012 #: build/C/man2/perf_event_open.2:1831
5013 msgid "This indicates the source instruction (may not be a branch)."
5014 msgstr ""
5015
5016 #. type: TP
5017 #: build/C/man2/perf_event_open.2:1831
5018 #, no-wrap
5019 msgid "I<to>"
5020 msgstr ""
5021
5022 #. type: Plain text
5023 #: build/C/man2/perf_event_open.2:1834
5024 msgid "The branch target."
5025 msgstr ""
5026
5027 #. type: TP
5028 #: build/C/man2/perf_event_open.2:1834
5029 #, no-wrap
5030 msgid "I<mispred>"
5031 msgstr ""
5032
5033 #. type: Plain text
5034 #: build/C/man2/perf_event_open.2:1837
5035 msgid "The branch target was mispredicted."
5036 msgstr ""
5037
5038 #. type: TP
5039 #: build/C/man2/perf_event_open.2:1837
5040 #, no-wrap
5041 msgid "I<predicted>"
5042 msgstr ""
5043
5044 #. type: Plain text
5045 #: build/C/man2/perf_event_open.2:1840
5046 msgid "The branch target was predicted."
5047 msgstr ""
5048
5049 #. type: TP
5050 #: build/C/man2/perf_event_open.2:1840
5051 #, no-wrap
5052 msgid "I<in_tx> (since Linux 3.11)"
5053 msgstr ""
5054
5055 #. type: Plain text
5056 #: build/C/man2/perf_event_open.2:1843
5057 msgid "The branch was in a transactional memory transaction."
5058 msgstr ""
5059
5060 #. type: TP
5061 #: build/C/man2/perf_event_open.2:1843
5062 #, no-wrap
5063 msgid "I<abort> (since Linux 3.11)"
5064 msgstr ""
5065
5066 #. type: Plain text
5067 #: build/C/man2/perf_event_open.2:1846
5068 msgid "The branch was in an aborted transactional memory transaction."
5069 msgstr ""
5070
5071 #. type: Plain text
5072 #: build/C/man2/perf_event_open.2:1850
5073 msgid ""
5074 "The entries are from most to least recent, so the first entry has the most "
5075 "recent branch."
5076 msgstr ""
5077
5078 #. type: Plain text
5079 #: build/C/man2/perf_event_open.2:1857
5080 msgid ""
5081 "Support for I<mispred> and I<predicted> is optional; if not supported, both "
5082 "values will be 0."
5083 msgstr ""
5084
5085 #. type: Plain text
5086 #: build/C/man2/perf_event_open.2:1861
5087 msgid ""
5088 "The type of branches recorded is specified by the I<branch_sample_type> "
5089 "field."
5090 msgstr ""
5091
5092 #. type: TP
5093 #: build/C/man2/perf_event_open.2:1863
5094 #, no-wrap
5095 msgid "I<abi>, I<regs[weight(mask)]>"
5096 msgstr ""
5097
5098 #. type: Plain text
5099 #: build/C/man2/perf_event_open.2:1868
5100 msgid ""
5101 "If B<PERF_SAMPLE_REGS_USER> is enabled, then the user CPU registers are "
5102 "recorded."
5103 msgstr ""
5104
5105 #. type: Plain text
5106 #: build/C/man2/perf_event_open.2:1874
5107 msgid ""
5108 "The I<abi> field is one of B<PERF_SAMPLE_REGS_ABI_NONE>, "
5109 "B<PERF_SAMPLE_REGS_ABI_32> or B<PERF_SAMPLE_REGS_ABI_64>."
5110 msgstr ""
5111
5112 #. type: Plain text
5113 #: build/C/man2/perf_event_open.2:1884
5114 msgid ""
5115 "The I<regs> field is an array of the CPU registers that were specified by "
5116 "the I<sample_regs_user> attr field.  The number of values is the number of "
5117 "bits set in the I<sample_regs_user> bit mask."
5118 msgstr ""
5119
5120 #. type: TP
5121 #: build/C/man2/perf_event_open.2:1884
5122 #, no-wrap
5123 msgid "I<size>, I<data[size]>, I<dyn_size>"
5124 msgstr ""
5125
5126 #. type: Plain text
5127 #: build/C/man2/perf_event_open.2:1898
5128 msgid ""
5129 "If B<PERF_SAMPLE_STACK_USER> is enabled, then record the user stack to "
5130 "enable backtracing.  I<size> is the size requested by the user in "
5131 "I<stack_user_size> or else the maximum record size.  I<data> is the stack "
5132 "data.  I<dyn_size> is the amount of data actually dumped (can be less than "
5133 "I<size>)."
5134 msgstr ""
5135
5136 #. type: TP
5137 #: build/C/man2/perf_event_open.2:1898
5138 #, no-wrap
5139 msgid "I<weight>"
5140 msgstr ""
5141
5142 #. type: Plain text
5143 #: build/C/man2/perf_event_open.2:1906
5144 msgid ""
5145 "If B<PERF_SAMPLE_WEIGHT> is enabled, then a 64-bit value provided by the "
5146 "hardware is recorded that indicates how costly the event was.  This allows "
5147 "expensive events to stand out more clearly in profiles."
5148 msgstr ""
5149
5150 #. type: TP
5151 #: build/C/man2/perf_event_open.2:1906
5152 #, no-wrap
5153 msgid "I<data_src>"
5154 msgstr ""
5155
5156 #. type: Plain text
5157 #: build/C/man2/perf_event_open.2:1912
5158 msgid ""
5159 "If B<PERF_SAMPLE_DATA_SRC> is enabled, then a 64-bit value is recorded that "
5160 "is made up of the following fields:"
5161 msgstr ""
5162
5163 #. type: TP
5164 #: build/C/man2/perf_event_open.2:1913
5165 #, no-wrap
5166 msgid "I<mem_op>"
5167 msgstr ""
5168
5169 #. type: Plain text
5170 #: build/C/man2/perf_event_open.2:1916
5171 msgid "Type of opcode, a bitwise combination of:"
5172 msgstr ""
5173
5174 #. type: TP
5175 #: build/C/man2/perf_event_open.2:1919
5176 #, no-wrap
5177 msgid "B<PERF_MEM_OP_NA>"
5178 msgstr ""
5179
5180 #. type: Plain text
5181 #: 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
5182 msgid "Not available"
5183 msgstr ""
5184
5185 #. type: TP
5186 #: build/C/man2/perf_event_open.2:1922
5187 #, no-wrap
5188 msgid "B<PERF_MEM_OP_LOAD>"
5189 msgstr ""
5190
5191 #. type: Plain text
5192 #: build/C/man2/perf_event_open.2:1925
5193 msgid "Load instruction"
5194 msgstr ""
5195
5196 #. type: TP
5197 #: build/C/man2/perf_event_open.2:1925
5198 #, no-wrap
5199 msgid "B<PERF_MEM_OP_STORE>"
5200 msgstr ""
5201
5202 #. type: Plain text
5203 #: build/C/man2/perf_event_open.2:1928
5204 msgid "Store instruction"
5205 msgstr ""
5206
5207 #. type: TP
5208 #: build/C/man2/perf_event_open.2:1928
5209 #, no-wrap
5210 msgid "B<PERF_MEM_OP_PFETCH>"
5211 msgstr ""
5212
5213 #. type: Plain text
5214 #: build/C/man2/perf_event_open.2:1931
5215 msgid "Prefetch"
5216 msgstr ""
5217
5218 #. type: TP
5219 #: build/C/man2/perf_event_open.2:1931
5220 #, no-wrap
5221 msgid "B<PERF_MEM_OP_EXEC>"
5222 msgstr ""
5223
5224 #. type: Plain text
5225 #: build/C/man2/perf_event_open.2:1934
5226 msgid "Executable code"
5227 msgstr ""
5228
5229 #. type: TP
5230 #: build/C/man2/perf_event_open.2:1936
5231 #, no-wrap
5232 msgid "I<mem_lvl>"
5233 msgstr ""
5234
5235 #. type: Plain text
5236 #: build/C/man2/perf_event_open.2:1939
5237 msgid "Memory hierarchy level hit or miss, a bitwise combination of:"
5238 msgstr ""
5239
5240 #. type: TP
5241 #: build/C/man2/perf_event_open.2:1942
5242 #, no-wrap
5243 msgid "B<PERF_MEM_LVL_NA>"
5244 msgstr ""
5245
5246 #. type: TP
5247 #: build/C/man2/perf_event_open.2:1945
5248 #, no-wrap
5249 msgid "B<PERF_MEM_LVL_HIT>"
5250 msgstr ""
5251
5252 #. type: Plain text
5253 #: build/C/man2/perf_event_open.2:1948 build/C/man2/perf_event_open.2:2035
5254 msgid "Hit"
5255 msgstr ""
5256
5257 #. type: TP
5258 #: build/C/man2/perf_event_open.2:1948
5259 #, no-wrap
5260 msgid "B<PERF_MEM_LVL_MISS>"
5261 msgstr ""
5262
5263 #. type: Plain text
5264 #: build/C/man2/perf_event_open.2:1951 build/C/man2/perf_event_open.2:2038
5265 msgid "Miss"
5266 msgstr ""
5267
5268 #. type: TP
5269 #: build/C/man2/perf_event_open.2:1951
5270 #, no-wrap
5271 msgid "B<PERF_MEM_LVL_L1>"
5272 msgstr ""
5273
5274 #. type: Plain text
5275 #: build/C/man2/perf_event_open.2:1954
5276 msgid "Level 1 cache"
5277 msgstr ""
5278
5279 #. type: TP
5280 #: build/C/man2/perf_event_open.2:1954
5281 #, no-wrap
5282 msgid "B<PERF_MEM_LVL_LFB>"
5283 msgstr ""
5284
5285 #. type: Plain text
5286 #: build/C/man2/perf_event_open.2:1957
5287 msgid "Line fill buffer"
5288 msgstr ""
5289
5290 #. type: TP
5291 #: build/C/man2/perf_event_open.2:1957
5292 #, no-wrap
5293 msgid "B<PERF_MEM_LVL_L2>"
5294 msgstr ""
5295
5296 #. type: Plain text
5297 #: build/C/man2/perf_event_open.2:1960
5298 msgid "Level 2 cache"
5299 msgstr ""
5300
5301 #. type: TP
5302 #: build/C/man2/perf_event_open.2:1960
5303 #, no-wrap
5304 msgid "B<PERF_MEM_LVL_L3>"
5305 msgstr ""
5306
5307 #. type: Plain text
5308 #: build/C/man2/perf_event_open.2:1963
5309 msgid "Level 3 cache"
5310 msgstr ""
5311
5312 #. type: TP
5313 #: build/C/man2/perf_event_open.2:1963
5314 #, no-wrap
5315 msgid "B<PERF_MEM_LVL_LOC_RAM>"
5316 msgstr ""
5317
5318 #. type: Plain text
5319 #: build/C/man2/perf_event_open.2:1966
5320 msgid "Local DRAM"
5321 msgstr ""
5322
5323 #. type: TP
5324 #: build/C/man2/perf_event_open.2:1966
5325 #, no-wrap
5326 msgid "B<PERF_MEM_LVL_REM_RAM1>"
5327 msgstr ""
5328
5329 #. type: Plain text
5330 #: build/C/man2/perf_event_open.2:1969
5331 msgid "Remote DRAM 1 hop"
5332 msgstr ""
5333
5334 #. type: TP
5335 #: build/C/man2/perf_event_open.2:1969
5336 #, no-wrap
5337 msgid "B<PERF_MEM_LVL_REM_RAM2>"
5338 msgstr ""
5339
5340 #. type: Plain text
5341 #: build/C/man2/perf_event_open.2:1972
5342 msgid "Remote DRAM 2 hops"
5343 msgstr ""
5344
5345 #. type: TP
5346 #: build/C/man2/perf_event_open.2:1972
5347 #, no-wrap
5348 msgid "B<PERF_MEM_LVL_REM_CCE1>"
5349 msgstr ""
5350
5351 #. type: Plain text
5352 #: build/C/man2/perf_event_open.2:1975
5353 msgid "Remote cache 1 hop"
5354 msgstr ""
5355
5356 #. type: TP
5357 #: build/C/man2/perf_event_open.2:1975
5358 #, no-wrap
5359 msgid "B<PERF_MEM_LVL_REM_CCE2>"
5360 msgstr ""
5361
5362 #. type: Plain text
5363 #: build/C/man2/perf_event_open.2:1978
5364 msgid "Remote cache 2 hops"
5365 msgstr ""
5366
5367 #. type: TP
5368 #: build/C/man2/perf_event_open.2:1978
5369 #, no-wrap
5370 msgid "B<PERF_MEM_LVL_IO>"
5371 msgstr ""
5372
5373 #. type: Plain text
5374 #: build/C/man2/perf_event_open.2:1981
5375 msgid "I/O memory"
5376 msgstr ""
5377
5378 #. type: TP
5379 #: build/C/man2/perf_event_open.2:1981
5380 #, no-wrap
5381 msgid "B<PERF_MEM_LVL_UNC>"
5382 msgstr ""
5383
5384 #. type: Plain text
5385 #: build/C/man2/perf_event_open.2:1984
5386 msgid "Uncached memory"
5387 msgstr ""
5388
5389 #. type: TP
5390 #: build/C/man2/perf_event_open.2:1986
5391 #, no-wrap
5392 msgid "I<mem_snoop>"
5393 msgstr ""
5394
5395 #. type: Plain text
5396 #: build/C/man2/perf_event_open.2:1989
5397 msgid "Snoop mode, a bitwise combination of:"
5398 msgstr ""
5399
5400 #. type: TP
5401 #: build/C/man2/perf_event_open.2:1992
5402 #, no-wrap
5403 msgid "B<PERF_MEM_SNOOP_NA>"
5404 msgstr ""
5405
5406 #. type: TP
5407 #: build/C/man2/perf_event_open.2:1995
5408 #, no-wrap
5409 msgid "B<PERF_MEM_SNOOP_NONE>"
5410 msgstr ""
5411
5412 #. type: Plain text
5413 #: build/C/man2/perf_event_open.2:1998
5414 msgid "No snoop"
5415 msgstr ""
5416
5417 #. type: TP
5418 #: build/C/man2/perf_event_open.2:1998
5419 #, no-wrap
5420 msgid "B<PERF_MEM_SNOOP_HIT>"
5421 msgstr ""
5422
5423 #. type: Plain text
5424 #: build/C/man2/perf_event_open.2:2001
5425 msgid "Snoop hit"
5426 msgstr ""
5427
5428 #. type: TP
5429 #: build/C/man2/perf_event_open.2:2001
5430 #, no-wrap
5431 msgid "B<PERF_MEM_SNOOP_MISS>"
5432 msgstr ""
5433
5434 #. type: Plain text
5435 #: build/C/man2/perf_event_open.2:2004
5436 msgid "Snoop miss"
5437 msgstr ""
5438
5439 #. type: TP
5440 #: build/C/man2/perf_event_open.2:2004
5441 #, no-wrap
5442 msgid "B<PERF_MEM_SNOOP_HITM>"
5443 msgstr ""
5444
5445 #. type: Plain text
5446 #: build/C/man2/perf_event_open.2:2007
5447 msgid "Snoop hit modified"
5448 msgstr ""
5449
5450 #. type: TP
5451 #: build/C/man2/perf_event_open.2:2009
5452 #, no-wrap
5453 msgid "I<mem_lock>"
5454 msgstr ""
5455
5456 #. type: Plain text
5457 #: build/C/man2/perf_event_open.2:2012
5458 msgid "Lock instruction, a bitwise combination of:"
5459 msgstr ""
5460
5461 #. type: TP
5462 #: build/C/man2/perf_event_open.2:2015
5463 #, no-wrap
5464 msgid "B<PERF_MEM_LOCK_NA>"
5465 msgstr ""
5466
5467 #. type: TP
5468 #: build/C/man2/perf_event_open.2:2018
5469 #, no-wrap
5470 msgid "B<PERF_MEM_LOCK_LOCKED>"
5471 msgstr ""
5472
5473 #. type: Plain text
5474 #: build/C/man2/perf_event_open.2:2021
5475 msgid "Locked transaction"
5476 msgstr ""
5477
5478 #. type: TP
5479 #: build/C/man2/perf_event_open.2:2023
5480 #, no-wrap
5481 msgid "I<mem_dtlb>"
5482 msgstr ""
5483
5484 #. type: Plain text
5485 #: build/C/man2/perf_event_open.2:2026
5486 msgid "TLB access hit or miss, a bitwise combination of:"
5487 msgstr ""
5488
5489 #. type: TP
5490 #: build/C/man2/perf_event_open.2:2029
5491 #, no-wrap
5492 msgid "B<PERF_MEM_TLB_NA>"
5493 msgstr ""
5494
5495 #. type: TP
5496 #: build/C/man2/perf_event_open.2:2032
5497 #, no-wrap
5498 msgid "B<PERF_MEM_TLB_HIT>"
5499 msgstr ""
5500
5501 #. type: TP
5502 #: build/C/man2/perf_event_open.2:2035
5503 #, no-wrap
5504 msgid "B<PERF_MEM_TLB_MISS>"
5505 msgstr ""
5506
5507 #. type: TP
5508 #: build/C/man2/perf_event_open.2:2038
5509 #, no-wrap
5510 msgid "B<PERF_MEM_TLB_L1>"
5511 msgstr ""
5512
5513 #. type: Plain text
5514 #: build/C/man2/perf_event_open.2:2041
5515 msgid "Level 1 TLB"
5516 msgstr ""
5517
5518 #. type: TP
5519 #: build/C/man2/perf_event_open.2:2041
5520 #, no-wrap
5521 msgid "B<PERF_MEM_TLB_L2>"
5522 msgstr ""
5523
5524 #. type: Plain text
5525 #: build/C/man2/perf_event_open.2:2044
5526 msgid "Level 2 TLB"
5527 msgstr ""
5528
5529 #. type: TP
5530 #: build/C/man2/perf_event_open.2:2044
5531 #, no-wrap
5532 msgid "B<PERF_MEM_TLB_WK>"
5533 msgstr ""
5534
5535 #. type: Plain text
5536 #: build/C/man2/perf_event_open.2:2047
5537 msgid "Hardware walker"
5538 msgstr ""
5539
5540 #. type: TP
5541 #: build/C/man2/perf_event_open.2:2047
5542 #, no-wrap
5543 msgid "B<PERF_MEM_TLB_OS>"
5544 msgstr ""
5545
5546 #. type: Plain text
5547 #: build/C/man2/perf_event_open.2:2050
5548 msgid "OS fault handler"
5549 msgstr ""
5550
5551 #. type: TP
5552 #: build/C/man2/perf_event_open.2:2053
5553 #, no-wrap
5554 msgid "I<transaction>"
5555 msgstr ""
5556
5557 #. type: Plain text
5558 #: build/C/man2/perf_event_open.2:2059
5559 msgid ""
5560 "If the B<PERF_SAMPLE_TRANSACTION> flag is set, then a 64-bit field is "
5561 "recorded describing the sources of any transactional memory aborts."
5562 msgstr ""
5563
5564 #. type: Plain text
5565 #: build/C/man2/perf_event_open.2:2061
5566 msgid "The field is a bitwise combination of the following values:"
5567 msgstr ""
5568
5569 #. type: TP
5570 #: build/C/man2/perf_event_open.2:2062
5571 #, no-wrap
5572 msgid "B<PERF_TXN_ELISION>"
5573 msgstr ""
5574
5575 #. type: Plain text
5576 #: build/C/man2/perf_event_open.2:2065
5577 msgid "Abort from an elision type transaction (Intel-CPU-specific)."
5578 msgstr ""
5579
5580 #. type: TP
5581 #: build/C/man2/perf_event_open.2:2065
5582 #, no-wrap
5583 msgid "B<PERF_TXN_TRANSACTION>"
5584 msgstr ""
5585
5586 #. type: Plain text
5587 #: build/C/man2/perf_event_open.2:2068
5588 msgid "Abort from a generic transaction."
5589 msgstr ""
5590
5591 #. type: TP
5592 #: build/C/man2/perf_event_open.2:2068
5593 #, no-wrap
5594 msgid "B<PERF_TXN_SYNC>"
5595 msgstr ""
5596
5597 #. type: Plain text
5598 #: build/C/man2/perf_event_open.2:2071
5599 msgid "Synchronous abort (related to the reported instruction)."
5600 msgstr ""
5601
5602 #. type: TP
5603 #: build/C/man2/perf_event_open.2:2071
5604 #, no-wrap
5605 msgid "B<PERF_TXN_ASYNC>"
5606 msgstr ""
5607
5608 #. type: Plain text
5609 #: build/C/man2/perf_event_open.2:2074
5610 msgid "Asynchronous abort (not related to the reported instruction)."
5611 msgstr ""
5612
5613 #. type: TP
5614 #: build/C/man2/perf_event_open.2:2074
5615 #, no-wrap
5616 msgid "B<PERF_TXN_RETRY>"
5617 msgstr ""
5618
5619 #. type: Plain text
5620 #: build/C/man2/perf_event_open.2:2077
5621 msgid "Retryable abort (retrying the transaction may have succeeded)."
5622 msgstr ""
5623
5624 #. type: TP
5625 #: build/C/man2/perf_event_open.2:2077
5626 #, no-wrap
5627 msgid "B<PERF_TXN_CONFLICT>"
5628 msgstr ""
5629
5630 #. type: Plain text
5631 #: build/C/man2/perf_event_open.2:2080
5632 msgid "Abort due to memory conflicts with other threads."
5633 msgstr ""
5634
5635 #. type: TP
5636 #: build/C/man2/perf_event_open.2:2080
5637 #, no-wrap
5638 msgid "B<PERF_TXN_CAPACITY_WRITE>"
5639 msgstr ""
5640
5641 #. type: Plain text
5642 #: build/C/man2/perf_event_open.2:2083
5643 msgid "Abort due to write capacity overflow."
5644 msgstr ""
5645
5646 #. type: TP
5647 #: build/C/man2/perf_event_open.2:2083
5648 #, no-wrap
5649 msgid "B<PERF_TXN_CAPACITY_READ>"
5650 msgstr ""
5651
5652 #. type: Plain text
5653 #: build/C/man2/perf_event_open.2:2086
5654 msgid "Abort due to read capacity overflow."
5655 msgstr ""
5656
5657 #. type: Plain text
5658 #: build/C/man2/perf_event_open.2:2093
5659 msgid ""
5660 "In addition, a user-specified abort code can be obtained from the high 32 "
5661 "bits of the field by shifting right by B<PERF_TXN_ABORT_SHIFT> and masking "
5662 "with B<PERF_TXN_ABORT_MASK>."
5663 msgstr ""
5664
5665 #. type: SS
5666 #: build/C/man2/perf_event_open.2:2095
5667 #, no-wrap
5668 msgid "Signal overflow"
5669 msgstr ""
5670
5671 #. type: Plain text
5672 #: build/C/man2/perf_event_open.2:2104
5673 msgid ""
5674 "Events can be set to deliver a signal when a threshold is crossed.  The "
5675 "signal handler is set up using the B<poll>(2), B<select>(2), B<epoll>(2)  "
5676 "and B<fcntl>(2), system calls."
5677 msgstr ""
5678
5679 #. type: Plain text
5680 #: build/C/man2/perf_event_open.2:2108
5681 msgid ""
5682 "To generate signals, sampling must be enabled (I<sample_period> must have a "
5683 "nonzero value)."
5684 msgstr ""
5685
5686 #. type: Plain text
5687 #: build/C/man2/perf_event_open.2:2110
5688 msgid "There are two ways to generate signals."
5689 msgstr ""
5690
5691 #. type: Plain text
5692 #: build/C/man2/perf_event_open.2:2120
5693 msgid ""
5694 "The first is to set a I<wakeup_events> or I<wakeup_watermark> value that "
5695 "will generate a signal if a certain number of samples or bytes have been "
5696 "written to the mmap ring buffer.  In this case, a signal of type B<POLL_IN> "
5697 "is sent."
5698 msgstr ""
5699
5700 #. type: Plain text
5701 #: build/C/man2/perf_event_open.2:2132
5702 msgid ""
5703 "The other way is by use of the B<PERF_EVENT_IOC_REFRESH> ioctl.  This ioctl "
5704 "adds to a counter that decrements each time the event overflows.  When "
5705 "nonzero, a B<POLL_IN> signal is sent on overflow, but once the value reaches "
5706 "0, a signal is sent of type B<POLL_HUP> and the underlying event is "
5707 "disabled."
5708 msgstr ""
5709
5710 #.  FIXME(Vince) : Find out when this was introduced
5711 #. type: Plain text
5712 #: build/C/man2/perf_event_open.2:2138
5713 msgid ""
5714 "Note: on newer kernels (definitely noticed with 3.2)  a signal is provided "
5715 "for every overflow, even if I<wakeup_events> is not set."
5716 msgstr ""
5717
5718 #. type: SS
5719 #: build/C/man2/perf_event_open.2:2138
5720 #, no-wrap
5721 msgid "rdpmc instruction"
5722 msgstr ""
5723
5724 #. type: Plain text
5725 #: build/C/man2/perf_event_open.2:2145
5726 msgid ""
5727 "Starting with Linux 3.4 on x86, you can use the I<rdpmc> instruction to get "
5728 "low-latency reads without having to enter the kernel.  Note that using "
5729 "I<rdpmc> is not necessarily faster than other methods for reading event "
5730 "values."
5731 msgstr ""
5732
5733 #. type: Plain text
5734 #: build/C/man2/perf_event_open.2:2150
5735 msgid ""
5736 "Support for this can be detected with the I<cap_usr_rdpmc> field in the mmap "
5737 "page; documentation on how to calculate event values can be found in that "
5738 "section."
5739 msgstr ""
5740
5741 #. type: SS
5742 #: build/C/man2/perf_event_open.2:2150
5743 #, no-wrap
5744 msgid "perf_event ioctl calls"
5745 msgstr ""
5746
5747 #. type: Plain text
5748 #: build/C/man2/perf_event_open.2:2155
5749 msgid "Various ioctls act on B<perf_event_open>()  file descriptors:"
5750 msgstr ""
5751
5752 #. type: TP
5753 #: build/C/man2/perf_event_open.2:2155
5754 #, no-wrap
5755 msgid "B<PERF_EVENT_IOC_ENABLE>"
5756 msgstr ""
5757
5758 #. type: Plain text
5759 #: build/C/man2/perf_event_open.2:2159
5760 msgid ""
5761 "This enables the individual event or event group specified by the file "
5762 "descriptor argument."
5763 msgstr ""
5764
5765 #. type: Plain text
5766 #: build/C/man2/perf_event_open.2:2165
5767 msgid ""
5768 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5769 "events in a group are enabled, even if the event specified is not the group "
5770 "leader (but see BUGS)."
5771 msgstr ""
5772
5773 #. type: TP
5774 #: build/C/man2/perf_event_open.2:2165
5775 #, no-wrap
5776 msgid "B<PERF_EVENT_IOC_DISABLE>"
5777 msgstr ""
5778
5779 #. type: Plain text
5780 #: build/C/man2/perf_event_open.2:2169
5781 msgid ""
5782 "This disables the individual counter or event group specified by the file "
5783 "descriptor argument."
5784 msgstr ""
5785
5786 #. type: Plain text
5787 #: build/C/man2/perf_event_open.2:2176
5788 msgid ""
5789 "Enabling or disabling the leader of a group enables or disables the entire "
5790 "group; that is, while the group leader is disabled, none of the counters in "
5791 "the group will count.  Enabling or disabling a member of a group other than "
5792 "the leader affects only that counter; disabling a non-leader stops that "
5793 "counter from counting but doesn't affect any other counter."
5794 msgstr ""
5795
5796 #. type: Plain text
5797 #: build/C/man2/perf_event_open.2:2182
5798 msgid ""
5799 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5800 "events in a group are disabled, even if the event specified is not the group "
5801 "leader (but see BUGS)."
5802 msgstr ""
5803
5804 #. type: TP
5805 #: build/C/man2/perf_event_open.2:2182
5806 #, no-wrap
5807 msgid "B<PERF_EVENT_IOC_REFRESH>"
5808 msgstr ""
5809
5810 #. type: Plain text
5811 #: build/C/man2/perf_event_open.2:2196
5812 msgid ""
5813 "Non-inherited overflow counters can use this to enable a counter for a "
5814 "number of overflows specified by the argument, after which it is disabled.  "
5815 "Subsequent calls of this ioctl add the argument value to the current count.  "
5816 "A signal with B<POLL_IN> set will happen on each overflow until the count "
5817 "reaches 0; when that happens a signal with POLL_HUP set is sent and the "
5818 "event is disabled.  Using an argument of 0 is considered undefined behavior."
5819 msgstr ""
5820
5821 #. type: TP
5822 #: build/C/man2/perf_event_open.2:2196
5823 #, no-wrap
5824 msgid "B<PERF_EVENT_IOC_RESET>"
5825 msgstr ""
5826
5827 #. type: Plain text
5828 #: build/C/man2/perf_event_open.2:2206
5829 msgid ""
5830 "Reset the event count specified by the file descriptor argument to zero.  "
5831 "This resets only the counts; there is no way to reset the multiplexing "
5832 "I<time_enabled> or I<time_running> values."
5833 msgstr ""
5834
5835 #. type: Plain text
5836 #: build/C/man2/perf_event_open.2:2212
5837 msgid ""
5838 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5839 "events in a group are reset, even if the event specified is not the group "
5840 "leader (but see BUGS)."
5841 msgstr ""
5842
5843 #. type: TP
5844 #: build/C/man2/perf_event_open.2:2212
5845 #, no-wrap
5846 msgid "B<PERF_EVENT_IOC_PERIOD>"
5847 msgstr ""
5848
5849 #. type: Plain text
5850 #: build/C/man2/perf_event_open.2:2215
5851 msgid "This updates the overflow period for the event."
5852 msgstr ""
5853
5854 #. type: Plain text
5855 #: build/C/man2/perf_event_open.2:2220
5856 msgid ""
5857 "Since Linux 3.7 (on ARM) and Linux 3.14 (all other architectures), the new "
5858 "period takes effect immediately.  On older kernels, the new period did not "
5859 "take effect until after the next overflow."
5860 msgstr ""
5861
5862 #. type: Plain text
5863 #: build/C/man2/perf_event_open.2:2223
5864 msgid ""
5865 "The argument is a pointer to a 64-bit value containing the desired new "
5866 "period."
5867 msgstr ""
5868
5869 #. type: Plain text
5870 #: build/C/man2/perf_event_open.2:2226
5871 msgid "Prior to Linux 2.6.36 this ioctl always failed due to a bug in the kernel."
5872 msgstr ""
5873
5874 #. type: TP
5875 #: build/C/man2/perf_event_open.2:2227
5876 #, no-wrap
5877 msgid "B<PERF_EVENT_IOC_SET_OUTPUT>"
5878 msgstr ""
5879
5880 #. type: Plain text
5881 #: build/C/man2/perf_event_open.2:2232
5882 msgid ""
5883 "This tells the kernel to report event notifications to the specified file "
5884 "descriptor rather than the default one.  The file descriptors must all be on "
5885 "the same CPU."
5886 msgstr ""
5887
5888 #. type: Plain text
5889 #: build/C/man2/perf_event_open.2:2235
5890 msgid ""
5891 "The argument specifies the desired file descriptor, or -1 if output should "
5892 "be ignored."
5893 msgstr ""
5894
5895 #. type: TP
5896 #: build/C/man2/perf_event_open.2:2235
5897 #, no-wrap
5898 msgid "B<PERF_EVENT_IOC_SET_FILTER> (since Linux 2.6.33)"
5899 msgstr ""
5900
5901 #. type: Plain text
5902 #: build/C/man2/perf_event_open.2:2238
5903 msgid "This adds an ftrace filter to this event."
5904 msgstr ""
5905
5906 #. type: Plain text
5907 #: build/C/man2/perf_event_open.2:2240
5908 msgid "The argument is a pointer to the desired ftrace filter."
5909 msgstr ""
5910
5911 #. type: TP
5912 #: build/C/man2/perf_event_open.2:2240
5913 #, no-wrap
5914 msgid "B<PERF_EVENT_IOC_ID> (since Linux 3.12)"
5915 msgstr ""
5916
5917 #. type: Plain text
5918 #: build/C/man2/perf_event_open.2:2243
5919 msgid "This returns the event ID value for the given event file descriptor."
5920 msgstr ""
5921
5922 #. type: Plain text
5923 #: build/C/man2/perf_event_open.2:2246
5924 msgid "The argument is a pointer to a 64-bit unsigned integer to hold the result."
5925 msgstr ""
5926
5927 #. type: SS
5928 #: build/C/man2/perf_event_open.2:2246
5929 #, no-wrap
5930 msgid "Using prctl"
5931 msgstr ""
5932
5933 #. type: Plain text
5934 #: build/C/man2/perf_event_open.2:2259
5935 msgid ""
5936 "A process can enable or disable all the event groups that are attached to it "
5937 "using the B<prctl>(2)  B<PR_TASK_PERF_EVENTS_ENABLE> and "
5938 "B<PR_TASK_PERF_EVENTS_DISABLE> operations.  This applies to all counters on "
5939 "the calling process, whether created by this process or by another, and does "
5940 "not affect any counters that this process has created on other processes.  "
5941 "It enables or disables only the group leaders, not any other members in the "
5942 "groups."
5943 msgstr ""
5944
5945 #. type: SS
5946 #: build/C/man2/perf_event_open.2:2259
5947 #, no-wrap
5948 msgid "perf_event related configuration files"
5949 msgstr ""
5950
5951 #. type: Plain text
5952 #: build/C/man2/perf_event_open.2:2262
5953 msgid "Files in I</proc/sys/kernel/>"
5954 msgstr ""
5955
5956 #. type: TP
5957 #: build/C/man2/perf_event_open.2:2263
5958 #, no-wrap
5959 msgid "I</proc/sys/kernel/perf_event_paranoid>"
5960 msgstr ""
5961
5962 #. type: Plain text
5963 #: build/C/man2/perf_event_open.2:2269
5964 msgid ""
5965 "The I<perf_event_paranoid> file can be set to restrict access to the "
5966 "performance counters."
5967 msgstr ""
5968
5969 #. type: IP
5970 #: build/C/man2/perf_event_open.2:2270
5971 #, no-wrap
5972 msgid "2"
5973 msgstr ""
5974
5975 #. type: Plain text
5976 #: build/C/man2/perf_event_open.2:2272
5977 msgid "only allow user-space measurements."
5978 msgstr ""
5979
5980 #. type: IP
5981 #: build/C/man2/perf_event_open.2:2272
5982 #, no-wrap
5983 msgid "1"
5984 msgstr ""
5985
5986 #. type: Plain text
5987 #: build/C/man2/perf_event_open.2:2274
5988 msgid "allow both kernel and user measurements (default)."
5989 msgstr ""
5990
5991 #. type: IP
5992 #: build/C/man2/perf_event_open.2:2274
5993 #, no-wrap
5994 msgid "0"
5995 msgstr ""
5996
5997 #. type: Plain text
5998 #: build/C/man2/perf_event_open.2:2276
5999 msgid "allow access to CPU-specific data but not raw tracepoint samples."
6000 msgstr ""
6001
6002 #. type: IP
6003 #: build/C/man2/perf_event_open.2:2276
6004 #, no-wrap
6005 msgid "-1"
6006 msgstr ""
6007
6008 #. type: Plain text
6009 #: build/C/man2/perf_event_open.2:2278
6010 msgid "no restrictions."
6011 msgstr ""
6012
6013 #. type: Plain text
6014 #: build/C/man2/perf_event_open.2:2284
6015 msgid ""
6016 "The existence of the I<perf_event_paranoid> file is the official method for "
6017 "determining if a kernel supports B<perf_event_open>()."
6018 msgstr ""
6019
6020 #. type: TP
6021 #: build/C/man2/perf_event_open.2:2284
6022 #, no-wrap
6023 msgid "I</proc/sys/kernel/perf_event_max_sample_rate>"
6024 msgstr ""
6025
6026 #. type: Plain text
6027 #: build/C/man2/perf_event_open.2:2293
6028 msgid ""
6029 "This sets the maximum sample rate.  Setting this too high can allow users to "
6030 "sample at a rate that impacts overall machine performance and potentially "
6031 "lock up the machine.  The default value is 100000 (samples per second)."
6032 msgstr ""
6033
6034 #. type: TP
6035 #: build/C/man2/perf_event_open.2:2293
6036 #, no-wrap
6037 msgid "I</proc/sys/kernel/perf_event_mlock_kb>"
6038 msgstr ""
6039
6040 #. type: Plain text
6041 #: build/C/man2/perf_event_open.2:2299
6042 msgid ""
6043 "Maximum number of pages an unprivileged user can B<mlock>(2).  The default "
6044 "is 516 (kB)."
6045 msgstr ""
6046
6047 #. type: Plain text
6048 #: build/C/man2/perf_event_open.2:2303
6049 msgid "Files in I</sys/bus/event_source/devices/>"
6050 msgstr ""
6051
6052 #. type: Plain text
6053 #: build/C/man2/perf_event_open.2:2309
6054 msgid ""
6055 "Since Linux 2.6.34, the kernel supports having multiple PMUs available for "
6056 "monitoring.  Information on how to program these PMUs can be found under "
6057 "I</sys/bus/event_source/devices/>.  Each subdirectory corresponds to a "
6058 "different PMU."
6059 msgstr ""
6060
6061 #. type: TP
6062 #: build/C/man2/perf_event_open.2:2309
6063 #, no-wrap
6064 msgid "I</sys/bus/event_source/devices/*/type> (since Linux 2.6.38)"
6065 msgstr ""
6066
6067 #. type: Plain text
6068 #: build/C/man2/perf_event_open.2:2316
6069 msgid ""
6070 "This contains an integer that can be used in the I<type> field of "
6071 "I<perf_event_attr> to indicate that you wish to use this PMU."
6072 msgstr ""
6073
6074 #. type: TP
6075 #: build/C/man2/perf_event_open.2:2316
6076 #, no-wrap
6077 msgid "I</sys/bus/event_source/devices/*/rdpmc> (since Linux 3.4)"
6078 msgstr ""
6079
6080 #. type: Plain text
6081 #: build/C/man2/perf_event_open.2:2321
6082 msgid ""
6083 "If this file is 1, then direct user-space access to the performance counter "
6084 "registers is allowed via the rdpmc instruction.  This can be disabled by "
6085 "echoing 0 to the file."
6086 msgstr ""
6087
6088 #. type: TP
6089 #: build/C/man2/perf_event_open.2:2321
6090 #, no-wrap
6091 msgid "I</sys/bus/event_source/devices/*/format/> (since Linux 3.4)"
6092 msgstr ""
6093
6094 #. type: Plain text
6095 #: build/C/man2/perf_event_open.2:2329
6096 msgid ""
6097 "This subdirectory contains information on the architecture-specific "
6098 "subfields available for programming the various I<config> fields in the "
6099 "I<perf_event_attr> struct."
6100 msgstr ""
6101
6102 #. type: Plain text
6103 #: build/C/man2/perf_event_open.2:2340
6104 msgid ""
6105 "The content of each file is the name of the config field, followed by a "
6106 "colon, followed by a series of integer bit ranges separated by commas.  For "
6107 "example, the file I<event> may contain the value I<config1:1,6-10,44> which "
6108 "indicates that event is an attribute that occupies bits 1,6-10, and 44 of "
6109 "I<perf_event_attr::config1>."
6110 msgstr ""
6111
6112 #. type: TP
6113 #: build/C/man2/perf_event_open.2:2340
6114 #, no-wrap
6115 msgid "I</sys/bus/event_source/devices/*/events/> (since Linux 3.4)"
6116 msgstr ""
6117
6118 #. type: Plain text
6119 #: build/C/man2/perf_event_open.2:2349
6120 msgid ""
6121 "This subdirectory contains files with predefined events.  The contents are "
6122 "strings describing the event settings expressed in terms of the fields found "
6123 "in the previously mentioned I<./format/> directory.  These are not "
6124 "necessarily complete lists of all events supported by a PMU, but usually a "
6125 "subset of events deemed useful or interesting."
6126 msgstr ""
6127
6128 #. type: Plain text
6129 #: build/C/man2/perf_event_open.2:2357
6130 msgid ""
6131 "The content of each file is a list of attribute names separated by commas.  "
6132 "Each entry has an optional value (either hex or decimal).  If no value is "
6133 "specified, then it is assumed to be a single-bit field with a value of 1.  "
6134 "An example entry may look like this: I<event=0x2,inv,ldlat=3>."
6135 msgstr ""
6136
6137 #. type: TP
6138 #: build/C/man2/perf_event_open.2:2357
6139 #, no-wrap
6140 msgid "I</sys/bus/event_source/devices/*/uevent>"
6141 msgstr ""
6142
6143 #. type: Plain text
6144 #: build/C/man2/perf_event_open.2:2361
6145 msgid ""
6146 "This file is the standard kernel device interface for injecting hotplug "
6147 "events."
6148 msgstr ""
6149
6150 #. type: TP
6151 #: build/C/man2/perf_event_open.2:2361
6152 #, no-wrap
6153 msgid "I</sys/bus/event_source/devices/*/cpumask> (since Linux 3.7)"
6154 msgstr ""
6155
6156 #. type: Plain text
6157 #: build/C/man2/perf_event_open.2:2370
6158 msgid ""
6159 "The I<cpumask> file contains a comma-separated list of integers that "
6160 "indicate a representative CPU number for each socket (package)  on the "
6161 "motherboard.  This is needed when setting up uncore or northbridge events, "
6162 "as those PMUs present socket-wide events."
6163 msgstr ""
6164
6165 #. type: Plain text
6166 #: build/C/man2/perf_event_open.2:2377
6167 msgid ""
6168 "B<perf_event_open>()  returns the new file descriptor, or -1 if an error "
6169 "occurred (in which case, I<errno> is set appropriately)."
6170 msgstr ""
6171
6172 #. type: Plain text
6173 #: build/C/man2/perf_event_open.2:2382
6174 msgid ""
6175 "The errors returned by B<perf_event_open>()  can be inconsistent, and may "
6176 "vary across processor architectures and performance monitoring units."
6177 msgstr ""
6178
6179 #. type: TP
6180 #: build/C/man2/perf_event_open.2:2382
6181 #, no-wrap
6182 msgid "B<E2BIG>"
6183 msgstr ""
6184
6185 #. type: Plain text
6186 #: build/C/man2/perf_event_open.2:2399
6187 msgid ""
6188 "Returned if the I<perf_event_attr> I<size> value is too small (smaller than "
6189 "B<PERF_ATTR_SIZE_VER0>), too big (larger than the page size), or larger than "
6190 "the kernel supports and the extra bytes are not zero.  When B<E2BIG> is "
6191 "returned, the I<perf_event_attr> I<size> field is overwritten by the kernel "
6192 "to be the size of the structure it was expecting."
6193 msgstr ""
6194
6195 #. type: Plain text
6196 #: build/C/man2/perf_event_open.2:2413
6197 msgid ""
6198 "Returned when the requested event requires B<CAP_SYS_ADMIN> permissions (or "
6199 "a more permissive perf_event paranoid setting).  Some common cases where an "
6200 "unprivileged process may encounter this error: attaching to a process owned "
6201 "by a different user; monitoring all processes on a given CPU (i.e., "
6202 "specifying the I<pid> argument as -1); and not setting I<exclude_kernel> "
6203 "when the paranoid setting requires it."
6204 msgstr ""
6205
6206 #. type: TP
6207 #: 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
6208 #, no-wrap
6209 msgid "B<EBADF>"
6210 msgstr ""
6211
6212 #. type: Plain text
6213 #: build/C/man2/perf_event_open.2:2423
6214 msgid ""
6215 "Returned if the I<group_fd> file descriptor is not valid, or, if "
6216 "B<PERF_FLAG_PID_CGROUP> is set, the cgroup file descriptor in I<pid> is not "
6217 "valid."
6218 msgstr ""
6219
6220 #. type: Plain text
6221 #: build/C/man2/perf_event_open.2:2428
6222 msgid "Returned if the I<attr> pointer points at an invalid memory address."
6223 msgstr ""
6224
6225 #. type: Plain text
6226 #: build/C/man2/perf_event_open.2:2454
6227 msgid ""
6228 "Returned if the specified event is invalid.  There are many possible reasons "
6229 "for this.  A not-exhaustive list: I<sample_freq> is higher than the maximum "
6230 "setting; the I<cpu> to monitor does not exist; I<read_format> is out of "
6231 "range; I<sample_type> is out of range; the I<flags> value is out of range; "
6232 "I<exclusive> or I<pinned> set and the event is not a group leader; the event "
6233 "I<config> values are out of range or set reserved bits; the generic event "
6234 "selected is not supported; or there is not enough room to add the selected "
6235 "event."
6236 msgstr ""
6237
6238 #. type: TP
6239 #: build/C/man2/perf_event_open.2:2454
6240 #, no-wrap
6241 msgid "B<EMFILE>"
6242 msgstr ""
6243
6244 #. type: Plain text
6245 #: build/C/man2/perf_event_open.2:2460
6246 msgid ""
6247 "Each opened event uses one file descriptor.  If a large number of events are "
6248 "opened the per-user file descriptor limit (often 1024) will be hit and no "
6249 "more events can be created."
6250 msgstr ""
6251
6252 #. type: Plain text
6253 #: build/C/man2/perf_event_open.2:2464
6254 msgid "Returned when the event involves a feature not supported by the current CPU."
6255 msgstr ""
6256
6257 #. type: TP
6258 #: build/C/man2/perf_event_open.2:2464 build/C/man2/quotactl.2:440
6259 #, no-wrap
6260 msgid "B<ENOENT>"
6261 msgstr ""
6262
6263 #. type: Plain text
6264 #: build/C/man2/perf_event_open.2:2471
6265 msgid ""
6266 "Returned if the I<type> setting is not valid.  This error is also returned "
6267 "for some unsupported generic events."
6268 msgstr ""
6269
6270 #. type: TP
6271 #: build/C/man2/perf_event_open.2:2471
6272 #, no-wrap
6273 msgid "B<ENOSPC>"
6274 msgstr ""
6275
6276 #. type: Plain text
6277 #: build/C/man2/perf_event_open.2:2481
6278 msgid ""
6279 "Prior to Linux 3.3, if there was not enough room for the event, B<ENOSPC> "
6280 "was returned.  In Linux 3.3, this was changed to B<EINVAL>.  B<ENOSPC> is "
6281 "still returned if you try to add more breakpoint events than supported by "
6282 "the hardware."
6283 msgstr ""
6284
6285 #. type: Plain text
6286 #: build/C/man2/perf_event_open.2:2488
6287 msgid ""
6288 "Returned if B<PERF_SAMPLE_STACK_USER> is set in I<sample_type> and it is not "
6289 "supported by hardware."
6290 msgstr ""
6291
6292 #. type: Plain text
6293 #: build/C/man2/perf_event_open.2:2495
6294 msgid ""
6295 "Returned if an event requiring a specific hardware feature is requested but "
6296 "there is no hardware support.  This includes requesting low-skid events if "
6297 "not supported, branch tracing if it is not available, sampling if no PMU "
6298 "interrupt is available, and branch stacks for software events."
6299 msgstr ""
6300
6301 #. type: Plain text
6302 #: build/C/man2/perf_event_open.2:2500
6303 msgid ""
6304 "Returned on many (but not all) architectures when an unsupported "
6305 "I<exclude_hv>, I<exclude_idle>, I<exclude_user>, or I<exclude_kernel> "
6306 "setting is specified."
6307 msgstr ""
6308
6309 #. type: Plain text
6310 #: build/C/man2/perf_event_open.2:2508
6311 msgid ""
6312 "It can also happen, as with B<EACCES>, when the requested event requires "
6313 "B<CAP_SYS_ADMIN> permissions (or a more permissive perf_event paranoid "
6314 "setting).  This includes setting a breakpoint on a kernel address, and "
6315 "(since Linux 3.13) setting a kernel function-trace tracepoint."
6316 msgstr ""
6317
6318 #. type: Plain text
6319 #: build/C/man2/perf_event_open.2:2511
6320 msgid "Returned if attempting to attach to a process that does not exist."
6321 msgstr ""
6322
6323 #. type: SH
6324 #: build/C/man2/perf_event_open.2:2511
6325 #, no-wrap
6326 msgid "VERSION"
6327 msgstr ""
6328
6329 #. type: Plain text
6330 #: build/C/man2/perf_event_open.2:2516
6331 msgid ""
6332 "B<perf_event_open>()  was introduced in Linux 2.6.31 but was called "
6333 "B<perf_counter_open>().  It was renamed in Linux 2.6.32."
6334 msgstr ""
6335
6336 #. type: Plain text
6337 #: build/C/man2/perf_event_open.2:2521
6338 msgid ""
6339 "This B<perf_event_open>()  system call Linux- specific and should not be "
6340 "used in programs intended to be portable."
6341 msgstr ""
6342
6343 #. type: Plain text
6344 #: build/C/man2/perf_event_open.2:2525
6345 msgid ""
6346 "Glibc does not provide a wrapper for this system call; call it using "
6347 "B<syscall>(2).  See the example below."
6348 msgstr ""
6349
6350 #. type: Plain text
6351 #: build/C/man2/perf_event_open.2:2531
6352 msgid ""
6353 "The official way of knowing if B<perf_event_open>()  support is enabled is "
6354 "checking for the existence of the file "
6355 "I</proc/sys/kernel/perf_event_paranoid>."
6356 msgstr ""
6357
6358 #. type: SH
6359 #: build/C/man2/perf_event_open.2:2531 build/C/man2/pivot_root.2:134 build/C/man2/ptrace.2:1963
6360 #, no-wrap
6361 msgid "BUGS"
6362 msgstr ""
6363
6364 #. type: Plain text
6365 #: build/C/man2/perf_event_open.2:2538
6366 msgid ""
6367 "The B<F_SETOWN_EX> option to B<fcntl>(2)  is needed to properly get overflow "
6368 "signals in threads.  This was introduced in Linux 2.6.32."
6369 msgstr ""
6370
6371 #. type: Plain text
6372 #: build/C/man2/perf_event_open.2:2546
6373 msgid ""
6374 "Prior to Linux 2.6.33 (at least for x86), the kernel did not check if events "
6375 "could be scheduled together until read time.  The same happens on all known "
6376 "kernels if the NMI watchdog is enabled.  This means to see if a given set of "
6377 "events works you have to B<perf_event_open>(), start, then read before you "
6378 "know for sure you can get valid measurements."
6379 msgstr ""
6380
6381 #. type: Plain text
6382 #: build/C/man2/perf_event_open.2:2550
6383 msgid ""
6384 "Prior to Linux 2.6.34, event constraints were not enforced by the kernel.  "
6385 "In that case, some events would silently return \"0\" if the kernel "
6386 "scheduled them in an improper counter slot."
6387 msgstr ""
6388
6389 #. type: Plain text
6390 #: build/C/man2/perf_event_open.2:2553
6391 msgid ""
6392 "Prior to Linux 2.6.34, there was a bug when multiplexing where the wrong "
6393 "results could be returned."
6394 msgstr ""
6395
6396 #. type: Plain text
6397 #: build/C/man2/perf_event_open.2:2556
6398 msgid ""
6399 "Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "
6400 "\"inherit\" is enabled and many threads are started."
6401 msgstr ""
6402
6403 #. type: Plain text
6404 #: build/C/man2/perf_event_open.2:2560
6405 msgid ""
6406 "Prior to Linux 2.6.35, B<PERF_FORMAT_GROUP> did not work with attached "
6407 "processes."
6408 msgstr ""
6409
6410 #. type: Plain text
6411 #: build/C/man2/perf_event_open.2:2565
6412 msgid ""
6413 "In older Linux 2.6 versions, refreshing an event group leader refreshed all "
6414 "siblings, and refreshing with a parameter of 0 enabled infinite refresh.  "
6415 "This behavior is unsupported and should not be relied on."
6416 msgstr ""
6417
6418 #. type: Plain text
6419 #: build/C/man2/perf_event_open.2:2571
6420 msgid ""
6421 "There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that "
6422 "ignores the \"watermark\" field and acts as if a wakeup_event was chosen if "
6423 "the union has a nonzero value in it."
6424 msgstr ""
6425
6426 #. type: Plain text
6427 #: build/C/man2/perf_event_open.2:2577
6428 msgid ""
6429 "From Linux 2.6.31 to Linux 3.4, the B<PERF_IOC_FLAG_GROUP> ioctl argument "
6430 "was broken and would repeatedly operate on the event specified rather than "
6431 "iterating across all sibling events in a group."
6432 msgstr ""
6433
6434 #. type: Plain text
6435 #: build/C/man2/perf_event_open.2:2588
6436 msgid ""
6437 "From Linux 3.4 to Linux 3.11, the mmap I<cap_usr_rdpmc> and I<cap_usr_time> "
6438 "bits mapped to the same location.  Code should migrate to the new "
6439 "I<cap_user_rdpmc> and I<cap_user_time> fields instead."
6440 msgstr ""
6441
6442 #. type: Plain text
6443 #: build/C/man2/perf_event_open.2:2593
6444 msgid ""
6445 "Always double-check your results! Various generalized events have had wrong "
6446 "values.  For example, retired branches measured the wrong thing on AMD "
6447 "machines until Linux 2.6.35."
6448 msgstr ""
6449
6450 #. type: SH
6451 #: build/C/man2/perf_event_open.2:2593 build/C/man2/process_vm_readv.2:311 build/C/man2/splice.2:223 build/C/man2/tee.2:130
6452 #, no-wrap
6453 msgid "EXAMPLE"
6454 msgstr ""
6455
6456 #. type: Plain text
6457 #: build/C/man2/perf_event_open.2:2597
6458 msgid ""
6459 "The following is a short example that measures the total instruction count "
6460 "of a call to B<printf>(3)."
6461 msgstr ""
6462
6463 #. type: Plain text
6464 #: build/C/man2/perf_event_open.2:2606
6465 #, no-wrap
6466 msgid ""
6467 "#include E<lt>stdlib.hE<gt>\n"
6468 "#include E<lt>stdio.hE<gt>\n"
6469 "#include E<lt>unistd.hE<gt>\n"
6470 "#include E<lt>string.hE<gt>\n"
6471 "#include E<lt>sys/ioctl.hE<gt>\n"
6472 "#include E<lt>linux/perf_event.hE<gt>\n"
6473 "#include E<lt>asm/unistd.hE<gt>\n"
6474 msgstr ""
6475
6476 #. type: Plain text
6477 #: build/C/man2/perf_event_open.2:2612
6478 #, no-wrap
6479 msgid ""
6480 "static long\n"
6481 "perf_event_open(struct perf_event_attr *hw_event, pid_t pid,\n"
6482 "                int cpu, int group_fd, unsigned long flags)\n"
6483 "{\n"
6484 "    int ret;\n"
6485 msgstr ""
6486
6487 #. type: Plain text
6488 #: build/C/man2/perf_event_open.2:2617
6489 #, no-wrap
6490 msgid ""
6491 "    ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,\n"
6492 "                   group_fd, flags);\n"
6493 "    return ret;\n"
6494 "}\n"
6495 msgstr ""
6496
6497 #. type: Plain text
6498 #: build/C/man2/perf_event_open.2:2624
6499 #, no-wrap
6500 msgid ""
6501 "int\n"
6502 "main(int argc, char **argv)\n"
6503 "{\n"
6504 "    struct perf_event_attr pe;\n"
6505 "    long long count;\n"
6506 "    int fd;\n"
6507 msgstr ""
6508
6509 #. type: Plain text
6510 #: build/C/man2/perf_event_open.2:2632
6511 #, no-wrap
6512 msgid ""
6513 "    memset(&pe, 0, sizeof(struct perf_event_attr));\n"
6514 "    pe.type = PERF_TYPE_HARDWARE;\n"
6515 "    pe.size = sizeof(struct perf_event_attr);\n"
6516 "    pe.config = PERF_COUNT_HW_INSTRUCTIONS;\n"
6517 "    pe.disabled = 1;\n"
6518 "    pe.exclude_kernel = 1;\n"
6519 "    pe.exclude_hv = 1;\n"
6520 msgstr ""
6521
6522 #. type: Plain text
6523 #: build/C/man2/perf_event_open.2:2638
6524 #, no-wrap
6525 msgid ""
6526 "    fd = perf_event_open(&pe, 0, -1, -1, 0);\n"
6527 "    if (fd == -1) {\n"
6528 "       fprintf(stderr, \"Error opening leader %llx\\en\", pe.config);\n"
6529 "       exit(EXIT_FAILURE);\n"
6530 "    }\n"
6531 msgstr ""
6532
6533 #. type: Plain text
6534 #: build/C/man2/perf_event_open.2:2641
6535 #, no-wrap
6536 msgid ""
6537 "    ioctl(fd, PERF_EVENT_IOC_RESET, 0);\n"
6538 "    ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);\n"
6539 msgstr ""
6540
6541 #. type: Plain text
6542 #: build/C/man2/perf_event_open.2:2643
6543 #, no-wrap
6544 msgid "    printf(\"Measuring instruction count for this printf\\en\");\n"
6545 msgstr ""
6546
6547 #. type: Plain text
6548 #: build/C/man2/perf_event_open.2:2646
6549 #, no-wrap
6550 msgid ""
6551 "    ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);\n"
6552 "    read(fd, &count, sizeof(long long));\n"
6553 msgstr ""
6554
6555 #. type: Plain text
6556 #: build/C/man2/perf_event_open.2:2648
6557 #, no-wrap
6558 msgid "    printf(\"Used %lld instructions\\en\", count);\n"
6559 msgstr ""
6560
6561 #. type: Plain text
6562 #: build/C/man2/perf_event_open.2:2651
6563 #, no-wrap
6564 msgid ""
6565 "    close(fd);\n"
6566 "}\n"
6567 msgstr ""
6568
6569 #. type: Plain text
6570 #: build/C/man2/perf_event_open.2:2658
6571 msgid "B<fcntl>(2), B<mmap>(2), B<open>(2), B<prctl>(2), B<read>(2)"
6572 msgstr ""
6573
6574 #. type: TH
6575 #: build/C/man2/perfmonctl.2:27
6576 #, no-wrap
6577 msgid "PERFMONCTL"
6578 msgstr ""
6579
6580 #. type: Plain text
6581 #: build/C/man2/perfmonctl.2:30
6582 msgid "perfmonctl - interface to IA-64 performance monitoring unit"
6583 msgstr ""
6584
6585 #. type: Plain text
6586 #: build/C/man2/perfmonctl.2:34
6587 #, no-wrap
6588 msgid ""
6589 "B<#include E<lt>syscall.hE<gt>>\n"
6590 "B<#include E<lt>perfmon.hE<gt>>\n"
6591 msgstr ""
6592
6593 #. type: Plain text
6594 #: build/C/man2/perfmonctl.2:36
6595 #, no-wrap
6596 msgid ""
6597 "B<long perfmonctl(int >I<fd>B<, int >I<cmd>B<, void *>I<arg>B<, int "
6598 ">I<narg>B<);>\n"
6599 msgstr ""
6600
6601 #. type: Plain text
6602 #: build/C/man2/perfmonctl.2:47
6603 msgid ""
6604 "The IA-64-specific B<perfmonctl>()  system call provides an interface to the "
6605 "PMU (performance monitoring unit).  The PMU consists of PMD (performance "
6606 "monitoring data) registers and PMC (performance monitoring control) "
6607 "registers, which gather hardware statistics."
6608 msgstr ""
6609
6610 #. type: Plain text
6611 #: build/C/man2/perfmonctl.2:57
6612 msgid ""
6613 "B<perfmonctl>()  applies the operation I<cmd> to the input arguments "
6614 "specified by I<arg>.  The number of arguments is defined by I<narg>.  The "
6615 "I<fd> argument specifies the perfmon context to operate on."
6616 msgstr ""
6617
6618 #. type: Plain text
6619 #: build/C/man2/perfmonctl.2:61
6620 msgid "Supported values for I<cmd> are:"
6621 msgstr ""
6622
6623 #. type: TP
6624 #: build/C/man2/perfmonctl.2:61
6625 #, no-wrap
6626 msgid "B<PFM_CREATE_CONTEXT>"
6627 msgstr ""
6628
6629 #. type: Plain text
6630 #: build/C/man2/perfmonctl.2:65
6631 #, no-wrap
6632 msgid ""
6633 "B<perfmonctl(int >I<fd>B<, PFM_CREATE_CONTEXT, pfarg_context_t *>I<ctxt>B<, "
6634 "1);>\n"
6635 msgstr ""
6636
6637 #. type: Plain text
6638 #: build/C/man2/perfmonctl.2:67
6639 msgid "Set up a context."
6640 msgstr ""
6641
6642 #. type: Plain text
6643 #: build/C/man2/perfmonctl.2:74
6644 msgid ""
6645 "The I<fd> parameter is ignored.  A new perfmon context is created as "
6646 "specified in I<ctxt> and its file descriptor is returned in "
6647 "I<ctxt-E<gt>ctx_fd>."
6648 msgstr ""
6649
6650 #. type: Plain text
6651 #: build/C/man2/perfmonctl.2:86
6652 msgid ""
6653 "The file descriptor can be used in subsequent calls to B<perfmonctl>()  and "
6654 "can be used to read event notifications (type I<pfm_msg_t>)  using "
6655 "B<read>(2).  The file descriptor is pollable using B<select>(2), B<poll>(2), "
6656 "and B<epoll>(7)."
6657 msgstr ""
6658
6659 #. type: Plain text
6660 #: build/C/man2/perfmonctl.2:90
6661 msgid "The context can be destroyed by calling B<close>(2)  on the file descriptor."
6662 msgstr ""
6663
6664 #. type: TP
6665 #: build/C/man2/perfmonctl.2:90
6666 #, no-wrap
6667 msgid "B<PFM_WRITE_PMCS>"
6668 msgstr ""
6669
6670 #. type: Plain text
6671 #: build/C/man2/perfmonctl.2:95
6672 #, no-wrap
6673 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMCS, pfarg_reg_t *>I<pmcs>B<, n);>\n"
6674 msgstr ""
6675
6676 #. type: Plain text
6677 #: build/C/man2/perfmonctl.2:97
6678 msgid "Set PMC registers."
6679 msgstr ""
6680
6681 #. type: TP
6682 #: build/C/man2/perfmonctl.2:97
6683 #, no-wrap
6684 msgid "B<PFM_WRITE_PMDS>"
6685 msgstr ""
6686
6687 #. type: Plain text
6688 #: build/C/man2/perfmonctl.2:101
6689 #, no-wrap
6690 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6691 msgstr ""
6692
6693 #.  pfm_write_pmds()
6694 #. type: Plain text
6695 #: build/C/man2/perfmonctl.2:104
6696 msgid "Set PMD registers."
6697 msgstr ""
6698
6699 #. type: TP
6700 #: build/C/man2/perfmonctl.2:104
6701 #, no-wrap
6702 msgid "B<PFM_READ_PMDS>"
6703 msgstr ""
6704
6705 #. type: Plain text
6706 #: build/C/man2/perfmonctl.2:109
6707 #, no-wrap
6708 msgid "B<perfmonctl(int >I<fd>B<, PFM_READ_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6709 msgstr ""
6710
6711 #. type: Plain text
6712 #: build/C/man2/perfmonctl.2:111
6713 msgid "Read PMD registers."
6714 msgstr ""
6715
6716 #. type: TP
6717 #: build/C/man2/perfmonctl.2:111
6718 #, no-wrap
6719 msgid "B<PFM_START>"
6720 msgstr ""
6721
6722 #.  .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
6723 #. type: Plain text
6724 #: build/C/man2/perfmonctl.2:117
6725 #, no-wrap
6726 msgid "B<perfmonctl(int >I<fd>B<, PFM_START, NULL, 0);>\n"
6727 msgstr ""
6728
6729 #. type: Plain text
6730 #: build/C/man2/perfmonctl.2:119
6731 msgid "Start monitoring."
6732 msgstr ""
6733
6734 #. type: TP
6735 #: build/C/man2/perfmonctl.2:119
6736 #, no-wrap
6737 msgid "B<PFM_STOP>"
6738 msgstr ""
6739
6740 #. type: Plain text
6741 #: build/C/man2/perfmonctl.2:124
6742 #, no-wrap
6743 msgid "B<perfmonctl(int >I<fd>B<, PFM_STOP, NULL, 0);>\n"
6744 msgstr ""
6745
6746 #. type: Plain text
6747 #: build/C/man2/perfmonctl.2:126
6748 msgid "Stop monitoring."
6749 msgstr ""
6750
6751 #. type: TP
6752 #: build/C/man2/perfmonctl.2:126
6753 #, no-wrap
6754 msgid "B<PFM_LOAD_CONTEXT>"
6755 msgstr ""
6756
6757 #. type: Plain text
6758 #: build/C/man2/perfmonctl.2:131
6759 #, no-wrap
6760 msgid ""
6761 "B<perfmonctl(int >I<fd>B<, PFM_LOAD_CONTEXT, pfarg_load_t *>I<largs>B<, "
6762 "1);>\n"
6763 msgstr ""
6764
6765 #. type: Plain text
6766 #: build/C/man2/perfmonctl.2:133
6767 msgid "Attach the context to a thread."
6768 msgstr ""
6769
6770 #. type: TP
6771 #: build/C/man2/perfmonctl.2:133
6772 #, no-wrap
6773 msgid "B<PFM_UNLOAD_CONTEXT>"
6774 msgstr ""
6775
6776 #. type: Plain text
6777 #: build/C/man2/perfmonctl.2:138
6778 #, no-wrap
6779 msgid "B<perfmonctl(int >I<fd>B<, PFM_UNLOAD_CONTEXT, NULL, 0);>\n"
6780 msgstr ""
6781
6782 #. type: Plain text
6783 #: build/C/man2/perfmonctl.2:140
6784 msgid "Detach the context from a thread."
6785 msgstr ""
6786
6787 #. type: TP
6788 #: build/C/man2/perfmonctl.2:140
6789 #, no-wrap
6790 msgid "B<PFM_RESTART>"
6791 msgstr ""
6792
6793 #. type: Plain text
6794 #: build/C/man2/perfmonctl.2:145
6795 #, no-wrap
6796 msgid "B<perfmonctl(int >I<fd>B<, PFM_RESTART, NULL, 0);>\n"
6797 msgstr ""
6798
6799 #. type: Plain text
6800 #: build/C/man2/perfmonctl.2:147
6801 msgid "Restart monitoring after receiving an overflow notification."
6802 msgstr ""
6803
6804 #. type: TP
6805 #: build/C/man2/perfmonctl.2:147
6806 #, no-wrap
6807 msgid "B<PFM_GET_FEATURES>"
6808 msgstr ""
6809
6810 #. type: Plain text
6811 #: build/C/man2/perfmonctl.2:152
6812 #, no-wrap
6813 msgid ""
6814 "B<perfmonctl(int >I<fd>B<, PFM_GET_FEARURES, pfarg_features_t *>I<arg>B<, "
6815 "1);>\n"
6816 msgstr ""
6817
6818 #. type: TP
6819 #: build/C/man2/perfmonctl.2:153
6820 #, no-wrap
6821 msgid "B<PFM_DEBUG>"
6822 msgstr ""
6823
6824 #. type: Plain text
6825 #: build/C/man2/perfmonctl.2:158
6826 #, no-wrap
6827 msgid "B<perfmonctl(int >I<fd>B<, PFM_DEBUG, >I<val>B<, 0);>\n"
6828 msgstr ""
6829
6830 #. type: Plain text
6831 #: build/C/man2/perfmonctl.2:162
6832 msgid "If I<val> is nonzero, enable debugging mode, otherwise disable."
6833 msgstr ""
6834
6835 #. type: TP
6836 #: build/C/man2/perfmonctl.2:162
6837 #, no-wrap
6838 msgid "B<PFM_GET_PMC_RESET_VAL>"
6839 msgstr ""
6840
6841 #. type: Plain text
6842 #: build/C/man2/perfmonctl.2:167
6843 #, no-wrap
6844 msgid ""
6845 "B<perfmonctl(int >I<fd>B<, PFM_GET_PMC_RESET_VAL, pfarg_reg_t * >I<req>B<, "
6846 "n);>\n"
6847 msgstr ""
6848
6849 #
6850 #
6851 #.  .TP
6852 #.  .B PFM_CREATE_EVTSETS
6853 #
6854 #.  create or modify event sets
6855 #.  .nf
6856 #.  .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
6857 #.  .fi
6858 #.  .TP
6859 #.  .B PFM_DELETE_EVTSETS
6860 #.  delete event sets
6861 #.  .nf
6862 #.  .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
6863 #.  .fi
6864 #.  .TP
6865 #.  .B PFM_GETINFO_EVTSETS
6866 #.  get information about event sets
6867 #.  .nf
6868 #.  .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
6869 #.  .fi
6870 #. type: Plain text
6871 #: build/C/man2/perfmonctl.2:190
6872 msgid "Reset PMC registers to default values."
6873 msgstr ""
6874
6875 #. type: Plain text
6876 #: build/C/man2/perfmonctl.2:196
6877 msgid ""
6878 "B<perfmonctl>()  returns zero when the operation is successful.  On error, "
6879 "-1 is returned and I<errno> is set to indicate the cause of the error."
6880 msgstr ""
6881
6882 #. type: Plain text
6883 #: build/C/man2/perfmonctl.2:199
6884 msgid "B<perfmonctl>()  is available since Linux 2.4."
6885 msgstr ""
6886
6887 #. type: Plain text
6888 #: build/C/man2/perfmonctl.2:202
6889 msgid ""
6890 "B<perfmonctl>()  is Linux-specific and is available only on the IA-64 "
6891 "architecture."
6892 msgstr ""
6893
6894 #. type: Plain text
6895 #: build/C/man2/perfmonctl.2:207
6896 msgid "B<gprof>(1)"
6897 msgstr ""
6898
6899 #. type: Plain text
6900 #: build/C/man2/perfmonctl.2:209
6901 msgid "The perfmon2 interface specification"
6902 msgstr ""
6903
6904 #. type: TH
6905 #: build/C/man2/personality.2:32
6906 #, no-wrap
6907 msgid "PERSONALITY"
6908 msgstr ""
6909
6910 #. type: TH
6911 #: build/C/man2/personality.2:32
6912 #, no-wrap
6913 msgid "2014-04-15"
6914 msgstr ""
6915
6916 #. type: Plain text
6917 #: build/C/man2/personality.2:35
6918 msgid "personality - set the process execution domain"
6919 msgstr ""
6920
6921 #. type: Plain text
6922 #: build/C/man2/personality.2:37
6923 msgid "B<#include E<lt>sys/personality.hE<gt>>"
6924 msgstr ""
6925
6926 #. type: Plain text
6927 #: build/C/man2/personality.2:39
6928 msgid "B<int personality(unsigned long >I<persona>B<);>"
6929 msgstr ""
6930
6931 #. type: Plain text
6932 #: build/C/man2/personality.2:47
6933 msgid ""
6934 "Linux supports different execution domains, or personalities, for each "
6935 "process.  Among other things, execution domains tell Linux how to map signal "
6936 "numbers into signal actions.  The execution domain system allows Linux to "
6937 "provide limited support for binaries compiled under other UNIX-like "
6938 "operating systems."
6939 msgstr ""
6940
6941 #. type: Plain text
6942 #: build/C/man2/personality.2:59
6943 msgid ""
6944 "If I<persona> is not 0xffffffff, then B<personality>()  sets the caller's "
6945 "execution domain to the value specified by I<persona>.  Specifying "
6946 "I<persona> as 0xffffffff provides a way of retrieving the current persona "
6947 "without changing it."
6948 msgstr ""
6949
6950 #. type: Plain text
6951 #: build/C/man2/personality.2:62
6952 msgid ""
6953 "A list of the available execution domains can be found in "
6954 "I<E<lt>sys/personality.hE<gt>>."
6955 msgstr ""
6956
6957 #. type: Plain text
6958 #: build/C/man2/personality.2:69
6959 msgid ""
6960 "On success, the previous I<persona> is returned.  On error, -1 is returned, "
6961 "and I<errno> is set appropriately."
6962 msgstr ""
6963
6964 #. type: Plain text
6965 #: build/C/man2/personality.2:73
6966 msgid "The kernel was unable to change the personality."
6967 msgstr ""
6968
6969 #. type: Plain text
6970 #: build/C/man2/personality.2:77
6971 msgid ""
6972 "B<personality>()  is Linux-specific and should not be used in programs "
6973 "intended to be portable."
6974 msgstr ""
6975
6976 #. type: TH
6977 #: build/C/man2/pivot_root.2:10
6978 #, no-wrap
6979 msgid "PIVOT_ROOT"
6980 msgstr ""
6981
6982 #. type: Plain text
6983 #: build/C/man2/pivot_root.2:13
6984 msgid "pivot_root - change the root filesystem"
6985 msgstr ""
6986
6987 #. type: Plain text
6988 #: build/C/man2/pivot_root.2:15
6989 msgid "B<int pivot_root(const char *>I<new_root>B<, const char *>I<put_old>B<);>"
6990 msgstr ""
6991
6992 #
6993 #.  The
6994 #.  .B CAP_SYS_ADMIN
6995 #.  capability is required.
6996 #. type: Plain text
6997 #: build/C/man2/pivot_root.2:27
6998 msgid ""
6999 "B<pivot_root>()  moves the root filesystem of the calling process to the "
7000 "directory I<put_old> and makes I<new_root> the new root filesystem of the "
7001 "calling process."
7002 msgstr ""
7003
7004 #. type: Plain text
7005 #: build/C/man2/pivot_root.2:34
7006 msgid ""
7007 "The typical use of B<pivot_root>()  is during system startup, when the "
7008 "system mounts a temporary root filesystem (e.g., an B<initrd>), then mounts "
7009 "the real root filesystem, and eventually turns the latter into the current "
7010 "root of all relevant processes or threads."
7011 msgstr ""
7012
7013 #. type: Plain text
7014 #: build/C/man2/pivot_root.2:46
7015 msgid ""
7016 "B<pivot_root>()  may or may not change the current root and the current "
7017 "working directory of any processes or threads which use the old root "
7018 "directory.  The caller of B<pivot_root>()  must ensure that processes with "
7019 "root or current working directory at the old root operate correctly in "
7020 "either case.  An easy way to ensure this is to change their root and current "
7021 "working directory to I<new_root> before invoking B<pivot_root>()."
7022 msgstr ""
7023
7024 #. type: Plain text
7025 #: build/C/man2/pivot_root.2:64
7026 msgid ""
7027 "The paragraph above is intentionally vague because the implementation of "
7028 "B<pivot_root>()  may change in the future.  At the time of writing, "
7029 "B<pivot_root>()  changes root and current working directory of each process "
7030 "or thread to I<new_root> if they point to the old root directory.  This is "
7031 "necessary in order to prevent kernel threads from keeping the old root "
7032 "directory busy with their root and current working directory, even if they "
7033 "never access the filesystem in any way.  In the future, there may be a "
7034 "mechanism for kernel threads to explicitly relinquish any access to the "
7035 "filesystem, such that this fairly intrusive mechanism can be removed from "
7036 "B<pivot_root>()."
7037 msgstr ""
7038
7039 #. type: Plain text
7040 #: build/C/man2/pivot_root.2:72
7041 msgid ""
7042 "Note that this also applies to the calling process: B<pivot_root>()  may or "
7043 "may not affect its current working directory.  It is therefore recommended "
7044 "to call B<chdir(\"/\")> immediately after B<pivot_root>()."
7045 msgstr ""
7046
7047 #. type: Plain text
7048 #: build/C/man2/pivot_root.2:74
7049 msgid "The following restrictions apply to I<new_root> and I<put_old>:"
7050 msgstr ""
7051
7052 #. type: IP
7053 #: 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
7054 #, no-wrap
7055 msgid "-"
7056 msgstr ""
7057
7058 #. type: Plain text
7059 #: build/C/man2/pivot_root.2:76
7060 msgid "They must be directories."
7061 msgstr ""
7062
7063 #. type: Plain text
7064 #: build/C/man2/pivot_root.2:79
7065 msgid ""
7066 "I<new_root> and I<put_old> must not be on the same filesystem as the current "
7067 "root."
7068 msgstr ""
7069
7070 #. type: Plain text
7071 #: build/C/man2/pivot_root.2:83
7072 msgid ""
7073 "I<put_old> must be underneath I<new_root>, that is, adding a nonzero number "
7074 "of I</..> to the string pointed to by I<put_old> must yield the same "
7075 "directory as I<new_root>."
7076 msgstr ""
7077
7078 #. type: Plain text
7079 #: build/C/man2/pivot_root.2:85
7080 msgid "No other filesystem may be mounted on I<put_old>."
7081 msgstr ""
7082
7083 #. type: Plain text
7084 #: build/C/man2/pivot_root.2:89
7085 msgid "See also B<pivot_root>(8)  for additional usage examples."
7086 msgstr ""
7087
7088 #. type: Plain text
7089 #: build/C/man2/pivot_root.2:96
7090 msgid ""
7091 "If the current root is not a mount point (e.g., after B<chroot>(2)  or "
7092 "B<pivot_root>(), see also below), not the old root directory, but the mount "
7093 "point of that filesystem is mounted on I<put_old>."
7094 msgstr ""
7095
7096 #. type: Plain text
7097 #: build/C/man2/pivot_root.2:101
7098 msgid ""
7099 "I<new_root> does not have to be a mount point.  In this case, "
7100 "I</proc/mounts> will show the mount point of the filesystem containing "
7101 "I<new_root> as root (I</>)."
7102 msgstr ""
7103
7104 #. type: Plain text
7105 #: build/C/man2/pivot_root.2:110
7106 msgid ""
7107 "B<pivot_root>()  may return (in I<errno>) any of the errors returned by "
7108 "B<stat>(2).  Additionally, it may return:"
7109 msgstr ""
7110
7111 #. type: Plain text
7112 #: build/C/man2/pivot_root.2:114
7113 msgid ""
7114 "I<new_root> or I<put_old> are on the current root filesystem, or a "
7115 "filesystem is already mounted on I<put_old>."
7116 msgstr ""
7117
7118 #. type: Plain text
7119 #: build/C/man2/pivot_root.2:117
7120 msgid "I<put_old> is not underneath I<new_root>."
7121 msgstr ""
7122
7123 #. type: TP
7124 #: build/C/man2/pivot_root.2:117
7125 #, no-wrap
7126 msgid "B<ENOTDIR>"
7127 msgstr ""
7128
7129 #. type: Plain text
7130 #: build/C/man2/pivot_root.2:120
7131 msgid "I<new_root> or I<put_old> is not a directory."
7132 msgstr ""
7133
7134 #. type: Plain text
7135 #: build/C/man2/pivot_root.2:125
7136 msgid "The calling process does not have the B<CAP_SYS_ADMIN> capability."
7137 msgstr ""
7138
7139 #. type: Plain text
7140 #: build/C/man2/pivot_root.2:128
7141 msgid "B<pivot_root>()  was introduced in Linux 2.3.41."
7142 msgstr ""
7143
7144 #. type: Plain text
7145 #: build/C/man2/pivot_root.2:131
7146 msgid "B<pivot_root>()  is Linux-specific and hence is not portable."
7147 msgstr ""
7148
7149 #. type: Plain text
7150 #: build/C/man2/pivot_root.2:138
7151 msgid ""
7152 "B<pivot_root>()  should not have to change root and current working "
7153 "directory of all other processes in the system."
7154 msgstr ""
7155
7156 #. type: Plain text
7157 #: build/C/man2/pivot_root.2:143
7158 msgid ""
7159 "Some of the more obscure uses of B<pivot_root>()  may quickly lead to "
7160 "insanity."
7161 msgstr ""
7162
7163 #. type: Plain text
7164 #: build/C/man2/pivot_root.2:149
7165 msgid "B<chdir>(2), B<chroot>(2), B<stat>(2), B<initrd>(4), B<pivot_root>(8)"
7166 msgstr ""
7167
7168 #. type: TH
7169 #: build/C/man2/process_vm_readv.2:29
7170 #, no-wrap
7171 msgid "PROCESS_VM_READV"
7172 msgstr ""
7173
7174 #. type: TH
7175 #: build/C/man2/process_vm_readv.2:29
7176 #, no-wrap
7177 msgid "2014-05-05"
7178 msgstr ""
7179
7180 #. type: Plain text
7181 #: build/C/man2/process_vm_readv.2:32
7182 msgid ""
7183 "process_vm_readv, process_vm_writev - transfer data between process address "
7184 "spaces"
7185 msgstr ""
7186
7187 #. type: Plain text
7188 #: build/C/man2/process_vm_readv.2:35
7189 #, no-wrap
7190 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
7191 msgstr ""
7192
7193 #. type: Plain text
7194 #: build/C/man2/process_vm_readv.2:42
7195 #, no-wrap
7196 msgid ""
7197 "B<ssize_t process_vm_readv(pid_t >I<pid>B<,>\n"
7198 "B<                         const struct iovec *>I<local_iov>B<,>\n"
7199 "B<                         unsigned long >I<liovcnt>B<,>\n"
7200 "B<                         const struct iovec *>I<remote_iov>B<,>\n"
7201 "B<                         unsigned long >I<riovcnt>B<,>\n"
7202 "B<                         unsigned long >I<flags>B<);>\n"
7203 msgstr ""
7204
7205 #. type: Plain text
7206 #: build/C/man2/process_vm_readv.2:49
7207 #, no-wrap
7208 msgid ""
7209 "B<ssize_t process_vm_writev(pid_t >I<pid>B<,>\n"
7210 "B<                          const struct iovec *>I<local_iov>B<,>\n"
7211 "B<                          unsigned long >I<liovcnt>B<,>\n"
7212 "B<                          const struct iovec *>I<remote_iov>B<,>\n"
7213 "B<                          unsigned long >I<riovcnt>B<,>\n"
7214 "B<                          unsigned long >I<flags>B<);>\n"
7215 msgstr ""
7216
7217 #. type: Plain text
7218 #: build/C/man2/process_vm_readv.2:54
7219 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
7220 msgstr ""
7221
7222 #. type: Plain text
7223 #: build/C/man2/process_vm_readv.2:58
7224 msgid "B<process_vm_readv>(), B<process_vm_write>():"
7225 msgstr ""
7226
7227 #. type: Plain text
7228 #: build/C/man2/process_vm_readv.2:62
7229 msgid "B<_GNU_SOURCE>"
7230 msgstr ""
7231
7232 #. type: Plain text
7233 #: build/C/man2/process_vm_readv.2:73
7234 msgid ""
7235 "These system calls transfer data between the address space of the calling "
7236 "process (\"the local process\") and the process identified by I<pid> (\"the "
7237 "remote process\").  The data moves directly between the address spaces of "
7238 "the two processes, without passing through kernel space."
7239 msgstr ""
7240
7241 #. type: Plain text
7242 #: build/C/man2/process_vm_readv.2:98
7243 msgid ""
7244 "The B<process_vm_readv>()  system call transfers data from the remote "
7245 "process to the local process.  The data to be transferred is identified by "
7246 "I<remote_iov> and I<riovcnt>: I<remote_iov> is a pointer to an array "
7247 "describing address ranges in the process I<pid>, and I<riovcnt> specifies "
7248 "the number of elements in I<remote_iov>.  The data is transferred to the "
7249 "locations specified by I<local_iov> and I<liovcnt>: I<local_iov> is a "
7250 "pointer to an array describing address ranges in the calling process, and "
7251 "I<liovcnt> specifies the number of elements in I<local_iov>."
7252 msgstr ""
7253
7254 #. type: Plain text
7255 #: build/C/man2/process_vm_readv.2:112
7256 msgid ""
7257 "The B<process_vm_writev>()  system call is the converse of "
7258 "B<process_vm_readv>()\\(emit transfers data from the local process to the "
7259 "remote process.  Other than the direction of the transfer, the arguments "
7260 "I<liovcnt>, I<local_iov>, I<riovcnt>, and I<remote_iov> have the same "
7261 "meaning as for B<process_vm_readv>()."
7262 msgstr ""
7263
7264 #. type: Plain text
7265 #: build/C/man2/process_vm_readv.2:122
7266 msgid ""
7267 "The I<local_iov> and I<remote_iov> arguments point to an array of I<iovec> "
7268 "structures, defined in I<E<lt>sys/uio.hE<gt>> as:"
7269 msgstr ""
7270
7271 #. type: Plain text
7272 #: build/C/man2/process_vm_readv.2:129
7273 #, no-wrap
7274 msgid ""
7275 "struct iovec {\n"
7276 "    void  *iov_base;    /* Starting address */\n"
7277 "    size_t iov_len;     /* Number of bytes to transfer */\n"
7278 "};\n"
7279 msgstr ""
7280
7281 #. type: Plain text
7282 #: build/C/man2/process_vm_readv.2:145
7283 msgid ""
7284 "Buffers are processed in array order.  This means that B<process_vm_readv>()  "
7285 "completely fills I<local_iov[0]> before proceeding to I<local_iov[1]>, and "
7286 "so on.  Likewise, I<remote_iov[0]> is completely read before proceeding to "
7287 "I<remote_iov[1]>, and so on."
7288 msgstr ""
7289
7290 #. type: Plain text
7291 #: build/C/man2/process_vm_readv.2:156
7292 msgid ""
7293 "Similarly, B<process_vm_writev>()  writes out the entire contents of "
7294 "I<local_iov[0]> before proceeding to I<local_iov[1]>, and it completely "
7295 "fills I<remote_iov[0]> before proceeding to I<remote_iov[1]>."
7296 msgstr ""
7297
7298 #. type: Plain text
7299 #: build/C/man2/process_vm_readv.2:164
7300 msgid ""
7301 "The lengths of I<remote_iov[i].iov_len> and I<local_iov[i].iov_len> do not "
7302 "have to be the same.  Thus, it is possible to split a single local buffer "
7303 "into multiple remote buffers, or vice versa."
7304 msgstr ""
7305
7306 #. type: Plain text
7307 #: build/C/man2/process_vm_readv.2:168
7308 msgid "The I<flags> argument is currently unused and must be set to 0."
7309 msgstr ""
7310
7311 #.  In time, glibc might provide a wrapper that works around this limit,
7312 #.  as is done for readv()/writev()
7313 #. type: Plain text
7314 #: build/C/man2/process_vm_readv.2:181
7315 msgid ""
7316 "The values specified in the I<liovcnt> and I<riovcnt> arguments must be less "
7317 "than or equal to B<IOV_MAX> (defined in I<E<lt>limits.hE<gt>> or accessible "
7318 "via the call I<sysconf(_SC_IOV_MAX)>)."
7319 msgstr ""
7320
7321 #. type: Plain text
7322 #: build/C/man2/process_vm_readv.2:191
7323 msgid ""
7324 "The count arguments and I<local_iov> are checked before doing any "
7325 "transfers.  If the counts are too big, or I<local_iov> is invalid, or the "
7326 "addresses refer to regions that are inaccessible to the local process, none "
7327 "of the vectors will be processed and an error will be returned immediately."
7328 msgstr ""
7329
7330 #. type: Plain text
7331 #: build/C/man2/process_vm_readv.2:211
7332 msgid ""
7333 "Note, however, that these system calls do not check the memory regions in "
7334 "the remote process until just before doing the read/write.  Consequently, a "
7335 "partial read/write (see RETURN VALUE)  may result if one of the "
7336 "I<remote_iov> elements points to an invalid memory region in the remote "
7337 "process.  No further reads/writes will be attempted beyond that point.  Keep "
7338 "this in mind when attempting to read data of unknown length (such as C "
7339 "strings that are null-terminated) from a remote process, by avoiding "
7340 "spanning memory pages (typically 4KiB) in a single remote I<iovec> element.  "
7341 "(Instead, split the remote read into two I<remote_iov> elements and have "
7342 "them merge back into a single write I<local_iov> entry.  The first read "
7343 "entry goes up to the page boundary, while the second starts on the next page "
7344 "boundary.)"
7345 msgstr ""
7346
7347 #. type: Plain text
7348 #: build/C/man2/process_vm_readv.2:225
7349 msgid ""
7350 "In order to read from or write to another process, either the caller must "
7351 "have the capability B<CAP_SYS_PTRACE>, or the real user ID, effective user "
7352 "ID, and saved set-user-ID of the remote process must match the real user ID "
7353 "of the caller I<and> the real group ID, effective group ID, and saved "
7354 "set-group-ID of the remote process must match the real group ID of the "
7355 "caller.  (The permission required is exactly the same as that required to "
7356 "perform a B<ptrace>(2)  B<PTRACE_ATTACH> on the remote process.)"
7357 msgstr ""
7358
7359 #. type: Plain text
7360 #: build/C/man2/process_vm_readv.2:241
7361 msgid ""
7362 "On success, B<process_vm_readv>()  returns the number of bytes read and "
7363 "B<process_vm_writev>()  returns the number of bytes written.  This return "
7364 "value may be less than the total number of requested bytes, if a partial "
7365 "read/write occurred.  (Partial transfers apply at the granularity of "
7366 "I<iovec> elements.  These system calls won't perform a partial transfer that "
7367 "splits a single I<iovec> element.)  The caller should check the return value "
7368 "to determine whether a partial read/write occurred."
7369 msgstr ""
7370
7371 #. type: Plain text
7372 #: build/C/man2/process_vm_readv.2:245
7373 msgid "On error, -1 is returned and I<errno> is set appropriately."
7374 msgstr ""
7375
7376 #. type: Plain text
7377 #: build/C/man2/process_vm_readv.2:257
7378 msgid ""
7379 "The sum of the I<iov_len> values of either I<local_iov> or I<remote_iov> "
7380 "overflows a I<ssize_t> value."
7381 msgstr ""
7382
7383 #. type: Plain text
7384 #: build/C/man2/process_vm_readv.2:261
7385 msgid "I<flags> is not 0."
7386 msgstr ""
7387
7388 #. type: Plain text
7389 #: build/C/man2/process_vm_readv.2:267
7390 msgid "I<liovcnt> or I<riovcnt> is too large."
7391 msgstr ""
7392
7393 #. type: Plain text
7394 #: build/C/man2/process_vm_readv.2:272
7395 msgid ""
7396 "The memory described by I<local_iov> is outside the caller's accessible "
7397 "address space."
7398 msgstr ""
7399
7400 #. type: Plain text
7401 #: build/C/man2/process_vm_readv.2:278
7402 msgid ""
7403 "The memory described by I<remote_iov> is outside the accessible address "
7404 "space of the process I<pid>."
7405 msgstr ""
7406
7407 #. type: Plain text
7408 #: build/C/man2/process_vm_readv.2:283
7409 msgid "Could not allocate memory for internal copies of the I<iovec> structures."
7410 msgstr ""
7411
7412 #. type: Plain text
7413 #: build/C/man2/process_vm_readv.2:287
7414 msgid ""
7415 "The caller does not have permission to access the address space of the "
7416 "process I<pid>."
7417 msgstr ""
7418
7419 #. type: Plain text
7420 #: build/C/man2/process_vm_readv.2:292
7421 msgid "No process with ID I<pid> exists."
7422 msgstr ""
7423
7424 #. type: Plain text
7425 #: build/C/man2/process_vm_readv.2:295
7426 msgid ""
7427 "These system calls were added in Linux 3.2.  Support is provided in glibc "
7428 "since version 2.15."
7429 msgstr ""
7430
7431 #. type: Plain text
7432 #: build/C/man2/process_vm_readv.2:297
7433 msgid "These system calls are nonstandard Linux extensions."
7434 msgstr ""
7435
7436 #. type: Plain text
7437 #: build/C/man2/process_vm_readv.2:303
7438 msgid ""
7439 "The data transfers performed by B<process_vm_readv>()  and "
7440 "B<process_vm_writev>()  are not guaranteed to be atomic in any way."
7441 msgstr ""
7442
7443 #.  Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
7444 #.  See also some benchmarks at http://lwn.net/Articles/405284/
7445 #.  and http://marc.info/?l=linux-mm&m=130105930902915&w=2
7446 #. type: Plain text
7447 #: build/C/man2/process_vm_readv.2:311
7448 msgid ""
7449 "These system calls were designed to permit fast message passing by allowing "
7450 "messages to be exchanged with a single copy operation (rather than the "
7451 "double copy that would be required when using, for example, shared memory or "
7452 "pipes)."
7453 msgstr ""
7454
7455 #. type: Plain text
7456 #: build/C/man2/process_vm_readv.2:319
7457 msgid ""
7458 "The following code sample demonstrates the use of B<process_vm_readv>().  It "
7459 "reads 20 bytes at the address 0x10000 from the process with PID 10 and "
7460 "writes the first 10 bytes into I<buf1> and the second 10 bytes into I<buf2>."
7461 msgstr ""
7462
7463 #. type: Plain text
7464 #: build/C/man2/process_vm_readv.2:322
7465 #, no-wrap
7466 msgid "#include E<lt>sys/uio.hE<gt>\n"
7467 msgstr ""
7468
7469 #. type: Plain text
7470 #: build/C/man2/process_vm_readv.2:332
7471 #, no-wrap
7472 msgid ""
7473 "int\n"
7474 "main(void)\n"
7475 "{\n"
7476 "    struct iovec local[2];\n"
7477 "    struct iovec remote[1];\n"
7478 "    char buf1[10];\n"
7479 "    char buf2[10];\n"
7480 "    ssize_t nread;\n"
7481 "    pid_t pid = 10;             /* PID of remote process */\n"
7482 msgstr ""
7483
7484 #. type: Plain text
7485 #: build/C/man2/process_vm_readv.2:339
7486 #, no-wrap
7487 msgid ""
7488 "    local[0].iov_base = buf1;\n"
7489 "    local[0].iov_len = 10;\n"
7490 "    local[1].iov_base = buf2;\n"
7491 "    local[1].iov_len = 10;\n"
7492 "    remote[0].iov_base = (void *) 0x10000;\n"
7493 "    remote[1].iov_len = 20;\n"
7494 msgstr ""
7495
7496 #. type: Plain text
7497 #: build/C/man2/process_vm_readv.2:346
7498 #, no-wrap
7499 msgid ""
7500 "    nread = process_vm_readv(pid, local, 2, remote, 1, 0);\n"
7501 "    if (nread != 20)\n"
7502 "        return 1;\n"
7503 "    else\n"
7504 "        return 0;\n"
7505 "}\n"
7506 msgstr ""
7507
7508 #. type: Plain text
7509 #: build/C/man2/process_vm_readv.2:350
7510 msgid "B<readv>(2), B<writev>(2)"
7511 msgstr ""
7512
7513 #. type: TH
7514 #: build/C/man2/ptrace.2:44
7515 #, no-wrap
7516 msgid "PTRACE"
7517 msgstr ""
7518
7519 #. type: TH
7520 #: build/C/man2/ptrace.2:44
7521 #, no-wrap
7522 msgid "2014-02-20"
7523 msgstr ""
7524
7525 #. type: Plain text
7526 #: build/C/man2/ptrace.2:47
7527 msgid "ptrace - process trace"
7528 msgstr ""
7529
7530 #. type: Plain text
7531 #: build/C/man2/ptrace.2:50
7532 #, no-wrap
7533 msgid "B<#include E<lt>sys/ptrace.hE<gt>>\n"
7534 msgstr ""
7535
7536 #. type: Plain text
7537 #: build/C/man2/ptrace.2:53
7538 #, no-wrap
7539 msgid ""
7540 "B<long ptrace(enum __ptrace_request >I<request>B<, pid_t >I<pid>B<, >\n"
7541 "B<            void *>I<addr>B<, void *>I<data>B<);>\n"
7542 msgstr ""
7543
7544 #. type: Plain text
7545 #: build/C/man2/ptrace.2:62
7546 msgid ""
7547 "The B<ptrace>()  system call provides a means by which one process (the "
7548 "\"tracer\")  may observe and control the execution of another process (the "
7549 "\"tracee\"), and examine and change the tracee's memory and registers.  It "
7550 "is primarily used to implement breakpoint debugging and system call tracing."
7551 msgstr ""
7552
7553 #. type: Plain text
7554 #: build/C/man2/ptrace.2:73
7555 msgid ""
7556 "A tracee first needs to be attached to the tracer.  Attachment and "
7557 "subsequent commands are per thread: in a multithreaded process, every thread "
7558 "can be individually attached to a (potentially different) tracer, or left "
7559 "not attached and thus not debugged.  Therefore, \"tracee\" always means "
7560 "\"(one) thread\", never \"a (possibly multithreaded) process\".  Ptrace "
7561 "commands are always sent to a specific tracee using a call of the form"
7562 msgstr ""
7563
7564 #. type: Plain text
7565 #: build/C/man2/ptrace.2:75
7566 #, no-wrap
7567 msgid "    ptrace(PTRACE_foo, pid, ...)\n"
7568 msgstr ""
7569
7570 #. type: Plain text
7571 #: build/C/man2/ptrace.2:79
7572 msgid "where I<pid> is the thread ID of the corresponding Linux thread."
7573 msgstr ""
7574
7575 #. type: Plain text
7576 #: build/C/man2/ptrace.2:85
7577 msgid ""
7578 "(Note that in this page, a \"multithreaded process\" means a thread group "
7579 "consisting of threads created using the B<clone>(2)  B<CLONE_THREAD> flag.)"
7580 msgstr ""
7581
7582 #. type: Plain text
7583 #: build/C/man2/ptrace.2:96
7584 msgid ""
7585 "A process can initiate a trace by calling B<fork>(2)  and having the "
7586 "resulting child do a B<PTRACE_TRACEME>, followed (typically) by an "
7587 "B<execve>(2).  Alternatively, one process may commence tracing another "
7588 "process using B<PTRACE_ATTACH> or B<PTRACE_SEIZE>."
7589 msgstr ""
7590
7591 #. type: Plain text
7592 #: build/C/man2/ptrace.2:113
7593 msgid ""
7594 "While being traced, the tracee will stop each time a signal is delivered, "
7595 "even if the signal is being ignored.  (An exception is B<SIGKILL>, which has "
7596 "its usual effect.)  The tracer will be notified at its next call to "
7597 "B<waitpid>(2)  (or one of the related \"wait\" system calls); that call will "
7598 "return a I<status> value containing information that indicates the cause of "
7599 "the stop in the tracee.  While the tracee is stopped, the tracer can use "
7600 "various ptrace requests to inspect and modify the tracee.  The tracer then "
7601 "causes the tracee to continue, optionally ignoring the delivered signal (or "
7602 "even delivering a different signal instead)."
7603 msgstr ""
7604
7605 #. type: Plain text
7606 #: build/C/man2/ptrace.2:123
7607 msgid ""
7608 "If the B<PTRACE_O_TRACEEXEC> option is not in effect, all successful calls "
7609 "to B<execve>(2)  by the traced process will cause it to be sent a B<SIGTRAP> "
7610 "signal, giving the parent a chance to gain control before the new program "
7611 "begins execution."
7612 msgstr ""
7613
7614 #. type: Plain text
7615 #: build/C/man2/ptrace.2:127
7616 msgid ""
7617 "When the tracer is finished tracing, it can cause the tracee to continue "
7618 "executing in a normal, untraced mode via B<PTRACE_DETACH>."
7619 msgstr ""
7620
7621 #. type: Plain text
7622 #: build/C/man2/ptrace.2:131
7623 msgid "The value of I<request> determines the action to be performed:"
7624 msgstr ""
7625
7626 #. type: TP
7627 #: build/C/man2/ptrace.2:131
7628 #, no-wrap
7629 msgid "B<PTRACE_TRACEME>"
7630 msgstr ""
7631
7632 #. type: Plain text
7633 #: build/C/man2/ptrace.2:141
7634 msgid ""
7635 "Indicate that this process is to be traced by its parent.  A process "
7636 "probably shouldn't make this request if its parent isn't expecting to trace "
7637 "it.  (I<pid>, I<addr>, and I<data> are ignored.)"
7638 msgstr ""
7639
7640 #. type: Plain text
7641 #: build/C/man2/ptrace.2:156
7642 msgid ""
7643 "The B<PTRACE_TRACEME> request is used only by the tracee; the remaining "
7644 "requests are used only by the tracer.  In the following requests, I<pid> "
7645 "specifies the thread ID of the tracee to be acted on.  For requests other "
7646 "than B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, B<PTRACE_INTERRUPT>, and "
7647 "B<PTRACE_KILL>, the tracee must be stopped."
7648 msgstr ""
7649
7650 #. type: TP
7651 #: build/C/man2/ptrace.2:156
7652 #, no-wrap
7653 msgid "B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>"
7654 msgstr ""
7655
7656 #. type: Plain text
7657 #: build/C/man2/ptrace.2:167
7658 msgid ""
7659 "Read a word at the address I<addr> in the tracee's memory, returning the "
7660 "word as the result of the B<ptrace>()  call.  Linux does not have separate "
7661 "text and data address spaces, so these two requests are currently "
7662 "equivalent.  (I<data> is ignored; but see NOTES.)"
7663 msgstr ""
7664
7665 #. type: TP
7666 #: build/C/man2/ptrace.2:167
7667 #, no-wrap
7668 msgid "B<PTRACE_PEEKUSER>"
7669 msgstr ""
7670
7671 #.  PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
7672 #.  and that is the name that seems common on other systems.
7673 #. type: Plain text
7674 #: build/C/man2/ptrace.2:185
7675 msgid ""
7676 "Read a word at offset I<addr> in the tracee's USER area, which holds the "
7677 "registers and other information about the process (see "
7678 "I<E<lt>sys/user.hE<gt>>).  The word is returned as the result of the "
7679 "B<ptrace>()  call.  Typically, the offset must be word-aligned, though this "
7680 "might vary by architecture.  See NOTES.  (I<data> is ignored; but see "
7681 "NOTES.)"
7682 msgstr ""
7683
7684 #. type: TP
7685 #: build/C/man2/ptrace.2:185
7686 #, no-wrap
7687 msgid "B<PTRACE_POKETEXT>, B<PTRACE_POKEDATA>"
7688 msgstr ""
7689
7690 #. type: Plain text
7691 #: build/C/man2/ptrace.2:197
7692 msgid ""
7693 "Copy the word I<data> to the address I<addr> in the tracee's memory.  As for "
7694 "B<PTRACE_PEEKTEXT> and B<PTRACE_PEEKDATA>, these two requests are currently "
7695 "equivalent."
7696 msgstr ""
7697
7698 #. type: TP
7699 #: build/C/man2/ptrace.2:197
7700 #, no-wrap
7701 msgid "B<PTRACE_POKEUSER>"
7702 msgstr ""
7703
7704 #.  PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
7705 #.  and that is the name that seems common on other systems.
7706 #.  FIXME In the preceding sentence, which modifications are disallowed,
7707 #.  and when they are disallowed, how does user space discover that fact?
7708 #. type: Plain text
7709 #: build/C/man2/ptrace.2:213
7710 msgid ""
7711 "Copy the word I<data> to offset I<addr> in the tracee's USER area.  As for "
7712 "B<PTRACE_PEEKUSER>, the offset must typically be word-aligned.  In order to "
7713 "maintain the integrity of the kernel, some modifications to the USER area "
7714 "are disallowed."
7715 msgstr ""
7716
7717 #. type: TP
7718 #: build/C/man2/ptrace.2:213
7719 #, no-wrap
7720 msgid "B<PTRACE_GETREGS>, B<PTRACE_GETFPREGS>"
7721 msgstr ""
7722
7723 #. type: Plain text
7724 #: build/C/man2/ptrace.2:236
7725 msgid ""
7726 "Copy the tracee's general-purpose or floating-point registers, respectively, "
7727 "to the address I<data> in the tracer.  See I<E<lt>sys/user.hE<gt>> for "
7728 "information on the format of this data.  (I<addr> is ignored.)  Note that "
7729 "SPARC systems have the meaning of I<data> and I<addr> reversed; that is, "
7730 "I<data> is ignored and the registers are copied to the address I<addr>.  "
7731 "B<PTRACE_GETREGS> and B<PTRACE_GETFPREGS> are not present on all "
7732 "architectures."
7733 msgstr ""
7734
7735 #. type: TP
7736 #: build/C/man2/ptrace.2:236
7737 #, no-wrap
7738 msgid "B<PTRACE_GETREGSET> (since Linux 2.6.34)"
7739 msgstr ""
7740
7741 #. type: Plain text
7742 #: build/C/man2/ptrace.2:257
7743 msgid ""
7744 "Read the tracee's registers.  I<addr> specifies, in an "
7745 "architecture-dependent way, the type of registers to be read.  "
7746 "B<NT_PRSTATUS> (with numerical value 1)  usually results in reading of "
7747 "general-purpose registers.  If the CPU has, for example, floating-point "
7748 "and/or vector registers, they can be retrieved by setting I<addr> to the "
7749 "corresponding B<NT_foo> constant.  I<data> points to a B<struct iovec>, "
7750 "which describes the destination buffer's location and length.  On return, "
7751 "the kernel modifies B<iov.len> to indicate the actual number of bytes "
7752 "returned."
7753 msgstr ""
7754
7755 #. type: TP
7756 #: build/C/man2/ptrace.2:257
7757 #, no-wrap
7758 msgid "B<PTRACE_SETREGS>, B<PTRACE_SETFPREGS>"
7759 msgstr ""
7760
7761 #.  FIXME In the preceding sentence, which modifications are disallowed,
7762 #.  and when they are disallowed, how does user space discover that fact?
7763 #. type: Plain text
7764 #: build/C/man2/ptrace.2:282
7765 msgid ""
7766 "Modify the tracee's general-purpose or floating-point registers, "
7767 "respectively, from the address I<data> in the tracer.  As for "
7768 "B<PTRACE_POKEUSER>, some general-purpose register modifications may be "
7769 "disallowed.  (I<addr> is ignored.)  Note that SPARC systems have the meaning "
7770 "of I<data> and I<addr> reversed; that is, I<data> is ignored and the "
7771 "registers are copied from the address I<addr>.  B<PTRACE_SETREGS> and "
7772 "B<PTRACE_SETFPREGS> are not present on all architectures."
7773 msgstr ""
7774
7775 #. type: TP
7776 #: build/C/man2/ptrace.2:282
7777 #, no-wrap
7778 msgid "B<PTRACE_SETREGSET> (since Linux 2.6.34)"
7779 msgstr ""
7780
7781 #. type: Plain text
7782 #: build/C/man2/ptrace.2:291
7783 msgid ""
7784 "Modify the tracee's registers.  The meaning of I<addr> and I<data> is "
7785 "analogous to B<PTRACE_GETREGSET>."
7786 msgstr ""
7787
7788 #. type: TP
7789 #: build/C/man2/ptrace.2:291
7790 #, no-wrap
7791 msgid "B<PTRACE_GETSIGINFO> (since Linux 2.3.99-pre6)"
7792 msgstr ""
7793
7794 #. type: Plain text
7795 #: build/C/man2/ptrace.2:303
7796 msgid ""
7797 "Retrieve information about the signal that caused the stop.  Copy a "
7798 "I<siginfo_t> structure (see B<sigaction>(2))  from the tracee to the address "
7799 "I<data> in the tracer.  (I<addr> is ignored.)"
7800 msgstr ""
7801
7802 #. type: TP
7803 #: build/C/man2/ptrace.2:303
7804 #, no-wrap
7805 msgid "B<PTRACE_SETSIGINFO> (since Linux 2.3.99-pre6)"
7806 msgstr ""
7807
7808 #. type: Plain text
7809 #: build/C/man2/ptrace.2:319
7810 msgid ""
7811 "Set signal information: copy a I<siginfo_t> structure from the address "
7812 "I<data> in the tracer to the tracee.  This will affect only signals that "
7813 "would normally be delivered to the tracee and were caught by the tracer.  It "
7814 "may be difficult to tell these normal signals from synthetic signals "
7815 "generated by B<ptrace>()  itself.  (I<addr> is ignored.)"
7816 msgstr ""
7817
7818 #. type: TP
7819 #: build/C/man2/ptrace.2:319
7820 #, no-wrap
7821 msgid "B<PTRACE_PEEKSIGINFO> (since Linux 3.10)"
7822 msgstr ""
7823
7824 #.  commit 84c751bd4aebbaae995fe32279d3dba48327bad4
7825 #. type: Plain text
7826 #: build/C/man2/ptrace.2:345
7827 msgid ""
7828 "Retrieve I<siginfo_t> structures without removing signals from a queue.  "
7829 "I<addr> points to a I<ptrace_peeksiginfo_args> structure that specifies the "
7830 "ordinal position from which copying of signals should start, and the number "
7831 "of signals to copy.  I<siginfo_t> structures are copied into the buffer "
7832 "pointed to by I<data>.  The return value contains the number of copied "
7833 "signals (zero indicates that there is no signal corresponding to the "
7834 "specified ordinal position).  Within the returned I<siginfo> structures, the "
7835 "I<si_code> field includes information (B<__SI_CHLD>, B<__SI_FAULT>, etc.) "
7836 "that are not otherwise exposed to user space."
7837 msgstr ""
7838
7839 #. type: Plain text
7840 #: build/C/man2/ptrace.2:354
7841 #, no-wrap
7842 msgid ""
7843 "struct ptrace_peeksiginfo_args {\n"
7844 "    u64 off;    /* Ordinal position in queue at which\n"
7845 "                   to start copying signals */\n"
7846 "    u32 flags;  /* PTRACE_PEEKSIGINFO_SHARED or 0 */\n"
7847 "    s32 nr;     /* Number of signals to copy */\n"
7848 "};\n"
7849 msgstr ""
7850
7851 #. type: Plain text
7852 #: build/C/man2/ptrace.2:361
7853 msgid ""
7854 "Currently, there is only one flag, B<PTRACE_PEEKSIGINFO_SHARED>, for dumping "
7855 "signals from the process-wide signal queue.  If this flag is not set, "
7856 "signals are read from the per-thread queue of the specified thread."
7857 msgstr ""
7858
7859 #. type: TP
7860 #: build/C/man2/ptrace.2:363
7861 #, no-wrap
7862 msgid "B<PTRACE_GETSIGMASK> (since Linux 3.11)"
7863 msgstr ""
7864
7865 #.  commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
7866 #. type: Plain text
7867 #: build/C/man2/ptrace.2:378
7868 msgid ""
7869 "Place a copy of the mask of blocked signals (see B<sigprocmask>(2))  in the "
7870 "buffer pointed to by I<data>, which should be a pointer to a buffer of type "
7871 "I<sigset_t>.  The I<addr> argument contains the size of the buffer pointed "
7872 "to by I<data> (i.e., I<sizeof(sigset_t)>)."
7873 msgstr ""
7874
7875 #. type: TP
7876 #: build/C/man2/ptrace.2:378
7877 #, no-wrap
7878 msgid "B<PTRACE_SETSIGMASK> (since Linux 3.11)"
7879 msgstr ""
7880
7881 #. type: Plain text
7882 #: build/C/man2/ptrace.2:392
7883 msgid ""
7884 "Change the mask of blocked signals (see B<sigprocmask>(2))  to the value "
7885 "specified in the buffer pointed to by I<data>, which should be a pointer to "
7886 "a buffer of type I<sigset_t>.  The I<addr> argument contains the size of the "
7887 "buffer pointed to by I<data> (i.e., I<sizeof(sigset_t)>)."
7888 msgstr ""
7889
7890 #. type: TP
7891 #: build/C/man2/ptrace.2:392
7892 #, no-wrap
7893 msgid "B<PTRACE_SETOPTIONS> (since Linux 2.4.6; see BUGS for caveats)"
7894 msgstr ""
7895
7896 #. type: Plain text
7897 #: build/C/man2/ptrace.2:401
7898 msgid ""
7899 "Set ptrace options from I<data>.  (I<addr> is ignored.)  I<data> is "
7900 "interpreted as a bit mask of options, which are specified by the following "
7901 "flags:"
7902 msgstr ""
7903
7904 #. type: TP
7905 #: build/C/man2/ptrace.2:402
7906 #, no-wrap
7907 msgid "B<PTRACE_O_EXITKILL> (since Linux 3.8)"
7908 msgstr ""
7909
7910 #.  commit 992fb6e170639b0849bace8e49bf31bd37c4123
7911 #. type: Plain text
7912 #: build/C/man2/ptrace.2:410
7913 msgid ""
7914 "If a tracer sets this flag, a B<SIGKILL> signal will be sent to every tracee "
7915 "if the tracer exits.  This option is useful for ptrace jailers that want to "
7916 "ensure that tracees can never escape the tracer's control."
7917 msgstr ""
7918
7919 #. type: TP
7920 #: build/C/man2/ptrace.2:410
7921 #, no-wrap
7922 msgid "B<PTRACE_O_TRACECLONE> (since Linux 2.5.46)"
7923 msgstr ""
7924
7925 #. type: Plain text
7926 #: build/C/man2/ptrace.2:427
7927 msgid ""
7928 "Stop the tracee at the next B<clone>(2)  and automatically start tracing the "
7929 "newly cloned process, which will start with a B<SIGSTOP>, or "
7930 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
7931 "tracer will return a I<status> value such that"
7932 msgstr ""
7933
7934 #. type: Plain text
7935 #: build/C/man2/ptrace.2:430
7936 #, no-wrap
7937 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_CLONEE<lt>E<lt>8))\n"
7938 msgstr ""
7939
7940 #. type: Plain text
7941 #: build/C/man2/ptrace.2:434 build/C/man2/ptrace.2:520 build/C/man2/ptrace.2:553
7942 msgid "The PID of the new process can be retrieved with B<PTRACE_GETEVENTMSG>."
7943 msgstr ""
7944
7945 #. type: Plain text
7946 #: build/C/man2/ptrace.2:455
7947 msgid ""
7948 "This option may not catch B<clone>(2)  calls in all cases.  If the tracee "
7949 "calls B<clone>(2)  with the B<CLONE_VFORK> flag, B<PTRACE_EVENT_VFORK> will "
7950 "be delivered instead if B<PTRACE_O_TRACEVFORK> is set; otherwise if the "
7951 "tracee calls B<clone>(2)  with the exit signal set to B<SIGCHLD>, "
7952 "B<PTRACE_EVENT_FORK> will be delivered if B<PTRACE_O_TRACEFORK> is set."
7953 msgstr ""
7954
7955 #. type: TP
7956 #: build/C/man2/ptrace.2:455
7957 #, no-wrap
7958 msgid "B<PTRACE_O_TRACEEXEC> (since Linux 2.5.46)"
7959 msgstr ""
7960
7961 #. type: Plain text
7962 #: build/C/man2/ptrace.2:464
7963 msgid ""
7964 "Stop the tracee at the next B<execve>(2).  A B<waitpid>(2)  by the tracer "
7965 "will return a I<status> value such that"
7966 msgstr ""
7967
7968 #. type: Plain text
7969 #: build/C/man2/ptrace.2:467
7970 #, no-wrap
7971 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXECE<lt>E<lt>8))\n"
7972 msgstr ""
7973
7974 #. type: Plain text
7975 #: build/C/man2/ptrace.2:473
7976 msgid ""
7977 "If the execing thread is not a thread group leader, the thread ID is reset "
7978 "to thread group leader's ID before this stop.  Since Linux 3.0, the former "
7979 "thread ID can be retrieved with B<PTRACE_GETEVENTMSG>."
7980 msgstr ""
7981
7982 #. type: TP
7983 #: build/C/man2/ptrace.2:473
7984 #, no-wrap
7985 msgid "B<PTRACE_O_TRACEEXIT> (since Linux 2.5.60)"
7986 msgstr ""
7987
7988 #. type: Plain text
7989 #: build/C/man2/ptrace.2:481
7990 msgid ""
7991 "Stop the tracee at exit.  A B<waitpid>(2)  by the tracer will return a "
7992 "I<status> value such that"
7993 msgstr ""
7994
7995 #. type: Plain text
7996 #: build/C/man2/ptrace.2:484
7997 #, no-wrap
7998 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXITE<lt>E<lt>8))\n"
7999 msgstr ""
8000
8001 #. type: Plain text
8002 #: build/C/man2/ptrace.2:488
8003 msgid "The tracee's exit status can be retrieved with B<PTRACE_GETEVENTMSG>."
8004 msgstr ""
8005
8006 #. type: Plain text
8007 #: build/C/man2/ptrace.2:496
8008 msgid ""
8009 "The tracee is stopped early during process exit, when registers are still "
8010 "available, allowing the tracer to see where the exit occurred, whereas the "
8011 "normal exit notification is done after the process is finished exiting.  "
8012 "Even though context is available, the tracer cannot prevent the exit from "
8013 "happening at this point."
8014 msgstr ""
8015
8016 #. type: TP
8017 #: build/C/man2/ptrace.2:496
8018 #, no-wrap
8019 msgid "B<PTRACE_O_TRACEFORK> (since Linux 2.5.46)"
8020 msgstr ""
8021
8022 #. type: Plain text
8023 #: build/C/man2/ptrace.2:513
8024 msgid ""
8025 "Stop the tracee at the next B<fork>(2)  and automatically start tracing the "
8026 "newly forked process, which will start with a B<SIGSTOP>, or "
8027 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
8028 "tracer will return a I<status> value such that"
8029 msgstr ""
8030
8031 #. type: Plain text
8032 #: build/C/man2/ptrace.2:516
8033 #, no-wrap
8034 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_FORKE<lt>E<lt>8))\n"
8035 msgstr ""
8036
8037 #. type: TP
8038 #: build/C/man2/ptrace.2:520
8039 #, no-wrap
8040 msgid "B<PTRACE_O_TRACESYSGOOD> (since Linux 2.4.6)"
8041 msgstr ""
8042
8043 #. type: Plain text
8044 #: build/C/man2/ptrace.2:529
8045 msgid ""
8046 "When delivering system call traps, set bit 7 in the signal number (i.e., "
8047 "deliver I<SIGTRAP|0x80>).  This makes it easy for the tracer to distinguish "
8048 "normal traps from those caused by a system call.  (B<PTRACE_O_TRACESYSGOOD> "
8049 "may not work on all architectures.)"
8050 msgstr ""
8051
8052 #. type: TP
8053 #: build/C/man2/ptrace.2:529
8054 #, no-wrap
8055 msgid "B<PTRACE_O_TRACEVFORK> (since Linux 2.5.46)"
8056 msgstr ""
8057
8058 #. type: Plain text
8059 #: build/C/man2/ptrace.2:546
8060 msgid ""
8061 "Stop the tracee at the next B<vfork>(2)  and automatically start tracing the "
8062 "newly vforked process, which will start with a B<SIGSTOP>, or "
8063 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
8064 "tracer will return a I<status> value such that"
8065 msgstr ""
8066
8067 #. type: Plain text
8068 #: build/C/man2/ptrace.2:549
8069 #, no-wrap
8070 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORKE<lt>E<lt>8))\n"
8071 msgstr ""
8072
8073 #. type: TP
8074 #: build/C/man2/ptrace.2:553
8075 #, no-wrap
8076 msgid "B<PTRACE_O_TRACEVFORKDONE> (since Linux 2.5.60)"
8077 msgstr ""
8078
8079 #. type: Plain text
8080 #: build/C/man2/ptrace.2:562
8081 msgid ""
8082 "Stop the tracee at the completion of the next B<vfork>(2).  A B<waitpid>(2)  "
8083 "by the tracer will return a I<status> value such that"
8084 msgstr ""
8085
8086 #. type: Plain text
8087 #: build/C/man2/ptrace.2:565
8088 #, no-wrap
8089 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONEE<lt>E<lt>8))\n"
8090 msgstr ""
8091
8092 #. type: Plain text
8093 #: build/C/man2/ptrace.2:569
8094 msgid ""
8095 "The PID of the new process can (since Linux 2.6.18) be retrieved with "
8096 "B<PTRACE_GETEVENTMSG>."
8097 msgstr ""
8098
8099 #. type: TP
8100 #: build/C/man2/ptrace.2:570
8101 #, no-wrap
8102 msgid "B<PTRACE_GETEVENTMSG> (since Linux 2.5.46)"
8103 msgstr ""
8104
8105 #. type: Plain text
8106 #: build/C/man2/ptrace.2:590
8107 msgid ""
8108 "Retrieve a message (as an I<unsigned long>)  about the ptrace event that "
8109 "just happened, placing it at the address I<data> in the tracer.  For "
8110 "B<PTRACE_EVENT_EXIT>, this is the tracee's exit status.  For "
8111 "B<PTRACE_EVENT_FORK>, B<PTRACE_EVENT_VFORK>, B<PTRACE_EVENT_VFORK_DONE>, and "
8112 "B<PTRACE_EVENT_CLONE>, this is the PID of the new process.  (I<addr> is "
8113 "ignored.)"
8114 msgstr ""
8115
8116 #. type: TP
8117 #: build/C/man2/ptrace.2:590
8118 #, no-wrap
8119 msgid "B<PTRACE_CONT>"
8120 msgstr ""
8121
8122 #. type: Plain text
8123 #: build/C/man2/ptrace.2:602
8124 msgid ""
8125 "Restart the stopped tracee process.  If I<data> is nonzero, it is "
8126 "interpreted as the number of a signal to be delivered to the tracee; "
8127 "otherwise, no signal is delivered.  Thus, for example, the tracer can "
8128 "control whether a signal sent to the tracee is delivered or not.  (I<addr> "
8129 "is ignored.)"
8130 msgstr ""
8131
8132 #. type: TP
8133 #: build/C/man2/ptrace.2:602
8134 #, no-wrap
8135 msgid "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>"
8136 msgstr ""
8137
8138 #. type: Plain text
8139 #: build/C/man2/ptrace.2:626
8140 msgid ""
8141 "Restart the stopped tracee as for B<PTRACE_CONT>, but arrange for the tracee "
8142 "to be stopped at the next entry to or exit from a system call, or after "
8143 "execution of a single instruction, respectively.  (The tracee will also, as "
8144 "usual, be stopped upon receipt of a signal.)  From the tracer's perspective, "
8145 "the tracee will appear to have been stopped by receipt of a B<SIGTRAP>.  So, "
8146 "for B<PTRACE_SYSCALL>, for example, the idea is to inspect the arguments to "
8147 "the system call at the first stop, then do another B<PTRACE_SYSCALL> and "
8148 "inspect the return value of the system call at the second stop.  The I<data> "
8149 "argument is treated as for B<PTRACE_CONT>.  (I<addr> is ignored.)"
8150 msgstr ""
8151
8152 #. type: TP
8153 #: build/C/man2/ptrace.2:626
8154 #, no-wrap
8155 msgid "B<PTRACE_SYSEMU>, B<PTRACE_SYSEMU_SINGLESTEP> (since Linux 2.6.14)"
8156 msgstr ""
8157
8158 #.  As at 3.7
8159 #. type: Plain text
8160 #: build/C/man2/ptrace.2:647
8161 msgid ""
8162 "For B<PTRACE_SYSEMU>, continue and stop on entry to the next system call, "
8163 "which will not be executed.  For B<PTRACE_SYSEMU_SINGLESTEP>, do the same "
8164 "but also singlestep if not a system call.  This call is used by programs "
8165 "like User Mode Linux that want to emulate all the tracee's system calls.  "
8166 "The I<data> argument is treated as for B<PTRACE_CONT>.  The I<addr> argument "
8167 "is ignored.  These requests are currently supported only on x86."
8168 msgstr ""
8169
8170 #. type: TP
8171 #: build/C/man2/ptrace.2:647
8172 #, no-wrap
8173 msgid "B<PTRACE_LISTEN> (since Linux 3.4)"
8174 msgstr ""
8175
8176 #. type: Plain text
8177 #: build/C/man2/ptrace.2:658
8178 msgid ""
8179 "Restart the stopped tracee, but prevent it from executing.  The resulting "
8180 "state of the tracee is similar to a process which has been stopped by a "
8181 "B<SIGSTOP> (or other stopping signal).  See the \"group-stop\" subsection "
8182 "for additional information.  B<PTRACE_LISTEN> works only on tracees attached "
8183 "by B<PTRACE_SEIZE>."
8184 msgstr ""
8185
8186 #. type: TP
8187 #: build/C/man2/ptrace.2:658
8188 #, no-wrap
8189 msgid "B<PTRACE_KILL>"
8190 msgstr ""
8191
8192 #. type: Plain text
8193 #: build/C/man2/ptrace.2:667
8194 msgid ""
8195 "Send the tracee a B<SIGKILL> to terminate it.  (I<addr> and I<data> are "
8196 "ignored.)"
8197 msgstr ""
8198
8199 #.  [Note from Denys Vlasenko:
8200 #.      deprecation suggested by Oleg Nesterov. He prefers to deprecate it
8201 #.      instead of describing (and needing to support) PTRACE_KILL's quirks.]
8202 #. type: Plain text
8203 #: build/C/man2/ptrace.2:686
8204 msgid ""
8205 "I<This operation is deprecated; do not use it!> Instead, send a B<SIGKILL> "
8206 "directly using B<kill>(2)  or B<tgkill>(2).  The problem with B<PTRACE_KILL> "
8207 "is that it requires the tracee to be in signal-delivery-stop, otherwise it "
8208 "may not work (i.e., may complete successfully but won't kill the tracee).  "
8209 "By contrast, sending a B<SIGKILL> directly has no such limitation."
8210 msgstr ""
8211
8212 #. type: TP
8213 #: build/C/man2/ptrace.2:686
8214 #, no-wrap
8215 msgid "B<PTRACE_INTERRUPT> (since Linux 3.4)"
8216 msgstr ""
8217
8218 #. type: Plain text
8219 #: build/C/man2/ptrace.2:714
8220 msgid ""
8221 "Stop a tracee.  If the tracee is running or sleeping in kernel space and "
8222 "B<PTRACE_SYSCALL> is in effect, the system call is interrupted and "
8223 "syscall-exit-stop is reported.  (The interrupted system call is restarted "
8224 "when the tracee is restarted.)  If the tracee was already stopped by a "
8225 "signal and B<PTRACE_LISTEN> was sent to it, the tracee stops with "
8226 "B<PTRACE_EVENT_STOP> and I<WSTOPSIG(status)> returns the stop signal.  If "
8227 "any other ptrace-stop is generated at the same time (for example, if a "
8228 "signal is sent to the tracee), this ptrace-stop happens.  If none of the "
8229 "above applies (for example, if the tracee is running in user space), it "
8230 "stops with B<PTRACE_EVENT_STOP> with I<WSTOPSIG(status)> == B<SIGTRAP>.  "
8231 "B<PTRACE_INTERRUPT> only works on tracees attached by B<PTRACE_SEIZE>."
8232 msgstr ""
8233
8234 #. type: TP
8235 #: build/C/man2/ptrace.2:714
8236 #, no-wrap
8237 msgid "B<PTRACE_ATTACH>"
8238 msgstr ""
8239
8240 #.  No longer true (removed by Denys Vlasenko, 2011, who remarks:
8241 #.         "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
8242 #.          Basically, it's not true for any Linux in practical use.
8243 #.  ; the behavior of the tracee is as if it had done a
8244 #.  .BR PTRACE_TRACEME .
8245 #.  The calling process actually becomes the parent of the tracee
8246 #.  process for most purposes (e.g., it will receive
8247 #.  notification of tracee events and appears in
8248 #.  .BR ps (1)
8249 #.  output as the tracee's parent), but a
8250 #.  .BR getppid (2)
8251 #.  by the tracee will still return the PID of the original parent.
8252 #. type: Plain text
8253 #: build/C/man2/ptrace.2:742
8254 msgid ""
8255 "Attach to the process specified in I<pid>, making it a tracee of the calling "
8256 "process.  The tracee is sent a B<SIGSTOP>, but will not necessarily have "
8257 "stopped by the completion of this call; use B<waitpid>(2)  to wait for the "
8258 "tracee to stop.  See the \"Attaching and detaching\" subsection for "
8259 "additional information.  (I<addr> and I<data> are ignored.)"
8260 msgstr ""
8261
8262 #. type: TP
8263 #: build/C/man2/ptrace.2:742
8264 #, no-wrap
8265 msgid "B<PTRACE_SEIZE> (since Linux 3.4)"
8266 msgstr ""
8267
8268 #. type: Plain text
8269 #: build/C/man2/ptrace.2:762
8270 msgid ""
8271 "Attach to the process specified in I<pid>, making it a tracee of the calling "
8272 "process.  Unlike B<PTRACE_ATTACH>, B<PTRACE_SEIZE> does not stop the "
8273 "process.  Only a B<PTRACE_SEIZE>d process can accept B<PTRACE_INTERRUPT> and "
8274 "B<PTRACE_LISTEN> commands.  I<addr> must be zero.  I<data> contains a bit "
8275 "mask of ptrace options to activate immediately."
8276 msgstr ""
8277
8278 #. type: TP
8279 #: build/C/man2/ptrace.2:762
8280 #, no-wrap
8281 msgid "B<PTRACE_DETACH>"
8282 msgstr ""
8283
8284 #. type: Plain text
8285 #: build/C/man2/ptrace.2:771
8286 msgid ""
8287 "Restart the stopped tracee as for B<PTRACE_CONT>, but first detach from it.  "
8288 "Under Linux, a tracee can be detached in this way regardless of which method "
8289 "was used to initiate tracing.  (I<addr> is ignored.)"
8290 msgstr ""
8291
8292 #. type: SS
8293 #: build/C/man2/ptrace.2:771
8294 #, no-wrap
8295 msgid "Death under ptrace"
8296 msgstr ""
8297
8298 #. type: Plain text
8299 #: build/C/man2/ptrace.2:780
8300 msgid ""
8301 "When a (possibly multithreaded) process receives a killing signal (one whose "
8302 "disposition is set to B<SIG_DFL> and whose default action is to kill the "
8303 "process), all threads exit.  Tracees report their death to their tracer(s).  "
8304 "Notification of this event is delivered via B<waitpid>(2)."
8305 msgstr ""
8306
8307 #. type: Plain text
8308 #: build/C/man2/ptrace.2:789
8309 msgid ""
8310 "Note that the killing signal will first cause signal-delivery-stop (on one "
8311 "tracee only), and only after it is injected by the tracer (or after it was "
8312 "dispatched to a thread which isn't traced), will death from the signal "
8313 "happen on I<all> tracees within a multithreaded process.  (The term "
8314 "\"signal-delivery-stop\" is explained below.)"
8315 msgstr ""
8316
8317 #. type: Plain text
8318 #: build/C/man2/ptrace.2:801
8319 msgid ""
8320 "B<SIGKILL> does not generate signal-delivery-stop and therefore the tracer "
8321 "can't suppress it.  B<SIGKILL> kills even within system calls "
8322 "(syscall-exit-stop is not generated prior to death by B<SIGKILL>).  The net "
8323 "effect is that B<SIGKILL> always kills the process (all its threads), even "
8324 "if some threads of the process are ptraced."
8325 msgstr ""
8326
8327 #. type: Plain text
8328 #: build/C/man2/ptrace.2:806
8329 msgid ""
8330 "When the tracee calls B<_exit>(2), it reports its death to its tracer.  "
8331 "Other threads are not affected."
8332 msgstr ""
8333
8334 #. type: Plain text
8335 #: build/C/man2/ptrace.2:810
8336 msgid ""
8337 "When any thread executes B<exit_group>(2), every tracee in its thread group "
8338 "reports its death to its tracer."
8339 msgstr ""
8340
8341 #. type: Plain text
8342 #: build/C/man2/ptrace.2:824
8343 msgid ""
8344 "If the B<PTRACE_O_TRACEEXIT> option is on, B<PTRACE_EVENT_EXIT> will happen "
8345 "before actual death.  This applies to exits via B<exit>(2), "
8346 "B<exit_group>(2), and signal deaths (except B<SIGKILL>), and when threads "
8347 "are torn down on B<execve>(2)  in a multithreaded process."
8348 msgstr ""
8349
8350 #. type: Plain text
8351 #: build/C/man2/ptrace.2:849
8352 msgid ""
8353 "The tracer cannot assume that the ptrace-stopped tracee exists.  There are "
8354 "many scenarios when the tracee may die while stopped (such as B<SIGKILL>).  "
8355 "Therefore, the tracer must be prepared to handle an B<ESRCH> error on any "
8356 "ptrace operation.  Unfortunately, the same error is returned if the tracee "
8357 "exists but is not ptrace-stopped (for commands which require a stopped "
8358 "tracee), or if it is not traced by the process which issued the ptrace "
8359 "call.  The tracer needs to keep track of the stopped/running state of the "
8360 "tracee, and interpret B<ESRCH> as \"tracee died unexpectedly\" only if it "
8361 "knows that the tracee has been observed to enter ptrace-stop.  Note that "
8362 "there is no guarantee that I<waitpid(WNOHANG)> will reliably report the "
8363 "tracee's death status if a ptrace operation returned B<ESRCH>.  "
8364 "I<waitpid(WNOHANG)> may return 0 instead.  In other words, the tracee may be "
8365 "\"not yet fully dead\", but already refusing ptrace requests."
8366 msgstr ""
8367
8368 #. type: Plain text
8369 #: build/C/man2/ptrace.2:863
8370 msgid ""
8371 "The tracer can't assume that the tracee I<always> ends its life by reporting "
8372 "I<WIFEXITED(status)> or I<WIFSIGNALED(status)>; there are cases where this "
8373 "does not occur.  For example, if a thread other than thread group leader "
8374 "does an B<execve>(2), it disappears; its PID will never be seen again, and "
8375 "any subsequent ptrace stops will be reported under the thread group leader's "
8376 "PID."
8377 msgstr ""
8378
8379 #. type: SS
8380 #: build/C/man2/ptrace.2:863
8381 #, no-wrap
8382 msgid "Stopped states"
8383 msgstr ""
8384
8385 #. type: Plain text
8386 #: build/C/man2/ptrace.2:885
8387 msgid ""
8388 "A tracee can be in two states: running or stopped.  For the purposes of "
8389 "ptrace, a tracee which is blocked in a system call (such as B<read>(2), "
8390 "B<pause>(2), etc.)  is nevertheless considered to be running, even if the "
8391 "tracee is blocked for a long time.  The state of the tracee after "
8392 "B<PTRACE_LISTEN> is somewhat of a gray area: it is not in any ptrace-stop "
8393 "(ptrace commands won't work on it, and it will deliver B<waitpid>(2)  "
8394 "notifications), but it also may be considered \"stopped\" because it is not "
8395 "executing instructions (is not scheduled), and if it was in group-stop "
8396 "before B<PTRACE_LISTEN>, it will not respond to signals until B<SIGCONT> is "
8397 "received."
8398 msgstr ""
8399
8400 #. type: Plain text
8401 #: build/C/man2/ptrace.2:889
8402 msgid ""
8403 "There are many kinds of states when the tracee is stopped, and in ptrace "
8404 "discussions they are often conflated.  Therefore, it is important to use "
8405 "precise terms."
8406 msgstr ""
8407
8408 #. type: Plain text
8409 #: build/C/man2/ptrace.2:900
8410 msgid ""
8411 "In this manual page, any stopped state in which the tracee is ready to "
8412 "accept ptrace commands from the tracer is called I<ptrace-stop>.  "
8413 "Ptrace-stops can be further subdivided into I<signal-delivery-stop>, "
8414 "I<group-stop>, I<syscall-stop>, and so on.  These stopped states are "
8415 "described in detail below."
8416 msgstr ""
8417
8418 #. type: Plain text
8419 #: build/C/man2/ptrace.2:905
8420 msgid ""
8421 "When the running tracee enters ptrace-stop, it notifies its tracer using "
8422 "B<waitpid>(2)  (or one of the other \"wait\" system calls).  Most of this "
8423 "manual page assumes that the tracer waits with:"
8424 msgstr ""
8425
8426 #. type: Plain text
8427 #: build/C/man2/ptrace.2:907
8428 #, no-wrap
8429 msgid "    pid = waitpid(pid_or_minus_1, &status, __WALL);\n"
8430 msgstr ""
8431
8432 #.  Denys Vlasenko:
8433 #.      Do we require __WALL usage, or will just using 0 be ok? (With 0,
8434 #.      I am not 100% sure there aren't ugly corner cases.) Are the
8435 #.      rules different if user wants to use waitid? Will waitid require
8436 #.      WEXITED?
8437 #. type: Plain text
8438 #: build/C/man2/ptrace.2:919
8439 msgid ""
8440 "Ptrace-stopped tracees are reported as returns with I<pid> greater than 0 "
8441 "and I<WIFSTOPPED(status)> true."
8442 msgstr ""
8443
8444 #. type: Plain text
8445 #: build/C/man2/ptrace.2:927
8446 msgid ""
8447 "The B<__WALL> flag does not include the B<WSTOPPED> and B<WEXITED> flags, "
8448 "but implies their functionality."
8449 msgstr ""
8450
8451 #. type: Plain text
8452 #: build/C/man2/ptrace.2:934
8453 msgid ""
8454 "Setting the B<WCONTINUED> flag when calling B<waitpid>(2)  is not "
8455 "recommended: the \"continued\" state is per-process and consuming it can "
8456 "confuse the real parent of the tracee."
8457 msgstr ""
8458
8459 #. type: Plain text
8460 #: build/C/man2/ptrace.2:942
8461 msgid ""
8462 "Use of the B<WNOHANG> flag may cause B<waitpid>(2)  to return 0 (\"no wait "
8463 "results available yet\")  even if the tracer knows there should be a "
8464 "notification.  Example:"
8465 msgstr ""
8466
8467 #. type: Plain text
8468 #: build/C/man2/ptrace.2:951
8469 #, no-wrap
8470 msgid ""
8471 "    errno = 0;\n"
8472 "    ptrace(PTRACE_CONT, pid, 0L, 0L);\n"
8473 "    if (errno == ESRCH) {\n"
8474 "        /* tracee is dead */\n"
8475 "        r = waitpid(tracee, &status, __WALL | WNOHANG);\n"
8476 "        /* r can still be 0 here! */\n"
8477 "    }\n"
8478 msgstr ""
8479
8480 #. type: Plain text
8481 #: build/C/man2/ptrace.2:974
8482 msgid ""
8483 "The following kinds of ptrace-stops exist: signal-delivery-stops, "
8484 "group-stops, B<PTRACE_EVENT> stops, syscall-stops.  They all are reported by "
8485 "B<waitpid>(2)  with I<WIFSTOPPED(status)> true.  They may be differentiated "
8486 "by examining the value I<statusE<gt>E<gt>8>, and if there is ambiguity in "
8487 "that value, by querying B<PTRACE_GETSIGINFO>.  (Note: the "
8488 "I<WSTOPSIG(status)> macro can't be used to perform this examination, because "
8489 "it returns the value I<(statusE<gt>E<gt>8)\\ &\\ 0xff>.)"
8490 msgstr ""
8491
8492 #. type: SS
8493 #: build/C/man2/ptrace.2:974
8494 #, no-wrap
8495 msgid "Signal-delivery-stop"
8496 msgstr ""
8497
8498 #. type: Plain text
8499 #: build/C/man2/ptrace.2:994
8500 msgid ""
8501 "When a (possibly multithreaded) process receives any signal except "
8502 "B<SIGKILL>, the kernel selects an arbitrary thread which handles the "
8503 "signal.  (If the signal is generated with B<tgkill>(2), the target thread "
8504 "can be explicitly selected by the caller.)  If the selected thread is "
8505 "traced, it enters signal-delivery-stop.  At this point, the signal is not "
8506 "yet delivered to the process, and can be suppressed by the tracer.  If the "
8507 "tracer doesn't suppress the signal, it passes the signal to the tracee in "
8508 "the next ptrace restart request.  This second step of signal delivery is "
8509 "called I<signal injection> in this manual page.  Note that if the signal is "
8510 "blocked, signal-delivery-stop doesn't happen until the signal is unblocked, "
8511 "with the usual exception that B<SIGSTOP> can't be blocked."
8512 msgstr ""
8513
8514 #. type: Plain text
8515 #: build/C/man2/ptrace.2:1008
8516 msgid ""
8517 "Signal-delivery-stop is observed by the tracer as B<waitpid>(2)  returning "
8518 "with I<WIFSTOPPED(status)> true, with the signal returned by "
8519 "I<WSTOPSIG(status)>.  If the signal is B<SIGTRAP>, this may be a different "
8520 "kind of ptrace-stop; see the \"Syscall-stops\" and \"execve\" sections below "
8521 "for details.  If I<WSTOPSIG(status)> returns a stopping signal, this may be "
8522 "a group-stop; see below."
8523 msgstr ""
8524
8525 #. type: SS
8526 #: build/C/man2/ptrace.2:1008
8527 #, no-wrap
8528 msgid "Signal injection and suppression"
8529 msgstr ""
8530
8531 #. type: Plain text
8532 #: build/C/man2/ptrace.2:1011
8533 msgid ""
8534 "After signal-delivery-stop is observed by the tracer, the tracer should "
8535 "restart the tracee with the call"
8536 msgstr ""
8537
8538 #. type: Plain text
8539 #: build/C/man2/ptrace.2:1013
8540 #, no-wrap
8541 msgid "    ptrace(PTRACE_restart, pid, 0, sig)\n"
8542 msgstr ""
8543
8544 #. type: Plain text
8545 #: build/C/man2/ptrace.2:1026
8546 msgid ""
8547 "where B<PTRACE_restart> is one of the restarting ptrace requests.  If I<sig> "
8548 "is 0, then a signal is not delivered.  Otherwise, the signal I<sig> is "
8549 "delivered.  This operation is called I<signal injection> in this manual "
8550 "page, to distinguish it from signal-delivery-stop."
8551 msgstr ""
8552
8553 #. type: Plain text
8554 #: build/C/man2/ptrace.2:1032
8555 msgid ""
8556 "The I<sig> value may be different from the I<WSTOPSIG(status)> value: the "
8557 "tracer can cause a different signal to be injected."
8558 msgstr ""
8559
8560 #. type: Plain text
8561 #: build/C/man2/ptrace.2:1048
8562 msgid ""
8563 "Note that a suppressed signal still causes system calls to return "
8564 "prematurely.  In this case, system calls will be restarted: the tracer will "
8565 "observe the tracee to reexecute the interrupted system call (or "
8566 "B<restart_syscall>(2)  system call for a few system calls which use a "
8567 "different mechanism for restarting) if the tracer uses B<PTRACE_SYSCALL>.  "
8568 "Even system calls (such as B<poll>(2))  which are not restartable after "
8569 "signal are restarted after signal is suppressed; however, kernel bugs exist "
8570 "which cause some system calls to fail with B<EINTR> even though no "
8571 "observable signal is injected to the tracee."
8572 msgstr ""
8573
8574 #. type: Plain text
8575 #: build/C/man2/ptrace.2:1059
8576 msgid ""
8577 "Restarting ptrace commands issued in ptrace-stops other than "
8578 "signal-delivery-stop are not guaranteed to inject a signal, even if I<sig> "
8579 "is nonzero.  No error is reported; a nonzero I<sig> may simply be ignored.  "
8580 "Ptrace users should not try to \"create a new signal\" this way: use "
8581 "B<tgkill>(2)  instead."
8582 msgstr ""
8583
8584 #. type: Plain text
8585 #: build/C/man2/ptrace.2:1066
8586 msgid ""
8587 "The fact that signal injection requests may be ignored when restarting the "
8588 "tracee after ptrace stops that are not signal-delivery-stops is a cause of "
8589 "confusion among ptrace users.  One typical scenario is that the tracer "
8590 "observes group-stop, mistakes it for signal-delivery-stop, restarts the "
8591 "tracee with"
8592 msgstr ""
8593
8594 #. type: Plain text
8595 #: build/C/man2/ptrace.2:1068
8596 #, no-wrap
8597 msgid "    ptrace(PTRACE_restart, pid, 0, stopsig)\n"
8598 msgstr ""
8599
8600 #. type: Plain text
8601 #: build/C/man2/ptrace.2:1074
8602 msgid ""
8603 "with the intention of injecting I<stopsig>, but I<stopsig> gets ignored and "
8604 "the tracee continues to run."
8605 msgstr ""
8606
8607 #. type: Plain text
8608 #: build/C/man2/ptrace.2:1094
8609 msgid ""
8610 "The B<SIGCONT> signal has a side effect of waking up (all threads of)  a "
8611 "group-stopped process.  This side effect happens before "
8612 "signal-delivery-stop.  The tracer can't suppress this side effect (it can "
8613 "only suppress signal injection, which only causes the B<SIGCONT> handler to "
8614 "not be executed in the tracee, if such a handler is installed).  In fact, "
8615 "waking up from group-stop may be followed by signal-delivery-stop for "
8616 "signal(s)  I<other than> B<SIGCONT>, if they were pending when B<SIGCONT> "
8617 "was delivered.  In other words, B<SIGCONT> may be not the first signal "
8618 "observed by the tracee after it was sent."
8619 msgstr ""
8620
8621 #. type: Plain text
8622 #: build/C/man2/ptrace.2:1098
8623 msgid ""
8624 "Stopping signals cause (all threads of) a process to enter group-stop.  This "
8625 "side effect happens after signal injection, and therefore can be suppressed "
8626 "by the tracer."
8627 msgstr ""
8628
8629 #.  In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
8630 #.  there is:
8631 #
8632 #.              /* The debugger continued.  Ignore SIGSTOP.  */
8633 #.              if (signr == SIGSTOP)
8634 #.                      continue;
8635 #. type: Plain text
8636 #: build/C/man2/ptrace.2:1108
8637 msgid "In Linux 2.4 and earlier, the B<SIGSTOP> signal can't be injected."
8638 msgstr ""
8639
8640 #. type: Plain text
8641 #: build/C/man2/ptrace.2:1125
8642 msgid ""
8643 "B<PTRACE_GETSIGINFO> can be used to retrieve a I<siginfo_t> structure which "
8644 "corresponds to the delivered signal.  B<PTRACE_SETSIGINFO> may be used to "
8645 "modify it.  If B<PTRACE_SETSIGINFO> has been used to alter I<siginfo_t>, the "
8646 "I<si_signo> field and the I<sig> parameter in the restarting command must "
8647 "match, otherwise the result is undefined."
8648 msgstr ""
8649
8650 #. type: SS
8651 #: build/C/man2/ptrace.2:1125
8652 #, no-wrap
8653 msgid "Group-stop"
8654 msgstr ""
8655
8656 #. type: Plain text
8657 #: build/C/man2/ptrace.2:1137
8658 msgid ""
8659 "When a (possibly multithreaded) process receives a stopping signal, all "
8660 "threads stop.  If some threads are traced, they enter a group-stop.  Note "
8661 "that the stopping signal will first cause signal-delivery-stop (on one "
8662 "tracee only), and only after it is injected by the tracer (or after it was "
8663 "dispatched to a thread which isn't traced), will group-stop be initiated on "
8664 "I<all> tracees within the multithreaded process.  As usual, every tracee "
8665 "reports its group-stop separately to the corresponding tracer."
8666 msgstr ""
8667
8668 #. type: Plain text
8669 #: build/C/man2/ptrace.2:1146
8670 msgid ""
8671 "Group-stop is observed by the tracer as B<waitpid>(2)  returning with "
8672 "I<WIFSTOPPED(status)> true, with the stopping signal available via "
8673 "I<WSTOPSIG(status)>.  The same result is returned by some other classes of "
8674 "ptrace-stops, therefore the recommended practice is to perform the call"
8675 msgstr ""
8676
8677 #. type: Plain text
8678 #: build/C/man2/ptrace.2:1148
8679 #, no-wrap
8680 msgid "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)\n"
8681 msgstr ""
8682
8683 #. type: Plain text
8684 #: build/C/man2/ptrace.2:1169
8685 msgid ""
8686 "The call can be avoided if the signal is not B<SIGSTOP>, B<SIGTSTP>, "
8687 "B<SIGTTIN>, or B<SIGTTOU>; only these four signals are stopping signals.  If "
8688 "the tracer sees something else, it can't be a group-stop.  Otherwise, the "
8689 "tracer needs to call B<PTRACE_GETSIGINFO>.  If B<PTRACE_GETSIGINFO> fails "
8690 "with B<EINVAL>, then it is definitely a group-stop.  (Other failure codes "
8691 "are possible, such as B<ESRCH> (\"no such process\") if a B<SIGKILL> killed "
8692 "the tracee.)"
8693 msgstr ""
8694
8695 #. type: Plain text
8696 #: build/C/man2/ptrace.2:1179
8697 msgid ""
8698 "If tracee was attached using B<PTRACE_SEIZE>, group-stop is indicated by "
8699 "B<PTRACE_EVENT_STOP>: I<statusE<gt>E<gt>16 == PTRACE_EVENT_STOP>.  This "
8700 "allows detection of group-stops without requiring an extra "
8701 "B<PTRACE_GETSIGINFO> call."
8702 msgstr ""
8703
8704 #. type: Plain text
8705 #: build/C/man2/ptrace.2:1188
8706 msgid ""
8707 "As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until "
8708 "it restarts or kills it, the tracee will not run, and will not send "
8709 "notifications (except B<SIGKILL> death) to the tracer, even if the tracer "
8710 "enters into another B<waitpid>(2)  call."
8711 msgstr ""
8712
8713 #. type: Plain text
8714 #: build/C/man2/ptrace.2:1202
8715 msgid ""
8716 "The kernel behavior described in the previous paragraph causes a problem "
8717 "with transparent handling of stopping signals.  If the tracer restarts the "
8718 "tracee after group-stop, the stopping signal is effectively ignored\\(emthe "
8719 "tracee doesn't remain stopped, it runs.  If the tracer doesn't restart the "
8720 "tracee before entering into the next B<waitpid>(2), future B<SIGCONT> "
8721 "signals will not be reported to the tracer; this would cause the B<SIGCONT> "
8722 "signals to have no effect on the tracee."
8723 msgstr ""
8724
8725 #. type: Plain text
8726 #: build/C/man2/ptrace.2:1213
8727 msgid ""
8728 "Since Linux 3.4, there is a method to overcome this problem: instead of "
8729 "B<PTRACE_CONT>, a B<PTRACE_LISTEN> command can be used to restart a tracee "
8730 "in a way where it does not execute, but waits for a new event which it can "
8731 "report via B<waitpid>(2)  (such as when it is restarted by a B<SIGCONT>)."
8732 msgstr ""
8733
8734 #. type: SS
8735 #: build/C/man2/ptrace.2:1213
8736 #, no-wrap
8737 msgid "PTRACE_EVENT stops"
8738 msgstr ""
8739
8740 #. type: Plain text
8741 #: build/C/man2/ptrace.2:1219
8742 msgid ""
8743 "If the tracer sets B<PTRACE_O_TRACE_*> options, the tracee will enter "
8744 "ptrace-stops called B<PTRACE_EVENT> stops."
8745 msgstr ""
8746
8747 #. type: Plain text
8748 #: build/C/man2/ptrace.2:1233
8749 msgid ""
8750 "B<PTRACE_EVENT> stops are observed by the tracer as B<waitpid>(2)  returning "
8751 "with I<WIFSTOPPED(status)>, and I<WSTOPSIG(status)> returns B<SIGTRAP>.  An "
8752 "additional bit is set in the higher byte of the status word: the value "
8753 "I<statusE<gt>E<gt>8> will be"
8754 msgstr ""
8755
8756 #. type: Plain text
8757 #: build/C/man2/ptrace.2:1235
8758 #, no-wrap
8759 msgid "    (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
8760 msgstr ""
8761
8762 #. type: Plain text
8763 #: build/C/man2/ptrace.2:1237
8764 msgid "The following events exist:"
8765 msgstr ""
8766
8767 #. type: TP
8768 #: build/C/man2/ptrace.2:1237
8769 #, no-wrap
8770 msgid "B<PTRACE_EVENT_VFORK>"
8771 msgstr ""
8772
8773 #. type: Plain text
8774 #: build/C/man2/ptrace.2:1250
8775 msgid ""
8776 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8777 "flag.  When the tracee is continued after this stop, it will wait for child "
8778 "to exit/exec before continuing its execution (in other words, the usual "
8779 "behavior on B<vfork>(2))."
8780 msgstr ""
8781
8782 #. type: TP
8783 #: build/C/man2/ptrace.2:1250
8784 #, no-wrap
8785 msgid "B<PTRACE_EVENT_FORK>"
8786 msgstr ""
8787
8788 #. type: Plain text
8789 #: build/C/man2/ptrace.2:1258
8790 msgid ""
8791 "Stop before return from B<fork>(2)  or B<clone>(2)  with the exit signal set "
8792 "to B<SIGCHLD>."
8793 msgstr ""
8794
8795 #. type: TP
8796 #: build/C/man2/ptrace.2:1258
8797 #, no-wrap
8798 msgid "B<PTRACE_EVENT_CLONE>"
8799 msgstr ""
8800
8801 #. type: Plain text
8802 #: build/C/man2/ptrace.2:1262
8803 msgid "Stop before return from B<clone>(2)."
8804 msgstr ""
8805
8806 #. type: TP
8807 #: build/C/man2/ptrace.2:1262
8808 #, no-wrap
8809 msgid "B<PTRACE_EVENT_VFORK_DONE>"
8810 msgstr ""
8811
8812 #. type: Plain text
8813 #: build/C/man2/ptrace.2:1272
8814 msgid ""
8815 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8816 "flag, but after the child unblocked this tracee by exiting or execing."
8817 msgstr ""
8818
8819 #. type: Plain text
8820 #: build/C/man2/ptrace.2:1278
8821 msgid ""
8822 "For all four stops described above, the stop occurs in the parent (i.e., the "
8823 "tracee), not in the newly created thread.  B<PTRACE_GETEVENTMSG> can be used "
8824 "to retrieve the new thread's ID."
8825 msgstr ""
8826
8827 #. type: TP
8828 #: build/C/man2/ptrace.2:1278
8829 #, no-wrap
8830 msgid "B<PTRACE_EVENT_EXEC>"
8831 msgstr ""
8832
8833 #. type: Plain text
8834 #: build/C/man2/ptrace.2:1285
8835 msgid ""
8836 "Stop before return from B<execve>(2).  Since Linux 3.0, "
8837 "B<PTRACE_GETEVENTMSG> returns the former thread ID."
8838 msgstr ""
8839
8840 #. type: TP
8841 #: build/C/man2/ptrace.2:1285
8842 #, no-wrap
8843 msgid "B<PTRACE_EVENT_EXIT>"
8844 msgstr ""
8845
8846 #. type: Plain text
8847 #: build/C/man2/ptrace.2:1301
8848 msgid ""
8849 "Stop before exit (including death from B<exit_group>(2)), signal death, or "
8850 "exit caused by B<execve>(2)  in a multithreaded process.  "
8851 "B<PTRACE_GETEVENTMSG> returns the exit status.  Registers can be examined "
8852 "(unlike when \"real\" exit happens).  The tracee is still alive; it needs to "
8853 "be B<PTRACE_CONT>ed or B<PTRACE_DETACH>ed to finish exiting."
8854 msgstr ""
8855
8856 #. type: TP
8857 #: build/C/man2/ptrace.2:1301
8858 #, no-wrap
8859 msgid "B<PTRACE_EVENT_STOP>"
8860 msgstr ""
8861
8862 #. type: Plain text
8863 #: build/C/man2/ptrace.2:1313
8864 msgid ""
8865 "Stop induced by B<PTRACE_INTERRUPT> command, or group-stop, or initial "
8866 "ptrace-stop when a new child is attached (only if attached using "
8867 "B<PTRACE_SEIZE>), or B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used."
8868 msgstr ""
8869
8870 #. type: Plain text
8871 #: build/C/man2/ptrace.2:1325
8872 msgid ""
8873 "B<PTRACE_GETSIGINFO> on B<PTRACE_EVENT> stops returns B<SIGTRAP> in "
8874 "I<si_signo>, with I<si_code> set to I<(eventE<lt>E<lt>8)\\ |\\ SIGTRAP>."
8875 msgstr ""
8876
8877 #. type: SS
8878 #: build/C/man2/ptrace.2:1325
8879 #, no-wrap
8880 msgid "Syscall-stops"
8881 msgstr ""
8882
8883 #. type: Plain text
8884 #: build/C/man2/ptrace.2:1338
8885 msgid ""
8886 "If the tracee was restarted by B<PTRACE_SYSCALL>, the tracee enters "
8887 "syscall-enter-stop just prior to entering any system call.  If the tracer "
8888 "restarts the tracee with B<PTRACE_SYSCALL>, the tracee enters "
8889 "syscall-exit-stop when the system call is finished, or if it is interrupted "
8890 "by a signal.  (That is, signal-delivery-stop never happens between "
8891 "syscall-enter-stop and syscall-exit-stop; it happens I<after> "
8892 "syscall-exit-stop.)"
8893 msgstr ""
8894
8895 #. type: Plain text
8896 #: build/C/man2/ptrace.2:1352
8897 msgid ""
8898 "Other possibilities are that the tracee may stop in a B<PTRACE_EVENT> stop, "
8899 "exit (if it entered B<_exit>(2)  or B<exit_group>(2)), be killed by "
8900 "B<SIGKILL>, or die silently (if it is a thread group leader, the "
8901 "B<execve>(2)  happened in another thread, and that thread is not traced by "
8902 "the same tracer; this situation is discussed later)."
8903 msgstr ""
8904
8905 #. type: Plain text
8906 #: build/C/man2/ptrace.2:1367
8907 msgid ""
8908 "Syscall-enter-stop and syscall-exit-stop are observed by the tracer as "
8909 "B<waitpid>(2)  returning with I<WIFSTOPPED(status)> true, and "
8910 "I<WSTOPSIG(status)> giving B<SIGTRAP>.  If the B<PTRACE_O_TRACESYSGOOD> "
8911 "option was set by the tracer, then I<WSTOPSIG(status)> will give the value "
8912 "I<(SIGTRAP\\ |\\ 0x80)>."
8913 msgstr ""
8914
8915 #. type: Plain text
8916 #: build/C/man2/ptrace.2:1373
8917 msgid ""
8918 "Syscall-stops can be distinguished from signal-delivery-stop with B<SIGTRAP> "
8919 "by querying B<PTRACE_GETSIGINFO> for the following cases:"
8920 msgstr ""
8921
8922 #. type: TP
8923 #: build/C/man2/ptrace.2:1373
8924 #, no-wrap
8925 msgid "I<si_code> E<lt>= 0"
8926 msgstr ""
8927
8928 #. type: Plain text
8929 #: build/C/man2/ptrace.2:1385
8930 msgid ""
8931 "B<SIGTRAP> was delivered as a result of a user-space action, for example, a "
8932 "system call (B<tgkill>(2), B<kill>(2), B<sigqueue>(3), etc.), expiration of "
8933 "a POSIX timer, change of state on a POSIX message queue, or completion of an "
8934 "asynchronous I/O request."
8935 msgstr ""
8936
8937 #. type: TP
8938 #: build/C/man2/ptrace.2:1385
8939 #, no-wrap
8940 msgid "I<si_code> == SI_KERNEL (0x80)"
8941 msgstr ""
8942
8943 #. type: Plain text
8944 #: build/C/man2/ptrace.2:1389
8945 msgid "B<SIGTRAP> was sent by the kernel."
8946 msgstr ""
8947
8948 #. type: TP
8949 #: build/C/man2/ptrace.2:1389
8950 #, no-wrap
8951 msgid "I<si_code> == SIGTRAP or I<si_code> == (SIGTRAP|0x80)"
8952 msgstr ""
8953
8954 #. type: Plain text
8955 #: build/C/man2/ptrace.2:1392
8956 msgid "This is a syscall-stop."
8957 msgstr ""
8958
8959 #. type: Plain text
8960 #: build/C/man2/ptrace.2:1397
8961 msgid ""
8962 "However, syscall-stops happen very often (twice per system call), and "
8963 "performing B<PTRACE_GETSIGINFO> for every syscall-stop may be somewhat "
8964 "expensive."
8965 msgstr ""
8966
8967 #. type: Plain text
8968 #: build/C/man2/ptrace.2:1420
8969 msgid ""
8970 "Some architectures allow the cases to be distinguished by examining "
8971 "registers.  For example, on x86, I<rax> == -B<ENOSYS> in "
8972 "syscall-enter-stop.  Since B<SIGTRAP> (like any other signal) always happens "
8973 "I<after> syscall-exit-stop, and at this point I<rax> almost never contains "
8974 "-B<ENOSYS>, the B<SIGTRAP> looks like \"syscall-stop which is not "
8975 "syscall-enter-stop\"; in other words, it looks like a \"stray "
8976 "syscall-exit-stop\" and can be detected this way.  But such detection is "
8977 "fragile and is best avoided."
8978 msgstr ""
8979
8980 #. type: Plain text
8981 #: build/C/man2/ptrace.2:1426
8982 msgid ""
8983 "Using the B<PTRACE_O_TRACESYSGOOD> option is the recommended method to "
8984 "distinguish syscall-stops from other kinds of ptrace-stops, since it is "
8985 "reliable and does not incur a performance penalty."
8986 msgstr ""
8987
8988 #. type: Plain text
8989 #: build/C/man2/ptrace.2:1437
8990 msgid ""
8991 "Syscall-enter-stop and syscall-exit-stop are indistinguishable from each "
8992 "other by the tracer.  The tracer needs to keep track of the sequence of "
8993 "ptrace-stops in order to not misinterpret syscall-enter-stop as "
8994 "syscall-exit-stop or vice versa.  The rule is that syscall-enter-stop is "
8995 "always followed by syscall-exit-stop, B<PTRACE_EVENT> stop or the tracee's "
8996 "death; no other kinds of ptrace-stop can occur in between."
8997 msgstr ""
8998
8999 #. type: Plain text
9000 #: build/C/man2/ptrace.2:1442
9001 msgid ""
9002 "If after syscall-enter-stop, the tracer uses a restarting command other than "
9003 "B<PTRACE_SYSCALL>, syscall-exit-stop is not generated."
9004 msgstr ""
9005
9006 #. type: Plain text
9007 #: build/C/man2/ptrace.2:1454
9008 msgid ""
9009 "B<PTRACE_GETSIGINFO> on syscall-stops returns B<SIGTRAP> in I<si_signo>, "
9010 "with I<si_code> set to B<SIGTRAP> or I<(SIGTRAP|0x80)>."
9011 msgstr ""
9012
9013 #. type: SS
9014 #: build/C/man2/ptrace.2:1454
9015 #, no-wrap
9016 msgid "PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops"
9017 msgstr ""
9018
9019 #
9020 #.  FIXME
9021 #.  document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
9022 #.  PTRACE_SYSEMU_SINGLESTEP
9023 #. type: Plain text
9024 #: build/C/man2/ptrace.2:1460
9025 msgid "[Details of these kinds of stops are yet to be documented.]"
9026 msgstr ""
9027
9028 #. type: SS
9029 #: build/C/man2/ptrace.2:1460
9030 #, no-wrap
9031 msgid "Informational and restarting ptrace commands"
9032 msgstr ""
9033
9034 #. type: Plain text
9035 #: build/C/man2/ptrace.2:1470
9036 msgid ""
9037 "Most ptrace commands (all except B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, "
9038 "B<PTRACE_TRACEME>, B<PTRACE_INTERRUPT>, and B<PTRACE_KILL>)  require the "
9039 "tracee to be in a ptrace-stop, otherwise they fail with B<ESRCH>."
9040 msgstr ""
9041
9042 #. type: Plain text
9043 #: build/C/man2/ptrace.2:1475
9044 msgid ""
9045 "When the tracee is in ptrace-stop, the tracer can read and write data to the "
9046 "tracee using informational commands.  These commands leave the tracee in "
9047 "ptrace-stopped state:"
9048 msgstr ""
9049
9050 #. type: Plain text
9051 #: build/C/man2/ptrace.2:1487
9052 #, no-wrap
9053 msgid ""
9054 "    ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);\n"
9055 "    ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);\n"
9056 "    ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);\n"
9057 "    ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);\n"
9058 "    ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);\n"
9059 "    ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);\n"
9060 "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);\n"
9061 "    ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);\n"
9062 "    ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);\n"
9063 "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
9064 msgstr ""
9065
9066 #. type: Plain text
9067 #: build/C/man2/ptrace.2:1499
9068 msgid ""
9069 "Note that some errors are not reported.  For example, setting signal "
9070 "information (I<siginfo>)  may have no effect in some ptrace-stops, yet the "
9071 "call may succeed (return 0 and not set I<errno>); querying "
9072 "B<PTRACE_GETEVENTMSG> may succeed and return some random value if current "
9073 "ptrace-stop is not documented as returning a meaningful event message."
9074 msgstr ""
9075
9076 #. type: Plain text
9077 #: build/C/man2/ptrace.2:1501
9078 msgid "The call"
9079 msgstr ""
9080
9081 #. type: Plain text
9082 #: build/C/man2/ptrace.2:1503
9083 #, no-wrap
9084 msgid "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
9085 msgstr ""
9086
9087 #. type: Plain text
9088 #: build/C/man2/ptrace.2:1512
9089 msgid ""
9090 "affects one tracee.  The tracee's current flags are replaced.  Flags are "
9091 "inherited by new tracees created and \"auto-attached\" via active "
9092 "B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or B<PTRACE_O_TRACECLONE> "
9093 "options."
9094 msgstr ""
9095
9096 #. type: Plain text
9097 #: build/C/man2/ptrace.2:1515
9098 msgid ""
9099 "Another group of commands makes the ptrace-stopped tracee run.  They have "
9100 "the form:"
9101 msgstr ""
9102
9103 #. type: Plain text
9104 #: build/C/man2/ptrace.2:1517
9105 #, no-wrap
9106 msgid "    ptrace(cmd, pid, 0, sig);\n"
9107 msgstr ""
9108
9109 #. type: Plain text
9110 #: build/C/man2/ptrace.2:1538
9111 msgid ""
9112 "where I<cmd> is B<PTRACE_CONT>, B<PTRACE_LISTEN>, B<PTRACE_DETACH>, "
9113 "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>, B<PTRACE_SYSEMU>, or "
9114 "B<PTRACE_SYSEMU_SINGLESTEP>.  If the tracee is in signal-delivery-stop, "
9115 "I<sig> is the signal to be injected (if it is nonzero).  Otherwise, I<sig> "
9116 "may be ignored.  (When restarting a tracee from a ptrace-stop other than "
9117 "signal-delivery-stop, recommended practice is to always pass 0 in I<sig>.)"
9118 msgstr ""
9119
9120 #. type: SS
9121 #: build/C/man2/ptrace.2:1538
9122 #, no-wrap
9123 msgid "Attaching and detaching"
9124 msgstr ""
9125
9126 #. type: Plain text
9127 #: build/C/man2/ptrace.2:1540
9128 msgid "A thread can be attached to the tracer using the call"
9129 msgstr ""
9130
9131 #. type: Plain text
9132 #: build/C/man2/ptrace.2:1542
9133 #, no-wrap
9134 msgid "    ptrace(PTRACE_ATTACH, pid, 0, 0);\n"
9135 msgstr ""
9136
9137 #. type: Plain text
9138 #: build/C/man2/ptrace.2:1544 build/C/man2/ptrace.2:2047
9139 msgid "or"
9140 msgstr ""
9141
9142 #. type: Plain text
9143 #: build/C/man2/ptrace.2:1546
9144 #, no-wrap
9145 msgid "    ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);\n"
9146 msgstr ""
9147
9148 #
9149 #.  FIXME: Describe how to attach to a thread which is already
9150 #.         group-stopped.
9151 #. type: Plain text
9152 #: build/C/man2/ptrace.2:1571
9153 msgid ""
9154 "B<PTRACE_ATTACH> sends B<SIGSTOP> to this thread.  If the tracer wants this "
9155 "B<SIGSTOP> to have no effect, it needs to suppress it.  Note that if other "
9156 "signals are concurrently sent to this thread during attach, the tracer may "
9157 "see the tracee enter signal-delivery-stop with other signal(s) first! The "
9158 "usual practice is to reinject these signals until B<SIGSTOP> is seen, then "
9159 "suppress B<SIGSTOP> injection.  The design bug here is that a ptrace attach "
9160 "and a concurrently delivered B<SIGSTOP> may race and the concurrent "
9161 "B<SIGSTOP> may be lost."
9162 msgstr ""
9163
9164 #. type: Plain text
9165 #: build/C/man2/ptrace.2:1578
9166 msgid ""
9167 "Since attaching sends B<SIGSTOP> and the tracer usually suppresses it, this "
9168 "may cause a stray B<EINTR> return from the currently executing system call "
9169 "in the tracee, as described in the \"Signal injection and suppression\" "
9170 "section."
9171 msgstr ""
9172
9173 #. type: Plain text
9174 #: build/C/man2/ptrace.2:1590
9175 msgid ""
9176 "Since Linux 3.4, B<PTRACE_SEIZE> can be used instead of B<PTRACE_ATTACH>.  "
9177 "B<PTRACE_SEIZE> does not stop the attached process.  If you need to stop it "
9178 "after attach (or at any other time) without sending it any signals, use "
9179 "B<PTRACE_INTERRUPT> command."
9180 msgstr ""
9181
9182 #. type: Plain text
9183 #: build/C/man2/ptrace.2:1592
9184 msgid "The request"
9185 msgstr ""
9186
9187 #. type: Plain text
9188 #: build/C/man2/ptrace.2:1594
9189 #, no-wrap
9190 msgid "    ptrace(PTRACE_TRACEME, 0, 0, 0);\n"
9191 msgstr ""
9192
9193 #. type: Plain text
9194 #: build/C/man2/ptrace.2:1600
9195 msgid ""
9196 "turns the calling thread into a tracee.  The thread continues to run "
9197 "(doesn't enter ptrace-stop).  A common practice is to follow the "
9198 "B<PTRACE_TRACEME> with"
9199 msgstr ""
9200
9201 #. type: Plain text
9202 #: build/C/man2/ptrace.2:1602
9203 #, no-wrap
9204 msgid "    raise(SIGSTOP);\n"
9205 msgstr ""
9206
9207 #. type: Plain text
9208 #: build/C/man2/ptrace.2:1605
9209 msgid ""
9210 "and allow the parent (which is our tracer now) to observe our "
9211 "signal-delivery-stop."
9212 msgstr ""
9213
9214 #. type: Plain text
9215 #: build/C/man2/ptrace.2:1629
9216 msgid ""
9217 "If the B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or "
9218 "B<PTRACE_O_TRACECLONE> options are in effect, then children created by, "
9219 "respectively, B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> flag, "
9220 "B<fork>(2)  or B<clone>(2)  with the exit signal set to B<SIGCHLD>, and "
9221 "other kinds of B<clone>(2), are automatically attached to the same tracer "
9222 "which traced their parent.  B<SIGSTOP> is delivered to the children, causing "
9223 "them to enter signal-delivery-stop after they exit the system call which "
9224 "created them."
9225 msgstr ""
9226
9227 #. type: Plain text
9228 #: build/C/man2/ptrace.2:1631
9229 msgid "Detaching of the tracee is performed by:"
9230 msgstr ""
9231
9232 #. type: Plain text
9233 #: build/C/man2/ptrace.2:1633
9234 #, no-wrap
9235 msgid "    ptrace(PTRACE_DETACH, pid, 0, sig);\n"
9236 msgstr ""
9237
9238 #. type: Plain text
9239 #: build/C/man2/ptrace.2:1641
9240 msgid ""
9241 "B<PTRACE_DETACH> is a restarting operation; therefore it requires the tracee "
9242 "to be in ptrace-stop.  If the tracee is in signal-delivery-stop, a signal "
9243 "can be injected.  Otherwise, the I<sig> parameter may be silently ignored."
9244 msgstr ""
9245
9246 #.  FIXME: Describe how to detach from a group-stopped tracee so that it
9247 #.         doesn't run, but continues to wait for SIGCONT.
9248 #. type: Plain text
9249 #: build/C/man2/ptrace.2:1665
9250 msgid ""
9251 "If the tracee is running when the tracer wants to detach it, the usual "
9252 "solution is to send B<SIGSTOP> (using B<tgkill>(2), to make sure it goes to "
9253 "the correct thread), wait for the tracee to stop in signal-delivery-stop for "
9254 "B<SIGSTOP> and then detach it (suppressing B<SIGSTOP> injection).  A design "
9255 "bug is that this can race with concurrent B<SIGSTOP>s.  Another complication "
9256 "is that the tracee may enter other ptrace-stops and needs to be restarted "
9257 "and waited for again, until B<SIGSTOP> is seen.  Yet another complication is "
9258 "to be sure that the tracee is not already ptrace-stopped, because no signal "
9259 "delivery happens while it is\\(emnot even B<SIGSTOP>."
9260 msgstr ""
9261
9262 #. type: Plain text
9263 #: build/C/man2/ptrace.2:1673
9264 msgid ""
9265 "If the tracer dies, all tracees are automatically detached and restarted, "
9266 "unless they were in group-stop.  Handling of restart from group-stop is "
9267 "currently buggy, but the \"as planned\" behavior is to leave tracee stopped "
9268 "and waiting for B<SIGCONT>.  If the tracee is restarted from "
9269 "signal-delivery-stop, the pending signal is injected."
9270 msgstr ""
9271
9272 #. type: SS
9273 #: build/C/man2/ptrace.2:1673
9274 #, no-wrap
9275 msgid "execve(2) under ptrace"
9276 msgstr ""
9277
9278 #.  clone(2) CLONE_THREAD says:
9279 #.      If  any  of the threads in a thread group performs an execve(2),
9280 #.      then all threads other than the thread group leader are terminated,
9281 #.      and the new program is executed in the thread group leader.
9282 #
9283 #.  In kernel 3.1 sources, see fs/exec.c::de_thread()
9284 #. type: Plain text
9285 #: build/C/man2/ptrace.2:1692
9286 msgid ""
9287 "When one thread in a multithreaded process calls B<execve>(2), the kernel "
9288 "destroys all other threads in the process, and resets the thread ID of the "
9289 "execing thread to the thread group ID (process ID).  (Or, to put things "
9290 "another way, when a multithreaded process does an B<execve>(2), at "
9291 "completion of the call, it appears as though the B<execve>(2)  occurred in "
9292 "the thread group leader, regardless of which thread did the B<execve>(2).)  "
9293 "This resetting of the thread ID looks very confusing to tracers:"
9294 msgstr ""
9295
9296 #. type: Plain text
9297 #: build/C/man2/ptrace.2:1702
9298 msgid ""
9299 "All other threads stop in B<PTRACE_EVENT_EXIT> stop, if the "
9300 "B<PTRACE_O_TRACEEXIT> option was turned on.  Then all other threads except "
9301 "the thread group leader report death as if they exited via B<_exit>(2)  with "
9302 "exit code 0."
9303 msgstr ""
9304
9305 #. type: Plain text
9306 #: build/C/man2/ptrace.2:1710
9307 msgid ""
9308 "The execing tracee changes its thread ID while it is in the B<execve>(2).  "
9309 "(Remember, under ptrace, the \"pid\" returned from B<waitpid>(2), or fed "
9310 "into ptrace calls, is the tracee's thread ID.)  That is, the tracee's thread "
9311 "ID is reset to be the same as its process ID, which is the same as the "
9312 "thread group leader's thread ID."
9313 msgstr ""
9314
9315 #. type: Plain text
9316 #: build/C/man2/ptrace.2:1716
9317 msgid ""
9318 "Then a B<PTRACE_EVENT_EXEC> stop happens, if the B<PTRACE_O_TRACEEXEC> "
9319 "option was turned on."
9320 msgstr ""
9321
9322 #. type: Plain text
9323 #: build/C/man2/ptrace.2:1737
9324 msgid ""
9325 "If the thread group leader has reported its B<PTRACE_EVENT_EXIT> stop by "
9326 "this time, it appears to the tracer that the dead thread leader \"reappears "
9327 "from nowhere\".  (Note: the thread group leader does not report death via "
9328 "I<WIFEXITED(status)> until there is at least one other live thread.  This "
9329 "eliminates the possibility that the tracer will see it dying and then "
9330 "reappearing.)  If the thread group leader was still alive, for the tracer "
9331 "this may look as if thread group leader returns from a different system call "
9332 "than it entered, or even \"returned from a system call even though it was "
9333 "not in any system call\".  If the thread group leader was not traced (or was "
9334 "traced by a different tracer), then during B<execve>(2)  it will appear as "
9335 "if it has become a tracee of the tracer of the execing tracee."
9336 msgstr ""
9337
9338 #. type: Plain text
9339 #: build/C/man2/ptrace.2:1740
9340 msgid ""
9341 "All of the above effects are the artifacts of the thread ID change in the "
9342 "tracee."
9343 msgstr ""
9344
9345 #. type: Plain text
9346 #: build/C/man2/ptrace.2:1760
9347 msgid ""
9348 "The B<PTRACE_O_TRACEEXEC> option is the recommended tool for dealing with "
9349 "this situation.  First, it enables B<PTRACE_EVENT_EXEC> stop, which occurs "
9350 "before B<execve>(2)  returns.  In this stop, the tracer can use "
9351 "B<PTRACE_GETEVENTMSG> to retrieve the tracee's former thread ID.  (This "
9352 "feature was introduced in Linux 3.0).  Second, the B<PTRACE_O_TRACEEXEC> "
9353 "option disables legacy B<SIGTRAP> generation on B<execve>(2)."
9354 msgstr ""
9355
9356 #. type: Plain text
9357 #: build/C/man2/ptrace.2:1766
9358 msgid ""
9359 "When the tracer receives B<PTRACE_EVENT_EXEC> stop notification, it is "
9360 "guaranteed that except this tracee and the thread group leader, no other "
9361 "threads from the process are alive."
9362 msgstr ""
9363
9364 #. type: Plain text
9365 #: build/C/man2/ptrace.2:1774
9366 msgid ""
9367 "On receiving the B<PTRACE_EVENT_EXEC> stop notification, the tracer should "
9368 "clean up all its internal data structures describing the threads of this "
9369 "process, and retain only one data structure\\(emone which describes the "
9370 "single still running tracee, with"
9371 msgstr ""
9372
9373 #. type: Plain text
9374 #: build/C/man2/ptrace.2:1776
9375 #, no-wrap
9376 msgid "    thread ID == thread group ID == process ID.\n"
9377 msgstr ""
9378
9379 #. type: Plain text
9380 #: build/C/man2/ptrace.2:1780
9381 msgid "Example: two threads call B<execve>(2)  at the same time:"
9382 msgstr ""
9383
9384 #. type: Plain text
9385 #: build/C/man2/ptrace.2:1791
9386 #, no-wrap
9387 msgid ""
9388 "*** we get syscall-enter-stop in thread 1: **\n"
9389 "PID1 execve(\"/bin/foo\", \"foo\" E<lt>unfinished ...E<gt>\n"
9390 "*** we issue PTRACE_SYSCALL for thread 1 **\n"
9391 "*** we get syscall-enter-stop in thread 2: **\n"
9392 "PID2 execve(\"/bin/bar\", \"bar\" E<lt>unfinished ...E<gt>\n"
9393 "*** we issue PTRACE_SYSCALL for thread 2 **\n"
9394 "*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **\n"
9395 "*** we get syscall-exit-stop for PID0: **\n"
9396 "PID0 E<lt>... execve resumedE<gt> )             = 0\n"
9397 msgstr ""
9398
9399 #. type: Plain text
9400 #: build/C/man2/ptrace.2:1814
9401 msgid ""
9402 "If the B<PTRACE_O_TRACEEXEC> option is I<not> in effect for the execing "
9403 "tracee, the kernel delivers an extra B<SIGTRAP> to the tracee after "
9404 "B<execve>(2)  returns.  This is an ordinary signal (similar to one which can "
9405 "be generated by I<kill -TRAP>), not a special kind of ptrace-stop.  "
9406 "Employing B<PTRACE_GETSIGINFO> for this signal returns I<si_code> set to 0 "
9407 "(I<SI_USER>).  This signal may be blocked by signal mask, and thus may be "
9408 "delivered (much) later."
9409 msgstr ""
9410
9411 #. type: Plain text
9412 #: build/C/man2/ptrace.2:1833
9413 msgid ""
9414 "Usually, the tracer (for example, B<strace>(1))  would not want to show this "
9415 "extra post-execve B<SIGTRAP> signal to the user, and would suppress its "
9416 "delivery to the tracee (if B<SIGTRAP> is set to B<SIG_DFL>, it is a killing "
9417 "signal).  However, determining I<which> B<SIGTRAP> to suppress is not easy.  "
9418 "Setting the B<PTRACE_O_TRACEEXEC> option and thus suppressing this extra "
9419 "B<SIGTRAP> is the recommended approach."
9420 msgstr ""
9421
9422 #. type: SS
9423 #: build/C/man2/ptrace.2:1833
9424 #, no-wrap
9425 msgid "Real parent"
9426 msgstr ""
9427
9428 #. type: Plain text
9429 #: build/C/man2/ptrace.2:1840
9430 msgid ""
9431 "The ptrace API (ab)uses the standard UNIX parent/child signaling over "
9432 "B<waitpid>(2).  This used to cause the real parent of the process to stop "
9433 "receiving several kinds of B<waitpid>(2)  notifications when the child "
9434 "process is traced by some other process."
9435 msgstr ""
9436
9437 #. type: Plain text
9438 #: build/C/man2/ptrace.2:1843
9439 msgid ""
9440 "Many of these bugs have been fixed, but as of Linux 2.6.38 several still "
9441 "exist; see BUGS below."
9442 msgstr ""
9443
9444 #. type: Plain text
9445 #: build/C/man2/ptrace.2:1845
9446 msgid "As of Linux 2.6.38, the following is believed to work correctly:"
9447 msgstr ""
9448
9449 #. type: Plain text
9450 #: build/C/man2/ptrace.2:1853
9451 msgid ""
9452 "exit/death by signal is reported first to the tracer, then, when the tracer "
9453 "consumes the B<waitpid>(2)  result, to the real parent (to the real parent "
9454 "only when the whole multithreaded process exits).  If the tracer and the "
9455 "real parent are the same process, the report is sent only once."
9456 msgstr ""
9457
9458 #. type: Plain text
9459 #: build/C/man2/ptrace.2:1858
9460 msgid ""
9461 "On success, the B<PTRACE_PEEK*> requests return the requested data (but see "
9462 "NOTES), while other requests return zero."
9463 msgstr ""
9464
9465 #. type: Plain text
9466 #: build/C/man2/ptrace.2:1868
9467 msgid ""
9468 "On error, all requests return -1, and I<errno> is set appropriately.  Since "
9469 "the value returned by a successful B<PTRACE_PEEK*> request may be -1, the "
9470 "caller must clear I<errno> before the call, and then check it afterward to "
9471 "determine whether or not an error occurred."
9472 msgstr ""
9473
9474 #. type: Plain text
9475 #: build/C/man2/ptrace.2:1872
9476 msgid "(i386 only) There was an error with allocating or freeing a debug register."
9477 msgstr ""
9478
9479 #. type: Plain text
9480 #: build/C/man2/ptrace.2:1883
9481 msgid ""
9482 "There was an attempt to read from or write to an invalid area in the "
9483 "tracer's or the tracee's memory, probably because the area wasn't mapped or "
9484 "accessible.  Unfortunately, under Linux, different variations of this fault "
9485 "will return B<EIO> or B<EFAULT> more or less arbitrarily."
9486 msgstr ""
9487
9488 #. type: Plain text
9489 #: build/C/man2/ptrace.2:1886
9490 msgid "An attempt was made to set an invalid option."
9491 msgstr ""
9492
9493 #. type: Plain text
9494 #: build/C/man2/ptrace.2:1893
9495 msgid ""
9496 "I<request> is invalid, or an attempt was made to read from or write to an "
9497 "invalid area in the tracer's or the tracee's memory, or there was a "
9498 "word-alignment violation, or an invalid signal was specified during a "
9499 "restart request."
9500 msgstr ""
9501
9502 #. type: Plain text
9503 #: build/C/man2/ptrace.2:1906
9504 msgid ""
9505 "The specified process cannot be traced.  This could be because the tracer "
9506 "has insufficient privileges (the required capability is B<CAP_SYS_PTRACE>); "
9507 "unprivileged processes cannot trace processes that they cannot send signals "
9508 "to or those running set-user-ID/set-group-ID programs, for obvious reasons.  "
9509 "Alternatively, the process may already be being traced, or (on kernels "
9510 "before 2.6.26) be B<init>(8)  (PID 1)."
9511 msgstr ""
9512
9513 #. type: Plain text
9514 #: build/C/man2/ptrace.2:1911
9515 msgid ""
9516 "The specified process does not exist, or is not currently being traced by "
9517 "the caller, or is not stopped (for requests that require a stopped tracee)."
9518 msgstr ""
9519
9520 #. type: Plain text
9521 #: build/C/man2/ptrace.2:1913
9522 msgid "SVr4, 4.3BSD."
9523 msgstr ""
9524
9525 #. type: Plain text
9526 #: build/C/man2/ptrace.2:1928
9527 msgid ""
9528 "Although arguments to B<ptrace>()  are interpreted according to the "
9529 "prototype given, glibc currently declares B<ptrace>()  as a variadic "
9530 "function with only the I<request> argument fixed.  It is recommended to "
9531 "always supply four arguments, even if the requested operation does not use "
9532 "them, setting unused/ignored arguments to I<0L> or I<(void\\ *)\\ 0>."
9533 msgstr ""
9534
9535 #. type: Plain text
9536 #: build/C/man2/ptrace.2:1940
9537 msgid ""
9538 "At the system call level, the B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>, and "
9539 "B<PTRACE_PEEKUSER> requests have a different API: they store the result at "
9540 "the address specified by the I<data> parameter, and the return value is the "
9541 "error flag.  The glibc wrapper function provides the API given in "
9542 "DESCRIPTION above, with the result being returned via the function return "
9543 "value."
9544 msgstr ""
9545
9546 #.  See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
9547 #. type: Plain text
9548 #: build/C/man2/ptrace.2:1945
9549 msgid ""
9550 "In Linux kernels before 2.6.26, B<init>(8), the process with PID 1, may not "
9551 "be traced."
9552 msgstr ""
9553
9554 #.  See http://lkml.org/lkml/2008/5/8/375
9555 #. type: Plain text
9556 #: build/C/man2/ptrace.2:1952
9557 msgid ""
9558 "The layout of the contents of memory and the USER area are quite "
9559 "operating-system- and architecture-specific.  The offset supplied, and the "
9560 "data returned, might not entirely match with the definition of I<struct "
9561 "user>."
9562 msgstr ""
9563
9564 #. type: Plain text
9565 #: build/C/man2/ptrace.2:1955
9566 msgid ""
9567 "The size of a \"word\" is determined by the operating-system variant (e.g., "
9568 "for 32-bit Linux it is 32 bits)."
9569 msgstr ""
9570
9571 #. type: Plain text
9572 #: build/C/man2/ptrace.2:1963
9573 msgid ""
9574 "This page documents the way the B<ptrace>()  call works currently in Linux.  "
9575 "Its behavior differs significantly on other flavors of UNIX.  In any case, "
9576 "use of B<ptrace>()  is highly specific to the operating system and "
9577 "architecture."
9578 msgstr ""
9579
9580 #. type: Plain text
9581 #: build/C/man2/ptrace.2:1974
9582 msgid ""
9583 "On hosts with 2.6 kernel headers, B<PTRACE_SETOPTIONS> is declared with a "
9584 "different value than the one for 2.4.  This leads to applications compiled "
9585 "with 2.6 kernel headers failing when run on 2.4 kernels.  This can be worked "
9586 "around by redefining B<PTRACE_SETOPTIONS> to B<PTRACE_OLDSETOPTIONS>, if "
9587 "that is defined."
9588 msgstr ""
9589
9590 #. type: Plain text
9591 #: build/C/man2/ptrace.2:1977
9592 msgid ""
9593 "Group-stop notifications are sent to the tracer, but not to real parent.  "
9594 "Last confirmed on 2.6.38.6."
9595 msgstr ""
9596
9597 #.  Note from Denys Vlasenko:
9598 #.      Here "exits" means any kind of death - _exit, exit_group,
9599 #.      signal death. Signal death and exit_group cases are trivial,
9600 #.      though: since signal death and exit_group kill all other threads
9601 #.      too, "until all other threads exit" thing happens rather soon
9602 #.      in these cases. Therefore, only _exit presents observably
9603 #.      puzzling behavior to ptrace users: thread leader _exit's,
9604 #.      but WIFEXITED isn't reported! We are trying to explain here
9605 #.      why it is so.
9606 #.   FIXME: ^^^ need to test/verify this scenario
9607 #. type: Plain text
9608 #: build/C/man2/ptrace.2:2008
9609 msgid ""
9610 "If a thread group leader is traced and exits by calling B<_exit>(2), a "
9611 "B<PTRACE_EVENT_EXIT> stop will happen for it (if requested), but the "
9612 "subsequent B<WIFEXITED> notification will not be delivered until all other "
9613 "threads exit.  As explained above, if one of other threads calls "
9614 "B<execve>(2), the death of the thread group leader will I<never> be "
9615 "reported.  If the execed thread is not traced by this tracer, the tracer "
9616 "will never know that B<execve>(2)  happened.  One possible workaround is to "
9617 "B<PTRACE_DETACH> the thread group leader instead of restarting it in this "
9618 "case.  Last confirmed on 2.6.38.6."
9619 msgstr ""
9620
9621 #. type: Plain text
9622 #: build/C/man2/ptrace.2:2018
9623 msgid ""
9624 "A B<SIGKILL> signal may still cause a B<PTRACE_EVENT_EXIT> stop before "
9625 "actual signal death.  This may be changed in the future; B<SIGKILL> is meant "
9626 "to always immediately kill tasks even under ptrace.  Last confirmed on "
9627 "2.6.38.6."
9628 msgstr ""
9629
9630 #. type: Plain text
9631 #: build/C/man2/ptrace.2:2036
9632 msgid ""
9633 "Some system calls return with B<EINTR> if a signal was sent to a tracee, but "
9634 "delivery was suppressed by the tracer.  (This is very typical operation: it "
9635 "is usually done by debuggers on every attach, in order to not introduce a "
9636 "bogus B<SIGSTOP>).  As of Linux 3.2.9, the following system calls are "
9637 "affected (this list is likely incomplete): B<epoll_wait>(2), and B<read>(2)  "
9638 "from an B<inotify>(7)  file descriptor.  The usual symptom of this bug is "
9639 "that when you attach to a quiescent process with the command"
9640 msgstr ""
9641
9642 #. type: Plain text
9643 #: build/C/man2/ptrace.2:2038
9644 #, no-wrap
9645 msgid "    strace -p E<lt>process-IDE<gt>\n"
9646 msgstr ""
9647
9648 #. type: Plain text
9649 #: build/C/man2/ptrace.2:2041
9650 msgid "then, instead of the usual and expected one-line output such as"
9651 msgstr ""
9652
9653 #. type: Plain text
9654 #: build/C/man2/ptrace.2:2044
9655 #, no-wrap
9656 msgid "    restart_syscall(E<lt>... resuming interrupted call ...E<gt>_\n"
9657 msgstr ""
9658
9659 #. type: Plain text
9660 #: build/C/man2/ptrace.2:2050
9661 #, no-wrap
9662 msgid "    select(6, [5], NULL, [5], NULL_\n"
9663 msgstr ""
9664
9665 #. type: Plain text
9666 #: build/C/man2/ptrace.2:2054
9667 msgid ""
9668 "('_' denotes the cursor position), you observe more than one line.  For "
9669 "example:"
9670 msgstr ""
9671
9672 #. type: Plain text
9673 #: build/C/man2/ptrace.2:2058
9674 #, no-wrap
9675 msgid ""
9676 "    clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0\n"
9677 "    epoll_wait(4,_\n"
9678 msgstr ""
9679
9680 #. type: Plain text
9681 #: build/C/man2/ptrace.2:2079
9682 msgid ""
9683 "What is not visible here is that the process was blocked in B<epoll_wait>(2)  "
9684 "before B<strace>(1)  has attached to it.  Attaching caused B<epoll_wait>(2)  "
9685 "to return to user space with the error B<EINTR>.  In this particular case, "
9686 "the program reacted to B<EINTR> by checking the current time, and then "
9687 "executing B<epoll_wait>(2)  again.  (Programs which do not expect such "
9688 "\"stray\" B<EINTR> errors may behave in an unintended way upon an "
9689 "B<strace>(1)  attach.)"
9690 msgstr ""
9691
9692 #. type: Plain text
9693 #: build/C/man2/ptrace.2:2093
9694 msgid ""
9695 "B<gdb>(1), B<strace>(1), B<clone>(2), B<execve>(2), B<fork>(2), "
9696 "B<gettid>(2), B<sigaction>(2), B<tgkill>(2), B<vfork>(2), B<waitpid>(2), "
9697 "B<exec>(3), B<capabilities>(7), B<signal>(7)"
9698 msgstr ""
9699
9700 #. type: TH
9701 #: build/C/man2/quotactl.2:27
9702 #, no-wrap
9703 msgid "QUOTACTL"
9704 msgstr ""
9705
9706 #. type: TH
9707 #: build/C/man2/quotactl.2:27
9708 #, no-wrap
9709 msgid "2010-06-16"
9710 msgstr ""
9711
9712 #. type: Plain text
9713 #: build/C/man2/quotactl.2:30
9714 msgid "quotactl - manipulate disk quotas"
9715 msgstr ""
9716
9717 #. type: Plain text
9718 #: build/C/man2/quotactl.2:34
9719 #, no-wrap
9720 msgid ""
9721 "B<#include E<lt>sys/quota.hE<gt>>\n"
9722 "B<#include E<lt>xfs/xqm.hE<gt>>\n"
9723 msgstr ""
9724
9725 #. type: Plain text
9726 #: build/C/man2/quotactl.2:37
9727 #, no-wrap
9728 msgid ""
9729 "B<int quotactl(int >I<cmd>B<, const char *>I<special>B<, int >I<id>B<, "
9730 "caddr_t >I<addr>B<);>\n"
9731 msgstr ""
9732
9733 #. type: Plain text
9734 #: build/C/man2/quotactl.2:49
9735 msgid ""
9736 "The quota system can be used to set per-user and per-group limits on the "
9737 "amount of disk space used on a filesystem.  For each user and/or group, a "
9738 "soft limit and a hard limit can be set for each filesystem.  The hard limit "
9739 "can't be exceeded.  The soft limit can be exceeded, but warnings will "
9740 "ensue.  Moreover, the user can't exceed the soft limit for more than one "
9741 "week (by default) at a time; after this time, the soft limit counts as a "
9742 "hard limit."
9743 msgstr ""
9744
9745 #. type: Plain text
9746 #: build/C/man2/quotactl.2:74
9747 msgid ""
9748 "The B<quotactl>()  call manipulates disk quotas.  The I<cmd> argument "
9749 "indicates a command to be applied to the user or group ID specified in "
9750 "I<id>.  To initialize the I<cmd> argument, use the I<QCMD(subcmd, type)> "
9751 "macro.  The I<type> value is either B<USRQUOTA>, for user quotas, or "
9752 "B<GRPQUOTA>, for group quotas.  The I<subcmd> value is described below."
9753 msgstr ""
9754
9755 #. type: Plain text
9756 #: build/C/man2/quotactl.2:79
9757 msgid ""
9758 "The I<special> argument is a pointer to a null-terminated string containing "
9759 "the pathname of the (mounted) block special device for the filesystem being "
9760 "manipulated."
9761 msgstr ""
9762
9763 #. type: Plain text
9764 #: build/C/man2/quotactl.2:87
9765 msgid ""
9766 "The I<addr> argument is the address of an optional, command-specific, data "
9767 "structure that is copied in or out of the system.  The interpretation of "
9768 "I<addr> is given with each command below."
9769 msgstr ""
9770
9771 #. type: Plain text
9772 #: build/C/man2/quotactl.2:91
9773 msgid "The I<subcmd> value is one of the following:"
9774 msgstr ""
9775
9776 #. type: TP
9777 #: build/C/man2/quotactl.2:91
9778 #, no-wrap
9779 msgid "B<Q_QUOTAON>"
9780 msgstr ""
9781
9782 #. type: Plain text
9783 #: build/C/man2/quotactl.2:98
9784 msgid ""
9785 "Turn on quotas for a filesystem.  The I<id> argument is the identification "
9786 "number of the quota format to be used.  Currently, there are three supported "
9787 "quota formats:"
9788 msgstr ""
9789
9790 #. type: TP
9791 #: build/C/man2/quotactl.2:99
9792 #, no-wrap
9793 msgid "B<QFMT_VFS_OLD>"
9794 msgstr ""
9795
9796 #. type: Plain text
9797 #: build/C/man2/quotactl.2:102
9798 msgid "The original quota format."
9799 msgstr ""
9800
9801 #. type: TP
9802 #: build/C/man2/quotactl.2:102
9803 #, no-wrap
9804 msgid "B<QFMT_VFS_V0>"
9805 msgstr ""
9806
9807 #. type: Plain text
9808 #: build/C/man2/quotactl.2:106
9809 msgid ""
9810 "The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and "
9811 "quota limits up to 2^42 bytes and 2^32 inodes."
9812 msgstr ""
9813
9814 #. type: TP
9815 #: build/C/man2/quotactl.2:106
9816 #, no-wrap
9817 msgid "B<QFMT_VFS_V1>"
9818 msgstr ""
9819
9820 #. type: Plain text
9821 #: build/C/man2/quotactl.2:110
9822 msgid ""
9823 "A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^64 "
9824 "bytes and 2^64 inodes."
9825 msgstr ""
9826
9827 #. type: Plain text
9828 #: build/C/man2/quotactl.2:121
9829 msgid ""
9830 "The I<addr> argument points to the pathname of a file containing the quotas "
9831 "for the filesystem.  The quota file must exist; it is normally created with "
9832 "the B<quotacheck>(8)  program.  This operation requires privilege "
9833 "(B<CAP_SYS_ADMIN>)."
9834 msgstr ""
9835
9836 #. type: TP
9837 #: build/C/man2/quotactl.2:121
9838 #, no-wrap
9839 msgid "B<Q_QUOTAOFF>"
9840 msgstr ""
9841
9842 #. type: Plain text
9843 #: build/C/man2/quotactl.2:131
9844 msgid ""
9845 "Turn off quotas for a filesystem.  The I<addr> and I<id> arguments are "
9846 "ignored.  This operation requires privilege (B<CAP_SYS_ADMIN>)."
9847 msgstr ""
9848
9849 #. type: TP
9850 #: build/C/man2/quotactl.2:131
9851 #, no-wrap
9852 msgid "B<Q_GETQUOTA>"
9853 msgstr ""
9854
9855 #. type: Plain text
9856 #: build/C/man2/quotactl.2:142
9857 msgid ""
9858 "Get disk quota limits and current usage for user or group I<id>.  The "
9859 "I<addr> argument is a pointer to a I<dqblk> structure defined in "
9860 "I<E<lt>sys/quota.hE<gt>> as follows:"
9861 msgstr ""
9862
9863 #. type: Plain text
9864 #: build/C/man2/quotactl.2:147 build/C/man2/quotactl.2:234
9865 #, no-wrap
9866 msgid ""
9867 "/* uint64_t is an unsigned 64-bit integer;\n"
9868 "   uint32_t is an unsigned 32-bit integer */\n"
9869 msgstr ""
9870
9871 #. type: Plain text
9872 #: build/C/man2/quotactl.2:167
9873 #, no-wrap
9874 msgid ""
9875 "struct dqblk {          /* Definition since Linux 2.4.22 */\n"
9876 "    uint64_t dqb_bhardlimit;   /* absolute limit on disk\n"
9877 "                                  quota blocks alloc */\n"
9878 "    uint64_t dqb_bsoftlimit;   /* preferred limit on\n"
9879 "                                  disk quota blocks */\n"
9880 "    uint64_t dqb_curspace;     /* current quota block\n"
9881 "                                  count */\n"
9882 "    uint64_t dqb_ihardlimit;   /* maximum number of\n"
9883 "                                  allocated inodes */\n"
9884 "    uint64_t dqb_isoftlimit;   /* preferred inode limit */\n"
9885 "    uint64_t dqb_curinodes;    /* current number of\n"
9886 "                                  allocated inodes */\n"
9887 "    uint64_t dqb_btime;        /* time limit for excessive\n"
9888 "                                  disk use */\n"
9889 "    uint64_t dqb_itime;        /* time limit for excessive\n"
9890 "                                  files */\n"
9891 "    uint32_t dqb_valid;        /* bit mask of QIF_*\n"
9892 "                                  constants */\n"
9893 "};\n"
9894 msgstr ""
9895
9896 #. type: Plain text
9897 #: build/C/man2/quotactl.2:170
9898 #, no-wrap
9899 msgid ""
9900 "/* Flags in dqb_valid that indicate which fields in\n"
9901 "   dqblk structure are valid. */\n"
9902 msgstr ""
9903
9904 #. type: Plain text
9905 #: build/C/man2/quotactl.2:181
9906 #, no-wrap
9907 msgid ""
9908 "#define QIF_BLIMITS   1\n"
9909 "#define QIF_SPACE     2\n"
9910 "#define QIF_ILIMITS   4\n"
9911 "#define QIF_INODES    8\n"
9912 "#define QIF_BTIME     16\n"
9913 "#define QIF_ITIME     32\n"
9914 "#define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)\n"
9915 "#define QIF_USAGE     (QIF_SPACE | QIF_INODES)\n"
9916 "#define QIF_TIMES     (QIF_BTIME | QIF_ITIME)\n"
9917 "#define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)\n"
9918 msgstr ""
9919
9920 #. type: Plain text
9921 #: build/C/man2/quotactl.2:198
9922 msgid ""
9923 "The I<dqb_valid> field is a bit mask that is set to indicate the entries in "
9924 "the I<dqblk> structure that are valid.  Currently, the kernel fills in all "
9925 "entries of the I<dqblk> structure and marks them as valid in the "
9926 "I<dqb_valid> field.  Unprivileged users may retrieve only their own quotas; "
9927 "a privileged user (B<CAP_SYS_ADMIN>)  can retrieve the quotas of any user."
9928 msgstr ""
9929
9930 #. type: TP
9931 #: build/C/man2/quotactl.2:198
9932 #, no-wrap
9933 msgid "B<Q_SETQUOTA>"
9934 msgstr ""
9935
9936 #. type: Plain text
9937 #: build/C/man2/quotactl.2:218
9938 msgid ""
9939 "Set quota information for user or group I<id>, using the information "
9940 "supplied in the I<dqblk> structure pointed to by I<addr>.  The I<dqb_valid> "
9941 "field of the I<dqblk> structure indicates which entries in the structure "
9942 "have been set by the caller.  This operation supersedes the B<Q_SETQLIM> and "
9943 "B<Q_SETUSE> operations in the previous quota interfaces.  This operation "
9944 "requires privilege (B<CAP_SYS_ADMIN>)."
9945 msgstr ""
9946
9947 #. type: TP
9948 #: build/C/man2/quotactl.2:218
9949 #, no-wrap
9950 msgid "B<Q_GETINFO>"
9951 msgstr ""
9952
9953 #. type: Plain text
9954 #: build/C/man2/quotactl.2:229
9955 msgid ""
9956 "Get information (like grace times) about quotafile.  The I<addr> argument "
9957 "should be a pointer to a I<dqinfo> structure.  This structure is defined in "
9958 "I<E<lt>sys/quota.hE<gt>> as follows:"
9959 msgstr ""
9960
9961 #. type: Plain text
9962 #: build/C/man2/quotactl.2:238
9963 #, no-wrap
9964 msgid ""
9965 "struct dqinfo {         /* Defined since kernel 2.4.22 */\n"
9966 "    uint64_t dqi_bgrace;    /* Time before block soft limit\n"
9967 "                               becomes hard limit */\n"
9968 msgstr ""
9969
9970 #. type: Plain text
9971 #: build/C/man2/quotactl.2:245
9972 #, no-wrap
9973 msgid ""
9974 "    uint64_t dqi_igrace;    /* Time before inode soft limit\n"
9975 "                               becomes hard limit */\n"
9976 "    uint32_t dqi_flags;     /* Flags for quotafile\n"
9977 "                               (DQF_*) */\n"
9978 "    uint32_t dqi_valid;\n"
9979 "};\n"
9980 msgstr ""
9981
9982 #. type: Plain text
9983 #: build/C/man2/quotactl.2:247
9984 #, no-wrap
9985 msgid "/* Bits for dqi_flags */\n"
9986 msgstr ""
9987
9988 #. type: Plain text
9989 #: build/C/man2/quotactl.2:249
9990 #, no-wrap
9991 msgid "/* Quota format QFMT_VFS_OLD */\n"
9992 msgstr ""
9993
9994 #. type: Plain text
9995 #: build/C/man2/quotactl.2:251
9996 #, no-wrap
9997 msgid "#define V1_DQF_RSQUASH\t1   /* Root squash enabled */\n"
9998 msgstr ""
9999
10000 #. type: Plain text
10001 #: build/C/man2/quotactl.2:253
10002 #, no-wrap
10003 msgid "/* Other quota formats have no dqi_flags bits defined */\n"
10004 msgstr ""
10005
10006 #. type: Plain text
10007 #: build/C/man2/quotactl.2:256
10008 #, no-wrap
10009 msgid ""
10010 "/* Flags in dqi_valid that indicate which fields in\n"
10011 "   dqinfo structure are valid. */\n"
10012 msgstr ""
10013
10014 #. type: Plain text
10015 #: build/C/man2/quotactl.2:261
10016 #, no-wrap
10017 msgid ""
10018 "# define IIF_BGRACE\t1\n"
10019 "# define IIF_IGRACE\t2\n"
10020 "# define IIF_FLAGS\t4\n"
10021 "# define IIF_ALL        (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)\n"
10022 msgstr ""
10023
10024 #. type: Plain text
10025 #: build/C/man2/quotactl.2:277
10026 msgid ""
10027 "The I<dqi_valid> field in the I<dqinfo> structure indicates the entries in "
10028 "the structure that are valid.  Currently, the kernel fills in all entries of "
10029 "the I<dqinfo> structure and marks them all as valid in the I<dqi_valid> "
10030 "field.  The I<id> argument is ignored."
10031 msgstr ""
10032
10033 #. type: TP
10034 #: build/C/man2/quotactl.2:277
10035 #, no-wrap
10036 msgid "B<Q_SETINFO>"
10037 msgstr ""
10038
10039 #. type: Plain text
10040 #: build/C/man2/quotactl.2:301
10041 msgid ""
10042 "Set information about quotafile.  The I<addr> argument should be a pointer "
10043 "to a I<dqinfo> structure.  The I<dqi_valid> field of the I<dqinfo> structure "
10044 "indicates the entries in the structure that have been set by the caller.  "
10045 "This operation supersedes the B<Q_SETGRACE> and B<Q_SETFLAGS> operations in "
10046 "the previous quota interfaces.  The I<id> argument is ignored.  This "
10047 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10048 msgstr ""
10049
10050 #. type: TP
10051 #: build/C/man2/quotactl.2:301
10052 #, no-wrap
10053 msgid "B<Q_GETFMT>"
10054 msgstr ""
10055
10056 #. type: Plain text
10057 #: build/C/man2/quotactl.2:308
10058 msgid ""
10059 "Get quota format used on the specified filesystem.  The I<addr> argument "
10060 "should be a pointer to a 4-byte buffer where the format number will be "
10061 "stored."
10062 msgstr ""
10063
10064 #. type: TP
10065 #: build/C/man2/quotactl.2:308
10066 #, no-wrap
10067 msgid "B<Q_SYNC>"
10068 msgstr ""
10069
10070 #. type: Plain text
10071 #: build/C/man2/quotactl.2:319
10072 msgid ""
10073 "Update the on-disk copy of quota usages for a filesystem.  If I<special> is "
10074 "NULL, then all filesystems with active quotas are sync'ed.  The I<addr> and "
10075 "I<id> arguments are ignored."
10076 msgstr ""
10077
10078 #. type: TP
10079 #: build/C/man2/quotactl.2:319
10080 #, no-wrap
10081 msgid "B<Q_GETSTATS>"
10082 msgstr ""
10083
10084 #.  Q_GETSTATS was removed in kernel 2.4.22.
10085 #. type: Plain text
10086 #: build/C/man2/quotactl.2:339
10087 msgid ""
10088 "Get statistics and other generic information about the quota subsystem.  The "
10089 "I<addr> argument should be a pointer to a I<dqstats> structure in which data "
10090 "should be stored.  This structure is defined in I<E<lt>sys/quota.hE<gt>>.  "
10091 "The I<special> and I<id> arguments are ignored.  This operation is obsolete "
10092 "and not supported by recent kernels.  Files in I</proc/sys/fs/quota/> carry "
10093 "the information instead."
10094 msgstr ""
10095
10096 #. type: Plain text
10097 #: build/C/man2/quotactl.2:342
10098 msgid ""
10099 "For XFS filesystems making use of the XFS Quota Manager (XQM), the above "
10100 "commands are bypassed and the following commands are used:"
10101 msgstr ""
10102
10103 #. type: TP
10104 #: build/C/man2/quotactl.2:342
10105 #, no-wrap
10106 msgid "B<Q_XQUOTAON>"
10107 msgstr ""
10108
10109 #. type: Plain text
10110 #: build/C/man2/quotactl.2:363
10111 msgid ""
10112 "Turn on quotas for an XFS filesystem.  XFS provides the ability to turn "
10113 "on/off quota limit enforcement with quota accounting.  Therefore, XFS "
10114 "expects I<addr> to be a pointer to an I<unsigned int> that contains either "
10115 "the flags B<XFS_QUOTA_UDQ_ACCT> and/or B<XFS_QUOTA_UDQ_ENFD> (for user "
10116 "quota), or B<XFS_QUOTA_GDQ_ACCT> and/or B<XFS_QUOTA_GDQ_ENFD> (for group "
10117 "quota), as defined in I<E<lt>xfs/xqm.hE<gt>>.  This operation requires "
10118 "privilege (B<CAP_SYS_ADMIN>)."
10119 msgstr ""
10120
10121 #. type: TP
10122 #: build/C/man2/quotactl.2:363
10123 #, no-wrap
10124 msgid "B<Q_XQUOTAOFF>"
10125 msgstr ""
10126
10127 #. type: Plain text
10128 #: build/C/man2/quotactl.2:374
10129 msgid ""
10130 "Turn off quotas for an XFS filesystem.  As with B<Q_QUOTAON>, XFS "
10131 "filesystems expect a pointer to an I<unsigned int> that specifies whether "
10132 "quota accounting and/or limit enforcement need to be turned off.  This "
10133 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10134 msgstr ""
10135
10136 #. type: TP
10137 #: build/C/man2/quotactl.2:374
10138 #, no-wrap
10139 msgid "B<Q_XGETQUOTA>"
10140 msgstr ""
10141
10142 #. type: Plain text
10143 #: build/C/man2/quotactl.2:388
10144 msgid ""
10145 "Get disk quota limits and current usage for user I<id>.  The I<addr> "
10146 "argument is a pointer to an I<fs_disk_quota> structure (defined in "
10147 "I<E<lt>xfs/xqm.hE<gt>>).  Unprivileged users may retrieve only their own "
10148 "quotas; a privileged user (B<CAP_SYS_ADMIN>)  may retrieve the quotas of any "
10149 "user."
10150 msgstr ""
10151
10152 #. type: TP
10153 #: build/C/man2/quotactl.2:388
10154 #, no-wrap
10155 msgid "B<Q_XSETQLIM>"
10156 msgstr ""
10157
10158 #. type: Plain text
10159 #: build/C/man2/quotactl.2:400
10160 msgid ""
10161 "Set disk quota limits for user I<id>.  The I<addr> argument is a pointer to "
10162 "an I<fs_disk_quota> structure (defined in I<E<lt>xfs/xqm.hE<gt>>).  This "
10163 "operation requires privilege (B<CAP_SYS_ADMIN>)."
10164 msgstr ""
10165
10166 #. type: TP
10167 #: build/C/man2/quotactl.2:400
10168 #, no-wrap
10169 msgid "B<Q_XGETQSTAT>"
10170 msgstr ""
10171
10172 #. type: Plain text
10173 #: build/C/man2/quotactl.2:408
10174 msgid ""
10175 "Returns an I<fs_quota_stat> structure containing XFS filesystem-specific "
10176 "quota information.  This is useful for finding out how much space is used to "
10177 "store quota information, and also to get quotaon/off status of a given local "
10178 "XFS filesystem."
10179 msgstr ""
10180
10181 #. type: TP
10182 #: build/C/man2/quotactl.2:408
10183 #, no-wrap
10184 msgid "B<Q_XQUOTARM>"
10185 msgstr ""
10186
10187 #. type: Plain text
10188 #: build/C/man2/quotactl.2:412
10189 msgid ""
10190 "Free the disk space taken by disk quotas.  Quotas must have already been "
10191 "turned off."
10192 msgstr ""
10193
10194 #. type: Plain text
10195 #: build/C/man2/quotactl.2:419
10196 msgid ""
10197 "There is no command equivalent to B<Q_SYNC> for XFS since B<sync>(1)  writes "
10198 "quota information to disk (in addition to the other filesystem metadata that "
10199 "it writes out)."
10200 msgstr ""
10201
10202 #. type: Plain text
10203 #: build/C/man2/quotactl.2:427
10204 msgid ""
10205 "On success, B<quotactl>()  returns 0; on error -1 is returned, and I<errno> "
10206 "is set to indicate the error."
10207 msgstr ""
10208
10209 #. type: Plain text
10210 #: build/C/man2/quotactl.2:434
10211 msgid "I<addr> or I<special> is invalid."
10212 msgstr ""
10213
10214 #. type: Plain text
10215 #: build/C/man2/quotactl.2:440
10216 msgid "I<cmd> or I<type> is invalid."
10217 msgstr ""
10218
10219 #. type: Plain text
10220 #: build/C/man2/quotactl.2:447
10221 msgid "The file specified by I<special> or I<addr> does not exist."
10222 msgstr ""
10223
10224 #. type: Plain text
10225 #: build/C/man2/quotactl.2:452
10226 msgid "The kernel has not been compiled with the B<CONFIG_QUOTA> option."
10227 msgstr ""
10228
10229 #. type: TP
10230 #: build/C/man2/quotactl.2:452
10231 #, no-wrap
10232 msgid "B<ENOTBLK>"
10233 msgstr ""
10234
10235 #. type: Plain text
10236 #: build/C/man2/quotactl.2:456
10237 msgid "I<special> is not a block device."
10238 msgstr ""
10239
10240 #. type: Plain text
10241 #: build/C/man2/quotactl.2:461
10242 msgid ""
10243 "The caller lacked the required privilege (B<CAP_SYS_ADMIN>)  for the "
10244 "specified operation."
10245 msgstr ""
10246
10247 #. type: Plain text
10248 #: build/C/man2/quotactl.2:465
10249 msgid ""
10250 "No disk quota is found for the indicated user.  Quotas have not been turned "
10251 "on for this filesystem."
10252 msgstr ""
10253
10254 #. type: Plain text
10255 #: build/C/man2/quotactl.2:474
10256 msgid "If I<cmd> is B<Q_SETQUOTA>, B<quotactl>()  may also set I<errno> to:"
10257 msgstr ""
10258
10259 #. type: Plain text
10260 #: build/C/man2/quotactl.2:477
10261 msgid "Specified limits are out of range allowed by quota format."
10262 msgstr ""
10263
10264 #. type: Plain text
10265 #: build/C/man2/quotactl.2:486
10266 msgid "If I<cmd> is B<Q_QUOTAON>, B<quotactl>()  may also set I<errno> to:"
10267 msgstr ""
10268
10269 #. type: Plain text
10270 #: build/C/man2/quotactl.2:495
10271 msgid ""
10272 "The quota file pointed to by I<addr> exists, but is not a regular file; or, "
10273 "the quota file pointed to by I<addr> exists, but is not on the filesystem "
10274 "pointed to by I<special>."
10275 msgstr ""
10276
10277 #. type: Plain text
10278 #: build/C/man2/quotactl.2:501
10279 msgid "B<Q_QUOTAON> attempted, but another B<Q_QUOTAON> had already been performed."
10280 msgstr ""
10281
10282 #. type: Plain text
10283 #: build/C/man2/quotactl.2:504
10284 msgid "The quota file is corrupted."
10285 msgstr ""
10286
10287 #. type: Plain text
10288 #: build/C/man2/quotactl.2:507
10289 msgid "Specified quota format was not found."
10290 msgstr ""
10291
10292 #. type: Plain text
10293 #: build/C/man2/quotactl.2:512
10294 msgid "B<quota>(1), B<getrlimit>(2), B<quotacheck>(8), B<quotaon>(8)"
10295 msgstr ""
10296
10297 #. type: TH
10298 #: build/C/man2/sendfile.2:19
10299 #, no-wrap
10300 msgid "SENDFILE"
10301 msgstr ""
10302
10303 #. type: TH
10304 #: build/C/man2/sendfile.2:19
10305 #, no-wrap
10306 msgid "2011-09-14"
10307 msgstr ""
10308
10309 #. type: Plain text
10310 #: build/C/man2/sendfile.2:22
10311 msgid "sendfile - transfer data between file descriptors"
10312 msgstr ""
10313
10314 #. type: Plain text
10315 #: build/C/man2/sendfile.2:24
10316 msgid "B<#include E<lt>sys/sendfile.hE<gt>>"
10317 msgstr ""
10318
10319 #.  The below is too ugly. Comments about glibc versions belong
10320 #.  in the notes, not in the header.
10321 #
10322 #.  .B #include <features.h>
10323 #.  .br
10324 #.  .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
10325 #.  .br
10326 #.  .B #include <sys/sendfile.h>
10327 #.  .br
10328 #.  #else
10329 #.  .br
10330 #.  .B #include <sys/types.h>
10331 #.  .br
10332 #.  .B /* No system prototype before glibc 2.1. */
10333 #.  .br
10334 #.  .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
10335 #.                        offset ", size_t" " count" )
10336 #.  .br
10337 #.  .B #endif
10338 #. type: Plain text
10339 #: build/C/man2/sendfile.2:47
10340 msgid ""
10341 "B<ssize_t sendfile(int>I< out_fd>B<, int>I< in_fd>B<, off_t *>I<offset>B<, "
10342 "size_t>I< count>B<);>"
10343 msgstr ""
10344
10345 #. type: Plain text
10346 #: build/C/man2/sendfile.2:57
10347 msgid ""
10348 "B<sendfile>()  copies data between one file descriptor and another.  Because "
10349 "this copying is done within the kernel, B<sendfile>()  is more efficient "
10350 "than the combination of B<read>(2)  and B<write>(2), which would require "
10351 "transferring data to and from user space."
10352 msgstr ""
10353
10354 #. type: Plain text
10355 #: build/C/man2/sendfile.2:62
10356 msgid ""
10357 "I<in_fd> should be a file descriptor opened for reading and I<out_fd> should "
10358 "be a descriptor opened for writing."
10359 msgstr ""
10360
10361 #. type: Plain text
10362 #: build/C/man2/sendfile.2:83
10363 msgid ""
10364 "If I<offset> is not NULL, then it points to a variable holding the file "
10365 "offset from which B<sendfile>()  will start reading data from I<in_fd>.  "
10366 "When B<sendfile>()  returns, this variable will be set to the offset of the "
10367 "byte following the last byte that was read.  If I<offset> is not NULL, then "
10368 "B<sendfile>()  does not modify the current file offset of I<in_fd>; "
10369 "otherwise the current file offset is adjusted to reflect the number of bytes "
10370 "read from I<in_fd>."
10371 msgstr ""
10372
10373 #. type: Plain text
10374 #: build/C/man2/sendfile.2:90
10375 msgid ""
10376 "If I<offset> is NULL, then data will be read from I<in_fd> starting at the "
10377 "current file offset, and the file offset will be updated by the call."
10378 msgstr ""
10379
10380 #. type: Plain text
10381 #: build/C/man2/sendfile.2:93
10382 msgid "I<count> is the number of bytes to copy between the file descriptors."
10383 msgstr ""
10384
10385 #. type: Plain text
10386 #: build/C/man2/sendfile.2:100
10387 msgid ""
10388 "The I<in_fd> argument must correspond to a file which supports "
10389 "B<mmap>(2)-like operations (i.e., it cannot be a socket)."
10390 msgstr ""
10391
10392 #. type: Plain text
10393 #: build/C/man2/sendfile.2:108
10394 msgid ""
10395 "In Linux kernels before 2.6.33, I<out_fd> must refer to a socket.  Since "
10396 "Linux 2.6.33 it can be any file.  If it is a regular file, then "
10397 "B<sendfile>()  changes the file offset appropriately."
10398 msgstr ""
10399
10400 #. type: Plain text
10401 #: build/C/man2/sendfile.2:115
10402 msgid ""
10403 "If the transfer was successful, the number of bytes written to I<out_fd> is "
10404 "returned.  On error, -1 is returned, and I<errno> is set appropriately."
10405 msgstr ""
10406
10407 #. type: Plain text
10408 #: build/C/man2/sendfile.2:121
10409 msgid ""
10410 "Nonblocking I/O has been selected using B<O_NONBLOCK> and the write would "
10411 "block."
10412 msgstr ""
10413
10414 #. type: Plain text
10415 #: build/C/man2/sendfile.2:125
10416 msgid ""
10417 "The input file was not opened for reading or the output file was not opened "
10418 "for writing."
10419 msgstr ""
10420
10421 #. type: Plain text
10422 #: build/C/man2/sendfile.2:128
10423 msgid "Bad address."
10424 msgstr ""
10425
10426 #. type: Plain text
10427 #: build/C/man2/sendfile.2:134
10428 msgid ""
10429 "Descriptor is not valid or locked, or an B<mmap>(2)-like operation is not "
10430 "available for I<in_fd>."
10431 msgstr ""
10432
10433 #. type: Plain text
10434 #: build/C/man2/sendfile.2:138
10435 msgid "Unspecified error while reading from I<in_fd>."
10436 msgstr ""
10437
10438 #. type: Plain text
10439 #: build/C/man2/sendfile.2:142
10440 msgid "Insufficient memory to read from I<in_fd>."
10441 msgstr ""
10442
10443 #. type: Plain text
10444 #: build/C/man2/sendfile.2:148
10445 msgid ""
10446 "B<sendfile>()  is a new feature in Linux 2.2.  The include file "
10447 "I<E<lt>sys/sendfile.hE<gt>> is present since glibc 2.1."
10448 msgstr ""
10449
10450 #. type: Plain text
10451 #: build/C/man2/sendfile.2:150
10452 msgid "Not specified in POSIX.1-2001, or other standards."
10453 msgstr ""
10454
10455 #. type: Plain text
10456 #: build/C/man2/sendfile.2:155
10457 msgid ""
10458 "Other UNIX systems implement B<sendfile>()  with different semantics and "
10459 "prototypes.  It should not be used in portable programs."
10460 msgstr ""
10461
10462 #. type: Plain text
10463 #: build/C/man2/sendfile.2:165
10464 msgid ""
10465 "If you plan to use B<sendfile>()  for sending files to a TCP socket, but "
10466 "need to send some header data in front of the file contents, you will find "
10467 "it useful to employ the B<TCP_CORK> option, described in B<tcp>(7), to "
10468 "minimize the number of packets and to tune performance."
10469 msgstr ""
10470
10471 #. type: Plain text
10472 #: build/C/man2/sendfile.2:171
10473 msgid ""
10474 "In Linux 2.4 and earlier, I<out_fd> could also refer to a regular file, and "
10475 "B<sendfile>()  changed the current offset of that file."
10476 msgstr ""
10477
10478 #. type: Plain text
10479 #: build/C/man2/sendfile.2:183
10480 msgid ""
10481 "The original Linux B<sendfile>()  system call was not designed to handle "
10482 "large file offsets.  Consequently, Linux 2.4 added B<sendfile64>(), with a "
10483 "wider type for the I<offset> argument.  The glibc B<sendfile>()  wrapper "
10484 "function transparently deals with the kernel differences."
10485 msgstr ""
10486
10487 #. type: Plain text
10488 #: build/C/man2/sendfile.2:192
10489 msgid ""
10490 "Applications may wish to fall back to B<read>(2)/B<write>(2)  in the case "
10491 "where B<sendfile>()  fails with B<EINVAL> or B<ENOSYS>."
10492 msgstr ""
10493
10494 #. type: Plain text
10495 #: build/C/man2/sendfile.2:197
10496 msgid ""
10497 "The Linux-specific B<splice>(2)  call supports transferring data between "
10498 "arbitrary files (e.g., a pair of sockets)."
10499 msgstr ""
10500
10501 #. type: Plain text
10502 #: build/C/man2/sendfile.2:202
10503 msgid "B<mmap>(2), B<open>(2), B<socket>(2), B<splice>(2)"
10504 msgstr ""
10505
10506 #. type: TH
10507 #: build/C/man2/set_tid_address.2:25
10508 #, no-wrap
10509 msgid "SET_TID_ADDRESS"
10510 msgstr ""
10511
10512 #. type: TH
10513 #: build/C/man2/set_tid_address.2:25
10514 #, no-wrap
10515 msgid "2012-07-19"
10516 msgstr ""
10517
10518 #. type: Plain text
10519 #: build/C/man2/set_tid_address.2:28
10520 msgid "set_tid_address - set pointer to thread ID"
10521 msgstr ""
10522
10523 #. type: Plain text
10524 #: build/C/man2/set_tid_address.2:31
10525 #, no-wrap
10526 msgid "B<#include E<lt>linux/unistd.hE<gt>>\n"
10527 msgstr ""
10528
10529 #. type: Plain text
10530 #: build/C/man2/set_tid_address.2:33
10531 #, no-wrap
10532 msgid "B<long set_tid_address(int *>I<tidptr>B<);>\n"
10533 msgstr ""
10534
10535 #. type: Plain text
10536 #: build/C/man2/set_tid_address.2:40
10537 msgid ""
10538 "For each process, the kernel maintains two attributes (addresses) called "
10539 "I<set_child_tid> and I<clear_child_tid>.  These two attributes contain the "
10540 "value NULL by default."
10541 msgstr ""
10542
10543 #. type: TP
10544 #: build/C/man2/set_tid_address.2:40
10545 #, no-wrap
10546 msgid "I<set_child_tid>"
10547 msgstr ""
10548
10549 #. type: Plain text
10550 #: build/C/man2/set_tid_address.2:51
10551 msgid ""
10552 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_SETTID> "
10553 "flag, I<set_child_tid> is set to the value passed in the I<ctid> argument of "
10554 "that system call."
10555 msgstr ""
10556
10557 #. type: Plain text
10558 #: build/C/man2/set_tid_address.2:56
10559 msgid ""
10560 "When I<set_child_tid> is set, the very first thing the new process does is "
10561 "writing its PID at this address."
10562 msgstr ""
10563
10564 #. type: TP
10565 #: build/C/man2/set_tid_address.2:56
10566 #, no-wrap
10567 msgid "I<clear_child_tid>"
10568 msgstr ""
10569
10570 #. type: Plain text
10571 #: build/C/man2/set_tid_address.2:67
10572 msgid ""
10573 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_CLEARTID> "
10574 "flag, I<clear_child_tid> is set to the value passed in the I<ctid> argument "
10575 "of that system call."
10576 msgstr ""
10577
10578 #. type: Plain text
10579 #: build/C/man2/set_tid_address.2:74
10580 msgid ""
10581 "The system call B<set_tid_address>()  sets the I<clear_child_tid> value for "
10582 "the calling process to I<tidptr>."
10583 msgstr ""
10584
10585 #. type: Plain text
10586 #: build/C/man2/set_tid_address.2:82
10587 msgid ""
10588 "When a process whose I<clear_child_tid> is not NULL terminates, then, if the "
10589 "process is sharing memory with other processes or threads, then 0 is written "
10590 "at the address specified in I<clear_child_tid> and the kernel performs the "
10591 "following operation:"
10592 msgstr ""
10593
10594 #. type: Plain text
10595 #: build/C/man2/set_tid_address.2:84
10596 #, no-wrap
10597 msgid "    futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);\n"
10598 msgstr ""
10599
10600 #. type: Plain text
10601 #: build/C/man2/set_tid_address.2:88
10602 msgid ""
10603 "The effect of this operation is to wake a single process that is performing "
10604 "a futex wait on the memory location.  Errors from the futex wake operation "
10605 "are ignored."
10606 msgstr ""
10607
10608 #. type: Plain text
10609 #: build/C/man2/set_tid_address.2:91
10610 msgid "B<set_tid_address>()  always returns the PID of the calling process."
10611 msgstr ""
10612
10613 #. type: Plain text
10614 #: build/C/man2/set_tid_address.2:94
10615 msgid "B<set_tid_address>()  always succeeds."
10616 msgstr ""
10617
10618 #. type: Plain text
10619 #: build/C/man2/set_tid_address.2:97
10620 msgid ""
10621 "This call is present since Linux 2.5.48.  Details as given here are valid "
10622 "since Linux 2.5.49."
10623 msgstr ""
10624
10625 #. type: Plain text
10626 #: build/C/man2/set_tid_address.2:102
10627 msgid "B<clone>(2), B<futex>(2)"
10628 msgstr ""
10629
10630 #. type: TH
10631 #: build/C/man2/splice.2:26
10632 #, no-wrap
10633 msgid "SPLICE"
10634 msgstr ""
10635
10636 #. type: TH
10637 #: build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vmsplice.2:26
10638 #, no-wrap
10639 msgid "2012-05-04"
10640 msgstr ""
10641
10642 #. type: Plain text
10643 #: build/C/man2/splice.2:29
10644 msgid "splice - splice data to/from a pipe"
10645 msgstr ""
10646
10647 #. type: Plain text
10648 #: build/C/man2/splice.2:33 build/C/man2/tee.2:33
10649 #, no-wrap
10650 msgid ""
10651 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
10652 "B<#include E<lt>fcntl.hE<gt>>\n"
10653 msgstr ""
10654
10655 #.  Return type was long before glibc 2.7
10656 #. type: Plain text
10657 #: build/C/man2/splice.2:38
10658 #, no-wrap
10659 msgid ""
10660 "B<ssize_t splice(int >I<fd_in>B<, loff_t *>I<off_in>B<, int >I<fd_out>B<,>\n"
10661 "B<               loff_t *>I<off_out>B<, size_t >I<len>B<, unsigned int "
10662 ">I<flags>B<);>\n"
10663 msgstr ""
10664
10665 #. type: Plain text
10666 #: build/C/man2/splice.2:50
10667 msgid ""
10668 "B<splice>()  moves data between two file descriptors without copying between "
10669 "kernel address space and user address space.  It transfers up to I<len> "
10670 "bytes of data from the file descriptor I<fd_in> to the file descriptor "
10671 "I<fd_out>, where one of the descriptors must refer to a pipe."
10672 msgstr ""
10673
10674 #. type: Plain text
10675 #: build/C/man2/splice.2:80
10676 msgid ""
10677 "If I<fd_in> refers to a pipe, then I<off_in> must be NULL.  If I<fd_in> does "
10678 "not refer to a pipe and I<off_in> is NULL, then bytes are read from I<fd_in> "
10679 "starting from the current file offset, and the current file offset is "
10680 "adjusted appropriately.  If I<fd_in> does not refer to a pipe and I<off_in> "
10681 "is not NULL, then I<off_in> must point to a buffer which specifies the "
10682 "starting offset from which bytes will be read from I<fd_in>; in this case, "
10683 "the current file offset of I<fd_in> is not changed.  Analogous statements "
10684 "apply for I<fd_out> and I<off_out>."
10685 msgstr ""
10686
10687 #. type: Plain text
10688 #: build/C/man2/splice.2:85 build/C/man2/vmsplice.2:78
10689 msgid ""
10690 "The I<flags> argument is a bit mask that is composed by ORing together zero "
10691 "or more of the following values:"
10692 msgstr ""
10693
10694 #. type: TP
10695 #: build/C/man2/splice.2:85 build/C/man2/tee.2:62 build/C/man2/vmsplice.2:78
10696 #, no-wrap
10697 msgid "B<SPLICE_F_MOVE>"
10698 msgstr ""
10699
10700 #. type: Plain text
10701 #: build/C/man2/splice.2:98
10702 msgid ""
10703 "Attempt to move pages instead of copying.  This is only a hint to the "
10704 "kernel: pages may still be copied if the kernel cannot move the pages from "
10705 "the pipe, or if the pipe buffers don't refer to full pages.  The initial "
10706 "implementation of this flag was buggy: therefore starting in Linux 2.6.21 it "
10707 "is a no-op (but is still permitted in a B<splice>()  call); in the future, a "
10708 "correct implementation may be restored."
10709 msgstr ""
10710
10711 #. type: TP
10712 #: build/C/man2/splice.2:98 build/C/man2/tee.2:68 build/C/man2/vmsplice.2:84
10713 #, no-wrap
10714 msgid "B<SPLICE_F_NONBLOCK>"
10715 msgstr ""
10716
10717 #. type: Plain text
10718 #: build/C/man2/splice.2:107
10719 msgid ""
10720 "Do not block on I/O.  This makes the splice pipe operations nonblocking, but "
10721 "B<splice>()  may nevertheless block because the file descriptors that are "
10722 "spliced to/from may block (unless they have the B<O_NONBLOCK> flag set)."
10723 msgstr ""
10724
10725 #. type: TP
10726 #: build/C/man2/splice.2:107 build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10727 #, no-wrap
10728 msgid "B<SPLICE_F_MORE>"
10729 msgstr ""
10730
10731 #. type: Plain text
10732 #: build/C/man2/splice.2:121
10733 msgid ""
10734 "More data will be coming in a subsequent splice.  This is a helpful hint "
10735 "when the I<fd_out> refers to a socket (see also the description of "
10736 "B<MSG_MORE> in B<send>(2), and the description of B<TCP_CORK> in B<tcp>(7))"
10737 msgstr ""
10738
10739 #. type: TP
10740 #: build/C/man2/splice.2:121 build/C/man2/tee.2:79 build/C/man2/vmsplice.2:97
10741 #, no-wrap
10742 msgid "B<SPLICE_F_GIFT>"
10743 msgstr ""
10744
10745 #. type: Plain text
10746 #: build/C/man2/splice.2:127
10747 msgid "Unused for B<splice>(); see B<vmsplice>(2)."
10748 msgstr ""
10749
10750 #. type: Plain text
10751 #: build/C/man2/splice.2:136
10752 msgid ""
10753 "Upon successful completion, B<splice>()  returns the number of bytes spliced "
10754 "to or from the pipe.  A return value of 0 means that there was no data to "
10755 "transfer, and it would not make sense to block, because there are no writers "
10756 "connected to the write end of the pipe referred to by I<fd_in>."
10757 msgstr ""
10758
10759 #. type: Plain text
10760 #: build/C/man2/splice.2:142
10761 msgid "On error, B<splice>()  returns -1 and I<errno> is set to indicate the error."
10762 msgstr ""
10763
10764 #. type: Plain text
10765 #: build/C/man2/splice.2:147
10766 msgid ""
10767 "One or both file descriptors are not valid, or do not have proper read-write "
10768 "mode."
10769 msgstr ""
10770
10771 #.  The append-mode error is given since 2.6.27; in earlier kernels,
10772 #.  splice() in append mode was broken
10773 #. type: Plain text
10774 #: build/C/man2/splice.2:155
10775 msgid ""
10776 "Target filesystem doesn't support splicing; target file is opened in append "
10777 "mode; neither of the descriptors refers to a pipe; or offset given for "
10778 "nonseekable device."
10779 msgstr ""
10780
10781 #. type: Plain text
10782 #: build/C/man2/splice.2:158 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
10783 msgid "Out of memory."
10784 msgstr ""
10785
10786 #. type: TP
10787 #: build/C/man2/splice.2:158
10788 #, no-wrap
10789 msgid "B<ESPIPE>"
10790 msgstr ""
10791
10792 #. type: Plain text
10793 #: build/C/man2/splice.2:165
10794 msgid ""
10795 "Either I<off_in> or I<off_out> was not NULL, but the corresponding file "
10796 "descriptor refers to a pipe."
10797 msgstr ""
10798
10799 #. type: Plain text
10800 #: build/C/man2/splice.2:170
10801 msgid ""
10802 "The B<splice>()  system call first appeared in Linux 2.6.17; library support "
10803 "was added to glibc in version 2.5."
10804 msgstr ""
10805
10806 #. type: Plain text
10807 #: build/C/man2/splice.2:182
10808 msgid ""
10809 "The three system calls B<splice>(), B<vmsplice>(2), and B<tee>(2), provide "
10810 "user-space programs with full control over an arbitrary kernel buffer, "
10811 "implemented within the kernel using the same type of buffer that is used for "
10812 "a pipe.  In overview, these system calls perform the following tasks:"
10813 msgstr ""
10814
10815 #. type: TP
10816 #: build/C/man2/splice.2:182
10817 #, no-wrap
10818 msgid "B<splice>()"
10819 msgstr ""
10820
10821 #. type: Plain text
10822 #: build/C/man2/splice.2:186
10823 msgid ""
10824 "moves data from the buffer to an arbitrary file descriptor, or vice versa, "
10825 "or from one buffer to another."
10826 msgstr ""
10827
10828 #. type: TP
10829 #: build/C/man2/splice.2:186
10830 #, no-wrap
10831 msgid "B<tee>(2)"
10832 msgstr ""
10833
10834 #. type: Plain text
10835 #: build/C/man2/splice.2:189
10836 msgid "\"copies\" the data from one buffer to another."
10837 msgstr ""
10838
10839 #. type: TP
10840 #: build/C/man2/splice.2:189
10841 #, no-wrap
10842 msgid "B<vmsplice>(2)"
10843 msgstr ""
10844
10845 #. type: Plain text
10846 #: build/C/man2/splice.2:192
10847 msgid "\"copies\" data from user space into the buffer."
10848 msgstr ""
10849
10850 #
10851 #.  Linus: Now, imagine using the above in a media server, for example.
10852 #.  Let's say that a year or two has passed, so that the video drivers
10853 #.  have been updated to be able to do the splice thing, and what can
10854 #.  you do? You can:
10855 #
10856 #.  - splice from the (mpeg or whatever - let's just assume that the video
10857 #.    input is either digital or does the encoding on its own - like they
10858 #.    pretty much all do) video input into a pipe (remember: no copies - the
10859 #.    video input will just DMA directly into memory, and splice will just
10860 #.    set up the pages in the pipe buffer)
10861 #.  - tee that pipe to split it up
10862 #.  - splice one end to a file (ie "save the compressed stream to disk")
10863 #.  - splice the other end to a real-time video decoder window for your
10864 #.    real-time viewing pleasure.
10865 #
10866 #.  Linus: Now, the advantage of splice()/tee() is that you can
10867 #.  do zero-copy movement of data, and unlike sendfile() you can
10868 #.  do it on _arbitrary_ data (and, as shown by "tee()", it's more
10869 #.  than just sending the data to somebody else: you can duplicate
10870 #.  the data and choose to forward it to two or more different
10871 #.  users - for things like logging etc.).
10872 #. type: Plain text
10873 #: build/C/man2/splice.2:223
10874 msgid ""
10875 "Though we talk of copying, actual copies are generally avoided.  The kernel "
10876 "does this by implementing a pipe buffer as a set of reference-counted "
10877 "pointers to pages of kernel memory.  The kernel creates \"copies\" of pages "
10878 "in a buffer by creating new pointers (for the output buffer) referring to "
10879 "the pages, and increasing the reference counts for the pages: only pointers "
10880 "are copied, not the pages of the buffer."
10881 msgstr ""
10882
10883 #. type: Plain text
10884 #: build/C/man2/splice.2:226
10885 msgid "See B<tee>(2)."
10886 msgstr ""
10887
10888 #. type: Plain text
10889 #: build/C/man2/splice.2:230
10890 msgid "B<sendfile>(2), B<tee>(2), B<vmsplice>(2)"
10891 msgstr ""
10892
10893 #. type: TH
10894 #: build/C/man2/tee.2:26
10895 #, no-wrap
10896 msgid "TEE"
10897 msgstr ""
10898
10899 #. type: Plain text
10900 #: build/C/man2/tee.2:29
10901 msgid "tee - duplicating pipe content"
10902 msgstr ""
10903
10904 #. type: Plain text
10905 #: build/C/man2/tee.2:36
10906 #, no-wrap
10907 msgid ""
10908 "B<ssize_t tee(int >I<fd_in>B<, int >I<fd_out>B<, size_t >I<len>B<, unsigned "
10909 "int >I<flags>B<);>\n"
10910 msgstr ""
10911
10912 #.  Example programs http://brick.kernel.dk/snaps
10913 #
10914 #
10915 #.  add a "tee(in, out1, out2)" system call that duplicates the pages
10916 #.  (again, incrementing their reference count, not copying the data) from
10917 #.  one pipe to two other pipes.
10918 #. type: Plain text
10919 #: build/C/man2/tee.2:56
10920 msgid ""
10921 "B<tee>()  duplicates up to I<len> bytes of data from the pipe referred to by "
10922 "the file descriptor I<fd_in> to the pipe referred to by the file descriptor "
10923 "I<fd_out>.  It does not consume the data that is duplicated from I<fd_in>; "
10924 "therefore, that data can be copied by a subsequent B<splice>(2)."
10925 msgstr ""
10926
10927 #. type: Plain text
10928 #: build/C/man2/tee.2:62
10929 msgid ""
10930 "I<flags> is a series of modifier flags, which share the name space with "
10931 "B<splice>(2)  and B<vmsplice>(2):"
10932 msgstr ""
10933
10934 #. type: Plain text
10935 #: build/C/man2/tee.2:68
10936 msgid "Currently has no effect for B<tee>(); see B<splice>(2)."
10937 msgstr ""
10938
10939 #.  Not used for vmsplice
10940 #.  May be in the future -- therefore EAGAIN
10941 #. type: Plain text
10942 #: build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10943 msgid "Do not block on I/O; see B<splice>(2)  for further details."
10944 msgstr ""
10945
10946 #. type: Plain text
10947 #: build/C/man2/tee.2:79
10948 msgid ""
10949 "Currently has no effect for B<tee>(), but may be implemented in the future; "
10950 "see B<splice>(2)."
10951 msgstr ""
10952
10953 #. type: Plain text
10954 #: build/C/man2/tee.2:85
10955 msgid "Unused for B<tee>(); see B<vmsplice>(2)."
10956 msgstr ""
10957
10958 #. type: Plain text
10959 #: build/C/man2/tee.2:94
10960 msgid ""
10961 "Upon successful completion, B<tee>()  returns the number of bytes that were "
10962 "duplicated between the input and output.  A return value of 0 means that "
10963 "there was no data to transfer, and it would not make sense to block, because "
10964 "there are no writers connected to the write end of the pipe referred to by "
10965 "I<fd_in>."
10966 msgstr ""
10967
10968 #. type: Plain text
10969 #: build/C/man2/tee.2:100
10970 msgid "On error, B<tee>()  returns -1 and I<errno> is set to indicate the error."
10971 msgstr ""
10972
10973 #. type: Plain text
10974 #: build/C/man2/tee.2:111
10975 msgid ""
10976 "I<fd_in> or I<fd_out> does not refer to a pipe; or I<fd_in> and I<fd_out> "
10977 "refer to the same pipe."
10978 msgstr ""
10979
10980 #. type: Plain text
10981 #: build/C/man2/tee.2:119
10982 msgid ""
10983 "The B<tee>()  system call first appeared in Linux 2.6.17; library support "
10984 "was added to glibc in version 2.5."
10985 msgstr ""
10986
10987 #. type: Plain text
10988 #: build/C/man2/tee.2:130
10989 msgid ""
10990 "Conceptually, B<tee>()  copies the data between the two pipes.  In reality "
10991 "no real data copying takes place though: under the covers, B<tee>()  assigns "
10992 "data in the output by merely grabbing a reference to the input."
10993 msgstr ""
10994
10995 #. type: Plain text
10996 #: build/C/man2/tee.2:136
10997 msgid ""
10998 "The following example implements a basic B<tee>(1)  program using the "
10999 "B<tee>()  system call."
11000 msgstr ""
11001
11002 #. type: Plain text
11003 #: build/C/man2/tee.2:145
11004 #, no-wrap
11005 msgid ""
11006 "#define _GNU_SOURCE\n"
11007 "#include E<lt>fcntl.hE<gt>\n"
11008 "#include E<lt>stdio.hE<gt>\n"
11009 "#include E<lt>stdlib.hE<gt>\n"
11010 "#include E<lt>unistd.hE<gt>\n"
11011 "#include E<lt>errno.hE<gt>\n"
11012 "#include E<lt>limits.hE<gt>\n"
11013 msgstr ""
11014
11015 #. type: Plain text
11016 #: build/C/man2/tee.2:151
11017 #, no-wrap
11018 msgid ""
11019 "int\n"
11020 "main(int argc, char *argv[])\n"
11021 "{\n"
11022 "    int fd;\n"
11023 "    int len, slen;\n"
11024 msgstr ""
11025
11026 #. type: Plain text
11027 #: build/C/man2/tee.2:156
11028 #, no-wrap
11029 msgid ""
11030 "    if (argc != 2) {\n"
11031 "        fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
11032 "        exit(EXIT_FAILURE);\n"
11033 "    }\n"
11034 msgstr ""
11035
11036 #. type: Plain text
11037 #: build/C/man2/tee.2:162
11038 #, no-wrap
11039 msgid ""
11040 "    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);\n"
11041 "    if (fd == -1) {\n"
11042 "        perror(\"open\");\n"
11043 "        exit(EXIT_FAILURE);\n"
11044 "    }\n"
11045 msgstr ""
11046
11047 #. type: Plain text
11048 #: build/C/man2/tee.2:169
11049 #, no-wrap
11050 msgid ""
11051 "    do {\n"
11052 "        /*\n"
11053 "         * tee stdin to stdout.\n"
11054 "         */\n"
11055 "        len = tee(STDIN_FILENO, STDOUT_FILENO,\n"
11056 "                  INT_MAX, SPLICE_F_NONBLOCK);\n"
11057 msgstr ""
11058
11059 #. type: Plain text
11060 #: build/C/man2/tee.2:178
11061 #, no-wrap
11062 msgid ""
11063 "        if (len E<lt> 0) {\n"
11064 "            if (errno == EAGAIN)\n"
11065 "                continue;\n"
11066 "            perror(\"tee\");\n"
11067 "            exit(EXIT_FAILURE);\n"
11068 "        } else\n"
11069 "            if (len == 0)\n"
11070 "                break;\n"
11071 msgstr ""
11072
11073 #. type: Plain text
11074 #: build/C/man2/tee.2:192
11075 #, no-wrap
11076 msgid ""
11077 "        /*\n"
11078 "         * Consume stdin by splicing it to a file.\n"
11079 "         */\n"
11080 "        while (len E<gt> 0) {\n"
11081 "            slen = splice(STDIN_FILENO, NULL, fd, NULL,\n"
11082 "                          len, SPLICE_F_MOVE);\n"
11083 "            if (slen E<lt> 0) {\n"
11084 "                perror(\"splice\");\n"
11085 "                break;\n"
11086 "            }\n"
11087 "            len -= slen;\n"
11088 "        }\n"
11089 "    } while (1);\n"
11090 msgstr ""
11091
11092 #. type: Plain text
11093 #: build/C/man2/tee.2:196
11094 #, no-wrap
11095 msgid ""
11096 "    close(fd);\n"
11097 "    exit(EXIT_SUCCESS);\n"
11098 "}\n"
11099 msgstr ""
11100
11101 #. type: Plain text
11102 #: build/C/man2/tee.2:200
11103 msgid "B<splice>(2), B<vmsplice>(2)"
11104 msgstr ""
11105
11106 #. type: TH
11107 #: build/C/man2/vm86.2:26
11108 #, no-wrap
11109 msgid "VM86"
11110 msgstr ""
11111
11112 #. type: TH
11113 #: build/C/man2/vm86.2:26
11114 #, no-wrap
11115 msgid "2009-02-20"
11116 msgstr ""
11117
11118 #. type: Plain text
11119 #: build/C/man2/vm86.2:29
11120 msgid "vm86old, vm86 - enter virtual 8086 mode"
11121 msgstr ""
11122
11123 #. type: Plain text
11124 #: build/C/man2/vm86.2:31
11125 msgid "B<#include E<lt>sys/vm86.hE<gt>>"
11126 msgstr ""
11127
11128 #. type: Plain text
11129 #: build/C/man2/vm86.2:33
11130 msgid "B<int vm86old(struct vm86_struct *>I<info>B<);>"
11131 msgstr ""
11132
11133 #. type: Plain text
11134 #: build/C/man2/vm86.2:35
11135 msgid "B<int vm86(unsigned long >I<fn>B<, struct vm86plus_struct *>I<v86>B<);>"
11136 msgstr ""
11137
11138 #. type: Plain text
11139 #: build/C/man2/vm86.2:48
11140 msgid ""
11141 "The system call B<vm86>()  was introduced in Linux 0.97p2.  In Linux 2.1.15 "
11142 "and 2.0.28, it was renamed to B<vm86old>(), and a new B<vm86>()  was "
11143 "introduced.  The definition of I<struct vm86_struct> was changed in 1.1.8 "
11144 "and 1.1.9."
11145 msgstr ""
11146
11147 #. type: Plain text
11148 #: build/C/man2/vm86.2:52
11149 msgid ""
11150 "These calls cause the process to enter VM86 mode (virtual-8086 in Intel "
11151 "literature), and are used by B<dosemu>."
11152 msgstr ""
11153
11154 #. type: Plain text
11155 #: build/C/man2/vm86.2:54
11156 msgid "VM86 mode is an emulation of real mode within a protected mode task."
11157 msgstr ""
11158
11159 #. type: Plain text
11160 #: build/C/man2/vm86.2:64
11161 msgid ""
11162 "This return value is specific to i386 and indicates a problem with getting "
11163 "user-space data."
11164 msgstr ""
11165
11166 #. type: Plain text
11167 #: build/C/man2/vm86.2:68
11168 msgid ""
11169 "This return value indicates the call is not implemented on the present "
11170 "architecture."
11171 msgstr ""
11172
11173 #. type: Plain text
11174 #: build/C/man2/vm86.2:73
11175 msgid ""
11176 "Saved kernel stack exists.  (This is a kernel sanity check; the saved stack "
11177 "should exist only within vm86 mode itself.)"
11178 msgstr ""
11179
11180 #. type: Plain text
11181 #: build/C/man2/vm86.2:76
11182 msgid ""
11183 "This call is specific to Linux on 32-bit Intel processors, and should not be "
11184 "used in programs intended to be portable."
11185 msgstr ""
11186
11187 #. type: TH
11188 #: build/C/man2/vmsplice.2:26
11189 #, no-wrap
11190 msgid "VMSPLICE"
11191 msgstr ""
11192
11193 #. type: Plain text
11194 #: build/C/man2/vmsplice.2:29
11195 msgid "vmsplice - splice user pages into a pipe"
11196 msgstr ""
11197
11198 #. type: Plain text
11199 #: build/C/man2/vmsplice.2:34
11200 #, no-wrap
11201 msgid ""
11202 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
11203 "B<#include E<lt>fcntl.hE<gt>>\n"
11204 "B<#include E<lt>sys/uio.hE<gt>>\n"
11205 msgstr ""
11206
11207 #. type: Plain text
11208 #: build/C/man2/vmsplice.2:37
11209 #, no-wrap
11210 msgid ""
11211 "B<ssize_t vmsplice(int >I<fd>B<, const struct iovec *>I<iov>B<,>\n"
11212 "B<                 unsigned long >I<nr_segs>B<, unsigned int "
11213 ">I<flags>B<);>\n"
11214 msgstr ""
11215
11216 #.  Linus: vmsplice() system call to basically do a "write to
11217 #.  the buffer", but using the reference counting and VM traversal
11218 #.  to actually fill the buffer. This means that the user needs to
11219 #.  be careful not to reuse the user-space buffer it spliced into
11220 #.  the kernel-space one (contrast this to "write()", which copies
11221 #.  the actual data, and you can thus reuse the buffer immediately
11222 #.  after a successful write), but that is often easy to do.
11223 #. type: Plain text
11224 #: build/C/man2/vmsplice.2:57
11225 msgid ""
11226 "The B<vmsplice>()  system call maps I<nr_segs> ranges of user memory "
11227 "described by I<iov> into a pipe.  The file descriptor I<fd> must refer to a "
11228 "pipe."
11229 msgstr ""
11230
11231 #. type: Plain text
11232 #: build/C/man2/vmsplice.2:64
11233 msgid ""
11234 "The pointer I<iov> points to an array of I<iovec> structures as defined in "
11235 "I<E<lt>sys/uio.hE<gt>>:"
11236 msgstr ""
11237
11238 #. type: Plain text
11239 #: build/C/man2/vmsplice.2:71
11240 #, no-wrap
11241 msgid ""
11242 "struct iovec {\n"
11243 "    void  *iov_base;            /* Starting address */\n"
11244 "    size_t iov_len;             /* Number of bytes */\n"
11245 "};\n"
11246 msgstr ""
11247
11248 #. type: Plain text
11249 #: build/C/man2/vmsplice.2:84
11250 msgid "Unused for B<vmsplice>(); see B<splice>(2)."
11251 msgstr ""
11252
11253 #. type: Plain text
11254 #: build/C/man2/vmsplice.2:97
11255 msgid ""
11256 "Currently has no effect for B<vmsplice>(), but may be implemented in the "
11257 "future; see B<splice>(2)."
11258 msgstr ""
11259
11260 #.  FIXME Explain the following line in a little more detail:
11261 #.  .... if we expect to later SPLICE_F_MOVE to the cache.
11262 #. type: Plain text
11263 #: build/C/man2/vmsplice.2:113
11264 msgid ""
11265 "The user pages are a gift to the kernel.  The application may not modify "
11266 "this memory ever, or page cache and on-disk data may differ.  Gifting pages "
11267 "to the kernel means that a subsequent B<splice>(2)  B<SPLICE_F_MOVE> can "
11268 "successfully move the pages; if this flag is not specified, then a "
11269 "subsequent B<splice>(2)  B<SPLICE_F_MOVE> must copy the pages.  Data must "
11270 "also be properly page aligned, both in memory and length."
11271 msgstr ""
11272
11273 #. type: Plain text
11274 #: build/C/man2/vmsplice.2:122
11275 msgid ""
11276 "Upon successful completion, B<vmsplice>()  returns the number of bytes "
11277 "transferred to the pipe.  On error, B<vmsplice>()  returns -1 and I<errno> "
11278 "is set to indicate the error."
11279 msgstr ""
11280
11281 #. type: Plain text
11282 #: build/C/man2/vmsplice.2:127
11283 msgid "I<fd> either not valid, or doesn't refer to a pipe."
11284 msgstr ""
11285
11286 #. type: Plain text
11287 #: build/C/man2/vmsplice.2:135
11288 msgid ""
11289 "I<nr_segs> is 0 or greater than B<IOV_MAX>; or memory not aligned if "
11290 "B<SPLICE_F_GIFT> set."
11291 msgstr ""
11292
11293 #. type: Plain text
11294 #: build/C/man2/vmsplice.2:143
11295 msgid ""
11296 "The B<vmsplice>()  system call first appeared in Linux 2.6.17; library "
11297 "support was added to glibc in version 2.5."
11298 msgstr ""
11299
11300 #. type: Plain text
11301 #: build/C/man2/vmsplice.2:154
11302 msgid ""
11303 "B<vmsplice>()  follows the other vectorized read/write type functions when "
11304 "it comes to limitations on number of segments being passed in.  This limit "
11305 "is B<IOV_MAX> as defined in I<E<lt>limits.hE<gt>>.  At the time of this "
11306 "writing, that limit is 1024."
11307 msgstr ""
11308
11309 #. type: Plain text
11310 #: build/C/man2/vmsplice.2:157
11311 msgid "B<splice>(2), B<tee>(2)"
11312 msgstr ""