manual/probes.texi

   1 @node Internal Probes
   2 @c @node Internal Probes, Tunables, POSIX Threads, Top
   3 @c %MENU% Probes to monitor libc internal behavior
   4 @chapter Internal probes
   5
   6 In order to aid in debugging and monitoring internal behavior,
   7 @theglibc{} exposes nearly-zero-overhead SystemTap probes marked with
   8 the @code{libc} provider.
   9
  10 These probes are not part of the @glibcadj{} stable ABI, and they are
  11 subject to change or removal across releases.  Our only promise with
  12 regard to them is that, if we find a need to remove or modify the
  13 arguments of a probe, the modified probe will have a different name, so
  14 that program monitors relying on the old probe will not get unexpected
  15 arguments.
  16
  17 @menu
  18 * Memory Allocation Probes::  Probes in the memory allocation subsystem
  19 * Mathematical Function Probes::  Probes in mathematical functions
  20 * Non-local Goto Probes::  Probes in setjmp and longjmp
  21 @end menu
  22
  23 @node Memory Allocation Probes
  24 @section Memory Allocation Probes
  25
  26 These probes are designed to signal relatively unusual situations within
  27 the virtual memory subsystem of @theglibc{}.
  28
  29 @deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2})
  30 This probe is triggered after the main arena is extended by calling
  31 @code{sbrk}.  Argument @var{$arg1} is the additional size requested to
  32 @code{sbrk}, and @var{$arg2} is the pointer that marks the end of the
  33 @code{sbrk} area, returned in response to the request.
  34 @end deftp
  35
  36 @deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2})
  37 This probe is triggered after the size of the main arena is decreased by
  38 calling @code{sbrk}.  Argument @var{$arg1} is the size released by
  39 @code{sbrk} (the positive value, rather than the negative value passed
  40 to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of
  41 the @code{sbrk} area, returned in response to the request.
  42 @end deftp
  43
  44 @deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2})
  45 This probe is triggered after a new heap is @code{mmap}ed.  Argument
  46 @var{$arg1} is a pointer to the base of the memory area, where the
  47 @code{heap_info} data structure is held, and @var{$arg2} is the size of
  48 the heap.
  49 @end deftp
  50
  51 @deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2})
  52 This probe is triggered @emph{before} (unlike the other sbrk and heap
  53 probes) a heap is completely removed via @code{munmap}.  Argument
  54 @var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the
  55 heap.
  56 @end deftp
  57
  58 @deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2})
  59 This probe is triggered after a trailing portion of an @code{mmap}ed
  60 heap is extended.  Argument @var{$arg1} is a pointer to the heap, and
  61 @var{$arg2} is the new size of the heap.
  62 @end deftp
  63
  64 @deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2})
  65 This probe is triggered after a trailing portion of an @code{mmap}ed
  66 heap is released.  Argument @var{$arg1} is a pointer to the heap, and
  67 @var{$arg2} is the new size of the heap.
  68 @end deftp
  69
  70 @deftp Probe memory_malloc_retry (size_t @var{$arg1})
  71 @deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2})
  72 @deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2})
  73 @deftpx Probe memory_calloc_retry (size_t @var{$arg1})
  74 These probes are triggered when the corresponding functions fail to
  75 obtain the requested amount of memory from the arena in use, before they
  76 call @code{arena_get_retry} to select an alternate arena in which to
  77 retry the allocation.  Argument @var{$arg1} is the amount of memory
  78 requested by the user; in the @code{calloc} case, that is the total size
  79 computed from both function arguments.  In the @code{realloc} case,
  80 @var{$arg2} is the pointer to the memory area being resized.  In the
  81 @code{memalign} case, @var{$arg2} is the alignment to be used for the
  82 request, which may be stricter than the value passed to the
  83 @code{memalign} function.  A @code{memalign} probe is also used by functions
  84 @code{posix_memalign, valloc} and @code{pvalloc}.
  85
  86 Note that the argument order does @emph{not} match that of the
  87 corresponding two-argument functions, so that in all of these probes the
  88 user-requested allocation size is in @var{$arg1}.
  89 @end deftp
  90
  91 @deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
  92 This probe is triggered within @code{arena_get_retry} (the function
  93 called to select the alternate arena in which to retry an allocation
  94 that failed on the first attempt), before the selection of an alternate
  95 arena.  This probe is redundant, but much easier to use when it's not
  96 important to determine which of the various memory allocation functions
  97 is failing to allocate on the first try.  Argument @var{$arg1} is the
  98 same as in the function-specific probes, except for extra room for
  99 padding introduced by functions that have to ensure stricter alignment.
 100 Argument @var{$arg2} is the arena in which allocation failed.
 101 @end deftp
 102
 103 @deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
 104 This probe is triggered when @code{malloc} allocates and initializes an
 105 additional arena (not the main arena), but before the arena is assigned
 106 to the running thread or inserted into the internal linked list of
 107 arenas.  The arena's @code{malloc_state} internal data structure is
 108 located at @var{$arg1}, within a newly-allocated heap big enough to hold
 109 at least @var{$arg2} bytes.
 110 @end deftp
 111
 112 @deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
 113 This probe is triggered when @code{malloc} has just selected an existing
 114 arena to reuse, and (temporarily) reserved it for exclusive use.
 115 Argument @var{$arg1} is a pointer to the newly-selected arena, and
 116 @var{$arg2} is a pointer to the arena previously used by that thread.
 117
 118 This occurs within
 119 @code{reused_arena}, right after the mutex mentioned in probe
 120 @code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
 121 point to the same arena.  In this configuration, this will usually only
 122 occur once per thread.  The exception is when a thread first selected
 123 the main arena, but a subsequent allocation from it fails: then, and
 124 only then, may we switch to another arena to retry that allocation, and
 125 for further allocations within that thread.
 126 @end deftp
 127
 128 @deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
 129 This probe is triggered when @code{malloc} is about to wait for an arena
 130 to become available for reuse.  Argument @var{$arg1} holds a pointer to
 131 the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
 132 newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
 133 arena previously used by that thread.
 134
 135 This occurs within
 136 @code{reused_arena}, when a thread first tries to allocate memory or
 137 needs a retry after a failure to allocate from the main arena, there
 138 isn't any free arena, the maximum number of arenas has been reached, and
 139 an existing arena was chosen for reuse, but its mutex could not be
 140 immediately acquired.  The mutex in @var{$arg1} is the mutex of the
 141 selected arena.
 142 @end deftp
 143
 144 @deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
 145 This probe is triggered when @code{malloc} has chosen an arena that is
 146 in the free list for use by a thread, within the @code{get_free_list}
 147 function.  The argument @var{$arg1} holds a pointer to the selected arena.
 148 @end deftp
 149
 150 @deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
 151 This probe is triggered when function @code{mallopt} is called to change
 152 @code{malloc} internal configuration parameters, before any change to
 153 the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
 154 the ones passed to the @code{mallopt} function.
 155 @end deftp
 156
 157 @deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
 158 This probe is triggered shortly after the @code{memory_mallopt} probe,
 159 when the parameter to be changed is @code{M_MXFAST}, and the requested
 160 value is in an acceptable range.  Argument @var{$arg1} is the requested
 161 value, and @var{$arg2} is the previous value of this @code{malloc}
 162 parameter.
 163 @end deftp
 164
 165 @deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 166 This probe is triggered shortly after the @code{memory_mallopt} probe,
 167 when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
 168 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 169 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 170 threshold adjustment was already disabled.
 171 @end deftp
 172
 173 @deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 174 This probe is triggered shortly after the @code{memory_mallopt} probe,
 175 when the parameter to be changed is @code{M_TOP_PAD}.  Argument
 176 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 177 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 178 threshold adjustment was already disabled.
 179 @end deftp
 180
 181 @deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 182 This probe is triggered shortly after the @code{memory_mallopt} probe,
 183 when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
 184 requested value is in an acceptable range.  Argument @var{$arg1} is the
 185 requested value, @var{$arg2} is the previous value of this @code{malloc}
 186 parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
 187 was already disabled.
 188 @end deftp
 189
 190 @deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
 191 This probe is triggered shortly after the @code{memory_mallopt} probe,
 192 when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
 193 @var{$arg1} is the requested value, @var{$arg2} is the previous value of
 194 this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
 195 threshold adjustment was already disabled.
 196 @end deftp
 197
 198 @deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
 199 This probe is triggered shortly after the @code{memory_mallopt} probe,
 200 when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
 201 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 202 value of this @code{malloc} parameter.
 203 @end deftp
 204
 205 @deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
 206 This probe is triggered shortly after the @code{memory_mallopt} probe,
 207 when the parameter to be changed is @code{M_PERTURB}.  Argument
 208 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 209 value of this @code{malloc} parameter.
 210 @end deftp
 211
 212 @deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
 213 This probe is triggered shortly after the @code{memory_mallopt} probe,
 214 when the parameter to be changed is @code{M_ARENA_TEST}, and the
 215 requested value is in an acceptable range.  Argument @var{$arg1} is the
 216 requested value, and @var{$arg2} is the previous value of this
 217 @code{malloc} parameter.
 218 @end deftp
 219
 220 @deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
 221 This probe is triggered shortly after the @code{memory_mallopt} probe,
 222 when the parameter to be changed is @code{M_ARENA_MAX}, and the
 223 requested value is in an acceptable range.  Argument @var{$arg1} is the
 224 requested value, and @var{$arg2} is the previous value of this
 225 @code{malloc} parameter.
 226 @end deftp
 227
 228 @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
 229 This probe is triggered when function @code{free} decides to adjust the
 230 dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
 231 the adjusted mmap and trim thresholds, respectively.
 232 @end deftp
 233
 234 @deftp Probe memory_tunable_tcache_max_bytes (int @var{$arg1}, int @var{$arg2})
 235 This probe is triggered when the @code{glibc.malloc.tcache_max}
 236 tunable is set.  Argument @var{$arg1} is the requested value, and
 237 @var{$arg2} is the previous value of this tunable.
 238 @end deftp
 239
 240 @deftp Probe memory_tunable_tcache_count (int @var{$arg1}, int @var{$arg2})
 241 This probe is triggered when the @code{glibc.malloc.tcache_count}
 242 tunable is set.  Argument @var{$arg1} is the requested value, and
 243 @var{$arg2} is the previous value of this tunable.
 244 @end deftp
 245
 246 @deftp Probe memory_tunable_tcache_unsorted_limit (int @var{$arg1}, int @var{$arg2})
 247 This probe is triggered when the
 248 @code{glibc.malloc.tcache_unsorted_limit} tunable is set.  Argument
 249 @var{$arg1} is the requested value, and @var{$arg2} is the previous
 250 value of this tunable.
 251 @end deftp
 252
 253 @node Mathematical Function Probes
 254 @section Mathematical Function Probes
 255
 256 Some mathematical functions fall back to multiple precision arithmetic for
 257 some inputs to get last bit precision for their return values.  This multiple
 258 precision fallback is much slower than the default algorithms and may have a
 259 significant impact on application performance.  The systemtap probe markers
 260 described in this section may help you determine if your application calls
 261 mathematical functions with inputs that may result in multiple-precision
 262 arithmetic.
 263
 264 Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
 265 precision in the mantissa of the multiple precision number.  Hence, a precision
 266 level of 32 implies 768 bits of precision in the mantissa.
 267
 268 @deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
 269 This probe is triggered when the @code{exp} function is called with an
 270 input that results in multiple precision computation with precision
 271 6.  Argument @var{$arg1} is the input value and @var{$arg2} is the
 272 computed output.
 273 @end deftp
 274
 275 @deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
 276 This probe is triggered when the @code{exp} function is called with an
 277 input that results in multiple precision computation with precision
 278 32.  Argument @var{$arg1} is the input value and @var{$arg2} is the
 279 computed output.
 280 @end deftp
 281
 282 @deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 283 This probe is triggered when the @code{pow} function is called with
 284 inputs that result in multiple precision computation with precision
 285 10.  Arguments @var{$arg1} and @var{$arg2} are the input values,
 286 @code{$arg3} is the value computed in the fast phase of the algorithm
 287 and @code{$arg4} is the final accurate value.
 288 @end deftp
 289
 290 @deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 291 This probe is triggered when the @code{pow} function is called with an
 292 input that results in multiple precision computation with precision
 293 32.  Arguments @var{$arg1} and @var{$arg2} are the input values,
 294 @code{$arg3} is the value computed in the fast phase of the algorithm
 295 and @code{$arg4} is the final accurate value.
 296 @end deftp
 297
 298 @deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 299 This probe is triggered when the @code{log} function is called with an
 300 input that results in multiple precision computation.  Argument
 301 @var{$arg1} is the precision with which the computation succeeded.
 302 Argument @var{$arg2} is the input and @var{$arg3} is the computed
 303 output.
 304 @end deftp
 305
 306 @deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 307 This probe is triggered when the @code{log} function is called with an
 308 input that results in multiple precision computation and none of the
 309 multiple precision computations result in an accurate result.
 310 Argument @var{$arg1} is the maximum precision with which computations
 311 were performed.  Argument @var{$arg2} is the input and @var{$arg3} is
 312 the computed output.
 313 @end deftp
 314
 315 @deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 316 This probe is triggered when the @code{atan2} function is called with
 317 an input that results in multiple precision computation.  Argument
 318 @var{$arg1} is the precision with which computation succeeded.
 319 Arguments @var{$arg2} and @var{$arg3} are inputs to the @code{atan2}
 320 function and @var{$arg4} is the computed result.
 321 @end deftp
 322
 323 @deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
 324 This probe is triggered when the @code{atan} function is called with
 325 an input that results in multiple precision computation and none of
 326 the multiple precision computations result in an accurate result.
 327 Argument @var{$arg1} is the maximum precision with which computations
 328 were performed.  Arguments @var{$arg2} and @var{$arg3} are inputs to
 329 the @code{atan2} function and @var{$arg4} is the computed result.
 330 @end deftp
 331
 332 @deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 333 This probe is triggered when the @code{atan} function is called with
 334 an input that results in multiple precision computation.  Argument
 335 @var{$arg1} is the precision with which computation succeeded.
 336 Argument @var{$arg2} is the input to the @code{atan} function and
 337 @var{$arg3} is the computed result.
 338 @end deftp
 339
 340 @deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 341 This probe is triggered when the @code{atan} function is called with
 342 an input that results in multiple precision computation and none of
 343 the multiple precision computations result in an accurate result.
 344 Argument @var{$arg1} is the maximum precision with which computations
 345 were performed.  Argument @var{$arg2} is the input to the @code{atan}
 346 function and @var{$arg3} is the computed result.
 347 @end deftp
 348
 349 @deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
 350 This probe is triggered when the @code{tan} function is called with an
 351 input that results in multiple precision computation with precision
 352 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
 353 is the computed result.
 354 @end deftp
 355
 356 @deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
 357 This probe is triggered when the @code{asin} function is called with
 358 an input that results in multiple precision computation with precision
 359 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
 360 is the computed result.
 361 @end deftp
 362
 363 @deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
 364 This probe is triggered when the @code{acos} function is called with
 365 an input that results in multiple precision computation with precision
 366 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
 367 is the computed result.
 368 @end deftp
 369
 370 @deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
 371 This probe is triggered when the @code{sin} function is called with an
 372 input that results in multiple precision computation with precision
 373 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
 374 is the computed result.
 375 @end deftp
 376
 377 @deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
 378 This probe is triggered when the @code{cos} function is called with an
 379 input that results in multiple precision computation with precision
 380 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
 381 is the computed result.
 382 @end deftp
 383
 384 @deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 385 This probe is triggered when the @code{sin} function is called with an
 386 input that results in multiple precision computation with precision
 387 32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
 388 the error bound of @var{$arg1} and @var{$arg3} is the computed result.
 389 @end deftp
 390
 391 @deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
 392 This probe is triggered when the @code{cos} function is called with an
 393 input that results in multiple precision computation with precision
 394 32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
 395 the error bound of @var{$arg1} and @var{$arg3} is the computed result.
 396 @end deftp
 397
 398 @node Non-local Goto Probes
 399 @section Non-local Goto Probes
 400
 401 These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
 402 @code{longjmp} or @code{siglongjmp}.
 403
 404 @deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
 405 This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is
 406 called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
 407 passed as the first argument of @code{setjmp} or @code{sigsetjmp},
 408 @var{$arg2} is the second argument of @code{sigsetjmp} or zero if this
 409 is a call to @code{setjmp} and @var{$arg3} is a pointer to the return
 410 address that will be stored in the @code{jmp_buf}.
 411 @end deftp
 412
 413 @deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
 414 This probe is triggered whenever @code{longjmp} or @code{siglongjmp}
 415 is called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
 416 passed as the first argument of @code{longjmp} or @code{siglongjmp},
 417 @var{$arg2} is the return value passed as the second argument of
 418 @code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to
 419 the return address @code{longjmp} or @code{siglongjmp} will return to.
 420
 421 The @code{longjmp} probe is triggered at a point where the registers
 422 have not yet been restored to the values in the @code{jmp_buf} and
 423 unwinding will show a call stack including the caller of
 424 @code{longjmp} or @code{siglongjmp}.
 425 @end deftp
 426
 427 @deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
 428 This probe is triggered under the same conditions and with the same
 429 arguments as the @code{longjmp} probe.
 430
 431 The @code{longjmp_target} probe is triggered at a point where the
 432 registers have been restored to the values in the @code{jmp_buf} and
 433 unwinding will show a call stack including the caller of @code{setjmp}
 434 or @code{sigsetjmp}.
 435 @end deftp