talloc_debug - Man Page

Name

talloc_debug — The talloc debugging support functions

— To aid memory debugging, talloc contains routines to inspect the currently allocated memory hierarchy.  

Synopsis

Functions

_PUBLIC_ void talloc_report_depth_cb (const void *ptr, int depth, int max_depth, void(*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *private_data), void *private_data)
Walk a complete talloc hierarchy.
_PUBLIC_ void talloc_report_depth_file (const void *ptr, int depth, int max_depth, FILE *f)
Print a talloc hierarchy.
_PUBLIC_ void talloc_report_full (const void *ptr, FILE *f)
Print a summary report of all memory used by ptr.
_PUBLIC_ void talloc_report (const void *ptr, FILE *f)
Print a summary report of all memory used by ptr.
_PUBLIC_ void talloc_enable_null_tracking (void)
Enable tracking the use of NULL memory contexts.
_PUBLIC_ void talloc_enable_null_tracking_no_autofree (void)
Enable tracking the use of NULL memory contexts.
_PUBLIC_ void talloc_disable_null_tracking (void)
Disable tracking of the NULL memory context.
_PUBLIC_ void talloc_enable_leak_report (void)
Enable leak report when a program exits.
_PUBLIC_ void talloc_enable_leak_report_full (void)
Enable full leak report when a program exits.
_PUBLIC_ void talloc_set_abort_fn (void(*abort_fn)(const char *reason))
Set a custom 'abort' function that is called on serious error.
_PUBLIC_ void talloc_set_log_fn (void(*log_fn)(const char *message))
Set a logging function.
_PUBLIC_ void talloc_set_log_stderr (void)
Set stderr as the output for logs.
_PUBLIC_ int talloc_set_memlimit (const void *ctx, size_t max_size) _DEPRECATED_
Set a max memory limit for the current context hierarchy This affects all children of this context and constrain any allocation in the hierarchy to never exceed the limit set.

Detailed Description

To aid memory debugging, talloc contains routines to inspect the currently allocated memory hierarchy.

Function Documentation

_PUBLIC_ void talloc_disable_null_tracking (void)

Disable tracking of the NULL memory context. This disables tracking of the NULL memory context.

_PUBLIC_ void talloc_enable_leak_report (void)

Enable leak report when a program exits. This enables calling of talloc_report(NULL, stderr) when the program exits. In Samba4 this is enabled by using the --leak-report command line option.

For it to be useful, this function must be called before any other talloc function as it establishes a 'null context' that acts as the top of the tree. If you don't call this function first then passing NULL to talloc_report() or talloc_report_full() won't give you the full tree printout.

Here is a typical talloc report:

talloc report on 'null_context' (total 267 bytes in 15 blocks)
     libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
     libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
     iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
     libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
     iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
     iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
     iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks

_PUBLIC_ void talloc_enable_leak_report_full (void)

Enable full leak report when a program exits. This enables calling of talloc_report_full(NULL, stderr) when the program exits. In Samba4 this is enabled by using the --leak-report-full command line option.

For it to be useful, this function must be called before any other talloc function as it establishes a 'null context' that acts as the top of the tree. If you don't call this function first then passing NULL to talloc_report() or talloc_report_full() won't give you the full tree printout.

Here is a typical full report:

full talloc report on 'root' (total 18 bytes in 8 blocks)
     p1                             contains     18 bytes in   7 blocks (ref 0)
     r1                             contains     13 bytes in   2 blocks (ref 0)
     reference to: p2
     p2                             contains      1 bytes in   1 blocks (ref 1)
     x3                             contains      1 bytes in   1 blocks (ref 0)
     x2                             contains      1 bytes in   1 blocks (ref 0)
     x1                             contains      1 bytes in   1 blocks (ref 0)

_PUBLIC_ void talloc_enable_null_tracking (void)

Enable tracking the use of NULL memory contexts. This enables tracking of the NULL memory context without enabling leak reporting on exit. Useful for when you want to do your own leak reporting call via talloc_report_null_full();

_PUBLIC_ void talloc_enable_null_tracking_no_autofree (void)

Enable tracking the use of NULL memory contexts. This enables tracking of the NULL memory context without enabling leak reporting on exit. Useful for when you want to do your own leak reporting call via talloc_report_null_full();

_PUBLIC_ void talloc_report (const void * ptr, FILE * f)

Print a summary report of all memory used by ptr. This function prints a summary report of all memory used by ptr. One line of report is printed for each immediate child of ptr, showing the total memory and number of blocks used by that child.

You can pass NULL for the pointer, in which case a report is printed for the top level memory context, but only if talloc_enable_leak_report() or talloc_enable_leak_report_full() has been called.

Parameters

ptr The talloc chunk.
f The file handle to print to.

Example:

unsigned int *a, *b;
a = talloc(NULL, unsigned int);
b = talloc(a, unsigned int);
fprintf(stderr, "Summary of memory tree for a:0);
talloc_report(a, stderr);
See also

talloc_report_full()

_PUBLIC_ void talloc_report_depth_cb (const void * ptr, int depth, int max_depth, void(*)(const void *ptr, int depth, int max_depth, int is_ref, void *private_data) callback, void * private_data)

Walk a complete talloc hierarchy. This provides a more flexible reports than talloc_report(). It will recursively call the callback for the entire tree of memory referenced by the pointer. References in the tree are passed with is_ref = 1 and the pointer that is referenced.

You can pass NULL for the pointer, in which case a report is printed for the top level memory context, but only if talloc_enable_leak_report() or talloc_enable_leak_report_full() has been called.

The recursion is stopped when depth >= max_depth. max_depth = -1 means only stop at leaf nodes.

Parameters

ptr The talloc chunk.
depth Internal parameter to control recursion. Call with 0.
max_depth Maximum recursion level.
callback Function to be called on every chunk.
private_data Private pointer passed to callback.

_PUBLIC_ void talloc_report_depth_file (const void * ptr, int depth, int max_depth, FILE * f)

Print a talloc hierarchy. This provides a more flexible reports than talloc_report(). It will let you specify the depth and max_depth.

Parameters

ptr The talloc chunk.
depth Internal parameter to control recursion. Call with 0.
max_depth Maximum recursion level.
f The file handle to print to.

_PUBLIC_ void talloc_report_full (const void * ptr, FILE * f)

Print a summary report of all memory used by ptr. This provides a more detailed report than talloc_report(). It will recursively print the entire tree of memory referenced by the pointer. References in the tree are shown by giving the name of the pointer that is referenced.

You can pass NULL for the pointer, in which case a report is printed for the top level memory context, but only if talloc_enable_leak_report() or talloc_enable_leak_report_full() has been called.

Parameters

ptr The talloc chunk.
f The file handle to print to.

Example:

unsigned int *a, *b;
a = talloc(NULL, unsigned int);
b = talloc(a, unsigned int);
fprintf(stderr, "Dumping memory tree for a:0);
talloc_report_full(a, stderr);
See also

talloc_report()

_PUBLIC_ void talloc_set_abort_fn (void(*)(const char *reason) abort_fn)

Set a custom 'abort' function that is called on serious error. The default 'abort' function is abort().

The 'abort' function is called when:

  • talloc_get_type_abort() fails
  • the provided pointer is not a valid talloc context
  • when the context meta data are invalid
  • when access after free is detected

Example:

void my_abort(const char *reason)
{
     fprintf(stderr, "talloc abort: %s0, reason);
     abort();
}

     talloc_set_abort_fn(my_abort);
Parameters

abort_fn The new 'abort' function.

See also

talloc_set_log_fn()

talloc_get_type()

_PUBLIC_ void talloc_set_log_fn (void(*)(const char *message) log_fn)

Set a logging function.

Parameters

log_fn The logging function.

See also

talloc_set_log_stderr()

talloc_set_abort_fn()

_PUBLIC_ void talloc_set_log_stderr (void)

Set stderr as the output for logs.

See also

talloc_set_log_fn()

talloc_set_abort_fn()

_PUBLIC_ int talloc_set_memlimit (const void * ctx, size_t max_size)

Set a max memory limit for the current context hierarchy This affects all children of this context and constrain any allocation in the hierarchy to never exceed the limit set. The limit can be removed by setting 0 (unlimited) as the max_size by calling the function again on the same context. Memory limits can also be nested, meaning a child can have a stricter memory limit than a parent. Memory limits are enforced only at memory allocation time. Stealing a context into a 'limited' hierarchy properly updates memory usage but does not cause failure if the move causes the new parent to exceed its limits. However any further allocation on that hierarchy will then fail.

Warning

talloc memlimit functionality is deprecated. Please consider using cgroup memory limits instead.

Parameters

ctx The talloc context to set the limit on
max_size The (new) max_size

Author

Generated automatically by Doxygen for talloc from the source code.

Info

Tue Jan 26 2021 Version 2.0 talloc