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