ccan/ccan_tools/talloc/talloc.3.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>talloc</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="id2486772"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>talloc &#8212; hierarchical reference counted memory pool system with destructors</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">#include &lt;talloc/talloc.h&gt;</pre></div><div class="refsect1" lang="en"><a name="id2525397"></a><h2>DESCRIPTION</h2><p>
   2       If you are used to talloc from Samba3 then please read this
   3       carefully, as talloc has changed a lot.
   4     </p><p>
   5       The new talloc is a hierarchical, reference counted memory pool
   6       system with destructors.  Quite a mouthful really, but not too bad
   7       once you get used to it.
   8     </p><p>
   9       Perhaps the biggest change from Samba3 is that there is no
  10       distinction between a "talloc context" and a "talloc pointer".  Any
  11       pointer returned from talloc() is itself a valid talloc context.
  12       This means you can do this:
  13     </p><pre class="programlisting">
  14     struct foo *X = talloc(mem_ctx, struct foo);
  15     X-&gt;name = talloc_strdup(X, "foo");
  16     </pre><p>
  17       and the pointer <code class="literal">X-&gt;name</code>
  18       would be a "child" of the talloc context <code class="literal">X</code> which is itself a child of
  19       <code class="literal">mem_ctx</code>.  So if you do
  20       <code class="literal">talloc_free(mem_ctx)</code> then
  21       it is all destroyed, whereas if you do <code class="literal">talloc_free(X)</code> then just <code class="literal">X</code> and <code class="literal">X-&gt;name</code> are destroyed, and if
  22       you do <code class="literal">talloc_free(X-&gt;name)</code> then just
  23       the name element of <code class="literal">X</code> is
  24       destroyed.
  25     </p><p>
  26       If you think about this, then what this effectively gives you is an
  27       n-ary tree, where you can free any part of the tree with
  28       talloc_free().
  29     </p><p>
  30       If you find this confusing, then I suggest you run the <code class="literal">testsuite</code> program to watch talloc
  31       in action.  You may also like to add your own tests to <code class="literal">testsuite.c</code> to clarify how some
  32       particular situation is handled.
  33     </p></div><div class="refsect1" lang="en"><a name="id2486869"></a><h2>TALLOC API</h2><p>
  34       The following is a complete guide to the talloc API. Read it all at
  35       least twice.
  36     </p><div class="refsect2" lang="en"><a name="id2486878"></a><h3>(type *)talloc(const void *ctx, type);</h3><p>
  37           The talloc() macro is the core of the talloc library.  It takes a
  38           memory <span class="italic">ctx</span> and a <span class="italic">type</span>, and returns a pointer to a new
  39           area of memory of the given <span class="italic">type</span>.
  40         </p><p>
  41           The returned pointer is itself a talloc context, so you can use
  42           it as the <span class="italic">ctx</span> argument to more
  43           calls to talloc() if you wish.
  44         </p><p>
  45           The returned pointer is a "child" of the supplied context.  This
  46           means that if you talloc_free() the <span class="italic">ctx</span> then the new child disappears as
  47           well.  Alternatively you can free just the child.
  48         </p><p>
  49           The <span class="italic">ctx</span> argument to talloc()
  50           can be NULL, in which case a new top level context is created.
  51         </p></div><div class="refsect2" lang="en"><a name="id2486942"></a><h3>void *talloc_size(const void *ctx, size_t size);</h3><p>
  52           The function talloc_size() should be used when you don't have a
  53           convenient type to pass to talloc().  Unlike talloc(), it is not
  54           type safe (as it returns a void *), so you are on your own for
  55           type checking.
  56         </p></div><div class="refsect2" lang="en"><a name="id2486956"></a><h3>(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);</h3><p>
  57           The talloc_ptrtype() macro should be used when you have a pointer and
  58           want to allocate memory to point at with this pointer. When compiling
  59           with gcc &gt;= 3 it is typesafe. Note this is a wrapper of talloc_size()
  60           and talloc_get_name() will return the current location in the source file.
  61           and not the type.
  62         </p></div><div class="refsect2" lang="en"><a name="id2486971"></a><h3>int talloc_free(void *ptr);</h3><p>
  63           The talloc_free() function frees a piece of talloc memory, and
  64           all its children.  You can call talloc_free() on any pointer
  65           returned by talloc().
  66         </p><p>
  67           The return value of talloc_free() indicates success or failure,
  68           with 0 returned for success and -1 for failure.  The only
  69           possible failure condition is if <span class="italic">ptr</span> had a destructor attached to it and
  70           the destructor returned -1.  See <a href="#talloc_set_destructor" title="void talloc_set_destructor(const void *ptr, int (*destructor)(void *));">&#8220;<span class="quote">talloc_set_destructor()</span>&#8221;</a>
  71           for details on destructors.
  72         </p><p>
  73           If this pointer has an additional parent when talloc_free() is
  74           called then the memory is not actually released, but instead the
  75           most recently established parent is destroyed.  See <a href="#talloc_reference" title="void *talloc_reference(const void *ctx, const void *ptr);">&#8220;<span class="quote">talloc_reference()</span>&#8221;</a>
  76           for details on establishing additional parents.
  77         </p><p>
  78           For more control on which parent is removed, see <a href="#talloc_unlink" title="int talloc_unlink(const void *ctx, const void *ptr);">&#8220;<span class="quote">talloc_unlink()</span>&#8221;</a>.
  79         </p><p>
  80           talloc_free() operates recursively on its children.
  81         </p></div><div class="refsect2" lang="en"><a name="talloc_reference"></a><h3>void *talloc_reference(const void *ctx, const void *ptr);</h3><p>
  82           The talloc_reference() function makes <span class="italic">ctx</span> an additional parent of <span class="italic">ptr</span>.
  83         </p><p>
  84           The return value of talloc_reference() is always the original
  85           pointer <span class="italic">ptr</span>, unless talloc ran
  86           out of memory in creating the reference in which case it will
  87           return NULL (each additional reference consumes around 48 bytes
  88           of memory on intel x86 platforms).
  89         </p><p>
  90           If <span class="italic">ptr</span> is NULL, then the
  91           function is a no-op, and simply returns NULL.
  92         </p><p>
  93           After creating a reference you can free it in one of the
  94           following ways:
  95         </p><p>
  96         </p><div class="itemizedlist"><ul type="disc"><li><p>
  97               you can talloc_free() any parent of the original pointer.
  98               That will reduce the number of parents of this pointer by 1,
  99               and will cause this pointer to be freed if it runs out of
 100               parents.
 101             </p></li><li><p>
 102               you can talloc_free() the pointer itself.  That will destroy
 103               the most recently established parent to the pointer and leave
 104               the pointer as a child of its current parent.
 105             </p></li></ul></div><p>
 106       </p><p>
 107         For more control on which parent to remove, see <a href="#talloc_unlink" title="int talloc_unlink(const void *ctx, const void *ptr);">&#8220;<span class="quote">talloc_unlink()</span>&#8221;</a>.
 108       </p></div><div class="refsect2" lang="en"><a name="talloc_unlink"></a><h3>int talloc_unlink(const void *ctx, const void *ptr);</h3><p>
 109           The talloc_unlink() function removes a specific parent from
 110           <span class="italic">ptr</span>. The <span class="italic">ctx</span> passed must either be a context used
 111           in talloc_reference() with this pointer, or must be a direct
 112           parent of ptr.
 113         </p><p>
 114           Note that if the parent has already been removed using
 115           talloc_free() then this function will fail and will return -1.
 116           Likewise, if <span class="italic">ptr</span> is NULL, then
 117           the function will make no modifications and return -1.
 118         </p><p>
 119           Usually you can just use talloc_free() instead of
 120           talloc_unlink(), but sometimes it is useful to have the
 121           additional control on which parent is removed.
 122         </p></div><div class="refsect2" lang="en"><a name="talloc_set_destructor"></a><h3>void talloc_set_destructor(const void *ptr, int (*destructor)(void *));</h3><p>
 123           The function talloc_set_destructor() sets the <span class="italic">destructor</span> for the pointer <span class="italic">ptr</span>.  A <span class="italic">destructor</span> is a function that is called
 124           when the memory used by a pointer is about to be released.  The
 125           destructor receives <span class="italic">ptr</span> as an
 126           argument, and should return 0 for success and -1 for failure.
 127         </p><p>
 128           The <span class="italic">destructor</span> can do anything
 129           it wants to, including freeing other pieces of memory.  A common
 130           use for destructors is to clean up operating system resources
 131           (such as open file descriptors) contained in the structure the
 132           destructor is placed on.
 133         </p><p>
 134           You can only place one destructor on a pointer.  If you need more
 135           than one destructor then you can create a zero-length child of
 136           the pointer and place an additional destructor on that.
 137         </p><p>
 138           To remove a destructor call talloc_set_destructor() with NULL for
 139           the destructor.
 140         </p><p>
 141           If your destructor attempts to talloc_free() the pointer that it
 142           is the destructor for then talloc_free() will return -1 and the
 143           free will be ignored.  This would be a pointless operation
 144           anyway, as the destructor is only called when the memory is just
 145           about to go away.
 146         </p></div><div class="refsect2" lang="en"><a name="id2488786"></a><h3>int talloc_increase_ref_count(const void *<span class="italic">ptr</span>);</h3><p>
 147           The talloc_increase_ref_count(<span class="italic">ptr</span>) function is exactly equivalent to:
 148         </p><pre class="programlisting">talloc_reference(NULL, ptr);</pre><p>
 149           You can use either syntax, depending on which you think is
 150           clearer in your code.
 151         </p><p>
 152           It returns 0 on success and -1 on failure.
 153         </p></div><div class="refsect2" lang="en"><a name="id2488823"></a><h3>size_t talloc_reference_count(const void *<span class="italic">ptr</span>);</h3><p>
 154           Return the number of references to the pointer.
 155         </p></div><div class="refsect2" lang="en"><a name="talloc_set_name"></a><h3>void talloc_set_name(const void *ptr, const char *fmt, ...);</h3><p>
 156           Each talloc pointer has a "name".  The name is used principally
 157           for debugging purposes, although it is also possible to set and
 158           get the name on a pointer in as a way of "marking" pointers in
 159           your code.
 160         </p><p>
 161           The main use for names on pointer is for "talloc reports".  See
 162           <a href="#talloc_report" title="void talloc_report(const void *ptr, FILE *f);">&#8220;<span class="quote">talloc_report_depth_cb()</span>&#8221;</a>,
 163           <a href="#talloc_report" title="void talloc_report(const void *ptr, FILE *f);">&#8220;<span class="quote">talloc_report_depth_file()</span>&#8221;</a>,
 164           <a href="#talloc_report" title="void talloc_report(const void *ptr, FILE *f);">&#8220;<span class="quote">talloc_report()</span>&#8221;</a>
 165           <a href="#talloc_report" title="void talloc_report(const void *ptr, FILE *f);">&#8220;<span class="quote">talloc_report()</span>&#8221;</a>
 166           and <a href="#talloc_report_full" title="void talloc_report_full(const void *ptr, FILE *f);">&#8220;<span class="quote">talloc_report_full()</span>&#8221;</a>
 167           for details.  Also see <a href="#talloc_enable_leak_report" title="void talloc_enable_leak_report(void);">&#8220;<span class="quote">talloc_enable_leak_report()</span>&#8221;</a>
 168           and <a href="#talloc_enable_leak_report_full" title="void talloc_enable_leak_report_full(void);">&#8220;<span class="quote">talloc_enable_leak_report_full()</span>&#8221;</a>.
 169         </p><p>
 170           The talloc_set_name() function allocates memory as a child of the
 171           pointer.  It is logically equivalent to:
 172         </p><pre class="programlisting">talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));</pre><p>
 173           Note that multiple calls to talloc_set_name() will allocate more
 174           memory without releasing the name.  All of the memory is released
 175           when the ptr is freed using talloc_free().
 176         </p></div><div class="refsect2" lang="en"><a name="id2488942"></a><h3>void talloc_set_name_const(const void *<span class="italic">ptr</span>, const char *<span class="italic">name</span>);</h3><p>
 177           The function talloc_set_name_const() is just like
 178           talloc_set_name(), but it takes a string constant, and is much
 179           faster.  It is extensively used by the "auto naming" macros, such
 180           as talloc_p().
 181         </p><p>
 182           This function does not allocate any memory.  It just copies the
 183           supplied pointer into the internal representation of the talloc
 184           ptr. This means you must not pass a <span class="italic">name</span> pointer to memory that will
 185           disappear before <span class="italic">ptr</span> is freed
 186           with talloc_free().
 187         </p></div><div class="refsect2" lang="en"><a name="id2488986"></a><h3>void *talloc_named(const void *<span class="italic">ctx</span>, size_t <span class="italic">size</span>, const char *<span class="italic">fmt</span>, ...);</h3><p>
 188           The talloc_named() function creates a named talloc pointer.  It
 189           is equivalent to:
 190         </p><pre class="programlisting">ptr = talloc_size(ctx, size);
 191 talloc_set_name(ptr, fmt, ....);</pre></div><div class="refsect2" lang="en"><a name="id2489022"></a><h3>void *talloc_named_const(const void *<span class="italic">ctx</span>, size_t <span class="italic">size</span>, const char *<span class="italic">name</span>);</h3><p>
 192           This is equivalent to:
 193         </p><pre class="programlisting">ptr = talloc_size(ctx, size);
 194 talloc_set_name_const(ptr, name);</pre></div><div class="refsect2" lang="en"><a name="id2489056"></a><h3>const char *talloc_get_name(const void *<span class="italic">ptr</span>);</h3><p>
 195           This returns the current name for the given talloc pointer,
 196           <span class="italic">ptr</span>. See <a href="#talloc_set_name" title="void talloc_set_name(const void *ptr, const char *fmt, ...);">&#8220;<span class="quote">talloc_set_name()</span>&#8221;</a>
 197           for details.
 198         </p></div><div class="refsect2" lang="en"><a name="id2489087"></a><h3>void *talloc_init(const char *<span class="italic">fmt</span>, ...);</h3><p>
 199           This function creates a zero length named talloc context as a top
 200           level context.  It is equivalent to:
 201         </p><pre class="programlisting">talloc_named(NULL, 0, fmt, ...);</pre></div><div class="refsect2" lang="en"><a name="id2489110"></a><h3>void *talloc_new(void *<span class="italic">ctx</span>);</h3><p>
 202           This is a utility macro that creates a new memory context hanging
 203           off an exiting context, automatically naming it "talloc_new:
 204           __location__" where __location__ is the source line it is called
 205           from.  It is particularly useful for creating a new temporary
 206           working context.
 207         </p></div><div class="refsect2" lang="en"><a name="id2489130"></a><h3>(<span class="italic">type</span> *)talloc_realloc(const void *<span class="italic">ctx</span>, void *<span class="italic">ptr</span>, <span class="italic">type</span>, <span class="italic">count</span>);</h3><p>
 208           The talloc_realloc() macro changes the size of a talloc pointer.
 209           It has the following equivalences:
 210         </p><pre class="programlisting">talloc_realloc(ctx, NULL, type, 1) ==&gt; talloc(ctx, type);
 211 talloc_realloc(ctx, ptr, type, 0)  ==&gt; talloc_free(ptr);</pre><p>
 212           The <span class="italic">ctx</span> argument is only used
 213           if <span class="italic">ptr</span> is not NULL, otherwise
 214           it is ignored.
 215         </p><p>
 216           talloc_realloc() returns the new pointer, or NULL on failure.
 217           The call will fail either due to a lack of memory, or because the
 218           pointer has more than one parent (see <a href="#talloc_reference" title="void *talloc_reference(const void *ctx, const void *ptr);">&#8220;<span class="quote">talloc_reference()</span>&#8221;</a>).
 219         </p></div><div class="refsect2" lang="en"><a name="id2534877"></a><h3>void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);</h3><p>
 220           the talloc_realloc_size() function is useful when the type is not
 221           known so the type-safe talloc_realloc() cannot be used.
 222         </p></div><div class="refsect2" lang="en"><a name="id2534889"></a><h3>TYPE *talloc_steal(const void *<span class="italic">new_ctx</span>, const TYPE *<span class="italic">ptr</span>);</h3><p>
 223           The talloc_steal() function changes the parent context of a
 224           talloc pointer.  It is typically used when the context that the
 225           pointer is currently a child of is going to be freed and you wish
 226           to keep the memory for a longer time.
 227         </p><p>
 228           The talloc_steal() function returns the pointer that you pass it.
 229            It does not have any failure modes.
 230         </p><p>
 231           NOTE: It is possible to produce loops in the parent/child
 232           relationship if you are not careful with talloc_steal().  No
 233           guarantees are provided as to your sanity or the safety of your
 234           data if you do this.
 235         </p></div><div class="refsect2" lang="en"><a name="id2534927"></a><h3>TYPE *talloc_move(const void *<span class="italic">new_ctx</span>, TYPE **<span class="italic">ptr</span>);</h3><p>
 236           The talloc_move() function is a wrapper around
 237           talloc_steal() which zeros the source pointer after the
 238           move. This avoids a potential source of bugs where a
 239           programmer leaves a pointer in two structures, and uses the
 240           pointer from the old structure after it has been moved to a
 241           new one.
 242         </p></div><div class="refsect2" lang="en"><a name="id2534953"></a><h3>size_t talloc_total_size(const void *<span class="italic">ptr</span>);</h3><p>
 243           The talloc_total_size() function returns the total size in bytes
 244           used by this pointer and all child pointers.  Mostly useful for
 245           debugging.
 246         </p><p>
 247           Passing NULL is allowed, but it will only give a meaningful
 248           result if talloc_enable_leak_report() or
 249           talloc_enable_leak_report_full() has been called.
 250         </p></div><div class="refsect2" lang="en"><a name="id2534976"></a><h3>size_t talloc_total_blocks(const void *<span class="italic">ptr</span>);</h3><p>
 251           The talloc_total_blocks() function returns the total memory block
 252           count used by this pointer and all child pointers.  Mostly useful
 253           for debugging.
 254         </p><p>
 255           Passing NULL is allowed, but it will only give a meaningful
 256           result if talloc_enable_leak_report() or
 257           talloc_enable_leak_report_full() has been called.
 258         </p></div><div class="refsect2" lang="en"><a name="talloc_report"></a><h3>void talloc_report(const void *ptr, FILE *f);</h3><p>
 259           The talloc_report() function prints a summary report of all
 260           memory used by <span class="italic">ptr</span>.  One line
 261           of report is printed for each immediate child of ptr, showing the
 262           total memory and number of blocks used by that child.
 263         </p><p>
 264           You can pass NULL for the pointer, in which case a report is
 265           printed for the top level memory context, but only if
 266           talloc_enable_leak_report() or talloc_enable_leak_report_full()
 267           has been called.
 268         </p></div><div class="refsect2" lang="en"><a name="talloc_report_full"></a><h3>void talloc_report_full(const void *<span class="italic">ptr</span>, FILE *<span class="italic">f</span>);</h3><p>
 269           This provides a more detailed report than talloc_report().  It
 270           will recursively print the entire tree of memory referenced by
 271           the pointer. References in the tree are shown by giving the name
 272           of the pointer that is referenced.
 273         </p><p>
 274           You can pass NULL for the pointer, in which case a report is
 275           printed for the top level memory context, but only if
 276           talloc_enable_leak_report() or talloc_enable_leak_report_full()
 277           has been called.
 278         </p></div><div class="refsect2" lang="en"><a name="talloc_report_depth_cb"></a><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">talloc_report_depth_cb</b>(</code></td><td><var class="pdparam">const void *ptr</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">int depth</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">int max_depth</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *priv)</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">void *priv</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code></code> </td><td><code><var class="pdparam">const void *ptr</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">int depth</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">int max_depth</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *priv)</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">void *priv</var>;</code></td></tr></table></div><p>
 279           This provides a more flexible reports than talloc_report(). It
 280           will recursively call the callback for the entire tree of memory
 281           referenced by the pointer. References in the tree are passed with
 282           <span class="italic">is_ref = 1</span> and the pointer that is referenced.
 283         </p><p>
 284           You can pass NULL for the pointer, in which case a report is
 285           printed for the top level memory context, but only if
 286           talloc_enable_leak_report() or talloc_enable_leak_report_full()
 287           has been called.
 288         </p><p>
 289           The recursion is stopped when depth &gt;= max_depth.
 290           max_depth = -1 means only stop at leaf nodes.
 291         </p></div><div class="refsect2" lang="en"><a name="talloc_report_depth_file"></a><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">talloc_report_depth_file</b>(</code></td><td><var class="pdparam">const void *ptr</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">int depth</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">int max_depth</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">FILE *f</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code></code> </td><td><code><var class="pdparam">const void *ptr</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">int depth</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">int max_depth</var>;</code></td></tr><tr><td><code></code> </td><td><code><var class="pdparam">FILE *f</var>;</code></td></tr></table></div><p>
 292           This provides a more flexible reports than talloc_report(). It
 293           will let you specify the depth and max_depth.
 294         </p></div><div class="refsect2" lang="en"><a name="talloc_enable_leak_report"></a><h3>void talloc_enable_leak_report(void);</h3><p>
 295           This enables calling of talloc_report(NULL, stderr) when the
 296           program exits.  In Samba4 this is enabled by using the
 297           --leak-report command line option.
 298         </p><p>
 299           For it to be useful, this function must be called before any
 300           other talloc function as it establishes a "null context" that
 301           acts as the top of the tree.  If you don't call this function
 302           first then passing NULL to talloc_report() or
 303           talloc_report_full() won't give you the full tree printout.
 304         </p><p>
 305           Here is a typical talloc report:
 306         </p><pre class="screen">talloc report on 'null_context' (total 267 bytes in 15 blocks)
 307 libcli/auth/spnego_parse.c:55  contains   31 bytes in   2 blocks
 308 libcli/auth/spnego_parse.c:55  contains   31 bytes in   2 blocks
 309 iconv(UTF8,CP850)              contains   42 bytes in   2 blocks
 310 libcli/auth/spnego_parse.c:55  contains   31 bytes in   2 blocks
 311 iconv(CP850,UTF8)              contains   42 bytes in   2 blocks
 312 iconv(UTF8,UTF-16LE)           contains   45 bytes in   2 blocks
 313 iconv(UTF-16LE,UTF8)           contains   45 bytes in   2 blocks
 314       </pre></div><div class="refsect2" lang="en"><a name="talloc_enable_leak_report_full"></a><h3>void talloc_enable_leak_report_full(void);</h3><p>
 315           This enables calling of talloc_report_full(NULL, stderr) when the
 316           program exits.  In Samba4 this is enabled by using the
 317           --leak-report-full command line option.
 318         </p><p>
 319           For it to be useful, this function must be called before any
 320           other talloc function as it establishes a "null context" that
 321           acts as the top of the tree.  If you don't call this function
 322           first then passing NULL to talloc_report() or
 323           talloc_report_full() won't give you the full tree printout.
 324         </p><p>
 325           Here is a typical full report:
 326         </p><pre class="screen">full talloc report on 'root' (total 18 bytes in 8 blocks)
 327 p1               contains     18 bytes in   7 blocks (ref 0)
 328     r1               contains     13 bytes in   2 blocks (ref 0)
 329         reference to: p2
 330     p2               contains      1 bytes in   1 blocks (ref 1)
 331     x3               contains      1 bytes in   1 blocks (ref 0)
 332     x2               contains      1 bytes in   1 blocks (ref 0)
 333     x1               contains      1 bytes in   1 blocks (ref 0)
 334       </pre></div><div class="refsect2" lang="en"><a name="id2535284"></a><h3>(<span class="italic">type</span> *)talloc_zero(const void *<span class="italic">ctx</span>, <span class="italic">type</span>);</h3><p>
 335           The talloc_zero() macro is equivalent to:
 336         </p><pre class="programlisting">ptr = talloc(ctx, type);
 337 if (ptr) memset(ptr, 0, sizeof(type));</pre></div><div class="refsect2" lang="en"><a name="id2535318"></a><h3>void *talloc_zero_size(const void *<span class="italic">ctx</span>, size_t <span class="italic">size</span>)</h3><p>
 338           The talloc_zero_size() function is useful when you don't have a
 339           known type.
 340         </p></div><div class="refsect2" lang="en"><a name="id2535340"></a><h3>void *talloc_memdup(const void *<span class="italic">ctx</span>, const void *<span class="italic">p</span>, size_t size);</h3><p>
 341           The talloc_memdup() function is equivalent to:
 342         </p><pre class="programlisting">ptr = talloc_size(ctx, size);
 343 if (ptr) memcpy(ptr, p, size);</pre></div><div class="refsect2" lang="en"><a name="id2535369"></a><h3>char *talloc_strdup(const void *<span class="italic">ctx</span>, const char *<span class="italic">p</span>);</h3><p>
 344           The talloc_strdup() function is equivalent to:
 345         </p><pre class="programlisting">ptr = talloc_size(ctx, strlen(p)+1);
 346 if (ptr) memcpy(ptr, p, strlen(p)+1);</pre><p>
 347           This function sets the name of the new pointer to the passed
 348           string. This is equivalent to:
 349         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535409"></a><h3>char *talloc_strndup(const void *<span class="italic">t</span>, const char *<span class="italic">p</span>, size_t <span class="italic">n</span>);</h3><p>
 350           The talloc_strndup() function is the talloc equivalent of the C
 351           library function strndup(3).
 352         </p><p>
 353           This function sets the name of the new pointer to the passed
 354           string. This is equivalent to:
 355         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535449"></a><h3>char *talloc_append_string(const void *<span class="italic">t</span>, char *<span class="italic">orig</span>, const char *<span class="italic">append</span>);</h3><p>
 356           The talloc_append_string() function appends the given formatted
 357           string to the given string.
 358         </p><p>
 359           This function sets the name of the new pointer to the new
 360           string. This is equivalent to:
 361         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535489"></a><h3>char *talloc_vasprintf(const void *<span class="italic">t</span>, const char *<span class="italic">fmt</span>, va_list <span class="italic">ap</span>);</h3><p>
 362           The talloc_vasprintf() function is the talloc equivalent of the C
 363           library function vasprintf(3).
 364         </p><p>
 365           This function sets the name of the new pointer to the new
 366           string. This is equivalent to:
 367         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535528"></a><h3>char *talloc_asprintf(const void *<span class="italic">t</span>, const char *<span class="italic">fmt</span>, ...);</h3><p>
 368           The talloc_asprintf() function is the talloc equivalent of the C
 369           library function asprintf(3).
 370         </p><p>
 371           This function sets the name of the new pointer to the passed
 372           string. This is equivalent to:
 373         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535562"></a><h3>char *talloc_asprintf_append(char *s, const char *fmt, ...);</h3><p>
 374           The talloc_asprintf_append() function appends the given formatted
 375           string to the given string.
 376         </p><p>
 377           This function sets the name of the new pointer to the new
 378           string. This is equivalent to:
 379         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2535586"></a><h3>(type *)talloc_array(const void *ctx, type, uint_t count);</h3><p>
 380           The talloc_array() macro is equivalent to:
 381         </p><pre class="programlisting">(type *)talloc_size(ctx, sizeof(type) * count);</pre><p>
 382           except that it provides integer overflow protection for the
 383           multiply, returning NULL if the multiply overflows.
 384         </p></div><div class="refsect2" lang="en"><a name="id2535608"></a><h3>void *talloc_array_size(const void *ctx, size_t size, uint_t count);</h3><p>
 385           The talloc_array_size() function is useful when the type is not
 386           known. It operates in the same way as talloc_array(), but takes a
 387           size instead of a type.
 388         </p></div><div class="refsect2" lang="en"><a name="id2535621"></a><h3>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);</h3><p>
 389           The talloc_ptrtype() macro should be used when you have a pointer to an array
 390           and want to allocate memory of an array to point at with this pointer. When compiling
 391           with gcc &gt;= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
 392           and talloc_get_name() will return the current location in the source file.
 393           and not the type.
 394         </p></div><div class="refsect2" lang="en"><a name="id2535637"></a><h3>void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size)</h3><p>
 395           This is a non-macro version of talloc_realloc(), which is useful
 396           as libraries sometimes want a realloc function pointer.  A
 397           realloc(3) implementation encapsulates the functionality of
 398           malloc(3), free(3) and realloc(3) in one call, which is why it is
 399           useful to be able to pass around a single function pointer.
 400         </p></div><div class="refsect2" lang="en"><a name="id2535653"></a><h3>void *talloc_autofree_context(void);</h3><p>
 401           This is a handy utility function that returns a talloc context
 402           which will be automatically freed on program exit.  This can be
 403           used to reduce the noise in memory leak reports.
 404         </p></div><div class="refsect2" lang="en"><a name="id2535665"></a><h3>void *talloc_check_name(const void *ptr, const char *name);</h3><p>
 405           This function checks if a pointer has the specified <span class="italic">name</span>.  If it does then the pointer is
 406           returned.  It it doesn't then NULL is returned.
 407         </p></div><div class="refsect2" lang="en"><a name="id2535683"></a><h3>(type *)talloc_get_type(const void *ptr, type);</h3><p>
 408           This macro allows you to do type checking on talloc pointers.  It
 409           is particularly useful for void* private pointers.  It is
 410           equivalent to this:
 411         </p><pre class="programlisting">(type *)talloc_check_name(ptr, #type)</pre></div><div class="refsect2" lang="en"><a name="id2535702"></a><h3>talloc_set_type(const void *ptr, type);</h3><p>
 412           This macro allows you to force the name of a pointer to be a
 413           particular <span class="emphasis"><em>type</em></span>.  This can be
 414           used in conjunction with talloc_get_type() to do type checking on
 415           void* pointers.
 416         </p><p>
 417           It is equivalent to this:
 418         </p><pre class="programlisting">talloc_set_name_const(ptr, #type)</pre></div></div><div class="refsect1" lang="en"><a name="id2535730"></a><h2>PERFORMANCE</h2><p>
 419       All the additional features of talloc(3) over malloc(3) do come at a
 420       price.  We have a simple performance test in Samba4 that measures
 421       talloc() versus malloc() performance, and it seems that talloc() is
 422       about 10% slower than malloc() on my x86 Debian Linux box.  For
 423       Samba, the great reduction in code complexity that we get by using
 424       talloc makes this worthwhile, especially as the total overhead of
 425       talloc/malloc in Samba is already quite small.
 426     </p></div><div class="refsect1" lang="en"><a name="id2535755"></a><h2>SEE ALSO</h2><p>
 427       malloc(3), strndup(3), vasprintf(3), asprintf(3),
 428       <a href="http://talloc.samba.org/" target="_top">http://talloc.samba.org/</a>
 429     </p></div><div class="refsect1" lang="en"><a name="id2535770"></a><h2>COPYRIGHT/LICENSE</h2><p>
 430       Copyright (C) Andrew Tridgell 2004
 431     </p><p>
 432       This program is free software; you can redistribute it and/or modify
 433       it under the terms of the GNU General Public License as published by
 434       the Free Software Foundation; either version 3 of the License, or (at
 435       your option) any later version.
 436     </p><p>
 437       This program is distributed in the hope that it will be useful, but
 438       WITHOUT ANY WARRANTY; without even the implied warranty of
 439       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 440       General Public License for more details.
 441     </p><p>
 442       You should have received a copy of the GNU General Public License
 443       along with this program; if not, see http://www.gnu.org/licenses/.
 444     </p></div></div></body></html>