talloc_debug(3)

💖 talloc_debug — the talloc debugging support functions 💖

okay bestie, welcome to talloc_debug(3), a page from the Library Functions Manual 🌸. this is the part of talloc where we stop just allocating stuff and start investigating it like the little detective main characters we are 🔍✨

so basically: to aid memory debugging, talloc contains routines to inspect the currently allocated memory hierarchy. that's the whole vibe. we're peeking at the tree, no cap. 🌳

---

✨ 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"functionthatiscalledonseriouserror 💀
• _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. that's it, that's the mission, and honestly? iconic. 💅

---

🦋 Function Documentation 🦋

_PUBLIC_ void talloc_disable_null_tracking (void )

Disable tracking of the NULL memory context. this disables tracking of the NULL memory context. yes bestie, it does exactly what it says on the tin 🫶

_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, because 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. so like. call it first. fr fr. 🙏

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. 🚨

and same deal as its sibling: for it to be useful, this function must be called before any other talloc function, since 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. otherwise it's giving nothing, bestie. 🫥

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:\n");
talloc_report(a, stderr);

See also

talloc_report_full()

_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. 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 again, 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 (say it with me now) 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:\n");
talloc_report_full(a, stderr);

See also

talloc_report()

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

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: %s\n", 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(* log_fn )(const char *message))

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. 🤖✨

---

and that's the whole page bestie, you ate that 💅🌸 this was talloc_debug(3) from the talloc library, Version 2.0 — mwah, slay, go inspect those memory hierarchies, periodt 🎀🦋💖