update lib/replace from samba4
[vlendec/samba-autobuild/.git] / ctdb / lib / 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.71.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"><a name="id2478730"></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="id2517362"></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="id2478829"></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="id2478838"></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="id2478902"></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="id2478915"></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="id2478930"></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="id2479748"></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="id2479785"></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="id2479904"></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="id2479948"></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="id2479983"></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="id2480018"></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="id2480049"></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="id2480072"></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="id2526763"></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="id2526841"></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="id2526853"></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="id2526890"></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="id2526916"></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="id2526940"></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="id2527248"></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="id2527281"></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="id2527304"></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="id2527332"></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="id2527372"></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="id2527412"></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>
356           The talloc_vasprintf() function is the talloc equivalent of the C
357           library function vasprintf(3).
358         </p></div><div class="refsect2" lang="en"><a name="id2527441"></a><h3>char *talloc_asprintf(const void *<span class="italic">t</span>, const char *<span class="italic">fmt</span>, ...);</h3><p>
359           The talloc_asprintf() function is the talloc equivalent of the C
360           library function asprintf(3).
361         </p><p>
362           This function sets the name of the new pointer to the passed
363           string. This is equivalent to:
364         </p><pre class="programlisting">talloc_set_name_const(ptr, ptr)</pre></div><div class="refsect2" lang="en"><a name="id2527475"></a><h3>char *talloc_asprintf_append(char *s, const char *fmt, ...);</h3><p>
365           The talloc_asprintf_append() function appends the given formatted
366           string to the given string.
367         </p></div><div class="refsect2" lang="en"><a name="id2527486"></a><h3>(type *)talloc_array(const void *ctx, type, uint_t count);</h3><p>
368           The talloc_array() macro is equivalent to:
369         </p><pre class="programlisting">(type *)talloc_size(ctx, sizeof(type) * count);</pre><p>
370           except that it provides integer overflow protection for the
371           multiply, returning NULL if the multiply overflows.
372         </p></div><div class="refsect2" lang="en"><a name="id2527509"></a><h3>void *talloc_array_size(const void *ctx, size_t size, uint_t count);</h3><p>
373           The talloc_array_size() function is useful when the type is not
374           known. It operates in the same way as talloc_array(), but takes a
375           size instead of a type.
376         </p></div><div class="refsect2" lang="en"><a name="id2527522"></a><h3>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);</h3><p>
377           The talloc_ptrtype() macro should be used when you have a pointer to an array
378           and want to allocate memory of an array to point at with this pointer. When compiling
379           with gcc &gt;= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
380           and talloc_get_name() will return the current location in the source file.
381           and not the type.
382         </p></div><div class="refsect2" lang="en"><a name="id2527538"></a><h3>void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size)</h3><p>
383           This is a non-macro version of talloc_realloc(), which is useful
384           as libraries sometimes want a realloc function pointer.  A
385           realloc(3) implementation encapsulates the functionality of
386           malloc(3), free(3) and realloc(3) in one call, which is why it is
387           useful to be able to pass around a single function pointer.
388         </p></div><div class="refsect2" lang="en"><a name="id2527554"></a><h3>void *talloc_autofree_context(void);</h3><p>
389           This is a handy utility function that returns a talloc context
390           which will be automatically freed on program exit.  This can be
391           used to reduce the noise in memory leak reports.
392         </p></div><div class="refsect2" lang="en"><a name="id2527566"></a><h3>void *talloc_check_name(const void *ptr, const char *name);</h3><p>
393           This function checks if a pointer has the specified <span class="italic">name</span>.  If it does then the pointer is
394           returned.  It it doesn't then NULL is returned.
395         </p></div><div class="refsect2" lang="en"><a name="id2527584"></a><h3>(type *)talloc_get_type(const void *ptr, type);</h3><p>
396           This macro allows you to do type checking on talloc pointers.  It
397           is particularly useful for void* private pointers.  It is
398           equivalent to this:
399         </p><pre class="programlisting">(type *)talloc_check_name(ptr, #type)</pre></div><div class="refsect2" lang="en"><a name="id2527603"></a><h3>talloc_set_type(const void *ptr, type);</h3><p>
400           This macro allows you to force the name of a pointer to be a
401           particular <span class="emphasis"><em>type</em></span>.  This can be
402           used in conjunction with talloc_get_type() to do type checking on
403           void* pointers.
404         </p><p>
405           It is equivalent to this:
406         </p><pre class="programlisting">talloc_set_name_const(ptr, #type)</pre></div></div><div class="refsect1" lang="en"><a name="id2527631"></a><h2>PERFORMANCE</h2><p>
407       All the additional features of talloc(3) over malloc(3) do come at a
408       price.  We have a simple performance test in Samba4 that measures
409       talloc() versus malloc() performance, and it seems that talloc() is
410       about 10% slower than malloc() on my x86 Debian Linux box.  For
411       Samba, the great reduction in code complexity that we get by using
412       talloc makes this worthwhile, especially as the total overhead of
413       talloc/malloc in Samba is already quite small.
414     </p></div><div class="refsect1" lang="en"><a name="id2527648"></a><h2>SEE ALSO</h2><p>
415       malloc(3), strndup(3), vasprintf(3), asprintf(3), 
416       <a href="http://talloc.samba.org/" target="_top">http://talloc.samba.org/</a>
417     </p></div><div class="refsect1" lang="en"><a name="id2527662"></a><h2>COPYRIGHT/LICENSE</h2><p>
418       Copyright (C) Andrew Tridgell 2004
419     </p><p>
420       This program is free software; you can redistribute it and/or modify
421       it under the terms of the GNU General Public License as published by
422       the Free Software Foundation; either version 3 of the License, or (at
423       your option) any later version.
424     </p><p>
425       This program is distributed in the hope that it will be useful, but
426       WITHOUT ANY WARRANTY; without even the implied warranty of
427       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
428       General Public License for more details.
429     </p><p>
430       You should have received a copy of the GNU General Public License
431       along with this program; if not, write to the Free Software
432       Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
433     </p></div></div></body></html>