updated XML source for talloc man page

1 files changed, 73 insertions, 1 deletions

diff --git a/lib/talloc/talloc.3.xml b/lib/talloc/talloc.3.xml
index 67de15bfc8..3e895b20b5 100644
--- a/lib/talloc/talloc.3.xml
+++ b/lib/talloc/talloc.3.xml
@@ -135,6 +135,29 @@
         <para>
 	  talloc_free() operates recursively on its children.
         </para>
+	<para>
+	  As a special case, talloc_free() is refused on pointers that
+	  have more than one parent, as talloc would have no way of knowing
+	  which parent should be removed. To free a pointer that has more than
+	  one parent please use talloc_unlink().
+	</para>
+	<para>
+	  To help you find problems in your code caused by this behaviour, if
+	  you do try and free a pointer with more than one parent then the
+	  talloc logging function will be called to give output like this:
+	</para>
+	<para>
+	  <screen format="linespecific">
+	    ERROR: talloc_free with references at some_dir/source/foo.c:123
+  	  	reference at some_dir/source/other.c:325
+  	  	reference at some_dir/source/third.c:121
+	  </screen>
+	</para>
+	<para>
+	  Please see the documentation for talloc_set_log_fn() and
+	  talloc_set_log_stderr() for more information on talloc logging
+	  functions.
+	</para>
     </refsect2>
     <refsect2 id="talloc_reference"><title>void *talloc_reference(const void *ctx, const void *ptr);</title>
         <para>
@@ -381,11 +404,48 @@ talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);</programlisting>
 	   It does not have any failure modes.
         </para>
         <para>
-	  NOTE: It is possible to produce loops in the parent/child
+	  It is possible to produce loops in the parent/child
 	  relationship if you are not careful with talloc_steal().  No
 	  guarantees are provided as to your sanity or the safety of your
 	  data if you do this.
         </para>
+        <para>
+	  Note that if you try and call talloc_steal() on a pointer that has
+	  more than one parent then the result is ambiguous. Talloc will choose
+	  to remove the parent that is currently indicated by talloc_parent()
+	  and replace it with the chosen parent. You will also get a message
+	  like this via the talloc logging functions:
+        </para>
+        <para>
+	  <screen format="linespecific">
+	  WARNING: talloc_steal with references at some_dir/source/foo.c:123
+  	  	reference at some_dir/source/other.c:325
+  	  	reference at some_dir/source/third.c:121
+	  </screen>
+        </para>
+        <para>
+	  To unambiguously change the parent of a pointer please see
+	  the
+	  function <link linkend="talloc_reference"><quote>talloc_reparent()</quote></link>. See
+	  the talloc_set_log_fn() documentation for more information
+	  on talloc logging.  </para
+    </refsect2>
+    <refsect2><title>TYPE *talloc_reparent(const void *<emphasis role="italic">old_parent</emphasis>, const void *<emphasis role="italic">new_parent</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>);</title>
+        <para>
+	  The talloc_reparent() 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.
+        </para>
+        <para>
+	  The talloc_reparent() function returns the pointer that you pass it. It
+	  does not have any failure modes.
+        </para>
+        <para>
+	  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.
+        </para>
     </refsect2>
     <refsect2><title>TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>);</title>
         <para>
@@ -696,6 +756,18 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
         </para>
         <programlisting>talloc_set_name_const(ptr, #type)</programlisting>
     </refsect2>
+    <refsect2><title>talloc_set_log_fn(void (*log_fn)(const char *message));</title>
+        <para>
+	  This function sets a logging function that talloc will use for
+	  warnings and errors. By default talloc will not print any warnings or
+	  errors.
+	</para>
+    </refsect2>
+    <refsect2><title>talloc_set_log_stderr(void);</title>
+        <para>
+	  This sets the talloc log function to write log messages to stderr
+	</para>
+    </refsect2>
   </refsect1>
   <refsect1><title>PERFORMANCE</title>
     <para>