talloc_ref(3)

🌸 talloc_ref(3) — Library Functions Manual 🌸

okay so bestie, this is the talloc_ref page from the Library Functions Manual, and it’s literally all about talloc references. 💅

🌸 NAME 🌸

talloc_ref — The talloc reference function.

This module contains the definitions around talloc references. ✨

🎀 SYNOPSIS 🎀

🧚 Topics 🧚

The talloc array functions

Talloc contains some handy helpers for handling Arrays conveniently. 🍓

💖 Functions 💖

• _PUBLIC_ int talloc_increase_ref_count (const void *ptr) — Increase the reference count of a talloc chunk.
• _PUBLIC_ size_t talloc_reference_count (const void *ptr) — Get the number of references to a talloc chunk.
• _PUBLIC_ void * talloc_reference (const void *ctx, const void *ptr) — Create an additional talloc parent to a pointer.
• _PUBLIC_ int talloc_unlink (const void *context, void *ptr) — Remove a specific parent from a talloc chunk.
• _PUBLIC_ void * talloc_autofree_context (void) _DEPRECATED_ — Provide a talloc context that is freed at program exit.
• _PUBLIC_ void talloc_show_parents (const void *context, FILE *file) — Show the parentage of a context.
• _PUBLIC_ int talloc_is_parent (const void *context, const void *ptr) — Check if a context is parent of a talloc chunk.
• _PUBLIC_ void * talloc_reparent (const void *old_parent, const void *new_parent, const void *ptr) — Change the parent context of a talloc pointer.

🦋 Detailed Description 🦋

This module contains the definitions around talloc references. That’s the whole vibe — reference lore lives here. 💜

👑 Function Documentation 👑

🌈 talloc_autofree_context 🌈

_PUBLIC_ void * talloc_autofree_context (void ) _DEPRECATED_

This is the handy utility function that gives you a talloc context that will be automatically freed on program exit. It’s the move when you want to reduce the noise in memory leak reports. ✨

⚠️ Never use this in code that might be used in objects loaded with dlopen and unloaded with dlclose. talloc_autofree_context() internally uses atexit(3). Some platforms like modern Linux handles this fine, but for example FreeBSD does not deal well with dlopen() and atexit() used simultaneously: dlclose() does not clean up the list of atexit-handlers, so when the program exits the code that was registered from within talloc_autofree_context() is gone, the program crashes at exit. 😭

Returns

A talloc context, NULL on error.

---

💖 talloc_increase_ref_count 💖

_PUBLIC_ int talloc_increase_ref_count (const void * ptr)

Increase the reference count of a talloc chunk. The talloc_increase_ref_count(ptr) function is exactly equivalent to:

talloc_reference(NULL, ptr);

You can use either syntax, depending on which you think is clearer in your code. 🫶

Parameters

• ptr — The pointer to increase the reference count.

Returns

0 on success, -1 on error.

---

🎀 talloc_is_parent 🎀

_PUBLIC_ int talloc_is_parent (const void * context, const void * ptr)

Check if a context is parent of a talloc chunk. This checks if context is referenced in the talloc hierarchy above ptr. 👑

Parameters

• context — The assumed talloc context.
• ptr — The talloc chunk to check.

Returns

Return 1 if this is the case, 0 if not.

---

🌸 talloc_reference 🌸

_PUBLIC_ void * talloc_reference (const void * ctx, const void * ptr)

Create an additional talloc parent to a pointer. The talloc_reference() function makes “context” an additional parent of ptr. Each additional reference consumes around 48 bytes of memory on intel x86 platforms. 💀

If ptr is NULL, then the function is a no-op, and simply returns NULL.

After creating a reference you can free it in one of the following ways:

• you can talloc_free() any parent of the original pointer. That will reduce the number of parents of this pointer by 1, and will cause this pointer to be freed if it runs out of parents.
• you can talloc_free() the pointer itself if it has at maximum one parent. This behaviour has been changed since the release of version 2.0. Further information in the description of "talloc_free".

For more control on which parent to remove, see talloc_unlink(). 🧚

Parameters

• ctx — The additional parent.
• ptr — The pointer you want to create an additional parent for.

Returns

The original pointer 'ptr', NULL if talloc ran out of memory in creating the reference.

⚠️ Warning: You should try to avoid using this interface. It turns a beautiful talloc-tree into a graph. It is often really hard to debug if you screw something up by accident. 🙈

Example:

unsigned int *a, *b, *c;
a = talloc(NULL, unsigned int);
b = talloc(NULL, unsigned int);
c = talloc(a, unsigned int);
// b also serves as a parent of c.
talloc_reference(b, c);

See also

talloc_unlink()

---

🍓 talloc_reference_count 🍓

_PUBLIC_ size_t talloc_reference_count (const void * ptr)

Get the number of references to a talloc chunk. 🔥

Parameters

• ptr — The pointer to retrieve the reference count from.

Returns

The number of references.

---

🦋 talloc_reparent 🦋

_PUBLIC_ void * talloc_reparent (const void * old_parent, const void * new_parent, const void * ptr)

Change the parent context of a talloc pointer. The function changes the parent context of a talloc pointer. It is typically used when the context that the pointer is currently a child of is going to be freed and you wish to keep the memory for a longer time. ✨

The difference between talloc_reparent() and talloc_steal() is that talloc_reparent() can specify which parent you wish to change. This is useful when a pointer has multiple parents via references. 💅

Parameters

old_parent, new_parent, ptr

Returns

Return the pointer you passed. It does not have any failure modes.

---

🌈 talloc_show_parents 🌈

_PUBLIC_ void talloc_show_parents (const void * context, FILE * file)

Show the parentage of a context. 👑

Parameters

• context — The talloc context to look at.
• file — The output to use, a file, stdout or stderr.

---

💜 talloc_unlink 💜

_PUBLIC_ int talloc_unlink (const void * context, void * ptr)

Remove a specific parent from a talloc chunk. The function removes a specific parent from ptr. The context passed must either be a context used in talloc_reference() with this pointer, or must be a direct parent of ptr. 🫶

You can just use talloc_free() instead of talloc_unlink() if there is at maximum one parent. This behaviour has been changed since the release of version 2.0. Further information in the description of "talloc_free".

Parameters

• context — The talloc parent to remove.
• ptr — The talloc ptr you want to remove the parent from.

Returns

0 on success, -1 on error.

📝 Note: If the parent has already been removed using talloc_free() then this function will fail and will return -1. Likewise, if ptr is NULL, then the function will make no modifications and return -1.

⚠️ Warning: You should try to avoid using this interface. It turns a beautiful talloc-tree into a graph. It is often really hard to debug if you screw something up by accident. 🙈

Example:

unsigned int *a, *b, *c;
a = talloc(NULL, unsigned int);
b = talloc(NULL, unsigned int);
c = talloc(a, unsigned int);
// b also serves as a parent of c.
talloc_reference(b, c);
talloc_unlink(b, c);

🌟 Author 🌟

Generated automatically by Doxygen for talloc from the source code. 🧚

---

💖 Sign-off, bestie: this page comes from the talloc source, Version 2.0, and the footer’s date/stamp slot is talloc_ref(3) (no separate date is shown on the page). Mwah! 💋