po4a/man2/po/man2.pot

   1 # SOME DESCRIPTIVE TITLE
   2 # Copyright (C) YEAR Free Software Foundation, Inc.
   3 # This file is distributed under the same license as the PACKAGE package.
   4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
   5 #
   6 #, fuzzy
   7 msgid ""
   8 msgstr ""
   9 "Project-Id-Version: PACKAGE VERSION\n"
  10 "POT-Creation-Date: 2013-09-28 04:06+0900\n"
  11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
  12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
  13 "Language-Team: LANGUAGE <LL@li.org>\n"
  14 "Language: \n"
  15 "MIME-Version: 1.0\n"
  16 "Content-Type: text/plain; charset=CHARSET\n"
  17 "Content-Transfer-Encoding: 8bit\n"
  18
  19 #. type: TH
  20 #: build/C/man2/arch_prctl.2:25
  21 #, no-wrap
  22 msgid "ARCH_PRCTL"
  23 msgstr ""
  24
  25 #. type: TH
  26 #: build/C/man2/arch_prctl.2:25
  27 #, no-wrap
  28 msgid "2007-12-26"
  29 msgstr ""
  30
  31 #. type: TH
  32 #: build/C/man2/arch_prctl.2:25 build/C/man2/futex.2:53 build/C/man2/get_robust_list.2:29 build/C/man2/getunwind.2:27 build/C/man2/kexec_load.2:26 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:24 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:26 build/C/man2/pciconfig_read.2:8 build/C/man2/perf_event_open.2:27 build/C/man2/perfmonctl.2:27 build/C/man2/personality.2:32 build/C/man2/pivot_root.2:10 build/C/man2/process_vm_readv.2:29 build/C/man2/ptrace.2:44 build/C/man2/quotactl.2:27 build/C/man2/sendfile.2:19 build/C/man2/set_tid_address.2:25 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
  33 #, no-wrap
  34 msgid "Linux"
  35 msgstr ""
  36
  37 #. type: TH
  38 #: build/C/man2/arch_prctl.2:25 build/C/man2/futex.2:53 build/C/man2/getunwind.2:27 build/C/man2/kexec_load.2:26 build/C/man2/lookup_dcookie.2:27 build/C/man2/modify_ldt.2:24 build/C/man2/nfsservctl.2:8 build/C/man2/outb.2:26 build/C/man2/pciconfig_read.2:8 build/C/man2/perf_event_open.2:27 build/C/man2/perfmonctl.2:27 build/C/man2/personality.2:32 build/C/man2/pivot_root.2:10 build/C/man2/process_vm_readv.2:29 build/C/man2/ptrace.2:44 build/C/man2/quotactl.2:27 build/C/man2/sendfile.2:19 build/C/man2/set_tid_address.2:25 build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vm86.2:26 build/C/man2/vmsplice.2:26
  39 #, no-wrap
  40 msgid "Linux Programmer's Manual"
  41 msgstr ""
  42
  43 #. type: SH
  44 #: build/C/man2/arch_prctl.2:26 build/C/man2/futex.2:54 build/C/man2/get_robust_list.2:30 build/C/man2/getunwind.2:28 build/C/man2/kexec_load.2:27 build/C/man2/lookup_dcookie.2:28 build/C/man2/modify_ldt.2:25 build/C/man2/nfsservctl.2:9 build/C/man2/outb.2:27 build/C/man2/pciconfig_read.2:9 build/C/man2/perf_event_open.2:28 build/C/man2/perfmonctl.2:28 build/C/man2/personality.2:33 build/C/man2/pivot_root.2:11 build/C/man2/process_vm_readv.2:30 build/C/man2/ptrace.2:45 build/C/man2/quotactl.2:28 build/C/man2/sendfile.2:20 build/C/man2/set_tid_address.2:26 build/C/man2/splice.2:27 build/C/man2/tee.2:27 build/C/man2/vm86.2:27 build/C/man2/vmsplice.2:27
  45 #, no-wrap
  46 msgid "NAME"
  47 msgstr ""
  48
  49 #. type: Plain text
  50 #: build/C/man2/arch_prctl.2:28
  51 msgid "arch_prctl - set architecture-specific thread state"
  52 msgstr ""
  53
  54 #. type: SH
  55 #: build/C/man2/arch_prctl.2:28 build/C/man2/futex.2:56 build/C/man2/get_robust_list.2:32 build/C/man2/getunwind.2:30 build/C/man2/kexec_load.2:29 build/C/man2/lookup_dcookie.2:30 build/C/man2/modify_ldt.2:27 build/C/man2/nfsservctl.2:11 build/C/man2/outb.2:31 build/C/man2/pciconfig_read.2:11 build/C/man2/perf_event_open.2:30 build/C/man2/perfmonctl.2:30 build/C/man2/personality.2:35 build/C/man2/pivot_root.2:13 build/C/man2/process_vm_readv.2:32 build/C/man2/ptrace.2:47 build/C/man2/quotactl.2:30 build/C/man2/sendfile.2:22 build/C/man2/set_tid_address.2:28 build/C/man2/splice.2:29 build/C/man2/tee.2:29 build/C/man2/vm86.2:29 build/C/man2/vmsplice.2:29
  56 #, no-wrap
  57 msgid "SYNOPSIS"
  58 msgstr ""
  59
  60 #. type: Plain text
  61 #: build/C/man2/arch_prctl.2:31
  62 #, no-wrap
  63 msgid "B<#include E<lt>asm/prctl.hE<gt>>\n"
  64 msgstr ""
  65
  66 #. type: Plain text
  67 #: build/C/man2/arch_prctl.2:33
  68 #, no-wrap
  69 msgid "B<#include E<lt>sys/prctl.hE<gt>>\n"
  70 msgstr ""
  71
  72 #. type: Plain text
  73 #: build/C/man2/arch_prctl.2:36
  74 #, no-wrap
  75 msgid ""
  76 "B<int arch_prctl(int >I<code>B<, unsigned long >I<addr>B<);>\n"
  77 "B<int arch_prctl(int >I<code>B<, unsigned long *>I<addr>B<);>\n"
  78 msgstr ""
  79
  80 #.  Return type was long before glibc 2.7
  81 #. type: SH
  82 #: build/C/man2/arch_prctl.2:37 build/C/man2/futex.2:68 build/C/man2/get_robust_list.2:44 build/C/man2/getunwind.2:40 build/C/man2/kexec_load.2:39 build/C/man2/lookup_dcookie.2:32 build/C/man2/modify_ldt.2:36 build/C/man2/nfsservctl.2:18 build/C/man2/outb.2:62 build/C/man2/pciconfig_read.2:22 build/C/man2/perf_event_open.2:42 build/C/man2/perfmonctl.2:39 build/C/man2/personality.2:39 build/C/man2/pivot_root.2:18 build/C/man2/process_vm_readv.2:50 build/C/man2/ptrace.2:54 build/C/man2/quotactl.2:38 build/C/man2/sendfile.2:47 build/C/man2/set_tid_address.2:34 build/C/man2/splice.2:39 build/C/man2/tee.2:38 build/C/man2/vm86.2:35 build/C/man2/vmsplice.2:39
  83 #, no-wrap
  84 msgid "DESCRIPTION"
  85 msgstr ""
  86
  87 #. type: Plain text
  88 #: build/C/man2/arch_prctl.2:52
  89 msgid ""
  90 "The B<arch_prctl>()  function sets architecture-specific process or thread "
  91 "state.  I<code> selects a subfunction and passes argument I<addr> to it; "
  92 "I<addr> is interpreted as either an I<unsigned long> for the \"set\" "
  93 "operations, or as an I<unsigned long\\ *>, for the \"get\" operations."
  94 msgstr ""
  95
  96 #. type: Plain text
  97 #: build/C/man2/arch_prctl.2:54
  98 msgid "Subfunctions for x86-64 are:"
  99 msgstr ""
 100
 101 #. type: TP
 102 #: build/C/man2/arch_prctl.2:54
 103 #, no-wrap
 104 msgid "B<ARCH_SET_FS>"
 105 msgstr ""
 106
 107 #. type: Plain text
 108 #: build/C/man2/arch_prctl.2:60
 109 msgid "Set the 64-bit base for the I<FS> register to I<addr>."
 110 msgstr ""
 111
 112 #. type: TP
 113 #: build/C/man2/arch_prctl.2:60
 114 #, no-wrap
 115 msgid "B<ARCH_GET_FS>"
 116 msgstr ""
 117
 118 #. type: Plain text
 119 #: build/C/man2/arch_prctl.2:68
 120 msgid ""
 121 "Return the 64-bit base value for the I<FS> register of the current thread in "
 122 "the I<unsigned long> pointed to by I<addr>."
 123 msgstr ""
 124
 125 #. type: TP
 126 #: build/C/man2/arch_prctl.2:68
 127 #, no-wrap
 128 msgid "B<ARCH_SET_GS>"
 129 msgstr ""
 130
 131 #. type: Plain text
 132 #: build/C/man2/arch_prctl.2:74
 133 msgid "Set the 64-bit base for the I<GS> register to I<addr>."
 134 msgstr ""
 135
 136 #. type: TP
 137 #: build/C/man2/arch_prctl.2:74
 138 #, no-wrap
 139 msgid "B<ARCH_GET_GS>"
 140 msgstr ""
 141
 142 #. type: Plain text
 143 #: build/C/man2/arch_prctl.2:82
 144 msgid ""
 145 "Return the 64-bit base value for the I<GS> register of the current thread in "
 146 "the I<unsigned long> pointed to by I<addr>."
 147 msgstr ""
 148
 149 #. type: SH
 150 #: build/C/man2/arch_prctl.2:82 build/C/man2/futex.2:214 build/C/man2/get_robust_list.2:77 build/C/man2/getunwind.2:81 build/C/man2/kexec_load.2:114 build/C/man2/lookup_dcookie.2:43 build/C/man2/modify_ldt.2:98 build/C/man2/nfsservctl.2:53 build/C/man2/pciconfig_read.2:50 build/C/man2/perf_event_open.2:2116 build/C/man2/perfmonctl.2:190 build/C/man2/personality.2:57 build/C/man2/pivot_root.2:101 build/C/man2/process_vm_readv.2:209 build/C/man2/ptrace.2:1780 build/C/man2/quotactl.2:419 build/C/man2/sendfile.2:108 build/C/man2/set_tid_address.2:88 build/C/man2/splice.2:127 build/C/man2/tee.2:85 build/C/man2/vm86.2:54 build/C/man2/vmsplice.2:113
 151 #, no-wrap
 152 msgid "RETURN VALUE"
 153 msgstr ""
 154
 155 #. type: Plain text
 156 #: build/C/man2/arch_prctl.2:88
 157 msgid ""
 158 "On success, B<arch_prctl>()  returns 0; on error, -1 is returned, and "
 159 "I<errno> is set to indicate the error."
 160 msgstr ""
 161
 162 #. type: SH
 163 #: build/C/man2/arch_prctl.2:88 build/C/man2/futex.2:239 build/C/man2/get_robust_list.2:84 build/C/man2/getunwind.2:88 build/C/man2/kexec_load.2:121 build/C/man2/lookup_dcookie.2:50 build/C/man2/modify_ldt.2:108 build/C/man2/pciconfig_read.2:77 build/C/man2/perf_event_open.2:2122 build/C/man2/personality.2:64 build/C/man2/pivot_root.2:105 build/C/man2/process_vm_readv.2:229 build/C/man2/ptrace.2:1801 build/C/man2/quotactl.2:427 build/C/man2/sendfile.2:115 build/C/man2/set_tid_address.2:91 build/C/man2/splice.2:142 build/C/man2/tee.2:100 build/C/man2/vm86.2:59 build/C/man2/vmsplice.2:122
 164 #, no-wrap
 165 msgid "ERRORS"
 166 msgstr ""
 167
 168 #. type: TP
 169 #: build/C/man2/arch_prctl.2:89 build/C/man2/futex.2:254 build/C/man2/get_robust_list.2:111 build/C/man2/lookup_dcookie.2:51 build/C/man2/modify_ldt.2:109 build/C/man2/process_vm_readv.2:251 build/C/man2/process_vm_readv.2:256 build/C/man2/ptrace.2:1805 build/C/man2/quotactl.2:428 build/C/man2/sendfile.2:125 build/C/man2/vm86.2:60
 170 #, no-wrap
 171 msgid "B<EFAULT>"
 172 msgstr ""
 173
 174 #. type: Plain text
 175 #: build/C/man2/arch_prctl.2:93
 176 msgid ""
 177 "I<addr> points to an unmapped address or is outside the process address "
 178 "space."
 179 msgstr ""
 180
 181 #. type: TP
 182 #: build/C/man2/arch_prctl.2:93 build/C/man2/futex.2:266 build/C/man2/get_robust_list.2:88 build/C/man2/kexec_load.2:126 build/C/man2/lookup_dcookie.2:54 build/C/man2/modify_ldt.2:113 build/C/man2/pciconfig_read.2:78 build/C/man2/perf_event_open.2:2123 build/C/man2/personality.2:65 build/C/man2/pivot_root.2:114 build/C/man2/process_vm_readv.2:230 build/C/man2/process_vm_readv.2:241 build/C/man2/process_vm_readv.2:245 build/C/man2/ptrace.2:1816 build/C/man2/quotactl.2:434 build/C/man2/quotactl.2:501 build/C/man2/sendfile.2:128 build/C/man2/splice.2:147 build/C/man2/tee.2:101 build/C/man2/vmsplice.2:127
 183 #, no-wrap
 184 msgid "B<EINVAL>"
 185 msgstr ""
 186
 187 #. type: Plain text
 188 #: build/C/man2/arch_prctl.2:97
 189 msgid "I<code> is not a valid subcommand."
 190 msgstr ""
 191
 192 #. type: TP
 193 #: build/C/man2/arch_prctl.2:97 build/C/man2/get_robust_list.2:98 build/C/man2/kexec_load.2:133 build/C/man2/lookup_dcookie.2:65 build/C/man2/pciconfig_read.2:105 build/C/man2/pivot_root.2:120 build/C/man2/process_vm_readv.2:267 build/C/man2/ptrace.2:1826 build/C/man2/quotactl.2:456 build/C/man2/vm86.2:68
 194 #, no-wrap
 195 msgid "B<EPERM>"
 196 msgstr ""
 197
 198 #.  .SH AUTHOR
 199 #.  Man page written by Andi Kleen.
 200 #. type: Plain text
 201 #: build/C/man2/arch_prctl.2:103
 202 msgid "I<addr> is outside the process address space."
 203 msgstr ""
 204
 205 #. type: SH
 206 #: build/C/man2/arch_prctl.2:103 build/C/man2/futex.2:301 build/C/man2/getunwind.2:96 build/C/man2/kexec_load.2:142 build/C/man2/lookup_dcookie.2:78 build/C/man2/modify_ldt.2:130 build/C/man2/nfsservctl.2:58 build/C/man2/outb.2:87 build/C/man2/pciconfig_read.2:112 build/C/man2/perf_event_open.2:2141 build/C/man2/perfmonctl.2:199 build/C/man2/personality.2:68 build/C/man2/pivot_root.2:128 build/C/man2/process_vm_readv.2:279 build/C/man2/ptrace.2:1844 build/C/man2/sendfile.2:148 build/C/man2/set_tid_address.2:97 build/C/man2/splice.2:170 build/C/man2/tee.2:119 build/C/man2/vm86.2:73 build/C/man2/vmsplice.2:143
 207 #, no-wrap
 208 msgid "CONFORMING TO"
 209 msgstr ""
 210
 211 #. type: Plain text
 212 #: build/C/man2/arch_prctl.2:107
 213 msgid ""
 214 "B<arch_prctl>()  is a Linux/x86-64 extension and should not be used in "
 215 "programs intended to be portable."
 216 msgstr ""
 217
 218 #. type: SH
 219 #: build/C/man2/arch_prctl.2:107 build/C/man2/futex.2:303 build/C/man2/get_robust_list.2:119 build/C/man2/getunwind.2:99 build/C/man2/kexec_load.2:144 build/C/man2/lookup_dcookie.2:81 build/C/man2/modify_ldt.2:133 build/C/man2/perf_event_open.2:2146 build/C/man2/perfmonctl.2:202 build/C/man2/pivot_root.2:131 build/C/man2/process_vm_readv.2:281 build/C/man2/ptrace.2:1846 build/C/man2/sendfile.2:155 build/C/man2/splice.2:172 build/C/man2/tee.2:121 build/C/man2/vmsplice.2:145
 220 #, no-wrap
 221 msgid "NOTES"
 222 msgstr ""
 223
 224 #. type: Plain text
 225 #: build/C/man2/arch_prctl.2:110
 226 msgid ""
 227 "B<arch_prctl>()  is supported only on Linux/x86-64 for 64-bit programs "
 228 "currently."
 229 msgstr ""
 230
 231 #. type: Plain text
 232 #: build/C/man2/arch_prctl.2:112
 233 msgid "The 64-bit base changes when a new 32-bit segment selector is loaded."
 234 msgstr ""
 235
 236 #. type: Plain text
 237 #: build/C/man2/arch_prctl.2:115
 238 msgid "B<ARCH_SET_GS> is disabled in some kernels."
 239 msgstr ""
 240
 241 #. type: Plain text
 242 #: build/C/man2/arch_prctl.2:130
 243 msgid ""
 244 "Context switches for 64-bit segment bases are rather expensive.  It may be a "
 245 "faster alternative to set a 32-bit base using a segment selector by setting "
 246 "up an LDT with B<modify_ldt>(2)  or using the B<set_thread_area>(2)  system "
 247 "call in kernel 2.5 or later.  B<arch_prctl>()  is needed only when you want "
 248 "to set bases that are larger than 4GB.  Memory in the first 2GB of address "
 249 "space can be allocated by using B<mmap>(2)  with the B<MAP_32BIT> flag."
 250 msgstr ""
 251
 252 #. type: Plain text
 253 #: build/C/man2/arch_prctl.2:135
 254 msgid ""
 255 "As of version 2.7, glibc provides no prototype for B<arch_prctl>().  You "
 256 "have to declare it yourself for now.  This may be fixed in future glibc "
 257 "versions."
 258 msgstr ""
 259
 260 #. type: Plain text
 261 #: build/C/man2/arch_prctl.2:138
 262 msgid "I<FS> may be already used by the threading library."
 263 msgstr ""
 264
 265 #. type: SH
 266 #: build/C/man2/arch_prctl.2:138 build/C/man2/futex.2:317 build/C/man2/get_robust_list.2:128 build/C/man2/getunwind.2:111 build/C/man2/kexec_load.2:159 build/C/man2/modify_ldt.2:136 build/C/man2/outb.2:96 build/C/man2/pciconfig_read.2:114 build/C/man2/perf_event_open.2:2266 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:143 build/C/man2/process_vm_readv.2:331 build/C/man2/ptrace.2:2000 build/C/man2/quotactl.2:507 build/C/man2/sendfile.2:197 build/C/man2/set_tid_address.2:99 build/C/man2/splice.2:226 build/C/man2/tee.2:197 build/C/man2/vmsplice.2:154
 267 #, no-wrap
 268 msgid "SEE ALSO"
 269 msgstr ""
 270
 271 #. type: Plain text
 272 #: build/C/man2/arch_prctl.2:143
 273 msgid "B<mmap>(2), B<modify_ldt>(2), B<prctl>(2), B<set_thread_area>(2)"
 274 msgstr ""
 275
 276 #. type: Plain text
 277 #: build/C/man2/arch_prctl.2:145
 278 msgid "AMD X86-64 Programmer's manual"
 279 msgstr ""
 280
 281 #. type: SH
 282 #: build/C/man2/arch_prctl.2:145 build/C/man2/futex.2:331 build/C/man2/get_robust_list.2:137 build/C/man2/getunwind.2:113 build/C/man2/kexec_load.2:162 build/C/man2/lookup_dcookie.2:88 build/C/man2/modify_ldt.2:138 build/C/man2/nfsservctl.2:60 build/C/man2/outb.2:99 build/C/man2/pciconfig_read.2:116 build/C/man2/perf_event_open.2:2272 build/C/man2/perfmonctl.2:209 build/C/man2/personality.2:72 build/C/man2/pivot_root.2:149 build/C/man2/process_vm_readv.2:334 build/C/man2/ptrace.2:2014 build/C/man2/quotactl.2:512 build/C/man2/sendfile.2:203 build/C/man2/set_tid_address.2:102 build/C/man2/splice.2:230 build/C/man2/tee.2:200 build/C/man2/vm86.2:76 build/C/man2/vmsplice.2:157
 283 #, no-wrap
 284 msgid "COLOPHON"
 285 msgstr ""
 286
 287 #. type: Plain text
 288 #: build/C/man2/arch_prctl.2:152 build/C/man2/futex.2:338 build/C/man2/get_robust_list.2:144 build/C/man2/getunwind.2:120 build/C/man2/kexec_load.2:169 build/C/man2/lookup_dcookie.2:95 build/C/man2/modify_ldt.2:145 build/C/man2/nfsservctl.2:67 build/C/man2/outb.2:106 build/C/man2/pciconfig_read.2:123 build/C/man2/perf_event_open.2:2279 build/C/man2/perfmonctl.2:216 build/C/man2/personality.2:79 build/C/man2/pivot_root.2:156 build/C/man2/process_vm_readv.2:341 build/C/man2/ptrace.2:2021 build/C/man2/quotactl.2:519 build/C/man2/sendfile.2:210 build/C/man2/set_tid_address.2:109 build/C/man2/splice.2:237 build/C/man2/tee.2:207 build/C/man2/vm86.2:83 build/C/man2/vmsplice.2:164
 289 msgid ""
 290 "This page is part of release 3.54 of the Linux I<man-pages> project.  A "
 291 "description of the project, and information about reporting bugs, can be "
 292 "found at \\%http://www.kernel.org/doc/man-pages/."
 293 msgstr ""
 294
 295 #. type: TH
 296 #: build/C/man2/futex.2:53
 297 #, no-wrap
 298 msgid "FUTEX"
 299 msgstr ""
 300
 301 #. type: TH
 302 #: build/C/man2/futex.2:53
 303 #, no-wrap
 304 msgid "2013-09-04"
 305 msgstr ""
 306
 307 #. type: Plain text
 308 #: build/C/man2/futex.2:56
 309 msgid "futex - fast user-space locking"
 310 msgstr ""
 311
 312 #. type: Plain text
 313 #: build/C/man2/futex.2:61
 314 #, no-wrap
 315 msgid ""
 316 "B<#include E<lt>linux/futex.hE<gt>>\n"
 317 "B<#include E<lt>sys/time.hE<gt>>\n"
 318 msgstr ""
 319
 320 #. type: Plain text
 321 #: build/C/man2/futex.2:64
 322 #, no-wrap
 323 msgid ""
 324 "B<int futex(int *>I<uaddr>B<, int >I<op>B<, int >I<val>B<, const struct "
 325 "timespec *>I<timeout>B<,>\n"
 326 msgstr ""
 327
 328 #.  int *? void *? u32 *?
 329 #. type: Plain text
 330 #: build/C/man2/futex.2:67
 331 #, no-wrap
 332 msgid "B<          int *>I<uaddr2>B<, int >I<val3>B<);>\n"
 333 msgstr ""
 334
 335 #. type: Plain text
 336 #: build/C/man2/futex.2:84
 337 msgid ""
 338 "The B<futex>()  system call provides a method for a program to wait for a "
 339 "value at a given address to change, and a method to wake up anyone waiting "
 340 "on a particular address (while the addresses for the same memory in separate "
 341 "processes may not be equal, the kernel maps them internally so the same "
 342 "memory mapped in different locations will correspond for B<futex>()  "
 343 "calls).  This system call is typically used to implement the contended case "
 344 "of a lock in shared memory, as described in B<futex>(7)."
 345 msgstr ""
 346
 347 #. type: Plain text
 348 #: build/C/man2/futex.2:91
 349 msgid ""
 350 "When a B<futex>(7)  operation did not finish uncontended in user space, a "
 351 "call needs to be made to the kernel to arbitrate.  Arbitration can either "
 352 "mean putting the calling process to sleep or, conversely, waking a waiting "
 353 "process."
 354 msgstr ""
 355
 356 #. type: Plain text
 357 #: build/C/man2/futex.2:98
 358 msgid ""
 359 "Callers of this function are expected to adhere to the semantics as set out "
 360 "in B<futex>(7).  As these semantics involve writing nonportable assembly "
 361 "instructions, this in turn probably means that most users will in fact be "
 362 "library authors and not general application developers."
 363 msgstr ""
 364
 365 #. type: Plain text
 366 #: build/C/man2/futex.2:106
 367 msgid ""
 368 "The I<uaddr> argument needs to point to an aligned integer which stores the "
 369 "counter.  The operation to execute is passed via the I<op> argument, along "
 370 "with a value I<val>."
 371 msgstr ""
 372
 373 #. type: Plain text
 374 #: build/C/man2/futex.2:108
 375 msgid "Five operations are currently defined:"
 376 msgstr ""
 377
 378 #. type: TP
 379 #: build/C/man2/futex.2:108 build/C/man2/futex.2:221
 380 #, no-wrap
 381 msgid "B<FUTEX_WAIT>"
 382 msgstr ""
 383
 384 #. type: Plain text
 385 #: build/C/man2/futex.2:131
 386 msgid ""
 387 "This operation atomically verifies that the futex address I<uaddr> still "
 388 "contains the value I<val>, and sleeps awaiting B<FUTEX_WAKE> on this futex "
 389 "address.  If the I<timeout> argument is non-NULL, its contents specify the "
 390 "duration of the wait.  (This interval will be rounded up to the system clock "
 391 "granularity, and kernel scheduling delays mean that the blocking interval "
 392 "may overrun by a small amount.)  If I<timeout> is NULL, the call blocks "
 393 "indefinitely.  The arguments I<uaddr2> and I<val3> are ignored."
 394 msgstr ""
 395
 396 #. type: Plain text
 397 #: build/C/man2/futex.2:139
 398 msgid ""
 399 "For B<futex>(7), this call is executed if decrementing the count gave a "
 400 "negative value (indicating contention), and will sleep until another process "
 401 "releases the futex and executes the B<FUTEX_WAKE> operation."
 402 msgstr ""
 403
 404 #. type: TP
 405 #: build/C/man2/futex.2:139 build/C/man2/futex.2:227
 406 #, no-wrap
 407 msgid "B<FUTEX_WAKE>"
 408 msgstr ""
 409
 410 #. type: Plain text
 411 #: build/C/man2/futex.2:150
 412 msgid ""
 413 "This operation wakes at most I<val> processes waiting on this futex address "
 414 "(i.e., inside B<FUTEX_WAIT>).  The arguments I<timeout>, I<uaddr2> and "
 415 "I<val3> are ignored."
 416 msgstr ""
 417
 418 #. type: Plain text
 419 #: build/C/man2/futex.2:156
 420 msgid ""
 421 "For B<futex>(7), this is executed if incrementing the count showed that "
 422 "there were waiters, once the futex value has been set to 1 (indicating that "
 423 "it is available)."
 424 msgstr ""
 425
 426 #. type: TP
 427 #: build/C/man2/futex.2:156
 428 #, no-wrap
 429 msgid "B<FUTEX_FD> (present up to and including Linux 2.6.25)"
 430 msgstr ""
 431
 432 #.  , suitable for .BR poll (2).
 433 #. type: Plain text
 434 #: build/C/man2/futex.2:172
 435 msgid ""
 436 "To support asynchronous wakeups, this operation associates a file descriptor "
 437 "with a futex.  If another process executes a B<FUTEX_WAKE>, the process will "
 438 "receive the signal number that was passed in I<val>.  The calling process "
 439 "must close the returned file descriptor after use.  The arguments "
 440 "I<timeout>, I<uaddr2> and I<val3> are ignored."
 441 msgstr ""
 442
 443 #. type: Plain text
 444 #: build/C/man2/futex.2:177
 445 msgid ""
 446 "To prevent race conditions, the caller should test if the futex has been "
 447 "upped after B<FUTEX_FD> returns."
 448 msgstr ""
 449
 450 #. type: Plain text
 451 #: build/C/man2/futex.2:181
 452 msgid ""
 453 "Because it was inherently racy, B<FUTEX_FD> has been removed from Linux "
 454 "2.6.26 onward."
 455 msgstr ""
 456
 457 #. type: TP
 458 #: build/C/man2/futex.2:181
 459 #, no-wrap
 460 msgid "B<FUTEX_REQUEUE> (since Linux 2.5.70)"
 461 msgstr ""
 462
 463 #. type: Plain text
 464 #: build/C/man2/futex.2:196
 465 msgid ""
 466 "This operation was introduced in order to avoid a \"thundering herd\" effect "
 467 "when B<FUTEX_WAKE> is used and all processes woken up need to acquire "
 468 "another futex.  This call wakes up I<val> processes, and requeues all other "
 469 "waiters on the futex at address I<uaddr2>.  The arguments I<timeout> and "
 470 "I<val3> are ignored."
 471 msgstr ""
 472
 473 #. type: TP
 474 #: build/C/man2/futex.2:196
 475 #, no-wrap
 476 msgid "B<FUTEX_CMP_REQUEUE> (since Linux 2.6.7)"
 477 msgstr ""
 478
 479 #. type: Plain text
 480 #: build/C/man2/futex.2:214
 481 msgid ""
 482 "There was a race in the intended use of B<FUTEX_REQUEUE>, so "
 483 "B<FUTEX_CMP_REQUEUE> was introduced.  This is similar to B<FUTEX_REQUEUE>, "
 484 "but first checks whether the location I<uaddr> still contains the value "
 485 "I<val3>.  If not, the operation fails with the error B<EAGAIN>.  The "
 486 "argument I<timeout> is ignored."
 487 msgstr ""
 488
 489 #. type: Plain text
 490 #: build/C/man2/futex.2:221
 491 msgid ""
 492 "In the event of an error, all operations return -1, and set I<errno> to "
 493 "indicate the error.  The return value on success depends on the operation, "
 494 "as described in the following list:"
 495 msgstr ""
 496
 497 #. type: Plain text
 498 #: build/C/man2/futex.2:227
 499 msgid ""
 500 "Returns 0 if the process was woken by a B<FUTEX_WAKE> call.  See ERRORS for "
 501 "the various possible error returns."
 502 msgstr ""
 503
 504 #. type: Plain text
 505 #: build/C/man2/futex.2:230 build/C/man2/futex.2:236 build/C/man2/futex.2:239
 506 msgid "Returns the number of processes woken up."
 507 msgstr ""
 508
 509 #. type: TP
 510 #: build/C/man2/futex.2:230
 511 #, no-wrap
 512 msgid "B<FUTEX_FD>"
 513 msgstr ""
 514
 515 #. type: Plain text
 516 #: build/C/man2/futex.2:233
 517 msgid "Returns the new file descriptor associated with the futex."
 518 msgstr ""
 519
 520 #. type: TP
 521 #: build/C/man2/futex.2:233
 522 #, no-wrap
 523 msgid "B<FUTEX_REQUEUE>"
 524 msgstr ""
 525
 526 #. type: TP
 527 #: build/C/man2/futex.2:236
 528 #, no-wrap
 529 msgid "B<FUTEX_CMP_REQUEUE>"
 530 msgstr ""
 531
 532 #. type: TP
 533 #: build/C/man2/futex.2:240 build/C/man2/quotactl.2:486
 534 #, no-wrap
 535 msgid "B<EACCES>"
 536 msgstr ""
 537
 538 #. type: Plain text
 539 #: build/C/man2/futex.2:243
 540 msgid "No read access to futex memory."
 541 msgstr ""
 542
 543 #. type: TP
 544 #: build/C/man2/futex.2:243 build/C/man2/sendfile.2:116
 545 #, no-wrap
 546 msgid "B<EAGAIN>"
 547 msgstr ""
 548
 549 #. type: Plain text
 550 #: build/C/man2/futex.2:254
 551 msgid ""
 552 "B<FUTEX_CMP_REQUEUE> detected that the value pointed to by I<uaddr> is not "
 553 "equal to the expected value I<val3>.  (This probably indicates a race; use "
 554 "the safe B<FUTEX_WAKE> now.)"
 555 msgstr ""
 556
 557 #. type: Plain text
 558 #: build/C/man2/futex.2:259
 559 msgid "Error retrieving I<timeout> information from user space."
 560 msgstr ""
 561
 562 #. type: TP
 563 #: build/C/man2/futex.2:259
 564 #, no-wrap
 565 msgid "B<EINTR>"
 566 msgstr ""
 567
 568 #. type: Plain text
 569 #: build/C/man2/futex.2:266
 570 msgid ""
 571 "A B<FUTEX_WAIT> operation was interrupted by a signal (see B<signal>(7))  or "
 572 "a spurious wakeup."
 573 msgstr ""
 574
 575 #. type: Plain text
 576 #: build/C/man2/futex.2:269
 577 msgid "Invalid argument."
 578 msgstr ""
 579
 580 #. type: TP
 581 #: build/C/man2/futex.2:269
 582 #, no-wrap
 583 msgid "B<ENFILE>"
 584 msgstr ""
 585
 586 #. type: Plain text
 587 #: build/C/man2/futex.2:272
 588 msgid "The system limit on the total number of open files has been reached."
 589 msgstr ""
 590
 591 #. type: TP
 592 #: build/C/man2/futex.2:272 build/C/man2/modify_ldt.2:126 build/C/man2/pciconfig_read.2:93 build/C/man2/quotactl.2:447 build/C/man2/vm86.2:64
 593 #, no-wrap
 594 msgid "B<ENOSYS>"
 595 msgstr ""
 596
 597 #. type: Plain text
 598 #: build/C/man2/futex.2:276
 599 msgid "Invalid operation specified in I<op>."
 600 msgstr ""
 601
 602 #. type: TP
 603 #: build/C/man2/futex.2:276
 604 #, no-wrap
 605 msgid "B<ETIMEDOUT>"
 606 msgstr ""
 607
 608 #. type: Plain text
 609 #: build/C/man2/futex.2:281
 610 msgid "Timeout during the B<FUTEX_WAIT> operation."
 611 msgstr ""
 612
 613 #. type: TP
 614 #: build/C/man2/futex.2:281
 615 #, no-wrap
 616 msgid "B<EWOULDBLOCK>"
 617 msgstr ""
 618
 619 #. type: Plain text
 620 #: build/C/man2/futex.2:291
 621 msgid ""
 622 "I<op> was B<FUTEX_WAIT> and the value pointed to by I<uaddr> was not equal "
 623 "to the expected value I<val> at the time of the call."
 624 msgstr ""
 625
 626 #. type: SH
 627 #: build/C/man2/futex.2:291 build/C/man2/get_robust_list.2:115 build/C/man2/getunwind.2:94 build/C/man2/kexec_load.2:138 build/C/man2/lookup_dcookie.2:73 build/C/man2/perfmonctl.2:196 build/C/man2/pivot_root.2:125 build/C/man2/process_vm_readv.2:276 build/C/man2/sendfile.2:142 build/C/man2/set_tid_address.2:94 build/C/man2/splice.2:165 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
 628 #, no-wrap
 629 msgid "VERSIONS"
 630 msgstr ""
 631
 632 #. type: Plain text
 633 #: build/C/man2/futex.2:301
 634 msgid ""
 635 "Initial futex support was merged in Linux 2.5.7 but with different semantics "
 636 "from what was described above.  A 4-argument system call with the semantics "
 637 "described in this page was introduced in Linux 2.5.40.  In Linux 2.5.70 one "
 638 "argument was added.  In Linux 2.6.7 a sixth argument was added\\(emmessy, "
 639 "especially on the s390 architecture."
 640 msgstr ""
 641
 642 #. type: Plain text
 643 #: build/C/man2/futex.2:303 build/C/man2/kexec_load.2:144 build/C/man2/set_tid_address.2:99 build/C/man2/splice.2:172 build/C/man2/tee.2:121 build/C/man2/vmsplice.2:145
 644 msgid "This system call is Linux-specific."
 645 msgstr ""
 646
 647 #.  .SH "AUTHORS"
 648 #.  .PP
 649 #.  Futexes were designed and worked on by
 650 #.  Hubertus Franke (IBM Thomas J. Watson Research Center),
 651 #.  Matthew Kirkwood, Ingo Molnar (Red Hat)
 652 #.  and Rusty Russell (IBM Linux Technology Center).
 653 #.  This page written by bert hubert.
 654 #. type: Plain text
 655 #: build/C/man2/futex.2:317
 656 msgid ""
 657 "To reiterate, bare futexes are not intended as an easy-to-use abstraction "
 658 "for end-users.  (There is no wrapper function for this system call in "
 659 "glibc.)  Implementors are expected to be assembly literate and to have read "
 660 "the sources of the futex user-space library referenced below."
 661 msgstr ""
 662
 663 #. type: Plain text
 664 #: build/C/man2/futex.2:320
 665 msgid "B<restart_syscall>(2), B<futex>(7)"
 666 msgstr ""
 667
 668 #. type: Plain text
 669 #: build/C/man2/futex.2:323
 670 msgid ""
 671 "I<Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux> (proceedings "
 672 "of the Ottawa Linux Symposium 2002), online at"
 673 msgstr ""
 674
 675 #. type: Plain text
 676 #: build/C/man2/futex.2:326
 677 msgid ""
 678 "E<.UR http://kernel.org\\:/doc\\:/ols\\:/2002\\:/ols2002-pages-479-495.pdf> "
 679 "E<.UE>"
 680 msgstr ""
 681
 682 #. type: Plain text
 683 #: build/C/man2/futex.2:328
 684 msgid "Futex example library, futex-*.tar.bz2 at"
 685 msgstr ""
 686
 687 #. type: Plain text
 688 #: build/C/man2/futex.2:331
 689 msgid ""
 690 "E<.UR ftp://ftp.nl.kernel.org\\:/pub\\:/linux\\:/kernel\\:/people\\:/rusty/> "
 691 "E<.UE>"
 692 msgstr ""
 693
 694 #. type: TH
 695 #: build/C/man2/get_robust_list.2:29
 696 #, no-wrap
 697 msgid "GET_ROBUST_LIST"
 698 msgstr ""
 699
 700 #. type: TH
 701 #: build/C/man2/get_robust_list.2:29 build/C/man2/kexec_load.2:26 build/C/man2/modify_ldt.2:24 build/C/man2/pivot_root.2:10
 702 #, no-wrap
 703 msgid "2012-07-13"
 704 msgstr ""
 705
 706 #. type: TH
 707 #: build/C/man2/get_robust_list.2:29
 708 #, no-wrap
 709 msgid "Linux System Calls"
 710 msgstr ""
 711
 712 #. type: Plain text
 713 #: build/C/man2/get_robust_list.2:32
 714 msgid "get_robust_list, set_robust_list - get/set list of robust futexes"
 715 msgstr ""
 716
 717 #. type: Plain text
 718 #: build/C/man2/get_robust_list.2:36
 719 #, no-wrap
 720 msgid ""
 721 "B<#include E<lt>linux/futex.hE<gt>>\n"
 722 "B<#include E<lt>syscall.hE<gt>>\n"
 723 msgstr ""
 724
 725 #. type: Plain text
 726 #: build/C/man2/get_robust_list.2:40
 727 #, no-wrap
 728 msgid ""
 729 "B<long get_robust_list(int >I<pid>B<, struct robust_list_head "
 730 "**>I<head_ptr>B<,>\n"
 731 "B<\t\t\t  size_t *>I<len_ptr>B<);>\n"
 732 "B<long set_robust_list(struct robust_list_head *>I<head>B<, size_t "
 733 ">I<len>B<);>\n"
 734 msgstr ""
 735
 736 #. type: Plain text
 737 #: build/C/man2/get_robust_list.2:44
 738 msgid "I<Note>: There are no glibc wrappers for these system calls; see NOTES."
 739 msgstr ""
 740
 741 #. type: Plain text
 742 #: build/C/man2/get_robust_list.2:49
 743 msgid ""
 744 "The robust futex implementation needs to maintain per-thread lists of robust "
 745 "futexes which are unlocked when the thread exits.  These lists are managed "
 746 "in user space; the kernel is notified about only the location of the head of "
 747 "the list."
 748 msgstr ""
 749
 750 #. type: Plain text
 751 #: build/C/man2/get_robust_list.2:65
 752 msgid ""
 753 "The B<get_robust_list>()  system call returns the head of the robust futex "
 754 "list of the thread whose thread ID is specified in I<pid>.  If I<pid> is 0, "
 755 "the head of the list for the calling thread is returned.  The list head is "
 756 "stored in the location pointed to by I<head_ptr>.  The size of the object "
 757 "pointed to by I<**head_ptr> is stored in I<len_ptr>."
 758 msgstr ""
 759
 760 #. type: Plain text
 761 #: build/C/man2/get_robust_list.2:77
 762 msgid ""
 763 "The B<set_robust_list>()  system call requests the kernel to record the head "
 764 "of the list of robust futexes owned by the calling thread.  The I<head> "
 765 "argument is the list head to record.  The I<len> argument should be "
 766 "I<sizeof(*head)>."
 767 msgstr ""
 768
 769 #. type: Plain text
 770 #: build/C/man2/get_robust_list.2:84
 771 msgid ""
 772 "The B<set_robust_list>()  and B<get_robust_list>()  system calls return zero "
 773 "when the operation is successful, an error code otherwise."
 774 msgstr ""
 775
 776 #. type: Plain text
 777 #: build/C/man2/get_robust_list.2:88
 778 msgid "The B<set_robust_list>()  system call can fail with the following error:"
 779 msgstr ""
 780
 781 #. type: Plain text
 782 #: build/C/man2/get_robust_list.2:94
 783 msgid ""
 784 "I<len> does not match the size of structure B<struct robust_list_head> "
 785 "expected by kernel."
 786 msgstr ""
 787
 788 #. type: Plain text
 789 #: build/C/man2/get_robust_list.2:98
 790 msgid "The B<get_robust_list>()  system call can fail with the following errors:"
 791 msgstr ""
 792
 793 #. type: Plain text
 794 #: build/C/man2/get_robust_list.2:106
 795 msgid ""
 796 "The calling process does not have permission to see the robust futex list of "
 797 "the thread with the thread ID I<pid>, and does not have the "
 798 "B<CAP_SYS_PTRACE> capability."
 799 msgstr ""
 800
 801 #. type: TP
 802 #: build/C/man2/get_robust_list.2:106 build/C/man2/process_vm_readv.2:271 build/C/man2/ptrace.2:1839 build/C/man2/quotactl.2:461 build/C/man2/quotactl.2:504
 803 #, no-wrap
 804 msgid "B<ESRCH>"
 805 msgstr ""
 806
 807 #. type: Plain text
 808 #: build/C/man2/get_robust_list.2:111
 809 msgid "No thread with the thread ID I<pid> could be found."
 810 msgstr ""
 811
 812 #. type: Plain text
 813 #: build/C/man2/get_robust_list.2:115
 814 msgid "The head of the robust futex list can't be stored at the location I<head>."
 815 msgstr ""
 816
 817 #. type: Plain text
 818 #: build/C/man2/get_robust_list.2:119
 819 msgid ""
 820 "These system calls were added in Linux 2.6.17.  No library support is "
 821 "provided; use B<syscall>(2)."
 822 msgstr ""
 823
 824 #. type: Plain text
 825 #: build/C/man2/get_robust_list.2:124
 826 msgid ""
 827 "These system calls are not needed by normal applications.  No support for "
 828 "them is provided in glibc.  In the unlikely event that you want to call them "
 829 "directly, use B<syscall>(2)."
 830 msgstr ""
 831
 832 #. type: Plain text
 833 #: build/C/man2/get_robust_list.2:128
 834 msgid ""
 835 "A thread can have only one robust futex list; therefore applications that "
 836 "wish to use this functionality should use the robust mutexes provided by "
 837 "glibc."
 838 msgstr ""
 839
 840 #.  .BR pthread_mutexattr_setrobust_np (3)
 841 #. type: Plain text
 842 #: build/C/man2/get_robust_list.2:131
 843 msgid "B<futex>(2)"
 844 msgstr ""
 845
 846 #.  http://lwn.net/Articles/172149/
 847 #. type: Plain text
 848 #: build/C/man2/get_robust_list.2:137
 849 msgid ""
 850 "I<Documentation/robust-futexes.txt> and "
 851 "I<Documentation/robust-futex-ABI.txt> in the Linux kernel source tree"
 852 msgstr ""
 853
 854 #. type: TH
 855 #: build/C/man2/getunwind.2:27
 856 #, no-wrap
 857 msgid "GETUNWIND"
 858 msgstr ""
 859
 860 #. type: TH
 861 #: build/C/man2/getunwind.2:27 build/C/man2/perfmonctl.2:27
 862 #, no-wrap
 863 msgid "2013-02-13"
 864 msgstr ""
 865
 866 #. type: Plain text
 867 #: build/C/man2/getunwind.2:30
 868 msgid "getunwind - copy the unwind data to caller's buffer"
 869 msgstr ""
 870
 871 #. type: Plain text
 872 #: build/C/man2/getunwind.2:34
 873 #, no-wrap
 874 msgid ""
 875 "B<#include E<lt>syscall.hE<gt>>\n"
 876 "B<#include E<lt>linux/unwind.hE<gt>>\n"
 877 msgstr ""
 878
 879 #. type: Plain text
 880 #: build/C/man2/getunwind.2:36
 881 #, no-wrap
 882 msgid "B<long getunwind(void >I<*buf>B<, size_t >I<buf_size>B<);>\n"
 883 msgstr ""
 884
 885 #. type: Plain text
 886 #: build/C/man2/getunwind.2:40 build/C/man2/kexec_load.2:39 build/C/man2/modify_ldt.2:36 build/C/man2/perf_event_open.2:42 build/C/man2/perfmonctl.2:39 build/C/man2/pivot_root.2:18
 887 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
 888 msgstr ""
 889
 890 #. type: Plain text
 891 #: build/C/man2/getunwind.2:42
 892 msgid "I<Note: this function is obsolete.>"
 893 msgstr ""
 894
 895 #. type: Plain text
 896 #: build/C/man2/getunwind.2:52
 897 msgid ""
 898 "The IA-64-specific B<getunwind>()  system call copies the kernel's call "
 899 "frame unwind data into the buffer pointed to by I<buf> and returns the size "
 900 "of the unwind data; this data describes the gate page (kernel code that is "
 901 "mapped into user space)."
 902 msgstr ""
 903
 904 #. type: Plain text
 905 #: build/C/man2/getunwind.2:64
 906 msgid ""
 907 "The size of the buffer I<buf> is specified in I<buf_size>.  The data is "
 908 "copied only if I<buf_size> is greater than or equal to the size of the "
 909 "unwind data and I<buf> is not NULL; otherwise, no data is copied, and the "
 910 "call succeeds, returning the size that would be needed to store the unwind "
 911 "data."
 912 msgstr ""
 913
 914 #. type: Plain text
 915 #: build/C/man2/getunwind.2:68
 916 msgid ""
 917 "The first part of the unwind data contains an unwind table.  The rest "
 918 "contains the associated unwind information, in no particular order.  The "
 919 "unwind table contains entries of the following form:"
 920 msgstr ""
 921
 922 #. type: Plain text
 923 #: build/C/man2/getunwind.2:73
 924 #, no-wrap
 925 msgid ""
 926 "\tu64 start;      (64-bit address of start of function)\n"
 927 "\tu64 end;        (64-bit address of end of function)\n"
 928 "\tu64 info;       (BUF-relative offset to unwind info)\n"
 929 msgstr ""
 930
 931 #. type: Plain text
 932 #: build/C/man2/getunwind.2:81
 933 msgid ""
 934 "An entry whose I<start> value is zero indicates the end of the table.  For "
 935 "more information about the format, see the I<IA-64 Software Conventions and "
 936 "Runtime Architecture> manual."
 937 msgstr ""
 938
 939 #. type: Plain text
 940 #: build/C/man2/getunwind.2:88
 941 msgid ""
 942 "On success, B<getunwind>()  returns the size of unwind table.  On error, -1 "
 943 "is returned and I<errno> is set to indicate the error."
 944 msgstr ""
 945
 946 #. type: Plain text
 947 #: build/C/man2/getunwind.2:94
 948 msgid ""
 949 "B<getunwind>()  fails with the error B<EFAULT> if the unwind info can't be "
 950 "stored in the space specified by I<buf>."
 951 msgstr ""
 952
 953 #. type: Plain text
 954 #: build/C/man2/getunwind.2:96
 955 msgid "This system call is available since Linux 2.4."
 956 msgstr ""
 957
 958 #. type: Plain text
 959 #: build/C/man2/getunwind.2:99
 960 msgid ""
 961 "This system call is Linux specific, and is available only on the IA-64 "
 962 "architecture."
 963 msgstr ""
 964
 965 #. type: Plain text
 966 #: build/C/man2/getunwind.2:107
 967 msgid ""
 968 "This system call has been deprecated.  The modern way to obtain the kernel's "
 969 "unwind data is via the gate DSO.  The address of the ELF header for this DSO "
 970 "is passed to user level via B<AT_SYSINFO_EHDR> (see B<getauxval>(3))."
 971 msgstr ""
 972
 973 #. type: Plain text
 974 #: build/C/man2/getunwind.2:111
 975 msgid ""
 976 "Glibc does not provide a wrapper for this system call; in the unlikely event "
 977 "that you want to call it, use B<syscall>(2)."
 978 msgstr ""
 979
 980 #. type: Plain text
 981 #: build/C/man2/getunwind.2:113
 982 msgid "B<getauxval>(3)"
 983 msgstr ""
 984
 985 #. type: TH
 986 #: build/C/man2/kexec_load.2:26
 987 #, no-wrap
 988 msgid "KEXEC_LOAD"
 989 msgstr ""
 990
 991 #. type: Plain text
 992 #: build/C/man2/kexec_load.2:29
 993 msgid "kexec_load - load a new kernel for later execution"
 994 msgstr ""
 995
 996 #. type: Plain text
 997 #: build/C/man2/kexec_load.2:31
 998 msgid "B<#include E<lt>linux/kexec.hE<gt>>"
 999 msgstr ""
1000
1001 #. type: Plain text
1002 #: build/C/man2/kexec_load.2:33
1003 msgid ""
1004 "B<long kexec_load(unsigned long >I<entry>B<, unsigned long "
1005 ">I<nr_segments>B<,>"
1006 msgstr ""
1007
1008 #. type: Plain text
1009 #: build/C/man2/kexec_load.2:36
1010 msgid "B< struct kexec_segment *>I<segments>B<, unsigned long >I<flags>B<);>"
1011 msgstr ""
1012
1013 #. type: Plain text
1014 #: build/C/man2/kexec_load.2:44
1015 msgid ""
1016 "The B<kexec_load>()  system call loads a new kernel that can be executed "
1017 "later by B<reboot>(2)."
1018 msgstr ""
1019
1020 #. type: Plain text
1021 #: build/C/man2/kexec_load.2:50
1022 msgid ""
1023 "The I<flags> argument is a mask whose high-order bits control the operation "
1024 "of the call.  The following values can be specified in I<flags>:"
1025 msgstr ""
1026
1027 #. type: TP
1028 #: build/C/man2/kexec_load.2:50
1029 #, no-wrap
1030 msgid "B<KEXEC_ON_CRASH> (since Linux 2.6.13)"
1031 msgstr ""
1032
1033 #.  FIXME figure out how this is really used
1034 #. type: Plain text
1035 #: build/C/man2/kexec_load.2:54
1036 msgid "Execute the new kernel automatically on a system crash."
1037 msgstr ""
1038
1039 #. type: TP
1040 #: build/C/man2/kexec_load.2:54
1041 #, no-wrap
1042 msgid "B<KEXEC_PRESERVE_CONTEXT> (since Linux 2.6.27)"
1043 msgstr ""
1044
1045 #. type: Plain text
1046 #: build/C/man2/kexec_load.2:64
1047 msgid ""
1048 "Preserve the system hardware and software states before executing the new "
1049 "kernel.  This could be used for system suspend.  This flag is available only "
1050 "if the kernel was configured with B<CONFIG_KEXEC_JUMP>, and is effective "
1051 "only if I<nr_segments> is greater than 0."
1052 msgstr ""
1053
1054 #. type: Plain text
1055 #: build/C/man2/kexec_load.2:84
1056 msgid ""
1057 "The low-order bits of I<flags> contain the architecture of the "
1058 "to-be-executed kernel.  Specify (OR) the constant B<KEXEC_ARCH_DEFAULT> to "
1059 "use the current architecture, or one of the following architecture constants "
1060 "B<KEXEC_ARCH_386>, B<KEXEC_ARCH_X86_64>, B<KEXEC_ARCH_PPC>, "
1061 "B<KEXEC_ARCH_PPC64>, B<KEXEC_ARCH_IA_64>, B<KEXEC_ARCH_ARM>, "
1062 "B<KEXEC_ARCH_S390>, B<KEXEC_ARCH_SH>, B<KEXEC_ARCH_MIPS>, and "
1063 "B<KEXEC_ARCH_MIPS_LE>.  The architecture must be executable on the CPU of "
1064 "the system."
1065 msgstr ""
1066
1067 #. type: Plain text
1068 #: build/C/man2/kexec_load.2:98
1069 msgid ""
1070 "The I<entry> argument is the physical entry address in the kernel image.  "
1071 "The I<nr_segments> argument is the number of segments pointed to by the "
1072 "I<segments> pointer.  The I<segments> argument is an array of "
1073 "I<kexec_segment> structures which define the kernel layout:"
1074 msgstr ""
1075
1076 #. type: Plain text
1077 #: build/C/man2/kexec_load.2:107
1078 #, no-wrap
1079 msgid ""
1080 "struct kexec_segment {\n"
1081 "    void   *buf;        /* Buffer in user space */\n"
1082 "    size_t  bufsz;      /* Buffer length in user space */\n"
1083 "    void   *mem;        /* Physical address of kernel */\n"
1084 "    size_t  memsz;      /* Physical address length */\n"
1085 "};\n"
1086 msgstr ""
1087
1088 #.  FIXME elaborate on the following:
1089 #. type: Plain text
1090 #: build/C/man2/kexec_load.2:114
1091 msgid ""
1092 "The kernel image defined by I<segments> is copied from the calling process "
1093 "into previously reserved memory."
1094 msgstr ""
1095
1096 #. type: Plain text
1097 #: build/C/man2/kexec_load.2:121
1098 msgid ""
1099 "On success, B<kexec_load>()  returns 0.  On error, -1 is returned and "
1100 "I<errno> is set to indicate the error."
1101 msgstr ""
1102
1103 #. type: TP
1104 #: build/C/man2/kexec_load.2:122 build/C/man2/pivot_root.2:110 build/C/man2/ptrace.2:1802 build/C/man2/quotactl.2:495
1105 #, no-wrap
1106 msgid "B<EBUSY>"
1107 msgstr ""
1108
1109 #. type: Plain text
1110 #: build/C/man2/kexec_load.2:126
1111 msgid ""
1112 "Another crash kernel is already being loaded or a crash kernel is already in "
1113 "use."
1114 msgstr ""
1115
1116 #.  KEXEC_SEGMENT_MAX == 16
1117 #. type: Plain text
1118 #: build/C/man2/kexec_load.2:133
1119 msgid "I<flags> is invalid; or I<nr_segments> is too large"
1120 msgstr ""
1121
1122 #. type: Plain text
1123 #: build/C/man2/kexec_load.2:138
1124 msgid "The caller does not have the B<CAP_SYS_BOOT> capability."
1125 msgstr ""
1126
1127 #. type: Plain text
1128 #: build/C/man2/kexec_load.2:142
1129 msgid "The B<kexec_load>()  system call first appeared in Linux 2.6.13."
1130 msgstr ""
1131
1132 #. type: Plain text
1133 #: build/C/man2/kexec_load.2:149
1134 msgid ""
1135 "Currently, there is no glibc support for B<kexec_load>().  Call it using "
1136 "B<syscall>(2)."
1137 msgstr ""
1138
1139 #.  FIXME Andi submitted a patch for this.
1140 #.  Check if it got accepted later.
1141 #. type: Plain text
1142 #: build/C/man2/kexec_load.2:156
1143 msgid ""
1144 "The required constants are in the Linux kernel source file I<linux/kexec.h>, "
1145 "which is not currently exported to glibc.  Therefore, these constants must "
1146 "be defined manually."
1147 msgstr ""
1148
1149 #. type: Plain text
1150 #: build/C/man2/kexec_load.2:159
1151 msgid ""
1152 "This system call is available only if the kernel was configured with "
1153 "B<CONFIG_KEXEC>."
1154 msgstr ""
1155
1156 #. type: Plain text
1157 #: build/C/man2/kexec_load.2:162
1158 msgid "B<reboot>(2), B<syscall>(2)"
1159 msgstr ""
1160
1161 #. type: TH
1162 #: build/C/man2/lookup_dcookie.2:27
1163 #, no-wrap
1164 msgid "LOOKUP_DCOOKIE"
1165 msgstr ""
1166
1167 #. type: TH
1168 #: build/C/man2/lookup_dcookie.2:27
1169 #, no-wrap
1170 msgid "2004-06-17"
1171 msgstr ""
1172
1173 #. type: Plain text
1174 #: build/C/man2/lookup_dcookie.2:30
1175 msgid "lookup_dcookie - return a directory entry's path"
1176 msgstr ""
1177
1178 #. type: Plain text
1179 #: build/C/man2/lookup_dcookie.2:32
1180 msgid ""
1181 "B<int lookup_dcookie(u64 >I<cookie>B<, char *>I<buffer>B<, size_t "
1182 ">I<len>B<);>"
1183 msgstr ""
1184
1185 #. type: Plain text
1186 #: build/C/man2/lookup_dcookie.2:38
1187 msgid ""
1188 "Look up the full path of the directory entry specified by the value "
1189 "I<cookie>.  The cookie is an opaque identifier uniquely identifying a "
1190 "particular directory entry.  The buffer given is filled in with the full "
1191 "path of the directory entry."
1192 msgstr ""
1193
1194 #. type: Plain text
1195 #: build/C/man2/lookup_dcookie.2:43
1196 msgid ""
1197 "For B<lookup_dcookie>()  to return successfully, the kernel must still hold "
1198 "a cookie reference to the directory entry."
1199 msgstr ""
1200
1201 #. type: Plain text
1202 #: build/C/man2/lookup_dcookie.2:50
1203 msgid ""
1204 "On success, B<lookup_dcookie>()  returns the length of the path string "
1205 "copied into the buffer.  On error, -1 is returned, and I<errno> is set "
1206 "appropriately."
1207 msgstr ""
1208
1209 #. type: Plain text
1210 #: build/C/man2/lookup_dcookie.2:54
1211 msgid "The buffer was not valid."
1212 msgstr ""
1213
1214 #. type: Plain text
1215 #: build/C/man2/lookup_dcookie.2:58
1216 msgid ""
1217 "The kernel has no registered cookie/directory entry mappings at the time of "
1218 "lookup, or the cookie does not refer to a valid directory entry."
1219 msgstr ""
1220
1221 #. type: TP
1222 #: build/C/man2/lookup_dcookie.2:58
1223 #, no-wrap
1224 msgid "B<ENAMETOOLONG>"
1225 msgstr ""
1226
1227 #. type: Plain text
1228 #: build/C/man2/lookup_dcookie.2:61
1229 msgid "The name could not fit in the buffer."
1230 msgstr ""
1231
1232 #. type: TP
1233 #: build/C/man2/lookup_dcookie.2:61 build/C/man2/process_vm_readv.2:262 build/C/man2/sendfile.2:138 build/C/man2/splice.2:155 build/C/man2/tee.2:111 build/C/man2/vmsplice.2:135
1234 #, no-wrap
1235 msgid "B<ENOMEM>"
1236 msgstr ""
1237
1238 #. type: Plain text
1239 #: build/C/man2/lookup_dcookie.2:65
1240 msgid ""
1241 "The kernel could not allocate memory for the temporary buffer holding the "
1242 "path."
1243 msgstr ""
1244
1245 #. type: Plain text
1246 #: build/C/man2/lookup_dcookie.2:70
1247 msgid ""
1248 "The process does not have the capability B<CAP_SYS_ADMIN> required to look "
1249 "up cookie values."
1250 msgstr ""
1251
1252 #. type: TP
1253 #: build/C/man2/lookup_dcookie.2:70 build/C/man2/quotactl.2:474
1254 #, no-wrap
1255 msgid "B<ERANGE>"
1256 msgstr ""
1257
1258 #. type: Plain text
1259 #: build/C/man2/lookup_dcookie.2:73
1260 msgid "The buffer was not large enough to hold the path of the directory entry."
1261 msgstr ""
1262
1263 #. type: Plain text
1264 #: build/C/man2/lookup_dcookie.2:78
1265 msgid ""
1266 "Available since Linux 2.5.43.  The B<ENAMETOOLONG> error return was added in "
1267 "2.5.70."
1268 msgstr ""
1269
1270 #. type: Plain text
1271 #: build/C/man2/lookup_dcookie.2:81
1272 msgid "B<lookup_dcookie>()  is Linux-specific."
1273 msgstr ""
1274
1275 #. type: Plain text
1276 #: build/C/man2/lookup_dcookie.2:85
1277 msgid ""
1278 "B<lookup_dcookie>()  is a special-purpose system call, currently used only "
1279 "by the oprofile profiler.  It relies on a kernel driver to register cookies "
1280 "for directory entries."
1281 msgstr ""
1282
1283 #. type: Plain text
1284 #: build/C/man2/lookup_dcookie.2:88
1285 msgid ""
1286 "The path returned may be suffixed by the string \" (deleted)\" if the "
1287 "directory entry has been removed."
1288 msgstr ""
1289
1290 #. type: TH
1291 #: build/C/man2/modify_ldt.2:24
1292 #, no-wrap
1293 msgid "MODIFY_LDT"
1294 msgstr ""
1295
1296 #. type: Plain text
1297 #: build/C/man2/modify_ldt.2:27
1298 msgid "modify_ldt - get or set ldt"
1299 msgstr ""
1300
1301 #. type: Plain text
1302 #: build/C/man2/modify_ldt.2:30
1303 #, no-wrap
1304 msgid "B<#include E<lt>sys/types.hE<gt>>\n"
1305 msgstr ""
1306
1307 #. type: Plain text
1308 #: build/C/man2/modify_ldt.2:32
1309 #, no-wrap
1310 msgid ""
1311 "B<int modify_ldt(int >I<func>B<, void *>I<ptr>B<, unsigned long "
1312 ">I<bytecount>B<);>\n"
1313 msgstr ""
1314
1315 #. type: Plain text
1316 #: build/C/man2/modify_ldt.2:41
1317 msgid ""
1318 "B<modify_ldt>()  reads or writes the local descriptor table (ldt) for a "
1319 "process.  The ldt is a per-process memory management table used by the i386 "
1320 "processor.  For more information on this table, see an Intel 386 processor "
1321 "handbook."
1322 msgstr ""
1323
1324 #. type: Plain text
1325 #: build/C/man2/modify_ldt.2:51
1326 msgid ""
1327 "When I<func> is 0, B<modify_ldt>()  reads the ldt into the memory pointed to "
1328 "by I<ptr>.  The number of bytes read is the smaller of I<bytecount> and the "
1329 "actual size of the ldt."
1330 msgstr ""
1331
1332 #
1333 #.  FIXME ? say something about func == 2 and func == 0x11?
1334 #.  In Linux 2.4, func == 2 returned "the default ldt"
1335 #.  In Linux 2.6, func == 2 is a nop, returning a zeroed out structure.
1336 #.  Linux 2.4 and 2.6 implement an operation for func == 0x11
1337 #. type: Plain text
1338 #: build/C/man2/modify_ldt.2:69
1339 msgid ""
1340 "When I<func> is 1, B<modify_ldt>()  modifies one ldt entry.  I<ptr> points "
1341 "to a I<user_desc> structure and I<bytecount> must equal the size of this "
1342 "structure."
1343 msgstr ""
1344
1345 #. type: Plain text
1346 #: build/C/man2/modify_ldt.2:73
1347 msgid "The I<user_desc> structure is defined in I<E<lt>asm/ldt.hE<gt>> as:"
1348 msgstr ""
1349
1350 #. type: Plain text
1351 #: build/C/man2/modify_ldt.2:87
1352 #, no-wrap
1353 msgid ""
1354 "struct user_desc {\n"
1355 "    unsigned int  entry_number;\n"
1356 "    unsigned long base_addr;\n"
1357 "    unsigned int  limit;\n"
1358 "    unsigned int  seg_32bit:1;\n"
1359 "    unsigned int  contents:2;\n"
1360 "    unsigned int  read_exec_only:1;\n"
1361 "    unsigned int  limit_in_pages:1;\n"
1362 "    unsigned int  seg_not_present:1;\n"
1363 "    unsigned int  useable:1;\n"
1364 "};\n"
1365 msgstr ""
1366
1367 #.  .PP
1368 #.  The ldt is specific for the calling process. Any attempts to change
1369 #.  the ldt to include the address space of another process or the kernel
1370 #.  will result in a segmentation violation when trying to access the memory
1371 #.  outside of the process address space. The memory protection is enforced
1372 #.  at the paging layer.
1373 #. type: Plain text
1374 #: build/C/man2/modify_ldt.2:98
1375 msgid "In Linux 2.4 and earlier, this structure was named I<modify_ldt_ldt_s>."
1376 msgstr ""
1377
1378 #. type: Plain text
1379 #: build/C/man2/modify_ldt.2:108
1380 msgid ""
1381 "On success, B<modify_ldt>()  returns either the actual number of bytes read "
1382 "(for reading)  or 0 (for writing).  On failure, B<modify_ldt>()  returns -1 "
1383 "and sets I<errno> to indicate the error."
1384 msgstr ""
1385
1386 #. type: Plain text
1387 #: build/C/man2/modify_ldt.2:113
1388 msgid "I<ptr> points outside the address space."
1389 msgstr ""
1390
1391 #. type: Plain text
1392 #: build/C/man2/modify_ldt.2:126
1393 msgid ""
1394 "I<ptr> is 0, or I<func> is 1 and I<bytecount> is not equal to the size of "
1395 "the structure I<modify_ldt_ldt_s>, or I<func> is 1 and the new ldt entry has "
1396 "invalid values."
1397 msgstr ""
1398
1399 #. type: Plain text
1400 #: build/C/man2/modify_ldt.2:130
1401 msgid "I<func> is neither 0 nor 1."
1402 msgstr ""
1403
1404 #. type: Plain text
1405 #: build/C/man2/modify_ldt.2:133
1406 msgid ""
1407 "This call is Linux-specific and should not be used in programs intended to "
1408 "be portable."
1409 msgstr ""
1410
1411 #. type: Plain text
1412 #: build/C/man2/modify_ldt.2:136 build/C/man2/perfmonctl.2:205 build/C/man2/pivot_root.2:134
1413 msgid ""
1414 "Glibc does not provide a wrapper for this system call; call it using "
1415 "B<syscall>(2)."
1416 msgstr ""
1417
1418 #. type: Plain text
1419 #: build/C/man2/modify_ldt.2:138
1420 msgid "B<vm86>(2)"
1421 msgstr ""
1422
1423 #. type: TH
1424 #: build/C/man2/nfsservctl.2:8
1425 #, no-wrap
1426 msgid "NFSSERVCTL"
1427 msgstr ""
1428
1429 #. type: TH
1430 #: build/C/man2/nfsservctl.2:8
1431 #, no-wrap
1432 msgid "2013-09-17"
1433 msgstr ""
1434
1435 #. type: Plain text
1436 #: build/C/man2/nfsservctl.2:11
1437 msgid "nfsservctl - syscall interface to kernel nfs daemon"
1438 msgstr ""
1439
1440 #. type: Plain text
1441 #: build/C/man2/nfsservctl.2:14
1442 #, no-wrap
1443 msgid "B<#include E<lt>linux/nfsd/syscall.hE<gt>>\n"
1444 msgstr ""
1445
1446 #. type: Plain text
1447 #: build/C/man2/nfsservctl.2:17
1448 #, no-wrap
1449 msgid ""
1450 "B<long nfsservctl(int >I<cmd>B<, struct nfsctl_arg *>I<argp>B<,>\n"
1451 "B<                union nfsctl_res *>I<resp>B<);>\n"
1452 msgstr ""
1453
1454 #. type: Plain text
1455 #: build/C/man2/nfsservctl.2:21
1456 msgid "I<Note>: Since Linux 3.1, this system call no longer exists."
1457 msgstr ""
1458
1459 #. type: Plain text
1460 #: build/C/man2/nfsservctl.2:35
1461 #, no-wrap
1462 msgid ""
1463 "/*\n"
1464 " * These are the commands understood by nfsctl().\n"
1465 " */\n"
1466 "#define NFSCTL_SVC          0    /* This is a server process. */\n"
1467 "#define NFSCTL_ADDCLIENT    1    /* Add an NFS client. */\n"
1468 "#define NFSCTL_DELCLIENT    2    /* Remove an NFS client. */\n"
1469 "#define NFSCTL_EXPORT       3    /* Export a filesystem. */\n"
1470 "#define NFSCTL_UNEXPORT     4    /* Unexport a filesystem. */\n"
1471 "#define NFSCTL_UGIDUPDATE   5    /* Update a client's UID/GID map\n"
1472 "                                    (only in Linux 2.4.x and earlier). */\n"
1473 "#define NFSCTL_GETFH        6    /* Get a file handle (used by mountd)\n"
1474 "                                    (only in Linux 2.4.x and earlier). */\n"
1475 msgstr ""
1476
1477 #. type: Plain text
1478 #: build/C/man2/nfsservctl.2:47
1479 #, no-wrap
1480 msgid ""
1481 "struct nfsctl_arg {\n"
1482 "    int                       ca_version;     /* safeguard */\n"
1483 "    union {\n"
1484 "        struct nfsctl_svc     u_svc;\n"
1485 "        struct nfsctl_client  u_client;\n"
1486 "        struct nfsctl_export  u_export;\n"
1487 "        struct nfsctl_uidmap  u_umap;\n"
1488 "        struct nfsctl_fhparm  u_getfh;\n"
1489 "        unsigned int          u_debug;\n"
1490 "    } u;\n"
1491 "}\n"
1492 msgstr ""
1493
1494 #. type: Plain text
1495 #: build/C/man2/nfsservctl.2:52
1496 #, no-wrap
1497 msgid ""
1498 "union nfsctl_res {\n"
1499 "        struct knfs_fh          cr_getfh;\n"
1500 "        unsigned int            cr_debug;\n"
1501 "};\n"
1502 msgstr ""
1503
1504 #. type: Plain text
1505 #: build/C/man2/nfsservctl.2:58 build/C/man2/pivot_root.2:105 build/C/man2/vm86.2:59
1506 msgid ""
1507 "On success, zero is returned.  On error, -1 is returned, and I<errno> is set "
1508 "appropriately."
1509 msgstr ""
1510
1511 #. type: Plain text
1512 #: build/C/man2/nfsservctl.2:60
1513 msgid "This call is Linux-specific."
1514 msgstr ""
1515
1516 #. type: TH
1517 #: build/C/man2/outb.2:26
1518 #, no-wrap
1519 msgid "OUTB"
1520 msgstr ""
1521
1522 #. type: TH
1523 #: build/C/man2/outb.2:26
1524 #, no-wrap
1525 msgid "2012-12-31"
1526 msgstr ""
1527
1528 #. type: Plain text
1529 #: build/C/man2/outb.2:31
1530 msgid ""
1531 "outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, "
1532 "outb_p, outw_p, outl_p, inb_p, inw_p, inl_p - port I/O"
1533 msgstr ""
1534
1535 #. type: Plain text
1536 #: build/C/man2/outb.2:34
1537 #, no-wrap
1538 msgid "B<#include E<lt>sys/io.hE<gt>>\n"
1539 msgstr ""
1540
1541 #. type: Plain text
1542 #: build/C/man2/outb.2:41
1543 #, no-wrap
1544 msgid ""
1545 "B<unsigned char inb(unsigned short int >I<port>B<);>\n"
1546 "B<unsigned char inb_p(unsigned short int >I<port>B<);>\n"
1547 "B<unsigned short int inw(unsigned short int >I<port>B<);>\n"
1548 "B<unsigned short int inw_p(unsigned short int >I<port>B<);>\n"
1549 "B<unsigned int inl(unsigned short int >I<port>B<);>\n"
1550 "B<unsigned int inl_p(unsigned short int >I<port>B<);>\n"
1551 msgstr ""
1552
1553 #. type: Plain text
1554 #: build/C/man2/outb.2:48
1555 #, no-wrap
1556 msgid ""
1557 "B<void outb(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1558 "B<void outb_p(unsigned char >I<value>B<, unsigned short int >I<port>B<);>\n"
1559 "B<void outw(unsigned short int >I<value>B<, unsigned short int "
1560 ">I<port>B<);>\n"
1561 "B<void outw_p(unsigned short int >I<value>B<, unsigned short int "
1562 ">I<port>B<);>\n"
1563 "B<void outl(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1564 "B<void outl_p(unsigned int >I<value>B<, unsigned short int >I<port>B<);>\n"
1565 msgstr ""
1566
1567 #. type: Plain text
1568 #: build/C/man2/outb.2:61
1569 #, no-wrap
1570 msgid ""
1571 "B<void insb(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1572 "B<           unsigned long int >I<count>B<);>\n"
1573 "B<void insw(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1574 "B<           unsigned long int >I<count>B<);>\n"
1575 "B<void insl(unsigned short int >I<port>B<, void *>I<addr>B<,>\n"
1576 "B<           unsigned long int >I<count>B<);>\n"
1577 "B<void outsb(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1578 "B<           unsigned long int >I<count>B<);>\n"
1579 "B<void outsw(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1580 "B<           unsigned long int >I<count>B<);>\n"
1581 "B<void outsl(unsigned short int >I<port>B<, const void *>I<addr>B<,>\n"
1582 "B<           unsigned long int >I<count>B<);>\n"
1583 msgstr ""
1584
1585 #. type: Plain text
1586 #: build/C/man2/outb.2:67
1587 msgid ""
1588 "This family of functions is used to do low-level port input and output.  The "
1589 "out* functions do port output, the in* functions do port input; the b-suffix "
1590 "functions are byte-width and the w-suffix functions word-width; the "
1591 "_p-suffix functions pause until the I/O completes."
1592 msgstr ""
1593
1594 #.  , given the following information
1595 #.  in addition to that given in
1596 #.  .BR outb (9).
1597 #. type: Plain text
1598 #: build/C/man2/outb.2:73
1599 msgid ""
1600 "They are primarily designed for internal kernel use, but can be used from "
1601 "user space."
1602 msgstr ""
1603
1604 #. type: Plain text
1605 #: build/C/man2/outb.2:78
1606 msgid ""
1607 "You must compile with B<-O> or B<-O2> or similar.  The functions are defined "
1608 "as inline macros, and will not be substituted in without optimization "
1609 "enabled, causing unresolved references at link time."
1610 msgstr ""
1611
1612 #. type: Plain text
1613 #: build/C/man2/outb.2:87
1614 msgid ""
1615 "You use B<ioperm>(2)  or alternatively B<iopl>(2)  to tell the kernel to "
1616 "allow the user space application to access the I/O ports in question.  "
1617 "Failure to do this will cause the application to receive a segmentation "
1618 "fault."
1619 msgstr ""
1620
1621 #. type: Plain text
1622 #: build/C/man2/outb.2:96
1623 msgid ""
1624 "B<outb>()  and friends are hardware-specific.  The I<value> argument is "
1625 "passed first and the I<port> argument is passed second, which is the "
1626 "opposite order from most DOS implementations."
1627 msgstr ""
1628
1629 #. type: Plain text
1630 #: build/C/man2/outb.2:99
1631 msgid "B<ioperm>(2), B<iopl>(2)"
1632 msgstr ""
1633
1634 #. type: TH
1635 #: build/C/man2/pciconfig_read.2:8
1636 #, no-wrap
1637 msgid "PCICONFIG_READ"
1638 msgstr ""
1639
1640 #. type: TH
1641 #: build/C/man2/pciconfig_read.2:8
1642 #, no-wrap
1643 msgid "2003-07-14"
1644 msgstr ""
1645
1646 #. type: Plain text
1647 #: build/C/man2/pciconfig_read.2:11
1648 msgid ""
1649 "pciconfig_read, pciconfig_write, pciconfig_iobase - pci device information "
1650 "handling"
1651 msgstr ""
1652
1653 #. type: Plain text
1654 #: build/C/man2/pciconfig_read.2:14
1655 #, no-wrap
1656 msgid "B<#include E<lt>pci.hE<gt>>\n"
1657 msgstr ""
1658
1659 #. type: Plain text
1660 #: build/C/man2/pciconfig_read.2:21
1661 #, no-wrap
1662 msgid ""
1663 "B<int pciconfig_read(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1664 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1665 "*>I<buf>B<);>\n"
1666 "B<int pciconfig_write(unsigned long >I<bus>B<, unsigned long >I<dfn>B<,>\n"
1667 "B<          unsigned long >I<off>B<, unsigned long >I<len>B<, void "
1668 "*>I<buf>B<);>\n"
1669 "B<int pciconfig_iobase(long >I<which>B<, unsigned long >I<bus>B<,>\n"
1670 "B<          unsigned long >I<devfn>B<);>\n"
1671 msgstr ""
1672
1673 #. type: Plain text
1674 #: build/C/man2/pciconfig_read.2:27
1675 msgid ""
1676 "Most of the interaction with PCI devices is already handled by the kernel "
1677 "PCI layer, and thus these calls should not normally need to be accessed from "
1678 "user space."
1679 msgstr ""
1680
1681 #. type: TP
1682 #: build/C/man2/pciconfig_read.2:27 build/C/man2/pciconfig_read.2:51
1683 #, no-wrap
1684 msgid "B<pciconfig_read>()"
1685 msgstr ""
1686
1687 #. type: Plain text
1688 #: build/C/man2/pciconfig_read.2:36
1689 msgid "Reads to I<buf> from device I<dev> at offset I<off> value."
1690 msgstr ""
1691
1692 #. type: TP
1693 #: build/C/man2/pciconfig_read.2:36 build/C/man2/pciconfig_read.2:57
1694 #, no-wrap
1695 msgid "B<pciconfig_write>()"
1696 msgstr ""
1697
1698 #. type: Plain text
1699 #: build/C/man2/pciconfig_read.2:45
1700 msgid "Writes from I<buf> to device I<dev> at offset I<off> value."
1701 msgstr ""
1702
1703 #. type: TP
1704 #: build/C/man2/pciconfig_read.2:45 build/C/man2/pciconfig_read.2:63
1705 #, no-wrap
1706 msgid "B<pciconfig_iobase>()"
1707 msgstr ""
1708
1709 #. type: Plain text
1710 #: build/C/man2/pciconfig_read.2:50
1711 msgid ""
1712 "You pass it a bus/devfn pair and get a physical address for either the "
1713 "memory offset (for things like prep, this is 0xc0000000), the IO base for "
1714 "PIO cycles, or the ISA holes if any."
1715 msgstr ""
1716
1717 #. type: Plain text
1718 #: build/C/man2/pciconfig_read.2:57 build/C/man2/pciconfig_read.2:63
1719 msgid ""
1720 "On success zero is returned.  On error, -1 is returned and I<errno> is set "
1721 "appropriately."
1722 msgstr ""
1723
1724 #. type: Plain text
1725 #: build/C/man2/pciconfig_read.2:77
1726 msgid ""
1727 "Returns information on locations of various I/O regions in physical memory "
1728 "according to the I<which> value.  Values for I<which> are: "
1729 "B<IOBASE_BRIDGE_NUMBER>, B<IOBASE_MEMORY>, B<IOBASE_IO>, B<IOBASE_ISA_IO>, "
1730 "B<IOBASE_ISA_MEM>."
1731 msgstr ""
1732
1733 #. type: Plain text
1734 #: build/C/man2/pciconfig_read.2:84
1735 msgid "I<len> value is invalid.  This does not apply to B<pciconfig_iobase>()."
1736 msgstr ""
1737
1738 #. type: TP
1739 #: build/C/man2/pciconfig_read.2:84 build/C/man2/ptrace.2:1819 build/C/man2/sendfile.2:134
1740 #, no-wrap
1741 msgid "B<EIO>"
1742 msgstr ""
1743
1744 #. type: Plain text
1745 #: build/C/man2/pciconfig_read.2:87
1746 msgid "I/O error."
1747 msgstr ""
1748
1749 #. type: TP
1750 #: build/C/man2/pciconfig_read.2:87
1751 #, no-wrap
1752 msgid "B<ENODEV>"
1753 msgstr ""
1754
1755 #. type: Plain text
1756 #: build/C/man2/pciconfig_read.2:93
1757 msgid ""
1758 "For B<pciconfig_iobase>(), \"hose\" value is NULL.  For the other calls, "
1759 "could not find a slot."
1760 msgstr ""
1761
1762 #. type: Plain text
1763 #: build/C/man2/pciconfig_read.2:98
1764 msgid "The system has not implemented these calls (B<CONFIG_PCI> not defined)."
1765 msgstr ""
1766
1767 #. type: TP
1768 #: build/C/man2/pciconfig_read.2:98
1769 #, no-wrap
1770 msgid "B<EOPNOTSUPP>"
1771 msgstr ""
1772
1773 #. type: Plain text
1774 #: build/C/man2/pciconfig_read.2:105
1775 msgid ""
1776 "This return value is valid only for B<pciconfig_iobase>().  It is returned "
1777 "if the value for I<which> is invalid."
1778 msgstr ""
1779
1780 #. type: Plain text
1781 #: build/C/man2/pciconfig_read.2:112
1782 msgid ""
1783 "User does not have the B<CAP_SYS_ADMIN> capability.  This does not apply to "
1784 "B<pciconfig_iobase>()."
1785 msgstr ""
1786
1787 #. type: Plain text
1788 #: build/C/man2/pciconfig_read.2:114
1789 msgid "These calls are Linux-specific, available since Linux 2.0.26/2.1.11."
1790 msgstr ""
1791
1792 #. type: Plain text
1793 #: build/C/man2/pciconfig_read.2:116
1794 msgid "B<capabilities>(7)"
1795 msgstr ""
1796
1797 #. type: TH
1798 #: build/C/man2/perf_event_open.2:27
1799 #, no-wrap
1800 msgid "PERF_EVENT_OPEN"
1801 msgstr ""
1802
1803 #. type: TH
1804 #: build/C/man2/perf_event_open.2:27
1805 #, no-wrap
1806 msgid "2013-09-13"
1807 msgstr ""
1808
1809 #. type: Plain text
1810 #: build/C/man2/perf_event_open.2:30
1811 msgid "perf_event_open - set up performance monitoring"
1812 msgstr ""
1813
1814 #. type: Plain text
1815 #: build/C/man2/perf_event_open.2:34
1816 #, no-wrap
1817 msgid ""
1818 "B<#include E<lt>linux/perf_event.hE<gt>>\n"
1819 "B<#include E<lt>linux/hw_breakpoint.hE<gt>>\n"
1820 msgstr ""
1821
1822 #. type: Plain text
1823 #: build/C/man2/perf_event_open.2:38
1824 #, no-wrap
1825 msgid ""
1826 "B<int perf_event_open(struct perf_event_attr *>I<attr>B<,>\n"
1827 "B<                    pid_t >I<pid>B<, int >I<cpu>B<, int >I<group_fd>B<,>\n"
1828 "B<                    unsigned long >I<flags>B<);>\n"
1829 msgstr ""
1830
1831 #. type: Plain text
1832 #: build/C/man2/perf_event_open.2:47
1833 msgid ""
1834 "Given a list of parameters, B<perf_event_open>()  returns a file descriptor, "
1835 "for use in subsequent system calls (B<read>(2), B<mmap>(2), B<prctl>(2), "
1836 "B<fcntl>(2), etc.)."
1837 msgstr ""
1838
1839 #. type: Plain text
1840 #: build/C/man2/perf_event_open.2:55
1841 msgid ""
1842 "A call to B<perf_event_open>()  creates a file descriptor that allows "
1843 "measuring performance information.  Each file descriptor corresponds to one "
1844 "event that is measured; these can be grouped together to measure multiple "
1845 "events simultaneously."
1846 msgstr ""
1847
1848 #. type: Plain text
1849 #: build/C/man2/perf_event_open.2:62
1850 msgid ""
1851 "Events can be enabled and disabled in two ways: via B<ioctl>(2)  and via "
1852 "B<prctl>(2)B<.> When an event is disabled it does not count or generate "
1853 "overflows but does continue to exist and maintain its count value."
1854 msgstr ""
1855
1856 #. type: Plain text
1857 #: build/C/man2/perf_event_open.2:76
1858 msgid ""
1859 "Events come in two flavors: counting and sampled.  A I<counting> event is "
1860 "one that is used for counting the aggregate number of events that occur.  In "
1861 "general, counting event results are gathered with a B<read>(2)  call.  A "
1862 "I<sampling> event periodically writes measurements to a buffer that can then "
1863 "be accessed via B<mmap>(2)B<.>"
1864 msgstr ""
1865
1866 #. type: SS
1867 #: build/C/man2/perf_event_open.2:76
1868 #, no-wrap
1869 msgid "Arguments"
1870 msgstr ""
1871
1872 #. type: Plain text
1873 #: build/C/man2/perf_event_open.2:90
1874 msgid ""
1875 "The argument I<pid> allows events to be attached to processes in various "
1876 "ways.  If I<pid> is 0, measurements happen on the current thread, if I<pid> "
1877 "is greater than 0, the process indicated by I<pid> is measured, and if "
1878 "I<pid> is -1, all processes are counted."
1879 msgstr ""
1880
1881 #. type: Plain text
1882 #: build/C/man2/perf_event_open.2:101
1883 msgid ""
1884 "The I<cpu> argument allows measurements to be specific to a CPU.  If I<cpu> "
1885 "is greater than or equal to 0, measurements are restricted to the specified "
1886 "CPU; if I<cpu> is -1, the events are measured on all CPUs."
1887 msgstr ""
1888
1889 #. type: Plain text
1890 #: build/C/man2/perf_event_open.2:107
1891 msgid "Note that the combination of I<pid> == -1 and I<cpu> == -1 is not valid."
1892 msgstr ""
1893
1894 #. type: Plain text
1895 #: build/C/man2/perf_event_open.2:115
1896 msgid ""
1897 "A I<pid> E<gt> 0 and I<cpu> == -1 setting measures per-process and follows "
1898 "that process to whatever CPU the process gets scheduled to.  Per-process "
1899 "events can be created by any user."
1900 msgstr ""
1901
1902 #. type: Plain text
1903 #: build/C/man2/perf_event_open.2:126
1904 msgid ""
1905 "A I<pid> == -1 and I<cpu> E<gt>= 0 setting is per-CPU and measures all "
1906 "processes on the specified CPU.  Per-CPU events need the B<CAP_SYS_ADMIN> "
1907 "capability or a I</proc/sys/kernel/perf_event_paranoid> value of less than "
1908 "1."
1909 msgstr ""
1910
1911 #. type: Plain text
1912 #: build/C/man2/perf_event_open.2:148
1913 msgid ""
1914 "The I<group_fd> argument allows event groups to be created.  An event group "
1915 "has one event which is the group leader.  The leader is created first, with "
1916 "I<group_fd> = -1.  The rest of the group members are created with subsequent "
1917 "B<perf_event_open>()  calls with I<group_fd> being set to the fd of the "
1918 "group leader.  (A single event on its own is created with I<group_fd> = -1 "
1919 "and is considered to be a group with only 1 member.)  An event group is "
1920 "scheduled onto the CPU as a unit: it will be put onto the CPU only if all of "
1921 "the events in the group can be put onto the CPU.  This means that the values "
1922 "of the member events can be meaningfully compared, added, divided (to get "
1923 "ratios), etc., with each other, since they have counted events for the same "
1924 "set of executed instructions."
1925 msgstr ""
1926
1927 #. type: Plain text
1928 #: build/C/man2/perf_event_open.2:152
1929 msgid ""
1930 "The I<flags> argument is formed by ORing together zero or more of the "
1931 "following values:"
1932 msgstr ""
1933
1934 #. type: TP
1935 #: build/C/man2/perf_event_open.2:152
1936 #, no-wrap
1937 msgid "B<PERF_FLAG_FD_NO_GROUP>"
1938 msgstr ""
1939
1940 #.  FIXME The following sentence is unclear
1941 #.  FIXME So, why is it useful?
1942 #. type: Plain text
1943 #: build/C/man2/perf_event_open.2:159
1944 msgid ""
1945 "This flag allows creating an event as part of an event group but having no "
1946 "group leader.  It is unclear why this is useful."
1947 msgstr ""
1948
1949 #. type: TP
1950 #: build/C/man2/perf_event_open.2:159
1951 #, no-wrap
1952 msgid "B<PERF_FLAG_FD_OUTPUT>"
1953 msgstr ""
1954
1955 #. type: Plain text
1956 #: build/C/man2/perf_event_open.2:162
1957 msgid "This flag re-routes the output from an event to the group leader."
1958 msgstr ""
1959
1960 #. type: TP
1961 #: build/C/man2/perf_event_open.2:162
1962 #, no-wrap
1963 msgid "B<PERF_FLAG_PID_CGROUP> (Since Linux 2.6.39)."
1964 msgstr ""
1965
1966 #. type: Plain text
1967 #: build/C/man2/perf_event_open.2:185
1968 msgid ""
1969 "This flag activates per-container system-wide monitoring.  A container is an "
1970 "abstraction that isolates a set of resources for finer grain control (CPUs, "
1971 "memory, etc.).  In this mode, the event is measured only if the thread "
1972 "running on the monitored CPU belongs to the designated container (cgroup).  "
1973 "The cgroup is identified by passing a file descriptor opened on its "
1974 "directory in the cgroupfs filesystem.  For instance, if the cgroup to "
1975 "monitor is called I<test>, then a file descriptor opened on "
1976 "I</dev/cgroup/test> (assuming cgroupfs is mounted on I</dev/cgroup>)  must "
1977 "be passed as the I<pid> parameter.  cgroup monitoring is available only for "
1978 "system-wide events and may therefore require extra permissions."
1979 msgstr ""
1980
1981 #. type: Plain text
1982 #: build/C/man2/perf_event_open.2:190
1983 msgid ""
1984 "The I<perf_event_attr> structure provides detailed configuration information "
1985 "for the event being created."
1986 msgstr ""
1987
1988 #. type: Plain text
1989 #: build/C/man2/perf_event_open.2:197
1990 #, no-wrap
1991 msgid ""
1992 "struct perf_event_attr {\n"
1993 "    __u32     type;         /* Type of event */\n"
1994 "    __u32     size;         /* Size of attribute structure */\n"
1995 "    __u64     config;       /* Type-specific configuration */\n"
1996 msgstr ""
1997
1998 #. type: Plain text
1999 #: build/C/man2/perf_event_open.2:202
2000 #, no-wrap
2001 msgid ""
2002 "    union {\n"
2003 "        __u64 sample_period;    /* Period of sampling */\n"
2004 "        __u64 sample_freq;      /* Frequency of sampling */\n"
2005 "    };\n"
2006 msgstr ""
2007
2008 #. type: Plain text
2009 #: build/C/man2/perf_event_open.2:205
2010 #, no-wrap
2011 msgid ""
2012 "    __u64     sample_type;  /* Specifies values included in sample */\n"
2013 "    __u64     read_format;  /* Specifies values returned in read */\n"
2014 msgstr ""
2015
2016 #. type: Plain text
2017 #: build/C/man2/perf_event_open.2:231
2018 #, no-wrap
2019 msgid ""
2020 "    __u64     disabled       : 1,   /* off by default */\n"
2021 "              inherit        : 1,   /* children inherit it */\n"
2022 "              pinned         : 1,   /* must always be on PMU */\n"
2023 "              exclusive      : 1,   /* only group on PMU */\n"
2024 "              exclude_user   : 1,   /* don't count user */\n"
2025 "              exclude_kernel : 1,   /* don't count kernel */\n"
2026 "              exclude_hv     : 1,   /* don't count hypervisor */\n"
2027 "              exclude_idle   : 1,   /* don't count when idle */\n"
2028 "              mmap           : 1,   /* include mmap data */\n"
2029 "              comm           : 1,   /* include comm data */\n"
2030 "              freq           : 1,   /* use freq, not period */\n"
2031 "              inherit_stat   : 1,   /* per task counts */\n"
2032 "              enable_on_exec : 1,   /* next exec enables */\n"
2033 "              task           : 1,   /* trace fork/exit */\n"
2034 "              watermark      : 1,   /* wakeup_watermark */\n"
2035 "              precise_ip     : 2,   /* skid constraint */\n"
2036 "              mmap_data      : 1,   /* non-exec mmap data */\n"
2037 "              sample_id_all  : 1,   /* sample_type all events */\n"
2038 "              exclude_host   : 1,   /* don't count in host */\n"
2039 "              exclude_guest  : 1,   /* don't count in guest */\n"
2040 "              exclude_callchain_kernel : 1,\n"
2041 "                                    /* exclude kernel callchains */\n"
2042 "              exclude_callchain_user   : 1,\n"
2043 "\t                            /* exclude user callchains */\n"
2044 "              __reserved_1   : 41;\n"
2045 msgstr ""
2046
2047 #. type: Plain text
2048 #: build/C/man2/perf_event_open.2:236
2049 #, no-wrap
2050 msgid ""
2051 "    union {\n"
2052 "        __u32 wakeup_events;    /* wakeup every n events */\n"
2053 "        __u32 wakeup_watermark; /* bytes before wakeup */\n"
2054 "    };\n"
2055 msgstr ""
2056
2057 #. type: Plain text
2058 #: build/C/man2/perf_event_open.2:238
2059 #, no-wrap
2060 msgid "    __u32     bp_type;          /* breakpoint type */\n"
2061 msgstr ""
2062
2063 #. type: Plain text
2064 #: build/C/man2/perf_event_open.2:243
2065 #, no-wrap
2066 msgid ""
2067 "    union {\n"
2068 "        __u64 bp_addr;          /* breakpoint address */\n"
2069 "        __u64 config1;          /* extension of config */\n"
2070 "    };\n"
2071 msgstr ""
2072
2073 #. type: Plain text
2074 #: build/C/man2/perf_event_open.2:253
2075 #, no-wrap
2076 msgid ""
2077 "    union {\n"
2078 "        __u64 bp_len;           /* breakpoint length */\n"
2079 "        __u64 config2;          /* extension of config1 */\n"
2080 "    };\n"
2081 "    __u64   branch_sample_type; /* enum perf_branch_sample_type */\n"
2082 "    __u64   sample_regs_user;   /* user regs to dump on samples */\n"
2083 "    __u32   sample_stack_user;  /* size of stack to dump on\n"
2084 "                                   samples */\n"
2085 "    __u32   __reserved_2;       /* Align to u64 */\n"
2086 msgstr ""
2087
2088 #. type: Plain text
2089 #: build/C/man2/perf_event_open.2:255
2090 #, no-wrap
2091 msgid "};\n"
2092 msgstr ""
2093
2094 #. type: Plain text
2095 #: build/C/man2/perf_event_open.2:261
2096 msgid ""
2097 "The fields of the I<perf_event_attr> structure are described in more detail "
2098 "below:"
2099 msgstr ""
2100
2101 #. type: TP
2102 #: build/C/man2/perf_event_open.2:261 build/C/man2/perf_event_open.2:1379
2103 #, no-wrap
2104 msgid "I<type>"
2105 msgstr ""
2106
2107 #. type: Plain text
2108 #: build/C/man2/perf_event_open.2:265
2109 msgid ""
2110 "This field specifies the overall event type.  It has one of the following "
2111 "values:"
2112 msgstr ""
2113
2114 #. type: TP
2115 #: build/C/man2/perf_event_open.2:266
2116 #, no-wrap
2117 msgid "B<PERF_TYPE_HARDWARE>"
2118 msgstr ""
2119
2120 #. type: Plain text
2121 #: build/C/man2/perf_event_open.2:273
2122 msgid ""
2123 "This indicates one of the \"generalized\" hardware events provided by the "
2124 "kernel.  See the I<config> field definition for more details."
2125 msgstr ""
2126
2127 #. type: TP
2128 #: build/C/man2/perf_event_open.2:273
2129 #, no-wrap
2130 msgid "B<PERF_TYPE_SOFTWARE>"
2131 msgstr ""
2132
2133 #. type: Plain text
2134 #: build/C/man2/perf_event_open.2:277
2135 msgid ""
2136 "This indicates one of the software-defined events provided by the kernel "
2137 "(even if no hardware support is available)."
2138 msgstr ""
2139
2140 #. type: TP
2141 #: build/C/man2/perf_event_open.2:277
2142 #, no-wrap
2143 msgid "B<PERF_TYPE_TRACEPOINT>"
2144 msgstr ""
2145
2146 #. type: Plain text
2147 #: build/C/man2/perf_event_open.2:281
2148 msgid ""
2149 "This indicates a tracepoint provided by the kernel tracepoint "
2150 "infrastructure."
2151 msgstr ""
2152
2153 #. type: TP
2154 #: build/C/man2/perf_event_open.2:281
2155 #, no-wrap
2156 msgid "B<PERF_TYPE_HW_CACHE>"
2157 msgstr ""
2158
2159 #. type: Plain text
2160 #: build/C/man2/perf_event_open.2:287
2161 msgid ""
2162 "This indicates a hardware cache event.  This has a special encoding, "
2163 "described in the I<config> field definition."
2164 msgstr ""
2165
2166 #. type: TP
2167 #: build/C/man2/perf_event_open.2:287
2168 #, no-wrap
2169 msgid "B<PERF_TYPE_RAW>"
2170 msgstr ""
2171
2172 #. type: Plain text
2173 #: build/C/man2/perf_event_open.2:291
2174 msgid ""
2175 "This indicates a \"raw\" implementation-specific event in the I<config> "
2176 "field."
2177 msgstr ""
2178
2179 #. type: TP
2180 #: build/C/man2/perf_event_open.2:291
2181 #, no-wrap
2182 msgid "B<PERF_TYPE_BREAKPOINT> (Since Linux 2.6.33)"
2183 msgstr ""
2184
2185 #. type: Plain text
2186 #: build/C/man2/perf_event_open.2:296
2187 msgid ""
2188 "This indicates a hardware breakpoint as provided by the CPU.  Breakpoints "
2189 "can be read/write accesses to an address as well as execution of an "
2190 "instruction address."
2191 msgstr ""
2192
2193 #. type: TP
2194 #: build/C/man2/perf_event_open.2:296
2195 #, no-wrap
2196 msgid "dynamic PMU"
2197 msgstr ""
2198
2199 #. type: Plain text
2200 #: build/C/man2/perf_event_open.2:315
2201 msgid ""
2202 "Since Linux 2.6.39, B<perf_event_open>()  can support multiple PMUs.  To "
2203 "enable this, a value exported by the kernel can be used in the I<type> field "
2204 "to indicate which PMU to use.  The value to use can be found in the sysfs "
2205 "filesystem: there is a subdirectory per PMU instance under "
2206 "I</sys/bus/event_source/devices>.  In each sub-directory there is a I<type> "
2207 "file whose content is an integer that can be used in the I<type> field.  For "
2208 "instance, I</sys/bus/event_source/devices/cpu/type> contains the value for "
2209 "the core CPU PMU, which is usually 4."
2210 msgstr ""
2211
2212 #. type: TP
2213 #: build/C/man2/perf_event_open.2:316 build/C/man2/perf_event_open.2:1327
2214 #, no-wrap
2215 msgid "I<size>"
2216 msgstr ""
2217
2218 #. type: Plain text
2219 #: build/C/man2/perf_event_open.2:325
2220 msgid ""
2221 "The size of the I<perf_event_attr> structure for forward/backward "
2222 "compatibility.  Set this using I<sizeof(struct perf_event_attr)> to allow "
2223 "the kernel to see the struct size at the time of compilation."
2224 msgstr ""
2225
2226 #. type: Plain text
2227 #: build/C/man2/perf_event_open.2:340
2228 msgid ""
2229 "The related define B<PERF_ATTR_SIZE_VER0> is set to 64; this was the size of "
2230 "the first published struct.  B<PERF_ATTR_SIZE_VER1> is 72, corresponding to "
2231 "the addition of breakpoints in Linux 2.6.33.  B<PERF_ATTR_SIZE_VER2> is 80 "
2232 "corresponding to the addition of branch sampling in Linux 3.4.  "
2233 "B<PERF_ATR_SIZE_VER3> is 96 corresponding to the addition of "
2234 "I<sample_regs_user> and I<sample_stack_user> in Linux 3.7."
2235 msgstr ""
2236
2237 #. type: TP
2238 #: build/C/man2/perf_event_open.2:340
2239 #, no-wrap
2240 msgid "I<config>"
2241 msgstr ""
2242
2243 #. type: Plain text
2244 #: build/C/man2/perf_event_open.2:351
2245 msgid ""
2246 "This specifies which event you want, in conjunction with the I<type> field.  "
2247 "The I<config1> and I<config2> fields are also taken into account in cases "
2248 "where 64 bits is not enough to fully specify the event.  The encoding of "
2249 "these fields are event dependent."
2250 msgstr ""
2251
2252 #. type: Plain text
2253 #: build/C/man2/perf_event_open.2:357
2254 msgid ""
2255 "The most significant bit (bit 63) of I<config> signifies CPU-specific (raw) "
2256 "counter configuration data; if the most significant bit is unset, the next 7 "
2257 "bits are an event type and the rest of the bits are the event identifier."
2258 msgstr ""
2259
2260 #. type: Plain text
2261 #: build/C/man2/perf_event_open.2:368
2262 msgid ""
2263 "There are various ways to set the I<config> field that are dependent on the "
2264 "value of the previously described I<type> field.  What follows are various "
2265 "possible settings for I<config> separated out by I<type>."
2266 msgstr ""
2267
2268 #. type: Plain text
2269 #: build/C/man2/perf_event_open.2:378
2270 msgid ""
2271 "If I<type> is B<PERF_TYPE_HARDWARE>, we are measuring one of the generalized "
2272 "hardware CPU events.  Not all of these are available on all platforms.  Set "
2273 "I<config> to one of the following:"
2274 msgstr ""
2275
2276 #. type: TP
2277 #: build/C/man2/perf_event_open.2:379
2278 #, no-wrap
2279 msgid "B<PERF_COUNT_HW_CPU_CYCLES>"
2280 msgstr ""
2281
2282 #. type: Plain text
2283 #: build/C/man2/perf_event_open.2:383
2284 msgid "Total cycles.  Be wary of what happens during CPU frequency scaling."
2285 msgstr ""
2286
2287 #. type: TP
2288 #: build/C/man2/perf_event_open.2:383
2289 #, no-wrap
2290 msgid "B<PERF_COUNT_HW_INSTRUCTIONS>"
2291 msgstr ""
2292
2293 #. type: Plain text
2294 #: build/C/man2/perf_event_open.2:388
2295 msgid ""
2296 "Retired instructions.  Be careful, these can be affected by various issues, "
2297 "most notably hardware interrupt counts."
2298 msgstr ""
2299
2300 #. type: TP
2301 #: build/C/man2/perf_event_open.2:388
2302 #, no-wrap
2303 msgid "B<PERF_COUNT_HW_CACHE_REFERENCES>"
2304 msgstr ""
2305
2306 #. type: Plain text
2307 #: build/C/man2/perf_event_open.2:395
2308 msgid ""
2309 "Cache accesses.  Usually this indicates Last Level Cache accesses but this "
2310 "may vary depending on your CPU.  This may include prefetches and coherency "
2311 "messages; again this depends on the design of your CPU."
2312 msgstr ""
2313
2314 #. type: TP
2315 #: build/C/man2/perf_event_open.2:395
2316 #, no-wrap
2317 msgid "B<PERF_COUNT_HW_CACHE_MISSES>"
2318 msgstr ""
2319
2320 #. type: Plain text
2321 #: build/C/man2/perf_event_open.2:402
2322 msgid ""
2323 "Cache misses.  Usually this indicates Last Level Cache misses; this is "
2324 "intended to be used in conjunction with the "
2325 "B<PERF_COUNT_HW_CACHE_REFERENCES> event to calculate cache miss rates."
2326 msgstr ""
2327
2328 #. type: TP
2329 #: build/C/man2/perf_event_open.2:402
2330 #, no-wrap
2331 msgid "B<PERF_COUNT_HW_BRANCH_INSTRUCTIONS>"
2332 msgstr ""
2333
2334 #. type: Plain text
2335 #: build/C/man2/perf_event_open.2:407
2336 msgid ""
2337 "Retired branch instructions.  Prior to Linux 2.6.34, this used the wrong "
2338 "event on AMD processors."
2339 msgstr ""
2340
2341 #. type: TP
2342 #: build/C/man2/perf_event_open.2:407
2343 #, no-wrap
2344 msgid "B<PERF_COUNT_HW_BRANCH_MISSES>"
2345 msgstr ""
2346
2347 #. type: Plain text
2348 #: build/C/man2/perf_event_open.2:410
2349 msgid "Mispredicted branch instructions."
2350 msgstr ""
2351
2352 #. type: TP
2353 #: build/C/man2/perf_event_open.2:410
2354 #, no-wrap
2355 msgid "B<PERF_COUNT_HW_BUS_CYCLES>"
2356 msgstr ""
2357
2358 #. type: Plain text
2359 #: build/C/man2/perf_event_open.2:413
2360 msgid "Bus cycles, which can be different from total cycles."
2361 msgstr ""
2362
2363 #. type: TP
2364 #: build/C/man2/perf_event_open.2:413
2365 #, no-wrap
2366 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_FRONTEND> (Since Linux 3.0)"
2367 msgstr ""
2368
2369 #. type: Plain text
2370 #: build/C/man2/perf_event_open.2:416
2371 msgid "Stalled cycles during issue."
2372 msgstr ""
2373
2374 #. type: TP
2375 #: build/C/man2/perf_event_open.2:416
2376 #, no-wrap
2377 msgid "B<PERF_COUNT_HW_STALLED_CYCLES_BACKEND> (Since Linux 3.0)"
2378 msgstr ""
2379
2380 #. type: Plain text
2381 #: build/C/man2/perf_event_open.2:419
2382 msgid "Stalled cycles during retirement."
2383 msgstr ""
2384
2385 #. type: TP
2386 #: build/C/man2/perf_event_open.2:419
2387 #, no-wrap
2388 msgid "B<PERF_COUNT_HW_REF_CPU_CYCLES> (Since Linux 3.3)"
2389 msgstr ""
2390
2391 #. type: Plain text
2392 #: build/C/man2/perf_event_open.2:422
2393 msgid "Total cycles; not affected by CPU frequency scaling."
2394 msgstr ""
2395
2396 #. type: Plain text
2397 #: build/C/man2/perf_event_open.2:432
2398 msgid ""
2399 "If I<type> is B<PERF_TYPE_SOFTWARE>, we are measuring software events "
2400 "provided by the kernel.  Set I<config> to one of the following:"
2401 msgstr ""
2402
2403 #. type: TP
2404 #: build/C/man2/perf_event_open.2:433
2405 #, no-wrap
2406 msgid "B<PERF_COUNT_SW_CPU_CLOCK>"
2407 msgstr ""
2408
2409 #. type: Plain text
2410 #: build/C/man2/perf_event_open.2:436
2411 msgid "This reports the CPU clock, a high-resolution per-CPU timer."
2412 msgstr ""
2413
2414 #. type: TP
2415 #: build/C/man2/perf_event_open.2:436
2416 #, no-wrap
2417 msgid "B<PERF_COUNT_SW_TASK_CLOCK>"
2418 msgstr ""
2419
2420 #. type: Plain text
2421 #: build/C/man2/perf_event_open.2:439
2422 msgid "This reports a clock count specific to the task that is running."
2423 msgstr ""
2424
2425 #. type: TP
2426 #: build/C/man2/perf_event_open.2:439
2427 #, no-wrap
2428 msgid "B<PERF_COUNT_SW_PAGE_FAULTS>"
2429 msgstr ""
2430
2431 #. type: Plain text
2432 #: build/C/man2/perf_event_open.2:442
2433 msgid "This reports the number of page faults."
2434 msgstr ""
2435
2436 #. type: TP
2437 #: build/C/man2/perf_event_open.2:442
2438 #, no-wrap
2439 msgid "B<PERF_COUNT_SW_CONTEXT_SWITCHES>"
2440 msgstr ""
2441
2442 #. type: Plain text
2443 #: build/C/man2/perf_event_open.2:447
2444 msgid ""
2445 "This counts context switches.  Until Linux 2.6.34, these were all reported "
2446 "as user-space events, after that they are reported as happening in the "
2447 "kernel."
2448 msgstr ""
2449
2450 #. type: TP
2451 #: build/C/man2/perf_event_open.2:447
2452 #, no-wrap
2453 msgid "B<PERF_COUNT_SW_CPU_MIGRATIONS>"
2454 msgstr ""
2455
2456 #. type: Plain text
2457 #: build/C/man2/perf_event_open.2:451
2458 msgid "This reports the number of times the process has migrated to a new CPU."
2459 msgstr ""
2460
2461 #. type: TP
2462 #: build/C/man2/perf_event_open.2:451
2463 #, no-wrap
2464 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MIN>"
2465 msgstr ""
2466
2467 #. type: Plain text
2468 #: build/C/man2/perf_event_open.2:455
2469 msgid ""
2470 "This counts the number of minor page faults.  These did not require disk I/O "
2471 "to handle."
2472 msgstr ""
2473
2474 #. type: TP
2475 #: build/C/man2/perf_event_open.2:455
2476 #, no-wrap
2477 msgid "B<PERF_COUNT_SW_PAGE_FAULTS_MAJ>"
2478 msgstr ""
2479
2480 #. type: Plain text
2481 #: build/C/man2/perf_event_open.2:459
2482 msgid ""
2483 "This counts the number of major page faults.  These required disk I/O to "
2484 "handle."
2485 msgstr ""
2486
2487 #. type: TP
2488 #: build/C/man2/perf_event_open.2:459
2489 #, no-wrap
2490 msgid "B<PERF_COUNT_SW_ALIGNMENT_FAULTS> (Since Linux 2.6.33)"
2491 msgstr ""
2492
2493 #. type: Plain text
2494 #: build/C/man2/perf_event_open.2:465
2495 msgid ""
2496 "This counts the number of alignment faults.  These happen when unaligned "
2497 "memory accesses happen; the kernel can handle these but it reduces "
2498 "performance.  This happens only on some architectures (never on x86)."
2499 msgstr ""
2500
2501 #. type: TP
2502 #: build/C/man2/perf_event_open.2:465
2503 #, no-wrap
2504 msgid "B<PERF_COUNT_SW_EMULATION_FAULTS> (Since Linux 2.6.33)"
2505 msgstr ""
2506
2507 #. type: Plain text
2508 #: build/C/man2/perf_event_open.2:471
2509 msgid ""
2510 "This counts the number of emulation faults.  The kernel sometimes traps on "
2511 "unimplemented instructions and emulates them for user space.  This can "
2512 "negatively impact performance."
2513 msgstr ""
2514
2515 #. type: Plain text
2516 #: build/C/man2/perf_event_open.2:484
2517 msgid ""
2518 "If I<type> is B<PERF_TYPE_TRACEPOINT>, then we are measuring kernel "
2519 "tracepoints.  The value to use in I<config> can be obtained from under "
2520 "debugfs I<tracing/events/*/*/id> if ftrace is enabled in the kernel."
2521 msgstr ""
2522
2523 #. type: Plain text
2524 #: build/C/man2/perf_event_open.2:495
2525 msgid ""
2526 "If I<type> is B<PERF_TYPE_HW_CACHE>, then we are measuring a hardware CPU "
2527 "cache event.  To calculate the appropriate I<config> value use the following "
2528 "equation:"
2529 msgstr ""
2530
2531 #. type: Plain text
2532 #: build/C/man2/perf_event_open.2:500
2533 #, no-wrap
2534 msgid ""
2535 "    (perf_hw_cache_id) | (perf_hw_cache_op_id E<lt>E<lt> 8) |\n"
2536 "    (perf_hw_cache_op_result_id E<lt>E<lt> 16)\n"
2537 msgstr ""
2538
2539 #. type: Plain text
2540 #: build/C/man2/perf_event_open.2:505
2541 msgid "where I<perf_hw_cache_id> is one of:"
2542 msgstr ""
2543
2544 #. type: TP
2545 #: build/C/man2/perf_event_open.2:506
2546 #, no-wrap
2547 msgid "B<PERF_COUNT_HW_CACHE_L1D>"
2548 msgstr ""
2549
2550 #. type: Plain text
2551 #: build/C/man2/perf_event_open.2:509
2552 msgid "for measuring Level 1 Data Cache"
2553 msgstr ""
2554
2555 #. type: TP
2556 #: build/C/man2/perf_event_open.2:509
2557 #, no-wrap
2558 msgid "B<PERF_COUNT_HW_CACHE_L1I>"
2559 msgstr ""
2560
2561 #. type: Plain text
2562 #: build/C/man2/perf_event_open.2:512
2563 msgid "for measuring Level 1 Instruction Cache"
2564 msgstr ""
2565
2566 #. type: TP
2567 #: build/C/man2/perf_event_open.2:512
2568 #, no-wrap
2569 msgid "B<PERF_COUNT_HW_CACHE_LL>"
2570 msgstr ""
2571
2572 #. type: Plain text
2573 #: build/C/man2/perf_event_open.2:515
2574 msgid "for measuring Last-Level Cache"
2575 msgstr ""
2576
2577 #. type: TP
2578 #: build/C/man2/perf_event_open.2:515
2579 #, no-wrap
2580 msgid "B<PERF_COUNT_HW_CACHE_DTLB>"
2581 msgstr ""
2582
2583 #. type: Plain text
2584 #: build/C/man2/perf_event_open.2:518
2585 msgid "for measuring the Data TLB"
2586 msgstr ""
2587
2588 #. type: TP
2589 #: build/C/man2/perf_event_open.2:518
2590 #, no-wrap
2591 msgid "B<PERF_COUNT_HW_CACHE_ITLB>"
2592 msgstr ""
2593
2594 #. type: Plain text
2595 #: build/C/man2/perf_event_open.2:521
2596 msgid "for measuring the Instruction TLB"
2597 msgstr ""
2598
2599 #. type: TP
2600 #: build/C/man2/perf_event_open.2:521
2601 #, no-wrap
2602 msgid "B<PERF_COUNT_HW_CACHE_BPU>"
2603 msgstr ""
2604
2605 #. type: Plain text
2606 #: build/C/man2/perf_event_open.2:524
2607 msgid "for measuring the branch prediction unit"
2608 msgstr ""
2609
2610 #. type: TP
2611 #: build/C/man2/perf_event_open.2:524
2612 #, no-wrap
2613 msgid "B<PERF_COUNT_HW_CACHE_NODE> (Since Linux 3.0)"
2614 msgstr ""
2615
2616 #. type: Plain text
2617 #: build/C/man2/perf_event_open.2:527
2618 msgid "for measuring local memory accesses"
2619 msgstr ""
2620
2621 #. type: Plain text
2622 #: build/C/man2/perf_event_open.2:532
2623 msgid "and I<perf_hw_cache_op_id> is one of"
2624 msgstr ""
2625
2626 #. type: TP
2627 #: build/C/man2/perf_event_open.2:533
2628 #, no-wrap
2629 msgid "B<PERF_COUNT_HW_CACHE_OP_READ>"
2630 msgstr ""
2631
2632 #. type: Plain text
2633 #: build/C/man2/perf_event_open.2:536
2634 msgid "for read accesses"
2635 msgstr ""
2636
2637 #. type: TP
2638 #: build/C/man2/perf_event_open.2:536
2639 #, no-wrap
2640 msgid "B<PERF_COUNT_HW_CACHE_OP_WRITE>"
2641 msgstr ""
2642
2643 #. type: Plain text
2644 #: build/C/man2/perf_event_open.2:539
2645 msgid "for write accesses"
2646 msgstr ""
2647
2648 #. type: TP
2649 #: build/C/man2/perf_event_open.2:539
2650 #, no-wrap
2651 msgid "B<PERF_COUNT_HW_CACHE_OP_PREFETCH>"
2652 msgstr ""
2653
2654 #. type: Plain text
2655 #: build/C/man2/perf_event_open.2:542
2656 msgid "for prefetch accesses"
2657 msgstr ""
2658
2659 #. type: Plain text
2660 #: build/C/man2/perf_event_open.2:547
2661 msgid "and I<perf_hw_cache_op_result_id> is one of"
2662 msgstr ""
2663
2664 #. type: TP
2665 #: build/C/man2/perf_event_open.2:548
2666 #, no-wrap
2667 msgid "B<PERF_COUNT_HW_CACHE_RESULT_ACCESS>"
2668 msgstr ""
2669
2670 #. type: Plain text
2671 #: build/C/man2/perf_event_open.2:551
2672 msgid "to measure accesses"
2673 msgstr ""
2674
2675 #. type: TP
2676 #: build/C/man2/perf_event_open.2:551
2677 #, no-wrap
2678 msgid "B<PERF_COUNT_HW_CACHE_RESULT_MISS>"
2679 msgstr ""
2680
2681 #. type: Plain text
2682 #: build/C/man2/perf_event_open.2:554
2683 msgid "to measure misses"
2684 msgstr ""
2685
2686 #. type: Plain text
2687 #: build/C/man2/perf_event_open.2:572
2688 msgid ""
2689 "If I<type> is B<PERF_TYPE_RAW>, then a custom \"raw\" I<config> value is "
2690 "needed.  Most CPUs support events that are not covered by the "
2691 "\"generalized\" events.  These are implementation defined; see your CPU "
2692 "manual (for example the Intel Volume 3B documentation or the AMD BIOS and "
2693 "Kernel Developer Guide).  The libpfm4 library can be used to translate from "
2694 "the name in the architectural manuals to the raw hex value "
2695 "B<perf_event_open>()  expects in this field."
2696 msgstr ""
2697
2698 #. type: Plain text
2699 #: build/C/man2/perf_event_open.2:581
2700 msgid ""
2701 "If I<type> is B<PERF_TYPE_BREAKPOINT>, then leave I<config> set to zero.  "
2702 "Its parameters are set in other places."
2703 msgstr ""
2704
2705 #. type: TP
2706 #: build/C/man2/perf_event_open.2:582
2707 #, no-wrap
2708 msgid "I<sample_period>, I<sample_freq>"
2709 msgstr ""
2710
2711 #. type: Plain text
2712 #: build/C/man2/perf_event_open.2:594
2713 msgid ""
2714 "A \"sampling\" counter is one that generates an interrupt every N events, "
2715 "where N is given by I<sample_period>.  A sampling counter has "
2716 "I<sample_period> E<gt> 0.  When an overflow interrupt occurs, requested data "
2717 "is recorded in the mmap buffer.  The I<sample_type> field controls what data "
2718 "is recorded on each interrupt."
2719 msgstr ""
2720
2721 #. type: Plain text
2722 #: build/C/man2/perf_event_open.2:604
2723 msgid ""
2724 "I<sample_freq> can be used if you wish to use frequency rather than period.  "
2725 "In this case you set the I<freq> flag.  The kernel will adjust the sampling "
2726 "period to try and achieve the desired rate.  The rate of adjustment is a "
2727 "timer tick."
2728 msgstr ""
2729
2730 #. type: TP
2731 #: build/C/man2/perf_event_open.2:604
2732 #, no-wrap
2733 msgid "I<sample_type>"
2734 msgstr ""
2735
2736 #. type: Plain text
2737 #: build/C/man2/perf_event_open.2:616
2738 msgid ""
2739 "The various bits in this field specify which values to include in the "
2740 "sample.  They will be recorded in a ring-buffer, which is available to user "
2741 "space using B<mmap>(2).  The order in which the values are saved in the "
2742 "sample are documented in the MMAP Layout subsection below; it is not the "
2743 "I<enum perf_event_sample_format> order."
2744 msgstr ""
2745
2746 #. type: TP
2747 #: build/C/man2/perf_event_open.2:617
2748 #, no-wrap
2749 msgid "B<PERF_SAMPLE_IP>"
2750 msgstr ""
2751
2752 #. type: Plain text
2753 #: build/C/man2/perf_event_open.2:620
2754 msgid "Records instruction pointer."
2755 msgstr ""
2756
2757 #. type: TP
2758 #: build/C/man2/perf_event_open.2:620
2759 #, no-wrap
2760 msgid "B<PERF_SAMPLE_TID>"
2761 msgstr ""
2762
2763 #. type: Plain text
2764 #: build/C/man2/perf_event_open.2:623
2765 msgid "Records the process and thread IDs."
2766 msgstr ""
2767
2768 #. type: TP
2769 #: build/C/man2/perf_event_open.2:623
2770 #, no-wrap
2771 msgid "B<PERF_SAMPLE_TIME>"
2772 msgstr ""
2773
2774 #. type: Plain text
2775 #: build/C/man2/perf_event_open.2:626
2776 msgid "Records a timestamp."
2777 msgstr ""
2778
2779 #. type: TP
2780 #: build/C/man2/perf_event_open.2:626
2781 #, no-wrap
2782 msgid "B<PERF_SAMPLE_ADDR>"
2783 msgstr ""
2784
2785 #. type: Plain text
2786 #: build/C/man2/perf_event_open.2:629
2787 msgid "Records an address, if applicable."
2788 msgstr ""
2789
2790 #. type: TP
2791 #: build/C/man2/perf_event_open.2:629
2792 #, no-wrap
2793 msgid "B<PERF_SAMPLE_READ>"
2794 msgstr ""
2795
2796 #. type: Plain text
2797 #: build/C/man2/perf_event_open.2:632
2798 msgid "Record counter values for all events in a group, not just the group leader."
2799 msgstr ""
2800
2801 #. type: TP
2802 #: build/C/man2/perf_event_open.2:632
2803 #, no-wrap
2804 msgid "B<PERF_SAMPLE_CALLCHAIN>"
2805 msgstr ""
2806
2807 #. type: Plain text
2808 #: build/C/man2/perf_event_open.2:635
2809 msgid "Records the callchain (stack backtrace)."
2810 msgstr ""
2811
2812 #. type: TP
2813 #: build/C/man2/perf_event_open.2:635
2814 #, no-wrap
2815 msgid "B<PERF_SAMPLE_ID>"
2816 msgstr ""
2817
2818 #. type: Plain text
2819 #: build/C/man2/perf_event_open.2:638
2820 msgid "Records a unique ID for the opened event's group leader."
2821 msgstr ""
2822
2823 #. type: TP
2824 #: build/C/man2/perf_event_open.2:638
2825 #, no-wrap
2826 msgid "B<PERF_SAMPLE_CPU>"
2827 msgstr ""
2828
2829 #. type: Plain text
2830 #: build/C/man2/perf_event_open.2:641
2831 msgid "Records CPU number."
2832 msgstr ""
2833
2834 #. type: TP
2835 #: build/C/man2/perf_event_open.2:641
2836 #, no-wrap
2837 msgid "B<PERF_SAMPLE_PERIOD>"
2838 msgstr ""
2839
2840 #. type: Plain text
2841 #: build/C/man2/perf_event_open.2:644
2842 msgid "Records the current sampling period."
2843 msgstr ""
2844
2845 #. type: TP
2846 #: build/C/man2/perf_event_open.2:644
2847 #, no-wrap
2848 msgid "B<PERF_SAMPLE_STREAM_ID>"
2849 msgstr ""
2850
2851 #. type: Plain text
2852 #: build/C/man2/perf_event_open.2:651
2853 msgid ""
2854 "Records a unique ID for the opened event.  Unlike B<PERF_SAMPLE_ID> the "
2855 "actual ID is returned, not the group leader.  This ID is the same as the one "
2856 "returned by PERF_FORMAT_ID."
2857 msgstr ""
2858
2859 #. type: TP
2860 #: build/C/man2/perf_event_open.2:651
2861 #, no-wrap
2862 msgid "B<PERF_SAMPLE_RAW>"
2863 msgstr ""
2864
2865 #. type: Plain text
2866 #: build/C/man2/perf_event_open.2:655
2867 msgid ""
2868 "Records additional data, if applicable.  Usually returned by tracepoint "
2869 "events."
2870 msgstr ""
2871
2872 #. type: TP
2873 #: build/C/man2/perf_event_open.2:655
2874 #, no-wrap
2875 msgid "B<PERF_SAMPLE_BRANCH_STACK> (Since Linux 3.4)"
2876 msgstr ""
2877
2878 #. type: Plain text
2879 #: build/C/man2/perf_event_open.2:660
2880 msgid ""
2881 "This provides a record of recent branches, as provided by CPU branch "
2882 "sampling hardware (such as Intel Last Branch Record).  Not all hardware "
2883 "supports this feature."
2884 msgstr ""
2885
2886 #. type: Plain text
2887 #: build/C/man2/perf_event_open.2:664
2888 msgid ""
2889 "See the I<branch_sample_type> field for how to filter which branches are "
2890 "reported."
2891 msgstr ""
2892
2893 #. type: TP
2894 #: build/C/man2/perf_event_open.2:664
2895 #, no-wrap
2896 msgid "B<PERF_SAMPLE_REGS_USER> (Since Linux 3.7)"
2897 msgstr ""
2898
2899 #. type: Plain text
2900 #: build/C/man2/perf_event_open.2:668
2901 msgid ""
2902 "Records the current user-level CPU register state (the values in the process "
2903 "before the kernel was called)."
2904 msgstr ""
2905
2906 #. type: TP
2907 #: build/C/man2/perf_event_open.2:668
2908 #, no-wrap
2909 msgid "B<PERF_SAMPLE_STACK_USER> (Since Linux 3.7)"
2910 msgstr ""
2911
2912 #. type: Plain text
2913 #: build/C/man2/perf_event_open.2:671
2914 msgid "Records the user level stack, allowing stack unwinding."
2915 msgstr ""
2916
2917 #. type: TP
2918 #: build/C/man2/perf_event_open.2:671
2919 #, no-wrap
2920 msgid "B<PERF_SAMPLE_WEIGHT> (Since Linux 3.10)"
2921 msgstr ""
2922
2923 #. type: Plain text
2924 #: build/C/man2/perf_event_open.2:677
2925 msgid ""
2926 "Records a hardware provided weight value that expresses how costly the "
2927 "sampled event was.  This allows the hardware to highlight expensive events "
2928 "in a profile."
2929 msgstr ""
2930
2931 #. type: TP
2932 #: build/C/man2/perf_event_open.2:677
2933 #, no-wrap
2934 msgid "B<PERF_SAMPLE_DATA_SRC> (Since Linux 3.10)"
2935 msgstr ""
2936
2937 #. type: Plain text
2938 #: build/C/man2/perf_event_open.2:683
2939 msgid ""
2940 "Records the data source: where in the memory hierarchy the data associated "
2941 "with the sampled instruction came from.  This is only available if the "
2942 "underlying hardware supports this feature."
2943 msgstr ""
2944
2945 #. type: TP
2946 #: build/C/man2/perf_event_open.2:684
2947 #, no-wrap
2948 msgid "I<read_format>"
2949 msgstr ""
2950
2951 #. type: Plain text
2952 #: build/C/man2/perf_event_open.2:691
2953 msgid ""
2954 "This field specifies the format of the data returned by B<read>(2)  on a "
2955 "B<perf_event_open>()  file descriptor."
2956 msgstr ""
2957
2958 #. type: TP
2959 #: build/C/man2/perf_event_open.2:692
2960 #, no-wrap
2961 msgid "B<PERF_FORMAT_TOTAL_TIME_ENABLED>"
2962 msgstr ""
2963
2964 #. type: Plain text
2965 #: build/C/man2/perf_event_open.2:699
2966 msgid ""
2967 "Adds the 64-bit I<time_enabled> field.  This can be used to calculate "
2968 "estimated totals if the PMU is overcommitted and multiplexing is happening."
2969 msgstr ""
2970
2971 #. type: TP
2972 #: build/C/man2/perf_event_open.2:699
2973 #, no-wrap
2974 msgid "B<PERF_FORMAT_TOTAL_TIME_RUNNING>"
2975 msgstr ""
2976
2977 #. type: Plain text
2978 #: build/C/man2/perf_event_open.2:706
2979 msgid ""
2980 "Adds the 64-bit I<time_running> field.  This can be used to calculate "
2981 "estimated totals if the PMU is overcommitted and multiplexing is happening."
2982 msgstr ""
2983
2984 #. type: TP
2985 #: build/C/man2/perf_event_open.2:706
2986 #, no-wrap
2987 msgid "B<PERF_FORMAT_ID>"
2988 msgstr ""
2989
2990 #. type: Plain text
2991 #: build/C/man2/perf_event_open.2:709
2992 msgid "Adds a 64-bit unique value that corresponds to the event group."
2993 msgstr ""
2994
2995 #. type: TP
2996 #: build/C/man2/perf_event_open.2:709
2997 #, no-wrap
2998 msgid "B<PERF_FORMAT_GROUP>"
2999 msgstr ""
3000
3001 #. type: Plain text
3002 #: build/C/man2/perf_event_open.2:712
3003 msgid "Allows all counter values in an event group to be read with one read."
3004 msgstr ""
3005
3006 #. type: TP
3007 #: build/C/man2/perf_event_open.2:713
3008 #, no-wrap
3009 msgid "I<disabled>"
3010 msgstr ""
3011
3012 #. type: Plain text
3013 #: build/C/man2/perf_event_open.2:723
3014 msgid ""
3015 "The I<disabled> bit specifies whether the counter starts out disabled or "
3016 "enabled.  If disabled, the event can later be enabled by B<ioctl>(2), "
3017 "B<prctl>(2), or I<enable_on_exec>."
3018 msgstr ""
3019
3020 #. type: TP
3021 #: build/C/man2/perf_event_open.2:723
3022 #, no-wrap
3023 msgid "I<inherit>"
3024 msgstr ""
3025
3026 #. type: Plain text
3027 #: build/C/man2/perf_event_open.2:732
3028 msgid ""
3029 "The I<inherit> bit specifies that this counter should count events of child "
3030 "tasks as well as the task specified.  This applies only to new children, not "
3031 "to any existing children at the time the counter is created (nor to any new "
3032 "children of existing children)."
3033 msgstr ""
3034
3035 #. type: Plain text
3036 #: build/C/man2/perf_event_open.2:737
3037 msgid ""
3038 "Inherit does not work for some combinations of I<read_format>s, such as "
3039 "B<PERF_FORMAT_GROUP>."
3040 msgstr ""
3041
3042 #. type: TP
3043 #: build/C/man2/perf_event_open.2:737
3044 #, no-wrap
3045 msgid "I<pinned>"
3046 msgstr ""
3047
3048 #. type: Plain text
3049 #: build/C/man2/perf_event_open.2:750
3050 msgid ""
3051 "The I<pinned> bit specifies that the counter should always be on the CPU if "
3052 "at all possible.  It applies only to hardware counters and only to group "
3053 "leaders.  If a pinned counter cannot be put onto the CPU (e.g., because "
3054 "there are not enough hardware counters or because of a conflict with some "
3055 "other event), then the counter goes into an 'error' state, where reads "
3056 "return end-of-file (i.e., B<read>(2)  returns 0) until the counter is "
3057 "subsequently enabled or disabled."
3058 msgstr ""
3059
3060 #. type: TP
3061 #: build/C/man2/perf_event_open.2:750
3062 #, no-wrap
3063 msgid "I<exclusive>"
3064 msgstr ""
3065
3066 #. type: Plain text
3067 #: build/C/man2/perf_event_open.2:759
3068 msgid ""
3069 "The I<exclusive> bit specifies that when this counter's group is on the CPU, "
3070 "it should be the only group using the CPU's counters.  In the future this "
3071 "may allow monitoring programs to support PMU features that need to run alone "
3072 "so that they do not disrupt other hardware counters."
3073 msgstr ""
3074
3075 #. type: TP
3076 #: build/C/man2/perf_event_open.2:759
3077 #, no-wrap
3078 msgid "I<exclude_user>"
3079 msgstr ""
3080
3081 #. type: Plain text
3082 #: build/C/man2/perf_event_open.2:762
3083 msgid "If this bit is set, the count excludes events that happen in user space."
3084 msgstr ""
3085
3086 #. type: TP
3087 #: build/C/man2/perf_event_open.2:762
3088 #, no-wrap
3089 msgid "I<exclude_kernel>"
3090 msgstr ""
3091
3092 #. type: Plain text
3093 #: build/C/man2/perf_event_open.2:765
3094 msgid "If this bit is set, the count excludes events that happen in kernel-space."
3095 msgstr ""
3096
3097 #. type: TP
3098 #: build/C/man2/perf_event_open.2:765
3099 #, no-wrap
3100 msgid "I<exclude_hv>"
3101 msgstr ""
3102
3103 #. type: Plain text
3104 #: build/C/man2/perf_event_open.2:773
3105 msgid ""
3106 "If this bit is set, the count excludes events that happen in the "
3107 "hypervisor.  This is mainly for PMUs that have built-in support for handling "
3108 "this (such as POWER).  Extra support is needed for handling hypervisor "
3109 "measurements on most machines."
3110 msgstr ""
3111
3112 #. type: TP
3113 #: build/C/man2/perf_event_open.2:773
3114 #, no-wrap
3115 msgid "I<exclude_idle>"
3116 msgstr ""
3117
3118 #. type: Plain text
3119 #: build/C/man2/perf_event_open.2:776
3120 msgid "If set, don't count when the CPU is idle."
3121 msgstr ""
3122
3123 #. type: TP
3124 #: build/C/man2/perf_event_open.2:776
3125 #, no-wrap
3126 msgid "I<mmap>"
3127 msgstr ""
3128
3129 #. type: Plain text
3130 #: build/C/man2/perf_event_open.2:781
3131 msgid "The I<mmap> bit enables recording of exec mmap events."
3132 msgstr ""
3133
3134 #. type: TP
3135 #: build/C/man2/perf_event_open.2:781
3136 #, no-wrap
3137 msgid "I<comm>"
3138 msgstr ""
3139
3140 #. type: Plain text
3141 #: build/C/man2/perf_event_open.2:792
3142 msgid ""
3143 "The I<comm> bit enables tracking of process command name as modified by the "
3144 "I<exec>(2)  and I<prctl>(PR_SET_NAME)  system calls.  Unfortunately for "
3145 "tools, there is no way to distinguish one system call versus the other."
3146 msgstr ""
3147
3148 #. type: TP
3149 #: build/C/man2/perf_event_open.2:792
3150 #, no-wrap
3151 msgid "I<freq>"
3152 msgstr ""
3153
3154 #. type: Plain text
3155 #: build/C/man2/perf_event_open.2:799
3156 msgid ""
3157 "If this bit is set, then I<sample_frequency> not I<sample_period> is used "
3158 "when setting up the sampling interval."
3159 msgstr ""
3160
3161 #. type: TP
3162 #: build/C/man2/perf_event_open.2:799
3163 #, no-wrap
3164 msgid "I<inherit_stat>"
3165 msgstr ""
3166
3167 #. type: Plain text
3168 #: build/C/man2/perf_event_open.2:806
3169 msgid ""
3170 "This bit enables saving of event counts on context switch for inherited "
3171 "tasks.  This is meaningful only if the I<inherit> field is set."
3172 msgstr ""
3173
3174 #. type: TP
3175 #: build/C/man2/perf_event_open.2:806
3176 #, no-wrap
3177 msgid "I<enable_on_exec>"
3178 msgstr ""
3179
3180 #. type: Plain text
3181 #: build/C/man2/perf_event_open.2:811
3182 msgid ""
3183 "If this bit is set, a counter is automatically enabled after a call to "
3184 "B<exec>(2)."
3185 msgstr ""
3186
3187 #. type: TP
3188 #: build/C/man2/perf_event_open.2:811
3189 #, no-wrap
3190 msgid "I<task>"
3191 msgstr ""
3192
3193 #. type: Plain text
3194 #: build/C/man2/perf_event_open.2:815
3195 msgid ""
3196 "If this bit is set, then fork/exit notifications are included in the ring "
3197 "buffer."
3198 msgstr ""
3199
3200 #. type: TP
3201 #: build/C/man2/perf_event_open.2:815
3202 #, no-wrap
3203 msgid "I<watermark>"
3204 msgstr ""
3205
3206 #. type: Plain text
3207 #: build/C/man2/perf_event_open.2:823
3208 msgid ""
3209 "If set, have a sampling interrupt happen when we cross the "
3210 "I<wakeup_watermark> boundary.  Otherwise interrupts happen after "
3211 "I<wakeup_events> samples."
3212 msgstr ""
3213
3214 #. type: TP
3215 #: build/C/man2/perf_event_open.2:823
3216 #, no-wrap
3217 msgid "I<precise_ip> (Since Linux 2.6.35)"
3218 msgstr ""
3219
3220 #. type: Plain text
3221 #: build/C/man2/perf_event_open.2:833
3222 msgid ""
3223 "This controls the amount of skid.  Skid is how many instructions execute "
3224 "between an event of interest happening and the kernel being able to stop and "
3225 "record the event.  Smaller skid is better and allows more accurate reporting "
3226 "of which events correspond to which instructions, but hardware is often "
3227 "limited with how small this can be."
3228 msgstr ""
3229
3230 #. type: Plain text
3231 #: build/C/man2/perf_event_open.2:835
3232 msgid "The values of this are the following:"
3233 msgstr ""
3234
3235 #. type: TP
3236 #: build/C/man2/perf_event_open.2:836
3237 #, no-wrap
3238 msgid "0 -"
3239 msgstr ""
3240
3241 #. type: Plain text
3242 #: build/C/man2/perf_event_open.2:840
3243 msgid "B<SAMPLE_IP> can have arbitrary skid."
3244 msgstr ""
3245
3246 #. type: TP
3247 #: build/C/man2/perf_event_open.2:840
3248 #, no-wrap
3249 msgid "1 -"
3250 msgstr ""
3251
3252 #. type: Plain text
3253 #: build/C/man2/perf_event_open.2:844
3254 msgid "B<SAMPLE_IP> must have constant skid."
3255 msgstr ""
3256
3257 #. type: TP
3258 #: build/C/man2/perf_event_open.2:844
3259 #, no-wrap
3260 msgid "2 -"
3261 msgstr ""
3262
3263 #. type: Plain text
3264 #: build/C/man2/perf_event_open.2:848
3265 msgid "B<SAMPLE_IP> requested to have 0 skid."
3266 msgstr ""
3267
3268 #. type: TP
3269 #: build/C/man2/perf_event_open.2:848
3270 #, no-wrap
3271 msgid "3 -"
3272 msgstr ""
3273
3274 #. type: Plain text
3275 #: build/C/man2/perf_event_open.2:854
3276 msgid "B<SAMPLE_IP> must have 0 skid.  See also B<PERF_RECORD_MISC_EXACT_IP>."
3277 msgstr ""
3278
3279 #. type: TP
3280 #: build/C/man2/perf_event_open.2:855
3281 #, no-wrap
3282 msgid "I<mmap_data> (Since Linux 2.6.36)"
3283 msgstr ""
3284
3285 #. type: Plain text
3286 #: build/C/man2/perf_event_open.2:861
3287 msgid ""
3288 "The counterpart of the I<mmap> field, but enables including data mmap events "
3289 "in the ring-buffer."
3290 msgstr ""
3291
3292 #. type: TP
3293 #: build/C/man2/perf_event_open.2:861
3294 #, no-wrap
3295 msgid "I<sample_id_all> (Since Linux 2.6.38)"
3296 msgstr ""
3297
3298 #. type: Plain text
3299 #: build/C/man2/perf_event_open.2:869
3300 msgid ""
3301 "If set, then TID, TIME, ID, CPU, and STREAM_ID can additionally be included "
3302 "in non-B<PERF_RECORD_SAMPLE>s if the corresponding I<sample_type> is "
3303 "selected."
3304 msgstr ""
3305
3306 #. type: TP
3307 #: build/C/man2/perf_event_open.2:869
3308 #, no-wrap
3309 msgid "I<exclude_host> (Since Linux 3.2)"
3310 msgstr ""
3311
3312 #. type: Plain text
3313 #: build/C/man2/perf_event_open.2:872
3314 msgid "Do not measure time spent in VM host."
3315 msgstr ""
3316
3317 #. type: TP
3318 #: build/C/man2/perf_event_open.2:872
3319 #, no-wrap
3320 msgid "I<exclude_guest> (Since Linux 3.2)"
3321 msgstr ""
3322
3323 #. type: Plain text
3324 #: build/C/man2/perf_event_open.2:875
3325 msgid "Do not measure time spent in VM guest."
3326 msgstr ""
3327
3328 #. type: TP
3329 #: build/C/man2/perf_event_open.2:875
3330 #, no-wrap
3331 msgid "I<exclude_callchain_kernel> (Since Linux 3.7)"
3332 msgstr ""
3333
3334 #. type: Plain text
3335 #: build/C/man2/perf_event_open.2:878
3336 msgid "Do not include kernel callchains."
3337 msgstr ""
3338
3339 #. type: TP
3340 #: build/C/man2/perf_event_open.2:878
3341 #, no-wrap
3342 msgid "I<exclude_callchain_user> (Since Linux 3.7)"
3343 msgstr ""
3344
3345 #. type: Plain text
3346 #: build/C/man2/perf_event_open.2:881
3347 msgid "Do not include user callchains."
3348 msgstr ""
3349
3350 #. type: TP
3351 #: build/C/man2/perf_event_open.2:881
3352 #, no-wrap
3353 msgid "I<wakeup_events>, I<wakeup_watermark>"
3354 msgstr ""
3355
3356 #. type: Plain text
3357 #: build/C/man2/perf_event_open.2:891
3358 msgid ""
3359 "This union sets how many samples (I<wakeup_events>)  or bytes "
3360 "(I<wakeup_watermark>)  happen before an overflow signal happens.  Which one "
3361 "is used is selected by the I<watermark> bitflag."
3362 msgstr ""
3363
3364 #. type: Plain text
3365 #: build/C/man2/perf_event_open.2:901
3366 msgid ""
3367 "I<wakeup_events> only counts B<PERF_RECORD_SAMPLE> record types.  To receive "
3368 "a signal for every incoming B<PERF_RECORD> type set I<wakeup_watermark> to "
3369 "1."
3370 msgstr ""
3371
3372 #. type: TP
3373 #: build/C/man2/perf_event_open.2:901
3374 #, no-wrap
3375 msgid "I<bp_type> (Since Linux 2.6.33)"
3376 msgstr ""
3377
3378 #. type: Plain text
3379 #: build/C/man2/perf_event_open.2:905
3380 msgid "This chooses the breakpoint type.  It is one of:"
3381 msgstr ""
3382
3383 #. type: TP
3384 #: build/C/man2/perf_event_open.2:906
3385 #, no-wrap
3386 msgid "B<HW_BREAKPOINT_EMPTY>"
3387 msgstr ""
3388
3389 #. type: Plain text
3390 #: build/C/man2/perf_event_open.2:909
3391 msgid "No breakpoint."
3392 msgstr ""
3393
3394 #. type: TP
3395 #: build/C/man2/perf_event_open.2:909
3396 #, no-wrap
3397 msgid "B<HW_BREAKPOINT_R>"
3398 msgstr ""
3399
3400 #. type: Plain text
3401 #: build/C/man2/perf_event_open.2:912
3402 msgid "Count when we read the memory location."
3403 msgstr ""
3404
3405 #. type: TP
3406 #: build/C/man2/perf_event_open.2:912
3407 #, no-wrap
3408 msgid "B<HW_BREAKPOINT_W>"
3409 msgstr ""
3410
3411 #. type: Plain text
3412 #: build/C/man2/perf_event_open.2:915
3413 msgid "Count when we write the memory location."
3414 msgstr ""
3415
3416 #. type: TP
3417 #: build/C/man2/perf_event_open.2:915
3418 #, no-wrap
3419 msgid "B<HW_BREAKPOINT_RW>"
3420 msgstr ""
3421
3422 #. type: Plain text
3423 #: build/C/man2/perf_event_open.2:918
3424 msgid "Count when we read or write the memory location."
3425 msgstr ""
3426
3427 #. type: TP
3428 #: build/C/man2/perf_event_open.2:918
3429 #, no-wrap
3430 msgid "B<HW_BREAKPOINT_X>"
3431 msgstr ""
3432
3433 #. type: Plain text
3434 #: build/C/man2/perf_event_open.2:921
3435 msgid "Count when we execute code at the memory location."
3436 msgstr ""
3437
3438 #. type: Plain text
3439 #: build/C/man2/perf_event_open.2:930
3440 msgid ""
3441 "The values can be combined via a bitwise or, but the combination of "
3442 "B<HW_BREAKPOINT_R> or B<HW_BREAKPOINT_W> with B<HW_BREAKPOINT_X> is not "
3443 "allowed."
3444 msgstr ""
3445
3446 #. type: TP
3447 #: build/C/man2/perf_event_open.2:931
3448 #, no-wrap
3449 msgid "I<bp_addr> (Since Linux 2.6.33)"
3450 msgstr ""
3451
3452 #. type: Plain text
3453 #: build/C/man2/perf_event_open.2:938
3454 msgid ""
3455 "I<bp_addr> address of the breakpoint.  For execution breakpoints this is the "
3456 "memory address of the instruction of interest; for read and write "
3457 "breakpoints it is the memory address of the memory location of interest."
3458 msgstr ""
3459
3460 #. type: TP
3461 #: build/C/man2/perf_event_open.2:938
3462 #, no-wrap
3463 msgid "I<config1> (Since Linux 2.6.39)"
3464 msgstr ""
3465
3466 #. type: Plain text
3467 #: build/C/man2/perf_event_open.2:945
3468 msgid ""
3469 "I<config1> is used for setting events that need an extra register or "
3470 "otherwise do not fit in the regular config field.  Raw OFFCORE_EVENTS on "
3471 "Nehalem/Westmere/SandyBridge use this field on 3.3 and later kernels."
3472 msgstr ""
3473
3474 #. type: TP
3475 #: build/C/man2/perf_event_open.2:945
3476 #, no-wrap
3477 msgid "I<bp_len> (Since Linux 2.6.33)"
3478 msgstr ""
3479
3480 #. type: Plain text
3481 #: build/C/man2/perf_event_open.2:959
3482 msgid ""
3483 "I<bp_len> is the length of the breakpoint being measured if I<type> is "
3484 "B<PERF_TYPE_BREAKPOINT>.  Options are B<HW_BREAKPOINT_LEN_1>, "
3485 "B<HW_BREAKPOINT_LEN_2>, B<HW_BREAKPOINT_LEN_4>, B<HW_BREAKPOINT_LEN_8>.  For "
3486 "an execution breakpoint, set this to I<sizeof(long)>."
3487 msgstr ""
3488
3489 #. type: TP
3490 #: build/C/man2/perf_event_open.2:959
3491 #, no-wrap
3492 msgid "I<config2> (Since Linux 2.6.39)"
3493 msgstr ""
3494
3495 #. type: Plain text
3496 #: build/C/man2/perf_event_open.2:966
3497 msgid "I<config2> is a further extension of the I<config1> field."
3498 msgstr ""
3499
3500 #. type: TP
3501 #: build/C/man2/perf_event_open.2:966
3502 #, no-wrap
3503 msgid "I<branch_sample_type> (Since Linux 3.4)"
3504 msgstr ""
3505
3506 #. type: Plain text
3507 #: build/C/man2/perf_event_open.2:972
3508 msgid ""
3509 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then this specifies what branches "
3510 "to include in the branch record."
3511 msgstr ""
3512
3513 #. type: Plain text
3514 #: build/C/man2/perf_event_open.2:978
3515 msgid ""
3516 "The first part of the value is the privilege level, which is a combination "
3517 "of one of the following values.  If the user does not set privilege level "
3518 "explicitly, the kernel will use the event's privilege level.  Event and "
3519 "branch privilege levels do not have to match."
3520 msgstr ""
3521
3522 #. type: TP
3523 #: build/C/man2/perf_event_open.2:979
3524 #, no-wrap
3525 msgid "B<PERF_SAMPLE_BRANCH_USER>"
3526 msgstr ""
3527
3528 #. type: Plain text
3529 #: build/C/man2/perf_event_open.2:982
3530 msgid "Branch target is in user space."
3531 msgstr ""
3532
3533 #. type: TP
3534 #: build/C/man2/perf_event_open.2:982
3535 #, no-wrap
3536 msgid "B<PERF_SAMPLE_BRANCH_KERNEL>"
3537 msgstr ""
3538
3539 #. type: Plain text
3540 #: build/C/man2/perf_event_open.2:985
3541 msgid "Branch target is in kernel space."
3542 msgstr ""
3543
3544 #. type: TP
3545 #: build/C/man2/perf_event_open.2:985
3546 #, no-wrap
3547 msgid "B<PERF_SAMPLE_BRANCH_HV>"
3548 msgstr ""
3549
3550 #. type: Plain text
3551 #: build/C/man2/perf_event_open.2:988
3552 msgid "Branch target is in hypervisor."
3553 msgstr ""
3554
3555 #. type: TP
3556 #: build/C/man2/perf_event_open.2:988
3557 #, no-wrap
3558 msgid "B<PERF_SAMPLE_BRANCH_PLM_ALL>"
3559 msgstr ""
3560
3561 #. type: Plain text
3562 #: build/C/man2/perf_event_open.2:991
3563 msgid "A convenience value that is the three preceding values ORed together."
3564 msgstr ""
3565
3566 #. type: Plain text
3567 #: build/C/man2/perf_event_open.2:995
3568 msgid ""
3569 "In addition to the privilege value, at least one or more of the following "
3570 "bits must be set."
3571 msgstr ""
3572
3573 #. type: TP
3574 #: build/C/man2/perf_event_open.2:996
3575 #, no-wrap
3576 msgid "B<PERF_SAMPLE_BRANCH_ANY>"
3577 msgstr ""
3578
3579 #. type: Plain text
3580 #: build/C/man2/perf_event_open.2:999
3581 msgid "Any branch type."
3582 msgstr ""
3583
3584 #. type: TP
3585 #: build/C/man2/perf_event_open.2:999
3586 #, no-wrap
3587 msgid "B<PERF_SAMPLE_BRANCH_ANY_CALL>"
3588 msgstr ""
3589
3590 #. type: Plain text
3591 #: build/C/man2/perf_event_open.2:1002
3592 msgid "Any call branch."
3593 msgstr ""
3594
3595 #. type: TP
3596 #: build/C/man2/perf_event_open.2:1002
3597 #, no-wrap
3598 msgid "B<PERF_SAMPLE_BRANCH_ANY_RETURN>"
3599 msgstr ""
3600
3601 #. type: Plain text
3602 #: build/C/man2/perf_event_open.2:1005
3603 msgid "Any return branch."
3604 msgstr ""
3605
3606 #. type: TP
3607 #: build/C/man2/perf_event_open.2:1005
3608 #, no-wrap
3609 msgid "B<PERF_SAMPLE_BRANCH_IND_CALL>"
3610 msgstr ""
3611
3612 #. type: Plain text
3613 #: build/C/man2/perf_event_open.2:1008
3614 msgid "Indirect calls."
3615 msgstr ""
3616
3617 #. type: TP
3618 #: build/C/man2/perf_event_open.2:1008
3619 #, no-wrap
3620 msgid "B<PERF_SAMPLE_BRANCH_ABORT_TX> (Since Linux 3.11)"
3621 msgstr ""
3622
3623 #. type: Plain text
3624 #: build/C/man2/perf_event_open.2:1011
3625 msgid "Transactional memory aborts."
3626 msgstr ""
3627
3628 #. type: TP
3629 #: build/C/man2/perf_event_open.2:1011
3630 #, no-wrap
3631 msgid "B<PERF_SAMPLE_BRANCH_IN_TX> (Since Linux 3.11)"
3632 msgstr ""
3633
3634 #. type: Plain text
3635 #: build/C/man2/perf_event_open.2:1014
3636 msgid "Branch in transactional memory transaction."
3637 msgstr ""
3638
3639 #. type: TP
3640 #: build/C/man2/perf_event_open.2:1014
3641 #, no-wrap
3642 msgid "B<PERF_SAMPLE_BRANCH_NO_TX> (Since Linux 3.11)"
3643 msgstr ""
3644
3645 #. type: Plain text
3646 #: build/C/man2/perf_event_open.2:1017
3647 msgid "Branch not in transactional memory transaction."
3648 msgstr ""
3649
3650 #. type: TP
3651 #: build/C/man2/perf_event_open.2:1019
3652 #, no-wrap
3653 msgid "I<sample_regs_user> (Since Linux 3.7)"
3654 msgstr ""
3655
3656 #. type: Plain text
3657 #: build/C/man2/perf_event_open.2:1025
3658 msgid ""
3659 "This bitmask defines the set of user CPU registers to dump on samples.  The "
3660 "layout of the register mask is architecture specific and described in the "
3661 "kernel header I<arch/ARCH/include/uapi/asm/perf_regs.h>."
3662 msgstr ""
3663
3664 #. type: TP
3665 #: build/C/man2/perf_event_open.2:1025
3666 #, no-wrap
3667 msgid "I<sample_stack_user> (Since Linux 3.7)"
3668 msgstr ""
3669
3670 #. type: Plain text
3671 #: build/C/man2/perf_event_open.2:1030
3672 msgid ""
3673 "This defines the size of the user stack to dump if B<PERF_SAMPLE_STACK_USER> "
3674 "is specified."
3675 msgstr ""
3676
3677 #. type: SS
3678 #: build/C/man2/perf_event_open.2:1030
3679 #, no-wrap
3680 msgid "Reading results"
3681 msgstr ""
3682
3683 #. type: Plain text
3684 #: build/C/man2/perf_event_open.2:1040
3685 msgid ""
3686 "Once a B<perf_event_open>()  file descriptor has been opened, the values of "
3687 "the events can be read from the file descriptor.  The values that are there "
3688 "are specified by the I<read_format> field in the I<attr> structure at open "
3689 "time."
3690 msgstr ""
3691
3692 #. type: Plain text
3693 #: build/C/man2/perf_event_open.2:1045
3694 msgid ""
3695 "If you attempt to read into a buffer that is not big enough to hold the data "
3696 "B<ENOSPC> is returned"
3697 msgstr ""
3698
3699 #. type: Plain text
3700 #: build/C/man2/perf_event_open.2:1047
3701 msgid "Here is the layout of the data returned by a read:"
3702 msgstr ""
3703
3704 #. type: IP
3705 #: build/C/man2/perf_event_open.2:1047 build/C/man2/perf_event_open.2:1065 build/C/man2/ptrace.2:1619 build/C/man2/ptrace.2:1629 build/C/man2/ptrace.2:1637 build/C/man2/ptrace.2:1643 build/C/man2/ptrace.2:1772
3706 #, no-wrap
3707 msgid "*"
3708 msgstr ""
3709
3710 #. type: Plain text
3711 #: build/C/man2/perf_event_open.2:1051
3712 msgid ""
3713 "If B<PERF_FORMAT_GROUP> was specified to allow reading all events in a group "
3714 "at once:"
3715 msgstr ""
3716
3717 #. type: Plain text
3718 #: build/C/man2/perf_event_open.2:1063
3719 #, no-wrap
3720 msgid ""
3721 "struct read_format {\n"
3722 "    u64 nr;            /* The number of events */\n"
3723 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3724 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3725 "    struct\n"
3726 "        u64 value;     /* The value of the event */\n"
3727 "        u64 id;        /* if PERF_FORMAT_ID */\n"
3728 "    } values[nr];\n"
3729 "};\n"
3730 msgstr ""
3731
3732 #. type: Plain text
3733 #: build/C/man2/perf_event_open.2:1071
3734 msgid "If B<PERF_FORMAT_GROUP> was I<not> specified:"
3735 msgstr ""
3736
3737 #. type: Plain text
3738 #: build/C/man2/perf_event_open.2:1080
3739 #, no-wrap
3740 msgid ""
3741 "struct read_format {\n"
3742 "    u64 value;         /* The value of the event */\n"
3743 "    u64 time_enabled;  /* if PERF_FORMAT_TOTAL_TIME_ENABLED */\n"
3744 "    u64 time_running;  /* if PERF_FORMAT_TOTAL_TIME_RUNNING */\n"
3745 "    u64 id;            /* if PERF_FORMAT_ID */\n"
3746 "};\n"
3747 msgstr ""
3748
3749 #. type: Plain text
3750 #: build/C/man2/perf_event_open.2:1084
3751 msgid "The values read are as follows:"
3752 msgstr ""
3753
3754 #. type: TP
3755 #: build/C/man2/perf_event_open.2:1084
3756 #, no-wrap
3757 msgid "I<nr>"
3758 msgstr ""
3759
3760 #. type: Plain text
3761 #: build/C/man2/perf_event_open.2:1090
3762 msgid ""
3763 "The number of events in this file descriptor.  Only available if "
3764 "B<PERF_FORMAT_GROUP> was specified."
3765 msgstr ""
3766
3767 #. type: TP
3768 #: build/C/man2/perf_event_open.2:1090
3769 #, no-wrap
3770 msgid "I<time_enabled>, I<time_running>"
3771 msgstr ""
3772
3773 #. type: Plain text
3774 #: build/C/man2/perf_event_open.2:1102
3775 msgid ""
3776 "Total time the event was enabled and running.  Normally these are the same.  "
3777 "If more events are started than available counter slots on the PMU, then "
3778 "multiplexing happens and events run only part of the time.  In that case the "
3779 "I<time_enabled> and I<time running> values can be used to scale an estimated "
3780 "value for the count."
3781 msgstr ""
3782
3783 #. type: TP
3784 #: build/C/man2/perf_event_open.2:1102
3785 #, no-wrap
3786 msgid "I<value>"
3787 msgstr ""
3788
3789 #. type: Plain text
3790 #: build/C/man2/perf_event_open.2:1105
3791 msgid "An unsigned 64-bit value containing the counter result."
3792 msgstr ""
3793
3794 #. type: TP
3795 #: build/C/man2/perf_event_open.2:1105 build/C/man2/perf_event_open.2:1423 build/C/man2/perf_event_open.2:1560
3796 #, no-wrap
3797 msgid "I<id>"
3798 msgstr ""
3799
3800 #. type: Plain text
3801 #: build/C/man2/perf_event_open.2:1111
3802 msgid ""
3803 "A globally unique value for this particular event, only there if "
3804 "B<PERF_FORMAT_ID> was specified in I<read_format>."
3805 msgstr ""
3806
3807 #. type: SS
3808 #: build/C/man2/perf_event_open.2:1111
3809 #, no-wrap
3810 msgid "MMAP layout"
3811 msgstr ""
3812
3813 #. type: Plain text
3814 #: build/C/man2/perf_event_open.2:1121
3815 msgid ""
3816 "When using B<perf_event_open>()  in sampled mode, asynchronous events (like "
3817 "counter overflow or B<PROT_EXEC> mmap tracking)  are logged into a "
3818 "ring-buffer.  This ring-buffer is created and accessed through B<mmap>(2)."
3819 msgstr ""
3820
3821 #. type: Plain text
3822 #: build/C/man2/perf_event_open.2:1127
3823 msgid ""
3824 "The mmap size should be 1+2^n pages, where the first page is a metadata page "
3825 "(I<struct perf_event_mmap_page>)  that contains various bits of information "
3826 "such as where the ring-buffer head is."
3827 msgstr ""
3828
3829 #. type: Plain text
3830 #: build/C/man2/perf_event_open.2:1130
3831 msgid ""
3832 "Before kernel 2.6.39, there is a bug that means you must allocate a mmap "
3833 "ring buffer when sampling even if you do not plan to access it."
3834 msgstr ""
3835
3836 #. type: Plain text
3837 #: build/C/man2/perf_event_open.2:1132
3838 msgid "The structure of the first metadata mmap page is as follows:"
3839 msgstr ""
3840
3841 #. type: Plain text
3842 #: build/C/man2/perf_event_open.2:1156
3843 #, no-wrap
3844 msgid ""
3845 "struct perf_event_mmap_page {\n"
3846 "    __u32 version;          /* version number of this structure */\n"
3847 "    __u32 compat_version;   /* lowest version this is compat with */\n"
3848 "    __u32 lock;             /* seqlock for synchronization */\n"
3849 "    __u32 index;            /* hardware counter identifier */\n"
3850 "    __s64 offset;           /* add to hardware counter value */\n"
3851 "    __u64 time_enabled;     /* time event active */\n"
3852 "    __u64 time_running;     /* time event on CPU */\n"
3853 "    union {\n"
3854 "        __u64   capabilities;\n"
3855 "        __u64   cap_usr_time  : 1,\n"
3856 "                cap_usr_rdpmc : 1,\n"
3857 "    };\n"
3858 "    __u16   pmc_width;\n"
3859 "    __u16   time_shift;\n"
3860 "    __u32   time_mult;\n"
3861 "    __u64   time_offset;\n"
3862 "    __u64   __reserved[120];   /* Pad to 1k */\n"
3863 "    __u64   data_head;         /* head in the data section */\n"
3864 "    __u64   data_tail;         /* user-space written tail */\n"
3865 "}\n"
3866 msgstr ""
3867
3868 #. type: Plain text
3869 #: build/C/man2/perf_event_open.2:1162
3870 msgid ""
3871 "The following looks at the fields in the I<perf_event_mmap_page> structure "
3872 "in more detail:"
3873 msgstr ""
3874
3875 #. type: TP
3876 #: build/C/man2/perf_event_open.2:1162
3877 #, no-wrap
3878 msgid "I<version>"
3879 msgstr ""
3880
3881 #. type: Plain text
3882 #: build/C/man2/perf_event_open.2:1165
3883 msgid "Version number of this structure."
3884 msgstr ""
3885
3886 #. type: TP
3887 #: build/C/man2/perf_event_open.2:1165
3888 #, no-wrap
3889 msgid "I<compat_version>"
3890 msgstr ""
3891
3892 #. type: Plain text
3893 #: build/C/man2/perf_event_open.2:1168
3894 msgid "The lowest version this is compatible with."
3895 msgstr ""
3896
3897 #. type: TP
3898 #: build/C/man2/perf_event_open.2:1168
3899 #, no-wrap
3900 msgid "I<lock>"
3901 msgstr ""
3902
3903 #. type: Plain text
3904 #: build/C/man2/perf_event_open.2:1171
3905 msgid "A seqlock for synchronization."
3906 msgstr ""
3907
3908 #. type: TP
3909 #: build/C/man2/perf_event_open.2:1171
3910 #, no-wrap
3911 msgid "I<index>"
3912 msgstr ""
3913
3914 #. type: Plain text
3915 #: build/C/man2/perf_event_open.2:1174
3916 msgid "A unique hardware counter identifier."
3917 msgstr ""
3918
3919 #. type: TP
3920 #: build/C/man2/perf_event_open.2:1174
3921 #, no-wrap
3922 msgid "I<offset>"
3923 msgstr ""
3924
3925 #.  FIXME clarify
3926 #. type: Plain text
3927 #: build/C/man2/perf_event_open.2:1178
3928 msgid "Add this to hardware counter value??"
3929 msgstr ""
3930
3931 #. type: TP
3932 #: build/C/man2/perf_event_open.2:1178
3933 #, no-wrap
3934 msgid "I<time_enabled>"
3935 msgstr ""
3936
3937 #. type: Plain text
3938 #: build/C/man2/perf_event_open.2:1181
3939 msgid "Time the event was active."
3940 msgstr ""
3941
3942 #. type: TP
3943 #: build/C/man2/perf_event_open.2:1181
3944 #, no-wrap
3945 msgid "I<time_running>"
3946 msgstr ""
3947
3948 #. type: Plain text
3949 #: build/C/man2/perf_event_open.2:1184
3950 msgid "Time the event was running."
3951 msgstr ""
3952
3953 #. type: TP
3954 #: build/C/man2/perf_event_open.2:1184
3955 #, no-wrap
3956 msgid "I<cap_usr_time>"
3957 msgstr ""
3958
3959 #. type: Plain text
3960 #: build/C/man2/perf_event_open.2:1187
3961 msgid "User time capability."
3962 msgstr ""
3963
3964 #. type: TP
3965 #: build/C/man2/perf_event_open.2:1187
3966 #, no-wrap
3967 msgid "I<cap_usr_rdpmc>"
3968 msgstr ""
3969
3970 #. type: Plain text
3971 #: build/C/man2/perf_event_open.2:1192
3972 msgid ""
3973 "If the hardware supports user-space read of performance counters without "
3974 "syscall (this is the \"rdpmc\" instruction on x86), then the following code "
3975 "can be used to do a read:"
3976 msgstr ""
3977
3978 #. type: Plain text
3979 #: build/C/man2/perf_event_open.2:1199
3980 #, no-wrap
3981 msgid ""
3982 "u32 seq, time_mult, time_shift, idx, width;\n"
3983 "u64 count, enabled, running;\n"
3984 "u64 cyc, time_offset;\n"
3985 "s64 pmc = 0;\n"
3986 msgstr ""
3987
3988 #. type: Plain text
3989 #: build/C/man2/perf_event_open.2:1205
3990 #, no-wrap
3991 msgid ""
3992 "do {\n"
3993 "    seq = pc-E<gt>lock;\n"
3994 "    barrier();\n"
3995 "    enabled = pc-E<gt>time_enabled;\n"
3996 "    running = pc-E<gt>time_running;\n"
3997 msgstr ""
3998
3999 #. type: Plain text
4000 #: build/C/man2/perf_event_open.2:1212
4001 #, no-wrap
4002 msgid ""
4003 "    if (pc-E<gt>cap_usr_time && enabled != running) {\n"
4004 "        cyc = rdtsc();\n"
4005 "        time_offset = pc-E<gt>time_offset;\n"
4006 "        time_mult   = pc-E<gt>time_mult;\n"
4007 "        time_shift  = pc-E<gt>time_shift;\n"
4008 "    }\n"
4009 msgstr ""
4010
4011 #. type: Plain text
4012 #: build/C/man2/perf_event_open.2:1215
4013 #, no-wrap
4014 msgid ""
4015 "    idx = pc-E<gt>index;\n"
4016 "    count = pc-E<gt>offset;\n"
4017 msgstr ""
4018
4019 #. type: Plain text
4020 #: build/C/man2/perf_event_open.2:1220
4021 #, no-wrap
4022 msgid ""
4023 "    if (pc-E<gt>cap_usr_rdpmc && idx) {\n"
4024 "        width = pc-E<gt>pmc_width;\n"
4025 "        pmc = rdpmc(idx - 1);\n"
4026 "    }\n"
4027 msgstr ""
4028
4029 #. type: Plain text
4030 #: build/C/man2/perf_event_open.2:1223
4031 #, no-wrap
4032 msgid ""
4033 "    barrier();\n"
4034 "} while (pc-E<gt>lock != seq);\n"
4035 msgstr ""
4036
4037 #. type: TP
4038 #: build/C/man2/perf_event_open.2:1225
4039 #, no-wrap
4040 msgid "I<pmc_width>"
4041 msgstr ""
4042
4043 #. type: Plain text
4044 #: build/C/man2/perf_event_open.2:1232
4045 msgid ""
4046 "If I<cap_usr_rdpmc>, this field provides the bit-width of the value read "
4047 "using the rdpmc or equivalent instruction.  This can be used to sign extend "
4048 "the result like:"
4049 msgstr ""
4050
4051 #. type: Plain text
4052 #: build/C/man2/perf_event_open.2:1238
4053 #, no-wrap
4054 msgid ""
4055 "pmc E<lt>E<lt>= 64 - pmc_width;\n"
4056 "pmc E<gt>E<gt>= 64 - pmc_width; // signed shift right\n"
4057 "count += pmc;\n"
4058 msgstr ""
4059
4060 #. type: TP
4061 #: build/C/man2/perf_event_open.2:1240
4062 #, no-wrap
4063 msgid "I<time_shift>, I<time_mult>, I<time_offset>"
4064 msgstr ""
4065
4066 #. type: Plain text
4067 #: build/C/man2/perf_event_open.2:1247
4068 msgid ""
4069 "If I<cap_usr_time>, these fields can be used to compute the time delta since "
4070 "time_enabled (in nanoseconds) using rdtsc or similar."
4071 msgstr ""
4072
4073 #. type: Plain text
4074 #: build/C/man2/perf_event_open.2:1255
4075 #, no-wrap
4076 msgid ""
4077 "    u64 quot, rem;\n"
4078 "    u64 delta;\n"
4079 "    quot = (cyc E<gt>E<gt> time_shift);\n"
4080 "    rem = cyc & ((1 E<lt>E<lt> time_shift) - 1);\n"
4081 "    delta = time_offset + quot * time_mult +\n"
4082 "            ((rem * time_mult) E<gt>E<gt> time_shift);\n"
4083 msgstr ""
4084
4085 #. type: Plain text
4086 #: build/C/man2/perf_event_open.2:1267
4087 msgid ""
4088 "Where I<time_offset>, I<time_mult>, I<time_shift>, and I<cyc> are read in "
4089 "the seqcount loop described above.  This delta can then be added to enabled "
4090 "and possible running (if idx), improving the scaling:"
4091 msgstr ""
4092
4093 #. type: Plain text
4094 #: build/C/man2/perf_event_open.2:1275
4095 #, no-wrap
4096 msgid ""
4097 "    enabled += delta;\n"
4098 "    if (idx)\n"
4099 "        running += delta;\n"
4100 "    quot = count / running;\n"
4101 "    rem  = count % running;\n"
4102 "    count = quot * enabled + (rem * enabled) / running;\n"
4103 msgstr ""
4104
4105 #. type: TP
4106 #: build/C/man2/perf_event_open.2:1276
4107 #, no-wrap
4108 msgid "I<data_head>"
4109 msgstr ""
4110
4111 #. type: Plain text
4112 #: build/C/man2/perf_event_open.2:1282
4113 msgid ""
4114 "This points to the head of the data section.  The value continuously "
4115 "increases, it does not wrap.  The value needs to be manually wrapped by the "
4116 "size of the mmap buffer before accessing the samples."
4117 msgstr ""
4118
4119 #. type: Plain text
4120 #: build/C/man2/perf_event_open.2:1285
4121 msgid ""
4122 "On SMP-capable platforms, after reading the data_head value, user space "
4123 "should issue an rmb()."
4124 msgstr ""
4125
4126 #. type: TP
4127 #: build/C/man2/perf_event_open.2:1285
4128 #, no-wrap
4129 msgid "I<data_tail;>"
4130 msgstr ""
4131
4132 #. type: Plain text
4133 #: build/C/man2/perf_event_open.2:1293
4134 msgid ""
4135 "When the mapping is B<PROT_WRITE>, the I<data_tail> value should be written "
4136 "by user space to reflect the last read data.  In this case the kernel will "
4137 "not over-write unread data."
4138 msgstr ""
4139
4140 #. type: Plain text
4141 #: build/C/man2/perf_event_open.2:1295
4142 msgid "The following 2^n ring-buffer pages have the layout described below."
4143 msgstr ""
4144
4145 #. type: Plain text
4146 #: build/C/man2/perf_event_open.2:1309
4147 msgid ""
4148 "If I<perf_event_attr.sample_id_all> is set, then all event types will have "
4149 "the sample_type selected fields related to where/when (identity)  an event "
4150 "took place (TID, TIME, ID, CPU, STREAM_ID) described in "
4151 "B<PERF_RECORD_SAMPLE> below, it will be stashed just after the "
4152 "I<perf_event_header> and the fields already present for the existing fields, "
4153 "that is, at the end of the payload.  That way a newer perf.data file will be "
4154 "supported by older perf tools, with these new optional fields being ignored."
4155 msgstr ""
4156
4157 #. type: Plain text
4158 #: build/C/man2/perf_event_open.2:1311
4159 msgid "The mmap values start with a header:"
4160 msgstr ""
4161
4162 #. type: Plain text
4163 #: build/C/man2/perf_event_open.2:1319
4164 #, no-wrap
4165 msgid ""
4166 "struct perf_event_header {\n"
4167 "    __u32   type;\n"
4168 "    __u16   misc;\n"
4169 "    __u16   size;\n"
4170 "};\n"
4171 msgstr ""
4172
4173 #. type: Plain text
4174 #: build/C/man2/perf_event_open.2:1327
4175 msgid ""
4176 "Below, we describe the I<perf_event_header> fields in more detail.  For ease "
4177 "of reading, the fields with shorter descriptions are presented first."
4178 msgstr ""
4179
4180 #. type: Plain text
4181 #: build/C/man2/perf_event_open.2:1330
4182 msgid "This indicates the size of the record."
4183 msgstr ""
4184
4185 #. type: TP
4186 #: build/C/man2/perf_event_open.2:1330
4187 #, no-wrap
4188 msgid "I<misc>"
4189 msgstr ""
4190
4191 #. type: Plain text
4192 #: build/C/man2/perf_event_open.2:1335
4193 msgid "The I<misc> field contains additional information about the sample."
4194 msgstr ""
4195
4196 #. type: Plain text
4197 #: build/C/man2/perf_event_open.2:1340
4198 msgid ""
4199 "The CPU mode can be determined from this value by masking with "
4200 "B<PERF_RECORD_MISC_CPUMODE_MASK> and looking for one of the following (note "
4201 "these are not bit masks, only one can be set at a time):"
4202 msgstr ""
4203
4204 #. type: TP
4205 #: build/C/man2/perf_event_open.2:1341
4206 #, no-wrap
4207 msgid "B<PERF_RECORD_MISC_CPUMODE_UNKNOWN>"
4208 msgstr ""
4209
4210 #. type: Plain text
4211 #: build/C/man2/perf_event_open.2:1344
4212 msgid "Unknown CPU mode."
4213 msgstr ""
4214
4215 #. type: TP
4216 #: build/C/man2/perf_event_open.2:1344
4217 #, no-wrap
4218 msgid "B<PERF_RECORD_MISC_KERNEL>"
4219 msgstr ""
4220
4221 #. type: Plain text
4222 #: build/C/man2/perf_event_open.2:1347
4223 msgid "Sample happened in the kernel."
4224 msgstr ""
4225
4226 #. type: TP
4227 #: build/C/man2/perf_event_open.2:1347
4228 #, no-wrap
4229 msgid "B<PERF_RECORD_MISC_USER>"
4230 msgstr ""
4231
4232 #. type: Plain text
4233 #: build/C/man2/perf_event_open.2:1350
4234 msgid "Sample happened in user code."
4235 msgstr ""
4236
4237 #. type: TP
4238 #: build/C/man2/perf_event_open.2:1350
4239 #, no-wrap
4240 msgid "B<PERF_RECORD_MISC_HYPERVISOR>"
4241 msgstr ""
4242
4243 #. type: Plain text
4244 #: build/C/man2/perf_event_open.2:1353
4245 msgid "Sample happened in the hypervisor."
4246 msgstr ""
4247
4248 #. type: TP
4249 #: build/C/man2/perf_event_open.2:1353
4250 #, no-wrap
4251 msgid "B<PERF_RECORD_MISC_GUEST_KERNEL>"
4252 msgstr ""
4253
4254 #. type: Plain text
4255 #: build/C/man2/perf_event_open.2:1356
4256 msgid "Sample happened in the guest kernel."
4257 msgstr ""
4258
4259 #. type: TP
4260 #: build/C/man2/perf_event_open.2:1356
4261 #, no-wrap
4262 msgid "B<PERF_RECORD_MISC_GUEST_USER>"
4263 msgstr ""
4264
4265 #. type: Plain text
4266 #: build/C/man2/perf_event_open.2:1359
4267 msgid "Sample happened in guest user code."
4268 msgstr ""
4269
4270 #. type: Plain text
4271 #: build/C/man2/perf_event_open.2:1363
4272 msgid "In addition, one of the following bits can be set:"
4273 msgstr ""
4274
4275 #. type: TP
4276 #: build/C/man2/perf_event_open.2:1363
4277 #, no-wrap
4278 msgid "B<PERF_RECORD_MISC_MMAP_DATA>"
4279 msgstr ""
4280
4281 #. type: Plain text
4282 #: build/C/man2/perf_event_open.2:1367
4283 msgid ""
4284 "This is set when the mapping is not executable; otherwise the mapping is "
4285 "executable."
4286 msgstr ""
4287
4288 #. type: TP
4289 #: build/C/man2/perf_event_open.2:1367
4290 #, no-wrap
4291 msgid "B<PERF_RECORD_MISC_EXACT_IP>"
4292 msgstr ""
4293
4294 #. type: Plain text
4295 #: build/C/man2/perf_event_open.2:1375
4296 msgid ""
4297 "This indicates that the content of B<PERF_SAMPLE_IP> points to the actual "
4298 "instruction that triggered the event.  See also "
4299 "I<perf_event_attr.precise_ip>."
4300 msgstr ""
4301
4302 #. type: TP
4303 #: build/C/man2/perf_event_open.2:1375
4304 #, no-wrap
4305 msgid "B<PERF_RECORD_MISC_EXT_RESERVED>"
4306 msgstr ""
4307
4308 #. type: Plain text
4309 #: build/C/man2/perf_event_open.2:1378
4310 msgid "This indicates there is extended data available (currently not used)."
4311 msgstr ""
4312
4313 #. type: Plain text
4314 #: build/C/man2/perf_event_open.2:1388
4315 msgid ""
4316 "The I<type> value is one of the below.  The values in the corresponding "
4317 "record (that follows the header)  depend on the I<type> selected as shown."
4318 msgstr ""
4319
4320 #. type: TP
4321 #: build/C/man2/perf_event_open.2:1389
4322 #, no-wrap
4323 msgid "B<PERF_RECORD_MMAP>"
4324 msgstr ""
4325
4326 #. type: Plain text
4327 #: build/C/man2/perf_event_open.2:1396
4328 msgid ""
4329 "The MMAP events record the B<PROT_EXEC> mappings so that we can correlate "
4330 "user-space IPs to code.  They have the following structure:"
4331 msgstr ""
4332
4333 #. type: Plain text
4334 #: build/C/man2/perf_event_open.2:1407
4335 #, no-wrap
4336 msgid ""
4337 "struct {\n"
4338 "    struct perf_event_header header;\n"
4339 "    u32    pid, tid;\n"
4340 "    u64    addr;\n"
4341 "    u64    len;\n"
4342 "    u64    pgoff;\n"
4343 "    char   filename[];\n"
4344 "};\n"
4345 msgstr ""
4346
4347 #. type: TP
4348 #: build/C/man2/perf_event_open.2:1409
4349 #, no-wrap
4350 msgid "B<PERF_RECORD_LOST>"
4351 msgstr ""
4352
4353 #. type: Plain text
4354 #: build/C/man2/perf_event_open.2:1412
4355 msgid "This record indicates when events are lost."
4356 msgstr ""
4357
4358 #. type: Plain text
4359 #: build/C/man2/perf_event_open.2:1420
4360 #, no-wrap
4361 msgid ""
4362 "struct {\n"
4363 "    struct perf_event_header header;\n"
4364 "    u64 id;\n"
4365 "    u64 lost;\n"
4366 "};\n"
4367 msgstr ""
4368
4369 #. type: Plain text
4370 #: build/C/man2/perf_event_open.2:1426
4371 msgid "is the unique event ID for the samples that were lost."
4372 msgstr ""
4373
4374 #. type: TP
4375 #: build/C/man2/perf_event_open.2:1426
4376 #, no-wrap
4377 msgid "I<lost>"
4378 msgstr ""
4379
4380 #. type: Plain text
4381 #: build/C/man2/perf_event_open.2:1429
4382 msgid "is the number of events that were lost."
4383 msgstr ""
4384
4385 #. type: TP
4386 #: build/C/man2/perf_event_open.2:1430
4387 #, no-wrap
4388 msgid "B<PERF_RECORD_COMM>"
4389 msgstr ""
4390
4391 #. type: Plain text
4392 #: build/C/man2/perf_event_open.2:1433
4393 msgid "This record indicates a change in the process name."
4394 msgstr ""
4395
4396 #. type: Plain text
4397 #: build/C/man2/perf_event_open.2:1441
4398 #, no-wrap
4399 msgid ""
4400 "struct {\n"
4401 "    struct perf_event_header header;\n"
4402 "    u32 pid, tid;\n"
4403 "    char comm[];\n"
4404 "};\n"
4405 msgstr ""
4406
4407 #. type: TP
4408 #: build/C/man2/perf_event_open.2:1443
4409 #, no-wrap
4410 msgid "B<PERF_RECORD_EXIT>"
4411 msgstr ""
4412
4413 #. type: Plain text
4414 #: build/C/man2/perf_event_open.2:1446
4415 msgid "This record indicates a process exit event."
4416 msgstr ""
4417
4418 #. type: Plain text
4419 #: build/C/man2/perf_event_open.2:1455 build/C/man2/perf_event_open.2:1483
4420 #, no-wrap
4421 msgid ""
4422 "struct {\n"
4423 "    struct perf_event_header header;\n"
4424 "    u32 pid, ppid;\n"
4425 "    u32 tid, ptid;\n"
4426 "    u64 time;\n"
4427 "};\n"
4428 msgstr ""
4429
4430 #. type: TP
4431 #: build/C/man2/perf_event_open.2:1457
4432 #, no-wrap
4433 msgid "B<PERF_RECORD_THROTTLE>, B<PERF_RECORD_UNTHROTTLE>"
4434 msgstr ""
4435
4436 #. type: Plain text
4437 #: build/C/man2/perf_event_open.2:1460
4438 msgid "This record indicates a throttle/unthrottle event."
4439 msgstr ""
4440
4441 #. type: Plain text
4442 #: build/C/man2/perf_event_open.2:1469
4443 #, no-wrap
4444 msgid ""
4445 "struct {\n"
4446 "    struct perf_event_header header;\n"
4447 "    u64 time;\n"
4448 "    u64 id;\n"
4449 "    u64 stream_id;\n"
4450 "};\n"
4451 msgstr ""
4452
4453 #. type: TP
4454 #: build/C/man2/perf_event_open.2:1471
4455 #, no-wrap
4456 msgid "B<PERF_RECORD_FORK>"
4457 msgstr ""
4458
4459 #. type: Plain text
4460 #: build/C/man2/perf_event_open.2:1474
4461 msgid "This record indicates a fork event."
4462 msgstr ""
4463
4464 #. type: TP
4465 #: build/C/man2/perf_event_open.2:1485
4466 #, no-wrap
4467 msgid "B<PERF_RECORD_READ>"
4468 msgstr ""
4469
4470 #. type: Plain text
4471 #: build/C/man2/perf_event_open.2:1488
4472 msgid "This record indicates a read event."
4473 msgstr ""
4474
4475 #. type: Plain text
4476 #: build/C/man2/perf_event_open.2:1496
4477 #, no-wrap
4478 msgid ""
4479 "struct {\n"
4480 "    struct perf_event_header header;\n"
4481 "    u32 pid, tid;\n"
4482 "    struct read_format values;\n"
4483 "};\n"
4484 msgstr ""
4485
4486 #. type: TP
4487 #: build/C/man2/perf_event_open.2:1498
4488 #, no-wrap
4489 msgid "B<PERF_RECORD_SAMPLE>"
4490 msgstr ""
4491
4492 #. type: Plain text
4493 #: build/C/man2/perf_event_open.2:1501
4494 msgid "This record indicates a sample."
4495 msgstr ""
4496
4497 #. type: Plain text
4498 #: build/C/man2/perf_event_open.2:1531
4499 #, no-wrap
4500 msgid ""
4501 "struct {\n"
4502 "    struct perf_event_header header;\n"
4503 "    u64   ip;         /* if PERF_SAMPLE_IP */\n"
4504 "    u32   pid, tid;   /* if PERF_SAMPLE_TID */\n"
4505 "    u64   time;       /* if PERF_SAMPLE_TIME */\n"
4506 "    u64   addr;       /* if PERF_SAMPLE_ADDR */\n"
4507 "    u64   id;         /* if PERF_SAMPLE_ID */\n"
4508 "    u64   stream_id;  /* if PERF_SAMPLE_STREAM_ID */\n"
4509 "    u32   cpu, res;   /* if PERF_SAMPLE_CPU */\n"
4510 "    u64   period;     /* if PERF_SAMPLE_PERIOD */\n"
4511 "    struct read_format v; /* if PERF_SAMPLE_READ */\n"
4512 "    u64   nr;         /* if PERF_SAMPLE_CALLCHAIN */\n"
4513 "    u64   ips[nr];    /* if PERF_SAMPLE_CALLCHAIN */\n"
4514 "    u32   size;       /* if PERF_SAMPLE_RAW */\n"
4515 "    char  data[size]; /* if PERF_SAMPLE_RAW */\n"
4516 "    u64   bnr;        /* if PERF_SAMPLE_BRANCH_STACK */\n"
4517 "    struct perf_branch_entry lbr[bnr];\n"
4518 "                      /* if PERF_SAMPLE_BRANCH_STACK */\n"
4519 "    u64   abi;        /* if PERF_SAMPLE_REGS_USER */\n"
4520 "    u64   regs[weight(mask)];\n"
4521 "                      /* if PERF_SAMPLE_REGS_USER */\n"
4522 "    u64   size;       /* if PERF_SAMPLE_STACK_USER */\n"
4523 "    char  data[size]; /* if PERF_SAMPLE_STACK_USER */\n"
4524 "    u64   dyn_size;   /* if PERF_SAMPLE_STACK_USER */\n"
4525 "    u64   weight;     /* if PERF_SAMPLE_WEIGHT */\n"
4526 "    u64   data_src;   /* if PERF_SAMPLE_DATA_SRC */\n"
4527 "};\n"
4528 msgstr ""
4529
4530 #. type: TP
4531 #: build/C/man2/perf_event_open.2:1533
4532 #, no-wrap
4533 msgid "I<ip>"
4534 msgstr ""
4535
4536 #. type: Plain text
4537 #: build/C/man2/perf_event_open.2:1539
4538 msgid ""
4539 "If B<PERF_SAMPLE_IP> is enabled, then a 64-bit instruction pointer value is "
4540 "included."
4541 msgstr ""
4542
4543 #. type: TP
4544 #: build/C/man2/perf_event_open.2:1539
4545 #, no-wrap
4546 msgid "I<pid>, I<tid>"
4547 msgstr ""
4548
4549 #. type: Plain text
4550 #: build/C/man2/perf_event_open.2:1545
4551 msgid ""
4552 "If B<PERF_SAMPLE_TID> is enabled, then a 32-bit process ID and 32-bit thread "
4553 "ID are included."
4554 msgstr ""
4555
4556 #. type: TP
4557 #: build/C/man2/perf_event_open.2:1545
4558 #, no-wrap
4559 msgid "I<time>"
4560 msgstr ""
4561
4562 #. type: Plain text
4563 #: build/C/man2/perf_event_open.2:1553
4564 msgid ""
4565 "If B<PERF_SAMPLE_TIME> is enabled, then a 64-bit timestamp is included.  "
4566 "This is obtained via local_clock() which is a hardware timestamp if "
4567 "available and the jiffies value if not."
4568 msgstr ""
4569
4570 #. type: TP
4571 #: build/C/man2/perf_event_open.2:1553
4572 #, no-wrap
4573 msgid "I<addr>"
4574 msgstr ""
4575
4576 #. type: Plain text
4577 #: build/C/man2/perf_event_open.2:1560
4578 msgid ""
4579 "If B<PERF_SAMPLE_ADDR> is enabled, then a 64-bit address is included.  This "
4580 "is usually the address of a tracepoint, breakpoint, or software event; "
4581 "otherwise the value is 0."
4582 msgstr ""
4583
4584 #. type: Plain text
4585 #: build/C/man2/perf_event_open.2:1568
4586 msgid ""
4587 "If B<PERF_SAMPLE_ID> is enabled, a 64-bit unique ID is included.  If the "
4588 "event is a member of an event group, the group leader ID is returned.  This "
4589 "ID is the same as the one returned by B<PERF_FORMAT_ID>."
4590 msgstr ""
4591
4592 #. type: TP
4593 #: build/C/man2/perf_event_open.2:1568
4594 #, no-wrap
4595 msgid "I<stream_id>"
4596 msgstr ""
4597
4598 #. type: Plain text
4599 #: build/C/man2/perf_event_open.2:1578
4600 msgid ""
4601 "If B<PERF_SAMPLE_STREAM_ID> is enabled, a 64-bit unique ID is included.  "
4602 "Unlike B<PERF_SAMPLE_ID> the actual ID is returned, not the group leader.  "
4603 "This ID is the same as the one returned by B<PERF_FORMAT_ID>."
4604 msgstr ""
4605
4606 #. type: TP
4607 #: build/C/man2/perf_event_open.2:1578
4608 #, no-wrap
4609 msgid "I<cpu>, I<res>"
4610 msgstr ""
4611
4612 #. type: Plain text
4613 #: build/C/man2/perf_event_open.2:1585
4614 msgid ""
4615 "If B<PERF_SAMPLE_CPU> is enabled, this is a 32-bit value indicating which "
4616 "CPU was being used, in addition to a reserved (unused)  32-bit value."
4617 msgstr ""
4618
4619 #. type: TP
4620 #: build/C/man2/perf_event_open.2:1585
4621 #, no-wrap
4622 msgid "I<period>"
4623 msgstr ""
4624
4625 #. type: Plain text
4626 #: build/C/man2/perf_event_open.2:1591
4627 msgid ""
4628 "If B<PERF_SAMPLE_PERIOD> is enabled, a 64-bit value indicating the current "
4629 "sampling period is written."
4630 msgstr ""
4631
4632 #. type: TP
4633 #: build/C/man2/perf_event_open.2:1591
4634 #, no-wrap
4635 msgid "I<v>"
4636 msgstr ""
4637
4638 #. type: Plain text
4639 #: build/C/man2/perf_event_open.2:1602
4640 msgid ""
4641 "If B<PERF_SAMPLE_READ> is enabled, a structure of type read_format is "
4642 "included which has values for all events in the event group.  The values "
4643 "included depend on the I<read_format> value used at B<perf_event_open>()  "
4644 "time."
4645 msgstr ""
4646
4647 #. type: TP
4648 #: build/C/man2/perf_event_open.2:1602
4649 #, no-wrap
4650 msgid "I<nr>, I<ips[nr]>"
4651 msgstr ""
4652
4653 #. type: Plain text
4654 #: build/C/man2/perf_event_open.2:1610
4655 msgid ""
4656 "If B<PERF_SAMPLE_CALLCHAIN> is enabled, then a 64-bit number is included "
4657 "which indicates how many following 64-bit instruction pointers will follow.  "
4658 "This is the current callchain."
4659 msgstr ""
4660
4661 #. type: TP
4662 #: build/C/man2/perf_event_open.2:1610
4663 #, no-wrap
4664 msgid "I<size>, I<data[size]>"
4665 msgstr ""
4666
4667 #. type: Plain text
4668 #: build/C/man2/perf_event_open.2:1617
4669 msgid ""
4670 "If B<PERF_SAMPLE_RAW> is enabled, then a 32-bit value indicating size is "
4671 "included followed by an array of 8-bit values of length size.  The values "
4672 "are padded with 0 to have 64-bit alignment."
4673 msgstr ""
4674
4675 #. type: Plain text
4676 #: build/C/man2/perf_event_open.2:1622
4677 msgid ""
4678 "This RAW record data is opaque with respect to the ABI.  The ABI doesn't "
4679 "make any promises with respect to the stability of its content, it may vary "
4680 "depending on event, hardware, and kernel version."
4681 msgstr ""
4682
4683 #. type: TP
4684 #: build/C/man2/perf_event_open.2:1622
4685 #, no-wrap
4686 msgid "I<bnr>, I<lbr[bnr]>"
4687 msgstr ""
4688
4689 #. type: Plain text
4690 #: build/C/man2/perf_event_open.2:1631
4691 msgid ""
4692 "If B<PERF_SAMPLE_BRANCH_STACK> is enabled, then a 64-bit value indicating "
4693 "the number of records is included, followed by I<bnr> I<perf_branch_entry> "
4694 "structures which each include the fields:"
4695 msgstr ""
4696
4697 #. type: TP
4698 #: build/C/man2/perf_event_open.2:1632
4699 #, no-wrap
4700 msgid "I<from>"
4701 msgstr ""
4702
4703 #. type: Plain text
4704 #: build/C/man2/perf_event_open.2:1635
4705 msgid "This indicates the source instruction (may not be a branch)."
4706 msgstr ""
4707
4708 #. type: TP
4709 #: build/C/man2/perf_event_open.2:1635
4710 #, no-wrap
4711 msgid "I<to>"
4712 msgstr ""
4713
4714 #. type: Plain text
4715 #: build/C/man2/perf_event_open.2:1638
4716 msgid "The branch target."
4717 msgstr ""
4718
4719 #. type: TP
4720 #: build/C/man2/perf_event_open.2:1638
4721 #, no-wrap
4722 msgid "I<mispred>"
4723 msgstr ""
4724
4725 #. type: Plain text
4726 #: build/C/man2/perf_event_open.2:1641
4727 msgid "The branch target was mispredicted."
4728 msgstr ""
4729
4730 #. type: TP
4731 #: build/C/man2/perf_event_open.2:1641
4732 #, no-wrap
4733 msgid "I<predicted>"
4734 msgstr ""
4735
4736 #. type: Plain text
4737 #: build/C/man2/perf_event_open.2:1644
4738 msgid "The branch target was predicted."
4739 msgstr ""
4740
4741 #. type: TP
4742 #: build/C/man2/perf_event_open.2:1644
4743 #, no-wrap
4744 msgid "I<in_tx> (Since Linux 3.11)"
4745 msgstr ""
4746
4747 #. type: Plain text
4748 #: build/C/man2/perf_event_open.2:1647
4749 msgid "The branch was in a transactional memory transaction."
4750 msgstr ""
4751
4752 #. type: TP
4753 #: build/C/man2/perf_event_open.2:1647
4754 #, no-wrap
4755 msgid "I<abort> (Since Linux 3.11)"
4756 msgstr ""
4757
4758 #. type: Plain text
4759 #: build/C/man2/perf_event_open.2:1650
4760 msgid "The branch was in an aborted transactional memory transaction."
4761 msgstr ""
4762
4763 #. type: Plain text
4764 #: build/C/man2/perf_event_open.2:1654
4765 msgid ""
4766 "The entries are from most to least recent, so the first entry has the most "
4767 "recent branch."
4768 msgstr ""
4769
4770 #. type: Plain text
4771 #: build/C/man2/perf_event_open.2:1661
4772 msgid ""
4773 "Support for I<mispred> and I<predicted> is optional; if not supported, both "
4774 "values will be 0."
4775 msgstr ""
4776
4777 #. type: Plain text
4778 #: build/C/man2/perf_event_open.2:1665
4779 msgid ""
4780 "The type of branches recorded is specified by the I<branch_sample_type> "
4781 "field."
4782 msgstr ""
4783
4784 #. type: TP
4785 #: build/C/man2/perf_event_open.2:1667
4786 #, no-wrap
4787 msgid "I<abi>, I<regs[weight(mask)]>"
4788 msgstr ""
4789
4790 #. type: Plain text
4791 #: build/C/man2/perf_event_open.2:1672
4792 msgid ""
4793 "If B<PERF_SAMPLE_REGS_USER> is enabled, then the user CPU registers are "
4794 "recorded."
4795 msgstr ""
4796
4797 #. type: Plain text
4798 #: build/C/man2/perf_event_open.2:1678
4799 msgid ""
4800 "The I<abi> field is one of B<PERF_SAMPLE_REGS_ABI_NONE>, "
4801 "B<PERF_SAMPLE_REGS_ABI_32> or B<PERF_SAMPLE_REGS_ABI_64>."
4802 msgstr ""
4803
4804 #. type: Plain text
4805 #: build/C/man2/perf_event_open.2:1688
4806 msgid ""
4807 "The I<regs> field is an array of the CPU registers that were specified by "
4808 "the I<sample_regs_user> attr field.  The number of values is the number of "
4809 "bits set in the I<sample_regs_user> bitmask."
4810 msgstr ""
4811
4812 #. type: TP
4813 #: build/C/man2/perf_event_open.2:1688
4814 #, no-wrap
4815 msgid "I<size>, I<data[size]>, I<dyn_size>"
4816 msgstr ""
4817
4818 #. type: Plain text
4819 #: build/C/man2/perf_event_open.2:1702
4820 msgid ""
4821 "If B<PERF_SAMPLE_STACK_USER> is enabled, then record the user stack to "
4822 "enable backtracing.  I<size> is the size requested by the user in "
4823 "I<stack_user_size> or else the maximum record size.  I<data> is the stack "
4824 "data.  I<dyn_size> is the amount of data actually dumped (can be less than "
4825 "I<size>)."
4826 msgstr ""
4827
4828 #. type: TP
4829 #: build/C/man2/perf_event_open.2:1702
4830 #, no-wrap
4831 msgid "I<weight>"
4832 msgstr ""
4833
4834 #. type: Plain text
4835 #: build/C/man2/perf_event_open.2:1710
4836 msgid ""
4837 "If B<PERF_SAMPLE_WEIGHT> is enabled, then a 64 bit value provided by the "
4838 "hardware is recorded that indicates how costly the event was.  This allows "
4839 "expensive events to stand out more clearly in profiles."
4840 msgstr ""
4841
4842 #. type: TP
4843 #: build/C/man2/perf_event_open.2:1710
4844 #, no-wrap
4845 msgid "I<data_src>"
4846 msgstr ""
4847
4848 #. type: Plain text
4849 #: build/C/man2/perf_event_open.2:1716
4850 msgid ""
4851 "If B<PERF_SAMPLE_DATA_SRC> is enabled, then a 64 bit value is recorded that "
4852 "is made up of the following fields:"
4853 msgstr ""
4854
4855 #. type: TP
4856 #: build/C/man2/perf_event_open.2:1717
4857 #, no-wrap
4858 msgid "I<mem_op>"
4859 msgstr ""
4860
4861 #. type: Plain text
4862 #: build/C/man2/perf_event_open.2:1720
4863 msgid "Type of opcode, a bitwise combination of:"
4864 msgstr ""
4865
4866 #. type: TP
4867 #: build/C/man2/perf_event_open.2:1723
4868 #, no-wrap
4869 msgid "B<PERF_MEM_OP_NA>"
4870 msgstr ""
4871
4872 #. type: Plain text
4873 #: build/C/man2/perf_event_open.2:1726 build/C/man2/perf_event_open.2:1749 build/C/man2/perf_event_open.2:1799 build/C/man2/perf_event_open.2:1822 build/C/man2/perf_event_open.2:1836
4874 msgid "Not available"
4875 msgstr ""
4876
4877 #. type: TP
4878 #: build/C/man2/perf_event_open.2:1726
4879 #, no-wrap
4880 msgid "B<PERF_MEM_OP_LOAD>"
4881 msgstr ""
4882
4883 #. type: Plain text
4884 #: build/C/man2/perf_event_open.2:1729
4885 msgid "Load instruction"
4886 msgstr ""
4887
4888 #. type: TP
4889 #: build/C/man2/perf_event_open.2:1729
4890 #, no-wrap
4891 msgid "B<PERF_MEM_OP_STORE>"
4892 msgstr ""
4893
4894 #. type: Plain text
4895 #: build/C/man2/perf_event_open.2:1732
4896 msgid "Store instruction"
4897 msgstr ""
4898
4899 #. type: TP
4900 #: build/C/man2/perf_event_open.2:1732
4901 #, no-wrap
4902 msgid "B<PERF_MEM_OP_PFETCH>"
4903 msgstr ""
4904
4905 #. type: Plain text
4906 #: build/C/man2/perf_event_open.2:1735
4907 msgid "Prefetch"
4908 msgstr ""
4909
4910 #. type: TP
4911 #: build/C/man2/perf_event_open.2:1735
4912 #, no-wrap
4913 msgid "B<PERF_MEM_OP_EXEC>"
4914 msgstr ""
4915
4916 #. type: Plain text
4917 #: build/C/man2/perf_event_open.2:1738
4918 msgid "Executable code"
4919 msgstr ""
4920
4921 #. type: TP
4922 #: build/C/man2/perf_event_open.2:1740
4923 #, no-wrap
4924 msgid "I<mem_lvl>"
4925 msgstr ""
4926
4927 #. type: Plain text
4928 #: build/C/man2/perf_event_open.2:1743
4929 msgid "Memory hierarchy level hit or miss, a bitwise combination of:"
4930 msgstr ""
4931
4932 #. type: TP
4933 #: build/C/man2/perf_event_open.2:1746
4934 #, no-wrap
4935 msgid "B<PERF_MEM_LVL_NA>"
4936 msgstr ""
4937
4938 #. type: TP
4939 #: build/C/man2/perf_event_open.2:1749
4940 #, no-wrap
4941 msgid "B<PERF_MEM_LVL_HIT>"
4942 msgstr ""
4943
4944 #. type: Plain text
4945 #: build/C/man2/perf_event_open.2:1752 build/C/man2/perf_event_open.2:1839
4946 msgid "Hit"
4947 msgstr ""
4948
4949 #. type: TP
4950 #: build/C/man2/perf_event_open.2:1752
4951 #, no-wrap
4952 msgid "B<PERF_MEM_LVL_MISS>"
4953 msgstr ""
4954
4955 #. type: Plain text
4956 #: build/C/man2/perf_event_open.2:1755 build/C/man2/perf_event_open.2:1842
4957 msgid "Miss"
4958 msgstr ""
4959
4960 #. type: TP
4961 #: build/C/man2/perf_event_open.2:1755
4962 #, no-wrap
4963 msgid "B<PERF_MEM_LVL_L1>"
4964 msgstr ""
4965
4966 #. type: Plain text
4967 #: build/C/man2/perf_event_open.2:1758
4968 msgid "Level 1 cache"
4969 msgstr ""
4970
4971 #. type: TP
4972 #: build/C/man2/perf_event_open.2:1758
4973 #, no-wrap
4974 msgid "B<PERF_MEM_LVL_LFB>"
4975 msgstr ""
4976
4977 #. type: Plain text
4978 #: build/C/man2/perf_event_open.2:1761
4979 msgid "Line fill buffer"
4980 msgstr ""
4981
4982 #. type: TP
4983 #: build/C/man2/perf_event_open.2:1761
4984 #, no-wrap
4985 msgid "B<PERF_MEM_LVL_L2>"
4986 msgstr ""
4987
4988 #. type: Plain text
4989 #: build/C/man2/perf_event_open.2:1764
4990 msgid "Level 2 cache"
4991 msgstr ""
4992
4993 #. type: TP
4994 #: build/C/man2/perf_event_open.2:1764
4995 #, no-wrap
4996 msgid "B<PERF_MEM_LVL_L3>"
4997 msgstr ""
4998
4999 #. type: Plain text
5000 #: build/C/man2/perf_event_open.2:1767
5001 msgid "Level 3 cache"
5002 msgstr ""
5003
5004 #. type: TP
5005 #: build/C/man2/perf_event_open.2:1767
5006 #, no-wrap
5007 msgid "B<PERF_MEM_LVL_LOC_RAM>"
5008 msgstr ""
5009
5010 #. type: Plain text
5011 #: build/C/man2/perf_event_open.2:1770
5012 msgid "Local DRAM"
5013 msgstr ""
5014
5015 #. type: TP
5016 #: build/C/man2/perf_event_open.2:1770
5017 #, no-wrap
5018 msgid "B<PERF_MEM_LVL_REM_RAM1>"
5019 msgstr ""
5020
5021 #. type: Plain text
5022 #: build/C/man2/perf_event_open.2:1773
5023 msgid "Remote DRAM 1 hop"
5024 msgstr ""
5025
5026 #. type: TP
5027 #: build/C/man2/perf_event_open.2:1773
5028 #, no-wrap
5029 msgid "B<PERF_MEM_LVL_REM_RAM2>"
5030 msgstr ""
5031
5032 #. type: Plain text
5033 #: build/C/man2/perf_event_open.2:1776
5034 msgid "Remote DRAM 2 hops"
5035 msgstr ""
5036
5037 #. type: TP
5038 #: build/C/man2/perf_event_open.2:1776
5039 #, no-wrap
5040 msgid "B<PERF_MEM_LVL_REM_CCE1>"
5041 msgstr ""
5042
5043 #. type: Plain text
5044 #: build/C/man2/perf_event_open.2:1779
5045 msgid "Remote cache 1 hop"
5046 msgstr ""
5047
5048 #. type: TP
5049 #: build/C/man2/perf_event_open.2:1779
5050 #, no-wrap
5051 msgid "B<PERF_MEM_LVL_REM_CCE2>"
5052 msgstr ""
5053
5054 #. type: Plain text
5055 #: build/C/man2/perf_event_open.2:1782
5056 msgid "Remote cache 2 hops"
5057 msgstr ""
5058
5059 #. type: TP
5060 #: build/C/man2/perf_event_open.2:1782
5061 #, no-wrap
5062 msgid "B<PERF_MEM_LVL_IO>"
5063 msgstr ""
5064
5065 #. type: Plain text
5066 #: build/C/man2/perf_event_open.2:1785
5067 msgid "I/O memory"
5068 msgstr ""
5069
5070 #. type: TP
5071 #: build/C/man2/perf_event_open.2:1785
5072 #, no-wrap
5073 msgid "B<PERF_MEM_LVL_UNC>"
5074 msgstr ""
5075
5076 #. type: Plain text
5077 #: build/C/man2/perf_event_open.2:1788
5078 msgid "Uncached memory"
5079 msgstr ""
5080
5081 #. type: TP
5082 #: build/C/man2/perf_event_open.2:1790
5083 #, no-wrap
5084 msgid "I<mem_snoop>"
5085 msgstr ""
5086
5087 #. type: Plain text
5088 #: build/C/man2/perf_event_open.2:1793
5089 msgid "Snoop mode, a bitwise combination of:"
5090 msgstr ""
5091
5092 #. type: TP
5093 #: build/C/man2/perf_event_open.2:1796
5094 #, no-wrap
5095 msgid "B<PERF_MEM_SNOOP_NA>"
5096 msgstr ""
5097
5098 #. type: TP
5099 #: build/C/man2/perf_event_open.2:1799
5100 #, no-wrap
5101 msgid "B<PERF_MEM_SNOOP_NONE>"
5102 msgstr ""
5103
5104 #. type: Plain text
5105 #: build/C/man2/perf_event_open.2:1802
5106 msgid "No snoop"
5107 msgstr ""
5108
5109 #. type: TP
5110 #: build/C/man2/perf_event_open.2:1802
5111 #, no-wrap
5112 msgid "B<PERF_MEM_SNOOP_HIT>"
5113 msgstr ""
5114
5115 #. type: Plain text
5116 #: build/C/man2/perf_event_open.2:1805
5117 msgid "Snoop hit"
5118 msgstr ""
5119
5120 #. type: TP
5121 #: build/C/man2/perf_event_open.2:1805
5122 #, no-wrap
5123 msgid "B<PERF_MEM_SNOOP_MISS>"
5124 msgstr ""
5125
5126 #. type: Plain text
5127 #: build/C/man2/perf_event_open.2:1808
5128 msgid "Snoop miss"
5129 msgstr ""
5130
5131 #. type: TP
5132 #: build/C/man2/perf_event_open.2:1808
5133 #, no-wrap
5134 msgid "B<PERF_MEM_SNOOP_HITM>"
5135 msgstr ""
5136
5137 #. type: Plain text
5138 #: build/C/man2/perf_event_open.2:1811
5139 msgid "Snoop hit modified"
5140 msgstr ""
5141
5142 #. type: TP
5143 #: build/C/man2/perf_event_open.2:1813
5144 #, no-wrap
5145 msgid "I<mem_lock>"
5146 msgstr ""
5147
5148 #. type: Plain text
5149 #: build/C/man2/perf_event_open.2:1816
5150 msgid "Lock instruction, a bitwise combination of:"
5151 msgstr ""
5152
5153 #. type: TP
5154 #: build/C/man2/perf_event_open.2:1819
5155 #, no-wrap
5156 msgid "B<PERF_MEM_LOCK_NA>"
5157 msgstr ""
5158
5159 #. type: TP
5160 #: build/C/man2/perf_event_open.2:1822
5161 #, no-wrap
5162 msgid "B<PERF_MEM_LOCK_LOCKED>"
5163 msgstr ""
5164
5165 #. type: Plain text
5166 #: build/C/man2/perf_event_open.2:1825
5167 msgid "Locked transaction"
5168 msgstr ""
5169
5170 #. type: TP
5171 #: build/C/man2/perf_event_open.2:1827
5172 #, no-wrap
5173 msgid "I<mem_dtlb>"
5174 msgstr ""
5175
5176 #. type: Plain text
5177 #: build/C/man2/perf_event_open.2:1830
5178 msgid "TLB access hit or miss, a bitwise combination of:"
5179 msgstr ""
5180
5181 #. type: TP
5182 #: build/C/man2/perf_event_open.2:1833
5183 #, no-wrap
5184 msgid "B<PERF_MEM_TLB_NA>"
5185 msgstr ""
5186
5187 #. type: TP
5188 #: build/C/man2/perf_event_open.2:1836
5189 #, no-wrap
5190 msgid "B<PERF_MEM_TLB_HIT>"
5191 msgstr ""
5192
5193 #. type: TP
5194 #: build/C/man2/perf_event_open.2:1839
5195 #, no-wrap
5196 msgid "B<PERF_MEM_TLB_MISS>"
5197 msgstr ""
5198
5199 #. type: TP
5200 #: build/C/man2/perf_event_open.2:1842
5201 #, no-wrap
5202 msgid "B<PERF_MEM_TLB_L1>"
5203 msgstr ""
5204
5205 #. type: Plain text
5206 #: build/C/man2/perf_event_open.2:1845
5207 msgid "Level 1 TLB"
5208 msgstr ""
5209
5210 #. type: TP
5211 #: build/C/man2/perf_event_open.2:1845
5212 #, no-wrap
5213 msgid "B<PERF_MEM_TLB_L2>"
5214 msgstr ""
5215
5216 #. type: Plain text
5217 #: build/C/man2/perf_event_open.2:1848
5218 msgid "Level 2 TLB"
5219 msgstr ""
5220
5221 #. type: TP
5222 #: build/C/man2/perf_event_open.2:1848
5223 #, no-wrap
5224 msgid "B<PERF_MEM_TLB_WK>"
5225 msgstr ""
5226
5227 #. type: Plain text
5228 #: build/C/man2/perf_event_open.2:1851
5229 msgid "Hardware walker"
5230 msgstr ""
5231
5232 #. type: TP
5233 #: build/C/man2/perf_event_open.2:1851
5234 #, no-wrap
5235 msgid "B<PERF_MEM_TLB_OS>"
5236 msgstr ""
5237
5238 #. type: Plain text
5239 #: build/C/man2/perf_event_open.2:1854
5240 msgid "OS fault handler"
5241 msgstr ""
5242
5243 #. type: SS
5244 #: build/C/man2/perf_event_open.2:1860
5245 #, no-wrap
5246 msgid "Signal overflow"
5247 msgstr ""
5248
5249 #. type: Plain text
5250 #: build/C/man2/perf_event_open.2:1869
5251 msgid ""
5252 "Events can be set to deliver a signal when a threshold is crossed.  The "
5253 "signal handler is set up using the B<poll>(2), B<select>(2), B<epoll>(2)  "
5254 "and B<fcntl>(2), system calls."
5255 msgstr ""
5256
5257 #. type: Plain text
5258 #: build/C/man2/perf_event_open.2:1873
5259 msgid ""
5260 "To generate signals, sampling must be enabled (I<sample_period> must have a "
5261 "non-zero value)."
5262 msgstr ""
5263
5264 #. type: Plain text
5265 #: build/C/man2/perf_event_open.2:1875
5266 msgid "There are two ways to generate signals."
5267 msgstr ""
5268
5269 #. type: Plain text
5270 #: build/C/man2/perf_event_open.2:1885
5271 msgid ""
5272 "The first is to set a I<wakeup_events> or I<wakeup_watermark> value that "
5273 "will generate a signal if a certain number of samples or bytes have been "
5274 "written to the mmap ring buffer.  In this case a signal of type B<POLL_IN> "
5275 "is sent."
5276 msgstr ""
5277
5278 #. type: Plain text
5279 #: build/C/man2/perf_event_open.2:1897
5280 msgid ""
5281 "The other way is by use of the B<PERF_EVENT_IOC_REFRESH> ioctl.  This ioctl "
5282 "adds to a counter that decrements each time the event overflows.  When "
5283 "non-zero, a B<POLL_IN> signal is sent on overflow, but once the value "
5284 "reaches 0, a signal is sent of type B<POLL_HUP> and the underlying event is "
5285 "disabled."
5286 msgstr ""
5287
5288 #.  FIXME(Vince) : Find out when this was introduced
5289 #. type: Plain text
5290 #: build/C/man2/perf_event_open.2:1903
5291 msgid ""
5292 "Note: on newer kernels (definitely noticed with 3.2)  a signal is provided "
5293 "for every overflow, even if I<wakeup_events> is not set."
5294 msgstr ""
5295
5296 #. type: SS
5297 #: build/C/man2/perf_event_open.2:1903
5298 #, no-wrap
5299 msgid "rdpmc instruction"
5300 msgstr ""
5301
5302 #. type: Plain text
5303 #: build/C/man2/perf_event_open.2:1910
5304 msgid ""
5305 "Starting with Linux 3.4 on x86, you can use the I<rdpmc> instruction to get "
5306 "low-latency reads without having to enter the kernel.  Note that using "
5307 "I<rdpmc> is not necessarily faster than other methods for reading event "
5308 "values."
5309 msgstr ""
5310
5311 #. type: Plain text
5312 #: build/C/man2/perf_event_open.2:1915
5313 msgid ""
5314 "Support for this can be detected with the I<cap_usr_rdpmc> field in the mmap "
5315 "page; documentation on how to calculate event values can be found in that "
5316 "section."
5317 msgstr ""
5318
5319 #. type: SS
5320 #: build/C/man2/perf_event_open.2:1915
5321 #, no-wrap
5322 msgid "perf_event ioctl calls"
5323 msgstr ""
5324
5325 #. type: Plain text
5326 #: build/C/man2/perf_event_open.2:1920
5327 msgid "Various ioctls act on B<perf_event_open>()  file descriptors"
5328 msgstr ""
5329
5330 #. type: TP
5331 #: build/C/man2/perf_event_open.2:1920
5332 #, no-wrap
5333 msgid "B<PERF_EVENT_IOC_ENABLE>"
5334 msgstr ""
5335
5336 #. type: Plain text
5337 #: build/C/man2/perf_event_open.2:1924
5338 msgid ""
5339 "Enables the individual event or event group specified by the file descriptor "
5340 "argument."
5341 msgstr ""
5342
5343 #. type: Plain text
5344 #: build/C/man2/perf_event_open.2:1930
5345 msgid ""
5346 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5347 "events in a group are enabled, even if the event specified is not the group "
5348 "leader (but see BUGS)."
5349 msgstr ""
5350
5351 #. type: TP
5352 #: build/C/man2/perf_event_open.2:1930
5353 #, no-wrap
5354 msgid "B<PERF_EVENT_IOC_DISABLE>"
5355 msgstr ""
5356
5357 #. type: Plain text
5358 #: build/C/man2/perf_event_open.2:1934
5359 msgid ""
5360 "Disables the individual counter or event group specified by the file "
5361 "descriptor argument."
5362 msgstr ""
5363
5364 #. type: Plain text
5365 #: build/C/man2/perf_event_open.2:1941
5366 msgid ""
5367 "Enabling or disabling the leader of a group enables or disables the entire "
5368 "group; that is, while the group leader is disabled, none of the counters in "
5369 "the group will count.  Enabling or disabling a member of a group other than "
5370 "the leader affects only that counter; disabling a non-leader stops that "
5371 "counter from counting but doesn't affect any other counter."
5372 msgstr ""
5373
5374 #. type: Plain text
5375 #: build/C/man2/perf_event_open.2:1947
5376 msgid ""
5377 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5378 "events in a group are disabled, even if the event specified is not the group "
5379 "leader (but see BUGS)."
5380 msgstr ""
5381
5382 #. type: TP
5383 #: build/C/man2/perf_event_open.2:1947
5384 #, no-wrap
5385 msgid "B<PERF_EVENT_IOC_REFRESH>"
5386 msgstr ""
5387
5388 #. type: Plain text
5389 #: build/C/man2/perf_event_open.2:1961
5390 msgid ""
5391 "Non-inherited overflow counters can use this to enable a counter for a "
5392 "number of overflows specified by the argument, after which it is disabled.  "
5393 "Subsequent calls of this ioctl add the argument value to the current count.  "
5394 "A signal with B<POLL_IN> set will happen on each overflow until the count "
5395 "reaches 0; when that happens a signal with POLL_HUP set is sent and the "
5396 "event is disabled.  Using an argument of 0 is considered undefined behavior."
5397 msgstr ""
5398
5399 #. type: TP
5400 #: build/C/man2/perf_event_open.2:1961
5401 #, no-wrap
5402 msgid "B<PERF_EVENT_IOC_RESET>"
5403 msgstr ""
5404
5405 #. type: Plain text
5406 #: build/C/man2/perf_event_open.2:1971
5407 msgid ""
5408 "Reset the event count specified by the file descriptor argument to zero.  "
5409 "This resets only the counts; there is no way to reset the multiplexing "
5410 "I<time_enabled> or I<time_running> values."
5411 msgstr ""
5412
5413 #. type: Plain text
5414 #: build/C/man2/perf_event_open.2:1977
5415 msgid ""
5416 "If the B<PERF_IOC_FLAG_GROUP> bit is set in the ioctl argument, then all "
5417 "events in a group are reset, even if the event specified is not the group "
5418 "leader (but see BUGS)."
5419 msgstr ""
5420
5421 #. type: TP
5422 #: build/C/man2/perf_event_open.2:1977
5423 #, no-wrap
5424 msgid "B<PERF_EVENT_IOC_PERIOD>"
5425 msgstr ""
5426
5427 #. type: Plain text
5428 #: build/C/man2/perf_event_open.2:1981
5429 msgid ""
5430 "IOC_PERIOD is the command to update the period; it does not update the "
5431 "current period but instead defers until next."
5432 msgstr ""
5433
5434 #. type: Plain text
5435 #: build/C/man2/perf_event_open.2:1984
5436 msgid ""
5437 "The argument is a pointer to a 64-bit value containing the desired new "
5438 "period."
5439 msgstr ""
5440
5441 #. type: TP
5442 #: build/C/man2/perf_event_open.2:1984
5443 #, no-wrap
5444 msgid "B<PERF_EVENT_IOC_SET_OUTPUT>"
5445 msgstr ""
5446
5447 #. type: Plain text
5448 #: build/C/man2/perf_event_open.2:1989
5449 msgid ""
5450 "This tells the kernel to report event notifications to the specified file "
5451 "descriptor rather than the default one.  The file descriptors must all be on "
5452 "the same CPU."
5453 msgstr ""
5454
5455 #. type: Plain text
5456 #: build/C/man2/perf_event_open.2:1992
5457 msgid ""
5458 "The argument specifies the desired file descriptor, or -1 if output should "
5459 "be ignored."
5460 msgstr ""
5461
5462 #. type: TP
5463 #: build/C/man2/perf_event_open.2:1992
5464 #, no-wrap
5465 msgid "B<PERF_EVENT_IOC_SET_FILTER> (Since Linux 2.6.33)"
5466 msgstr ""
5467
5468 #. type: Plain text
5469 #: build/C/man2/perf_event_open.2:1995
5470 msgid "This adds an ftrace filter to this event."
5471 msgstr ""
5472
5473 #. type: Plain text
5474 #: build/C/man2/perf_event_open.2:1997
5475 msgid "The argument is a pointer to the desired ftrace filter."
5476 msgstr ""
5477
5478 #. type: SS
5479 #: build/C/man2/perf_event_open.2:1997
5480 #, no-wrap
5481 msgid "Using prctl"
5482 msgstr ""
5483
5484 #. type: Plain text
5485 #: build/C/man2/perf_event_open.2:2010
5486 msgid ""
5487 "A process can enable or disable all the event groups that are attached to it "
5488 "using the B<prctl>(2)  B<PR_TASK_PERF_EVENTS_ENABLE> and "
5489 "B<PR_TASK_PERF_EVENTS_DISABLE> operations.  This applies to all counters on "
5490 "the current process, whether created by this process or by another, and does "
5491 "not affect any counters that this process has created on other processes.  "
5492 "It enables or disables only the group leaders, not any other members in the "
5493 "groups."
5494 msgstr ""
5495
5496 #. type: SS
5497 #: build/C/man2/perf_event_open.2:2010
5498 #, no-wrap
5499 msgid "perf_event related configuration files"
5500 msgstr ""
5501
5502 #. type: Plain text
5503 #: build/C/man2/perf_event_open.2:2013
5504 msgid "Files in I</proc/sys/kernel/>"
5505 msgstr ""
5506
5507 #. type: TP
5508 #: build/C/man2/perf_event_open.2:2014
5509 #, no-wrap
5510 msgid "I</proc/sys/kernel/perf_event_paranoid>"
5511 msgstr ""
5512
5513 #. type: Plain text
5514 #: build/C/man2/perf_event_open.2:2020
5515 msgid ""
5516 "The I<perf_event_paranoid> file can be set to restrict access to the "
5517 "performance counters."
5518 msgstr ""
5519
5520 #. type: IP
5521 #: build/C/man2/perf_event_open.2:2021
5522 #, no-wrap
5523 msgid "2"
5524 msgstr ""
5525
5526 #. type: Plain text
5527 #: build/C/man2/perf_event_open.2:2023
5528 msgid "only allow user-space measurements."
5529 msgstr ""
5530
5531 #. type: IP
5532 #: build/C/man2/perf_event_open.2:2023
5533 #, no-wrap
5534 msgid "1"
5535 msgstr ""
5536
5537 #. type: Plain text
5538 #: build/C/man2/perf_event_open.2:2025
5539 msgid "allow both kernel and user measurements (default)."
5540 msgstr ""
5541
5542 #. type: IP
5543 #: build/C/man2/perf_event_open.2:2025
5544 #, no-wrap
5545 msgid "0"
5546 msgstr ""
5547
5548 #. type: Plain text
5549 #: build/C/man2/perf_event_open.2:2027
5550 msgid "allow access to CPU-specific data but not raw tracepoint samples."
5551 msgstr ""
5552
5553 #. type: IP
5554 #: build/C/man2/perf_event_open.2:2027
5555 #, no-wrap
5556 msgid "-1"
5557 msgstr ""
5558
5559 #. type: Plain text
5560 #: build/C/man2/perf_event_open.2:2029
5561 msgid "no restrictions."
5562 msgstr ""
5563
5564 #. type: Plain text
5565 #: build/C/man2/perf_event_open.2:2035
5566 msgid ""
5567 "The existence of the I<perf_event_paranoid> file is the official method for "
5568 "determining if a kernel supports B<perf_event_open>()."
5569 msgstr ""
5570
5571 #. type: TP
5572 #: build/C/man2/perf_event_open.2:2035
5573 #, no-wrap
5574 msgid "I</proc/sys/kernel/perf_event_max_sample_rate>"
5575 msgstr ""
5576
5577 #. type: Plain text
5578 #: build/C/man2/perf_event_open.2:2044
5579 msgid ""
5580 "This sets the maximum sample rate.  Setting this too high can allow users to "
5581 "sample at a rate that impacts overall machine performance and potentially "
5582 "lock up the machine.  The default value is 100000 (samples per second)."
5583 msgstr ""
5584
5585 #. type: TP
5586 #: build/C/man2/perf_event_open.2:2044
5587 #, no-wrap
5588 msgid "I</proc/sys/kernel/perf_event_mlock_kb>"
5589 msgstr ""
5590
5591 #. type: Plain text
5592 #: build/C/man2/perf_event_open.2:2049
5593 msgid ""
5594 "Maximum number of pages an unprivileged user can mlock (2) .  The default is "
5595 "516 (kB)."
5596 msgstr ""
5597
5598 #. type: Plain text
5599 #: build/C/man2/perf_event_open.2:2053
5600 msgid "Files in I</sys/bus/event_source/devices/>"
5601 msgstr ""
5602
5603 #. type: Plain text
5604 #: build/C/man2/perf_event_open.2:2059
5605 msgid ""
5606 "Since Linux 2.6.34 the kernel supports having multiple PMUs available for "
5607 "monitoring.  Information on how to program these PMUs can be found under "
5608 "I</sys/bus/event_source/devices/>.  Each subdirectory corresponds to a "
5609 "different PMU."
5610 msgstr ""
5611
5612 #. type: TP
5613 #: build/C/man2/perf_event_open.2:2059
5614 #, no-wrap
5615 msgid "I</sys/bus/event_source/devices/*/type> (Since Linux 2.6.38)"
5616 msgstr ""
5617
5618 #. type: Plain text
5619 #: build/C/man2/perf_event_open.2:2064
5620 msgid ""
5621 "This contains an integer that can be used in the I<type> field of "
5622 "perf_event_attr to indicate you wish to use this PMU."
5623 msgstr ""
5624
5625 #. type: TP
5626 #: build/C/man2/perf_event_open.2:2064
5627 #, no-wrap
5628 msgid "I</sys/bus/event_source/devices/*/rdpmc> (Since Linux 3.4)"
5629 msgstr ""
5630
5631 #. type: Plain text
5632 #: build/C/man2/perf_event_open.2:2069
5633 msgid ""
5634 "If this file is 1, then direct user-space access to the performance counter "
5635 "registers is allowed via the rdpmc instruction.  This can be disabled by "
5636 "echoing 0 to the file."
5637 msgstr ""
5638
5639 #. type: TP
5640 #: build/C/man2/perf_event_open.2:2069
5641 #, no-wrap
5642 msgid "I</sys/bus/event_source/devices/*/format/> (Since Linux 3.4)"
5643 msgstr ""
5644
5645 #. type: Plain text
5646 #: build/C/man2/perf_event_open.2:2075
5647 msgid ""
5648 "This sub-directory contains information on the architecture-specific "
5649 "sub-fields available for programming the various I<config> fields in the "
5650 "perf_event_attr struct."
5651 msgstr ""
5652
5653 #. type: Plain text
5654 #: build/C/man2/perf_event_open.2:2085
5655 msgid ""
5656 "The content of each file is the name of the config field, followed by a "
5657 "colon, followed by a series of integer bit ranges separated by commas.  For "
5658 "example, the file I<event> may contain the value I<config1:1,6-10,44> which "
5659 "indicates that event is an attribute that occupies bits 1,6-10, and 44 of "
5660 "perf_event_attr::config1."
5661 msgstr ""
5662
5663 #. type: TP
5664 #: build/C/man2/perf_event_open.2:2085
5665 #, no-wrap
5666 msgid "I</sys/bus/event_source/devices/*/events/> (Since Linux 3.4)"
5667 msgstr ""
5668
5669 #. type: Plain text
5670 #: build/C/man2/perf_event_open.2:2094
5671 msgid ""
5672 "This sub-directory contains files with pre-defined events.  The contents are "
5673 "strings describing the event settings expressed in terms of the fields found "
5674 "in the previously mentioned I<./format/> directory.  These are not "
5675 "necessarily complete lists of all events supported by a PMU, but usually a "
5676 "subset of events deemed useful or interesting."
5677 msgstr ""
5678
5679 #. type: Plain text
5680 #: build/C/man2/perf_event_open.2:2102
5681 msgid ""
5682 "The content of each file is a list of attribute names separated by commas.  "
5683 "Each entry has an optional value (either hex or decimal).  If no value is "
5684 "specified than it is assumed to be a single-bit field with a value of 1.  An "
5685 "example entry may look like this: I<event=0x2,inv,ldlat=3>."
5686 msgstr ""
5687
5688 #. type: TP
5689 #: build/C/man2/perf_event_open.2:2102
5690 #, no-wrap
5691 msgid "I</sys/bus/event_source/devices/*/uevent>"
5692 msgstr ""
5693
5694 #. type: Plain text
5695 #: build/C/man2/perf_event_open.2:2106
5696 msgid ""
5697 "This file is the standard kernel device interface for injecting hotplug "
5698 "events."
5699 msgstr ""
5700
5701 #. type: TP
5702 #: build/C/man2/perf_event_open.2:2106
5703 #, no-wrap
5704 msgid "I</sys/bus/event_source/devices/*/cpumask> (Since Linux 3.7)"
5705 msgstr ""
5706
5707 #. type: Plain text
5708 #: build/C/man2/perf_event_open.2:2115
5709 msgid ""
5710 "The I<cpumask> file contains a comma-separated list of integers that "
5711 "indicate a representative CPU number for each socket (package)  on the "
5712 "motherboard.  This is needed when setting up uncore or northbridge events, "
5713 "as those PMUs present socket-wide events."
5714 msgstr ""
5715
5716 #. type: Plain text
5717 #: build/C/man2/perf_event_open.2:2122
5718 msgid ""
5719 "B<perf_event_open>()  returns the new file descriptor, or -1 if an error "
5720 "occurred (in which case, I<errno> is set appropriately)."
5721 msgstr ""
5722
5723 #. type: Plain text
5724 #: build/C/man2/perf_event_open.2:2126
5725 msgid "Returned if the specified event is not available."
5726 msgstr ""
5727
5728 #. type: TP
5729 #: build/C/man2/perf_event_open.2:2126
5730 #, no-wrap
5731 msgid "B<ENOSPC>"
5732 msgstr ""
5733
5734 #. type: Plain text
5735 #: build/C/man2/perf_event_open.2:2136
5736 msgid ""
5737 "Prior to Linux 3.3, if there was not enough room for the event, B<ENOSPC> "
5738 "was returned.  Linus did not like this, and this was changed to B<EINVAL>.  "
5739 "B<ENOSPC> is still returned if you try to read results into too small of a "
5740 "buffer."
5741 msgstr ""
5742
5743 #. type: SH
5744 #: build/C/man2/perf_event_open.2:2136
5745 #, no-wrap
5746 msgid "VERSION"
5747 msgstr ""
5748
5749 #. type: Plain text
5750 #: build/C/man2/perf_event_open.2:2141
5751 msgid ""
5752 "B<perf_event_open>()  was introduced in Linux 2.6.31 but was called "
5753 "B<perf_counter_open>()B<.> It was renamed in Linux 2.6.32."
5754 msgstr ""
5755
5756 #. type: Plain text
5757 #: build/C/man2/perf_event_open.2:2146
5758 msgid ""
5759 "This B<perf_event_open>()  system call Linux- specific and should not be "
5760 "used in programs intended to be portable."
5761 msgstr ""
5762
5763 #. type: Plain text
5764 #: build/C/man2/perf_event_open.2:2150
5765 msgid ""
5766 "Glibc does not provide a wrapper for this system call; call it using "
5767 "B<syscall>(2).  See the example below."
5768 msgstr ""
5769
5770 #. type: Plain text
5771 #: build/C/man2/perf_event_open.2:2156
5772 msgid ""
5773 "The official way of knowing if B<perf_event_open>()  support is enabled is "
5774 "checking for the existence of the file "
5775 "I</proc/sys/kernel/perf_event_paranoid>."
5776 msgstr ""
5777
5778 #. type: SH
5779 #: build/C/man2/perf_event_open.2:2156 build/C/man2/pivot_root.2:134 build/C/man2/ptrace.2:1884
5780 #, no-wrap
5781 msgid "BUGS"
5782 msgstr ""
5783
5784 #. type: Plain text
5785 #: build/C/man2/perf_event_open.2:2163
5786 msgid ""
5787 "The B<F_SETOWN_EX> option to B<fcntl>(2)  is needed to properly get overflow "
5788 "signals in threads.  This was introduced in Linux 2.6.32."
5789 msgstr ""
5790
5791 #. type: Plain text
5792 #: build/C/man2/perf_event_open.2:2171
5793 msgid ""
5794 "Prior to Linux 2.6.33 (at least for x86) the kernel did not check if events "
5795 "could be scheduled together until read time.  The same happens on all known "
5796 "kernels if the NMI watchdog is enabled.  This means to see if a given set of "
5797 "events works you have to B<perf_event_open>(), start, then read before you "
5798 "know for sure you can get valid measurements."
5799 msgstr ""
5800
5801 #. type: Plain text
5802 #: build/C/man2/perf_event_open.2:2175
5803 msgid ""
5804 "Prior to Linux 2.6.34 event constraints were not enforced by the kernel.  In "
5805 "that case, some events would silently return \"0\" if the kernel scheduled "
5806 "them in an improper counter slot."
5807 msgstr ""
5808
5809 #. type: Plain text
5810 #: build/C/man2/perf_event_open.2:2178
5811 msgid ""
5812 "Prior to Linux 2.6.34 there was a bug when multiplexing where the wrong "
5813 "results could be returned."
5814 msgstr ""
5815
5816 #. type: Plain text
5817 #: build/C/man2/perf_event_open.2:2181
5818 msgid ""
5819 "Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "
5820 "\"inherit\" is enabled and many threads are started."
5821 msgstr ""
5822
5823 #. type: Plain text
5824 #: build/C/man2/perf_event_open.2:2185
5825 msgid ""
5826 "Prior to Linux 2.6.35, B<PERF_FORMAT_GROUP> did not work with attached "
5827 "processes."
5828 msgstr ""
5829
5830 #. type: Plain text
5831 #: build/C/man2/perf_event_open.2:2190
5832 msgid ""
5833 "In older Linux 2.6 versions, refreshing an event group leader refreshed all "
5834 "siblings, and refreshing with a parameter of 0 enabled infinite refresh.  "
5835 "This behavior is unsupported and should not be relied on."
5836 msgstr ""
5837
5838 #. type: Plain text
5839 #: build/C/man2/perf_event_open.2:2196
5840 msgid ""
5841 "There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that "
5842 "ignores the \"watermark\" field and acts as if a wakeup_event was chosen if "
5843 "the union has a non-zero value in it."
5844 msgstr ""
5845
5846 #. type: Plain text
5847 #: build/C/man2/perf_event_open.2:2202
5848 msgid ""
5849 "From Linux 2.6.31 to Linux 3.4, the B<PERF_IOC_FLAG_GROUP> ioctl argument "
5850 "was broken and would repeatedly operate on the event specified rather than "
5851 "iterating across all sibling events in a group."
5852 msgstr ""
5853
5854 #. type: Plain text
5855 #: build/C/man2/perf_event_open.2:2207
5856 msgid ""
5857 "Always double-check your results! Various generalized events have had wrong "
5858 "values.  For example, retired branches measured the wrong thing on AMD "
5859 "machines until Linux 2.6.35."
5860 msgstr ""
5861
5862 #. type: SH
5863 #: build/C/man2/perf_event_open.2:2207 build/C/man2/process_vm_readv.2:295 build/C/man2/splice.2:223 build/C/man2/tee.2:130
5864 #, no-wrap
5865 msgid "EXAMPLE"
5866 msgstr ""
5867
5868 #. type: Plain text
5869 #: build/C/man2/perf_event_open.2:2211
5870 msgid ""
5871 "The following is a short example that measures the total instruction count "
5872 "of a call to B<printf>(3)."
5873 msgstr ""
5874
5875 #. type: Plain text
5876 #: build/C/man2/perf_event_open.2:2220
5877 #, no-wrap
5878 msgid ""
5879 "#include E<lt>stdlib.hE<gt>\n"
5880 "#include E<lt>stdio.hE<gt>\n"
5881 "#include E<lt>unistd.hE<gt>\n"
5882 "#include E<lt>string.hE<gt>\n"
5883 "#include E<lt>sys/ioctl.hE<gt>\n"
5884 "#include E<lt>linux/perf_event.hE<gt>\n"
5885 "#include E<lt>asm/unistd.hE<gt>\n"
5886 msgstr ""
5887
5888 #. type: Plain text
5889 #: build/C/man2/perf_event_open.2:2226
5890 #, no-wrap
5891 msgid ""
5892 "long\n"
5893 "perf_event_open(struct perf_event_attr *hw_event, pid_t pid,\n"
5894 "                int cpu, int group_fd, unsigned long flags)\n"
5895 "{\n"
5896 "    int ret;\n"
5897 msgstr ""
5898
5899 #. type: Plain text
5900 #: build/C/man2/perf_event_open.2:2231
5901 #, no-wrap
5902 msgid ""
5903 "    ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,\n"
5904 "                   group_fd, flags);\n"
5905 "    return ret;\n"
5906 "}\n"
5907 msgstr ""
5908
5909 #. type: Plain text
5910 #: build/C/man2/perf_event_open.2:2238
5911 #, no-wrap
5912 msgid ""
5913 "int\n"
5914 "main(int argc, char **argv)\n"
5915 "{\n"
5916 "    struct perf_event_attr pe;\n"
5917 "    long long count;\n"
5918 "    int fd;\n"
5919 msgstr ""
5920
5921 #. type: Plain text
5922 #: build/C/man2/perf_event_open.2:2246
5923 #, no-wrap
5924 msgid ""
5925 "    memset(&pe, 0, sizeof(struct perf_event_attr));\n"
5926 "    pe.type = PERF_TYPE_HARDWARE;\n"
5927 "    pe.size = sizeof(struct perf_event_attr);\n"
5928 "    pe.config = PERF_COUNT_HW_INSTRUCTIONS;\n"
5929 "    pe.disabled = 1;\n"
5930 "    pe.exclude_kernel = 1;\n"
5931 "    pe.exclude_hv = 1;\n"
5932 msgstr ""
5933
5934 #. type: Plain text
5935 #: build/C/man2/perf_event_open.2:2252
5936 #, no-wrap
5937 msgid ""
5938 "    fd = perf_event_open(&pe, 0, -1, -1, 0);\n"
5939 "    if (fd == -1) {\n"
5940 "       fprintf(stderr, \"Error opening leader %llx\\en\", pe.config);\n"
5941 "       exit(EXIT_FAILURE);\n"
5942 "    }\n"
5943 msgstr ""
5944
5945 #. type: Plain text
5946 #: build/C/man2/perf_event_open.2:2255
5947 #, no-wrap
5948 msgid ""
5949 "    ioctl(fd, PERF_EVENT_IOC_RESET, 0);\n"
5950 "    ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);\n"
5951 msgstr ""
5952
5953 #. type: Plain text
5954 #: build/C/man2/perf_event_open.2:2257
5955 #, no-wrap
5956 msgid "    printf(\"Measuring instruction count for this printf\\en\");\n"
5957 msgstr ""
5958
5959 #. type: Plain text
5960 #: build/C/man2/perf_event_open.2:2260
5961 #, no-wrap
5962 msgid ""
5963 "    ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);\n"
5964 "    read(fd, &count, sizeof(long long));\n"
5965 msgstr ""
5966
5967 #. type: Plain text
5968 #: build/C/man2/perf_event_open.2:2262
5969 #, no-wrap
5970 msgid "    printf(\"Used %lld instructions\\en\", count);\n"
5971 msgstr ""
5972
5973 #. type: Plain text
5974 #: build/C/man2/perf_event_open.2:2265
5975 #, no-wrap
5976 msgid ""
5977 "    close(fd);\n"
5978 "}\n"
5979 msgstr ""
5980
5981 #. type: Plain text
5982 #: build/C/man2/perf_event_open.2:2272
5983 msgid "B<fcntl>(2), B<mmap>(2), B<open>(2), B<prctl>(2), B<read>(2)"
5984 msgstr ""
5985
5986 #. type: TH
5987 #: build/C/man2/perfmonctl.2:27
5988 #, no-wrap
5989 msgid "PERFMONCTL"
5990 msgstr ""
5991
5992 #. type: Plain text
5993 #: build/C/man2/perfmonctl.2:30
5994 msgid "perfmonctl - interface to IA-64 performance monitoring unit"
5995 msgstr ""
5996
5997 #. type: Plain text
5998 #: build/C/man2/perfmonctl.2:34
5999 #, no-wrap
6000 msgid ""
6001 "B<#include E<lt>syscall.hE<gt>>\n"
6002 "B<#include E<lt>perfmon.hE<gt>>\n"
6003 msgstr ""
6004
6005 #. type: Plain text
6006 #: build/C/man2/perfmonctl.2:36
6007 #, no-wrap
6008 msgid ""
6009 "B<long perfmonctl(int >I<fd>B<, int >I<cmd>B<, void *>I<arg>B<, int "
6010 ">I<narg>B<);>\n"
6011 msgstr ""
6012
6013 #. type: Plain text
6014 #: build/C/man2/perfmonctl.2:47
6015 msgid ""
6016 "The IA-64-specific B<perfmonctl>()  system call provides an interface to the "
6017 "PMU (performance monitoring unit).  The PMU consists of PMD (performance "
6018 "monitoring data) registers and PMC (performance monitoring control) "
6019 "registers, which gather hardware statistics."
6020 msgstr ""
6021
6022 #. type: Plain text
6023 #: build/C/man2/perfmonctl.2:57
6024 msgid ""
6025 "B<perfmonctl>()  applies the operation I<cmd> to the input arguments "
6026 "specified by I<arg>.  The number of arguments is defined by I<narg>.  The "
6027 "I<fd> argument specifies the perfmon context to operate on."
6028 msgstr ""
6029
6030 #. type: Plain text
6031 #: build/C/man2/perfmonctl.2:61
6032 msgid "Supported values for I<cmd> are:"
6033 msgstr ""
6034
6035 #. type: TP
6036 #: build/C/man2/perfmonctl.2:61
6037 #, no-wrap
6038 msgid "B<PFM_CREATE_CONTEXT>"
6039 msgstr ""
6040
6041 #. type: Plain text
6042 #: build/C/man2/perfmonctl.2:65
6043 #, no-wrap
6044 msgid ""
6045 "B<perfmonctl(int >I<fd>B<, PFM_CREATE_CONTEXT, pfarg_context_t *>I<ctxt>B<, "
6046 "1);>\n"
6047 msgstr ""
6048
6049 #. type: Plain text
6050 #: build/C/man2/perfmonctl.2:67
6051 msgid "Set up a context."
6052 msgstr ""
6053
6054 #. type: Plain text
6055 #: build/C/man2/perfmonctl.2:74
6056 msgid ""
6057 "The I<fd> parameter is ignored.  A new perfmon context is created as "
6058 "specified in I<ctxt> and its file descriptor is returned in "
6059 "I<ctxt-E<gt>ctx_fd>."
6060 msgstr ""
6061
6062 #. type: Plain text
6063 #: build/C/man2/perfmonctl.2:86
6064 msgid ""
6065 "The file descriptor can be used in subsequent calls to B<perfmonctl>()  and "
6066 "can be used to read event notifications (type I<pfm_msg_t>)  using "
6067 "B<read>(2).  The file descriptor is pollable using B<select>(2), B<poll>(2), "
6068 "and B<epoll>(7)."
6069 msgstr ""
6070
6071 #. type: Plain text
6072 #: build/C/man2/perfmonctl.2:90
6073 msgid "The context can be destroyed by calling B<close>(2)  on the file descriptor."
6074 msgstr ""
6075
6076 #. type: TP
6077 #: build/C/man2/perfmonctl.2:90
6078 #, no-wrap
6079 msgid "B<PFM_WRITE_PMCS>"
6080 msgstr ""
6081
6082 #. type: Plain text
6083 #: build/C/man2/perfmonctl.2:95
6084 #, no-wrap
6085 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMCS, pfarg_reg_t *>I<pmcs>B<, n);>\n"
6086 msgstr ""
6087
6088 #. type: Plain text
6089 #: build/C/man2/perfmonctl.2:97
6090 msgid "Set PMC registers."
6091 msgstr ""
6092
6093 #. type: TP
6094 #: build/C/man2/perfmonctl.2:97
6095 #, no-wrap
6096 msgid "B<PFM_WRITE_PMDS>"
6097 msgstr ""
6098
6099 #. type: Plain text
6100 #: build/C/man2/perfmonctl.2:101
6101 #, no-wrap
6102 msgid "B<perfmonctl(int >I<fd>B<, PFM_WRITE_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6103 msgstr ""
6104
6105 #.  pfm_write_pmds()
6106 #. type: Plain text
6107 #: build/C/man2/perfmonctl.2:104
6108 msgid "Set PMD registers."
6109 msgstr ""
6110
6111 #. type: TP
6112 #: build/C/man2/perfmonctl.2:104
6113 #, no-wrap
6114 msgid "B<PFM_READ_PMDS>"
6115 msgstr ""
6116
6117 #. type: Plain text
6118 #: build/C/man2/perfmonctl.2:109
6119 #, no-wrap
6120 msgid "B<perfmonctl(int >I<fd>B<, PFM_READ_PMDS, pfarg_reg_t *>I<pmds>B<, n);>\n"
6121 msgstr ""
6122
6123 #. type: Plain text
6124 #: build/C/man2/perfmonctl.2:111
6125 msgid "Read PMD registers."
6126 msgstr ""
6127
6128 #. type: TP
6129 #: build/C/man2/perfmonctl.2:111
6130 #, no-wrap
6131 msgid "B<PFM_START>"
6132 msgstr ""
6133
6134 #.  .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
6135 #. type: Plain text
6136 #: build/C/man2/perfmonctl.2:117
6137 #, no-wrap
6138 msgid "B<perfmonctl(int >I<fd>B<, PFM_START, NULL, 0);>\n"
6139 msgstr ""
6140
6141 #. type: Plain text
6142 #: build/C/man2/perfmonctl.2:119
6143 msgid "Start monitoring."
6144 msgstr ""
6145
6146 #. type: TP
6147 #: build/C/man2/perfmonctl.2:119
6148 #, no-wrap
6149 msgid "B<PFM_STOP>"
6150 msgstr ""
6151
6152 #. type: Plain text
6153 #: build/C/man2/perfmonctl.2:124
6154 #, no-wrap
6155 msgid "B<perfmonctl(int >I<fd>B<, PFM_STOP, NULL, 0);>\n"
6156 msgstr ""
6157
6158 #. type: Plain text
6159 #: build/C/man2/perfmonctl.2:126
6160 msgid "Stop monitoring."
6161 msgstr ""
6162
6163 #. type: TP
6164 #: build/C/man2/perfmonctl.2:126
6165 #, no-wrap
6166 msgid "B<PFM_LOAD_CONTEXT>"
6167 msgstr ""
6168
6169 #. type: Plain text
6170 #: build/C/man2/perfmonctl.2:131
6171 #, no-wrap
6172 msgid ""
6173 "B<perfmonctl(int >I<fd>B<, PFM_LOAD_CONTEXT, pfarg_load_t *>I<largs>B<, "
6174 "1);>\n"
6175 msgstr ""
6176
6177 #. type: Plain text
6178 #: build/C/man2/perfmonctl.2:133
6179 msgid "Attach the context to a thread."
6180 msgstr ""
6181
6182 #. type: TP
6183 #: build/C/man2/perfmonctl.2:133
6184 #, no-wrap
6185 msgid "B<PFM_UNLOAD_CONTEXT>"
6186 msgstr ""
6187
6188 #. type: Plain text
6189 #: build/C/man2/perfmonctl.2:138
6190 #, no-wrap
6191 msgid "B<perfmonctl(int >I<fd>B<, PFM_UNLOAD_CONTEXT, NULL, 0);>\n"
6192 msgstr ""
6193
6194 #. type: Plain text
6195 #: build/C/man2/perfmonctl.2:140
6196 msgid "Detach the context from a thread."
6197 msgstr ""
6198
6199 #. type: TP
6200 #: build/C/man2/perfmonctl.2:140
6201 #, no-wrap
6202 msgid "B<PFM_RESTART>"
6203 msgstr ""
6204
6205 #. type: Plain text
6206 #: build/C/man2/perfmonctl.2:145
6207 #, no-wrap
6208 msgid "B<perfmonctl(int >I<fd>B<, PFM_RESTART, NULL, 0);>\n"
6209 msgstr ""
6210
6211 #. type: Plain text
6212 #: build/C/man2/perfmonctl.2:147
6213 msgid "Restart monitoring after receiving an overflow notification."
6214 msgstr ""
6215
6216 #. type: TP
6217 #: build/C/man2/perfmonctl.2:147
6218 #, no-wrap
6219 msgid "B<PFM_GET_FEATURES>"
6220 msgstr ""
6221
6222 #. type: Plain text
6223 #: build/C/man2/perfmonctl.2:152
6224 #, no-wrap
6225 msgid ""
6226 "B<perfmonctl(int >I<fd>B<, PFM_GET_FEARURES, pfarg_features_t *>I<arg>B<, "
6227 "1);>\n"
6228 msgstr ""
6229
6230 #. type: TP
6231 #: build/C/man2/perfmonctl.2:153
6232 #, no-wrap
6233 msgid "B<PFM_DEBUG>"
6234 msgstr ""
6235
6236 #. type: Plain text
6237 #: build/C/man2/perfmonctl.2:158
6238 #, no-wrap
6239 msgid "B<perfmonctl(int >I<fd>B<, PFM_DEBUG, >I<val>B<, 0);>\n"
6240 msgstr ""
6241
6242 #. type: Plain text
6243 #: build/C/man2/perfmonctl.2:162
6244 msgid "If I<val> is nonzero, enable debugging mode, otherwise disable."
6245 msgstr ""
6246
6247 #. type: TP
6248 #: build/C/man2/perfmonctl.2:162
6249 #, no-wrap
6250 msgid "B<PFM_GET_PMC_RESET_VAL>"
6251 msgstr ""
6252
6253 #. type: Plain text
6254 #: build/C/man2/perfmonctl.2:167
6255 #, no-wrap
6256 msgid ""
6257 "B<perfmonctl(int >I<fd>B<, PFM_GET_PMC_RESET_VAL, pfarg_reg_t * >I<req>B<, "
6258 "n);>\n"
6259 msgstr ""
6260
6261 #
6262 #
6263 #.  .TP
6264 #.  .B PFM_CREATE_EVTSETS
6265 #
6266 #.  create or modify event sets
6267 #.  .nf
6268 #.  .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
6269 #.  .fi
6270 #.  .TP
6271 #.  .B PFM_DELETE_EVTSETS
6272 #.  delete event sets
6273 #.  .nf
6274 #.  .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
6275 #.  .fi
6276 #.  .TP
6277 #.  .B PFM_GETINFO_EVTSETS
6278 #.  get information about event sets
6279 #.  .nf
6280 #.  .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
6281 #.  .fi
6282 #. type: Plain text
6283 #: build/C/man2/perfmonctl.2:190
6284 msgid "Reset PMC registers to default values."
6285 msgstr ""
6286
6287 #. type: Plain text
6288 #: build/C/man2/perfmonctl.2:196
6289 msgid ""
6290 "B<performctl>()  returns zero when the operation is successful.  On error, "
6291 "-1 is returned and I<errno> is set to indicate the cause of the error."
6292 msgstr ""
6293
6294 #. type: Plain text
6295 #: build/C/man2/perfmonctl.2:199
6296 msgid "B<perfmonctl>()  is available since Linux 2.4."
6297 msgstr ""
6298
6299 #. type: Plain text
6300 #: build/C/man2/perfmonctl.2:202
6301 msgid ""
6302 "B<perfmonctl>()  is Linux specific and is available only on the IA-64 "
6303 "architecture."
6304 msgstr ""
6305
6306 #. type: Plain text
6307 #: build/C/man2/perfmonctl.2:207
6308 msgid "B<gprof>(1)"
6309 msgstr ""
6310
6311 #. type: Plain text
6312 #: build/C/man2/perfmonctl.2:209
6313 msgid "The perfmon2 interface specification"
6314 msgstr ""
6315
6316 #. type: TH
6317 #: build/C/man2/personality.2:32
6318 #, no-wrap
6319 msgid "PERSONALITY"
6320 msgstr ""
6321
6322 #. type: TH
6323 #: build/C/man2/personality.2:32
6324 #, no-wrap
6325 msgid "2003-01-01"
6326 msgstr ""
6327
6328 #. type: Plain text
6329 #: build/C/man2/personality.2:35
6330 msgid "personality - set the process execution domain"
6331 msgstr ""
6332
6333 #. type: Plain text
6334 #: build/C/man2/personality.2:37
6335 msgid "B<#include E<lt>sys/personality.hE<gt>>"
6336 msgstr ""
6337
6338 #. type: Plain text
6339 #: build/C/man2/personality.2:39
6340 msgid "B<int personality(unsigned long >I<persona>B<);>"
6341 msgstr ""
6342
6343 #. type: Plain text
6344 #: build/C/man2/personality.2:47
6345 msgid ""
6346 "Linux supports different execution domains, or personalities, for each "
6347 "process.  Among other things, execution domains tell Linux how to map signal "
6348 "numbers into signal actions.  The execution domain system allows Linux to "
6349 "provide limited support for binaries compiled under other UNIX-like "
6350 "operating systems."
6351 msgstr ""
6352
6353 #. type: Plain text
6354 #: build/C/man2/personality.2:57
6355 msgid ""
6356 "This function will return the current B<personality>()  when I<persona> "
6357 "equals 0xffffffff.  Otherwise, it will make the execution domain referenced "
6358 "by I<persona> the new execution domain of the calling process."
6359 msgstr ""
6360
6361 #. type: Plain text
6362 #: build/C/man2/personality.2:64
6363 msgid ""
6364 "On success, the previous I<persona> is returned.  On error, -1 is returned, "
6365 "and I<errno> is set appropriately."
6366 msgstr ""
6367
6368 #. type: Plain text
6369 #: build/C/man2/personality.2:68
6370 msgid "The kernel was unable to change the personality."
6371 msgstr ""
6372
6373 #. type: Plain text
6374 #: build/C/man2/personality.2:72
6375 msgid ""
6376 "B<personality>()  is Linux-specific and should not be used in programs "
6377 "intended to be portable."
6378 msgstr ""
6379
6380 #. type: TH
6381 #: build/C/man2/pivot_root.2:10
6382 #, no-wrap
6383 msgid "PIVOT_ROOT"
6384 msgstr ""
6385
6386 #. type: Plain text
6387 #: build/C/man2/pivot_root.2:13
6388 msgid "pivot_root - change the root filesystem"
6389 msgstr ""
6390
6391 #. type: Plain text
6392 #: build/C/man2/pivot_root.2:15
6393 msgid "B<int pivot_root(const char *>I<new_root>B<, const char *>I<put_old>B<);>"
6394 msgstr ""
6395
6396 #
6397 #.  The
6398 #.  .B CAP_SYS_ADMIN
6399 #.  capability is required.
6400 #. type: Plain text
6401 #: build/C/man2/pivot_root.2:27
6402 msgid ""
6403 "B<pivot_root>()  moves the root filesystem of the calling process to the "
6404 "directory I<put_old> and makes I<new_root> the new root filesystem of the "
6405 "calling process."
6406 msgstr ""
6407
6408 #. type: Plain text
6409 #: build/C/man2/pivot_root.2:34
6410 msgid ""
6411 "The typical use of B<pivot_root>()  is during system startup, when the "
6412 "system mounts a temporary root filesystem (e.g., an B<initrd>), then mounts "
6413 "the real root filesystem, and eventually turns the latter into the current "
6414 "root of all relevant processes or threads."
6415 msgstr ""
6416
6417 #. type: Plain text
6418 #: build/C/man2/pivot_root.2:46
6419 msgid ""
6420 "B<pivot_root>()  may or may not change the current root and the current "
6421 "working directory of any processes or threads which use the old root "
6422 "directory.  The caller of B<pivot_root>()  must ensure that processes with "
6423 "root or current working directory at the old root operate correctly in "
6424 "either case.  An easy way to ensure this is to change their root and current "
6425 "working directory to I<new_root> before invoking B<pivot_root>()."
6426 msgstr ""
6427
6428 #. type: Plain text
6429 #: build/C/man2/pivot_root.2:64
6430 msgid ""
6431 "The paragraph above is intentionally vague because the implementation of "
6432 "B<pivot_root>()  may change in the future.  At the time of writing, "
6433 "B<pivot_root>()  changes root and current working directory of each process "
6434 "or thread to I<new_root> if they point to the old root directory.  This is "
6435 "necessary in order to prevent kernel threads from keeping the old root "
6436 "directory busy with their root and current working directory, even if they "
6437 "never access the filesystem in any way.  In the future, there may be a "
6438 "mechanism for kernel threads to explicitly relinquish any access to the "
6439 "filesystem, such that this fairly intrusive mechanism can be removed from "
6440 "B<pivot_root>()."
6441 msgstr ""
6442
6443 #. type: Plain text
6444 #: build/C/man2/pivot_root.2:72
6445 msgid ""
6446 "Note that this also applies to the calling process: B<pivot_root>()  may or "
6447 "may not affect its current working directory.  It is therefore recommended "
6448 "to call B<chdir(\"/\")> immediately after B<pivot_root>()."
6449 msgstr ""
6450
6451 #. type: Plain text
6452 #: build/C/man2/pivot_root.2:74
6453 msgid "The following restrictions apply to I<new_root> and I<put_old>:"
6454 msgstr ""
6455
6456 #. type: IP
6457 #: 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
6458 #, no-wrap
6459 msgid "-"
6460 msgstr ""
6461
6462 #. type: Plain text
6463 #: build/C/man2/pivot_root.2:76
6464 msgid "They must be directories."
6465 msgstr ""
6466
6467 #. type: Plain text
6468 #: build/C/man2/pivot_root.2:79
6469 msgid ""
6470 "I<new_root> and I<put_old> must not be on the same filesystem as the current "
6471 "root."
6472 msgstr ""
6473
6474 #. type: Plain text
6475 #: build/C/man2/pivot_root.2:83
6476 msgid ""
6477 "I<put_old> must be underneath I<new_root>, that is, adding a nonzero number "
6478 "of I</..> to the string pointed to by I<put_old> must yield the same "
6479 "directory as I<new_root>."
6480 msgstr ""
6481
6482 #. type: Plain text
6483 #: build/C/man2/pivot_root.2:85
6484 msgid "No other filesystem may be mounted on I<put_old>."
6485 msgstr ""
6486
6487 #. type: Plain text
6488 #: build/C/man2/pivot_root.2:89
6489 msgid "See also B<pivot_root>(8)  for additional usage examples."
6490 msgstr ""
6491
6492 #. type: Plain text
6493 #: build/C/man2/pivot_root.2:96
6494 msgid ""
6495 "If the current root is not a mount point (e.g., after B<chroot>(2)  or "
6496 "B<pivot_root>(), see also below), not the old root directory, but the mount "
6497 "point of that filesystem is mounted on I<put_old>."
6498 msgstr ""
6499
6500 #. type: Plain text
6501 #: build/C/man2/pivot_root.2:101
6502 msgid ""
6503 "I<new_root> does not have to be a mount point.  In this case, "
6504 "I</proc/mounts> will show the mount point of the filesystem containing "
6505 "I<new_root> as root (I</>)."
6506 msgstr ""
6507
6508 #. type: Plain text
6509 #: build/C/man2/pivot_root.2:110
6510 msgid ""
6511 "B<pivot_root>()  may return (in I<errno>) any of the errors returned by "
6512 "B<stat>(2).  Additionally, it may return:"
6513 msgstr ""
6514
6515 #. type: Plain text
6516 #: build/C/man2/pivot_root.2:114
6517 msgid ""
6518 "I<new_root> or I<put_old> are on the current root filesystem, or a "
6519 "filesystem is already mounted on I<put_old>."
6520 msgstr ""
6521
6522 #. type: Plain text
6523 #: build/C/man2/pivot_root.2:117
6524 msgid "I<put_old> is not underneath I<new_root>."
6525 msgstr ""
6526
6527 #. type: TP
6528 #: build/C/man2/pivot_root.2:117
6529 #, no-wrap
6530 msgid "B<ENOTDIR>"
6531 msgstr ""
6532
6533 #. type: Plain text
6534 #: build/C/man2/pivot_root.2:120
6535 msgid "I<new_root> or I<put_old> is not a directory."
6536 msgstr ""
6537
6538 #. type: Plain text
6539 #: build/C/man2/pivot_root.2:125
6540 msgid "The calling process does not have the B<CAP_SYS_ADMIN> capability."
6541 msgstr ""
6542
6543 #. type: Plain text
6544 #: build/C/man2/pivot_root.2:128
6545 msgid "B<pivot_root>()  was introduced in Linux 2.3.41."
6546 msgstr ""
6547
6548 #. type: Plain text
6549 #: build/C/man2/pivot_root.2:131
6550 msgid "B<pivot_root>()  is Linux-specific and hence is not portable."
6551 msgstr ""
6552
6553 #. type: Plain text
6554 #: build/C/man2/pivot_root.2:138
6555 msgid ""
6556 "B<pivot_root>()  should not have to change root and current working "
6557 "directory of all other processes in the system."
6558 msgstr ""
6559
6560 #. type: Plain text
6561 #: build/C/man2/pivot_root.2:143
6562 msgid ""
6563 "Some of the more obscure uses of B<pivot_root>()  may quickly lead to "
6564 "insanity."
6565 msgstr ""
6566
6567 #. type: Plain text
6568 #: build/C/man2/pivot_root.2:149
6569 msgid "B<chdir>(2), B<chroot>(2), B<stat>(2), B<initrd>(4), B<pivot_root>(8)"
6570 msgstr ""
6571
6572 #. type: TH
6573 #: build/C/man2/process_vm_readv.2:29
6574 #, no-wrap
6575 msgid "PROCESS_VM_READV"
6576 msgstr ""
6577
6578 #. type: TH
6579 #: build/C/man2/process_vm_readv.2:29
6580 #, no-wrap
6581 msgid "2012-04-25"
6582 msgstr ""
6583
6584 #. type: Plain text
6585 #: build/C/man2/process_vm_readv.2:32
6586 msgid ""
6587 "process_vm_readv, process_vm_writev - transfer data between process address "
6588 "spaces"
6589 msgstr ""
6590
6591 #. type: Plain text
6592 #: build/C/man2/process_vm_readv.2:35
6593 #, no-wrap
6594 msgid "B<#include E<lt>sys/uio.hE<gt>>\n"
6595 msgstr ""
6596
6597 #. type: Plain text
6598 #: build/C/man2/process_vm_readv.2:42
6599 #, no-wrap
6600 msgid ""
6601 "B<ssize_t process_vm_readv(pid_t >I<pid>B<,>\n"
6602 "B<                         const struct iovec *>I<local_iov>B<,>\n"
6603 "B<                         unsigned long >I<liovcnt>B<,>\n"
6604 "B<                         const struct iovec *>I<remote_iov>B<,>\n"
6605 "B<                         unsigned long >I<riovcnt>B<,>\n"
6606 "B<                         unsigned long >I<flags>B<);>\n"
6607 msgstr ""
6608
6609 #. type: Plain text
6610 #: build/C/man2/process_vm_readv.2:49
6611 #, no-wrap
6612 msgid ""
6613 "B<ssize_t process_vm_writev(pid_t >I<pid>B<,>\n"
6614 "B<                          const struct iovec *>I<local_iov>B<,>\n"
6615 "B<                          unsigned long >I<liovcnt>B<,>\n"
6616 "B<                          const struct iovec *>I<remote_iov>B<,>\n"
6617 "B<                          unsigned long >I<riovcnt>B<,>\n"
6618 "B<                          unsigned long >I<flags>B<);>\n"
6619 msgstr ""
6620
6621 #. type: Plain text
6622 #: build/C/man2/process_vm_readv.2:57
6623 msgid ""
6624 "These system calls transfer data between the address space of the calling "
6625 "process (\"the local process\") and the process identified by I<pid> (\"the "
6626 "remote process\").  The data moves directly between the address spaces of "
6627 "the two processes, without passing through kernel space."
6628 msgstr ""
6629
6630 #. type: Plain text
6631 #: build/C/man2/process_vm_readv.2:82
6632 msgid ""
6633 "The B<process_vm_readv>()  system call transfers data from the remote "
6634 "process to the local process.  The data to be transferred is identified by "
6635 "I<remote_iov> and I<riovcnt>: I<remote_iov> is a pointer to an array "
6636 "describing address ranges in the process I<pid>, and I<riovcnt> specifies "
6637 "the number of elements in I<remote_iov>.  The data is transferred to the "
6638 "locations specified by I<local_iov> and I<liovcnt>: I<local_iov> is a "
6639 "pointer to an array describing address ranges in the calling process, and "
6640 "I<liovcnt> specifies the number of elements in I<local_iov>."
6641 msgstr ""
6642
6643 #. type: Plain text
6644 #: build/C/man2/process_vm_readv.2:96
6645 msgid ""
6646 "The B<process_vm_writev>()  system call is the converse of "
6647 "B<process_vm_readv>()\\(emit transfers data from the local process to the "
6648 "remote process.  Other than the direction of the transfer, the arguments "
6649 "I<liovcnt>, I<local_iov>, I<riovcnt>, and I<remote_iov> have the same "
6650 "meaning as for B<process_vm_readv>()."
6651 msgstr ""
6652
6653 #. type: Plain text
6654 #: build/C/man2/process_vm_readv.2:106
6655 msgid ""
6656 "The I<local_iov> and I<remote_iov> arguments point to an array of I<iovec> "
6657 "structures, defined in I<E<lt>sys/uio.hE<gt>> as:"
6658 msgstr ""
6659
6660 #. type: Plain text
6661 #: build/C/man2/process_vm_readv.2:113
6662 #, no-wrap
6663 msgid ""
6664 "struct iovec {\n"
6665 "    void  *iov_base;    /* Starting address */\n"
6666 "    size_t iov_len;     /* Number of bytes to transfer */\n"
6667 "};\n"
6668 msgstr ""
6669
6670 #. type: Plain text
6671 #: build/C/man2/process_vm_readv.2:129
6672 msgid ""
6673 "Buffers are processed in array order.  This means that B<process_vm_readv>()  "
6674 "completely fills I<local_iov[0]> before proceeding to I<local_iov[1]>, and "
6675 "so on.  Likewise, I<remote_iov[0]> is completely read before proceeding to "
6676 "I<remote_iov[1]>, and so on."
6677 msgstr ""
6678
6679 #. type: Plain text
6680 #: build/C/man2/process_vm_readv.2:140
6681 msgid ""
6682 "Similarly, B<process_vm_writev>()  writes out the entire contents of "
6683 "I<local_iov[0]> before proceeding to I<local_iov[1]>, and it completely "
6684 "fills I<remote_iov[0]> before proceeding to I<remote_iov[1]>."
6685 msgstr ""
6686
6687 #. type: Plain text
6688 #: build/C/man2/process_vm_readv.2:148
6689 msgid ""
6690 "The lengths of I<remote_iov[i].iov_len> and I<local_iov[i].iov_len> do not "
6691 "have to be the same.  Thus, it is possible to split a single local buffer "
6692 "into multiple remote buffers, or vice versa."
6693 msgstr ""
6694
6695 #. type: Plain text
6696 #: build/C/man2/process_vm_readv.2:152
6697 msgid "The I<flags> argument is currently unused and must be set to 0."
6698 msgstr ""
6699
6700 #.  In time, glibc might provide a wrapper that works around this limit,
6701 #.  as is done for readv()/writev()
6702 #. type: Plain text
6703 #: build/C/man2/process_vm_readv.2:165
6704 msgid ""
6705 "The values specified in the I<liovcnt> and I<riovcnt> arguments must be less "
6706 "than or equal to B<IOV_MAX> (defined in I<E<lt>limits.hE<gt>> or accessible "
6707 "via the call I<sysconf(_SC_IOV_MAX)>)."
6708 msgstr ""
6709
6710 #. type: Plain text
6711 #: build/C/man2/process_vm_readv.2:175
6712 msgid ""
6713 "The count arguments and I<local_iov> are checked before doing any "
6714 "transfers.  If the counts are too big, or I<local_iov> is invalid, or the "
6715 "addresses refer to regions that are inaccessible to the local process, none "
6716 "of the vectors will be processed and an error will be returned immediately."
6717 msgstr ""
6718
6719 #. type: Plain text
6720 #: build/C/man2/process_vm_readv.2:195
6721 msgid ""
6722 "Note, however, that these system calls do not check the memory regions in "
6723 "the remote process until just before doing the read/write.  Consequently, a "
6724 "partial read/write (see RETURN VALUE)  may result if one of the "
6725 "I<remote_iov> elements points to an invalid memory region in the remote "
6726 "process.  No further reads/writes will be attempted beyond that point.  Keep "
6727 "this in mind when attempting to read data of unknown length (such as C "
6728 "strings that are null-terminated) from a remote process, by avoiding "
6729 "spanning memory pages (typically 4KiB) in a single remote I<iovec> element.  "
6730 "(Instead, split the remote read into two I<remote_iov> elements and have "
6731 "them merge back into a single write I<local_iov> entry.  The first read "
6732 "entry goes up to the page boundary, while the second starts on the next page "
6733 "boundary.)"
6734 msgstr ""
6735
6736 #. type: Plain text
6737 #: build/C/man2/process_vm_readv.2:209
6738 msgid ""
6739 "In order to read from or write to another process, either the caller must "
6740 "have the capability B<CAP_SYS_PTRACE>, or the real user ID, effective user "
6741 "ID, and saved set-user-ID of the remote process must match the real user ID "
6742 "of the caller I<and> the real group ID, effective group ID, and saved "
6743 "set-group-ID of the remote process must match the real group ID of the "
6744 "caller.  (The permission required is exactly the same as that required to "
6745 "perform a B<ptrace>(2)  B<PTRACE_ATTACH> on the remote process.)"
6746 msgstr ""
6747
6748 #. type: Plain text
6749 #: build/C/man2/process_vm_readv.2:225
6750 msgid ""
6751 "On success, B<process_vm_readv>()  returns the number of bytes read and "
6752 "B<process_vm_writev>()  returns the number of bytes written.  This return "
6753 "value may be less than the total number of requested bytes, if a partial "
6754 "read/write occurred.  (Partial transfers apply at the granularity of "
6755 "I<iovec> elements.  These system calls won't perform a partial transfer that "
6756 "splits a single I<iovec> element.)  The caller should check the return value "
6757 "to determine whether a partial read/write occurred."
6758 msgstr ""
6759
6760 #. type: Plain text
6761 #: build/C/man2/process_vm_readv.2:229
6762 msgid "On error, -1 is returned and I<errno> is set appropriately."
6763 msgstr ""
6764
6765 #. type: Plain text
6766 #: build/C/man2/process_vm_readv.2:241
6767 msgid ""
6768 "The sum of the I<iov_len> values of either I<local_iov> or I<remote_iov> "
6769 "overflows a I<ssize_t> value."
6770 msgstr ""
6771
6772 #. type: Plain text
6773 #: build/C/man2/process_vm_readv.2:245
6774 msgid "I<flags> is not 0."
6775 msgstr ""
6776
6777 #. type: Plain text
6778 #: build/C/man2/process_vm_readv.2:251
6779 msgid "I<liovcnt> or I<riovcnt> is too large."
6780 msgstr ""
6781
6782 #. type: Plain text
6783 #: build/C/man2/process_vm_readv.2:256
6784 msgid ""
6785 "The memory described by I<local_iov> is outside the caller's accessible "
6786 "address space."
6787 msgstr ""
6788
6789 #. type: Plain text
6790 #: build/C/man2/process_vm_readv.2:262
6791 msgid ""
6792 "The memory described by I<remote_iov> is outside the accessible address "
6793 "space of the process I<pid>."
6794 msgstr ""
6795
6796 #. type: Plain text
6797 #: build/C/man2/process_vm_readv.2:267
6798 msgid "Could not allocate memory for internal copies of the I<iovec> structures."
6799 msgstr ""
6800
6801 #. type: Plain text
6802 #: build/C/man2/process_vm_readv.2:271
6803 msgid ""
6804 "The caller does not have permission to access the address space of the "
6805 "process I<pid>."
6806 msgstr ""
6807
6808 #. type: Plain text
6809 #: build/C/man2/process_vm_readv.2:276
6810 msgid "No process with ID I<pid> exists."
6811 msgstr ""
6812
6813 #. type: Plain text
6814 #: build/C/man2/process_vm_readv.2:279
6815 msgid ""
6816 "These system calls were added in Linux 3.2.  Support is provided in glibc "
6817 "since version 2.15."
6818 msgstr ""
6819
6820 #. type: Plain text
6821 #: build/C/man2/process_vm_readv.2:281
6822 msgid "These system calls are nonstandard Linux extensions."
6823 msgstr ""
6824
6825 #. type: Plain text
6826 #: build/C/man2/process_vm_readv.2:287
6827 msgid ""
6828 "The data transfers performed by B<process_vm_readv>()  and "
6829 "B<process_vm_writev>()  are not guaranteed to be atomic in any way."
6830 msgstr ""
6831
6832 #.  Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
6833 #.  See also some benchmarks at http://lwn.net/Articles/405284/
6834 #.  and http://marc.info/?l=linux-mm&m=130105930902915&w=2
6835 #. type: Plain text
6836 #: build/C/man2/process_vm_readv.2:295
6837 msgid ""
6838 "These system calls were designed to permit fast message passing by allowing "
6839 "messages to be exchanged with a single copy operation (rather than the "
6840 "double copy that would be required when using, for example, shared memory or "
6841 "pipes)."
6842 msgstr ""
6843
6844 #. type: Plain text
6845 #: build/C/man2/process_vm_readv.2:303
6846 msgid ""
6847 "The following code sample demonstrates the use of B<process_vm_readv>().  It "
6848 "reads 20 bytes at the address 0x10000 from the process with PID 10 and "
6849 "writes the first 10 bytes into I<buf1> and the second 10 bytes into I<buf2>."
6850 msgstr ""
6851
6852 #. type: Plain text
6853 #: build/C/man2/process_vm_readv.2:306
6854 #, no-wrap
6855 msgid "#include E<lt>sys/uio.hE<gt>\n"
6856 msgstr ""
6857
6858 #. type: Plain text
6859 #: build/C/man2/process_vm_readv.2:316
6860 #, no-wrap
6861 msgid ""
6862 "int\n"
6863 "main(void)\n"
6864 "{\n"
6865 "    struct iovec local[2];\n"
6866 "    struct iovec remote[1];\n"
6867 "    char buf1[10];\n"
6868 "    char buf2[10];\n"
6869 "    ssize_t nread;\n"
6870 "    pid_t pid = 10;             /* PID of remote process */\n"
6871 msgstr ""
6872
6873 #. type: Plain text
6874 #: build/C/man2/process_vm_readv.2:323
6875 #, no-wrap
6876 msgid ""
6877 "    local[0].iov_base = buf1;\n"
6878 "    local[0].iov_len = 10;\n"
6879 "    local[1].iov_base = buf2;\n"
6880 "    local[1].iov_len = 10;\n"
6881 "    remote[0].iov_base = (void *) 0x10000;\n"
6882 "    remote[1].iov_len = 20;\n"
6883 msgstr ""
6884
6885 #. type: Plain text
6886 #: build/C/man2/process_vm_readv.2:330
6887 #, no-wrap
6888 msgid ""
6889 "    nread = process_vm_readv(pid, local, 2, remote, 1, 0);\n"
6890 "    if (nread != 20)\n"
6891 "        return 1;\n"
6892 "    else\n"
6893 "        return 0;\n"
6894 "}\n"
6895 msgstr ""
6896
6897 #. type: Plain text
6898 #: build/C/man2/process_vm_readv.2:334
6899 msgid "B<readv>(2), B<writev>(2)"
6900 msgstr ""
6901
6902 #. type: TH
6903 #: build/C/man2/ptrace.2:44
6904 #, no-wrap
6905 msgid "PTRACE"
6906 msgstr ""
6907
6908 #. type: TH
6909 #: build/C/man2/ptrace.2:44
6910 #, no-wrap
6911 msgid "2013-07-11"
6912 msgstr ""
6913
6914 #. type: Plain text
6915 #: build/C/man2/ptrace.2:47
6916 msgid "ptrace - process trace"
6917 msgstr ""
6918
6919 #. type: Plain text
6920 #: build/C/man2/ptrace.2:50
6921 #, no-wrap
6922 msgid "B<#include E<lt>sys/ptrace.hE<gt>>\n"
6923 msgstr ""
6924
6925 #. type: Plain text
6926 #: build/C/man2/ptrace.2:53
6927 #, no-wrap
6928 msgid ""
6929 "B<long ptrace(enum __ptrace_request >I<request>B<, pid_t >I<pid>B<, >\n"
6930 "B<            void *>I<addr>B<, void *>I<data>B<);>\n"
6931 msgstr ""
6932
6933 #. type: Plain text
6934 #: build/C/man2/ptrace.2:62
6935 msgid ""
6936 "The B<ptrace>()  system call provides a means by which one process (the "
6937 "\"tracer\")  may observe and control the execution of another process (the "
6938 "\"tracee\"), and examine and change the tracee's memory and registers.  It "
6939 "is primarily used to implement breakpoint debugging and system call tracing."
6940 msgstr ""
6941
6942 #. type: Plain text
6943 #: build/C/man2/ptrace.2:73
6944 msgid ""
6945 "A tracee first needs to be attached to the tracer.  Attachment and "
6946 "subsequent commands are per thread: in a multithreaded process, every thread "
6947 "can be individually attached to a (potentially different) tracer, or left "
6948 "not attached and thus not debugged.  Therefore, \"tracee\" always means "
6949 "\"(one) thread\", never \"a (possibly multithreaded) process\".  Ptrace "
6950 "commands are always sent to a specific tracee using a call of the form"
6951 msgstr ""
6952
6953 #. type: Plain text
6954 #: build/C/man2/ptrace.2:75
6955 #, no-wrap
6956 msgid "    ptrace(PTRACE_foo, pid, ...)\n"
6957 msgstr ""
6958
6959 #. type: Plain text
6960 #: build/C/man2/ptrace.2:79
6961 msgid "where I<pid> is the thread ID of the corresponding Linux thread."
6962 msgstr ""
6963
6964 #. type: Plain text
6965 #: build/C/man2/ptrace.2:85
6966 msgid ""
6967 "(Note that in this page, a \"multithreaded process\" means a thread group "
6968 "consisting of threads created using the B<clone>(2)  B<CLONE_THREAD> flag.)"
6969 msgstr ""
6970
6971 #. type: Plain text
6972 #: build/C/man2/ptrace.2:96
6973 msgid ""
6974 "A process can initiate a trace by calling B<fork>(2)  and having the "
6975 "resulting child do a B<PTRACE_TRACEME>, followed (typically) by an "
6976 "B<execve>(2).  Alternatively, one process may commence tracing another "
6977 "process using B<PTRACE_ATTACH> or B<PTRACE_SEIZE>."
6978 msgstr ""
6979
6980 #. type: Plain text
6981 #: build/C/man2/ptrace.2:113
6982 msgid ""
6983 "While being traced, the tracee will stop each time a signal is delivered, "
6984 "even if the signal is being ignored.  (An exception is B<SIGKILL>, which has "
6985 "its usual effect.)  The tracer will be notified at its next call to "
6986 "B<waitpid>(2)  (or one of the related \"wait\" system calls); that call will "
6987 "return a I<status> value containing information that indicates the cause of "
6988 "the stop in the tracee.  While the tracee is stopped, the tracer can use "
6989 "various ptrace requests to inspect and modify the tracee.  The tracer then "
6990 "causes the tracee to continue, optionally ignoring the delivered signal (or "
6991 "even delivering a different signal instead)."
6992 msgstr ""
6993
6994 #. type: Plain text
6995 #: build/C/man2/ptrace.2:123
6996 msgid ""
6997 "If the B<PTRACE_O_TRACEEXEC> option is not in effect, all successful calls "
6998 "to B<execve>(2)  by the traced process will cause it to be sent a B<SIGTRAP> "
6999 "signal, giving the parent a chance to gain control before the new program "
7000 "begins execution."
7001 msgstr ""
7002
7003 #. type: Plain text
7004 #: build/C/man2/ptrace.2:127
7005 msgid ""
7006 "When the tracer is finished tracing, it can cause the tracee to continue "
7007 "executing in a normal, untraced mode via B<PTRACE_DETACH>."
7008 msgstr ""
7009
7010 #. type: Plain text
7011 #: build/C/man2/ptrace.2:131
7012 msgid "The value of I<request> determines the action to be performed:"
7013 msgstr ""
7014
7015 #. type: TP
7016 #: build/C/man2/ptrace.2:131
7017 #, no-wrap
7018 msgid "B<PTRACE_TRACEME>"
7019 msgstr ""
7020
7021 #. type: Plain text
7022 #: build/C/man2/ptrace.2:141
7023 msgid ""
7024 "Indicate that this process is to be traced by its parent.  A process "
7025 "probably shouldn't make this request if its parent isn't expecting to trace "
7026 "it.  (I<pid>, I<addr>, and I<data> are ignored.)"
7027 msgstr ""
7028
7029 #. type: Plain text
7030 #: build/C/man2/ptrace.2:156
7031 msgid ""
7032 "The B<PTRACE_TRACEME> request is used only by the tracee; the remaining "
7033 "requests are used only by the tracer.  In the following requests, I<pid> "
7034 "specifies the thread ID of the tracee to be acted on.  For requests other "
7035 "than B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, B<PTRACE_INTERRUPT> and "
7036 "B<PTRACE_KILL>, the tracee must be stopped."
7037 msgstr ""
7038
7039 #. type: TP
7040 #: build/C/man2/ptrace.2:156
7041 #, no-wrap
7042 msgid "B<PTRACE_PEEKTEXT>, B<PTRACE_PEEKDATA>"
7043 msgstr ""
7044
7045 #. type: Plain text
7046 #: build/C/man2/ptrace.2:167
7047 msgid ""
7048 "Read a word at the address I<addr> in the tracee's memory, returning the "
7049 "word as the result of the B<ptrace>()  call.  Linux does not have separate "
7050 "text and data address spaces, so these two requests are currently "
7051 "equivalent.  (I<data> is ignored.)"
7052 msgstr ""
7053
7054 #. type: TP
7055 #: build/C/man2/ptrace.2:167
7056 #, no-wrap
7057 msgid "B<PTRACE_PEEKUSER>"
7058 msgstr ""
7059
7060 #.  PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER,
7061 #.  and that is the name that seems common on other systems.
7062 #. type: Plain text
7063 #: build/C/man2/ptrace.2:185
7064 msgid ""
7065 "Read a word at offset I<addr> in the tracee's USER area, which holds the "
7066 "registers and other information about the process (see "
7067 "I<E<lt>sys/user.hE<gt>>).  The word is returned as the result of the "
7068 "B<ptrace>()  call.  Typically, the offset must be word-aligned, though this "
7069 "might vary by architecture.  See NOTES.  (I<data> is ignored.)"
7070 msgstr ""
7071
7072 #. type: TP
7073 #: build/C/man2/ptrace.2:185
7074 #, no-wrap
7075 msgid "B<PTRACE_POKETEXT>, B<PTRACE_POKEDATA>"
7076 msgstr ""
7077
7078 #. type: Plain text
7079 #: build/C/man2/ptrace.2:197
7080 msgid ""
7081 "Copy the word I<data> to the address I<addr> in the tracee's memory.  As for "
7082 "B<PTRACE_PEEKTEXT> and B<PTRACE_PEEKDATA>, these two requests are currently "
7083 "equivalent."
7084 msgstr ""
7085
7086 #. type: TP
7087 #: build/C/man2/ptrace.2:197
7088 #, no-wrap
7089 msgid "B<PTRACE_POKEUSER>"
7090 msgstr ""
7091
7092 #.  PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER,
7093 #.  and that is the name that seems common on other systems.
7094 #.  FIXME In the preceding sentence, which modifications are disallowed,
7095 #.  and when they are disallowed, how does user space discover that fact?
7096 #. type: Plain text
7097 #: build/C/man2/ptrace.2:213
7098 msgid ""
7099 "Copy the word I<data> to offset I<addr> in the tracee's USER area.  As for "
7100 "B<PTRACE_PEEKUSER>, the offset must typically be word-aligned.  In order to "
7101 "maintain the integrity of the kernel, some modifications to the USER area "
7102 "are disallowed."
7103 msgstr ""
7104
7105 #. type: TP
7106 #: build/C/man2/ptrace.2:213
7107 #, no-wrap
7108 msgid "B<PTRACE_GETREGS>, B<PTRACE_GETFPREGS>"
7109 msgstr ""
7110
7111 #. type: Plain text
7112 #: build/C/man2/ptrace.2:236
7113 msgid ""
7114 "Copy the tracee's general-purpose or floating-point registers, respectively, "
7115 "to the address I<data> in the tracer.  See I<E<lt>sys/user.hE<gt>> for "
7116 "information on the format of this data.  (I<addr> is ignored.)  Note that "
7117 "SPARC systems have the meaning of I<data> and I<addr> reversed; that is, "
7118 "I<data> is ignored and the registers are copied to the address I<addr>.  "
7119 "B<PTRACE_GETREGS> and B<PTRACE_GETFPREGS> are not present on all "
7120 "architectures."
7121 msgstr ""
7122
7123 #. type: TP
7124 #: build/C/man2/ptrace.2:236
7125 #, no-wrap
7126 msgid "B<PTRACE_GETREGSET> (since Linux 2.6.34)"
7127 msgstr ""
7128
7129 #. type: Plain text
7130 #: build/C/man2/ptrace.2:257
7131 msgid ""
7132 "Read the tracee's registers.  I<addr> specifies, in an "
7133 "architecture-dependent way, the type of registers to be read.  "
7134 "B<NT_PRSTATUS> (with numerical value 1)  usually results in reading of "
7135 "general-purpose registers.  If the CPU has, for example, floating-point "
7136 "and/or vector registers, they can be retrieved by setting I<addr> to the "
7137 "corresponding B<NT_foo> constant.  I<data> points to a B<struct iovec>, "
7138 "which describes the destination buffer's location and length.  On return, "
7139 "the kernel modifies B<iov.len> to indicate the actual number of bytes "
7140 "returned."
7141 msgstr ""
7142
7143 #. type: TP
7144 #: build/C/man2/ptrace.2:257
7145 #, no-wrap
7146 msgid "B<PTRACE_SETREGS>, B<PTRACE_SETFPREGS>"
7147 msgstr ""
7148
7149 #.  FIXME In the preceding sentence, which modifications are disallowed,
7150 #.  and when they are disallowed, how does user space discover that fact?
7151 #. type: Plain text
7152 #: build/C/man2/ptrace.2:282
7153 msgid ""
7154 "Modify the tracee's general-purpose or floating-point registers, "
7155 "respectively, from the address I<data> in the tracer.  As for "
7156 "B<PTRACE_POKEUSER>, some general-purpose register modifications may be "
7157 "disallowed.  (I<addr> is ignored.)  Note that SPARC systems have the meaning "
7158 "of I<data> and I<addr> reversed; that is, I<data> is ignored and the "
7159 "registers are copied from the address I<addr>.  B<PTRACE_SETREGS> and "
7160 "B<PTRACE_SETFPREGS> are not present on all architectures."
7161 msgstr ""
7162
7163 #. type: TP
7164 #: build/C/man2/ptrace.2:282
7165 #, no-wrap
7166 msgid "B<PTRACE_SETREGSET> (since Linux 2.6.34)"
7167 msgstr ""
7168
7169 #. type: Plain text
7170 #: build/C/man2/ptrace.2:291
7171 msgid ""
7172 "Modify the tracee's registers.  The meaning of I<addr> and I<data> is "
7173 "analogous to B<PTRACE_GETREGSET>."
7174 msgstr ""
7175
7176 #. type: TP
7177 #: build/C/man2/ptrace.2:291
7178 #, no-wrap
7179 msgid "B<PTRACE_GETSIGINFO> (since Linux 2.3.99-pre6)"
7180 msgstr ""
7181
7182 #. type: Plain text
7183 #: build/C/man2/ptrace.2:303
7184 msgid ""
7185 "Retrieve information about the signal that caused the stop.  Copy a "
7186 "I<siginfo_t> structure (see B<sigaction>(2))  from the tracee to the address "
7187 "I<data> in the tracer.  (I<addr> is ignored.)"
7188 msgstr ""
7189
7190 #. type: TP
7191 #: build/C/man2/ptrace.2:303
7192 #, no-wrap
7193 msgid "B<PTRACE_SETSIGINFO> (since Linux 2.3.99-pre6)"
7194 msgstr ""
7195
7196 #. type: Plain text
7197 #: build/C/man2/ptrace.2:319
7198 msgid ""
7199 "Set signal information: copy a I<siginfo_t> structure from the address "
7200 "I<data> in the tracer to the tracee.  This will affect only signals that "
7201 "would normally be delivered to the tracee and were caught by the tracer.  It "
7202 "may be difficult to tell these normal signals from synthetic signals "
7203 "generated by B<ptrace>()  itself.  (I<addr> is ignored.)"
7204 msgstr ""
7205
7206 #. type: TP
7207 #: build/C/man2/ptrace.2:319
7208 #, no-wrap
7209 msgid "B<PTRACE_SETOPTIONS> (since Linux 2.4.6; see BUGS for caveats)"
7210 msgstr ""
7211
7212 #. type: Plain text
7213 #: build/C/man2/ptrace.2:328
7214 msgid ""
7215 "Set ptrace options from I<data>.  (I<addr> is ignored.)  I<data> is "
7216 "interpreted as a bit mask of options, which are specified by the following "
7217 "flags:"
7218 msgstr ""
7219
7220 #. type: TP
7221 #: build/C/man2/ptrace.2:329
7222 #, no-wrap
7223 msgid "B<PTRACE_O_EXITKILL> (since Linux 3.8)"
7224 msgstr ""
7225
7226 #.  commit 992fb6e170639b0849bace8e49bf31bd37c4123
7227 #. type: Plain text
7228 #: build/C/man2/ptrace.2:337
7229 msgid ""
7230 "If a tracer sets this flag, a B<SIGKILL> signal will be sent to every tracee "
7231 "if the tracer exits.  This option is useful for ptrace jailers that want to "
7232 "ensure that tracees can never escape the tracer's control."
7233 msgstr ""
7234
7235 #. type: TP
7236 #: build/C/man2/ptrace.2:337
7237 #, no-wrap
7238 msgid "B<PTRACE_O_TRACECLONE> (since Linux 2.5.46)"
7239 msgstr ""
7240
7241 #. type: Plain text
7242 #: build/C/man2/ptrace.2:354
7243 msgid ""
7244 "Stop the tracee at the next B<clone>(2)  and automatically start tracing the "
7245 "newly cloned process, which will start with a B<SIGSTOP>, or "
7246 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
7247 "tracer will return a I<status> value such that"
7248 msgstr ""
7249
7250 #. type: Plain text
7251 #: build/C/man2/ptrace.2:357
7252 #, no-wrap
7253 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_CLONEE<lt>E<lt>8))\n"
7254 msgstr ""
7255
7256 #. type: Plain text
7257 #: build/C/man2/ptrace.2:361 build/C/man2/ptrace.2:447 build/C/man2/ptrace.2:480
7258 msgid "The PID of the new process can be retrieved with B<PTRACE_GETEVENTMSG>."
7259 msgstr ""
7260
7261 #. type: Plain text
7262 #: build/C/man2/ptrace.2:382
7263 msgid ""
7264 "This option may not catch B<clone>(2)  calls in all cases.  If the tracee "
7265 "calls B<clone>(2)  with the B<CLONE_VFORK> flag, B<PTRACE_EVENT_VFORK> will "
7266 "be delivered instead if B<PTRACE_O_TRACEVFORK> is set; otherwise if the "
7267 "tracee calls B<clone>(2)  with the exit signal set to B<SIGCHLD>, "
7268 "B<PTRACE_EVENT_FORK> will be delivered if B<PTRACE_O_TRACEFORK> is set."
7269 msgstr ""
7270
7271 #. type: TP
7272 #: build/C/man2/ptrace.2:382
7273 #, no-wrap
7274 msgid "B<PTRACE_O_TRACEEXEC> (since Linux 2.5.46)"
7275 msgstr ""
7276
7277 #. type: Plain text
7278 #: build/C/man2/ptrace.2:391
7279 msgid ""
7280 "Stop the tracee at the next B<execve>(2).  A B<waitpid>(2)  by the tracer "
7281 "will return a I<status> value such that"
7282 msgstr ""
7283
7284 #. type: Plain text
7285 #: build/C/man2/ptrace.2:394
7286 #, no-wrap
7287 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXECE<lt>E<lt>8))\n"
7288 msgstr ""
7289
7290 #. type: Plain text
7291 #: build/C/man2/ptrace.2:400
7292 msgid ""
7293 "If the execing thread is not a thread group leader, the thread ID is reset "
7294 "to thread group leader's ID before this stop.  Since Linux 3.0, the former "
7295 "thread ID can be retrieved with B<PTRACE_GETEVENTMSG>."
7296 msgstr ""
7297
7298 #. type: TP
7299 #: build/C/man2/ptrace.2:400
7300 #, no-wrap
7301 msgid "B<PTRACE_O_TRACEEXIT> (since Linux 2.5.60)"
7302 msgstr ""
7303
7304 #. type: Plain text
7305 #: build/C/man2/ptrace.2:408
7306 msgid ""
7307 "Stop the tracee at exit.  A B<waitpid>(2)  by the tracer will return a "
7308 "I<status> value such that"
7309 msgstr ""
7310
7311 #. type: Plain text
7312 #: build/C/man2/ptrace.2:411
7313 #, no-wrap
7314 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_EXITE<lt>E<lt>8))\n"
7315 msgstr ""
7316
7317 #. type: Plain text
7318 #: build/C/man2/ptrace.2:415
7319 msgid "The tracee's exit status can be retrieved with B<PTRACE_GETEVENTMSG>."
7320 msgstr ""
7321
7322 #. type: Plain text
7323 #: build/C/man2/ptrace.2:423
7324 msgid ""
7325 "The tracee is stopped early during process exit, when registers are still "
7326 "available, allowing the tracer to see where the exit occurred, whereas the "
7327 "normal exit notification is done after the process is finished exiting.  "
7328 "Even though context is available, the tracer cannot prevent the exit from "
7329 "happening at this point."
7330 msgstr ""
7331
7332 #. type: TP
7333 #: build/C/man2/ptrace.2:423
7334 #, no-wrap
7335 msgid "B<PTRACE_O_TRACEFORK> (since Linux 2.5.46)"
7336 msgstr ""
7337
7338 #. type: Plain text
7339 #: build/C/man2/ptrace.2:440
7340 msgid ""
7341 "Stop the tracee at the next B<fork>(2)  and automatically start tracing the "
7342 "newly forked process, which will start with a B<SIGSTOP>, or "
7343 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
7344 "tracer will return a I<status> value such that"
7345 msgstr ""
7346
7347 #. type: Plain text
7348 #: build/C/man2/ptrace.2:443
7349 #, no-wrap
7350 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_FORKE<lt>E<lt>8))\n"
7351 msgstr ""
7352
7353 #. type: TP
7354 #: build/C/man2/ptrace.2:447
7355 #, no-wrap
7356 msgid "B<PTRACE_O_TRACESYSGOOD> (since Linux 2.4.6)"
7357 msgstr ""
7358
7359 #. type: Plain text
7360 #: build/C/man2/ptrace.2:456
7361 msgid ""
7362 "When delivering system call traps, set bit 7 in the signal number (i.e., "
7363 "deliver I<SIGTRAP|0x80>).  This makes it easy for the tracer to distinguish "
7364 "normal traps from those caused by a system call.  (B<PTRACE_O_TRACESYSGOOD> "
7365 "may not work on all architectures.)"
7366 msgstr ""
7367
7368 #. type: TP
7369 #: build/C/man2/ptrace.2:456
7370 #, no-wrap
7371 msgid "B<PTRACE_O_TRACEVFORK> (since Linux 2.5.46)"
7372 msgstr ""
7373
7374 #. type: Plain text
7375 #: build/C/man2/ptrace.2:473
7376 msgid ""
7377 "Stop the tracee at the next B<vfork>(2)  and automatically start tracing the "
7378 "newly vforked process, which will start with a B<SIGSTOP>, or "
7379 "B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used.  A B<waitpid>(2)  by the "
7380 "tracer will return a I<status> value such that"
7381 msgstr ""
7382
7383 #. type: Plain text
7384 #: build/C/man2/ptrace.2:476
7385 #, no-wrap
7386 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORKE<lt>E<lt>8))\n"
7387 msgstr ""
7388
7389 #. type: TP
7390 #: build/C/man2/ptrace.2:480
7391 #, no-wrap
7392 msgid "B<PTRACE_O_TRACEVFORKDONE> (since Linux 2.5.60)"
7393 msgstr ""
7394
7395 #. type: Plain text
7396 #: build/C/man2/ptrace.2:489
7397 msgid ""
7398 "Stop the tracee at the completion of the next B<vfork>(2).  A B<waitpid>(2)  "
7399 "by the tracer will return a I<status> value such that"
7400 msgstr ""
7401
7402 #. type: Plain text
7403 #: build/C/man2/ptrace.2:492
7404 #, no-wrap
7405 msgid "  statusE<gt>E<gt>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONEE<lt>E<lt>8))\n"
7406 msgstr ""
7407
7408 #. type: Plain text
7409 #: build/C/man2/ptrace.2:496
7410 msgid ""
7411 "The PID of the new process can (since Linux 2.6.18) be retrieved with "
7412 "B<PTRACE_GETEVENTMSG>."
7413 msgstr ""
7414
7415 #. type: TP
7416 #: build/C/man2/ptrace.2:497
7417 #, no-wrap
7418 msgid "B<PTRACE_GETEVENTMSG> (since Linux 2.5.46)"
7419 msgstr ""
7420
7421 #. type: Plain text
7422 #: build/C/man2/ptrace.2:517
7423 msgid ""
7424 "Retrieve a message (as an I<unsigned long>)  about the ptrace event that "
7425 "just happened, placing it at the address I<data> in the tracer.  For "
7426 "B<PTRACE_EVENT_EXIT>, this is the tracee's exit status.  For "
7427 "B<PTRACE_EVENT_FORK>, B<PTRACE_EVENT_VFORK>, B<PTRACE_EVENT_VFORK_DONE>, and "
7428 "B<PTRACE_EVENT_CLONE>, this is the PID of the new process.  (I<addr> is "
7429 "ignored.)"
7430 msgstr ""
7431
7432 #. type: TP
7433 #: build/C/man2/ptrace.2:517
7434 #, no-wrap
7435 msgid "B<PTRACE_CONT>"
7436 msgstr ""
7437
7438 #. type: Plain text
7439 #: build/C/man2/ptrace.2:529
7440 msgid ""
7441 "Restart the stopped tracee process.  If I<data> is nonzero, it is "
7442 "interpreted as the number of a signal to be delivered to the tracee; "
7443 "otherwise, no signal is delivered.  Thus, for example, the tracer can "
7444 "control whether a signal sent to the tracee is delivered or not.  (I<addr> "
7445 "is ignored.)"
7446 msgstr ""
7447
7448 #. type: TP
7449 #: build/C/man2/ptrace.2:529
7450 #, no-wrap
7451 msgid "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>"
7452 msgstr ""
7453
7454 #. type: Plain text
7455 #: build/C/man2/ptrace.2:553
7456 msgid ""
7457 "Restart the stopped tracee as for B<PTRACE_CONT>, but arrange for the tracee "
7458 "to be stopped at the next entry to or exit from a system call, or after "
7459 "execution of a single instruction, respectively.  (The tracee will also, as "
7460 "usual, be stopped upon receipt of a signal.)  From the tracer's perspective, "
7461 "the tracee will appear to have been stopped by receipt of a B<SIGTRAP>.  So, "
7462 "for B<PTRACE_SYSCALL>, for example, the idea is to inspect the arguments to "
7463 "the system call at the first stop, then do another B<PTRACE_SYSCALL> and "
7464 "inspect the return value of the system call at the second stop.  The I<data> "
7465 "argument is treated as for B<PTRACE_CONT>.  (I<addr> is ignored.)"
7466 msgstr ""
7467
7468 #. type: TP
7469 #: build/C/man2/ptrace.2:553
7470 #, no-wrap
7471 msgid "B<PTRACE_SYSEMU>, B<PTRACE_SYSEMU_SINGLESTEP> (since Linux 2.6.14)"
7472 msgstr ""
7473
7474 #.  As at 3.7
7475 #. type: Plain text
7476 #: build/C/man2/ptrace.2:574
7477 msgid ""
7478 "For B<PTRACE_SYSEMU>, continue and stop on entry to the next system call, "
7479 "which will not be executed.  For B<PTRACE_SYSEMU_SINGLESTEP>, do the same "
7480 "but also singlestep if not a system call.  This call is used by programs "
7481 "like User Mode Linux that want to emulate all the tracee's system calls.  "
7482 "The I<data> argument is treated as for B<PTRACE_CONT>.  The I<addr> argument "
7483 "is ignored.  These requests are currently supported only on x86."
7484 msgstr ""
7485
7486 #. type: TP
7487 #: build/C/man2/ptrace.2:574
7488 #, no-wrap
7489 msgid "B<PTRACE_LISTEN> (since Linux 3.4)"
7490 msgstr ""
7491
7492 #. type: Plain text
7493 #: build/C/man2/ptrace.2:585
7494 msgid ""
7495 "Restart the stopped tracee, but prevent it from executing.  The resulting "
7496 "state of the tracee is similar to a process which has been stopped by a "
7497 "B<SIGSTOP> (or other stopping signal).  See the \"group-stop\" subsection "
7498 "for additional information.  B<PTRACE_LISTEN> works only on tracees attached "
7499 "by B<PTRACE_SEIZE>."
7500 msgstr ""
7501
7502 #. type: TP
7503 #: build/C/man2/ptrace.2:585
7504 #, no-wrap
7505 msgid "B<PTRACE_KILL>"
7506 msgstr ""
7507
7508 #. type: Plain text
7509 #: build/C/man2/ptrace.2:594
7510 msgid ""
7511 "Send the tracee a B<SIGKILL> to terminate it.  (I<addr> and I<data> are "
7512 "ignored.)"
7513 msgstr ""
7514
7515 #.  [Note from Denys Vlasenko:
7516 #.      deprecation suggested by Oleg Nesterov. He prefers to deprecate it
7517 #.      instead of describing (and needing to support) PTRACE_KILL's quirks.]
7518 #. type: Plain text
7519 #: build/C/man2/ptrace.2:613
7520 msgid ""
7521 "I<This operation is deprecated; do not use it!> Instead, send a B<SIGKILL> "
7522 "directly using B<kill>(2)  or B<tgkill>(2).  The problem with B<PTRACE_KILL> "
7523 "is that it requires the tracee to be in signal-delivery-stop, otherwise it "
7524 "may not work (i.e., may complete successfully but won't kill the tracee).  "
7525 "By contrast, sending a B<SIGKILL> directly has no such limitation."
7526 msgstr ""
7527
7528 #. type: TP
7529 #: build/C/man2/ptrace.2:613
7530 #, no-wrap
7531 msgid "B<PTRACE_INTERRUPT> (since Linux 3.4)"
7532 msgstr ""
7533
7534 #. type: Plain text
7535 #: build/C/man2/ptrace.2:641
7536 msgid ""
7537 "Stop a tracee.  If the tracee is running or sleeping in kernel space and "
7538 "B<PTRACE_SYSCALL> is in effect, the system call is interrupted and "
7539 "syscall-exit-stop is reported.  (The interrupted system call is restarted "
7540 "when the tracee is restarted.)  If the tracee was already stopped by a "
7541 "signal and B<PTRACE_LISTEN> was sent to it, the tracee stops with "
7542 "B<PTRACE_EVENT_STOP> and I<WSTOPSIG(status)> returns the stop signal.  If "
7543 "any other ptrace-stop is generated at the same time (for example, if a "
7544 "signal is sent to the tracee), this ptrace-stop happens.  If none of the "
7545 "above applies (for example, if the tracee is running in userspace), it stops "
7546 "with B<PTRACE_EVENT_STOP> with I<WSTOPSIG(status)> == B<SIGTRAP>.  "
7547 "B<PTRACE_INTERRUPT> only works on tracees attached by B<PTRACE_SEIZE>."
7548 msgstr ""
7549
7550 #. type: TP
7551 #: build/C/man2/ptrace.2:641
7552 #, no-wrap
7553 msgid "B<PTRACE_ATTACH>"
7554 msgstr ""
7555
7556 #.  No longer true (removed by Denys Vlasenko, 2011, who remarks:
7557 #.         "I think it isn't true in non-ancient 2.4 and in 2.6/3.x.
7558 #.          Basically, it's not true for any Linux in practical use.
7559 #.  ; the behavior of the tracee is as if it had done a
7560 #.  .BR PTRACE_TRACEME .
7561 #.  The calling process actually becomes the parent of the tracee
7562 #.  process for most purposes (e.g., it will receive
7563 #.  notification of tracee events and appears in
7564 #.  .BR ps (1)
7565 #.  output as the tracee's parent), but a
7566 #.  .BR getppid (2)
7567 #.  by the tracee will still return the PID of the original parent.
7568 #. type: Plain text
7569 #: build/C/man2/ptrace.2:669
7570 msgid ""
7571 "Attach to the process specified in I<pid>, making it a tracee of the calling "
7572 "process.  The tracee is sent a B<SIGSTOP>, but will not necessarily have "
7573 "stopped by the completion of this call; use B<waitpid>(2)  to wait for the "
7574 "tracee to stop.  See the \"Attaching and detaching\" subsection for "
7575 "additional information.  (I<addr> and I<data> are ignored.)"
7576 msgstr ""
7577
7578 #. type: TP
7579 #: build/C/man2/ptrace.2:669
7580 #, no-wrap
7581 msgid "B<PTRACE_SEIZE> (since Linux 3.4)"
7582 msgstr ""
7583
7584 #. type: Plain text
7585 #: build/C/man2/ptrace.2:689
7586 msgid ""
7587 "Attach to the process specified in I<pid>, making it a tracee of the calling "
7588 "process.  Unlike B<PTRACE_ATTACH>, B<PTRACE_SEIZE> does not stop the "
7589 "process.  Only a B<PTRACE_SEIZE>d process can accept B<PTRACE_INTERRUPT> and "
7590 "B<PTRACE_LISTEN> commands.  I<addr> must be zero.  I<data> contains a bit "
7591 "mask of ptrace options to activate immediately."
7592 msgstr ""
7593
7594 #. type: TP
7595 #: build/C/man2/ptrace.2:689
7596 #, no-wrap
7597 msgid "B<PTRACE_DETACH>"
7598 msgstr ""
7599
7600 #. type: Plain text
7601 #: build/C/man2/ptrace.2:698
7602 msgid ""
7603 "Restart the stopped tracee as for B<PTRACE_CONT>, but first detach from it.  "
7604 "Under Linux, a tracee can be detached in this way regardless of which method "
7605 "was used to initiate tracing.  (I<addr> is ignored.)"
7606 msgstr ""
7607
7608 #. type: SS
7609 #: build/C/man2/ptrace.2:698
7610 #, no-wrap
7611 msgid "Death under ptrace"
7612 msgstr ""
7613
7614 #. type: Plain text
7615 #: build/C/man2/ptrace.2:707
7616 msgid ""
7617 "When a (possibly multithreaded) process receives a killing signal (one whose "
7618 "disposition is set to B<SIG_DFL> and whose default action is to kill the "
7619 "process), all threads exit.  Tracees report their death to their tracer(s).  "
7620 "Notification of this event is delivered via B<waitpid>(2)."
7621 msgstr ""
7622
7623 #. type: Plain text
7624 #: build/C/man2/ptrace.2:716
7625 msgid ""
7626 "Note that the killing signal will first cause signal-delivery-stop (on one "
7627 "tracee only), and only after it is injected by the tracer (or after it was "
7628 "dispatched to a thread which isn't traced), will death from the signal "
7629 "happen on I<all> tracees within a multithreaded process.  (The term "
7630 "\"signal-delivery-stop\" is explained below.)"
7631 msgstr ""
7632
7633 #. type: Plain text
7634 #: build/C/man2/ptrace.2:728
7635 msgid ""
7636 "B<SIGKILL> does not generate signal-delivery-stop and therefore the tracer "
7637 "can't suppress it.  B<SIGKILL> kills even within system calls "
7638 "(syscall-exit-stop is not generated prior to death by B<SIGKILL>).  The net "
7639 "effect is that B<SIGKILL> always kills the process (all its threads), even "
7640 "if some threads of the process are ptraced."
7641 msgstr ""
7642
7643 #. type: Plain text
7644 #: build/C/man2/ptrace.2:733
7645 msgid ""
7646 "When the tracee calls B<_exit>(2), it reports its death to its tracer.  "
7647 "Other threads are not affected."
7648 msgstr ""
7649
7650 #. type: Plain text
7651 #: build/C/man2/ptrace.2:737
7652 msgid ""
7653 "When any thread executes B<exit_group>(2), every tracee in its thread group "
7654 "reports its death to its tracer."
7655 msgstr ""
7656
7657 #. type: Plain text
7658 #: build/C/man2/ptrace.2:751
7659 msgid ""
7660 "If the B<PTRACE_O_TRACEEXIT> option is on, B<PTRACE_EVENT_EXIT> will happen "
7661 "before actual death.  This applies to exits via B<exit>(2), "
7662 "B<exit_group>(2), and signal deaths (except B<SIGKILL>), and when threads "
7663 "are torn down on B<execve>(2)  in a multithreaded process."
7664 msgstr ""
7665
7666 #. type: Plain text
7667 #: build/C/man2/ptrace.2:776
7668 msgid ""
7669 "The tracer cannot assume that the ptrace-stopped tracee exists.  There are "
7670 "many scenarios when the tracee may die while stopped (such as B<SIGKILL>).  "
7671 "Therefore, the tracer must be prepared to handle an B<ESRCH> error on any "
7672 "ptrace operation.  Unfortunately, the same error is returned if the tracee "
7673 "exists but is not ptrace-stopped (for commands which require a stopped "
7674 "tracee), or if it is not traced by the process which issued the ptrace "
7675 "call.  The tracer needs to keep track of the stopped/running state of the "
7676 "tracee, and interpret B<ESRCH> as \"tracee died unexpectedly\" only if it "
7677 "knows that the tracee has been observed to enter ptrace-stop.  Note that "
7678 "there is no guarantee that I<waitpid(WNOHANG)> will reliably report the "
7679 "tracee's death status if a ptrace operation returned B<ESRCH>.  "
7680 "I<waitpid(WNOHANG)> may return 0 instead.  In other words, the tracee may be "
7681 "\"not yet fully dead\", but already refusing ptrace requests."
7682 msgstr ""
7683
7684 #. type: Plain text
7685 #: build/C/man2/ptrace.2:790
7686 msgid ""
7687 "The tracer can't assume that the tracee I<always> ends its life by reporting "
7688 "I<WIFEXITED(status)> or I<WIFSIGNALED(status)>; there are cases where this "
7689 "does not occur.  For example, if a thread other than thread group leader "
7690 "does an B<execve>(2), it disappears; its PID will never be seen again, and "
7691 "any subsequent ptrace stops will be reported under the thread group leader's "
7692 "PID."
7693 msgstr ""
7694
7695 #. type: SS
7696 #: build/C/man2/ptrace.2:790
7697 #, no-wrap
7698 msgid "Stopped states"
7699 msgstr ""
7700
7701 #. type: Plain text
7702 #: build/C/man2/ptrace.2:812
7703 msgid ""
7704 "A tracee can be in two states: running or stopped.  For the purposes of "
7705 "ptrace, a tracee which is blocked in a system call (such as B<read>(2), "
7706 "B<pause>(2), etc.)  is nevertheless considered to be running, even if the "
7707 "tracee is blocked for a long time.  The state of the tracee after "
7708 "B<PTRACE_LISTEN> is somewhat of a gray area: it is not in any ptrace-stop "
7709 "(ptrace commands won't work on it, and it will deliver B<waitpid>(2)  "
7710 "notifications), but it also may be considered \"stopped\" because it is not "
7711 "executing instructions (is not scheduled), and if it was in group-stop "
7712 "before B<PTRACE_LISTEN>, it will not respond to signals until B<SIGCONT> is "
7713 "received."
7714 msgstr ""
7715
7716 #. type: Plain text
7717 #: build/C/man2/ptrace.2:816
7718 msgid ""
7719 "There are many kinds of states when the tracee is stopped, and in ptrace "
7720 "discussions they are often conflated.  Therefore, it is important to use "
7721 "precise terms."
7722 msgstr ""
7723
7724 #. type: Plain text
7725 #: build/C/man2/ptrace.2:827
7726 msgid ""
7727 "In this manual page, any stopped state in which the tracee is ready to "
7728 "accept ptrace commands from the tracer is called I<ptrace-stop>.  "
7729 "Ptrace-stops can be further subdivided into I<signal-delivery-stop>, "
7730 "I<group-stop>, I<syscall-stop>, and so on.  These stopped states are "
7731 "described in detail below."
7732 msgstr ""
7733
7734 #. type: Plain text
7735 #: build/C/man2/ptrace.2:832
7736 msgid ""
7737 "When the running tracee enters ptrace-stop, it notifies its tracer using "
7738 "B<waitpid>(2)  (or one of the other \"wait\" system calls).  Most of this "
7739 "manual page assumes that the tracer waits with:"
7740 msgstr ""
7741
7742 #. type: Plain text
7743 #: build/C/man2/ptrace.2:834
7744 #, no-wrap
7745 msgid "    pid = waitpid(pid_or_minus_1, &status, __WALL);\n"
7746 msgstr ""
7747
7748 #.  Denys Vlasenko:
7749 #.      Do we require __WALL usage, or will just using 0 be ok? (With 0,
7750 #.      I am not 100% sure there aren't ugly corner cases.) Are the
7751 #.      rules different if user wants to use waitid? Will waitid require
7752 #.      WEXITED?
7753 #. type: Plain text
7754 #: build/C/man2/ptrace.2:846
7755 msgid ""
7756 "Ptrace-stopped tracees are reported as returns with I<pid> greater than 0 "
7757 "and I<WIFSTOPPED(status)> true."
7758 msgstr ""
7759
7760 #. type: Plain text
7761 #: build/C/man2/ptrace.2:854
7762 msgid ""
7763 "The B<__WALL> flag does not include the B<WSTOPPED> and B<WEXITED> flags, "
7764 "but implies their functionality."
7765 msgstr ""
7766
7767 #. type: Plain text
7768 #: build/C/man2/ptrace.2:861
7769 msgid ""
7770 "Setting the B<WCONTINUED> flag when calling B<waitpid>(2)  is not "
7771 "recommended: the \"continued\" state is per-process and consuming it can "
7772 "confuse the real parent of the tracee."
7773 msgstr ""
7774
7775 #. type: Plain text
7776 #: build/C/man2/ptrace.2:869
7777 msgid ""
7778 "Use of the B<WNOHANG> flag may cause B<waitpid>(2)  to return 0 (\"no wait "
7779 "results available yet\")  even if the tracer knows there should be a "
7780 "notification.  Example:"
7781 msgstr ""
7782
7783 #. type: Plain text
7784 #: build/C/man2/ptrace.2:878
7785 #, no-wrap
7786 msgid ""
7787 "    errno = 0;\n"
7788 "    ptrace(PTRACE_CONT, pid, 0L, 0L);\n"
7789 "    if (errno == ESRCH) {\n"
7790 "        /* tracee is dead */\n"
7791 "        r = waitpid(tracee, &status, __WALL | WNOHANG);\n"
7792 "        /* r can still be 0 here! */\n"
7793 "    }\n"
7794 msgstr ""
7795
7796 #. type: Plain text
7797 #: build/C/man2/ptrace.2:901
7798 msgid ""
7799 "The following kinds of ptrace-stops exist: signal-delivery-stops, "
7800 "group-stops, B<PTRACE_EVENT> stops, syscall-stops.  They all are reported by "
7801 "B<waitpid>(2)  with I<WIFSTOPPED(status)> true.  They may be differentiated "
7802 "by examining the value I<statusE<gt>E<gt>8>, and if there is ambiguity in "
7803 "that value, by querying B<PTRACE_GETSIGINFO>.  (Note: the "
7804 "I<WSTOPSIG(status)> macro can't be used to perform this examination, because "
7805 "it returns the value I<(statusE<gt>E<gt>8)\\ &\\ 0xff>.)"
7806 msgstr ""
7807
7808 #. type: SS
7809 #: build/C/man2/ptrace.2:901
7810 #, no-wrap
7811 msgid "Signal-delivery-stop"
7812 msgstr ""
7813
7814 #. type: Plain text
7815 #: build/C/man2/ptrace.2:921
7816 msgid ""
7817 "When a (possibly multithreaded) process receives any signal except "
7818 "B<SIGKILL>, the kernel selects an arbitrary thread which handles the "
7819 "signal.  (If the signal is generated with B<tgkill>(2), the target thread "
7820 "can be explicitly selected by the caller.)  If the selected thread is "
7821 "traced, it enters signal-delivery-stop.  At this point, the signal is not "
7822 "yet delivered to the process, and can be suppressed by the tracer.  If the "
7823 "tracer doesn't suppress the signal, it passes the signal to the tracee in "
7824 "the next ptrace restart request.  This second step of signal delivery is "
7825 "called I<signal injection> in this manual page.  Note that if the signal is "
7826 "blocked, signal-delivery-stop doesn't happen until the signal is unblocked, "
7827 "with the usual exception that B<SIGSTOP> can't be blocked."
7828 msgstr ""
7829
7830 #. type: Plain text
7831 #: build/C/man2/ptrace.2:935
7832 msgid ""
7833 "Signal-delivery-stop is observed by the tracer as B<waitpid>(2)  returning "
7834 "with I<WIFSTOPPED(status)> true, with the signal returned by "
7835 "I<WSTOPSIG(status)>.  If the signal is B<SIGTRAP>, this may be a different "
7836 "kind of ptrace-stop; see the \"Syscall-stops\" and \"execve\" sections below "
7837 "for details.  If I<WSTOPSIG(status)> returns a stopping signal, this may be "
7838 "a group-stop; see below."
7839 msgstr ""
7840
7841 #. type: SS
7842 #: build/C/man2/ptrace.2:935
7843 #, no-wrap
7844 msgid "Signal injection and suppression"
7845 msgstr ""
7846
7847 #. type: Plain text
7848 #: build/C/man2/ptrace.2:938
7849 msgid ""
7850 "After signal-delivery-stop is observed by the tracer, the tracer should "
7851 "restart the tracee with the call"
7852 msgstr ""
7853
7854 #. type: Plain text
7855 #: build/C/man2/ptrace.2:940
7856 #, no-wrap
7857 msgid "    ptrace(PTRACE_restart, pid, 0, sig)\n"
7858 msgstr ""
7859
7860 #. type: Plain text
7861 #: build/C/man2/ptrace.2:953
7862 msgid ""
7863 "where B<PTRACE_restart> is one of the restarting ptrace requests.  If I<sig> "
7864 "is 0, then a signal is not delivered.  Otherwise, the signal I<sig> is "
7865 "delivered.  This operation is called I<signal injection> in this manual "
7866 "page, to distinguish it from signal-delivery-stop."
7867 msgstr ""
7868
7869 #. type: Plain text
7870 #: build/C/man2/ptrace.2:959
7871 msgid ""
7872 "The I<sig> value may be different from the I<WSTOPSIG(status)> value: the "
7873 "tracer can cause a different signal to be injected."
7874 msgstr ""
7875
7876 #. type: Plain text
7877 #: build/C/man2/ptrace.2:975
7878 msgid ""
7879 "Note that a suppressed signal still causes system calls to return "
7880 "prematurely.  In this case system calls will be restarted: the tracer will "
7881 "observe the tracee to reexecute the interrupted system call (or "
7882 "B<restart_syscall>(2)  system call for a few syscalls which use a different "
7883 "mechanism for restarting) if the tracer uses B<PTRACE_SYSCALL>.  Even system "
7884 "calls (such as B<poll>(2))  which are not restartable after signal are "
7885 "restarted after signal is suppressed; however, kernel bugs exist which cause "
7886 "some syscalls to fail with B<EINTR> even though no observable signal is "
7887 "injected to the tracee."
7888 msgstr ""
7889
7890 #. type: Plain text
7891 #: build/C/man2/ptrace.2:986
7892 msgid ""
7893 "Restarting ptrace commands issued in ptrace-stops other than "
7894 "signal-delivery-stop are not guaranteed to inject a signal, even if I<sig> "
7895 "is nonzero.  No error is reported; a nonzero I<sig> may simply be ignored.  "
7896 "Ptrace users should not try to \"create a new signal\" this way: use "
7897 "B<tgkill>(2)  instead."
7898 msgstr ""
7899
7900 #. type: Plain text
7901 #: build/C/man2/ptrace.2:993
7902 msgid ""
7903 "The fact that signal injection requests may be ignored when restarting the "
7904 "tracee after ptrace stops that are not signal-delivery-stops is a cause of "
7905 "confusion among ptrace users.  One typical scenario is that the tracer "
7906 "observes group-stop, mistakes it for signal-delivery-stop, restarts the "
7907 "tracee with"
7908 msgstr ""
7909
7910 #. type: Plain text
7911 #: build/C/man2/ptrace.2:995
7912 #, no-wrap
7913 msgid "    ptrace(PTRACE_restart, pid, 0, stopsig)\n"
7914 msgstr ""
7915
7916 #. type: Plain text
7917 #: build/C/man2/ptrace.2:1001
7918 msgid ""
7919 "with the intention of injecting I<stopsig>, but I<stopsig> gets ignored and "
7920 "the tracee continues to run."
7921 msgstr ""
7922
7923 #. type: Plain text
7924 #: build/C/man2/ptrace.2:1021
7925 msgid ""
7926 "The B<SIGCONT> signal has a side effect of waking up (all threads of)  a "
7927 "group-stopped process.  This side effect happens before "
7928 "signal-delivery-stop.  The tracer can't suppress this side effect (it can "
7929 "only suppress signal injection, which only causes the B<SIGCONT> handler to "
7930 "not be executed in the tracee, if such a handler is installed).  In fact, "
7931 "waking up from group-stop may be followed by signal-delivery-stop for "
7932 "signal(s)  I<other than> B<SIGCONT>, if they were pending when B<SIGCONT> "
7933 "was delivered.  In other words, B<SIGCONT> may be not the first signal "
7934 "observed by the tracee after it was sent."
7935 msgstr ""
7936
7937 #. type: Plain text
7938 #: build/C/man2/ptrace.2:1025
7939 msgid ""
7940 "Stopping signals cause (all threads of) a process to enter group-stop.  This "
7941 "side effect happens after signal injection, and therefore can be suppressed "
7942 "by the tracer."
7943 msgstr ""
7944
7945 #.  In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(),
7946 #.  there is:
7947 #
7948 #.              /* The debugger continued.  Ignore SIGSTOP.  */
7949 #.              if (signr == SIGSTOP)
7950 #.                      continue;
7951 #. type: Plain text
7952 #: build/C/man2/ptrace.2:1035
7953 msgid "In Linux 2.4 and earlier, the B<SIGSTOP> signal can't be injected."
7954 msgstr ""
7955
7956 #. type: Plain text
7957 #: build/C/man2/ptrace.2:1052
7958 msgid ""
7959 "B<PTRACE_GETSIGINFO> can be used to retrieve a I<siginfo_t> structure which "
7960 "corresponds to the delivered signal.  B<PTRACE_SETSIGINFO> may be used to "
7961 "modify it.  If B<PTRACE_SETSIGINFO> has been used to alter I<siginfo_t>, the "
7962 "I<si_signo> field and the I<sig> parameter in the restarting command must "
7963 "match, otherwise the result is undefined."
7964 msgstr ""
7965
7966 #. type: SS
7967 #: build/C/man2/ptrace.2:1052
7968 #, no-wrap
7969 msgid "Group-stop"
7970 msgstr ""
7971
7972 #. type: Plain text
7973 #: build/C/man2/ptrace.2:1064
7974 msgid ""
7975 "When a (possibly multithreaded) process receives a stopping signal, all "
7976 "threads stop.  If some threads are traced, they enter a group-stop.  Note "
7977 "that the stopping signal will first cause signal-delivery-stop (on one "
7978 "tracee only), and only after it is injected by the tracer (or after it was "
7979 "dispatched to a thread which isn't traced), will group-stop be initiated on "
7980 "I<all> tracees within the multithreaded process.  As usual, every tracee "
7981 "reports its group-stop separately to the corresponding tracer."
7982 msgstr ""
7983
7984 #. type: Plain text
7985 #: build/C/man2/ptrace.2:1073
7986 msgid ""
7987 "Group-stop is observed by the tracer as B<waitpid>(2)  returning with "
7988 "I<WIFSTOPPED(status)> true, with the stopping signal available via "
7989 "I<WSTOPSIG(status)>.  The same result is returned by some other classes of "
7990 "ptrace-stops, therefore the recommended practice is to perform the call"
7991 msgstr ""
7992
7993 #. type: Plain text
7994 #: build/C/man2/ptrace.2:1075
7995 #, no-wrap
7996 msgid "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)\n"
7997 msgstr ""
7998
7999 #. type: Plain text
8000 #: build/C/man2/ptrace.2:1096
8001 msgid ""
8002 "The call can be avoided if the signal is not B<SIGSTOP>, B<SIGTSTP>, "
8003 "B<SIGTTIN>, or B<SIGTTOU>; only these four signals are stopping signals.  If "
8004 "the tracer sees something else, it can't be a group-stop.  Otherwise, the "
8005 "tracer needs to call B<PTRACE_GETSIGINFO>.  If B<PTRACE_GETSIGINFO> fails "
8006 "with B<EINVAL>, then it is definitely a group-stop.  (Other failure codes "
8007 "are possible, such as B<ESRCH> (\"no such process\") if a B<SIGKILL> killed "
8008 "the tracee.)"
8009 msgstr ""
8010
8011 #. type: Plain text
8012 #: build/C/man2/ptrace.2:1106
8013 msgid ""
8014 "If tracee was attached using B<PTRACE_SEIZE>, group-stop is indicated by "
8015 "B<PTRACE_EVENT_STOP>: I<statusE<gt>E<gt>16 == PTRACE_EVENT_STOP>.  This "
8016 "allows detection of group-stops without requiring an extra "
8017 "B<PTRACE_GETSIGINFO> call."
8018 msgstr ""
8019
8020 #. type: Plain text
8021 #: build/C/man2/ptrace.2:1115
8022 msgid ""
8023 "As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until "
8024 "it restarts or kills it, the tracee will not run, and will not send "
8025 "notifications (except B<SIGKILL> death) to the tracer, even if the tracer "
8026 "enters into another B<waitpid>(2)  call."
8027 msgstr ""
8028
8029 #. type: Plain text
8030 #: build/C/man2/ptrace.2:1129
8031 msgid ""
8032 "The kernel behavior described in the previous paragraph causes a problem "
8033 "with transparent handling of stopping signals.  If the tracer restarts the "
8034 "tracee after group-stop, the stopping signal is effectively ignored\\(emthe "
8035 "tracee doesn't remain stopped, it runs.  If the tracer doesn't restart the "
8036 "tracee before entering into the next B<waitpid>(2), future B<SIGCONT> "
8037 "signals will not be reported to the tracer; this would cause the B<SIGCONT> "
8038 "signals to have no effect on the tracee."
8039 msgstr ""
8040
8041 #. type: Plain text
8042 #: build/C/man2/ptrace.2:1140
8043 msgid ""
8044 "Since Linux 3.4, there is a method to overcome this problem: instead of "
8045 "B<PTRACE_CONT>, a B<PTRACE_LISTEN> command can be used to restart a tracee "
8046 "in a way where it does not execute, but waits for a new event which it can "
8047 "report via B<waitpid>(2)  (such as when it is restarted by a B<SIGCONT>)."
8048 msgstr ""
8049
8050 #. type: SS
8051 #: build/C/man2/ptrace.2:1140
8052 #, no-wrap
8053 msgid "PTRACE_EVENT stops"
8054 msgstr ""
8055
8056 #. type: Plain text
8057 #: build/C/man2/ptrace.2:1146
8058 msgid ""
8059 "If the tracer sets B<PTRACE_O_TRACE_*> options, the tracee will enter "
8060 "ptrace-stops called B<PTRACE_EVENT> stops."
8061 msgstr ""
8062
8063 #. type: Plain text
8064 #: build/C/man2/ptrace.2:1160
8065 msgid ""
8066 "B<PTRACE_EVENT> stops are observed by the tracer as B<waitpid>(2)  returning "
8067 "with I<WIFSTOPPED(status)>, and I<WSTOPSIG(status)> returns B<SIGTRAP>.  An "
8068 "additional bit is set in the higher byte of the status word: the value "
8069 "I<statusE<gt>E<gt>8> will be"
8070 msgstr ""
8071
8072 #. type: Plain text
8073 #: build/C/man2/ptrace.2:1162
8074 #, no-wrap
8075 msgid "    (SIGTRAP | PTRACE_EVENT_foo E<lt>E<lt> 8).\n"
8076 msgstr ""
8077
8078 #. type: Plain text
8079 #: build/C/man2/ptrace.2:1164
8080 msgid "The following events exist:"
8081 msgstr ""
8082
8083 #. type: TP
8084 #: build/C/man2/ptrace.2:1164
8085 #, no-wrap
8086 msgid "B<PTRACE_EVENT_VFORK>"
8087 msgstr ""
8088
8089 #. type: Plain text
8090 #: build/C/man2/ptrace.2:1177
8091 msgid ""
8092 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8093 "flag.  When the tracee is continued after this stop, it will wait for child "
8094 "to exit/exec before continuing its execution (in other words, the usual "
8095 "behavior on B<vfork>(2))."
8096 msgstr ""
8097
8098 #. type: TP
8099 #: build/C/man2/ptrace.2:1177
8100 #, no-wrap
8101 msgid "B<PTRACE_EVENT_FORK>"
8102 msgstr ""
8103
8104 #. type: Plain text
8105 #: build/C/man2/ptrace.2:1185
8106 msgid ""
8107 "Stop before return from B<fork>(2)  or B<clone>(2)  with the exit signal set "
8108 "to B<SIGCHLD>."
8109 msgstr ""
8110
8111 #. type: TP
8112 #: build/C/man2/ptrace.2:1185
8113 #, no-wrap
8114 msgid "B<PTRACE_EVENT_CLONE>"
8115 msgstr ""
8116
8117 #. type: Plain text
8118 #: build/C/man2/ptrace.2:1189
8119 msgid "Stop before return from B<clone>(2)."
8120 msgstr ""
8121
8122 #. type: TP
8123 #: build/C/man2/ptrace.2:1189
8124 #, no-wrap
8125 msgid "B<PTRACE_EVENT_VFORK_DONE>"
8126 msgstr ""
8127
8128 #. type: Plain text
8129 #: build/C/man2/ptrace.2:1199
8130 msgid ""
8131 "Stop before return from B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> "
8132 "flag, but after the child unblocked this tracee by exiting or execing."
8133 msgstr ""
8134
8135 #. type: Plain text
8136 #: build/C/man2/ptrace.2:1205
8137 msgid ""
8138 "For all four stops described above, the stop occurs in the parent (i.e., the "
8139 "tracee), not in the newly created thread.  B<PTRACE_GETEVENTMSG> can be used "
8140 "to retrieve the new thread's ID."
8141 msgstr ""
8142
8143 #. type: TP
8144 #: build/C/man2/ptrace.2:1205
8145 #, no-wrap
8146 msgid "B<PTRACE_EVENT_EXEC>"
8147 msgstr ""
8148
8149 #. type: Plain text
8150 #: build/C/man2/ptrace.2:1212
8151 msgid ""
8152 "Stop before return from B<execve>(2).  Since Linux 3.0, "
8153 "B<PTRACE_GETEVENTMSG> returns the former thread ID."
8154 msgstr ""
8155
8156 #. type: TP
8157 #: build/C/man2/ptrace.2:1212
8158 #, no-wrap
8159 msgid "B<PTRACE_EVENT_EXIT>"
8160 msgstr ""
8161
8162 #. type: Plain text
8163 #: build/C/man2/ptrace.2:1228
8164 msgid ""
8165 "Stop before exit (including death from B<exit_group>(2)), signal death, or "
8166 "exit caused by B<execve>(2)  in a multithreaded process.  "
8167 "B<PTRACE_GETEVENTMSG> returns the exit status.  Registers can be examined "
8168 "(unlike when \"real\" exit happens).  The tracee is still alive; it needs to "
8169 "be B<PTRACE_CONT>ed or B<PTRACE_DETACH>ed to finish exiting."
8170 msgstr ""
8171
8172 #. type: TP
8173 #: build/C/man2/ptrace.2:1228
8174 #, no-wrap
8175 msgid "B<PTRACE_EVENT_STOP>"
8176 msgstr ""
8177
8178 #. type: Plain text
8179 #: build/C/man2/ptrace.2:1240
8180 msgid ""
8181 "Stop induced by B<PTRACE_INTERRUPT> command, or group-stop, or initial "
8182 "ptrace-stop when a new child is attached (only if attached using "
8183 "B<PTRACE_SEIZE>), or B<PTRACE_EVENT_STOP> if B<PTRACE_SEIZE> was used."
8184 msgstr ""
8185
8186 #. type: Plain text
8187 #: build/C/man2/ptrace.2:1252
8188 msgid ""
8189 "B<PTRACE_GETSIGINFO> on B<PTRACE_EVENT> stops returns B<SIGTRAP> in "
8190 "I<si_signo>, with I<si_code> set to I<(eventE<lt>E<lt>8)\\ |\\ SIGTRAP>."
8191 msgstr ""
8192
8193 #. type: SS
8194 #: build/C/man2/ptrace.2:1252
8195 #, no-wrap
8196 msgid "Syscall-stops"
8197 msgstr ""
8198
8199 #. type: Plain text
8200 #: build/C/man2/ptrace.2:1265
8201 msgid ""
8202 "If the tracee was restarted by B<PTRACE_SYSCALL>, the tracee enters "
8203 "syscall-enter-stop just prior to entering any system call.  If the tracer "
8204 "restarts the tracee with B<PTRACE_SYSCALL>, the tracee enters "
8205 "syscall-exit-stop when the system call is finished, or if it is interrupted "
8206 "by a signal.  (That is, signal-delivery-stop never happens between "
8207 "syscall-enter-stop and syscall-exit-stop; it happens I<after> "
8208 "syscall-exit-stop.)"
8209 msgstr ""
8210
8211 #. type: Plain text
8212 #: build/C/man2/ptrace.2:1279
8213 msgid ""
8214 "Other possibilities are that the tracee may stop in a B<PTRACE_EVENT> stop, "
8215 "exit (if it entered B<_exit>(2)  or B<exit_group>(2)), be killed by "
8216 "B<SIGKILL>, or die silently (if it is a thread group leader, the "
8217 "B<execve>(2)  happened in another thread, and that thread is not traced by "
8218 "the same tracer; this situation is discussed later)."
8219 msgstr ""
8220
8221 #. type: Plain text
8222 #: build/C/man2/ptrace.2:1294
8223 msgid ""
8224 "Syscall-enter-stop and syscall-exit-stop are observed by the tracer as "
8225 "B<waitpid>(2)  returning with I<WIFSTOPPED(status)> true, and "
8226 "I<WSTOPSIG(status)> giving B<SIGTRAP>.  If the B<PTRACE_O_TRACESYSGOOD> "
8227 "option was set by the tracer, then I<WSTOPSIG(status)> will give the value "
8228 "I<(SIGTRAP\\ |\\ 0x80)>."
8229 msgstr ""
8230
8231 #. type: Plain text
8232 #: build/C/man2/ptrace.2:1300
8233 msgid ""
8234 "Syscall-stops can be distinguished from signal-delivery-stop with B<SIGTRAP> "
8235 "by querying B<PTRACE_GETSIGINFO> for the following cases:"
8236 msgstr ""
8237
8238 #. type: TP
8239 #: build/C/man2/ptrace.2:1300
8240 #, no-wrap
8241 msgid "I<si_code> E<lt>= 0"
8242 msgstr ""
8243
8244 #. type: Plain text
8245 #: build/C/man2/ptrace.2:1312
8246 msgid ""
8247 "B<SIGTRAP> was delivered as a result of a user-space action, for example, a "
8248 "system call (B<tgkill>(2), B<kill>(2), B<sigqueue>(3), etc.), expiration of "
8249 "a POSIX timer, change of state on a POSIX message queue, or completion of an "
8250 "asynchronous I/O request."
8251 msgstr ""
8252
8253 #. type: TP
8254 #: build/C/man2/ptrace.2:1312
8255 #, no-wrap
8256 msgid "I<si_code> == SI_KERNEL (0x80)"
8257 msgstr ""
8258
8259 #. type: Plain text
8260 #: build/C/man2/ptrace.2:1316
8261 msgid "B<SIGTRAP> was sent by the kernel."
8262 msgstr ""
8263
8264 #. type: TP
8265 #: build/C/man2/ptrace.2:1316
8266 #, no-wrap
8267 msgid "I<si_code> == SIGTRAP or I<si_code> == (SIGTRAP|0x80)"
8268 msgstr ""
8269
8270 #. type: Plain text
8271 #: build/C/man2/ptrace.2:1319
8272 msgid "This is a syscall-stop."
8273 msgstr ""
8274
8275 #. type: Plain text
8276 #: build/C/man2/ptrace.2:1324
8277 msgid ""
8278 "However, syscall-stops happen very often (twice per system call), and "
8279 "performing B<PTRACE_GETSIGINFO> for every syscall-stop may be somewhat "
8280 "expensive."
8281 msgstr ""
8282
8283 #. type: Plain text
8284 #: build/C/man2/ptrace.2:1347
8285 msgid ""
8286 "Some architectures allow the cases to be distinguished by examining "
8287 "registers.  For example, on x86, I<rax> == -B<ENOSYS> in "
8288 "syscall-enter-stop.  Since B<SIGTRAP> (like any other signal) always happens "
8289 "I<after> syscall-exit-stop, and at this point I<rax> almost never contains "
8290 "-B<ENOSYS>, the B<SIGTRAP> looks like \"syscall-stop which is not "
8291 "syscall-enter-stop\"; in other words, it looks like a \"stray "
8292 "syscall-exit-stop\" and can be detected this way.  But such detection is "
8293 "fragile and is best avoided."
8294 msgstr ""
8295
8296 #. type: Plain text
8297 #: build/C/man2/ptrace.2:1353
8298 msgid ""
8299 "Using the B<PTRACE_O_TRACESYSGOOD> option is the recommended method to "
8300 "distinguish syscall-stops from other kinds of ptrace-stops, since it is "
8301 "reliable and does not incur a performance penalty."
8302 msgstr ""
8303
8304 #. type: Plain text
8305 #: build/C/man2/ptrace.2:1364
8306 msgid ""
8307 "Syscall-enter-stop and syscall-exit-stop are indistinguishable from each "
8308 "other by the tracer.  The tracer needs to keep track of the sequence of "
8309 "ptrace-stops in order to not misinterpret syscall-enter-stop as "
8310 "syscall-exit-stop or vice versa.  The rule is that syscall-enter-stop is "
8311 "always followed by syscall-exit-stop, B<PTRACE_EVENT> stop or the tracee's "
8312 "death; no other kinds of ptrace-stop can occur in between."
8313 msgstr ""
8314
8315 #. type: Plain text
8316 #: build/C/man2/ptrace.2:1369
8317 msgid ""
8318 "If after syscall-enter-stop, the tracer uses a restarting command other than "
8319 "B<PTRACE_SYSCALL>, syscall-exit-stop is not generated."
8320 msgstr ""
8321
8322 #. type: Plain text
8323 #: build/C/man2/ptrace.2:1381
8324 msgid ""
8325 "B<PTRACE_GETSIGINFO> on syscall-stops returns B<SIGTRAP> in I<si_signo>, "
8326 "with I<si_code> set to B<SIGTRAP> or I<(SIGTRAP|0x80)>."
8327 msgstr ""
8328
8329 #. type: SS
8330 #: build/C/man2/ptrace.2:1381
8331 #, no-wrap
8332 msgid "PTRACE_SINGLESTEP, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP stops"
8333 msgstr ""
8334
8335 #
8336 #.  FIXME
8337 #.  document stops occurring with PTRACE_SINGLESTEP, PTRACE_SYSEMU,
8338 #.  PTRACE_SYSEMU_SINGLESTEP
8339 #. type: Plain text
8340 #: build/C/man2/ptrace.2:1387
8341 msgid "[Details of these kinds of stops are yet to be documented.]"
8342 msgstr ""
8343
8344 #. type: SS
8345 #: build/C/man2/ptrace.2:1387
8346 #, no-wrap
8347 msgid "Informational and restarting ptrace commands"
8348 msgstr ""
8349
8350 #. type: Plain text
8351 #: build/C/man2/ptrace.2:1397
8352 msgid ""
8353 "Most ptrace commands (all except B<PTRACE_ATTACH>, B<PTRACE_SEIZE>, "
8354 "B<PTRACE_TRACEME>, B<PTRACE_INTERRUPT>, and B<PTRACE_KILL>)  require the "
8355 "tracee to be in a ptrace-stop, otherwise they fail with B<ESRCH>."
8356 msgstr ""
8357
8358 #. type: Plain text
8359 #: build/C/man2/ptrace.2:1402
8360 msgid ""
8361 "When the tracee is in ptrace-stop, the tracer can read and write data to the "
8362 "tracee using informational commands.  These commands leave the tracee in "
8363 "ptrace-stopped state:"
8364 msgstr ""
8365
8366 #. type: Plain text
8367 #: build/C/man2/ptrace.2:1414
8368 #, no-wrap
8369 msgid ""
8370 "    ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);\n"
8371 "    ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val);\n"
8372 "    ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct);\n"
8373 "    ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct);\n"
8374 "    ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov);\n"
8375 "    ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov);\n"
8376 "    ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo);\n"
8377 "    ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo);\n"
8378 "    ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var);\n"
8379 "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
8380 msgstr ""
8381
8382 #. type: Plain text
8383 #: build/C/man2/ptrace.2:1426
8384 msgid ""
8385 "Note that some errors are not reported.  For example, setting signal "
8386 "information (I<siginfo>)  may have no effect in some ptrace-stops, yet the "
8387 "call may succeed (return 0 and not set I<errno>); querying "
8388 "B<PTRACE_GETEVENTMSG> may succeed and return some random value if current "
8389 "ptrace-stop is not documented as returning a meaningful event message."
8390 msgstr ""
8391
8392 #. type: Plain text
8393 #: build/C/man2/ptrace.2:1428
8394 msgid "The call"
8395 msgstr ""
8396
8397 #. type: Plain text
8398 #: build/C/man2/ptrace.2:1430
8399 #, no-wrap
8400 msgid "    ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);\n"
8401 msgstr ""
8402
8403 #. type: Plain text
8404 #: build/C/man2/ptrace.2:1439
8405 msgid ""
8406 "affects one tracee.  The tracee's current flags are replaced.  Flags are "
8407 "inherited by new tracees created and \"auto-attached\" via active "
8408 "B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or B<PTRACE_O_TRACECLONE> "
8409 "options."
8410 msgstr ""
8411
8412 #. type: Plain text
8413 #: build/C/man2/ptrace.2:1442
8414 msgid ""
8415 "Another group of commands makes the ptrace-stopped tracee run.  They have "
8416 "the form:"
8417 msgstr ""
8418
8419 #. type: Plain text
8420 #: build/C/man2/ptrace.2:1444
8421 #, no-wrap
8422 msgid "    ptrace(cmd, pid, 0, sig);\n"
8423 msgstr ""
8424
8425 #. type: Plain text
8426 #: build/C/man2/ptrace.2:1465
8427 msgid ""
8428 "where I<cmd> is B<PTRACE_CONT>, B<PTRACE_LISTEN>, B<PTRACE_DETACH>, "
8429 "B<PTRACE_SYSCALL>, B<PTRACE_SINGLESTEP>, B<PTRACE_SYSEMU>, or "
8430 "B<PTRACE_SYSEMU_SINGLESTEP>.  If the tracee is in signal-delivery-stop, "
8431 "I<sig> is the signal to be injected (if it is nonzero).  Otherwise, I<sig> "
8432 "may be ignored.  (When restarting a tracee from a ptrace-stop other than "
8433 "signal-delivery-stop, recommended practice is to always pass 0 in I<sig>.)"
8434 msgstr ""
8435
8436 #. type: SS
8437 #: build/C/man2/ptrace.2:1465
8438 #, no-wrap
8439 msgid "Attaching and detaching"
8440 msgstr ""
8441
8442 #. type: Plain text
8443 #: build/C/man2/ptrace.2:1467
8444 msgid "A thread can be attached to the tracer using the call"
8445 msgstr ""
8446
8447 #. type: Plain text
8448 #: build/C/man2/ptrace.2:1469
8449 #, no-wrap
8450 msgid "    ptrace(PTRACE_ATTACH, pid, 0, 0);\n"
8451 msgstr ""
8452
8453 #. type: Plain text
8454 #: build/C/man2/ptrace.2:1471 build/C/man2/ptrace.2:1968
8455 msgid "or"
8456 msgstr ""
8457
8458 #. type: Plain text
8459 #: build/C/man2/ptrace.2:1473
8460 #, no-wrap
8461 msgid "    ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);\n"
8462 msgstr ""
8463
8464 #
8465 #.  FIXME: Describe how to attach to a thread which is already
8466 #.         group-stopped.
8467 #. type: Plain text
8468 #: build/C/man2/ptrace.2:1498
8469 msgid ""
8470 "B<PTRACE_ATTACH> sends B<SIGSTOP> to this thread.  If the tracer wants this "
8471 "B<SIGSTOP> to have no effect, it needs to suppress it.  Note that if other "
8472 "signals are concurrently sent to this thread during attach, the tracer may "
8473 "see the tracee enter signal-delivery-stop with other signal(s) first! The "
8474 "usual practice is to reinject these signals until B<SIGSTOP> is seen, then "
8475 "suppress B<SIGSTOP> injection.  The design bug here is that a ptrace attach "
8476 "and a concurrently delivered B<SIGSTOP> may race and the concurrent "
8477 "B<SIGSTOP> may be lost."
8478 msgstr ""
8479
8480 #. type: Plain text
8481 #: build/C/man2/ptrace.2:1505
8482 msgid ""
8483 "Since attaching sends B<SIGSTOP> and the tracer usually suppresses it, this "
8484 "may cause a stray B<EINTR> return from the currently executing system call "
8485 "in the tracee, as described in the \"Signal injection and suppression\" "
8486 "section."
8487 msgstr ""
8488
8489 #. type: Plain text
8490 #: build/C/man2/ptrace.2:1517
8491 msgid ""
8492 "Since Linux 3.4, B<PTRACE_SEIZE> can be used instead of B<PTRACE_ATTACH>.  "
8493 "B<PTRACE_SEIZE> does not stop the attached process.  If you need to stop it "
8494 "after attach (or at any other time) without sending it any signals, use "
8495 "B<PTRACE_INTERRUPT> command."
8496 msgstr ""
8497
8498 #. type: Plain text
8499 #: build/C/man2/ptrace.2:1519
8500 msgid "The request"
8501 msgstr ""
8502
8503 #. type: Plain text
8504 #: build/C/man2/ptrace.2:1521
8505 #, no-wrap
8506 msgid "    ptrace(PTRACE_TRACEME, 0, 0, 0);\n"
8507 msgstr ""
8508
8509 #. type: Plain text
8510 #: build/C/man2/ptrace.2:1527
8511 msgid ""
8512 "turns the calling thread into a tracee.  The thread continues to run "
8513 "(doesn't enter ptrace-stop).  A common practice is to follow the "
8514 "B<PTRACE_TRACEME> with"
8515 msgstr ""
8516
8517 #. type: Plain text
8518 #: build/C/man2/ptrace.2:1529
8519 #, no-wrap
8520 msgid "    raise(SIGSTOP);\n"
8521 msgstr ""
8522
8523 #. type: Plain text
8524 #: build/C/man2/ptrace.2:1532
8525 msgid ""
8526 "and allow the parent (which is our tracer now) to observe our "
8527 "signal-delivery-stop."
8528 msgstr ""
8529
8530 #. type: Plain text
8531 #: build/C/man2/ptrace.2:1556
8532 msgid ""
8533 "If the B<PTRACE_O_TRACEFORK>, B<PTRACE_O_TRACEVFORK>, or "
8534 "B<PTRACE_O_TRACECLONE> options are in effect, then children created by, "
8535 "respectively, B<vfork>(2)  or B<clone>(2)  with the B<CLONE_VFORK> flag, "
8536 "B<fork>(2)  or B<clone>(2)  with the exit signal set to B<SIGCHLD>, and "
8537 "other kinds of B<clone>(2), are automatically attached to the same tracer "
8538 "which traced their parent.  B<SIGSTOP> is delivered to the children, causing "
8539 "them to enter signal-delivery-stop after they exit the system call which "
8540 "created them."
8541 msgstr ""
8542
8543 #. type: Plain text
8544 #: build/C/man2/ptrace.2:1558
8545 msgid "Detaching of the tracee is performed by:"
8546 msgstr ""
8547
8548 #. type: Plain text
8549 #: build/C/man2/ptrace.2:1560
8550 #, no-wrap
8551 msgid "    ptrace(PTRACE_DETACH, pid, 0, sig);\n"
8552 msgstr ""
8553
8554 #. type: Plain text
8555 #: build/C/man2/ptrace.2:1568
8556 msgid ""
8557 "B<PTRACE_DETACH> is a restarting operation; therefore it requires the tracee "
8558 "to be in ptrace-stop.  If the tracee is in signal-delivery-stop, a signal "
8559 "can be injected.  Otherwise, the I<sig> parameter may be silently ignored."
8560 msgstr ""
8561
8562 #.  FIXME: Describe how to detach from a group-stopped tracee so that it
8563 #.         doesn't run, but continues to wait for SIGCONT.
8564 #. type: Plain text
8565 #: build/C/man2/ptrace.2:1592
8566 msgid ""
8567 "If the tracee is running when the tracer wants to detach it, the usual "
8568 "solution is to send B<SIGSTOP> (using B<tgkill>(2), to make sure it goes to "
8569 "the correct thread), wait for the tracee to stop in signal-delivery-stop for "
8570 "B<SIGSTOP> and then detach it (suppressing B<SIGSTOP> injection).  A design "
8571 "bug is that this can race with concurrent B<SIGSTOP>s.  Another complication "
8572 "is that the tracee may enter other ptrace-stops and needs to be restarted "
8573 "and waited for again, until B<SIGSTOP> is seen.  Yet another complication is "
8574 "to be sure that the tracee is not already ptrace-stopped, because no signal "
8575 "delivery happens while it is\\(emnot even B<SIGSTOP>."
8576 msgstr ""
8577
8578 #. type: Plain text
8579 #: build/C/man2/ptrace.2:1600
8580 msgid ""
8581 "If the tracer dies, all tracees are automatically detached and restarted, "
8582 "unless they were in group-stop.  Handling of restart from group-stop is "
8583 "currently buggy, but the \"as planned\" behavior is to leave tracee stopped "
8584 "and waiting for B<SIGCONT>.  If the tracee is restarted from "
8585 "signal-delivery-stop, the pending signal is injected."
8586 msgstr ""
8587
8588 #. type: SS
8589 #: build/C/man2/ptrace.2:1600
8590 #, no-wrap
8591 msgid "execve(2) under ptrace"
8592 msgstr ""
8593
8594 #.  clone(2) CLONE_THREAD says:
8595 #.      If  any  of the threads in a thread group performs an execve(2),
8596 #.      then all threads other than the thread group leader are terminated,
8597 #.      and the new program is executed in the thread group leader.
8598 #
8599 #.  In kernel 3.1 sources, see fs/exec.c::de_thread()
8600 #. type: Plain text
8601 #: build/C/man2/ptrace.2:1619
8602 msgid ""
8603 "When one thread in a multithreaded process calls B<execve>(2), the kernel "
8604 "destroys all other threads in the process, and resets the thread ID of the "
8605 "execing thread to the thread group ID (process ID).  (Or, to put things "
8606 "another way, when a multithreaded process does an B<execve>(2), at "
8607 "completion of the call, it appears as though the B<execve>(2)  occurred in "
8608 "the thread group leader, regardless of which thread did the B<execve>(2).)  "
8609 "This resetting of the thread ID looks very confusing to tracers:"
8610 msgstr ""
8611
8612 #. type: Plain text
8613 #: build/C/man2/ptrace.2:1629
8614 msgid ""
8615 "All other threads stop in B<PTRACE_EVENT_EXIT> stop, if the "
8616 "B<PTRACE_O_TRACEEXIT> option was turned on.  Then all other threads except "
8617 "the thread group leader report death as if they exited via B<_exit>(2)  with "
8618 "exit code 0."
8619 msgstr ""
8620
8621 #. type: Plain text
8622 #: build/C/man2/ptrace.2:1637
8623 msgid ""
8624 "The execing tracee changes its thread ID while it is in the B<execve>(2).  "
8625 "(Remember, under ptrace, the \"pid\" returned from B<waitpid>(2), or fed "
8626 "into ptrace calls, is the tracee's thread ID.)  That is, the tracee's thread "
8627 "ID is reset to be the same as its process ID, which is the same as the "
8628 "thread group leader's thread ID."
8629 msgstr ""
8630
8631 #. type: Plain text
8632 #: build/C/man2/ptrace.2:1643
8633 msgid ""
8634 "Then a B<PTRACE_EVENT_EXEC> stop happens, if the B<PTRACE_O_TRACEEXEC> "
8635 "option was turned on."
8636 msgstr ""
8637
8638 #. type: Plain text
8639 #: build/C/man2/ptrace.2:1664
8640 msgid ""
8641 "If the thread group leader has reported its B<PTRACE_EVENT_EXIT> stop by "
8642 "this time, it appears to the tracer that the dead thread leader \"reappears "
8643 "from nowhere\".  (Note: the thread group leader does not report death via "
8644 "I<WIFEXITED(status)> until there is at least one other live thread.  This "
8645 "eliminates the possibility that the tracer will see it dying and then "
8646 "reappearing.)  If the thread group leader was still alive, for the tracer "
8647 "this may look as if thread group leader returns from a different system call "
8648 "than it entered, or even \"returned from a system call even though it was "
8649 "not in any system call\".  If the thread group leader was not traced (or was "
8650 "traced by a different tracer), then during B<execve>(2)  it will appear as "
8651 "if it has become a tracee of the tracer of the execing tracee."
8652 msgstr ""
8653
8654 #. type: Plain text
8655 #: build/C/man2/ptrace.2:1667
8656 msgid ""
8657 "All of the above effects are the artifacts of the thread ID change in the "
8658 "tracee."
8659 msgstr ""
8660
8661 #. type: Plain text
8662 #: build/C/man2/ptrace.2:1687
8663 msgid ""
8664 "The B<PTRACE_O_TRACEEXEC> option is the recommended tool for dealing with "
8665 "this situation.  First, it enables B<PTRACE_EVENT_EXEC> stop, which occurs "
8666 "before B<execve>(2)  returns.  In this stop, the tracer can use "
8667 "B<PTRACE_GETEVENTMSG> to retrieve the tracee's former thread ID.  (This "
8668 "feature was introduced in Linux 3.0).  Second, the B<PTRACE_O_TRACEEXEC> "
8669 "option disables legacy B<SIGTRAP> generation on B<execve>(2)."
8670 msgstr ""
8671
8672 #. type: Plain text
8673 #: build/C/man2/ptrace.2:1693
8674 msgid ""
8675 "When the tracer receives B<PTRACE_EVENT_EXEC> stop notification, it is "
8676 "guaranteed that except this tracee and the thread group leader, no other "
8677 "threads from the process are alive."
8678 msgstr ""
8679
8680 #. type: Plain text
8681 #: build/C/man2/ptrace.2:1701
8682 msgid ""
8683 "On receiving the B<PTRACE_EVENT_EXEC> stop notification, the tracer should "
8684 "clean up all its internal data structures describing the threads of this "
8685 "process, and retain only one data structure\\(emone which describes the "
8686 "single still running tracee, with"
8687 msgstr ""
8688
8689 #. type: Plain text
8690 #: build/C/man2/ptrace.2:1703
8691 #, no-wrap
8692 msgid "    thread ID == thread group ID == process ID.\n"
8693 msgstr ""
8694
8695 #. type: Plain text
8696 #: build/C/man2/ptrace.2:1707
8697 msgid "Example: two threads call B<execve>(2)  at the same time:"
8698 msgstr ""
8699
8700 #. type: Plain text
8701 #: build/C/man2/ptrace.2:1718
8702 #, no-wrap
8703 msgid ""
8704 "*** we get syscall-enter-stop in thread 1: **\n"
8705 "PID1 execve(\"/bin/foo\", \"foo\" E<lt>unfinished ...E<gt>\n"
8706 "*** we issue PTRACE_SYSCALL for thread 1 **\n"
8707 "*** we get syscall-enter-stop in thread 2: **\n"
8708 "PID2 execve(\"/bin/bar\", \"bar\" E<lt>unfinished ...E<gt>\n"
8709 "*** we issue PTRACE_SYSCALL for thread 2 **\n"
8710 "*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL **\n"
8711 "*** we get syscall-exit-stop for PID0: **\n"
8712 "PID0 E<lt>... execve resumedE<gt> )             = 0\n"
8713 msgstr ""
8714
8715 #. type: Plain text
8716 #: build/C/man2/ptrace.2:1741
8717 msgid ""
8718 "If the B<PTRACE_O_TRACEEXEC> option is I<not> in effect for the execing "
8719 "tracee, the kernel delivers an extra B<SIGTRAP> to the tracee after "
8720 "B<execve>(2)  returns.  This is an ordinary signal (similar to one which can "
8721 "be generated by I<kill -TRAP>), not a special kind of ptrace-stop.  "
8722 "Employing B<PTRACE_GETSIGINFO> for this signal returns I<si_code> set to 0 "
8723 "(I<SI_USER>).  This signal may be blocked by signal mask, and thus may be "
8724 "delivered (much) later."
8725 msgstr ""
8726
8727 #. type: Plain text
8728 #: build/C/man2/ptrace.2:1760
8729 msgid ""
8730 "Usually, the tracer (for example, B<strace>(1))  would not want to show this "
8731 "extra post-execve B<SIGTRAP> signal to the user, and would suppress its "
8732 "delivery to the tracee (if B<SIGTRAP> is set to B<SIG_DFL>, it is a killing "
8733 "signal).  However, determining I<which> B<SIGTRAP> to suppress is not easy.  "
8734 "Setting the B<PTRACE_O_TRACEEXEC> option and thus suppressing this extra "
8735 "B<SIGTRAP> is the recommended approach."
8736 msgstr ""
8737
8738 #. type: SS
8739 #: build/C/man2/ptrace.2:1760
8740 #, no-wrap
8741 msgid "Real parent"
8742 msgstr ""
8743
8744 #. type: Plain text
8745 #: build/C/man2/ptrace.2:1767
8746 msgid ""
8747 "The ptrace API (ab)uses the standard UNIX parent/child signaling over "
8748 "B<waitpid>(2).  This used to cause the real parent of the process to stop "
8749 "receiving several kinds of B<waitpid>(2)  notifications when the child "
8750 "process is traced by some other process."
8751 msgstr ""
8752
8753 #. type: Plain text
8754 #: build/C/man2/ptrace.2:1770
8755 msgid ""
8756 "Many of these bugs have been fixed, but as of Linux 2.6.38 several still "
8757 "exist; see BUGS below."
8758 msgstr ""
8759
8760 #. type: Plain text
8761 #: build/C/man2/ptrace.2:1772
8762 msgid "As of Linux 2.6.38, the following is believed to work correctly:"
8763 msgstr ""
8764
8765 #. type: Plain text
8766 #: build/C/man2/ptrace.2:1780
8767 msgid ""
8768 "exit/death by signal is reported first to the tracer, then, when the tracer "
8769 "consumes the B<waitpid>(2)  result, to the real parent (to the real parent "
8770 "only when the whole multithreaded process exits).  If the tracer and the "
8771 "real parent are the same process, the report is sent only once."
8772 msgstr ""
8773
8774 #. type: Plain text
8775 #: build/C/man2/ptrace.2:1791
8776 msgid ""
8777 "On success, B<PTRACE_PEEK*> requests return the requested data, while other "
8778 "requests return zero.  (On Linux, this is done in the libc wrapper around "
8779 "ptrace system call.  On the system call level, B<PTRACE_PEEK*> requests have "
8780 "a different API: they store the result at the address specified by I<data> "
8781 "parameter, and return value is the error flag.)"
8782 msgstr ""
8783
8784 #. type: Plain text
8785 #: build/C/man2/ptrace.2:1801
8786 msgid ""
8787 "On error, all requests return -1, and I<errno> is set appropriately.  Since "
8788 "the value returned by a successful B<PTRACE_PEEK*> request may be -1, the "
8789 "caller must clear I<errno> before the call, and then check it afterward to "
8790 "determine whether or not an error occurred."
8791 msgstr ""
8792
8793 #. type: Plain text
8794 #: build/C/man2/ptrace.2:1805
8795 msgid "(i386 only) There was an error with allocating or freeing a debug register."
8796 msgstr ""
8797
8798 #. type: Plain text
8799 #: build/C/man2/ptrace.2:1816
8800 msgid ""
8801 "There was an attempt to read from or write to an invalid area in the "
8802 "tracer's or the tracee's memory, probably because the area wasn't mapped or "
8803 "accessible.  Unfortunately, under Linux, different variations of this fault "
8804 "will return B<EIO> or B<EFAULT> more or less arbitrarily."
8805 msgstr ""
8806
8807 #. type: Plain text
8808 #: build/C/man2/ptrace.2:1819
8809 msgid "An attempt was made to set an invalid option."
8810 msgstr ""
8811
8812 #. type: Plain text
8813 #: build/C/man2/ptrace.2:1826
8814 msgid ""
8815 "I<request> is invalid, or an attempt was made to read from or write to an "
8816 "invalid area in the tracer's or the tracee's memory, or there was a "
8817 "word-alignment violation, or an invalid signal was specified during a "
8818 "restart request."
8819 msgstr ""
8820
8821 #. type: Plain text
8822 #: build/C/man2/ptrace.2:1839
8823 msgid ""
8824 "The specified process cannot be traced.  This could be because the tracer "
8825 "has insufficient privileges (the required capability is B<CAP_SYS_PTRACE>); "
8826 "unprivileged processes cannot trace processes that they cannot send signals "
8827 "to or those running set-user-ID/set-group-ID programs, for obvious reasons.  "
8828 "Alternatively, the process may already be being traced, or (on kernels "
8829 "before 2.6.26) be B<init>(8)  (PID 1)."
8830 msgstr ""
8831
8832 #. type: Plain text
8833 #: build/C/man2/ptrace.2:1844
8834 msgid ""
8835 "The specified process does not exist, or is not currently being traced by "
8836 "the caller, or is not stopped (for requests that require a stopped tracee)."
8837 msgstr ""
8838
8839 #. type: Plain text
8840 #: build/C/man2/ptrace.2:1846
8841 msgid "SVr4, 4.3BSD."
8842 msgstr ""
8843
8844 #. type: Plain text
8845 #: build/C/man2/ptrace.2:1861
8846 msgid ""
8847 "Although arguments to B<ptrace>()  are interpreted according to the "
8848 "prototype given, glibc currently declares B<ptrace>()  as a variadic "
8849 "function with only the I<request> argument fixed.  It is recommended to "
8850 "always supply four arguments, even if the requested operation does not use "
8851 "them, setting unused/ignored arguments to I<0L> or I<(void\\ *)\\ 0>."
8852 msgstr ""
8853
8854 #.  See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
8855 #. type: Plain text
8856 #: build/C/man2/ptrace.2:1866
8857 msgid ""
8858 "In Linux kernels before 2.6.26, B<init>(8), the process with PID 1, may not "
8859 "be traced."
8860 msgstr ""
8861
8862 #.  See http://lkml.org/lkml/2008/5/8/375
8863 #. type: Plain text
8864 #: build/C/man2/ptrace.2:1873
8865 msgid ""
8866 "The layout of the contents of memory and the USER area are quite "
8867 "operating-system- and architecture-specific.  The offset supplied, and the "
8868 "data returned, might not entirely match with the definition of I<struct "
8869 "user>."
8870 msgstr ""
8871
8872 #. type: Plain text
8873 #: build/C/man2/ptrace.2:1876
8874 msgid ""
8875 "The size of a \"word\" is determined by the operating-system variant (e.g., "
8876 "for 32-bit Linux it is 32 bits)."
8877 msgstr ""
8878
8879 #. type: Plain text
8880 #: build/C/man2/ptrace.2:1884
8881 msgid ""
8882 "This page documents the way the B<ptrace>()  call works currently in Linux.  "
8883 "Its behavior differs noticeably on other flavors of UNIX.  In any case, use "
8884 "of B<ptrace>()  is highly specific to the operating system and architecture."
8885 msgstr ""
8886
8887 #. type: Plain text
8888 #: build/C/man2/ptrace.2:1895
8889 msgid ""
8890 "On hosts with 2.6 kernel headers, B<PTRACE_SETOPTIONS> is declared with a "
8891 "different value than the one for 2.4.  This leads to applications compiled "
8892 "with 2.6 kernel headers failing when run on 2.4 kernels.  This can be worked "
8893 "around by redefining B<PTRACE_SETOPTIONS> to B<PTRACE_OLDSETOPTIONS>, if "
8894 "that is defined."
8895 msgstr ""
8896
8897 #. type: Plain text
8898 #: build/C/man2/ptrace.2:1898
8899 msgid ""
8900 "Group-stop notifications are sent to the tracer, but not to real parent.  "
8901 "Last confirmed on 2.6.38.6."
8902 msgstr ""
8903
8904 #.  Note from Denys Vlasenko:
8905 #.      Here "exits" means any kind of death - _exit, exit_group,
8906 #.      signal death. Signal death and exit_group cases are trivial,
8907 #.      though: since signal death and exit_group kill all other threads
8908 #.      too, "until all other threads exit" thing happens rather soon
8909 #.      in these cases. Therefore, only _exit presents observably
8910 #.      puzzling behavior to ptrace users: thread leader _exit's,
8911 #.      but WIFEXITED isn't reported! We are trying to explain here
8912 #.      why it is so.
8913 #.   FIXME: ^^^ need to test/verify this scenario
8914 #. type: Plain text
8915 #: build/C/man2/ptrace.2:1929
8916 msgid ""
8917 "If a thread group leader is traced and exits by calling B<_exit>(2), a "
8918 "B<PTRACE_EVENT_EXIT> stop will happen for it (if requested), but the "
8919 "subsequent B<WIFEXITED> notification will not be delivered until all other "
8920 "threads exit.  As explained above, if one of other threads calls "
8921 "B<execve>(2), the death of the thread group leader will I<never> be "
8922 "reported.  If the execed thread is not traced by this tracer, the tracer "
8923 "will never know that B<execve>(2)  happened.  One possible workaround is to "
8924 "B<PTRACE_DETACH> the thread group leader instead of restarting it in this "
8925 "case.  Last confirmed on 2.6.38.6."
8926 msgstr ""
8927
8928 #. type: Plain text
8929 #: build/C/man2/ptrace.2:1939
8930 msgid ""
8931 "A B<SIGKILL> signal may still cause a B<PTRACE_EVENT_EXIT> stop before "
8932 "actual signal death.  This may be changed in the future; B<SIGKILL> is meant "
8933 "to always immediately kill tasks even under ptrace.  Last confirmed on "
8934 "2.6.38.6."
8935 msgstr ""
8936
8937 #. type: Plain text
8938 #: build/C/man2/ptrace.2:1957
8939 msgid ""
8940 "Some system calls return with B<EINTR> if a signal was sent to a tracee, but "
8941 "delivery was suppressed by the tracer.  (This is very typical operation: it "
8942 "is usually done by debuggers on every attach, in order to not introduce a "
8943 "bogus B<SIGSTOP>).  As of Linux 3.2.9, the following system calls are "
8944 "affected (this list is likely incomplete): B<epoll_wait>(2), and B<read>(2)  "
8945 "from an B<inotify>(7)  file descriptor.  The usual symptom of this bug is "
8946 "that when you attach to a quiescent process with the command"
8947 msgstr ""
8948
8949 #. type: Plain text
8950 #: build/C/man2/ptrace.2:1959
8951 #, no-wrap
8952 msgid "    strace -p E<lt>process-IDE<gt>\n"
8953 msgstr ""
8954
8955 #. type: Plain text
8956 #: build/C/man2/ptrace.2:1962
8957 msgid "then, instead of the usual and expected one-line output such as"
8958 msgstr ""
8959
8960 #. type: Plain text
8961 #: build/C/man2/ptrace.2:1965
8962 #, no-wrap
8963 msgid "    restart_syscall(E<lt>... resuming interrupted call ...E<gt>_\n"
8964 msgstr ""
8965
8966 #. type: Plain text
8967 #: build/C/man2/ptrace.2:1971
8968 #, no-wrap
8969 msgid "    select(6, [5], NULL, [5], NULL_\n"
8970 msgstr ""
8971
8972 #. type: Plain text
8973 #: build/C/man2/ptrace.2:1975
8974 msgid ""
8975 "('_' denotes the cursor position), you observe more than one line.  For "
8976 "example:"
8977 msgstr ""
8978
8979 #. type: Plain text
8980 #: build/C/man2/ptrace.2:1979
8981 #, no-wrap
8982 msgid ""
8983 "    clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0\n"
8984 "    epoll_wait(4,_\n"
8985 msgstr ""
8986
8987 #. type: Plain text
8988 #: build/C/man2/ptrace.2:2000
8989 msgid ""
8990 "What is not visible here is that the process was blocked in B<epoll_wait>(2)  "
8991 "before B<strace>(1)  has attached to it.  Attaching caused B<epoll_wait>(2)  "
8992 "to return to user space with the error B<EINTR>.  In this particular case, "
8993 "the program reacted to B<EINTR> by checking the current time, and then "
8994 "executing B<epoll_wait>(2)  again.  (Programs which do not expect such "
8995 "\"stray\" B<EINTR> errors may behave in an unintended way upon an "
8996 "B<strace>(1)  attach.)"
8997 msgstr ""
8998
8999 #. type: Plain text
9000 #: build/C/man2/ptrace.2:2014
9001 msgid ""
9002 "B<gdb>(1), B<strace>(1), B<clone>(2), B<execve>(2), B<fork>(2), "
9003 "B<gettid>(2), B<sigaction>(2), B<tgkill>(2), B<vfork>(2), B<waitpid>(2), "
9004 "B<exec>(3), B<capabilities>(7), B<signal>(7)"
9005 msgstr ""
9006
9007 #. type: TH
9008 #: build/C/man2/quotactl.2:27
9009 #, no-wrap
9010 msgid "QUOTACTL"
9011 msgstr ""
9012
9013 #. type: TH
9014 #: build/C/man2/quotactl.2:27
9015 #, no-wrap
9016 msgid "2010-06-16"
9017 msgstr ""
9018
9019 #. type: Plain text
9020 #: build/C/man2/quotactl.2:30
9021 msgid "quotactl - manipulate disk quotas"
9022 msgstr ""
9023
9024 #. type: Plain text
9025 #: build/C/man2/quotactl.2:34
9026 #, no-wrap
9027 msgid ""
9028 "B<#include E<lt>sys/quota.hE<gt>>\n"
9029 "B<#include E<lt>xfs/xqm.hE<gt>>\n"
9030 msgstr ""
9031
9032 #. type: Plain text
9033 #: build/C/man2/quotactl.2:37
9034 #, no-wrap
9035 msgid ""
9036 "B<int quotactl(int >I<cmd>B<, const char *>I<special>B<, int >I<id>B<, "
9037 "caddr_t >I<addr>B<);>\n"
9038 msgstr ""
9039
9040 #. type: Plain text
9041 #: build/C/man2/quotactl.2:49
9042 msgid ""
9043 "The quota system can be used to set per-user and per-group limits on the "
9044 "amount of disk space used on a filesystem.  For each user and/or group, a "
9045 "soft limit and a hard limit can be set for each filesystem.  The hard limit "
9046 "can't be exceeded.  The soft limit can be exceeded, but warnings will "
9047 "ensue.  Moreover, the user can't exceed the soft limit for more than one "
9048 "week (by default) at a time; after this time, the soft limit counts as a "
9049 "hard limit."
9050 msgstr ""
9051
9052 #. type: Plain text
9053 #: build/C/man2/quotactl.2:74
9054 msgid ""
9055 "The B<quotactl>()  call manipulates disk quotas.  The I<cmd> argument "
9056 "indicates a command to be applied to the user or group ID specified in "
9057 "I<id>.  To initialize the I<cmd> argument, use the I<QCMD(subcmd, type)> "
9058 "macro.  The I<type> value is either B<USRQUOTA>, for user quotas, or "
9059 "B<GRPQUOTA>, for group quotas.  The I<subcmd> value is described below."
9060 msgstr ""
9061
9062 #. type: Plain text
9063 #: build/C/man2/quotactl.2:79
9064 msgid ""
9065 "The I<special> argument is a pointer to a null-terminated string containing "
9066 "the pathname of the (mounted) block special device for the filesystem being "
9067 "manipulated."
9068 msgstr ""
9069
9070 #. type: Plain text
9071 #: build/C/man2/quotactl.2:87
9072 msgid ""
9073 "The I<addr> argument is the address of an optional, command-specific, data "
9074 "structure that is copied in or out of the system.  The interpretation of "
9075 "I<addr> is given with each command below."
9076 msgstr ""
9077
9078 #. type: Plain text
9079 #: build/C/man2/quotactl.2:91
9080 msgid "The I<subcmd> value is one of the following:"
9081 msgstr ""
9082
9083 #. type: TP
9084 #: build/C/man2/quotactl.2:91
9085 #, no-wrap
9086 msgid "B<Q_QUOTAON>"
9087 msgstr ""
9088
9089 #. type: Plain text
9090 #: build/C/man2/quotactl.2:98
9091 msgid ""
9092 "Turn on quotas for a filesystem.  The I<id> argument is the identification "
9093 "number of the quota format to be used.  Currently, there are three supported "
9094 "quota formats:"
9095 msgstr ""
9096
9097 #. type: TP
9098 #: build/C/man2/quotactl.2:99
9099 #, no-wrap
9100 msgid "B<QFMT_VFS_OLD>"
9101 msgstr ""
9102
9103 #. type: Plain text
9104 #: build/C/man2/quotactl.2:102
9105 msgid "The original quota format."
9106 msgstr ""
9107
9108 #. type: TP
9109 #: build/C/man2/quotactl.2:102
9110 #, no-wrap
9111 msgid "B<QFMT_VFS_V0>"
9112 msgstr ""
9113
9114 #. type: Plain text
9115 #: build/C/man2/quotactl.2:106
9116 msgid ""
9117 "The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs and "
9118 "quota limits up to 2^42 bytes and 2^32 inodes."
9119 msgstr ""
9120
9121 #. type: TP
9122 #: build/C/man2/quotactl.2:106
9123 #, no-wrap
9124 msgid "B<QFMT_VFS_V1>"
9125 msgstr ""
9126
9127 #. type: Plain text
9128 #: build/C/man2/quotactl.2:110
9129 msgid ""
9130 "A quota format that can handle 32-bit UIDs and GIDs and quota limits of 2^64 "
9131 "bytes and 2^64 inodes."
9132 msgstr ""
9133
9134 #. type: Plain text
9135 #: build/C/man2/quotactl.2:121
9136 msgid ""
9137 "The I<addr> argument points to the pathname of a file containing the quotas "
9138 "for the filesystem.  The quota file must exist; it is normally created with "
9139 "the B<quotacheck>(8)  program.  This operation requires privilege "
9140 "(B<CAP_SYS_ADMIN>)."
9141 msgstr ""
9142
9143 #. type: TP
9144 #: build/C/man2/quotactl.2:121
9145 #, no-wrap
9146 msgid "B<Q_QUOTAOFF>"
9147 msgstr ""
9148
9149 #. type: Plain text
9150 #: build/C/man2/quotactl.2:131
9151 msgid ""
9152 "Turn off quotas for a filesystem.  The I<addr> and I<id> arguments are "
9153 "ignored.  This operation requires privilege (B<CAP_SYS_ADMIN>)."
9154 msgstr ""
9155
9156 #. type: TP
9157 #: build/C/man2/quotactl.2:131
9158 #, no-wrap
9159 msgid "B<Q_GETQUOTA>"
9160 msgstr ""
9161
9162 #. type: Plain text
9163 #: build/C/man2/quotactl.2:142
9164 msgid ""
9165 "Get disk quota limits and current usage for user or group I<id>.  The "
9166 "I<addr> argument is a pointer to a I<dqblk> structure defined in "
9167 "I<E<lt>sys/quota.hE<gt>> as follows:"
9168 msgstr ""
9169
9170 #. type: Plain text
9171 #: build/C/man2/quotactl.2:147 build/C/man2/quotactl.2:234
9172 #, no-wrap
9173 msgid ""
9174 "/* uint64_t is an unsigned 64-bit integer;\n"
9175 "   uint32_t is an unsigned 32-bit integer */\n"
9176 msgstr ""
9177
9178 #. type: Plain text
9179 #: build/C/man2/quotactl.2:167
9180 #, no-wrap
9181 msgid ""
9182 "struct dqblk {          /* Definition since Linux 2.4.22 */\n"
9183 "    uint64_t dqb_bhardlimit;   /* absolute limit on disk\n"
9184 "                                  quota blocks alloc */\n"
9185 "    uint64_t dqb_bsoftlimit;   /* preferred limit on\n"
9186 "                                  disk quota blocks */\n"
9187 "    uint64_t dqb_curspace;     /* current quota block\n"
9188 "                                  count */\n"
9189 "    uint64_t dqb_ihardlimit;   /* maximum number of\n"
9190 "                                  allocated inodes */\n"
9191 "    uint64_t dqb_isoftlimit;   /* preferred inode limit */\n"
9192 "    uint64_t dqb_curinodes;    /* current number of\n"
9193 "                                  allocated inodes */\n"
9194 "    uint64_t dqb_btime;        /* time limit for excessive\n"
9195 "                                  disk use */\n"
9196 "    uint64_t dqb_itime;        /* time limit for excessive\n"
9197 "                                  files */\n"
9198 "    uint32_t dqb_valid;        /* bit mask of QIF_*\n"
9199 "                                  constants */\n"
9200 "};\n"
9201 msgstr ""
9202
9203 #. type: Plain text
9204 #: build/C/man2/quotactl.2:170
9205 #, no-wrap
9206 msgid ""
9207 "/* Flags in dqb_valid that indicate which fields in\n"
9208 "   dqblk structure are valid. */\n"
9209 msgstr ""
9210
9211 #. type: Plain text
9212 #: build/C/man2/quotactl.2:181
9213 #, no-wrap
9214 msgid ""
9215 "#define QIF_BLIMITS   1\n"
9216 "#define QIF_SPACE     2\n"
9217 "#define QIF_ILIMITS   4\n"
9218 "#define QIF_INODES    8\n"
9219 "#define QIF_BTIME     16\n"
9220 "#define QIF_ITIME     32\n"
9221 "#define QIF_LIMITS    (QIF_BLIMITS | QIF_ILIMITS)\n"
9222 "#define QIF_USAGE     (QIF_SPACE | QIF_INODES)\n"
9223 "#define QIF_TIMES     (QIF_BTIME | QIF_ITIME)\n"
9224 "#define QIF_ALL       (QIF_LIMITS | QIF_USAGE | QIF_TIMES)\n"
9225 msgstr ""
9226
9227 #. type: Plain text
9228 #: build/C/man2/quotactl.2:198
9229 msgid ""
9230 "The I<dqb_valid> field is a bit mask that is set to indicate the entries in "
9231 "the I<dqblk> structure that are valid.  Currently, the kernel fills in all "
9232 "entries of the I<dqblk> structure and marks them as valid in the "
9233 "I<dqb_valid> field.  Unprivileged users may retrieve only their own quotas; "
9234 "a privileged user (B<CAP_SYS_ADMIN>)  can retrieve the quotas of any user."
9235 msgstr ""
9236
9237 #. type: TP
9238 #: build/C/man2/quotactl.2:198
9239 #, no-wrap
9240 msgid "B<Q_SETQUOTA>"
9241 msgstr ""
9242
9243 #. type: Plain text
9244 #: build/C/man2/quotactl.2:218
9245 msgid ""
9246 "Set quota information for user or group I<id>, using the information "
9247 "supplied in the I<dqblk> structure pointed to by I<addr>.  The I<dqb_valid> "
9248 "field of the I<dqblk> structure indicates which entries in the structure "
9249 "have been set by the caller.  This operation supersedes the B<Q_SETQLIM> and "
9250 "B<Q_SETUSE> operations in the previous quota interfaces.  This operation "
9251 "requires privilege (B<CAP_SYS_ADMIN>)."
9252 msgstr ""
9253
9254 #. type: TP
9255 #: build/C/man2/quotactl.2:218
9256 #, no-wrap
9257 msgid "B<Q_GETINFO>"
9258 msgstr ""
9259
9260 #. type: Plain text
9261 #: build/C/man2/quotactl.2:229
9262 msgid ""
9263 "Get information (like grace times) about quotafile.  The I<addr> argument "
9264 "should be a pointer to a I<dqinfo> structure.  This structure is defined in "
9265 "I<E<lt>sys/quota.hE<gt>> as follows:"
9266 msgstr ""
9267
9268 #. type: Plain text
9269 #: build/C/man2/quotactl.2:238
9270 #, no-wrap
9271 msgid ""
9272 "struct dqinfo {         /* Defined since kernel 2.4.22 */\n"
9273 "    uint64_t dqi_bgrace;    /* Time before block soft limit\n"
9274 "                               becomes hard limit */\n"
9275 msgstr ""
9276
9277 #. type: Plain text
9278 #: build/C/man2/quotactl.2:245
9279 #, no-wrap
9280 msgid ""
9281 "    uint64_t dqi_igrace;    /* Time before inode soft limit\n"
9282 "                               becomes hard limit */\n"
9283 "    uint32_t dqi_flags;     /* Flags for quotafile\n"
9284 "                               (DQF_*) */\n"
9285 "    uint32_t dqi_valid;\n"
9286 "};\n"
9287 msgstr ""
9288
9289 #. type: Plain text
9290 #: build/C/man2/quotactl.2:247
9291 #, no-wrap
9292 msgid "/* Bits for dqi_flags */\n"
9293 msgstr ""
9294
9295 #. type: Plain text
9296 #: build/C/man2/quotactl.2:249
9297 #, no-wrap
9298 msgid "/* Quota format QFMT_VFS_OLD */\n"
9299 msgstr ""
9300
9301 #. type: Plain text
9302 #: build/C/man2/quotactl.2:251
9303 #, no-wrap
9304 msgid "#define V1_DQF_RSQUASH\t1   /* Root squash enabled */\n"
9305 msgstr ""
9306
9307 #. type: Plain text
9308 #: build/C/man2/quotactl.2:253
9309 #, no-wrap
9310 msgid "/* Other quota formats have no dqi_flags bits defined */\n"
9311 msgstr ""
9312
9313 #. type: Plain text
9314 #: build/C/man2/quotactl.2:256
9315 #, no-wrap
9316 msgid ""
9317 "/* Flags in dqi_valid that indicate which fields in\n"
9318 "   dqinfo structure are valid. */\n"
9319 msgstr ""
9320
9321 #. type: Plain text
9322 #: build/C/man2/quotactl.2:261
9323 #, no-wrap
9324 msgid ""
9325 "# define IIF_BGRACE\t1\n"
9326 "# define IIF_IGRACE\t2\n"
9327 "# define IIF_FLAGS\t4\n"
9328 "# define IIF_ALL\t(IIF_BGRACE | IIF_IGRACE | IIF_FLAGS)\n"
9329 msgstr ""
9330
9331 #. type: Plain text
9332 #: build/C/man2/quotactl.2:277
9333 msgid ""
9334 "The I<dqi_valid> field in the I<dqinfo> structure indicates the entries in "
9335 "the structure that are valid.  Currently, the kernel fills in all entries of "
9336 "the I<dqinfo> structure and marks them all as valid in the I<dqi_valid> "
9337 "field.  The I<id> argument is ignored."
9338 msgstr ""
9339
9340 #. type: TP
9341 #: build/C/man2/quotactl.2:277
9342 #, no-wrap
9343 msgid "B<Q_SETINFO>"
9344 msgstr ""
9345
9346 #. type: Plain text
9347 #: build/C/man2/quotactl.2:301
9348 msgid ""
9349 "Set information about quotafile.  The I<addr> argument should be a pointer "
9350 "to a I<dqinfo> structure.  The I<dqi_valid> field of the I<dqinfo> structure "
9351 "indicates the entries in the structure that have been set by the caller.  "
9352 "This operation supersedes the B<Q_SETGRACE> and B<Q_SETFLAGS> operations in "
9353 "the previous quota interfaces.  The I<id> argument is ignored.  This "
9354 "operation requires privilege (B<CAP_SYS_ADMIN>)."
9355 msgstr ""
9356
9357 #. type: TP
9358 #: build/C/man2/quotactl.2:301
9359 #, no-wrap
9360 msgid "B<Q_GETFMT>"
9361 msgstr ""
9362
9363 #. type: Plain text
9364 #: build/C/man2/quotactl.2:308
9365 msgid ""
9366 "Get quota format used on the specified filesystem.  The I<addr> argument "
9367 "should be a pointer to a 4-byte buffer where the format number will be "
9368 "stored."
9369 msgstr ""
9370
9371 #. type: TP
9372 #: build/C/man2/quotactl.2:308
9373 #, no-wrap
9374 msgid "B<Q_SYNC>"
9375 msgstr ""
9376
9377 #. type: Plain text
9378 #: build/C/man2/quotactl.2:319
9379 msgid ""
9380 "Update the on-disk copy of quota usages for a filesystem.  If I<special> is "
9381 "NULL, then all filesystems with active quotas are sync'ed.  The I<addr> and "
9382 "I<id> arguments are ignored."
9383 msgstr ""
9384
9385 #. type: TP
9386 #: build/C/man2/quotactl.2:319
9387 #, no-wrap
9388 msgid "B<Q_GETSTATS>"
9389 msgstr ""
9390
9391 #.  Q_GETSTATS was removed in kernel 2.4.22.
9392 #. type: Plain text
9393 #: build/C/man2/quotactl.2:339
9394 msgid ""
9395 "Get statistics and other generic information about the quota subsystem.  The "
9396 "I<addr> argument should be a pointer to a I<dqstats> structure in which data "
9397 "should be stored.  This structure is defined in I<E<lt>sys/quota.hE<gt>.> "
9398 "The I<special> and I<id> arguments are ignored.  This operation is obsolete "
9399 "and not supported by recent kernels.  Files in I</proc/sys/fs/quota/> carry "
9400 "the information instead."
9401 msgstr ""
9402
9403 #. type: Plain text
9404 #: build/C/man2/quotactl.2:342
9405 msgid ""
9406 "For XFS filesystems making use of the XFS Quota Manager (XQM), the above "
9407 "commands are bypassed and the following commands are used:"
9408 msgstr ""
9409
9410 #. type: TP
9411 #: build/C/man2/quotactl.2:342
9412 #, no-wrap
9413 msgid "B<Q_XQUOTAON>"
9414 msgstr ""
9415
9416 #. type: Plain text
9417 #: build/C/man2/quotactl.2:363
9418 msgid ""
9419 "Turn on quotas for an XFS filesystem.  XFS provides the ability to turn "
9420 "on/off quota limit enforcement with quota accounting.  Therefore, XFS "
9421 "expects I<addr> to be a pointer to an I<unsigned int> that contains either "
9422 "the flags B<XFS_QUOTA_UDQ_ACCT> and/or B<XFS_QUOTA_UDQ_ENFD> (for user "
9423 "quota), or B<XFS_QUOTA_GDQ_ACCT> and/or B<XFS_QUOTA_GDQ_ENFD> (for group "
9424 "quota), as defined in I<E<lt>xfs/xqm.hE<gt>>.  This operation requires "
9425 "privilege (B<CAP_SYS_ADMIN>)."
9426 msgstr ""
9427
9428 #. type: TP
9429 #: build/C/man2/quotactl.2:363
9430 #, no-wrap
9431 msgid "B<Q_XQUOTAOFF>"
9432 msgstr ""
9433
9434 #. type: Plain text
9435 #: build/C/man2/quotactl.2:374
9436 msgid ""
9437 "Turn off quotas for an XFS filesystem.  As with B<Q_QUOTAON>, XFS "
9438 "filesystems expect a pointer to an I<unsigned int> that specifies whether "
9439 "quota accounting and/or limit enforcement need to be turned off.  This "
9440 "operation requires privilege (B<CAP_SYS_ADMIN>)."
9441 msgstr ""
9442
9443 #. type: TP
9444 #: build/C/man2/quotactl.2:374
9445 #, no-wrap
9446 msgid "B<Q_XGETQUOTA>"
9447 msgstr ""
9448
9449 #. type: Plain text
9450 #: build/C/man2/quotactl.2:388
9451 msgid ""
9452 "Get disk quota limits and current usage for user I<id>.  The I<addr> "
9453 "argument is a pointer to an I<fs_disk_quota> structure (defined in "
9454 "I<E<lt>xfs/xqm.hE<gt>>).  Unprivileged users may retrieve only their own "
9455 "quotas; a privileged user (B<CAP_SYS_ADMIN>)  may retrieve the quotas of any "
9456 "user."
9457 msgstr ""
9458
9459 #. type: TP
9460 #: build/C/man2/quotactl.2:388
9461 #, no-wrap
9462 msgid "B<Q_XSETQLIM>"
9463 msgstr ""
9464
9465 #. type: Plain text
9466 #: build/C/man2/quotactl.2:400
9467 msgid ""
9468 "Set disk quota limits for user I<id>.  The I<addr> argument is a pointer to "
9469 "an I<fs_disk_quota> structure (defined in I<E<lt>xfs/xqm.hE<gt>>).  This "
9470 "operation requires privilege (B<CAP_SYS_ADMIN>)."
9471 msgstr ""
9472
9473 #. type: TP
9474 #: build/C/man2/quotactl.2:400
9475 #, no-wrap
9476 msgid "B<Q_XGETQSTAT>"
9477 msgstr ""
9478
9479 #. type: Plain text
9480 #: build/C/man2/quotactl.2:408
9481 msgid ""
9482 "Returns an I<fs_quota_stat> structure containing XFS filesystem specific "
9483 "quota information.  This is useful for finding out how much space is used to "
9484 "store quota information, and also to get quotaon/off status of a given local "
9485 "XFS filesystem."
9486 msgstr ""
9487
9488 #. type: TP
9489 #: build/C/man2/quotactl.2:408
9490 #, no-wrap
9491 msgid "B<Q_XQUOTARM>"
9492 msgstr ""
9493
9494 #. type: Plain text
9495 #: build/C/man2/quotactl.2:412
9496 msgid ""
9497 "Free the disk space taken by disk quotas.  Quotas must have already been "
9498 "turned off."
9499 msgstr ""
9500
9501 #. type: Plain text
9502 #: build/C/man2/quotactl.2:419
9503 msgid ""
9504 "There is no command equivalent to B<Q_SYNC> for XFS since B<sync>(1)  writes "
9505 "quota information to disk (in addition to the other filesystem metadata that "
9506 "it writes out)."
9507 msgstr ""
9508
9509 #. type: Plain text
9510 #: build/C/man2/quotactl.2:427
9511 msgid ""
9512 "On success, B<quotactl>()  returns 0; on error -1 is returned, and I<errno> "
9513 "is set to indicate the error."
9514 msgstr ""
9515
9516 #. type: Plain text
9517 #: build/C/man2/quotactl.2:434
9518 msgid "I<addr> or I<special> is invalid."
9519 msgstr ""
9520
9521 #. type: Plain text
9522 #: build/C/man2/quotactl.2:440
9523 msgid "I<cmd> or I<type> is invalid."
9524 msgstr ""
9525
9526 #. type: TP
9527 #: build/C/man2/quotactl.2:440
9528 #, no-wrap
9529 msgid "B<ENOENT>"
9530 msgstr ""
9531
9532 #. type: Plain text
9533 #: build/C/man2/quotactl.2:447
9534 msgid "The file specified by I<special> or I<addr> does not exist."
9535 msgstr ""
9536
9537 #. type: Plain text
9538 #: build/C/man2/quotactl.2:452
9539 msgid "The kernel has not been compiled with the B<CONFIG_QUOTA> option."
9540 msgstr ""
9541
9542 #. type: TP
9543 #: build/C/man2/quotactl.2:452
9544 #, no-wrap
9545 msgid "B<ENOTBLK>"
9546 msgstr ""
9547
9548 #. type: Plain text
9549 #: build/C/man2/quotactl.2:456
9550 msgid "I<special> is not a block device."
9551 msgstr ""
9552
9553 #. type: Plain text
9554 #: build/C/man2/quotactl.2:461
9555 msgid ""
9556 "The caller lacked the required privilege (B<CAP_SYS_ADMIN>)  for the "
9557 "specified operation."
9558 msgstr ""
9559
9560 #. type: Plain text
9561 #: build/C/man2/quotactl.2:465
9562 msgid ""
9563 "No disk quota is found for the indicated user.  Quotas have not been turned "
9564 "on for this filesystem."
9565 msgstr ""
9566
9567 #. type: Plain text
9568 #: build/C/man2/quotactl.2:474
9569 msgid "If I<cmd> is B<Q_SETQUOTA>, B<quotactl>()  may also set I<errno> to:"
9570 msgstr ""
9571
9572 #. type: Plain text
9573 #: build/C/man2/quotactl.2:477
9574 msgid "Specified limits are out of range allowed by quota format."
9575 msgstr ""
9576
9577 #. type: Plain text
9578 #: build/C/man2/quotactl.2:486
9579 msgid "If I<cmd> is B<Q_QUOTAON>, B<quotactl>()  may also set I<errno> to:"
9580 msgstr ""
9581
9582 #. type: Plain text
9583 #: build/C/man2/quotactl.2:495
9584 msgid ""
9585 "The quota file pointed to by I<addr> exists, but is not a regular file; or, "
9586 "the quota file pointed to by I<addr> exists, but is not on the filesystem "
9587 "pointed to by I<special>."
9588 msgstr ""
9589
9590 #. type: Plain text
9591 #: build/C/man2/quotactl.2:501
9592 msgid "B<Q_QUOTAON> attempted, but another B<Q_QUOTAON> had already been performed."
9593 msgstr ""
9594
9595 #. type: Plain text
9596 #: build/C/man2/quotactl.2:504
9597 msgid "The quota file is corrupted."
9598 msgstr ""
9599
9600 #. type: Plain text
9601 #: build/C/man2/quotactl.2:507
9602 msgid "Specified quota format was not found."
9603 msgstr ""
9604
9605 #. type: Plain text
9606 #: build/C/man2/quotactl.2:512
9607 msgid "B<quota>(1), B<getrlimit>(2), B<quotacheck>(8), B<quotaon>(8)"
9608 msgstr ""
9609
9610 #. type: TH
9611 #: build/C/man2/sendfile.2:19
9612 #, no-wrap
9613 msgid "SENDFILE"
9614 msgstr ""
9615
9616 #. type: TH
9617 #: build/C/man2/sendfile.2:19
9618 #, no-wrap
9619 msgid "2011-09-14"
9620 msgstr ""
9621
9622 #. type: Plain text
9623 #: build/C/man2/sendfile.2:22
9624 msgid "sendfile - transfer data between file descriptors"
9625 msgstr ""
9626
9627 #. type: Plain text
9628 #: build/C/man2/sendfile.2:24
9629 msgid "B<#include E<lt>sys/sendfile.hE<gt>>"
9630 msgstr ""
9631
9632 #.  The below is too ugly. Comments about glibc versions belong
9633 #.  in the notes, not in the header.
9634 #
9635 #.  .B #include <features.h>
9636 #.  .br
9637 #.  .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
9638 #.  .br
9639 #.  .B #include <sys/sendfile.h>
9640 #.  .br
9641 #.  #else
9642 #.  .br
9643 #.  .B #include <sys/types.h>
9644 #.  .br
9645 #.  .B /* No system prototype before glibc 2.1. */
9646 #.  .br
9647 #.  .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
9648 #.                        offset ", size_t" " count" )
9649 #.  .br
9650 #.  .B #endif
9651 #. type: Plain text
9652 #: build/C/man2/sendfile.2:47
9653 msgid ""
9654 "B<ssize_t sendfile(int>I< out_fd>B<, int>I< in_fd>B<, off_t *>I<offset>B<, "
9655 "size_t>I< count>B<);>"
9656 msgstr ""
9657
9658 #. type: Plain text
9659 #: build/C/man2/sendfile.2:57
9660 msgid ""
9661 "B<sendfile>()  copies data between one file descriptor and another.  Because "
9662 "this copying is done within the kernel, B<sendfile>()  is more efficient "
9663 "than the combination of B<read>(2)  and B<write>(2), which would require "
9664 "transferring data to and from user space."
9665 msgstr ""
9666
9667 #. type: Plain text
9668 #: build/C/man2/sendfile.2:62
9669 msgid ""
9670 "I<in_fd> should be a file descriptor opened for reading and I<out_fd> should "
9671 "be a descriptor opened for writing."
9672 msgstr ""
9673
9674 #. type: Plain text
9675 #: build/C/man2/sendfile.2:83
9676 msgid ""
9677 "If I<offset> is not NULL, then it points to a variable holding the file "
9678 "offset from which B<sendfile>()  will start reading data from I<in_fd>.  "
9679 "When B<sendfile>()  returns, this variable will be set to the offset of the "
9680 "byte following the last byte that was read.  If I<offset> is not NULL, then "
9681 "B<sendfile>()  does not modify the current file offset of I<in_fd>; "
9682 "otherwise the current file offset is adjusted to reflect the number of bytes "
9683 "read from I<in_fd>."
9684 msgstr ""
9685
9686 #. type: Plain text
9687 #: build/C/man2/sendfile.2:90
9688 msgid ""
9689 "If I<offset> is NULL, then data will be read from I<in_fd> starting at the "
9690 "current file offset, and the file offset will be updated by the call."
9691 msgstr ""
9692
9693 #. type: Plain text
9694 #: build/C/man2/sendfile.2:93
9695 msgid "I<count> is the number of bytes to copy between the file descriptors."
9696 msgstr ""
9697
9698 #. type: Plain text
9699 #: build/C/man2/sendfile.2:100
9700 msgid ""
9701 "The I<in_fd> argument must correspond to a file which supports "
9702 "B<mmap>(2)-like operations (i.e., it cannot be a socket)."
9703 msgstr ""
9704
9705 #. type: Plain text
9706 #: build/C/man2/sendfile.2:108
9707 msgid ""
9708 "In Linux kernels before 2.6.33, I<out_fd> must refer to a socket.  Since "
9709 "Linux 2.6.33 it can be any file.  If it is a regular file, then "
9710 "B<sendfile>()  changes the file offset appropriately."
9711 msgstr ""
9712
9713 #. type: Plain text
9714 #: build/C/man2/sendfile.2:115
9715 msgid ""
9716 "If the transfer was successful, the number of bytes written to I<out_fd> is "
9717 "returned.  On error, -1 is returned, and I<errno> is set appropriately."
9718 msgstr ""
9719
9720 #. type: Plain text
9721 #: build/C/man2/sendfile.2:121
9722 msgid ""
9723 "Nonblocking I/O has been selected using B<O_NONBLOCK> and the write would "
9724 "block."
9725 msgstr ""
9726
9727 #. type: TP
9728 #: build/C/man2/sendfile.2:121 build/C/man2/splice.2:143 build/C/man2/vmsplice.2:123
9729 #, no-wrap
9730 msgid "B<EBADF>"
9731 msgstr ""
9732
9733 #. type: Plain text
9734 #: build/C/man2/sendfile.2:125
9735 msgid ""
9736 "The input file was not opened for reading or the output file was not opened "
9737 "for writing."
9738 msgstr ""
9739
9740 #. type: Plain text
9741 #: build/C/man2/sendfile.2:128
9742 msgid "Bad address."
9743 msgstr ""
9744
9745 #. type: Plain text
9746 #: build/C/man2/sendfile.2:134
9747 msgid ""
9748 "Descriptor is not valid or locked, or an B<mmap>(2)-like operation is not "
9749 "available for I<in_fd>."
9750 msgstr ""
9751
9752 #. type: Plain text
9753 #: build/C/man2/sendfile.2:138
9754 msgid "Unspecified error while reading from I<in_fd>."
9755 msgstr ""
9756
9757 #. type: Plain text
9758 #: build/C/man2/sendfile.2:142
9759 msgid "Insufficient memory to read from I<in_fd>."
9760 msgstr ""
9761
9762 #. type: Plain text
9763 #: build/C/man2/sendfile.2:148
9764 msgid ""
9765 "B<sendfile>()  is a new feature in Linux 2.2.  The include file "
9766 "I<E<lt>sys/sendfile.hE<gt>> is present since glibc 2.1."
9767 msgstr ""
9768
9769 #. type: Plain text
9770 #: build/C/man2/sendfile.2:150
9771 msgid "Not specified in POSIX.1-2001, or other standards."
9772 msgstr ""
9773
9774 #. type: Plain text
9775 #: build/C/man2/sendfile.2:155
9776 msgid ""
9777 "Other UNIX systems implement B<sendfile>()  with different semantics and "
9778 "prototypes.  It should not be used in portable programs."
9779 msgstr ""
9780
9781 #. type: Plain text
9782 #: build/C/man2/sendfile.2:165
9783 msgid ""
9784 "If you plan to use B<sendfile>()  for sending files to a TCP socket, but "
9785 "need to send some header data in front of the file contents, you will find "
9786 "it useful to employ the B<TCP_CORK> option, described in B<tcp>(7), to "
9787 "minimize the number of packets and to tune performance."
9788 msgstr ""
9789
9790 #. type: Plain text
9791 #: build/C/man2/sendfile.2:171
9792 msgid ""
9793 "In Linux 2.4 and earlier, I<out_fd> could also refer to a regular file, and "
9794 "B<sendfile>()  changed the current offset of that file."
9795 msgstr ""
9796
9797 #. type: Plain text
9798 #: build/C/man2/sendfile.2:183
9799 msgid ""
9800 "The original Linux B<sendfile>()  system call was not designed to handle "
9801 "large file offsets.  Consequently, Linux 2.4 added B<sendfile64>(), with a "
9802 "wider type for the I<offset> argument.  The glibc B<sendfile>()  wrapper "
9803 "function transparently deals with the kernel differences."
9804 msgstr ""
9805
9806 #. type: Plain text
9807 #: build/C/man2/sendfile.2:192
9808 msgid ""
9809 "Applications may wish to fall back to B<read>(2)/B<write>(2)  in the case "
9810 "where B<sendfile>()  fails with B<EINVAL> or B<ENOSYS>."
9811 msgstr ""
9812
9813 #. type: Plain text
9814 #: build/C/man2/sendfile.2:197
9815 msgid ""
9816 "The Linux-specific B<splice>(2)  call supports transferring data between "
9817 "arbitrary files (e.g., a pair of sockets)."
9818 msgstr ""
9819
9820 #. type: Plain text
9821 #: build/C/man2/sendfile.2:202
9822 msgid "B<mmap>(2), B<open>(2), B<socket>(2), B<splice>(2)"
9823 msgstr ""
9824
9825 #. type: TH
9826 #: build/C/man2/set_tid_address.2:25
9827 #, no-wrap
9828 msgid "SET_TID_ADDRESS"
9829 msgstr ""
9830
9831 #. type: TH
9832 #: build/C/man2/set_tid_address.2:25
9833 #, no-wrap
9834 msgid "2012-07-19"
9835 msgstr ""
9836
9837 #. type: Plain text
9838 #: build/C/man2/set_tid_address.2:28
9839 msgid "set_tid_address - set pointer to thread ID"
9840 msgstr ""
9841
9842 #. type: Plain text
9843 #: build/C/man2/set_tid_address.2:31
9844 #, no-wrap
9845 msgid "B<#include E<lt>linux/unistd.hE<gt>>\n"
9846 msgstr ""
9847
9848 #. type: Plain text
9849 #: build/C/man2/set_tid_address.2:33
9850 #, no-wrap
9851 msgid "B<long set_tid_address(int *>I<tidptr>B<);>\n"
9852 msgstr ""
9853
9854 #. type: Plain text
9855 #: build/C/man2/set_tid_address.2:40
9856 msgid ""
9857 "For each process, the kernel maintains two attributes (addresses) called "
9858 "I<set_child_tid> and I<clear_child_tid>.  These two attributes contain the "
9859 "value NULL by default."
9860 msgstr ""
9861
9862 #. type: TP
9863 #: build/C/man2/set_tid_address.2:40
9864 #, no-wrap
9865 msgid "I<set_child_tid>"
9866 msgstr ""
9867
9868 #. type: Plain text
9869 #: build/C/man2/set_tid_address.2:51
9870 msgid ""
9871 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_SETTID> "
9872 "flag, I<set_child_tid> is set to the value passed in the I<ctid> argument of "
9873 "that system call."
9874 msgstr ""
9875
9876 #. type: Plain text
9877 #: build/C/man2/set_tid_address.2:56
9878 msgid ""
9879 "When I<set_child_tid> is set, the very first thing the new process does is "
9880 "writing its PID at this address."
9881 msgstr ""
9882
9883 #. type: TP
9884 #: build/C/man2/set_tid_address.2:56
9885 #, no-wrap
9886 msgid "I<clear_child_tid>"
9887 msgstr ""
9888
9889 #. type: Plain text
9890 #: build/C/man2/set_tid_address.2:67
9891 msgid ""
9892 "If a process is started using B<clone>(2)  with the B<CLONE_CHILD_CLEARTID> "
9893 "flag, I<clear_child_tid> is set to the value passed in the I<ctid> argument "
9894 "of that system call."
9895 msgstr ""
9896
9897 #. type: Plain text
9898 #: build/C/man2/set_tid_address.2:74
9899 msgid ""
9900 "The system call B<set_tid_address>()  sets the I<clear_child_tid> value for "
9901 "the calling process to I<tidptr>."
9902 msgstr ""
9903
9904 #. type: Plain text
9905 #: build/C/man2/set_tid_address.2:82
9906 msgid ""
9907 "When a process whose I<clear_child_tid> is not NULL terminates, then, if the "
9908 "process is sharing memory with other processes or threads, then 0 is written "
9909 "at the address specified in I<clear_child_tid> and the kernel performs the "
9910 "following operation:"
9911 msgstr ""
9912
9913 #. type: Plain text
9914 #: build/C/man2/set_tid_address.2:84
9915 #, no-wrap
9916 msgid "    futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);\n"
9917 msgstr ""
9918
9919 #. type: Plain text
9920 #: build/C/man2/set_tid_address.2:88
9921 msgid ""
9922 "The effect of this operation is to wake a single process that is performing "
9923 "a futex wait on the memory location.  Errors from the futex wake operation "
9924 "are ignored."
9925 msgstr ""
9926
9927 #. type: Plain text
9928 #: build/C/man2/set_tid_address.2:91
9929 msgid "B<set_tid_address>()  always returns the PID of the calling process."
9930 msgstr ""
9931
9932 #. type: Plain text
9933 #: build/C/man2/set_tid_address.2:94
9934 msgid "B<set_tid_address>()  always succeeds."
9935 msgstr ""
9936
9937 #. type: Plain text
9938 #: build/C/man2/set_tid_address.2:97
9939 msgid ""
9940 "This call is present since Linux 2.5.48.  Details as given here are valid "
9941 "since Linux 2.5.49."
9942 msgstr ""
9943
9944 #. type: Plain text
9945 #: build/C/man2/set_tid_address.2:102
9946 msgid "B<clone>(2), B<futex>(2)"
9947 msgstr ""
9948
9949 #. type: TH
9950 #: build/C/man2/splice.2:26
9951 #, no-wrap
9952 msgid "SPLICE"
9953 msgstr ""
9954
9955 #. type: TH
9956 #: build/C/man2/splice.2:26 build/C/man2/tee.2:26 build/C/man2/vmsplice.2:26
9957 #, no-wrap
9958 msgid "2012-05-04"
9959 msgstr ""
9960
9961 #. type: Plain text
9962 #: build/C/man2/splice.2:29
9963 msgid "splice - splice data to/from a pipe"
9964 msgstr ""
9965
9966 #. type: Plain text
9967 #: build/C/man2/splice.2:33 build/C/man2/tee.2:33
9968 #, no-wrap
9969 msgid ""
9970 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
9971 "B<#include E<lt>fcntl.hE<gt>>\n"
9972 msgstr ""
9973
9974 #.  Return type was long before glibc 2.7
9975 #. type: Plain text
9976 #: build/C/man2/splice.2:38
9977 #, no-wrap
9978 msgid ""
9979 "B<ssize_t splice(int >I<fd_in>B<, loff_t *>I<off_in>B<, int >I<fd_out>B<,>\n"
9980 "B<               loff_t *>I<off_out>B<, size_t >I<len>B<, unsigned int "
9981 ">I<flags>B<);>\n"
9982 msgstr ""
9983
9984 #. type: Plain text
9985 #: build/C/man2/splice.2:50
9986 msgid ""
9987 "B<splice>()  moves data between two file descriptors without copying between "
9988 "kernel address space and user address space.  It transfers up to I<len> "
9989 "bytes of data from the file descriptor I<fd_in> to the file descriptor "
9990 "I<fd_out>, where one of the descriptors must refer to a pipe."
9991 msgstr ""
9992
9993 #. type: Plain text
9994 #: build/C/man2/splice.2:80
9995 msgid ""
9996 "If I<fd_in> refers to a pipe, then I<off_in> must be NULL.  If I<fd_in> does "
9997 "not refer to a pipe and I<off_in> is NULL, then bytes are read from I<fd_in> "
9998 "starting from the current file offset, and the current file offset is "
9999 "adjusted appropriately.  If I<fd_in> does not refer to a pipe and I<off_in> "
10000 "is not NULL, then I<off_in> must point to a buffer which specifies the "
10001 "starting offset from which bytes will be read from I<fd_in>; in this case, "
10002 "the current file offset of I<fd_in> is not changed.  Analogous statements "
10003 "apply for I<fd_out> and I<off_out>."
10004 msgstr ""
10005
10006 #. type: Plain text
10007 #: build/C/man2/splice.2:85 build/C/man2/vmsplice.2:78
10008 msgid ""
10009 "The I<flags> argument is a bit mask that is composed by ORing together zero "
10010 "or more of the following values:"
10011 msgstr ""
10012
10013 #. type: TP
10014 #: build/C/man2/splice.2:85 build/C/man2/tee.2:62 build/C/man2/vmsplice.2:78
10015 #, no-wrap
10016 msgid "B<SPLICE_F_MOVE>"
10017 msgstr ""
10018
10019 #. type: Plain text
10020 #: build/C/man2/splice.2:98
10021 msgid ""
10022 "Attempt to move pages instead of copying.  This is only a hint to the "
10023 "kernel: pages may still be copied if the kernel cannot move the pages from "
10024 "the pipe, or if the pipe buffers don't refer to full pages.  The initial "
10025 "implementation of this flag was buggy: therefore starting in Linux 2.6.21 it "
10026 "is a no-op (but is still permitted in a B<splice>()  call); in the future, a "
10027 "correct implementation may be restored."
10028 msgstr ""
10029
10030 #. type: TP
10031 #: build/C/man2/splice.2:98 build/C/man2/tee.2:68 build/C/man2/vmsplice.2:84
10032 #, no-wrap
10033 msgid "B<SPLICE_F_NONBLOCK>"
10034 msgstr ""
10035
10036 #. type: Plain text
10037 #: build/C/man2/splice.2:107
10038 msgid ""
10039 "Do not block on I/O.  This makes the splice pipe operations nonblocking, but "
10040 "B<splice>()  may nevertheless block because the file descriptors that are "
10041 "spliced to/from may block (unless they have the B<O_NONBLOCK> flag set)."
10042 msgstr ""
10043
10044 #. type: TP
10045 #: build/C/man2/splice.2:107 build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10046 #, no-wrap
10047 msgid "B<SPLICE_F_MORE>"
10048 msgstr ""
10049
10050 #. type: Plain text
10051 #: build/C/man2/splice.2:121
10052 msgid ""
10053 "More data will be coming in a subsequent splice.  This is a helpful hint "
10054 "when the I<fd_out> refers to a socket (see also the description of "
10055 "B<MSG_MORE> in B<send>(2), and the description of B<TCP_CORK> in B<tcp>(7))"
10056 msgstr ""
10057
10058 #. type: TP
10059 #: build/C/man2/splice.2:121 build/C/man2/tee.2:79 build/C/man2/vmsplice.2:97
10060 #, no-wrap
10061 msgid "B<SPLICE_F_GIFT>"
10062 msgstr ""
10063
10064 #. type: Plain text
10065 #: build/C/man2/splice.2:127
10066 msgid "Unused for B<splice>(); see B<vmsplice>(2)."
10067 msgstr ""
10068
10069 #. type: Plain text
10070 #: build/C/man2/splice.2:136
10071 msgid ""
10072 "Upon successful completion, B<splice>()  returns the number of bytes spliced "
10073 "to or from the pipe.  A return value of 0 means that there was no data to "
10074 "transfer, and it would not make sense to block, because there are no writers "
10075 "connected to the write end of the pipe referred to by I<fd_in>."
10076 msgstr ""
10077
10078 #. type: Plain text
10079 #: build/C/man2/splice.2:142
10080 msgid "On error, B<splice>()  returns -1 and I<errno> is set to indicate the error."
10081 msgstr ""
10082
10083 #. type: Plain text
10084 #: build/C/man2/splice.2:147
10085 msgid ""
10086 "One or both file descriptors are not valid, or do not have proper read-write "
10087 "mode."
10088 msgstr ""
10089
10090 #.  The append-mode error is given since 2.6.27; in earlier kernels,
10091 #.  splice() in append mode was broken
10092 #. type: Plain text
10093 #: build/C/man2/splice.2:155
10094 msgid ""
10095 "Target filesystem doesn't support splicing; target file is opened in append "
10096 "mode; neither of the descriptors refers to a pipe; or offset given for "
10097 "nonseekable device."
10098 msgstr ""
10099
10100 #. type: Plain text
10101 #: build/C/man2/splice.2:158 build/C/man2/tee.2:114 build/C/man2/vmsplice.2:138
10102 msgid "Out of memory."
10103 msgstr ""
10104
10105 #. type: TP
10106 #: build/C/man2/splice.2:158
10107 #, no-wrap
10108 msgid "B<ESPIPE>"
10109 msgstr ""
10110
10111 #. type: Plain text
10112 #: build/C/man2/splice.2:165
10113 msgid ""
10114 "Either I<off_in> or I<off_out> was not NULL, but the corresponding file "
10115 "descriptor refers to a pipe."
10116 msgstr ""
10117
10118 #. type: Plain text
10119 #: build/C/man2/splice.2:170
10120 msgid ""
10121 "The B<splice>()  system call first appeared in Linux 2.6.17; library support "
10122 "was added to glibc in version 2.5."
10123 msgstr ""
10124
10125 #. type: Plain text
10126 #: build/C/man2/splice.2:182
10127 msgid ""
10128 "The three system calls B<splice>(), B<vmsplice>(2), and B<tee>(2), provide "
10129 "user-space programs with full control over an arbitrary kernel buffer, "
10130 "implemented within the kernel using the same type of buffer that is used for "
10131 "a pipe.  In overview, these system calls perform the following tasks:"
10132 msgstr ""
10133
10134 #. type: TP
10135 #: build/C/man2/splice.2:182
10136 #, no-wrap
10137 msgid "B<splice>()"
10138 msgstr ""
10139
10140 #. type: Plain text
10141 #: build/C/man2/splice.2:186
10142 msgid ""
10143 "moves data from the buffer to an arbitrary file descriptor, or vice versa, "
10144 "or from one buffer to another."
10145 msgstr ""
10146
10147 #. type: TP
10148 #: build/C/man2/splice.2:186
10149 #, no-wrap
10150 msgid "B<tee>(2)"
10151 msgstr ""
10152
10153 #. type: Plain text
10154 #: build/C/man2/splice.2:189
10155 msgid "\"copies\" the data from one buffer to another."
10156 msgstr ""
10157
10158 #. type: TP
10159 #: build/C/man2/splice.2:189
10160 #, no-wrap
10161 msgid "B<vmsplice>(2)"
10162 msgstr ""
10163
10164 #. type: Plain text
10165 #: build/C/man2/splice.2:192
10166 msgid "\"copies\" data from user space into the buffer."
10167 msgstr ""
10168
10169 #
10170 #.  Linus: Now, imagine using the above in a media server, for example.
10171 #.  Let's say that a year or two has passed, so that the video drivers
10172 #.  have been updated to be able to do the splice thing, and what can
10173 #.  you do? You can:
10174 #
10175 #.  - splice from the (mpeg or whatever - let's just assume that the video
10176 #.    input is either digital or does the encoding on its own - like they
10177 #.    pretty much all do) video input into a pipe (remember: no copies - the
10178 #.    video input will just DMA directly into memory, and splice will just
10179 #.    set up the pages in the pipe buffer)
10180 #.  - tee that pipe to split it up
10181 #.  - splice one end to a file (ie "save the compressed stream to disk")
10182 #.  - splice the other end to a real-time video decoder window for your
10183 #.    real-time viewing pleasure.
10184 #
10185 #.  Linus: Now, the advantage of splice()/tee() is that you can
10186 #.  do zero-copy movement of data, and unlike sendfile() you can
10187 #.  do it on _arbitrary_ data (and, as shown by "tee()", it's more
10188 #.  than just sending the data to somebody else: you can duplicate
10189 #.  the data and choose to forward it to two or more different
10190 #.  users - for things like logging etc.).
10191 #. type: Plain text
10192 #: build/C/man2/splice.2:223
10193 msgid ""
10194 "Though we talk of copying, actual copies are generally avoided.  The kernel "
10195 "does this by implementing a pipe buffer as a set of reference-counted "
10196 "pointers to pages of kernel memory.  The kernel creates \"copies\" of pages "
10197 "in a buffer by creating new pointers (for the output buffer) referring to "
10198 "the pages, and increasing the reference counts for the pages: only pointers "
10199 "are copied, not the pages of the buffer."
10200 msgstr ""
10201
10202 #. type: Plain text
10203 #: build/C/man2/splice.2:226
10204 msgid "See B<tee>(2)."
10205 msgstr ""
10206
10207 #. type: Plain text
10208 #: build/C/man2/splice.2:230
10209 msgid "B<sendfile>(2), B<tee>(2), B<vmsplice>(2)"
10210 msgstr ""
10211
10212 #. type: TH
10213 #: build/C/man2/tee.2:26
10214 #, no-wrap
10215 msgid "TEE"
10216 msgstr ""
10217
10218 #. type: Plain text
10219 #: build/C/man2/tee.2:29
10220 msgid "tee - duplicating pipe content"
10221 msgstr ""
10222
10223 #. type: Plain text
10224 #: build/C/man2/tee.2:36
10225 #, no-wrap
10226 msgid ""
10227 "B<ssize_t tee(int >I<fd_in>B<, int >I<fd_out>B<, size_t >I<len>B<, unsigned "
10228 "int >I<flags>B<);>\n"
10229 msgstr ""
10230
10231 #.  Example programs http://brick.kernel.dk/snaps
10232 #
10233 #
10234 #.  add a "tee(in, out1, out2)" system call that duplicates the pages
10235 #.  (again, incrementing their reference count, not copying the data) from
10236 #.  one pipe to two other pipes.
10237 #. type: Plain text
10238 #: build/C/man2/tee.2:56
10239 msgid ""
10240 "B<tee>()  duplicates up to I<len> bytes of data from the pipe referred to by "
10241 "the file descriptor I<fd_in> to the pipe referred to by the file descriptor "
10242 "I<fd_out>.  It does not consume the data that is duplicated from I<fd_in>; "
10243 "therefore, that data can be copied by a subsequent B<splice>(2)."
10244 msgstr ""
10245
10246 #. type: Plain text
10247 #: build/C/man2/tee.2:62
10248 msgid ""
10249 "I<flags> is a series of modifier flags, which share the name space with "
10250 "B<splice>(2)  and B<vmsplice>(2):"
10251 msgstr ""
10252
10253 #. type: Plain text
10254 #: build/C/man2/tee.2:68
10255 msgid "Currently has no effect for B<tee>(); see B<splice>(2)."
10256 msgstr ""
10257
10258 #.  Not used for vmsplice
10259 #.  May be in the future -- therefore EAGAIN
10260 #. type: Plain text
10261 #: build/C/man2/tee.2:73 build/C/man2/vmsplice.2:91
10262 msgid "Do not block on I/O; see B<splice>(2)  for further details."
10263 msgstr ""
10264
10265 #. type: Plain text
10266 #: build/C/man2/tee.2:79
10267 msgid ""
10268 "Currently has no effect for B<tee>(), but may be implemented in the future; "
10269 "see B<splice>(2)."
10270 msgstr ""
10271
10272 #. type: Plain text
10273 #: build/C/man2/tee.2:85
10274 msgid "Unused for B<tee>(); see B<vmsplice>(2)."
10275 msgstr ""
10276
10277 #. type: Plain text
10278 #: build/C/man2/tee.2:94
10279 msgid ""
10280 "Upon successful completion, B<tee>()  returns the number of bytes that were "
10281 "duplicated between the input and output.  A return value of 0 means that "
10282 "there was no data to transfer, and it would not make sense to block, because "
10283 "there are no writers connected to the write end of the pipe referred to by "
10284 "I<fd_in>."
10285 msgstr ""
10286
10287 #. type: Plain text
10288 #: build/C/man2/tee.2:100
10289 msgid "On error, B<tee>()  returns -1 and I<errno> is set to indicate the error."
10290 msgstr ""
10291
10292 #. type: Plain text
10293 #: build/C/man2/tee.2:111
10294 msgid ""
10295 "I<fd_in> or I<fd_out> does not refer to a pipe; or I<fd_in> and I<fd_out> "
10296 "refer to the same pipe."
10297 msgstr ""
10298
10299 #. type: Plain text
10300 #: build/C/man2/tee.2:119
10301 msgid ""
10302 "The B<tee>()  system call first appeared in Linux 2.6.17; library support "
10303 "was added to glibc in version 2.5."
10304 msgstr ""
10305
10306 #. type: Plain text
10307 #: build/C/man2/tee.2:130
10308 msgid ""
10309 "Conceptually, B<tee>()  copies the data between the two pipes.  In reality "
10310 "no real data copying takes place though: under the covers, B<tee>()  assigns "
10311 "data in the output by merely grabbing a reference to the input."
10312 msgstr ""
10313
10314 #. type: Plain text
10315 #: build/C/man2/tee.2:136
10316 msgid ""
10317 "The following example implements a basic B<tee>(1)  program using the "
10318 "B<tee>()  system call."
10319 msgstr ""
10320
10321 #. type: Plain text
10322 #: build/C/man2/tee.2:145
10323 #, no-wrap
10324 msgid ""
10325 "#define _GNU_SOURCE\n"
10326 "#include E<lt>fcntl.hE<gt>\n"
10327 "#include E<lt>stdio.hE<gt>\n"
10328 "#include E<lt>stdlib.hE<gt>\n"
10329 "#include E<lt>unistd.hE<gt>\n"
10330 "#include E<lt>errno.hE<gt>\n"
10331 "#include E<lt>limits.hE<gt>\n"
10332 msgstr ""
10333
10334 #. type: Plain text
10335 #: build/C/man2/tee.2:151
10336 #, no-wrap
10337 msgid ""
10338 "int\n"
10339 "main(int argc, char *argv[])\n"
10340 "{\n"
10341 "    int fd;\n"
10342 "    int len, slen;\n"
10343 msgstr ""
10344
10345 #. type: Plain text
10346 #: build/C/man2/tee.2:156
10347 #, no-wrap
10348 msgid ""
10349 "    if (argc != 2) {\n"
10350 "        fprintf(stderr, \"Usage: %s E<lt>fileE<gt>\\en\", argv[0]);\n"
10351 "        exit(EXIT_FAILURE);\n"
10352 "    }\n"
10353 msgstr ""
10354
10355 #. type: Plain text
10356 #: build/C/man2/tee.2:162
10357 #, no-wrap
10358 msgid ""
10359 "    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);\n"
10360 "    if (fd == -1) {\n"
10361 "        perror(\"open\");\n"
10362 "        exit(EXIT_FAILURE);\n"
10363 "    }\n"
10364 msgstr ""
10365
10366 #. type: Plain text
10367 #: build/C/man2/tee.2:169
10368 #, no-wrap
10369 msgid ""
10370 "    do {\n"
10371 "        /*\n"
10372 "         * tee stdin to stdout.\n"
10373 "         */\n"
10374 "        len = tee(STDIN_FILENO, STDOUT_FILENO,\n"
10375 "                  INT_MAX, SPLICE_F_NONBLOCK);\n"
10376 msgstr ""
10377
10378 #. type: Plain text
10379 #: build/C/man2/tee.2:178
10380 #, no-wrap
10381 msgid ""
10382 "        if (len E<lt> 0) {\n"
10383 "            if (errno == EAGAIN)\n"
10384 "                continue;\n"
10385 "            perror(\"tee\");\n"
10386 "            exit(EXIT_FAILURE);\n"
10387 "        } else\n"
10388 "            if (len == 0)\n"
10389 "                break;\n"
10390 msgstr ""
10391
10392 #. type: Plain text
10393 #: build/C/man2/tee.2:192
10394 #, no-wrap
10395 msgid ""
10396 "        /*\n"
10397 "         * Consume stdin by splicing it to a file.\n"
10398 "         */\n"
10399 "        while (len E<gt> 0) {\n"
10400 "            slen = splice(STDIN_FILENO, NULL, fd, NULL,\n"
10401 "                          len, SPLICE_F_MOVE);\n"
10402 "            if (slen E<lt> 0) {\n"
10403 "                perror(\"splice\");\n"
10404 "                break;\n"
10405 "            }\n"
10406 "            len -= slen;\n"
10407 "        }\n"
10408 "    } while (1);\n"
10409 msgstr ""
10410
10411 #. type: Plain text
10412 #: build/C/man2/tee.2:196
10413 #, no-wrap
10414 msgid ""
10415 "    close(fd);\n"
10416 "    exit(EXIT_SUCCESS);\n"
10417 "}\n"
10418 msgstr ""
10419
10420 #. type: Plain text
10421 #: build/C/man2/tee.2:200
10422 msgid "B<splice>(2), B<vmsplice>(2)"
10423 msgstr ""
10424
10425 #. type: TH
10426 #: build/C/man2/vm86.2:26
10427 #, no-wrap
10428 msgid "VM86"
10429 msgstr ""
10430
10431 #. type: TH
10432 #: build/C/man2/vm86.2:26
10433 #, no-wrap
10434 msgid "2009-02-20"
10435 msgstr ""
10436
10437 #. type: Plain text
10438 #: build/C/man2/vm86.2:29
10439 msgid "vm86old, vm86 - enter virtual 8086 mode"
10440 msgstr ""
10441
10442 #. type: Plain text
10443 #: build/C/man2/vm86.2:31
10444 msgid "B<#include E<lt>sys/vm86.hE<gt>>"
10445 msgstr ""
10446
10447 #. type: Plain text
10448 #: build/C/man2/vm86.2:33
10449 msgid "B<int vm86old(struct vm86_struct *>I<info>B<);>"
10450 msgstr ""
10451
10452 #. type: Plain text
10453 #: build/C/man2/vm86.2:35
10454 msgid "B<int vm86(unsigned long >I<fn>B<, struct vm86plus_struct *>I<v86>B<);>"
10455 msgstr ""
10456
10457 #. type: Plain text
10458 #: build/C/man2/vm86.2:48
10459 msgid ""
10460 "The system call B<vm86>()  was introduced in Linux 0.97p2.  In Linux 2.1.15 "
10461 "and 2.0.28 it was renamed to B<vm86old>(), and a new B<vm86>()  was "
10462 "introduced.  The definition of I<struct vm86_struct> was changed in 1.1.8 "
10463 "and 1.1.9."
10464 msgstr ""
10465
10466 #. type: Plain text
10467 #: build/C/man2/vm86.2:52
10468 msgid ""
10469 "These calls cause the process to enter VM86 mode (virtual-8086 in Intel "
10470 "literature), and are used by B<dosemu>."
10471 msgstr ""
10472
10473 #. type: Plain text
10474 #: build/C/man2/vm86.2:54
10475 msgid "VM86 mode is an emulation of real mode within a protected mode task."
10476 msgstr ""
10477
10478 #. type: Plain text
10479 #: build/C/man2/vm86.2:64
10480 msgid ""
10481 "This return value is specific to i386 and indicates a problem with getting "
10482 "user-space data."
10483 msgstr ""
10484
10485 #. type: Plain text
10486 #: build/C/man2/vm86.2:68
10487 msgid ""
10488 "This return value indicates the call is not implemented on the present "
10489 "architecture."
10490 msgstr ""
10491
10492 #. type: Plain text
10493 #: build/C/man2/vm86.2:73
10494 msgid ""
10495 "Saved kernel stack exists.  (This is a kernel sanity check; the saved stack "
10496 "should exist only within vm86 mode itself.)"
10497 msgstr ""
10498
10499 #. type: Plain text
10500 #: build/C/man2/vm86.2:76
10501 msgid ""
10502 "This call is specific to Linux on 32-bit Intel processors, and should not be "
10503 "used in programs intended to be portable."
10504 msgstr ""
10505
10506 #. type: TH
10507 #: build/C/man2/vmsplice.2:26
10508 #, no-wrap
10509 msgid "VMSPLICE"
10510 msgstr ""
10511
10512 #. type: Plain text
10513 #: build/C/man2/vmsplice.2:29
10514 msgid "vmsplice - splice user pages into a pipe"
10515 msgstr ""
10516
10517 #. type: Plain text
10518 #: build/C/man2/vmsplice.2:34
10519 #, no-wrap
10520 msgid ""
10521 "B<#define _GNU_SOURCE>         /* See feature_test_macros(7) */\n"
10522 "B<#include E<lt>fcntl.hE<gt>>\n"
10523 "B<#include E<lt>sys/uio.hE<gt>>\n"
10524 msgstr ""
10525
10526 #. type: Plain text
10527 #: build/C/man2/vmsplice.2:37
10528 #, no-wrap
10529 msgid ""
10530 "B<ssize_t vmsplice(int >I<fd>B<, const struct iovec *>I<iov>B<,>\n"
10531 "B<                 unsigned long >I<nr_segs>B<, unsigned int "
10532 ">I<flags>B<);>\n"
10533 msgstr ""
10534
10535 #.  Linus: vmsplice() system call to basically do a "write to
10536 #.  the buffer", but using the reference counting and VM traversal
10537 #.  to actually fill the buffer. This means that the user needs to
10538 #.  be careful not to reuse the user-space buffer it spliced into
10539 #.  the kernel-space one (contrast this to "write()", which copies
10540 #.  the actual data, and you can thus reuse the buffer immediately
10541 #.  after a successful write), but that is often easy to do.
10542 #. type: Plain text
10543 #: build/C/man2/vmsplice.2:57
10544 msgid ""
10545 "The B<vmsplice>()  system call maps I<nr_segs> ranges of user memory "
10546 "described by I<iov> into a pipe.  The file descriptor I<fd> must refer to a "
10547 "pipe."
10548 msgstr ""
10549
10550 #. type: Plain text
10551 #: build/C/man2/vmsplice.2:64
10552 msgid ""
10553 "The pointer I<iov> points to an array of I<iovec> structures as defined in "
10554 "I<E<lt>sys/uio.hE<gt>>:"
10555 msgstr ""
10556
10557 #. type: Plain text
10558 #: build/C/man2/vmsplice.2:71
10559 #, no-wrap
10560 msgid ""
10561 "struct iovec {\n"
10562 "    void  *iov_base;            /* Starting address */\n"
10563 "    size_t iov_len;             /* Number of bytes */\n"
10564 "};\n"
10565 msgstr ""
10566
10567 #. type: Plain text
10568 #: build/C/man2/vmsplice.2:84
10569 msgid "Unused for B<vmsplice>(); see B<splice>(2)."
10570 msgstr ""
10571
10572 #. type: Plain text
10573 #: build/C/man2/vmsplice.2:97
10574 msgid ""
10575 "Currently has no effect for B<vmsplice>(), but may be implemented in the "
10576 "future; see B<splice>(2)."
10577 msgstr ""
10578
10579 #.  FIXME Explain the following line in a little more detail:
10580 #.  .... if we expect to later SPLICE_F_MOVE to the cache.
10581 #. type: Plain text
10582 #: build/C/man2/vmsplice.2:113
10583 msgid ""
10584 "The user pages are a gift to the kernel.  The application may not modify "
10585 "this memory ever, or page cache and on-disk data may differ.  Gifting pages "
10586 "to the kernel means that a subsequent B<splice>(2)  B<SPLICE_F_MOVE> can "
10587 "successfully move the pages; if this flag is not specified, then a "
10588 "subsequent B<splice>(2)  B<SPLICE_F_MOVE> must copy the pages.  Data must "
10589 "also be properly page aligned, both in memory and length."
10590 msgstr ""
10591
10592 #. type: Plain text
10593 #: build/C/man2/vmsplice.2:122
10594 msgid ""
10595 "Upon successful completion, B<vmsplice>()  returns the number of bytes "
10596 "transferred to the pipe.  On error, B<vmsplice>()  returns -1 and I<errno> "
10597 "is set to indicate the error."
10598 msgstr ""
10599
10600 #. type: Plain text
10601 #: build/C/man2/vmsplice.2:127
10602 msgid "I<fd> either not valid, or doesn't refer to a pipe."
10603 msgstr ""
10604
10605 #. type: Plain text
10606 #: build/C/man2/vmsplice.2:135
10607 msgid ""
10608 "I<nr_segs> is 0 or greater than B<IOV_MAX>; or memory not aligned if "
10609 "B<SPLICE_F_GIFT> set."
10610 msgstr ""
10611
10612 #. type: Plain text
10613 #: build/C/man2/vmsplice.2:143
10614 msgid ""
10615 "The B<vmsplice>()  system call first appeared in Linux 2.6.17; library "
10616 "support was added to glibc in version 2.5."
10617 msgstr ""
10618
10619 #. type: Plain text
10620 #: build/C/man2/vmsplice.2:154
10621 msgid ""
10622 "B<vmsplice>()  follows the other vectorized read/write type functions when "
10623 "it comes to limitations on number of segments being passed in.  This limit "
10624 "is B<IOV_MAX> as defined in I<E<lt>limits.hE<gt>>.  At the time of this "
10625 "writing, that limit is 1024."
10626 msgstr ""
10627
10628 #. type: Plain text
10629 #: build/C/man2/vmsplice.2:157
10630 msgid "B<splice>(2), B<tee>(2)"
10631 msgstr ""