Constify string parameters

[glibc.git] / manual / probes.texi

@node Internal Probes
@c @node Internal Probes, , POSIX Threads, Top
@c %MENU% Probes to monitor libc internal behavior
@chapter Internal probes

In order to aid in debugging and monitoring internal behavior,
@theglibc{} exposes nearly-zero-overhead SystemTap probes marked with
the @code{libc} provider.

These probes are not part of the @glibcadj{} stable ABI, and they are
subject to change or removal across releases.  Our only promise with
regard to them is that, if we find a need to remove or modify the
arguments of a probe, the modified probe will have a different name, so
that program monitors relying on the old probe will not get unexpected
arguments.

@menu
* Memory Allocation Probes::  Probes in the memory allocation subsystem
* Mathematical Function Probes::  Probes in mathematical functions
* Non-local Goto Probes::  Probes in setjmp and longjmp
@end menu

@node Memory Allocation Probes
@section Memory Allocation Probes

These probes are designed to signal relatively unusual situations within
the virtual memory subsystem of @theglibc{}.

@deftp Probe memory_sbrk_more (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered after the main arena is extended by calling
@code{sbrk}.  Argument @var{$arg1} is the additional size requested to
@code{sbrk}, and @var{$arg2} is the pointer that marks the end of the
@code{sbrk} area, returned in response to the request.
@end deftp

@deftp Probe memory_sbrk_less (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered after the size of the main arena is decreased by
calling @code{sbrk}.  Argument @var{$arg1} is the size released by
@code{sbrk} (the positive value, rather than the negative value passed
to @code{sbrk}), and @var{$arg2} is the pointer that marks the end of
the @code{sbrk} area, returned in response to the request.
@end deftp

@deftp Probe memory_heap_new (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered after a new heap is @code{mmap}ed.  Argument
@var{$arg1} is a pointer to the base of the memory area, where the
@code{heap_info} data structure is held, and @var{$arg2} is the size of
the heap.
@end deftp

@deftp Probe memory_heap_free (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered @emph{before} (unlike the other sbrk and heap
probes) a heap is completely removed via @code{munmap}.  Argument
@var{$arg1} is a pointer to the heap, and @var{$arg2} is the size of the
heap.
@end deftp

@deftp Probe memory_heap_more (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered after a trailing portion of an @code{mmap}ed
heap is extended.  Argument @var{$arg1} is a pointer to the heap, and
@var{$arg2} is the new size of the heap.
@end deftp

@deftp Probe memory_heap_less (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered after a trailing portion of an @code{mmap}ed
heap is released.  Argument @var{$arg1} is a pointer to the heap, and
@var{$arg2} is the new size of the heap.
@end deftp

@deftp Probe memory_malloc_retry (size_t @var{$arg1})
@deftpx Probe memory_realloc_retry (size_t @var{$arg1}, void *@var{$arg2})
@deftpx Probe memory_memalign_retry (size_t @var{$arg1}, size_t @var{$arg2})
@deftpx Probe memory_calloc_retry (size_t @var{$arg1})
These probes are triggered when the corresponding functions fail to
obtain the requested amount of memory from the arena in use, before they
call @code{arena_get_retry} to select an alternate arena in which to
retry the allocation.  Argument @var{$arg1} is the amount of memory
requested by the user; in the @code{calloc} case, that is the total size
computed from both function arguments.  In the @code{realloc} case,
@var{$arg2} is the pointer to the memory area being resized.  In the
@code{memalign} case, @var{$arg2} is the alignment to be used for the
request, which may be stricter than the value passed to the
@code{memalign} function.  A @code{memalign} probe is also used by functions
@code{posix_memalign, valloc} and @code{pvalloc}.

Note that the argument order does @emph{not} match that of the
corresponding two-argument functions, so that in all of these probes the
user-requested allocation size is in @var{$arg1}.
@end deftp

@deftp Probe memory_arena_retry (size_t @var{$arg1}, void *@var{$arg2})
This probe is triggered within @code{arena_get_retry} (the function
called to select the alternate arena in which to retry an allocation
that failed on the first attempt), before the selection of an alternate
arena.  This probe is redundant, but much easier to use when it's not
important to determine which of the various memory allocation functions
is failing to allocate on the first try.  Argument @var{$arg1} is the
same as in the function-specific probes, except for extra room for
padding introduced by functions that have to ensure stricter alignment.
Argument @var{$arg2} is the arena in which allocation failed.
@end deftp

@deftp Probe memory_arena_new (void *@var{$arg1}, size_t @var{$arg2})
This probe is triggered when @code{malloc} allocates and initializes an
additional arena (not the main arena), but before the arena is assigned
to the running thread or inserted into the internal linked list of
arenas.  The arena's @code{malloc_state} internal data structure is
located at @var{$arg1}, within a newly-allocated heap big enough to hold
at least @var{$arg2} bytes.
@end deftp

@deftp Probe memory_arena_reuse (void *@var{$arg1}, void *@var{$arg2})
This probe is triggered when @code{malloc} has just selected an existing
arena to reuse, and (temporarily) reserved it for exclusive use.
Argument @var{$arg1} is a pointer to the newly-selected arena, and
@var{$arg2} is a pointer to the arena previously used by that thread.

This occurs within
@code{reused_arena}, right after the mutex mentioned in probe
@code{memory_arena_reuse_wait} is acquired; argument @var{$arg1} will
point to the same arena.  In this configuration, this will usually only
occur once per thread.  The exception is when a thread first selected
the main arena, but a subsequent allocation from it fails: then, and
only then, may we switch to another arena to retry that allocations, and
for further allocations within that thread.
@end deftp

@deftp Probe memory_arena_reuse_wait (void *@var{$arg1}, void *@var{$arg2}, void *@var{$arg3})
This probe is triggered when @code{malloc} is about to wait for an arena
to become available for reuse.  Argument @var{$arg1} holds a pointer to
the mutex the thread is going to wait on, @var{$arg2} is a pointer to a
newly-chosen arena to be reused, and @var{$arg3} is a pointer to the
arena previously used by that thread.

This occurs within
@code{reused_arena}, when a thread first tries to allocate memory or
needs a retry after a failure to allocate from the main arena, there
isn't any free arena, the maximum number of arenas has been reached, and
an existing arena was chosen for reuse, but its mutex could not be
immediately acquired.  The mutex in @var{$arg1} is the mutex of the
selected arena.
@end deftp

@deftp Probe memory_arena_reuse_free_list (void *@var{$arg1})
This probe is triggered when @code{malloc} has chosen an arena that is
in the free list for use by a thread, within the @code{get_free_list}
function.  The argument @var{$arg1} holds a pointer to the selected arena.
@end deftp

@deftp Probe memory_mallopt (int @var{$arg1}, int @var{$arg2})
This probe is triggered when function @code{mallopt} is called to change
@code{malloc} internal configuration parameters, before any change to
the parameters is made.  The arguments @var{$arg1} and @var{$arg2} are
the ones passed to the @code{mallopt} function.
@end deftp

@deftp Probe memory_mallopt_mxfast (int @var{$arg1}, int @var{$arg2})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_MXFAST}, and the requested
value is in an acceptable range.  Argument @var{$arg1} is the requested
value, and @var{$arg2} is the previous value of this @code{malloc}
parameter.
@end deftp

@deftp Probe memory_mallopt_trim_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
This probe is triggere shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_TRIM_THRESHOLD}.  Argument
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
threshold adjustment was already disabled.
@end deftp

@deftp Probe memory_mallopt_top_pad (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_TOP_PAD}.  Argument
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
threshold adjustment was already disabled.
@end deftp

@deftp Probe memory_mallopt_mmap_threshold (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_MMAP_THRESHOLD}, and the
requested value is in an acceptable range.  Argument @var{$arg1} is the
requested value, @var{$arg2} is the previous value of this @code{malloc}
parameter, and @var{$arg3} is nonzero if dynamic threshold adjustment
was already disabled.
@end deftp

@deftp Probe memory_mallopt_mmap_max (int @var{$arg1}, int @var{$arg2}, int @var{$arg3})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_MMAP_MAX}.  Argument
@var{$arg1} is the requested value, @var{$arg2} is the previous value of
this @code{malloc} parameter, and @var{$arg3} is nonzero if dynamic
threshold adjustment was already disabled.
@end deftp

@deftp Probe memory_mallopt_check_action (int @var{$arg1}, int @var{$arg2})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_CHECK_ACTION}.  Argument
@var{$arg1} is the requested value, and @var{$arg2} is the previous
value of this @code{malloc} parameter.
@end deftp

@deftp Probe memory_mallopt_perturb (int @var{$arg1}, int @var{$arg2})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_PERTURB}.  Argument
@var{$arg1} is the requested value, and @var{$arg2} is the previous
value of this @code{malloc} parameter.
@end deftp

@deftp Probe memory_mallopt_arena_test (int @var{$arg1}, int @var{$arg2})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_ARENA_TEST}, and the
requested value is in an acceptable range.  Argument @var{$arg1} is the
requested value, and @var{$arg2} is the previous value of this
@code{malloc} parameter.
@end deftp

@deftp Probe memory_mallopt_arena_max (int @var{$arg1}, int @var{$arg2})
This probe is triggered shortly after the @code{memory_mallopt} probe,
when the parameter to be changed is @code{M_ARENA_MAX}, and the
requested value is in an acceptable range.  Argument @var{$arg1} is the
requested value, and @var{$arg2} is the previous value of this
@code{malloc} parameter.
@end deftp

@deftp Probe memory_mallopt_free_dyn_thresholds (int @var{$arg1}, int @var{$arg2})
This probe is triggered when function @code{free} decides to adjust the
dynamic brk/mmap thresholds.  Argument @var{$arg1} and @var{$arg2} are
the adjusted mmap and trim thresholds, respectively.
@end deftp

@node Mathematical Function Probes
@section Mathematical Function Probes

Some mathematical functions fall back to multiple precision arithmetic for
some inputs to get last bit precision for their return values.  This multiple
precision fallback is much slower than the default algorithms and may have a
significant impact on application performance.  The systemtap probe markers
described in this section may help you determine if your application calls
mathematical functions with inputs that may result in multiple-precision
arithmetic.

Unless explicitly mentioned otherwise, a precision of 1 implies 24 bits of
precision in the mantissa of the multiple precision number.  Hence, a precision
level of 32 implies 768 bits of precision in the mantissa.

@deftp Probe slowexp_p6 (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{exp} function is called with an
input that results in multiple precision computation with precision
6.  Argument @var{$arg1} is the input value and @var{$arg2} is the
computed output.
@end deftp

@deftp Probe slowexp_p32 (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{exp} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input value and @var{$arg2} is the
computed output.
@end deftp

@deftp Probe slowpow_p10 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
This probe is triggered when the @code{pow} function is called with
inputs that result in multiple precision computation with precision
10.  Arguments @var{$arg1} and @var{$arg2} are the input values,
@code{$arg3} is the value computed in the fast phase of the algorithm
and @code{$arg4} is the final accurate value.
@end deftp

@deftp Probe slowpow_p32 (double @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
This probe is triggered when the @code{pow} function is called with an
input that results in multiple precision computation with precision
32.  Arguments @var{$arg1} and @var{$arg2} are the input values,
@code{$arg3} is the value computed in the fast phase of the algorithm
and @code{$arg4} is the final accurate value.
@end deftp

@deftp Probe slowlog (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{log} function is called with an
input that results in multiple precision computation.  Argument
@var{$arg1} is the precision with which the computation succeeded.
Argument @var{$arg2} is the input and @var{$arg3} is the computed
output.
@end deftp

@deftp Probe slowlog_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{log} function is called with an
input that results in multiple precision computation and none of the
multiple precision computations result in an accurate result.
Argument @var{$arg1} is the maximum precision with which computations
were performed.  Argument @var{$arg2} is the input and @var{$arg3} is
the computed output.
@end deftp

@deftp Probe slowatan2 (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
This probe is triggered when the @code{atan2} function is called with
an input that results in multiple precision computation.  Argument
@var{$arg1} is the precision with which computation succeeded.
Arguments @var{$arg2} and @var{$arg3} are inputs to the @code{atan2}
function and @var{$arg4} is the computed result.
@end deftp

@deftp Probe slowatan2_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3}, double @var{$arg4})
This probe is triggered when the @code{atan} function is called with
an input that results in multiple precision computation and none of
the multiple precision computations result in an accurate result.
Argument @var{$arg1} is the maximum precision with which computations
were performed.  Arguments @var{$arg2} and @var{$arg3} are inputs to
the @code{atan2} function and @var{$arg4} is the computed result.
@end deftp

@deftp Probe slowatan (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{atan} function is called with
an input that results in multiple precision computation.  Argument
@var{$arg1} is the precision with which computation succeeded.
Argument @var{$arg2} is the input to the @code{atan} function and
@var{$arg3} is the computed result.
@end deftp

@deftp Probe slowatan_inexact (int @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{atan} function is called with
an input that results in multiple precision computation and none of
the multiple precision computations result in an accurate result.
Argument @var{$arg1} is the maximum precision with which computations
were performed.  Argument @var{$arg2} is the input to the @code{atan}
function and @var{$arg3} is the computed result.
@end deftp

@deftp Probe slowtan (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{tan} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
is the computed result.
@end deftp

@deftp Probe slowasin (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{asin} function is called with
an input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
is the computed result.
@end deftp

@deftp Probe slowacos (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{acos} function is called with
an input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
is the computed result.
@end deftp

@deftp Probe slowsin (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{sin} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
is the computed result.
@end deftp

@deftp Probe slowcos (double @var{$arg1}, double @var{$arg2})
This probe is triggered when the @code{cos} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function and @var{$arg2}
is the computed result.
@end deftp

@deftp Probe slowsin_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{sin} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
the error bound of @var{$arg1} and @var{$arg3} is the computed result.
@end deftp

@deftp Probe slowcos_dx (double @var{$arg1}, double @var{$arg2}, double @var{$arg3})
This probe is triggered when the @code{cos} function is called with an
input that results in multiple precision computation with precision
32.  Argument @var{$arg1} is the input to the function, @var{$arg2} is
the error bound of @var{$arg1} and @var{$arg3} is the computed result.
@end deftp

@node Non-local Goto Probes
@section Non-local Goto Probes

These probes are used to signal calls to @code{setjmp}, @code{sigsetjmp},
@code{longjmp} or @code{siglongjmp}.

@deftp Probe setjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
This probe is triggered whenever @code{setjmp} or @code{sigsetjmp} is
called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
passed as the first argument of @code{setjmp} or @code{sigsetjmp},
@var{$arg2} is the second argument of @code{sigsetjmp} or zero if this
is a call to @code{setjmp} and @var{$arg3} is a pointer to the return
address that will be stored in the @code{jmp_buf}.
@end deftp

@deftp Probe longjmp (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
This probe is triggered whenever @code{longjmp} or @code{siglongjmp}
is called.  Argument @var{$arg1} is a pointer to the @code{jmp_buf}
passed as the first argument of @code{longjmp} or @code{siglongjmp},
@var{$arg2} is the return value passed as the second argument of
@code{longjmp} or @code{siglongjmp} and @var{$arg3} is a pointer to
the return address @code{longjmp} or @code{siglongjmp} will return to.

The @code{longjmp} probe is triggered at a point where the registers
have not yet been restored to the values in the @code{jmp_buf} and
unwinding will show a call stack including the caller of
@code{longjmp} or @code{siglongjmp}.
@end deftp

@deftp Probe longjmp_target (void *@var{$arg1}, int @var{$arg2}, void *@var{$arg3})
This probe is triggered under the same conditions and with the same
arguments as the @code{longjmp} probe.

The @code{longjmp_target} probe is triggered at a point where the
registers have been restored to the values in the @code{jmp_buf} and
unwinding will show a call stack including the caller of @code{setjmp}
or @code{sigsetjmp}.
@end deftp