talloc_debug man page

talloc_debug — The talloc debugging support functions

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

Functions

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.
void talloc_report_depth_file (const void *ptr, int depth, int max_depth, FILE *f)
Print a talloc hierarchy.
void talloc_report_full (const void *ptr, FILE *f)
Print a summary report of all memory used by ptr.
void talloc_report (const void *ptr, FILE *f)
Print a summary report of all memory used by ptr.
void talloc_enable_null_tracking (void)
Enable tracking the use of NULL memory contexts.
void talloc_enable_null_tracking_no_autofree (void)
Enable tracking the use of NULL memory contexts.
void talloc_disable_null_tracking (void)
Disable tracking of the NULL memory context.
void talloc_enable_leak_report (void)
Enable leak report when a program exits.
void talloc_enable_leak_report_full (void)
Enable full leak report when a program exits.
void talloc_set_abort_fn (void(*abort_fn)(const char *reason))
Set a custom 'abort' function that is called on serious error.
void talloc_set_log_fn (void(*log_fn)(const char *message))
Set a logging function.
void talloc_set_log_stderr (void)
Set stderr as the output for logs.
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.

Detailed Description

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

Function Documentation

void talloc_disable_null_tracking (void)

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

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:

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

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:

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

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();

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();

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:

1 unsigned int *a, *b;
2 a = talloc(NULL, unsigned int);
3 b = talloc(a, unsigned int);
4 fprintf(stderr, "Summary of memory tree for a:0);
5 talloc_report(a, stderr);

See also:

talloc_report_full()

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.

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.

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:

1 unsigned int *a, *b;
2 a = talloc(NULL, unsigned int);
3 b = talloc(a, unsigned int);
4 fprintf(stderr, "Dumping memory tree for a:0);
5 talloc_report_full(a, stderr);

See also:

talloc_report()

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:

1 void my_abort(const char *reason)
2 {
3      fprintf(stderr, "talloc abort: %s0, reason);
4      abort();
5 }
6 
7      talloc_set_abort_fn(my_abort);

Parameters:

abort_fn The new 'abort' function.

See also:

talloc_set_log_fn()

talloc_get_type()

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()

void talloc_set_log_stderr (void)

Set stderr as the output for logs.

See also:

talloc_set_log_fn()

talloc_set_abort_fn()

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 funciton again on the sam context. Memory limits can also be nested, meaning a hild 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.

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

Thu Jul 28 2016 Version 2.0 talloc