Makeconfig: sandwich gnulib-tests between libc/ld linking of tests
[glibc.git] / manual / probes.texi
blob0ea560ed78bcfd7eb0905875bf83fb08d95b507a
1 @node Internal Probes
2 @c @node Internal Probes, Tunables, Threads, Top
3 @c %MENU% Probes to monitor libc internal behavior
4 @chapter Internal probes
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.
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.
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
23 @node Memory Allocation Probes
24 @section Memory Allocation Probes
26 These probes are designed to signal relatively unusual situations within
27 the virtual memory subsystem of @theglibc{}.
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
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
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
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
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
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
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}.
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
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
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
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.
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
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.
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
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
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
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
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
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
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
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
198 @deftp Probe memory_mallopt_perturb (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_PERTURB}.  Argument
201 @var{$arg1} is the requested value, and @var{$arg2} is the previous
202 value of this @code{malloc} parameter.
203 @end deftp
205 @deftp Probe memory_mallopt_arena_test (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_ARENA_TEST}, and the
208 requested value is in an acceptable range.  Argument @var{$arg1} is the
209 requested value, and @var{$arg2} is the previous value of this
210 @code{malloc} parameter.
211 @end deftp
213 @deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
214 This probe is triggered shortly after the @code{memory_mallopt} probe,
215 when the parameter to be changed is @code{M_ARENA_MAX}, and the
216 requested value is in an acceptable range.  Argument @var{$arg1} is the
217 requested value, and @var{$arg2} is the previous value of this
218 @code{malloc} parameter.
219 @end deftp
221 @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
222 This probe is triggered when function @code{free} decides to adjust the
223 dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
224 the adjusted mmap and trim thresholds, respectively.
225 @end deftp
227 @deftp Probe memory_tunable_tcache_max_bytes (int @var{$arg1}, int @var{$arg2})
228 This probe is triggered when the @code{glibc.malloc.tcache_max}
229 tunable is set.  Argument @var{$arg1} is the requested value, and
230 @var{$arg2} is the previous value of this tunable.
231 @end deftp
233 @deftp Probe memory_tunable_tcache_count (int @var{$arg1}, int @var{$arg2})
234 This probe is triggered when the @code{glibc.malloc.tcache_count}
235 tunable is set.  Argument @var{$arg1} is the requested value, and
236 @var{$arg2} is the previous value of this tunable.
237 @end deftp
239 @deftp Probe memory_tunable_tcache_unsorted_limit (int @var{$arg1}, int @var{$arg2})
240 This probe is triggered when the
241 @code{glibc.malloc.tcache_unsorted_limit} tunable is set.  Argument
242 @var{$arg1} is the requested value, and @var{$arg2} is the previous
243 value of this tunable.
244 @end deftp
246 @deftp Probe memory_tcache_double_free (void *@var{$arg1}, int @var{$arg2})
247 This probe is triggered when @code{free} determines that the memory
248 being freed has probably already been freed, and resides in the
249 per-thread cache.  Note that there is an extremely unlikely chance
250 that this probe will trigger due to random payload data remaining in
251 the allocated memory matching the key used to detect double frees.
252 This probe actually indicates that an expensive linear search of the
253 tcache, looking for a double free, has happened.  Argument @var{$arg1}
254 is the memory location as passed to @code{free}, Argument @var{$arg2}
255 is the tcache bin it resides in.
256 @end deftp
258 @node Mathematical Function Probes
259 @section Mathematical Function Probes
261 Some mathematical functions fall back to multiple precision arithmetic for
262 some inputs to get last bit precision for their return values.  This multiple
263 precision fallback is much slower than the default algorithms and may have a
264 significant impact on application performance.  The systemtap probe markers
265 described in this section may help you determine if your application calls
266 mathematical functions with inputs that may result in multiple-precision
267 arithmetic.
269 Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
270 precision in the mantissa of the multiple precision number.  Hence, a precision
271 level of 32 implies 768 bits of precision in the mantissa.
273 @deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
274 This probe is triggered when the @code{atan2} function is called with
275 an input that results in multiple precision computation.  Argument
276 @var{$arg1} is the precision with which computation succeeded.
277 Arguments @var{$arg2} and @var{$arg3} are inputs to the @code{atan2}
278 function and @var{$arg4} is the computed result.
279 @end deftp
281 @deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
282 This probe is triggered when the @code{atan} function is called with
283 an input that results in multiple precision computation and none of
284 the multiple precision computations result in an accurate result.
285 Argument @var{$arg1} is the maximum precision with which computations
286 were performed.  Arguments @var{$arg2} and @var{$arg3} are inputs to
287 the @code{atan2} function and @var{$arg4} is the computed result.
288 @end deftp
290 @deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
291 This probe is triggered when the @code{atan} function is called with
292 an input that results in multiple precision computation.  Argument
293 @var{$arg1} is the precision with which computation succeeded.
294 Argument @var{$arg2} is the input to the @code{atan} function and
295 @var{$arg3} is the computed result.
296 @end deftp
298 @deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
299 This probe is triggered when the @code{atan} function is called with
300 an input that results in multiple precision computation and none of
301 the multiple precision computations result in an accurate result.
302 Argument @var{$arg1} is the maximum precision with which computations
303 were performed.  Argument @var{$arg2} is the input to the @code{atan}
304 function and @var{$arg3} is the computed result.
305 @end deftp
307 @deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
308 This probe is triggered when the @code{tan} function is called with an
309 input that results in multiple precision computation with precision
310 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
311 is the computed result.
312 @end deftp
314 @deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
315 This probe is triggered when the @code{asin} function is called with
316 an input that results in multiple precision computation with precision
317 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
318 is the computed result.
319 @end deftp
321 @deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
322 This probe is triggered when the @code{acos} function is called with
323 an input that results in multiple precision computation with precision
324 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
325 is the computed result.
326 @end deftp
328 @deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
329 This probe is triggered when the @code{sin} function is called with an
330 input that results in multiple precision computation with precision
331 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
332 is the computed result.
333 @end deftp
335 @deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
336 This probe is triggered when the @code{cos} function is called with an
337 input that results in multiple precision computation with precision
338 32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
339 is the computed result.
340 @end deftp
342 @deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
343 This probe is triggered when the @code{sin} function is called with an
344 input that results in multiple precision computation with precision
345 32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
346 the error bound of @var{$arg1} and @var{$arg3} is the computed result.
347 @end deftp
349 @deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
350 This probe is triggered when the @code{cos} 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, @var{$arg2} is
353 the error bound of @var{$arg1} and @var{$arg3} is the computed result.
354 @end deftp
356 @node Non-local Goto Probes
357 @section Non-local Goto Probes
359 These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
360 @code{longjmp} or @code{siglongjmp}.
362 @deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
363 This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is
364 called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
365 passed as the first argument of @code{setjmp} or @code{sigsetjmp},
366 @var{$arg2} is the second argument of @code{sigsetjmp} or zero if this
367 is a call to @code{setjmp} and @var{$arg3} is a pointer to the return
368 address that will be stored in the @code{jmp_buf}.
369 @end deftp
371 @deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
372 This probe is triggered whenever @code{longjmp} or @code{siglongjmp}
373 is called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
374 passed as the first argument of @code{longjmp} or @code{siglongjmp},
375 @var{$arg2} is the return value passed as the second argument of
376 @code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to
377 the return address @code{longjmp} or @code{siglongjmp} will return to.
379 The @code{longjmp} probe is triggered at a point where the registers
380 have not yet been restored to the values in the @code{jmp_buf} and
381 unwinding will show a call stack including the caller of
382 @code{longjmp} or @code{siglongjmp}.
383 @end deftp
385 @deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
386 This probe is triggered under the same conditions and with the same
387 arguments as the @code{longjmp} probe.
389 The @code{longjmp_target} probe is triggered at a point where the
390 registers have been restored to the values in the @code{jmp_buf} and
391 unwinding will show a call stack including the caller of @code{setjmp}
392 or @code{sigsetjmp}.
393 @end deftp