| blob | a327922dbeacf107ddd8a9dfb7e979cbb73da56a |
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3 <refentry>
4 <refmeta>
5 <refentrytitle>talloc</refentrytitle>
6 <manvolnum>3</manvolnum>
7 </refmeta>
8 <refnamediv>
9 <refname>talloc</refname>
10 <refpurpose>hierarchical reference counted memory pool system with destructors</refpurpose>
11 </refnamediv>
12 <refsynopsisdiv>
13 <synopsis>#include <talloc.h></synopsis>
14 </refsynopsisdiv>
15 <refsect1><title>DESCRIPTION</title>
16 <para>
17 If you are used to talloc from Samba3 then please read this
18 carefully, as talloc has changed a lot.
19 </para>
20 <para>
21 The new talloc is a hierarchical, reference counted memory pool
22 system with destructors. Quite a mouthful really, but not too bad
23 once you get used to it.
24 </para>
25 <para>
26 Perhaps the biggest change from Samba3 is that there is no
27 distinction between a "talloc context" and a "talloc pointer". Any
28 pointer returned from talloc() is itself a valid talloc context.
29 This means you can do this:
30 </para>
31 <programlisting>
32 struct foo *X = talloc(mem_ctx, struct foo);
33 X->name = talloc_strdup(X, "foo");
34 </programlisting>
35 <para>
36 and the pointer <literal role="code">X->name</literal>
37 would be a "child" of the talloc context <literal
38 role="code">X</literal> which is itself a child of
39 <literal role="code">mem_ctx</literal>. So if you do
40 <literal role="code">talloc_free(mem_ctx)</literal> then
41 it is all destroyed, whereas if you do <literal
42 role="code">talloc_free(X)</literal> then just <literal
43 role="code">X</literal> and <literal
44 role="code">X->name</literal> are destroyed, and if
45 you do <literal
46 role="code">talloc_free(X->name)</literal> then just
47 the name element of <literal role="code">X</literal> is
48 destroyed.
49 </para>
50 <para>
51 If you think about this, then what this effectively gives you is an
52 n-ary tree, where you can free any part of the tree with
53 talloc_free().
54 </para>
55 <para>
56 If you find this confusing, then I suggest you run the <literal
57 role="code">testsuite</literal> program to watch talloc
58 in action. You may also like to add your own tests to <literal
59 role="code">testsuite.c</literal> to clarify how some
60 particular situation is handled.
61 </para>
62 </refsect1>
63 <refsect1><title>TALLOC API</title>
64 <para>
65 The following is a complete guide to the talloc API. Read it all at
66 least twice.
67 </para>
68 <refsect2><title>(type *)talloc(const void *ctx, type);</title>
69 <para>
70 The talloc() macro is the core of the talloc library. It takes a
71 memory <emphasis role="italic">ctx</emphasis> and a <emphasis
72 role="italic">type</emphasis>, and returns a pointer to a new
73 area of memory of the given <emphasis
74 role="italic">type</emphasis>.
75 </para>
76 <para>
77 The returned pointer is itself a talloc context, so you can use
78 it as the <emphasis role="italic">ctx</emphasis> argument to more
79 calls to talloc() if you wish.
80 </para>
81 <para>
82 The returned pointer is a "child" of the supplied context. This
83 means that if you talloc_free() the <emphasis
84 role="italic">ctx</emphasis> then the new child disappears as
85 well. Alternatively you can free just the child.
86 </para>
87 <para>
88 The <emphasis role="italic">ctx</emphasis> argument to talloc()
89 can be NULL, in which case a new top level context is created.
90 </para>
91 </refsect2>
92 <refsect2><title>void *talloc_size(const void *ctx, size_t size);</title>
93 <para>
94 The function talloc_size() should be used when you don't have a
95 convenient type to pass to talloc(). Unlike talloc(), it is not
96 type safe (as it returns a void *), so you are on your own for
97 type checking.
98 </para>
99 </refsect2>
100 <refsect2><title>(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);</title>
101 <para>
102 The talloc_ptrtype() macro should be used when you have a pointer and
103 want to allocate memory to point at with this pointer. When compiling
104 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
105 and talloc_get_name() will return the current location in the source file.
106 and not the type.
107 </para>
108 </refsect2>
109 <refsect2><title>int talloc_free(void *ptr);</title>
110 <para>
111 The talloc_free() function frees a piece of talloc memory, and
112 all its children. You can call talloc_free() on any pointer
113 returned by talloc().
114 </para>
115 <para>
116 The return value of talloc_free() indicates success or failure,
117 with 0 returned for success and -1 for failure. The only
118 possible failure condition is if <emphasis
119 role="italic">ptr</emphasis> had a destructor attached to it and
120 the destructor returned -1. See <link
121 linkend="talloc_set_destructor"><quote>talloc_set_destructor()</quote></link>
122 for details on destructors.
123 </para>
124 <para>
125 If this pointer has an additional parent when talloc_free() is
126 called then the memory is not actually released, but instead the
127 most recently established parent is destroyed. See <link
128 linkend="talloc_reference"><quote>talloc_reference()</quote></link>
129 for details on establishing additional parents.
130 </para>
131 <para>
132 For more control on which parent is removed, see <link
133 linkend="talloc_unlink"><quote>talloc_unlink()</quote></link>.
134 </para>
135 <para>
136 talloc_free() operates recursively on its children.
137 </para>
138 <para>
139 From the 2.0 version of talloc, as a special case,
140 talloc_free() is refused on pointers that have more than one
141 parent, as talloc would have no way of knowing which parent
142 should be removed. To free a pointer that has more than one
143 parent please use talloc_unlink().
144 </para>
145 <para>
146 To help you find problems in your code caused by this behaviour, if
147 you do try and free a pointer with more than one parent then the
148 talloc logging function will be called to give output like this:
149 </para>
150 <para>
151 <screen format="linespecific">
152 ERROR: talloc_free with references at some_dir/source/foo.c:123
153 reference at some_dir/source/other.c:325
154 reference at some_dir/source/third.c:121
155 </screen>
156 </para>
157 <para>
158 Please see the documentation for talloc_set_log_fn() and
159 talloc_set_log_stderr() for more information on talloc logging
160 functions.
161 </para>
162 </refsect2>
163 <refsect2 id="talloc_reference"><title>void *talloc_reference(const void *ctx, const void *ptr);</title>
164 <para>
165 The talloc_reference() function makes <emphasis
166 role="italic">ctx</emphasis> an additional parent of <emphasis
167 role="italic">ptr</emphasis>.
168 </para>
169 <para>
170 The return value of talloc_reference() is always the original
171 pointer <emphasis role="italic">ptr</emphasis>, unless talloc ran
172 out of memory in creating the reference in which case it will
173 return NULL (each additional reference consumes around 48 bytes
174 of memory on intel x86 platforms).
175 </para>
176 <para>
177 If <emphasis role="italic">ptr</emphasis> is NULL, then the
178 function is a no-op, and simply returns NULL.
179 </para>
180 <para>
181 After creating a reference you can free it in one of the
182 following ways:
183 </para>
184 <para>
185 <itemizedlist>
186 <listitem>
187 <para>
188 you can talloc_free() any parent of the original pointer.
189 That will reduce the number of parents of this pointer by 1,
190 and will cause this pointer to be freed if it runs out of
191 parents.
192 </para>
193 </listitem>
194 <listitem>
195 <para>
196 you can talloc_free() the pointer itself. That will destroy
197 the most recently established parent to the pointer and leave
198 the pointer as a child of its current parent.
199 </para>
200 </listitem>
201 </itemizedlist>
202 </para>
203 <para>
204 For more control on which parent to remove, see <link
205 linkend="talloc_unlink"><quote>talloc_unlink()</quote></link>.
206 </para>
207 </refsect2>
208 <refsect2 id="talloc_unlink"><title>int talloc_unlink(const void *ctx, const void *ptr);</title>
209 <para>
210 The talloc_unlink() function removes a specific parent from
211 <emphasis role="italic">ptr</emphasis>. The <emphasis
212 role="italic">ctx</emphasis> passed must either be a context used
213 in talloc_reference() with this pointer, or must be a direct
214 parent of ptr.
215 </para>
216 <para>
217 Note that if the parent has already been removed using
218 talloc_free() then this function will fail and will return -1.
219 Likewise, if <emphasis role="italic">ptr</emphasis> is NULL, then
220 the function will make no modifications and return -1.
221 </para>
222 <para>
223 Usually you can just use talloc_free() instead of
224 talloc_unlink(), but sometimes it is useful to have the
225 additional control on which parent is removed.
226 </para>
227 </refsect2>
228 <refsect2 id="talloc_set_destructor"><title>void talloc_set_destructor(const void *ptr, int (*destructor)(void *));</title>
229 <para>
230 The function talloc_set_destructor() sets the <emphasis
231 role="italic">destructor</emphasis> for the pointer <emphasis
232 role="italic">ptr</emphasis>. A <emphasis
233 role="italic">destructor</emphasis> is a function that is called
234 when the memory used by a pointer is about to be released. The
235 destructor receives <emphasis role="italic">ptr</emphasis> as an
236 argument, and should return 0 for success and -1 for failure.
237 </para>
238 <para>
239 The <emphasis role="italic">destructor</emphasis> can do anything
240 it wants to, including freeing other pieces of memory. A common
241 use for destructors is to clean up operating system resources
242 (such as open file descriptors) contained in the structure the
243 destructor is placed on.
244 </para>
245 <para>
246 You can only place one destructor on a pointer. If you need more
247 than one destructor then you can create a zero-length child of
248 the pointer and place an additional destructor on that.
249 </para>
250 <para>
251 To remove a destructor call talloc_set_destructor() with NULL for
252 the destructor.
253 </para>
254 <para>
255 If your destructor attempts to talloc_free() the pointer that it
256 is the destructor for then talloc_free() will return -1 and the
257 free will be ignored. This would be a pointless operation
258 anyway, as the destructor is only called when the memory is just
259 about to go away.
260 </para>
261 </refsect2>
262 <refsect2><title>int talloc_increase_ref_count(const void *<emphasis role="italic">ptr</emphasis>);</title>
263 <para>
264 The talloc_increase_ref_count(<emphasis
265 role="italic">ptr</emphasis>) function is exactly equivalent to:
266 </para>
267 <programlisting>talloc_reference(NULL, ptr);</programlisting>
268 <para>
269 You can use either syntax, depending on which you think is
270 clearer in your code.
271 </para>
272 <para>
273 It returns 0 on success and -1 on failure.
274 </para>
275 </refsect2>
276 <refsect2><title>size_t talloc_reference_count(const void *<emphasis role="italic">ptr</emphasis>);</title>
277 <para>
278 Return the number of references to the pointer.
279 </para>
280 </refsect2>
281 <refsect2 id="talloc_set_name"><title>void talloc_set_name(const void *ptr, const char *fmt, ...);</title>
282 <para>
283 Each talloc pointer has a "name". The name is used principally
284 for debugging purposes, although it is also possible to set and
285 get the name on a pointer in as a way of "marking" pointers in
286 your code.
287 </para>
288 <para>
289 The main use for names on pointer is for "talloc reports". See
290 <link
291 linkend="talloc_report"><quote>talloc_report_depth_cb()</quote></link>,
292 <link
293 linkend="talloc_report"><quote>talloc_report_depth_file()</quote></link>,
294 <link
295 linkend="talloc_report"><quote>talloc_report()</quote></link>
296 <link
297 linkend="talloc_report"><quote>talloc_report()</quote></link>
298 and <link
299 linkend="talloc_report_full"><quote>talloc_report_full()</quote></link>
300 for details. Also see <link
301 linkend="talloc_enable_leak_report"><quote>talloc_enable_leak_report()</quote></link>
302 and <link
303 linkend="talloc_enable_leak_report_full"><quote>talloc_enable_leak_report_full()</quote></link>.
304 </para>
305 <para>
306 The talloc_set_name() function allocates memory as a child of the
307 pointer. It is logically equivalent to:
308 </para>
309 <programlisting>talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));</programlisting>
310 <para>
311 Note that multiple calls to talloc_set_name() will allocate more
312 memory without releasing the name. All of the memory is released
313 when the ptr is freed using talloc_free().
314 </para>
315 </refsect2>
316 <refsect2><title>void talloc_set_name_const(const void *<emphasis role="italic">ptr</emphasis>, const char *<emphasis role="italic">name</emphasis>);</title>
317 <para>
318 The function talloc_set_name_const() is just like
319 talloc_set_name(), but it takes a string constant, and is much
320 faster. It is extensively used by the "auto naming" macros, such
321 as talloc_p().
322 </para>
323 <para>
324 This function does not allocate any memory. It just copies the
325 supplied pointer into the internal representation of the talloc
326 ptr. This means you must not pass a <emphasis
327 role="italic">name</emphasis> pointer to memory that will
328 disappear before <emphasis role="italic">ptr</emphasis> is freed
329 with talloc_free().
330 </para>
331 </refsect2>
332 <refsect2><title>void *talloc_named(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
333 <para>
334 The talloc_named() function creates a named talloc pointer. It
335 is equivalent to:
336 </para>
337 <programlisting>ptr = talloc_size(ctx, size);
338 talloc_set_name(ptr, fmt, ....);</programlisting>
339 </refsect2>
340 <refsect2><title>void *talloc_named_const(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>, const char *<emphasis role="italic">name</emphasis>);</title>
341 <para>
342 This is equivalent to:
343 </para>
344 <programlisting>ptr = talloc_size(ctx, size);
345 talloc_set_name_const(ptr, name);</programlisting>
346 </refsect2>
347 <refsect2><title>const char *talloc_get_name(const void *<emphasis role="italic">ptr</emphasis>);</title>
348 <para>
349 This returns the current name for the given talloc pointer,
350 <emphasis role="italic">ptr</emphasis>. See <link
351 linkend="talloc_set_name"><quote>talloc_set_name()</quote></link>
352 for details.
353 </para>
354 </refsect2>
355 <refsect2><title>void *talloc_init(const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
356 <para>
357 This function creates a zero length named talloc context as a top
358 level context. It is equivalent to:
359 </para>
360 <programlisting>talloc_named(NULL, 0, fmt, ...);</programlisting>
361 </refsect2>
362 <refsect2><title>void *talloc_new(void *<emphasis role="italic">ctx</emphasis>);</title>
363 <para>
364 This is a utility macro that creates a new memory context hanging
365 off an existing context, automatically naming it "talloc_new:
366 __location__" where __location__ is the source line it is called
367 from. It is particularly useful for creating a new temporary
368 working context.
369 </para>
370 </refsect2>
371 <refsect2><title>(<emphasis role="italic">type</emphasis> *)talloc_realloc(const void *<emphasis role="italic">ctx</emphasis>, void *<emphasis role="italic">ptr</emphasis>, <emphasis role="italic">type</emphasis>, <emphasis role="italic">count</emphasis>);</title>
372 <para>
373 The talloc_realloc() macro changes the size of a talloc pointer.
374 It has the following equivalences:
375 </para>
376 <programlisting>talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
377 talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);</programlisting>
378 <para>
379 The <emphasis role="italic">ctx</emphasis> argument is only used
380 if <emphasis role="italic">ptr</emphasis> is not NULL, otherwise
381 it is ignored.
382 </para>
383 <para>
384 talloc_realloc() returns the new pointer, or NULL on failure.
385 The call will fail either due to a lack of memory, or because the
386 pointer has more than one parent (see <link
387 linkend="talloc_reference"><quote>talloc_reference()</quote></link>).
388 </para>
389 </refsect2>
390 <refsect2><title>void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);</title>
391 <para>
392 the talloc_realloc_size() function is useful when the type is not
393 known so the type-safe talloc_realloc() cannot be used.
394 </para>
395 </refsect2>
396 <refsect2><title>TYPE *talloc_steal(const void *<emphasis role="italic">new_ctx</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>);</title>
397 <para>
398 The talloc_steal() function changes the parent context of a
399 talloc pointer. It is typically used when the context that the
400 pointer is currently a child of is going to be freed and you wish
401 to keep the memory for a longer time.
402 </para>
403 <para>
404 The talloc_steal() function returns the pointer that you pass it.
405 It does not have any failure modes.
406 </para>
407 <para>
408 It is possible to produce loops in the parent/child
409 relationship if you are not careful with talloc_steal(). No
410 guarantees are provided as to your sanity or the safety of your
411 data if you do this.
412 </para>
413 <para>
414 Note that if you try and call talloc_steal() on a pointer that has
415 more than one parent then the result is ambiguous. Talloc will choose
416 to remove the parent that is currently indicated by talloc_parent()
417 and replace it with the chosen parent. You will also get a message
418 like this via the talloc logging functions:
419 </para>
420 <para>
421 <screen format="linespecific">
422 WARNING: talloc_steal with references at some_dir/source/foo.c:123
423 reference at some_dir/source/other.c:325
424 reference at some_dir/source/third.c:121
425 </screen>
426 </para>
427 <para>
428 To unambiguously change the parent of a pointer please see
429 the
430 function <link linkend="talloc_reference"><quote>talloc_reparent()</quote></link>. See
431 the talloc_set_log_fn() documentation for more information
432 on talloc logging.
433 </para>
434 </refsect2>
435 <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>
436 <para>
437 The talloc_reparent() function changes the parent context of a talloc
438 pointer. It is typically used when the context that the pointer is
439 currently a child of is going to be freed and you wish to keep the
440 memory for a longer time.
441 </para>
442 <para>
443 The talloc_reparent() function returns the pointer that you pass it. It
444 does not have any failure modes.
445 </para>
446 <para>
447 The difference between talloc_reparent() and talloc_steal() is that
448 talloc_reparent() can specify which parent you wish to change. This is
449 useful when a pointer has multiple parents via references.
450 </para>
451 </refsect2>
452 <refsect2><title>TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>);</title>
453 <para>
454 The talloc_move() function is a wrapper around
455 talloc_steal() which zeros the source pointer after the
456 move. This avoids a potential source of bugs where a
457 programmer leaves a pointer in two structures, and uses the
458 pointer from the old structure after it has been moved to a
459 new one.
460 </para>
461 </refsect2>
462 <refsect2><title>size_t talloc_total_size(const void *<emphasis role="italic">ptr</emphasis>);</title>
463 <para>
464 The talloc_total_size() function returns the total size in bytes
465 used by this pointer and all child pointers. Mostly useful for
466 debugging.
467 </para>
468 <para>
469 Passing NULL is allowed, but it will only give a meaningful
470 result if talloc_enable_leak_report() or
471 talloc_enable_leak_report_full() has been called.
472 </para>
473 </refsect2>
474 <refsect2><title>size_t talloc_total_blocks(const void *<emphasis role="italic">ptr</emphasis>);</title>
475 <para>
476 The talloc_total_blocks() function returns the total memory block
477 count used by this pointer and all child pointers. Mostly useful
478 for debugging.
479 </para>
480 <para>
481 Passing NULL is allowed, but it will only give a meaningful
482 result if talloc_enable_leak_report() or
483 talloc_enable_leak_report_full() has been called.
484 </para>
485 </refsect2>
486 <refsect2 id="talloc_report"><title>void talloc_report(const void *ptr, FILE *f);</title>
487 <para>
488 The talloc_report() function prints a summary report of all
489 memory used by <emphasis role="italic">ptr</emphasis>. One line
490 of report is printed for each immediate child of ptr, showing the
491 total memory and number of blocks used by that child.
492 </para>
493 <para>
494 You can pass NULL for the pointer, in which case a report is
495 printed for the top level memory context, but only if
496 talloc_enable_leak_report() or talloc_enable_leak_report_full()
497 has been called.
498 </para>
499 </refsect2>
500 <refsect2 id="talloc_report_full"><title>void talloc_report_full(const void *<emphasis role="italic">ptr</emphasis>, FILE *<emphasis role="italic">f</emphasis>);</title>
501 <para>
502 This provides a more detailed report than talloc_report(). It
503 will recursively print the entire tree of memory referenced by
504 the pointer. References in the tree are shown by giving the name
505 of the pointer that is referenced.
506 </para>
507 <para>
508 You can pass NULL for the pointer, in which case a report is
509 printed for the top level memory context, but only if
510 talloc_enable_leak_report() or talloc_enable_leak_report_full()
511 has been called.
512 </para>
513 </refsect2>
514 <refsect2 id="talloc_report_depth_cb">
515 <funcsynopsis><funcprototype>
516 <funcdef>void <function>talloc_report_depth_cb</function></funcdef>
517 <paramdef><parameter>const void *ptr</parameter></paramdef>
518 <paramdef><parameter>int depth</parameter></paramdef>
519 <paramdef><parameter>int max_depth</parameter></paramdef>
520 <paramdef><parameter>void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *priv)</parameter></paramdef>
521 <paramdef><parameter>void *priv</parameter></paramdef>
522 </funcprototype></funcsynopsis>
523 <para>
524 This provides a more flexible reports than talloc_report(). It
525 will recursively call the callback for the entire tree of memory
526 referenced by the pointer. References in the tree are passed with
527 <emphasis role="italic">is_ref = 1</emphasis> and the pointer that is referenced.
528 </para>
529 <para>
530 You can pass NULL for the pointer, in which case a report is
531 printed for the top level memory context, but only if
532 talloc_enable_leak_report() or talloc_enable_leak_report_full()
533 has been called.
534 </para>
535 <para>
536 The recursion is stopped when depth >= max_depth.
537 max_depth = -1 means only stop at leaf nodes.
538 </para>
539 </refsect2>
540 <refsect2 id="talloc_report_depth_file">
541 <funcsynopsis><funcprototype>
542 <funcdef>void <function>talloc_report_depth_file</function></funcdef>
543 <paramdef><parameter>const void *ptr</parameter></paramdef>
544 <paramdef><parameter>int depth</parameter></paramdef>
545 <paramdef><parameter>int max_depth</parameter></paramdef>
546 <paramdef><parameter>FILE *f</parameter></paramdef>
547 </funcprototype></funcsynopsis>
548 <para>
549 This provides a more flexible reports than talloc_report(). It
550 will let you specify the depth and max_depth.
551 </para>
552 </refsect2>
553 <refsect2 id="talloc_enable_leak_report"><title>void talloc_enable_leak_report(void);</title>
554 <para>
555 This enables calling of talloc_report(NULL, stderr) when the
556 program exits. In Samba4 this is enabled by using the
557 --leak-report command line option.
558 </para>
559 <para>
560 For it to be useful, this function must be called before any
561 other talloc function as it establishes a "null context" that
562 acts as the top of the tree. If you don't call this function
563 first then passing NULL to talloc_report() or
564 talloc_report_full() won't give you the full tree printout.
565 </para>
566 <para>
567 Here is a typical talloc report:
568 </para>
569 <screen format="linespecific">talloc report on 'null_context' (total 267 bytes in 15 blocks)
570 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
571 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
572 iconv(UTF8,CP850) contains 42 bytes in 2 blocks
573 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
574 iconv(CP850,UTF8) contains 42 bytes in 2 blocks
575 iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
576 iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
577 </screen>
578 </refsect2>
579 <refsect2 id="talloc_enable_leak_report_full"><title>void talloc_enable_leak_report_full(void);</title>
580 <para>
581 This enables calling of talloc_report_full(NULL, stderr) when the
582 program exits. In Samba4 this is enabled by using the
583 --leak-report-full command line option.
584 </para>
585 <para>
586 For it to be useful, this function must be called before any
587 other talloc function as it establishes a "null context" that
588 acts as the top of the tree. If you don't call this function
589 first then passing NULL to talloc_report() or
590 talloc_report_full() won't give you the full tree printout.
591 </para>
592 <para>
593 Here is a typical full report:
594 </para>
595 <screen format="linespecific">full talloc report on 'root' (total 18 bytes in 8 blocks)
596 p1 contains 18 bytes in 7 blocks (ref 0)
597 r1 contains 13 bytes in 2 blocks (ref 0)
598 reference to: p2
599 p2 contains 1 bytes in 1 blocks (ref 1)
600 x3 contains 1 bytes in 1 blocks (ref 0)
601 x2 contains 1 bytes in 1 blocks (ref 0)
602 x1 contains 1 bytes in 1 blocks (ref 0)
603 </screen>
604 </refsect2>
605 <refsect2><title>(<emphasis role="italic">type</emphasis> *)talloc_zero(const void *<emphasis role="italic">ctx</emphasis>, <emphasis role="italic">type</emphasis>);</title>
606 <para>
607 The talloc_zero() macro is equivalent to:
608 </para>
609 <programlisting>ptr = talloc(ctx, type);
610 if (ptr) memset(ptr, 0, sizeof(type));</programlisting>
611 </refsect2>
612 <refsect2><title>void *talloc_zero_size(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>)</title>
613 <para>
614 The talloc_zero_size() function is useful when you don't have a
615 known type.
616 </para>
617 </refsect2>
618 <refsect2><title>void *talloc_memdup(const void *<emphasis role="italic">ctx</emphasis>, const void *<emphasis role="italic">p</emphasis>, size_t size);</title>
619 <para>
620 The talloc_memdup() function is equivalent to:
621 </para>
622 <programlisting>ptr = talloc_size(ctx, size);
623 if (ptr) memcpy(ptr, p, size);</programlisting>
624 </refsect2>
625 <refsect2><title>char *talloc_strdup(const void *<emphasis role="italic">ctx</emphasis>, const char *<emphasis role="italic">p</emphasis>);</title>
626 <para>
627 The talloc_strdup() function is equivalent to:
628 </para>
629 <programlisting>ptr = talloc_size(ctx, strlen(p)+1);
630 if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
631 <para>
632 This function sets the name of the new pointer to the passed
633 string. This is equivalent to:
634 </para>
635 <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
636 </refsect2>
637 <refsect2><title>char *talloc_strndup(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">p</emphasis>, size_t <emphasis role="italic">n</emphasis>);</title>
638 <para>
639 The talloc_strndup() function is the talloc equivalent of the C
640 library function strndup(3).
641 </para>
642 <para>
643 This function sets the name of the new pointer to the passed
644 string. This is equivalent to:
645 </para>
646 <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
647 </refsect2>
648 <refsect2><title>char *talloc_vasprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, va_list <emphasis role="italic">ap</emphasis>);</title>
649 <para>
650 The talloc_vasprintf() function is the talloc equivalent of the C
651 library function vasprintf(3).
652 </para>
653 <para>
654 This function sets the name of the new pointer to the new
655 string. This is equivalent to:
656 </para>
657 <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
658 </refsect2>
659 <refsect2><title>char *talloc_asprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
660 <para>
661 The talloc_asprintf() function is the talloc equivalent of the C
662 library function asprintf(3).
663 </para>
664 <para>
665 This function sets the name of the new pointer to the passed
666 string. This is equivalent to:
667 </para>
668 <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
669 </refsect2>
670 <refsect2><title>char *talloc_asprintf_append(char *s, const char *fmt, ...);</title>
671 <para>
672 The talloc_asprintf_append() function appends the given formatted
673 string to the given string.
674 </para>
675 <para>
676 This function sets the name of the new pointer to the new
677 string. This is equivalent to:
678 </para>
679 <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
680 </refsect2>
681 <refsect2><title>(type *)talloc_array(const void *ctx, type, unsigned int count);</title>
682 <para>
683 The talloc_array() macro is equivalent to:
684 </para>
685 <programlisting>(type *)talloc_size(ctx, sizeof(type) * count);</programlisting>
686 <para>
687 except that it provides integer overflow protection for the
688 multiply, returning NULL if the multiply overflows.
689 </para>
690 </refsect2>
691 <refsect2><title>void *talloc_array_size(const void *ctx, size_t size, unsigned int count);</title>
692 <para>
693 The talloc_array_size() function is useful when the type is not
694 known. It operates in the same way as talloc_array(), but takes a
695 size instead of a type.
696 </para>
697 </refsect2>
698 <refsect2><title>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);</title>
699 <para>
700 The talloc_ptrtype() macro should be used when you have a pointer to an array
701 and want to allocate memory of an array to point at with this pointer. When compiling
702 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
703 and talloc_get_name() will return the current location in the source file.
704 and not the type.
705 </para>
706 </refsect2>
707 <refsect2><title>void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size)</title>
708 <para>
709 This is a non-macro version of talloc_realloc(), which is useful
710 as libraries sometimes want a realloc function pointer. A
711 realloc(3) implementation encapsulates the functionality of
712 malloc(3), free(3) and realloc(3) in one call, which is why it is
713 useful to be able to pass around a single function pointer.
714 </para>
715 </refsect2>
716 <refsect2><title>void *talloc_autofree_context(void);</title>
717 <para>
718 This is a handy utility function that returns a talloc context
719 which will be automatically freed on program exit. This can be
720 used to reduce the noise in memory leak reports.
721 </para>
722 </refsect2>
723 <refsect2><title>void *talloc_check_name(const void *ptr, const char *name);</title>
724 <para>
725 This function checks if a pointer has the specified <emphasis
726 role="italic">name</emphasis>. If it does then the pointer is
727 returned. It it doesn't then NULL is returned.
728 </para>
729 </refsect2>
730 <refsect2><title>(type *)talloc_get_type(const void *ptr, type);</title>
731 <para>
732 This macro allows you to do type checking on talloc pointers. It
733 is particularly useful for void* private pointers. It is
734 equivalent to this:
735 </para>
736 <programlisting>(type *)talloc_check_name(ptr, #type)</programlisting>
737 </refsect2>
738 <refsect2><title>talloc_set_type(const void *ptr, type);</title>
739 <para>
740 This macro allows you to force the name of a pointer to be a
741 particular <emphasis>type</emphasis>. This can be
742 used in conjunction with talloc_get_type() to do type checking on
743 void* pointers.
744 </para>
745 <para>
746 It is equivalent to this:
747 </para>
748 <programlisting>talloc_set_name_const(ptr, #type)</programlisting>
749 </refsect2>
750 <refsect2><title>talloc_set_log_fn(void (*log_fn)(const char *message));</title>
751 <para>
752 This function sets a logging function that talloc will use for
753 warnings and errors. By default talloc will not print any warnings or
754 errors.
755 </para>
756 </refsect2>
757 <refsect2><title>talloc_set_log_stderr(void);</title>
758 <para>
759 This sets the talloc log function to write log messages to stderr
760 </para>
761 </refsect2>
762 </refsect1>
763 <refsect1><title>PERFORMANCE</title>
764 <para>
765 All the additional features of talloc(3) over malloc(3) do come at a
766 price. We have a simple performance test in Samba4 that measures
767 talloc() versus malloc() performance, and it seems that talloc() is
768 about 10% slower than malloc() on my x86 Debian Linux box. For
769 Samba, the great reduction in code complexity that we get by using
770 talloc makes this worthwhile, especially as the total overhead of
771 talloc/malloc in Samba is already quite small.
772 </para>
773 </refsect1>
774 <refsect1><title>SEE ALSO</title>
775 <para>
776 malloc(3), strndup(3), vasprintf(3), asprintf(3),
777 <ulink url="http://talloc.samba.org/"/>
778 </para>
779 </refsect1>
780 <refsect1><title>COPYRIGHT/LICENSE</title>
781 <para>
782 Copyright (C) Andrew Tridgell 2004
783 </para>
784 <para>
785 This program is free software; you can redistribute it and/or modify
786 it under the terms of the GNU General Public License as published by
787 the Free Software Foundation; either version 3 of the License, or (at
788 your option) any later version.
789 </para>
790 <para>
791 This program is distributed in the hope that it will be useful, but
792 WITHOUT ANY WARRANTY; without even the implied warranty of
793 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
794 General Public License for more details.
795 </para>
796 <para>
797 You should have received a copy of the GNU General Public License
798 along with this program; if not, see http://www.gnu.org/licenses/.
799 </para>
800 </refsect1>
801 </refentry>