summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lib/talloc/doc/tutorial_stealing.dox33
1 files changed, 24 insertions, 9 deletions
diff --git a/lib/talloc/doc/tutorial_stealing.dox b/lib/talloc/doc/tutorial_stealing.dox
index 9ac5cbd3f9..67eae1dfc7 100644
--- a/lib/talloc/doc/tutorial_stealing.dox
+++ b/lib/talloc/doc/tutorial_stealing.dox
@@ -1,5 +1,6 @@
/**
@page libtalloc_stealing Chapter 2: Stealing a context
+
@section stealing Stealing a context
Talloc has the ability to change the parent of a talloc context to another
@@ -10,10 +11,21 @@ Stealing a context is necessary if we want the pointer to outlive the context it
is created on. This has many possible use cases, for instance stealing a result
of a database search to an in-memory cache context, changing the parent of a
field of a generic structure to a more specific one or vice-versa. The most
-common scenario, at least in SSSD, is to steal output data from a function-specific
+common scenario, at least in Samba, is to steal output data from a function-specific
context to the output context given as an argument of that function.
@code
+struct foo {
+ char *a1;
+ char *a2;
+ char *a3;
+};
+
+struct bar {
+ char *wurst;
+ struct foo *foo;
+};
+
struct foo *foo = talloc_zero(ctx, struct foo);
foo->a1 = talloc_strdup(foo, "a1");
foo->a2 = talloc_strdup(foo, "a2");
@@ -27,14 +39,17 @@ bar->foo = talloc_steal(bar, foo);
bar->foo = talloc_move(bar, &foo);
@endcode
-In general, the pointer itself is not changed (it only replaces the
-parent in the meta data). But the common usage is that the result is assigned
-to another variable, thus further accessing the pointer from the original
-variable should be avoided unless it is necessary. In this case
-talloc_move() is the preferred way of stealing a context as it protects the
-pointer from being accidentally freed and accessed using the old variable after
-its parent has been changed.
+The talloc_move() function is similar to the talloc_steal() function but
+additionally sets the source pointer to NULL.
+
+In general, the source pointer itself is not changed (it only replaces the
+parent in the meta data). But the common usage is that the result is
+assigned to another variable, thus further accessing the pointer from the
+original variable should be avoided unless it is necessary. In this case
+talloc_move() is the preferred way of stealing a context. Additionally sets the
+source pointer to NULL, thus.protects the pointer from being accidentally freed
+and accessed using the old variable after its parent has been changed.
@image html stealing.png
-*/ \ No newline at end of file
+*/