]>
Commit | Line | Data |
---|---|---|
3ea5be54 | 1 | @node Internal Probes |
5d28a896 | 2 | @c @node Internal Probes, Tunables, Dynamic Linker, Top |
3ea5be54 AO |
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 | |
7b3436d4 | 19 | * Non-local Goto Probes:: Probes in setjmp and longjmp |
3ea5be54 AO |
20 | @end menu |
21 | ||
22 | @node Memory Allocation Probes | |
23 | @section Memory Allocation Probes | |
24 | ||
25 | These probes are designed to signal relatively unusual situations within | |
4d84e6ad | 26 | the virtual memory subsystem of @theglibc{}. |
3ea5be54 | 27 | |
322dea08 AO |
28 | @deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2}) |
29 | This probe is triggered after the main arena is extended by calling | |
30 | @code{sbrk}. Argument @var{$arg1} is the additional size requested to | |
31 | @code{sbrk}, and @var{$arg2} is the pointer that marks the end of the | |
32 | @code{sbrk} area, returned in response to the request. | |
33 | @end deftp | |
34 | ||
35 | @deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2}) | |
36 | This probe is triggered after the size of the main arena is decreased by | |
37 | calling @code{sbrk}. Argument @var{$arg1} is the size released by | |
38 | @code{sbrk} (the positive value, rather than the negative value passed | |
39 | to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of | |
40 | the @code{sbrk} area, returned in response to the request. | |
41 | @end deftp | |
42 | ||
43 | @deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2}) | |
44 | This probe is triggered after a new heap is @code{mmap}ed. Argument | |
45 | @var{$arg1} is a pointer to the base of the memory area, where the | |
46 | @code{heap_info} data structure is held, and @var{$arg2} is the size of | |
47 | the heap. | |
48 | @end deftp | |
49 | ||
50 | @deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2}) | |
51 | This probe is triggered @emph{before} (unlike the other sbrk and heap | |
52 | probes) a heap is completely removed via @code{munmap}. Argument | |
53 | @var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the | |
54 | heap. | |
55 | @end deftp | |
56 | ||
57 | @deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2}) | |
58 | This probe is triggered after a trailing portion of an @code{mmap}ed | |
59 | heap is extended. Argument @var{$arg1} is a pointer to the heap, and | |
60 | @var{$arg2} is the new size of the heap. | |
61 | @end deftp | |
62 | ||
63 | @deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2}) | |
64 | This probe is triggered after a trailing portion of an @code{mmap}ed | |
65 | heap is released. Argument @var{$arg1} is a pointer to the heap, and | |
66 | @var{$arg2} is the new size of the heap. | |
67 | @end deftp | |
68 | ||
35fed6f1 AO |
69 | @deftp Probe memory_malloc_retry (size_t @var{$arg1}) |
70 | @deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2}) | |
71 | @deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2}) | |
35fed6f1 AO |
72 | @deftpx Probe memory_calloc_retry (size_t @var{$arg1}) |
73 | These probes are triggered when the corresponding functions fail to | |
74 | obtain the requested amount of memory from the arena in use, before they | |
75 | call @code{arena_get_retry} to select an alternate arena in which to | |
76 | retry the allocation. Argument @var{$arg1} is the amount of memory | |
77 | requested by the user; in the @code{calloc} case, that is the total size | |
78 | computed from both function arguments. In the @code{realloc} case, | |
79 | @var{$arg2} is the pointer to the memory area being resized. In the | |
80 | @code{memalign} case, @var{$arg2} is the alignment to be used for the | |
81 | request, which may be stricter than the value passed to the | |
10ad46bc OB |
82 | @code{memalign} function. A @code{memalign} probe is also used by functions |
83 | @code{posix_memalign, valloc} and @code{pvalloc}. | |
35fed6f1 AO |
84 | |
85 | Note that the argument order does @emph{not} match that of the | |
86 | corresponding two-argument functions, so that in all of these probes the | |
87 | user-requested allocation size is in @var{$arg1}. | |
88 | @end deftp | |
89 | ||
655673f3 AO |
90 | @deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2}) |
91 | This probe is triggered within @code{arena_get_retry} (the function | |
92 | called to select the alternate arena in which to retry an allocation | |
93 | that failed on the first attempt), before the selection of an alternate | |
94 | arena. This probe is redundant, but much easier to use when it's not | |
95 | important to determine which of the various memory allocation functions | |
96 | is failing to allocate on the first try. Argument @var{$arg1} is the | |
97 | same as in the function-specific probes, except for extra room for | |
98 | padding introduced by functions that have to ensure stricter alignment. | |
99 | Argument @var{$arg2} is the arena in which allocation failed. | |
100 | @end deftp | |
101 | ||
3ea5be54 AO |
102 | @deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2}) |
103 | This probe is triggered when @code{malloc} allocates and initializes an | |
104 | additional arena (not the main arena), but before the arena is assigned | |
105 | to the running thread or inserted into the internal linked list of | |
106 | arenas. The arena's @code{malloc_state} internal data structure is | |
107 | located at @var{$arg1}, within a newly-allocated heap big enough to hold | |
108 | at least @var{$arg2} bytes. | |
109 | @end deftp | |
110 | ||
6999d38c AO |
111 | @deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2}) |
112 | This probe is triggered when @code{malloc} has just selected an existing | |
113 | arena to reuse, and (temporarily) reserved it for exclusive use. | |
114 | Argument @var{$arg1} is a pointer to the newly-selected arena, and | |
115 | @var{$arg2} is a pointer to the arena previously used by that thread. | |
116 | ||
4d84e6ad | 117 | This occurs within |
6999d38c AO |
118 | @code{reused_arena}, right after the mutex mentioned in probe |
119 | @code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will | |
120 | point to the same arena. In this configuration, this will usually only | |
121 | occur once per thread. The exception is when a thread first selected | |
122 | the main arena, but a subsequent allocation from it fails: then, and | |
8e52276e | 123 | only then, may we switch to another arena to retry that allocation, and |
6999d38c | 124 | for further allocations within that thread. |
51942fca | 125 | @end deftp |
6999d38c | 126 | |
6999d38c AO |
127 | @deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3}) |
128 | This probe is triggered when @code{malloc} is about to wait for an arena | |
129 | to become available for reuse. Argument @var{$arg1} holds a pointer to | |
130 | the mutex the thread is going to wait on, @var{$arg2} is a pointer to a | |
131 | newly-chosen arena to be reused, and @var{$arg3} is a pointer to the | |
132 | arena previously used by that thread. | |
133 | ||
4d84e6ad | 134 | This occurs within |
6999d38c AO |
135 | @code{reused_arena}, when a thread first tries to allocate memory or |
136 | needs a retry after a failure to allocate from the main arena, there | |
137 | isn't any free arena, the maximum number of arenas has been reached, and | |
138 | an existing arena was chosen for reuse, but its mutex could not be | |
139 | immediately acquired. The mutex in @var{$arg1} is the mutex of the | |
140 | selected arena. | |
51942fca | 141 | @end deftp |
6999d38c | 142 | |
6999d38c AO |
143 | @deftp Probe memory_arena_reuse_free_list (void *@var{$arg1}) |
144 | This probe is triggered when @code{malloc} has chosen an arena that is | |
145 | in the free list for use by a thread, within the @code{get_free_list} | |
4d84e6ad | 146 | function. The argument @var{$arg1} holds a pointer to the selected arena. |
6999d38c AO |
147 | @end deftp |
148 | ||
3ea5be54 AO |
149 | @deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2}) |
150 | This probe is triggered when function @code{mallopt} is called to change | |
151 | @code{malloc} internal configuration parameters, before any change to | |
152 | the parameters is made. The arguments @var{$arg1} and @var{$arg2} are | |
153 | the ones passed to the @code{mallopt} function. | |
154 | @end deftp | |
0653427f AO |
155 | |
156 | @deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2}) | |
157 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
158 | when the parameter to be changed is @code{M_MXFAST}, and the requested | |
159 | value is in an acceptable range. Argument @var{$arg1} is the requested | |
160 | value, and @var{$arg2} is the previous value of this @code{malloc} | |
161 | parameter. | |
162 | @end deftp | |
163 | ||
164 | @deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) | |
8e52276e | 165 | This probe is triggered shortly after the @code{memory_mallopt} probe, |
0653427f AO |
166 | when the parameter to be changed is @code{M_TRIM_THRESHOLD}. Argument |
167 | @var{$arg1} is the requested value, @var{$arg2} is the previous value of | |
168 | this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic | |
169 | threshold adjustment was already disabled. | |
170 | @end deftp | |
171 | ||
172 | @deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) | |
173 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
174 | when the parameter to be changed is @code{M_TOP_PAD}. Argument | |
175 | @var{$arg1} is the requested value, @var{$arg2} is the previous value of | |
176 | this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic | |
177 | threshold adjustment was already disabled. | |
178 | @end deftp | |
179 | ||
180 | @deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) | |
181 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
182 | when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the | |
183 | requested value is in an acceptable range. Argument @var{$arg1} is the | |
184 | requested value, @var{$arg2} is the previous value of this @code{malloc} | |
185 | parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment | |
186 | was already disabled. | |
187 | @end deftp | |
188 | ||
189 | @deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3}) | |
190 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
191 | when the parameter to be changed is @code{M_MMAP_MAX}. Argument | |
192 | @var{$arg1} is the requested value, @var{$arg2} is the previous value of | |
193 | this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic | |
194 | threshold adjustment was already disabled. | |
195 | @end deftp | |
196 | ||
0653427f AO |
197 | @deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2}) |
198 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
199 | when the parameter to be changed is @code{M_PERTURB}. Argument | |
200 | @var{$arg1} is the requested value, and @var{$arg2} is the previous | |
201 | value of this @code{malloc} parameter. | |
202 | @end deftp | |
203 | ||
204 | @deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2}) | |
205 | This probe is triggered shortly after the @code{memory_mallopt} probe, | |
206 | when the parameter to be changed is @code{M_ARENA_TEST}, and the | |
207 | requested value is in an acceptable range. Argument @var{$arg1} is the | |
208 | requested value, and @var{$arg2} is the previous value of this | |
4d84e6ad | 209 | @code{malloc} parameter. |
0653427f AO |
210 | @end deftp |
211 | ||
212 | @deftp Probe memory_mallopt_arena_max (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_MAX}, 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 | |
4d84e6ad | 217 | @code{malloc} parameter. |
0653427f AO |
218 | @end deftp |
219 | ||
220 | @deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2}) | |
221 | This probe is triggered when function @code{free} decides to adjust the | |
222 | dynamic brk/mmap thresholds. Argument @var{$arg1} and @var{$arg2} are | |
223 | the adjusted mmap and trim thresholds, respectively. | |
224 | @end deftp | |
10e1cf6b | 225 | |
d5c3fafc DD |
226 | @deftp Probe memory_tunable_tcache_max_bytes (int @var{$arg1}, int @var{$arg2}) |
227 | This probe is triggered when the @code{glibc.malloc.tcache_max} | |
228 | tunable is set. Argument @var{$arg1} is the requested value, and | |
229 | @var{$arg2} is the previous value of this tunable. | |
230 | @end deftp | |
231 | ||
232 | @deftp Probe memory_tunable_tcache_count (int @var{$arg1}, int @var{$arg2}) | |
233 | This probe is triggered when the @code{glibc.malloc.tcache_count} | |
234 | tunable is set. Argument @var{$arg1} is the requested value, and | |
235 | @var{$arg2} is the previous value of this tunable. | |
236 | @end deftp | |
237 | ||
238 | @deftp Probe memory_tunable_tcache_unsorted_limit (int @var{$arg1}, int @var{$arg2}) | |
239 | This probe is triggered when the | |
240 | @code{glibc.malloc.tcache_unsorted_limit} tunable is set. Argument | |
241 | @var{$arg1} is the requested value, and @var{$arg2} is the previous | |
242 | value of this tunable. | |
243 | @end deftp | |
244 | ||
bcdaad21 DD |
245 | @deftp Probe memory_tcache_double_free (void *@var{$arg1}, int @var{$arg2}) |
246 | This probe is triggered when @code{free} determines that the memory | |
247 | being freed has probably already been freed, and resides in the | |
248 | per-thread cache. Note that there is an extremely unlikely chance | |
249 | that this probe will trigger due to random payload data remaining in | |
250 | the allocated memory matching the key used to detect double frees. | |
251 | This probe actually indicates that an expensive linear search of the | |
252 | tcache, looking for a double free, has happened. Argument @var{$arg1} | |
253 | is the memory location as passed to @code{free}, Argument @var{$arg2} | |
254 | is the tcache bin it resides in. | |
255 | @end deftp | |
256 | ||
7b3436d4 WN |
257 | @node Non-local Goto Probes |
258 | @section Non-local Goto Probes | |
259 | ||
260 | These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp}, | |
261 | @code{longjmp} or @code{siglongjmp}. | |
262 | ||
263 | @deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) | |
264 | This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is | |
265 | called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} | |
266 | passed as the first argument of @code{setjmp} or @code{sigsetjmp}, | |
267 | @var{$arg2} is the second argument of @code{sigsetjmp} or zero if this | |
268 | is a call to @code{setjmp} and @var{$arg3} is a pointer to the return | |
269 | address that will be stored in the @code{jmp_buf}. | |
270 | @end deftp | |
271 | ||
272 | @deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) | |
273 | This probe is triggered whenever @code{longjmp} or @code{siglongjmp} | |
cf822e3c | 274 | is called. Argument @var{$arg1} is a pointer to the @code{jmp_buf} |
7b3436d4 WN |
275 | passed as the first argument of @code{longjmp} or @code{siglongjmp}, |
276 | @var{$arg2} is the return value passed as the second argument of | |
277 | @code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to | |
278 | the return address @code{longjmp} or @code{siglongjmp} will return to. | |
279 | ||
280 | The @code{longjmp} probe is triggered at a point where the registers | |
281 | have not yet been restored to the values in the @code{jmp_buf} and | |
282 | unwinding will show a call stack including the caller of | |
283 | @code{longjmp} or @code{siglongjmp}. | |
284 | @end deftp | |
285 | ||
286 | @deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3}) | |
287 | This probe is triggered under the same conditions and with the same | |
288 | arguments as the @code{longjmp} probe. | |
289 | ||
290 | The @code{longjmp_target} probe is triggered at a point where the | |
291 | registers have been restored to the values in the @code{jmp_buf} and | |
292 | unwinding will show a call stack including the caller of @code{setjmp} | |
293 | or @code{sigsetjmp}. | |
294 | @end deftp |