diff options
| -rw-r--r-- | lib/talloc/doc/tutorial_stealing.dox | 33 |
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 +*/ |