4 Copyright (C) Andrew Tridgell 2004-2005
5 Copyright (C) Stefan Metzmacher 2006
7 ** NOTE! The following LGPL license applies to the talloc
8 ** library. This does NOT imply that all of Samba is released
11 This library is free software; you can redistribute it and/or
12 modify it under the terms of the GNU Lesser General Public
13 License as published by the Free Software Foundation; either
14 version 2 of the License, or (at your option) any later version.
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Lesser General Public License for more details.
21 You should have received a copy of the GNU Lesser General Public
22 License along with this library; if not, write to the Free Software
23 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
29 #include <ccan/typesafe_cb/typesafe_cb.h>
30 #include <ccan/compiler/compiler.h>
34 this uses a little trick to allow __LINE__ to be stringified
37 #define __TALLOC_STRING_LINE1__(s) #s
38 #define __TALLOC_STRING_LINE2__(s) __TALLOC_STRING_LINE1__(s)
39 #define __TALLOC_STRING_LINE3__ __TALLOC_STRING_LINE2__(__LINE__)
40 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
43 /* try to make talloc_set_destructor() and talloc_steal() type safe,
44 if we have a recent gcc */
46 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
48 #define _TALLOC_TYPEOF(ptr) void *
51 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
54 * talloc - allocate dynamic memory for a type
55 * @ctx: context to be parent of this allocation, or NULL.
56 * @type: the type to be allocated.
58 * The talloc() macro is the core of the talloc library. It takes a memory
59 * context and a type, and returns a pointer to a new area of memory of the
62 * The returned pointer is itself a talloc context, so you can use it as the
63 * context argument to more calls to talloc if you wish.
65 * The returned pointer is a "child" of @ctx. This means that if you
66 * talloc_free() @ctx then the new child disappears as well. Alternatively you
67 * can free just the child.
69 * @ctx can be NULL, in which case a new top level context is created.
72 * unsigned int *a, *b;
73 * a = talloc(NULL, unsigned int);
74 * b = talloc(a, unsigned int);
77 * talloc_zero, talloc_array, talloc_steal, talloc_free.
79 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
82 * TALLOC_CTX - indicate that a pointer is used as a talloc parent.
84 * As talloc is a hierarchial memory allocator, every talloc chunk is a
85 * potential parent to other talloc chunks. So defining a separate type for a
86 * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
87 * as it provides an indicator for function arguments.
94 * static struct foo *foo_new(TALLOC_CTX *mem_ctx)
96 * struct foo *foo = talloc(mem_ctx, struct foo);
102 typedef void TALLOC_CTX;
105 * talloc_set - allocate dynamic memory for a type, into a pointer
106 * @ptr: pointer to the pointer to assign.
107 * @ctx: context to be parent of this allocation, or NULL.
109 * talloc_set() does a talloc, but also adds a destructor which will make the
110 * pointer invalid when it is freed. This can find many use-after-free bugs.
112 * Note that the destructor is chained off a zero-length allocation, and so
113 * is not affected by talloc_set_destructor().
116 * unsigned int *b, *a;
117 * a = talloc(NULL, unsigned int);
120 * *b = 1; // This will crash!
125 #define talloc_set(pptr, ctx) \
126 _talloc_set((pptr), (ctx), sizeof(&**(pptr)), __location__)
129 * talloc_free - free talloc'ed memory and its children
130 * @ptr: the talloced pointer to free
132 * The talloc_free() function frees a piece of talloc memory, and all its
133 * children. You can call talloc_free() on any pointer returned by talloc().
135 * The return value of talloc_free() indicates success or failure, with 0
136 * returned for success and -1 for failure. The only possible failure condition
137 * is if the pointer had a destructor attached to it and the destructor
138 * returned -1. See talloc_set_destructor() for details on destructors.
139 * errno will be preserved unless the talloc_free fails.
141 * If this pointer has an additional parent when talloc_free() is called then
142 * the memory is not actually released, but instead the most recently
143 * established parent is destroyed. See talloc_reference() for details on
144 * establishing additional parents.
146 * For more control on which parent is removed, see talloc_unlink().
148 * talloc_free() operates recursively on its children.
151 * unsigned int *a, *b;
152 * a = talloc(NULL, unsigned int);
153 * b = talloc(a, unsigned int);
158 * talloc_set_destructor, talloc_unlink
160 int talloc_free(const void *ptr);
163 * talloc_set_destructor - set a destructor for when this pointer is freed
164 * @ptr: the talloc pointer to set the destructor on
165 * @destructor: the function to be called
167 * The function talloc_set_destructor() sets the "destructor" for the pointer
168 * @ptr. A destructor is a function that is called when the memory used by a
169 * pointer is about to be released. The destructor receives the pointer as an
170 * argument, and should return 0 for success and -1 for failure.
172 * The destructor can do anything it wants to, including freeing other pieces
173 * of memory. A common use for destructors is to clean up operating system
174 * resources (such as open file descriptors) contained in the structure the
175 * destructor is placed on.
177 * You can only place one destructor on a pointer. If you need more than one
178 * destructor then you can create a zero-length child of the pointer and place
179 * an additional destructor on that.
181 * To remove a destructor call talloc_set_destructor() with NULL for the
184 * If your destructor attempts to talloc_free() the pointer that it is the
185 * destructor for then talloc_free() will return -1 and the free will be
186 * ignored. This would be a pointless operation anyway, as the destructor is
187 * only called when the memory is just about to go away.
190 * static int destroy_fd(int *fd)
196 * static int *open_file(const char *filename)
198 * int *fd = talloc(NULL, int);
199 * *fd = open(filename, O_RDONLY);
204 * // Whenever they free this, we close the file.
205 * talloc_set_destructor(fd, destroy_fd);
210 * talloc, talloc_free
212 #define talloc_set_destructor(ptr, function) \
213 _talloc_set_destructor((ptr), typesafe_cb(int, void *, (function), (ptr)))
216 * talloc_zero - allocate zeroed dynamic memory for a type
217 * @ctx: context to be parent of this allocation, or NULL.
218 * @type: the type to be allocated.
220 * The talloc_zero() macro is equivalent to:
222 * ptr = talloc(ctx, type);
223 * if (ptr) memset(ptr, 0, sizeof(type));
226 * unsigned int *a, *b;
227 * a = talloc_zero(NULL, unsigned int);
228 * b = talloc_zero(a, unsigned int);
231 * talloc, talloc_zero_size, talloc_zero_array
233 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
236 * talloc_array - allocate dynamic memory for an array of a given type
237 * @ctx: context to be parent of this allocation, or NULL.
238 * @type: the type to be allocated.
239 * @count: the number of elements to be allocated.
241 * The talloc_array() macro is a safe way of allocating an array. It is
244 * (type *)talloc_size(ctx, sizeof(type) * count);
246 * except that it provides integer overflow protection for the multiply,
247 * returning NULL if the multiply overflows.
250 * unsigned int *a, *b;
251 * a = talloc_zero(NULL, unsigned int);
252 * b = talloc_array(a, unsigned int, 100);
255 * talloc, talloc_zero_array, talloc_array_length
257 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
260 * talloc_size - allocate a particular size of memory
261 * @ctx: context to be parent of this allocation, or NULL.
262 * @size: the number of bytes to allocate
264 * The function talloc_size() should be used when you don't have a convenient
265 * type to pass to talloc(). Unlike talloc(), it is not type safe (as it
266 * returns a void *), so you are on your own for type checking.
268 * Best to use talloc() or talloc_array() instead.
271 * void *mem = talloc_size(NULL, 100);
272 * memset(mem, 0xFF, 100);
275 * talloc, talloc_array, talloc_zero_size
277 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
281 * talloc_steal - change/set the parent context of a talloc pointer
282 * @ctx: the new parent
283 * @ptr: the talloc pointer to reparent
285 * The talloc_steal() function changes the parent context of a talloc
286 * pointer. It is typically used when the context that the pointer is currently
287 * a child of is going to be freed and you wish to keep the memory for a longer
290 * The talloc_steal() function returns the pointer that you pass it. It does
291 * not have any failure modes.
293 * NOTE: It is possible to produce loops in the parent/child relationship if
294 * you are not careful with talloc_steal(). No guarantees are provided as to
295 * your sanity or the safety of your data if you do this.
297 * talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
300 * unsigned int *a, *b;
301 * a = talloc(NULL, unsigned int);
302 * b = talloc(NULL, unsigned int);
303 * // Reparent b to a as if we'd done 'b = talloc(a, unsigned int)'.
304 * talloc_steal(a, b);
309 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) _talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); _talloc_steal_ret; }) /* this extremely strange macro is to avoid some braindamaged warning stupidity in gcc 4.1.x */
311 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
312 #endif /* HAVE_TYPEOF */
315 * talloc_report_full - report all the memory used by a pointer and children.
316 * @ptr: the context to report on
317 * @f: the file to report to
319 * Recursively print the entire tree of memory referenced by the
320 * pointer. References in the tree are shown by giving the name of the pointer
321 * that is referenced.
323 * You can pass NULL for the pointer, in which case a report is printed for the
324 * top level memory context, but only if talloc_enable_null_tracking() has been
328 * unsigned int *a, *b;
329 * a = talloc(NULL, unsigned int);
330 * b = talloc(a, unsigned int);
331 * fprintf(stderr, "Dumping memory tree for a:\n");
332 * talloc_report_full(a, stderr);
337 void talloc_report_full(const void *ptr, FILE *f);
340 * talloc_reference - add an additional parent to a context
341 * @ctx: the additional parent
342 * @ptr: the talloc pointer
344 * The talloc_reference() function makes @ctx an additional parent of @ptr.
346 * The return value of talloc_reference() is always the original pointer @ptr,
347 * unless talloc ran out of memory in creating the reference in which case it
348 * will return NULL (each additional reference consumes around 48 bytes of
349 * memory on intel x86 platforms).
351 * If @ptr is NULL, then the function is a no-op, and simply returns NULL.
353 * After creating a reference you can free it in one of the following ways:
355 * - you can talloc_free() any parent of the original pointer. That will
356 * reduce the number of parents of this pointer by 1, and will cause this
357 * pointer to be freed if it runs out of parents.
359 * - you can talloc_free() the pointer itself. That will destroy the most
360 * recently established parent to the pointer and leave the pointer as a
361 * child of its current parent.
363 * For more control on which parent to remove, see talloc_unlink().
365 * unsigned int *a, *b, *c;
366 * a = talloc(NULL, unsigned int);
367 * b = talloc(NULL, unsigned int);
368 * c = talloc(a, unsigned int);
369 * // b also serves as a parent of c (don't care about errors)
370 * (void)talloc_reference(b, c);
372 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
375 * talloc_unlink - remove a specific parent from a talloc pointer.
376 * @context: the parent to remove
377 * @ptr: the talloc pointer
379 * The talloc_unlink() function removes a specific parent from @ptr. The
380 * context passed must either be a context used in talloc_reference() with this
381 * pointer, or must be a direct parent of @ptr.
383 * Note that if the parent has already been removed using talloc_free() then
384 * this function will fail and will return -1. Likewise, if @ptr is NULL,
385 * then the function will make no modifications and return -1.
387 * Usually you can just use talloc_free() instead of talloc_unlink(), but
388 * sometimes it is useful to have the additional control on which parent is
392 * unsigned int *a, *b, *c;
393 * a = talloc(NULL, unsigned int);
394 * b = talloc(NULL, unsigned int);
395 * c = talloc(a, unsigned int);
396 * // b also serves as a parent of c.
397 * (void)talloc_reference(b, c);
398 * talloc_unlink(b, c);
400 int talloc_unlink(const void *context, void *ptr);
403 * talloc_report - print a summary of memory used by a pointer
405 * The talloc_report() function prints a summary report of all memory
406 * used by @ptr. One line of report is printed for each immediate child of
407 * @ptr, showing the total memory and number of blocks used by that child.
409 * You can pass NULL for the pointer, in which case a report is printed for the
410 * top level memory context, but only if talloc_enable_null_tracking() has been
414 * unsigned int *a, *b;
415 * a = talloc(NULL, unsigned int);
416 * b = talloc(a, unsigned int);
417 * fprintf(stderr, "Summary of memory tree for a:\n");
418 * talloc_report(a, stderr);
423 void talloc_report(const void *ptr, FILE *f);
426 * talloc_ptrtype - allocate a size of memory suitable for this pointer
427 * @ctx: context to be parent of this allocation, or NULL.
428 * @ptr: the pointer whose type we are to allocate
430 * The talloc_ptrtype() macro should be used when you have a pointer and
431 * want to allocate memory to point at with this pointer. When compiling
432 * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
433 * and talloc_get_name() will return the current location in the source file.
437 * unsigned int *a = talloc_ptrtype(NULL, a);
439 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
442 * talloc_new - create a new context
443 * @ctx: the context to use as a parent.
445 * This is a utility macro that creates a new memory context hanging off an
446 * exiting context, automatically naming it "talloc_new: __location__" where
447 * __location__ is the source line it is called from. It is particularly useful
448 * for creating a new temporary working context.
450 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
453 * talloc_zero_size - allocate a particular size of zeroed memory
455 * The talloc_zero_size() function is useful when you don't have a known type.
457 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
460 * talloc_zero_array - allocate an array of zeroed types
461 * @ctx: context to be parent of this allocation, or NULL.
462 * @type: the type to be allocated.
463 * @count: the number of elements to be allocated.
465 * Just like talloc_array, but zeroes the memory.
467 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
470 * talloc_array_size - allocate an array of elements of the given size
471 * @ctx: context to be parent of this allocation, or NULL.
472 * @size: the size of each element
473 * @count: the number of elements to be allocated.
475 * Typeless form of talloc_array.
477 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
480 * talloc_array_ptrtype - allocate an array of memory suitable for this pointer
481 * @ctx: context to be parent of this allocation, or NULL.
482 * @ptr: the pointer whose type we are to allocate
483 * @count: the number of elements for the array
485 * Like talloc_ptrtype(), except it allocates an array.
487 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
490 * talloc_realloc - resize a talloc array
491 * @ctx: the parent to assign (if p is NULL)
492 * @p: the memory to reallocate
493 * @type: the type of the object to allocate
494 * @count: the number of objects to reallocate
496 * The talloc_realloc() macro changes the size of a talloc pointer. The "count"
497 * argument is the number of elements of type "type" that you want the
498 * resulting pointer to hold.
500 * talloc_realloc() has the following equivalences:
502 * talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
503 * talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
504 * talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
506 * The "context" argument is only used if "ptr" is NULL, otherwise it is
509 * talloc_realloc() returns the new pointer, or NULL on failure. The call will
510 * fail either due to a lack of memory, or because the pointer has more than
511 * one parent (see talloc_reference()).
513 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
516 * talloc_realloc_size - resize talloc memory
517 * @ctx: the parent to assign (if p is NULL)
518 * @ptr: the memory to reallocate
519 * @size: the new size of memory.
521 * The talloc_realloc_size() function is useful when the type is not known so
522 * the typesafe talloc_realloc() cannot be used.
524 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
527 * talloc_strdup - duplicate a string
528 * @ctx: the talloc context for the new string
529 * @p: the string to copy
531 * The talloc_strdup() function is equivalent to:
533 * ptr = talloc_size(ctx, strlen(p)+1);
534 * if (ptr) memcpy(ptr, p, strlen(p)+1);
536 * This functions sets the name of the new pointer to the passed string. This
539 * talloc_set_name_const(ptr, ptr)
541 char *talloc_strdup(const void *t, const char *p);
544 * talloc_strndup - duplicate a limited length of a string
545 * @ctx: the talloc context for the new string
546 * @p: the string to copy
547 * @n: the maximum length of the returned string.
549 * The talloc_strndup() function is the talloc equivalent of the C library
550 * function strndup(): the result will be truncated to @n characters before
551 * the nul terminator.
553 * This functions sets the name of the new pointer to the passed string. This
556 * talloc_set_name_const(ptr, ptr)
558 char *talloc_strndup(const void *t, const char *p, size_t n);
561 * talloc_memdup - duplicate some talloc memory
563 * The talloc_memdup() function is equivalent to:
565 * ptr = talloc_size(ctx, size);
566 * if (ptr) memcpy(ptr, p, size);
568 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
571 * talloc_asprintf - sprintf into a talloc buffer.
572 * @t: The context to allocate the buffer from
573 * @fmt: printf-style format for the buffer.
575 * The talloc_asprintf() function is the talloc equivalent of the C library
576 * function asprintf().
578 * This functions sets the name of the new pointer to the new string. This is
581 * talloc_set_name_const(ptr, ptr)
583 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_FMT(2,3);
586 * talloc_append_string - concatenate onto a tallocated string
587 * @orig: the tallocated string to append to
588 * @append: the string to add, or NULL to add nothing.
590 * The talloc_append_string() function appends the given formatted string to
593 * This function sets the name of the new pointer to the new string. This is
596 * talloc_set_name_const(ptr, ptr)
598 char *WARN_UNUSED_RESULT talloc_append_string(char *orig, const char *append);
601 * talloc_asprintf_append - sprintf onto the end of a talloc buffer.
602 * @s: The tallocated string buffer
603 * @fmt: printf-style format to append to the buffer.
605 * The talloc_asprintf_append() function appends the given formatted string to
608 * This functions sets the name of the new pointer to the new string. This is
610 * talloc_set_name_const(ptr, ptr)
612 char *WARN_UNUSED_RESULT talloc_asprintf_append(char *s, const char *fmt, ...)
616 * talloc_vasprintf - vsprintf into a talloc buffer.
617 * @t: The context to allocate the buffer from
618 * @fmt: printf-style format for the buffer
619 * @ap: va_list arguments
621 * The talloc_vasprintf() function is the talloc equivalent of the C library
622 * function vasprintf()
624 * This functions sets the name of the new pointer to the new string. This is
627 * talloc_set_name_const(ptr, ptr)
629 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap)
633 * talloc_vasprintf_append - sprintf onto the end of a talloc buffer.
634 * @t: The context to allocate the buffer from
635 * @fmt: printf-style format for the buffer
636 * @ap: va_list arguments
638 * The talloc_vasprintf_append() function is equivalent to
639 * talloc_asprintf_append(), except it takes a va_list.
641 char *WARN_UNUSED_RESULT talloc_vasprintf_append(char *s, const char *fmt, va_list ap)
645 * talloc_set_type - force the name of a pointer to a particular type
646 * @ptr: the talloc pointer
647 * @type: the type whose name to set the ptr name to.
649 * This macro allows you to force the name of a pointer to be a particular
650 * type. This can be used in conjunction with talloc_get_type() to do type
651 * checking on void* pointers.
653 * It is equivalent to this:
654 * talloc_set_name_const(ptr, #type)
656 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
659 * talloc_get_type - convert a talloced pointer with typechecking
660 * @ptr: the talloc pointer
661 * @type: the type which we expect the talloced pointer to be.
663 * This macro allows you to do type checking on talloc pointers. It is
664 * particularly useful for void* private pointers. It is equivalent to this:
666 * (type *)talloc_check_name(ptr, #type)
668 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
671 * talloc_find_parent_byname - find a talloc parent by type
672 * @ptr: the talloc pointer
673 * @type: the type we're looking for
675 * Find a parent memory context of the current context that has the given
676 * name. This can be very useful in complex programs where it may be difficult
677 * to pass all information down to the level you need, but you know the
678 * structure you want is a parent of another context.
680 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
683 * talloc_increase_ref_count - hold a reference to a talloc pointer
684 * @ptr: the talloc pointer
686 * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
688 * talloc_reference(NULL, ptr);
690 * You can use either syntax, depending on which you think is clearer in your
693 * It returns 0 on success and -1 on failure.
695 int talloc_increase_ref_count(const void *ptr);
698 * talloc_set_name - set the name for a talloc pointer
699 * @ptr: the talloc pointer
700 * @fmt: the printf-style format string for the name
702 * Each talloc pointer has a "name". The name is used principally for debugging
703 * purposes, although it is also possible to set and get the name on a pointer
704 * in as a way of "marking" pointers in your code.
706 * The main use for names on pointer is for "talloc reports". See
707 * talloc_report() and talloc_report_full() for details. Also see
708 * talloc_enable_leak_report() and talloc_enable_leak_report_full().
710 * The talloc_set_name() function allocates memory as a child of the
711 * pointer. It is logically equivalent to:
712 * talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
714 * Note that multiple calls to talloc_set_name() will allocate more memory
715 * without releasing the name. All of the memory is released when the ptr is
716 * freed using talloc_free().
718 const char *talloc_set_name(const void *ptr, const char *fmt, ...)
722 * talloc_set_name_const - set a talloc pointer name to a string constant
723 * @ptr: the talloc pointer to name
724 * @name: the strucng constant.
726 * The function talloc_set_name_const() is just like talloc_set_name(), but it
727 * takes a string constant, and is much faster. It is extensively used by the
728 * "auto naming" macros, such as talloc().
730 * This function does not allocate any memory. It just copies the supplied
731 * pointer into the internal representation of the talloc ptr. This means you
732 * must not pass a name pointer to memory that will disappear before the ptr is
733 * freed with talloc_free().
735 void talloc_set_name_const(const void *ptr, const char *name);
738 * talloc_named - create a specifically-named talloc pointer
739 * @context: the parent context for the allocation
740 * @size: the size to allocate
741 * @fmt: the printf-style format for the name
743 * The talloc_named() function creates a named talloc pointer. It is equivalent
746 * ptr = talloc_size(context, size);
747 * talloc_set_name(ptr, fmt, ....);
749 void *talloc_named(const void *context, size_t size,
750 const char *fmt, ...) PRINTF_FMT(3,4);
753 * talloc_named_const - create a specifically-named talloc pointer
754 * @context: the parent context for the allocation
755 * @size: the size to allocate
756 * @name: the string constant to use as the name
758 * This is equivalent to:
760 * ptr = talloc_size(context, size);
761 * talloc_set_name_const(ptr, name);
763 void *talloc_named_const(const void *context, size_t size, const char *name);
766 * talloc_get_name - get the name of a talloc pointer
767 * @ptr: the talloc pointer
769 * This returns the current name for the given talloc pointer. See
770 * talloc_set_name() for details.
772 const char *talloc_get_name(const void *ptr);
775 * talloc_check_name - check if a pointer has the specified name
776 * @ptr: the talloc pointer
777 * @name: the name to compare with the pointer's name
779 * This function checks if a pointer has the specified name. If it does then
780 * the pointer is returned. It it doesn't then NULL is returned.
782 void *talloc_check_name(const void *ptr, const char *name);
785 * talloc_init - create a top-level context of particular name
786 * @fmt: the printf-style format of the name
788 * This function creates a zero length named talloc context as a top level
789 * context. It is equivalent to:
791 * talloc_named(NULL, 0, fmt, ...);
793 void *talloc_init(const char *fmt, ...) PRINTF_FMT(1,2);
796 * talloc_total_size - get the bytes used by the pointer and its children
797 * @ptr: the talloc pointer
799 * The talloc_total_size() function returns the total size in bytes used by
800 * this pointer and all child pointers. Mostly useful for debugging.
802 * Passing NULL is allowed, but it will only give a meaningful result if
803 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has been
806 size_t talloc_total_size(const void *ptr);
809 * talloc_total_blocks - get the number of allocations for the pointer
810 * @ptr: the talloc pointer
812 * The talloc_total_blocks() function returns the total allocations used by
813 * this pointer and all child pointers. Mostly useful for debugging. For
814 * example, a pointer with no children will return "1".
816 * Passing NULL is allowed, but it will only give a meaningful result if
817 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has been
820 size_t talloc_total_blocks(const void *ptr);
823 * talloc_report_depth_cb - walk the entire talloc tree under a talloc pointer
824 * @ptr: the talloc pointer to recurse under
825 * @depth: the current depth of traversal
826 * @max_depth: maximum depth to traverse, or -1 for no maximum
827 * @callback: the function to call on each pointer
828 * @private_data: pointer to hand to @callback.
830 * This provides a more flexible reports than talloc_report(). It will
831 * recursively call the callback for the entire tree of memory referenced by
832 * the pointer. References in the tree are passed with is_ref = 1 and the
833 * pointer that is referenced.
835 * You can pass NULL for the pointer, in which case a report is printed for the
836 * top level memory context, but only if talloc_enable_leak_report() or
837 * talloc_enable_leak_report_full() has been called.
839 * The recursion is stopped when depth >= max_depth. max_depth = -1 means only
840 * stop at leaf nodes.
842 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
843 void (*callback)(const void *ptr,
844 int depth, int max_depth,
850 * talloc_report_depth_file - report talloc usage to a maximum depth
851 * @ptr: the talloc pointer to recurse under
852 * @depth: the current depth of traversal
853 * @max_depth: maximum depth to traverse, or -1 for no maximum
854 * @f: the file to report to
856 * This provides a more flexible reports than talloc_report(). It will let you
857 * specify the depth and max_depth.
859 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
862 * talloc_enable_null_tracking - enable tracking of top-level tallocs
864 * This enables tracking of the NULL memory context without enabling leak
865 * reporting on exit. Useful for when you want to do your own leak reporting
866 * call via talloc_report_null_full();
868 void talloc_enable_null_tracking(void);
871 * talloc_disable_null_tracking - enable tracking of top-level tallocs
873 * This disables tracking of the NULL memory context.
875 void talloc_disable_null_tracking(void);
878 * talloc_enable_leak_report - call talloc_report on program exit
880 * This enables calling of talloc_report(NULL, stderr) when the program
881 * exits. In Samba4 this is enabled by using the --leak-report command line
884 * For it to be useful, this function must be called before any other talloc
885 * function as it establishes a "null context" that acts as the top of the
886 * tree. If you don't call this function first then passing NULL to
887 * talloc_report() or talloc_report_full() won't give you the full tree
890 * Here is a typical talloc report:
892 * talloc report on 'null_context' (total 267 bytes in 15 blocks)
893 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
894 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
895 * iconv(UTF8,CP850) contains 42 bytes in 2 blocks
896 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
897 * iconv(CP850,UTF8) contains 42 bytes in 2 blocks
898 * iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
899 * iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
901 void talloc_enable_leak_report(void);
904 * talloc_enable_leak_report - call talloc_report_full on program exit
906 * This enables calling of talloc_report_full(NULL, stderr) when the program
907 * exits. In Samba4 this is enabled by using the --leak-report-full command
910 * For it to be useful, this function must be called before any other talloc
911 * function as it establishes a "null context" that acts as the top of the
912 * tree. If you don't call this function first then passing NULL to
913 * talloc_report() or talloc_report_full() won't give you the full tree
916 * Here is a typical full report:
918 * full talloc report on 'root' (total 18 bytes in 8 blocks)
919 * p1 contains 18 bytes in 7 blocks (ref 0)
920 * r1 contains 13 bytes in 2 blocks (ref 0)
922 * p2 contains 1 bytes in 1 blocks (ref 1)
923 * x3 contains 1 bytes in 1 blocks (ref 0)
924 * x2 contains 1 bytes in 1 blocks (ref 0)
925 * x1 contains 1 bytes in 1 blocks (ref 0)
927 void talloc_enable_leak_report_full(void);
930 * talloc_autofree_context - a context which will be freed at exit
932 * This is a handy utility function that returns a talloc context which will be
933 * automatically freed on program exit. This can be used to reduce the noise in
934 * memory leak reports.
936 void *talloc_autofree_context(void);
939 * talloc_array_length - get the number of elements in a talloc array
940 * @p: the talloc pointer whose allocation to measure.
942 * This assumes that @p has been allocated as the same type. NULL returns 0.
947 #define talloc_array_length(p) (talloc_get_size(p) / sizeof((*p)))
950 * talloc_get_size - get the requested size of an allocation
951 * @ctx: the talloc pointer whose allocation to measure.
953 * This function lets you know the amount of memory alloced so far by this
954 * context. It does NOT account for subcontext memory.
957 * talloc_array_length
959 size_t talloc_get_size(const void *ctx);
962 * talloc_find_parent_byname - find a parent of this context with this name
963 * @ctx: the context whose ancestors to search
964 * @name: the name to look for
966 * Find a parent memory context of @ctx that has the given name. This can be
967 * very useful in complex programs where it may be difficult to pass all
968 * information down to the level you need, but you know the structure you want
969 * is a parent of another context.
971 void *talloc_find_parent_byname(const void *ctx, const char *name);
974 * talloc_set_allocator - set the allocations function(s) for talloc.
975 * @malloc: the malloc function
976 * @free: the free function
977 * @realloc: the realloc function
979 * Instead of using the standard malloc, free and realloc, talloc will use
980 * these replacements. @realloc will never be called with size 0 or ptr NULL.
982 void talloc_set_allocator(void *(*malloc)(size_t size),
983 void (*free)(void *ptr),
984 void *(*realloc)(void *ptr, size_t size));
987 * talloc_add_external - create an externally allocated node
989 * @realloc: the realloc() equivalent
990 * @lock: the call to lock before manipulation of external nodes
991 * @unlock: the call to unlock after manipulation of external nodes
993 * talloc_add_external() creates a node which uses a separate allocator. All
994 * children allocated from that node will also use that allocator.
996 * Note: Currently there is only one external allocator, not per-node,
997 * and it is set with this function.
999 * @lock is handed a pointer which was previous returned from your realloc
1000 * function; you should use that to figure out which lock to get if you have
1001 * multiple external pools.
1003 * The parent pointers in realloc is the talloc pointer of the parent, if any.
1005 void *talloc_add_external(const void *ctx,
1006 void *(*realloc)(const void *parent,
1008 void (*lock)(const void *p),
1009 void (*unlock)(void));
1011 /* The following definitions come from talloc.c */
1012 void *_talloc(const void *context, size_t size);
1013 void _talloc_set(void *ptr, const void *ctx, size_t size, const char *name);
1014 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
1015 size_t talloc_reference_count(const void *ptr);
1016 void *_talloc_reference(const void *context, const void *ptr);
1018 void *WARN_UNUSED_RESULT _talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
1019 void *talloc_parent(const void *ptr);
1020 const char *talloc_parent_name(const void *ptr);
1021 void *_talloc_steal(const void *new_ctx, const void *ptr);
1022 void *_talloc_move(const void *new_ctx, const void *pptr);
1023 void *_talloc_zero(const void *ctx, size_t size, const char *name);
1024 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
1025 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1026 void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1027 void *WARN_UNUSED_RESULT _talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
1028 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
1029 void talloc_show_parents(const void *context, FILE *file);
1030 int talloc_is_parent(const void *context, const void *ptr);
1032 #endif /* CCAN_TALLOC_H */