9 The most current version of this document is available at
10 http://samba.org/ftp/unpacked/talloc/talloc_guide.txt
12 If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
13 this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
14 Samba4 talloc has been ported back to Samba3, so this guide applies to both.
16 The new talloc is a hierarchical, reference counted memory pool system
17 with destructors. Quite a mouthful really, but not too bad once you
20 Perhaps the biggest change from Samba3 is that there is no distinction
21 between a "talloc context" and a "talloc pointer". Any pointer
22 returned from talloc() is itself a valid talloc context. This means
25 struct foo *X = talloc(mem_ctx, struct foo);
26 X->name = talloc_strdup(X, "foo");
28 and the pointer X->name would be a "child" of the talloc context "X"
29 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
30 then it is all destroyed, whereas if you do talloc_free(X) then just X
31 and X->name are destroyed, and if you do talloc_free(X->name) then
32 just the name element of X is destroyed.
34 If you think about this, then what this effectively gives you is an
35 n-ary tree, where you can free any part of the tree with
38 If you find this confusing, then I suggest you run the testsuite to
39 watch talloc in action. You may also like to add your own tests to
40 testsuite.c to clarify how some particular situation is handled.
46 All the additional features of talloc() over malloc() do come at a
47 price. We have a simple performance test in Samba4 that measures
48 talloc() versus malloc() performance, and it seems that talloc() is
49 about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
50 the great reduction in code complexity that we get by using talloc
51 makes this worthwhile, especially as the total overhead of
52 talloc/malloc in Samba is already quite small.
58 The following is a complete guide to the talloc API. Read it all at
64 talloc itself does not deal with threads. It is thread-safe (assuming
65 the underlying "malloc" is), as long as each thread uses different
67 If two threads uses the same context then they need to synchronize in
68 order to be safe. In particular:
69 - when using talloc_enable_leak_report(), giving directly NULL as a
70 parent context implicitly refers to a hidden "null context" global
71 variable, so this should not be used in a multi-threaded environment
72 without proper synchronization ;
73 - the context returned by talloc_autofree_context() is also global so
74 shouldn't be used by several threads simultaneously without
77 talloc and shared objects
78 -------------------------
80 talloc can be used in shared objects. Special care needs to be taken
81 to never use talloc_autofree_context() in code that might be loaded
82 with dlopen() and unloaded with dlclose(), as talloc_autofree_context()
83 internally uses atexit(3). Some platforms like modern Linux handles
84 this fine, but for example FreeBSD does not deal well with dlopen()
85 and atexit() used simultaneously: dlclose() does not clean up the list
86 of atexit-handlers, so when the program exits the code that was
87 registered from within talloc_autofree_context() is gone, the program
91 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
92 (type *)talloc(const void *context, type);
94 The talloc() macro is the core of the talloc library. It takes a
95 memory context and a type, and returns a pointer to a new area of
96 memory of the given type.
98 The returned pointer is itself a talloc context, so you can use it as
99 the context argument to more calls to talloc if you wish.
101 The returned pointer is a "child" of the supplied context. This means
102 that if you talloc_free() the context then the new child disappears as
103 well. Alternatively you can free just the child.
105 The context argument to talloc() can be NULL, in which case a new top
106 level context is created.
109 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
110 void *talloc_size(const void *context, size_t size);
112 The function talloc_size() should be used when you don't have a
113 convenient type to pass to talloc(). Unlike talloc(), it is not type
114 safe (as it returns a void *), so you are on your own for type checking.
116 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
117 (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
119 The talloc_ptrtype() macro should be used when you have a pointer and
120 want to allocate memory to point at with this pointer. When compiling
121 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
122 and talloc_get_name() will return the current location in the source file.
125 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
126 int talloc_free(void *ptr);
128 The talloc_free() function frees a piece of talloc memory, and all its
129 children. You can call talloc_free() on any pointer returned by
132 The return value of talloc_free() indicates success or failure, with 0
133 returned for success and -1 for failure. The only possible failure
134 condition is if the pointer had a destructor attached to it and the
135 destructor returned -1. See talloc_set_destructor() for details on
138 If this pointer has an additional parent when talloc_free() is called
139 then the memory is not actually released, but instead the most
140 recently established parent is destroyed. See talloc_reference() for
141 details on establishing additional parents.
143 For more control on which parent is removed, see talloc_unlink()
145 talloc_free() operates recursively on its children.
147 From the 2.0 version of talloc, as a special case, talloc_free() is
148 refused on pointers that have more than one parent, as talloc would
149 have no way of knowing which parent should be removed. To free a
150 pointer that has more than one parent please use talloc_unlink().
152 To help you find problems in your code caused by this behaviour, if
153 you do try and free a pointer with more than one parent then the
154 talloc logging function will be called to give output like this:
156 ERROR: talloc_free with references at some_dir/source/foo.c:123
157 reference at some_dir/source/other.c:325
158 reference at some_dir/source/third.c:121
160 Please see the documentation for talloc_set_log_fn() and
161 talloc_set_log_stderr() for more information on talloc logging
164 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
165 int talloc_free_children(void *ptr);
167 The talloc_free_children() walks along the list of all children of a
168 talloc context and talloc_free()s only the children, not the context
172 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
173 void *talloc_reference(const void *context, const void *ptr);
175 The talloc_reference() function makes "context" an additional parent
178 The return value of talloc_reference() is always the original pointer
179 "ptr", unless talloc ran out of memory in creating the reference in
180 which case it will return NULL (each additional reference consumes
181 around 48 bytes of memory on intel x86 platforms).
183 If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
185 After creating a reference you can free it in one of the following
188 - you can talloc_free() any parent of the original pointer. That
189 will reduce the number of parents of this pointer by 1, and will
190 cause this pointer to be freed if it runs out of parents.
192 - you can talloc_free() the pointer itself. That will destroy the
193 most recently established parent to the pointer and leave the
194 pointer as a child of its current parent.
196 For more control on which parent to remove, see talloc_unlink()
199 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
200 int talloc_unlink(const void *context, const void *ptr);
202 The talloc_unlink() function removes a specific parent from ptr. The
203 context passed must either be a context used in talloc_reference()
204 with this pointer, or must be a direct parent of ptr.
206 Note that if the parent has already been removed using talloc_free()
207 then this function will fail and will return -1. Likewise, if "ptr"
208 is NULL, then the function will make no modifications and return -1.
210 Usually you can just use talloc_free() instead of talloc_unlink(), but
211 sometimes it is useful to have the additional control on which parent
215 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
216 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
218 The function talloc_set_destructor() sets the "destructor" for the
219 pointer "ptr". A destructor is a function that is called when the
220 memory used by a pointer is about to be released. The destructor
221 receives the pointer as an argument, and should return 0 for success
224 The destructor can do anything it wants to, including freeing other
225 pieces of memory. A common use for destructors is to clean up
226 operating system resources (such as open file descriptors) contained
227 in the structure the destructor is placed on.
229 You can only place one destructor on a pointer. If you need more than
230 one destructor then you can create a zero-length child of the pointer
231 and place an additional destructor on that.
233 To remove a destructor call talloc_set_destructor() with NULL for the
236 If your destructor attempts to talloc_free() the pointer that it is
237 the destructor for then talloc_free() will return -1 and the free will
238 be ignored. This would be a pointless operation anyway, as the
239 destructor is only called when the memory is just about to go away.
242 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
243 int talloc_increase_ref_count(const void *ptr);
245 The talloc_increase_ref_count(ptr) function is exactly equivalent to:
247 talloc_reference(NULL, ptr);
249 You can use either syntax, depending on which you think is clearer in
252 It returns 0 on success and -1 on failure.
254 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
255 size_t talloc_reference_count(const void *ptr);
257 Return the number of references to the pointer.
259 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
260 void talloc_set_name(const void *ptr, const char *fmt, ...);
262 Each talloc pointer has a "name". The name is used principally for
263 debugging purposes, although it is also possible to set and get the
264 name on a pointer in as a way of "marking" pointers in your code.
266 The main use for names on pointer is for "talloc reports". See
267 talloc_report() and talloc_report_full() for details. Also see
268 talloc_enable_leak_report() and talloc_enable_leak_report_full().
270 The talloc_set_name() function allocates memory as a child of the
271 pointer. It is logically equivalent to:
272 talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
274 Note that multiple calls to talloc_set_name() will allocate more
275 memory without releasing the name. All of the memory is released when
276 the ptr is freed using talloc_free().
279 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
280 void talloc_set_name_const(const void *ptr, const char *name);
282 The function talloc_set_name_const() is just like talloc_set_name(),
283 but it takes a string constant, and is much faster. It is extensively
284 used by the "auto naming" macros, such as talloc_p().
286 This function does not allocate any memory. It just copies the
287 supplied pointer into the internal representation of the talloc
288 ptr. This means you must not pass a name pointer to memory that will
289 disappear before the ptr is freed with talloc_free().
292 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
293 void *talloc_named(const void *context, size_t size, const char *fmt, ...);
295 The talloc_named() function creates a named talloc pointer. It is
298 ptr = talloc_size(context, size);
299 talloc_set_name(ptr, fmt, ....);
302 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
303 void *talloc_named_const(const void *context, size_t size, const char *name);
305 This is equivalent to::
307 ptr = talloc_size(context, size);
308 talloc_set_name_const(ptr, name);
311 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
312 const char *talloc_get_name(const void *ptr);
314 This returns the current name for the given talloc pointer. See
315 talloc_set_name() for details.
318 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
319 void *talloc_init(const char *fmt, ...);
321 This function creates a zero length named talloc context as a top
322 level context. It is equivalent to::
324 talloc_named(NULL, 0, fmt, ...);
327 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
328 void *talloc_new(void *ctx);
330 This is a utility macro that creates a new memory context hanging
331 off an exiting context, automatically naming it "talloc_new: __location__"
332 where __location__ is the source line it is called from. It is
333 particularly useful for creating a new temporary working context.
336 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
337 (type *)talloc_realloc(const void *context, void *ptr, type, count);
339 The talloc_realloc() macro changes the size of a talloc
340 pointer. The "count" argument is the number of elements of type "type"
341 that you want the resulting pointer to hold.
343 talloc_realloc() has the following equivalences::
345 talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
346 talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
347 talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
349 The "context" argument is only used if "ptr" is NULL, otherwise it is
352 talloc_realloc() returns the new pointer, or NULL on failure. The call
353 will fail either due to a lack of memory, or because the pointer has
354 more than one parent (see talloc_reference()).
357 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
358 void *talloc_realloc_size(const void *context, void *ptr, size_t size);
360 the talloc_realloc_size() function is useful when the type is not
361 known so the typesafe talloc_realloc() cannot be used.
364 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
365 void *talloc_steal(const void *new_ctx, const void *ptr);
367 The talloc_steal() function changes the parent context of a talloc
368 pointer. It is typically used when the context that the pointer is
369 currently a child of is going to be freed and you wish to keep the
370 memory for a longer time.
372 The talloc_steal() function returns the pointer that you pass it. It
373 does not have any failure modes.
375 NOTE: It is possible to produce loops in the parent/child relationship
376 if you are not careful with talloc_steal(). No guarantees are provided
377 as to your sanity or the safety of your data if you do this.
379 talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
381 Note that if you try and call talloc_steal() on a pointer that has
382 more than one parent then the result is ambiguous. Talloc will choose
383 to remove the parent that is currently indicated by talloc_parent()
384 and replace it with the chosen parent. You will also get a message
385 like this via the talloc logging functions:
387 WARNING: talloc_steal with references at some_dir/source/foo.c:123
388 reference at some_dir/source/other.c:325
389 reference at some_dir/source/third.c:121
391 To unambiguously change the parent of a pointer please see the
392 function talloc_reparent(). See the talloc_set_log_fn() documentation
393 for more information on talloc logging.
395 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
396 void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
398 The talloc_reparent() function changes the parent context of a talloc
399 pointer. It is typically used when the context that the pointer is
400 currently a child of is going to be freed and you wish to keep the
401 memory for a longer time.
403 The talloc_reparent() function returns the pointer that you pass it. It
404 does not have any failure modes.
406 The difference between talloc_reparent() and talloc_steal() is that
407 talloc_reparent() can specify which parent you wish to change. This is
408 useful when a pointer has multiple parents via references.
410 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
411 void *talloc_parent(const void *ptr);
413 The talloc_parent() function returns the current talloc parent. This
414 is usually the pointer under which this memory was originally created,
415 but it may have changed due to a talloc_steal() or talloc_reparent()
417 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
418 size_t talloc_total_size(const void *ptr);
420 The talloc_total_size() function returns the total size in bytes used
421 by this pointer and all child pointers. Mostly useful for debugging.
423 Passing NULL is allowed, but it will only give a meaningful result if
424 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
428 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
429 size_t talloc_total_blocks(const void *ptr);
431 The talloc_total_blocks() function returns the total memory block
432 count used by this pointer and all child pointers. Mostly useful for
435 Passing NULL is allowed, but it will only give a meaningful result if
436 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
439 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
440 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
441 void (*callback)(const void *ptr,
442 int depth, int max_depth,
447 This provides a more flexible reports than talloc_report(). It
448 will recursively call the callback for the entire tree of memory
449 referenced by the pointer. References in the tree are passed with
450 is_ref = 1 and the pointer that is referenced.
452 You can pass NULL for the pointer, in which case a report is
453 printed for the top level memory context, but only if
454 talloc_enable_leak_report() or talloc_enable_leak_report_full()
457 The recursion is stopped when depth >= max_depth.
458 max_depth = -1 means only stop at leaf nodes.
461 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
462 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
464 This provides a more flexible reports than talloc_report(). It
465 will let you specify the depth and max_depth.
468 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
469 void talloc_report(const void *ptr, FILE *f);
471 The talloc_report() function prints a summary report of all memory
472 used by ptr. One line of report is printed for each immediate child of
473 ptr, showing the total memory and number of blocks used by that child.
475 You can pass NULL for the pointer, in which case a report is printed
476 for the top level memory context, but only if
477 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
481 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
482 void talloc_report_full(const void *ptr, FILE *f);
484 This provides a more detailed report than talloc_report(). It will
485 recursively print the ensire tree of memory referenced by the
486 pointer. References in the tree are shown by giving the name of the
487 pointer that is referenced.
489 You can pass NULL for the pointer, in which case a report is printed
490 for the top level memory context, but only if
491 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
495 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
496 void talloc_enable_leak_report(void);
498 This enables calling of talloc_report(NULL, stderr) when the program
499 exits. In Samba4 this is enabled by using the --leak-report command
502 For it to be useful, this function must be called before any other
503 talloc function as it establishes a "null context" that acts as the
504 top of the tree. If you don't call this function first then passing
505 NULL to talloc_report() or talloc_report_full() won't give you the
508 Here is a typical talloc report:
510 talloc report on 'null_context' (total 267 bytes in 15 blocks)
511 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
512 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
513 iconv(UTF8,CP850) contains 42 bytes in 2 blocks
514 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
515 iconv(CP850,UTF8) contains 42 bytes in 2 blocks
516 iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
517 iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
520 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
521 void talloc_enable_leak_report_full(void);
523 This enables calling of talloc_report_full(NULL, stderr) when the
524 program exits. In Samba4 this is enabled by using the
525 --leak-report-full command line option.
527 For it to be useful, this function must be called before any other
528 talloc function as it establishes a "null context" that acts as the
529 top of the tree. If you don't call this function first then passing
530 NULL to talloc_report() or talloc_report_full() won't give you the
533 Here is a typical full report:
535 full talloc report on 'root' (total 18 bytes in 8 blocks)
536 p1 contains 18 bytes in 7 blocks (ref 0)
537 r1 contains 13 bytes in 2 blocks (ref 0)
539 p2 contains 1 bytes in 1 blocks (ref 1)
540 x3 contains 1 bytes in 1 blocks (ref 0)
541 x2 contains 1 bytes in 1 blocks (ref 0)
542 x1 contains 1 bytes in 1 blocks (ref 0)
545 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
546 void talloc_enable_null_tracking(void);
548 This enables tracking of the NULL memory context without enabling leak
549 reporting on exit. Useful for when you want to do your own leak
550 reporting call via talloc_report_null_full();
552 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
553 void talloc_disable_null_tracking(void);
555 This disables tracking of the NULL memory context.
557 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
558 (type *)talloc_zero(const void *ctx, type);
560 The talloc_zero() macro is equivalent to::
562 ptr = talloc(ctx, type);
563 if (ptr) memset(ptr, 0, sizeof(type));
566 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
567 void *talloc_zero_size(const void *ctx, size_t size)
569 The talloc_zero_size() function is useful when you don't have a known type
572 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
573 void *talloc_memdup(const void *ctx, const void *p, size_t size);
575 The talloc_memdup() function is equivalent to::
577 ptr = talloc_size(ctx, size);
578 if (ptr) memcpy(ptr, p, size);
581 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
582 char *talloc_strdup(const void *ctx, const char *p);
584 The talloc_strdup() function is equivalent to::
586 ptr = talloc_size(ctx, strlen(p)+1);
587 if (ptr) memcpy(ptr, p, strlen(p)+1);
589 This functions sets the name of the new pointer to the passed
590 string. This is equivalent to::
592 talloc_set_name_const(ptr, ptr)
594 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
595 char *talloc_strndup(const void *t, const char *p, size_t n);
597 The talloc_strndup() function is the talloc equivalent of the C
598 library function strndup()
600 This functions sets the name of the new pointer to the passed
601 string. This is equivalent to:
602 talloc_set_name_const(ptr, ptr)
604 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
605 char *talloc_append_string(const void *t, char *orig, const char *append);
607 The talloc_append_string() function appends the given formatted
608 string to the given string.
610 This function sets the name of the new pointer to the new
611 string. This is equivalent to::
613 talloc_set_name_const(ptr, ptr)
615 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
616 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
618 The talloc_vasprintf() function is the talloc equivalent of the C
619 library function vasprintf()
621 This functions sets the name of the new pointer to the new
622 string. This is equivalent to::
624 talloc_set_name_const(ptr, ptr)
627 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
628 char *talloc_asprintf(const void *t, const char *fmt, ...);
630 The talloc_asprintf() function is the talloc equivalent of the C
631 library function asprintf()
633 This functions sets the name of the new pointer to the new
634 string. This is equivalent to::
636 talloc_set_name_const(ptr, ptr)
639 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
640 char *talloc_asprintf_append(char *s, const char *fmt, ...);
642 The talloc_asprintf_append() function appends the given formatted
643 string to the given string.
644 Use this varient when the string in the current talloc buffer may
645 have been truncated in length.
647 This functions sets the name of the new pointer to the new
648 string. This is equivalent to::
650 talloc_set_name_const(ptr, ptr)
653 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
654 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...);
656 The talloc_asprintf_append() function appends the given formatted
657 string to the end of the currently allocated talloc buffer.
658 Use this varient when the string in the current talloc buffer has
661 This functions sets the name of the new pointer to the new
662 string. This is equivalent to::
664 talloc_set_name_const(ptr, ptr)
667 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
668 ((type *)talloc_array(const void *ctx, type, unsigned int count);
670 The talloc_array() macro is equivalent to::
672 (type *)talloc_size(ctx, sizeof(type) * count);
674 except that it provides integer overflow protection for the multiply,
675 returning NULL if the multiply overflows.
678 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
679 void *talloc_array_size(const void *ctx, size_t size, unsigned int count);
681 The talloc_array_size() function is useful when the type is not
682 known. It operates in the same way as talloc_array(), but takes a size
685 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
686 (typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);
688 The talloc_ptrtype() macro should be used when you have a pointer to an array
689 and want to allocate memory of an array to point at with this pointer. When compiling
690 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
691 and talloc_get_name() will return the current location in the source file.
694 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
695 void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
697 This is a non-macro version of talloc_realloc(), which is useful
698 as libraries sometimes want a ralloc function pointer. A realloc()
699 implementation encapsulates the functionality of malloc(), free() and
700 realloc() in one call, which is why it is useful to be able to pass
701 around a single function pointer.
704 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
705 void *talloc_autofree_context(void);
707 This is a handy utility function that returns a talloc context
708 which will be automatically freed on program exit. This can be used
709 to reduce the noise in memory leak reports.
712 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
713 void *talloc_check_name(const void *ptr, const char *name);
715 This function checks if a pointer has the specified name. If it does
716 then the pointer is returned. It it doesn't then NULL is returned.
719 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
720 (type *)talloc_get_type(const void *ptr, type);
722 This macro allows you to do type checking on talloc pointers. It is
723 particularly useful for void* private pointers. It is equivalent to
726 (type *)talloc_check_name(ptr, #type)
729 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
730 talloc_set_type(const void *ptr, type);
732 This macro allows you to force the name of a pointer to be a
733 particular type. This can be used in conjunction with
734 talloc_get_type() to do type checking on void* pointers.
736 It is equivalent to this::
738 talloc_set_name_const(ptr, #type)
740 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
741 talloc_get_size(const void *ctx);
743 This function lets you know the amount of memory alloced so far by
744 this context. It does NOT account for subcontext memory.
745 This can be used to calculate the size of an array.
747 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
748 void *talloc_find_parent_byname(const void *ctx, const char *name);
750 Find a parent memory context of the current context that has the given
751 name. This can be very useful in complex programs where it may be
752 difficult to pass all information down to the level you need, but you
753 know the structure you want is a parent of another context.
755 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
756 (type *)talloc_find_parent_bytype(ctx, type);
758 Like talloc_find_parent_byname() but takes a type, making it typesafe.
760 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
761 void talloc_set_log_fn(void (*log_fn)(const char *message));
763 This function sets a logging function that talloc will use for
764 warnings and errors. By default talloc will not print any warnings or
767 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
768 void talloc_set_log_stderr(void)
770 This sets the talloc log function to write log messages to stderr