summaryrefslogtreecommitdiff
path: root/lib/talloc
diff options
context:
space:
mode:
authorAndrew Tridgell <tridge@samba.org>2009-08-24 16:01:18 +1000
committerAndrew Tridgell <tridge@samba.org>2009-08-24 16:30:00 +1000
commit798b3fbb53fb229c93b841e380a4439d6575d75a (patch)
treed453adff044c905a43e586d82ec194fe0aac469d /lib/talloc
parente6da38c8b7791292243b539cfbaf763f5b61f509 (diff)
downloadsamba-798b3fbb53fb229c93b841e380a4439d6575d75a.tar.gz
samba-798b3fbb53fb229c93b841e380a4439d6575d75a.tar.bz2
samba-798b3fbb53fb229c93b841e380a4439d6575d75a.zip
updated XML source for talloc man page
Diffstat (limited to 'lib/talloc')
-rw-r--r--lib/talloc/talloc.3.xml74
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>