4 Unix SMB/CIFS implementation.
5 Samba temporary memory allocation functions
7 Copyright (C) Andrew Tridgell 2004-2005
8 Copyright (C) Stefan Metzmacher 2006
10 ** NOTE! The following LGPL license applies to the talloc
11 ** library. This does NOT imply that all of Samba is released
14 This library is free software; you can redistribute it and/or
15 modify it under the terms of the GNU Lesser General Public
16 License as published by the Free Software Foundation; either
17 version 3 of the License, or (at your option) any later version.
19 This library is distributed in the hope that it will be useful,
20 but WITHOUT ANY WARRANTY; without even the implied warranty of
21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 Lesser General Public License for more details.
24 You should have received a copy of the GNU Lesser General Public
25 License along with this library; if not, see <http://www.gnu.org/licenses/>.
33 * @defgroup talloc The talloc API
35 * talloc is a hierarchical, reference counted memory pool system with
36 * destructors. It is the core memory allocator used in Samba.
38 * Perhaps the biggest difference from other memory pool systems is that there
39 * is no distinction between a "talloc context" and a "talloc pointer". Any
40 * pointer returned from talloc() is itself a valid talloc context. This means
44 * struct foo *X = talloc(mem_ctx, struct foo);
45 * X->name = talloc_strdup(X, "foo");
48 * The pointer X->name would be a "child" of the talloc context "X" which is
49 * itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
50 * destroyed, whereas if you do talloc_free(X) then just X and X->name are
51 * destroyed, and if you do talloc_free(X->name) then just the name element of
54 * If you think about this, then what this effectively gives you is an n-ary
55 * tree, where you can free any part of the tree with talloc_free().
57 * If you find this confusing, then run the testsuite to watch talloc in
58 * action. You may also like to add your own tests to testsuite.c to clarify
59 * how some particular situation is handled.
61 * @section talloc_performance Performance
63 * All the additional features of talloc() over malloc() do come at a price. We
64 * have a simple performance test in Samba4 that measures talloc() versus
65 * malloc() performance, and it seems that talloc() is about 4% slower than
66 * malloc() on my x86 Debian Linux box. For Samba, the great reduction in code
67 * complexity that we get by using talloc makes this worthwhile, especially as
68 * the total overhead of talloc/malloc in Samba is already quite small.
70 * @section talloc_named Named blocks
72 * Every talloc chunk has a name that can be used as a dynamic type-checking
73 * system. If for some reason like a callback function you had to cast a
74 * "struct foo *" to a "void *" variable, later you can safely reassign the
75 * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
76 * talloc_get_type_abort() macros.
79 * struct foo *X = talloc_get_type_abort(ptr, struct foo);
82 * This will abort if "ptr" does not contain a pointer that has been created
83 * with talloc(mem_ctx, struct foo).
85 * @section talloc_threading Multi-threading
87 * talloc itself does not deal with threads. It is thread-safe (assuming the
88 * underlying "malloc" is), as long as each thread uses different memory
91 * If two threads uses the same context then they need to synchronize in order
92 * to be safe. In particular:
94 * - when using talloc_enable_leak_report(), giving directly NULL as a parent
95 * context implicitly refers to a hidden "null context" global variable, so
96 * this should not be used in a multi-threaded environment without proper
98 * - the context returned by talloc_autofree_context() is also global so
99 * shouldn't be used by several threads simultaneously without
105 #define TALLOC_VERSION_MAJOR 2
106 #define TALLOC_VERSION_MINOR 0
108 int talloc_version_major(void);
109 int talloc_version_minor(void);
112 * @brief Define a talloc parent type
114 * As talloc is a hierarchial memory allocator, every talloc chunk is a
115 * potential parent to other talloc chunks. So defining a separate type for a
116 * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
117 * as it provides an indicator for function arguments. You will frequently
121 * struct foo *foo_create(TALLOC_CTX *mem_ctx)
123 * struct foo *result;
124 * result = talloc(mem_ctx, struct foo);
125 * if (result == NULL) return NULL;
126 * ... initialize foo ...
131 * In this type of allocating functions it is handy to have a general
132 * TALLOC_CTX type to indicate which parent to put allocated structures on.
134 typedef void TALLOC_CTX;
137 this uses a little trick to allow __LINE__ to be stringified
140 #define __TALLOC_STRING_LINE1__(s) #s
141 #define __TALLOC_STRING_LINE2__(s) __TALLOC_STRING_LINE1__(s)
142 #define __TALLOC_STRING_LINE3__ __TALLOC_STRING_LINE2__(__LINE__)
143 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
146 #ifndef TALLOC_DEPRECATED
147 #define TALLOC_DEPRECATED 0
150 #ifndef PRINTF_ATTRIBUTE
152 /** Use gcc attribute to check printf fns. a1 is the 1-based index of
153 * the parameter containing the format, and a2 the index of the first
154 * argument. Note that some gcc 2.x versions don't handle this
156 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
158 #define PRINTF_ATTRIBUTE(a1, a2)
164 * @brief Create a new talloc context.
166 * The talloc() macro is the core of the talloc library. It takes a memory
167 * context and a type, and returns a pointer to a new area of memory of the
170 * The returned pointer is itself a talloc context, so you can use it as the
171 * context argument to more calls to talloc if you wish.
173 * The returned pointer is a "child" of the supplied context. This means that if
174 * you talloc_free() the context then the new child disappears as well.
175 * Alternatively you can free just the child.
177 * @param[in] ctx A talloc context to create a new reference on or NULL to
178 * create a new top level context.
180 * @param[in] type The type of memory to allocate.
182 * @return A type casted talloc context or NULL on error.
185 * unsigned int *a, *b;
187 * a = talloc(NULL, unsigned int);
188 * b = talloc(a, unsigned int);
196 void *talloc(const void *ctx, #type);
198 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
199 void *_talloc(const void *context, size_t size);
203 * @brief Create a new top level talloc context.
205 * This function creates a zero length named talloc context as a top level
206 * context. It is equivalent to:
209 * talloc_named(NULL, 0, fmt, ...);
211 * @param[in] fmt Format string for the name.
213 * @param[in] ... Additional printf-style arguments.
215 * @return The allocated memory chunk, NULL on error.
217 * @see talloc_named()
219 void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
223 * @brief Free a chunk of talloc memory.
225 * This function frees a piece of talloc memory, and all its children. It
226 * operates recursively on its children. You can call talloc_free() on any
227 * pointer returned by talloc().
229 * If this pointer has an additional parent when talloc_free() is called then
230 * the memory is not actually released, but instead the most recently
231 * established parent is destroyed. See talloc_reference() for details on
232 * establishing additional parents.
234 * For more control on which parent is removed, see talloc_unlink().
236 * From the 2.0 version of talloc, as a special case, talloc_free() is
237 * refused on pointers that have more than one parent, as talloc would
238 * have no way of knowing which parent should be removed. To free a
239 * pointer that has more than one parent please use talloc_unlink().
241 * To help you find problems in your code caused by this behaviour, if
242 * you do try and free a pointer with more than one parent then the
243 * talloc logging function will be called to give output like this:
246 * ERROR: talloc_free with references at some_dir/source/foo.c:123
247 * reference at some_dir/source/other.c:325
248 * reference at some_dir/source/third.c:121
251 * Please see the documentation for talloc_set_log_fn() and
252 * talloc_set_log_stderr() for more information on talloc logging
255 * @param[in] ptr The chunk to be freed.
257 * @return Returns 0 on success and -1 on error. The only possible
258 * failure condition is if the pointer had a destructor
259 * attached to it and the destructor returned -1.
263 * unsigned int *a, *b;
264 * a = talloc(NULL, unsigned int);
265 * b = talloc(a, unsigned int);
267 * talloc_free(a); // Frees a and b
270 * @see talloc_set_destructor()
271 * @see talloc_unlink()
273 int talloc_free(void *ptr);
275 #define talloc_free(ctx) _talloc_free(ctx, __location__)
276 int _talloc_free(void *ptr, const char *location);
280 * @brief Free a talloc chunk's children.
282 * The function walks along the list of all children of a talloc context and
283 * talloc_free()s only the children, not the context itself.
285 * @param[in] ptr The chunk that you want to free the children of.
287 void talloc_free_children(void *ptr);
291 * @brief Assign a destructor function to be called when a chunk is freed.
293 * The function talloc_set_destructor() sets the "destructor" for the pointer
294 * "ptr". A destructor is a function that is called when the memory used by a
295 * pointer is about to be released. The destructor receives the pointer as an
296 * argument, and should return 0 for success and -1 for failure.
298 * The destructor can do anything it wants to, including freeing other pieces
299 * of memory. A common use for destructors is to clean up operating system
300 * resources (such as open file descriptors) contained in the structure the
301 * destructor is placed on.
303 * You can only place one destructor on a pointer. If you need more than one
304 * destructor then you can create a zero-length child of the pointer and place
305 * an additional destructor on that.
307 * To remove a destructor call talloc_set_destructor() with NULL for the
310 * If your destructor attempts to talloc_free() the pointer that it is the
311 * destructor for then talloc_free() will return -1 and the free will be
312 * ignored. This would be a pointless operation anyway, as the destructor is
313 * only called when the memory is just about to go away.
315 * @param[in] ptr The talloc chunk to add a destructor to.
317 * @param[in] destructor The destructor function to be called. NULL to remove
322 * static int destroy_fd(int *fd) {
327 * int *open_file(const char *filename) {
328 * int *fd = talloc(NULL, int);
329 * *fd = open(filename, O_RDONLY);
334 * // Whenever they free this, we close the file.
335 * talloc_set_destructor(fd, destroy_fd);
343 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
346 * @brief Change a talloc chunk's parent.
348 * The talloc_steal() function changes the parent context of a talloc
349 * pointer. It is typically used when the context that the pointer is
350 * currently a child of is going to be freed and you wish to keep the
351 * memory for a longer time.
353 * To make the changed hierarchy less error-prone, you might consider to use
356 * If you try and call talloc_steal() on a pointer that has more than one
357 * parent then the result is ambiguous. Talloc will choose to remove the
358 * parent that is currently indicated by talloc_parent() and replace it with
359 * the chosen parent. You will also get a message like this via the talloc
363 * WARNING: talloc_steal with references at some_dir/source/foo.c:123
364 * reference at some_dir/source/other.c:325
365 * reference at some_dir/source/third.c:121
368 * To unambiguously change the parent of a pointer please see the function
369 * talloc_reparent(). See the talloc_set_log_fn() documentation for more
370 * information on talloc logging.
372 * @param[in] new_ctx The new parent context.
374 * @param[in] ptr The talloc chunk to move.
376 * @return Returns the pointer that you pass it. It does not have
379 * @note It is possible to produce loops in the parent/child relationship
380 * if you are not careful with talloc_steal(). No guarantees are provided
381 * as to your sanity or the safety of your data if you do this.
383 void *talloc_steal(const void *new_ctx, const void *ptr);
385 /* try to make talloc_set_destructor() and talloc_steal() type safe,
386 if we have a recent gcc */
388 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
389 #define talloc_set_destructor(ptr, function) \
391 int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function); \
392 _talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
394 /* this extremely strange macro is to avoid some braindamaged warning
395 stupidity in gcc 4.1.x */
396 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__); __talloc_steal_ret; })
397 #else /* __GNUC__ >= 3 */
398 #define talloc_set_destructor(ptr, function) \
399 _talloc_set_destructor((ptr), (int (*)(void *))(function))
400 #define _TALLOC_TYPEOF(ptr) void *
401 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__)
402 #endif /* __GNUC__ >= 3 */
403 void _talloc_set_destructor(const void *ptr, int (*_destructor)(void *));
404 void *_talloc_steal_loc(const void *new_ctx, const void *ptr, const char *location);
408 * @brief Assign a name to a talloc chunk.
410 * Each talloc pointer has a "name". The name is used principally for
411 * debugging purposes, although it is also possible to set and get the name on
412 * a pointer in as a way of "marking" pointers in your code.
414 * The main use for names on pointer is for "talloc reports". See
415 * talloc_report() and talloc_report_full() for details. Also see
416 * talloc_enable_leak_report() and talloc_enable_leak_report_full().
418 * The talloc_set_name() function allocates memory as a child of the
419 * pointer. It is logically equivalent to:
422 * talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
425 * @param[in] ptr The talloc chunk to assign a name to.
427 * @param[in] fmt Format string for the name.
429 * @param[in] ... Add printf-style additional arguments.
431 * @return The assigned name, NULL on error.
433 * @note Multiple calls to talloc_set_name() will allocate more memory without
434 * releasing the name. All of the memory is released when the ptr is freed
435 * using talloc_free().
437 const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
441 * @brief Change a talloc chunk's parent.
443 * This function has the same effect as talloc_steal(), and additionally sets
444 * the source pointer to NULL. You would use it like this:
447 * struct foo *X = talloc(tmp_ctx, struct foo);
449 * Y = talloc_move(new_ctx, &X);
452 * @param[in] new_ctx The new parent context.
454 * @param[in] ptr Pointer to the talloc chunk to move.
456 * @return The pointer of the talloc chunk it has been moved to,
459 void *talloc_move(const void *new_ctx, const void *ptr);
461 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
462 void *_talloc_move(const void *new_ctx, const void *pptr);
466 * @brief Assign a name to a talloc chunk.
468 * The function is just like talloc_set_name(), but it takes a string constant,
469 * and is much faster. It is extensively used by the "auto naming" macros, such
472 * This function does not allocate any memory. It just copies the supplied
473 * pointer into the internal representation of the talloc ptr. This means you
474 * must not pass a name pointer to memory that will disappear before the ptr
475 * is freed with talloc_free().
477 * @param[in] ptr The talloc chunk to assign a name to.
479 * @param[in] name Format string for the name.
481 void talloc_set_name_const(const void *ptr, const char *name);
484 * @brief Create a named talloc chunk.
486 * The talloc_named() function creates a named talloc pointer. It is
490 * ptr = talloc_size(context, size);
491 * talloc_set_name(ptr, fmt, ....);
494 * @param[in] context The talloc context to hang the result off.
496 * @param[in] size Number of char's that you want to allocate.
498 * @param[in] fmt Format string for the name.
500 * @param[in] ... Additional printf-style arguments.
502 * @return The allocated memory chunk, NULL on error.
504 * @see talloc_set_name()
506 void *talloc_named(const void *context, size_t size,
507 const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
510 * @brief Basic routine to allocate a chunk of memory.
512 * This is equivalent to:
515 * ptr = talloc_size(context, size);
516 * talloc_set_name_const(ptr, name);
519 * @param[in] context The parent context.
521 * @param[in] size The number of char's that we want to allocate.
523 * @param[in] name The name the talloc block has.
525 * @return The allocated memory chunk, NULL on error.
527 void *talloc_named_const(const void *context, size_t size, const char *name);
531 * @brief Untyped allocation.
533 * The function should be used when you don't have a convenient type to pass to
534 * talloc(). Unlike talloc(), it is not type safe (as it returns a void *), so
535 * you are on your own for type checking.
537 * Best to use talloc() or talloc_array() instead.
539 * @param[in] ctx The talloc context to hang the result off.
541 * @param[in] size Number of char's that you want to allocate.
543 * @return The allocated memory chunk, NULL on error.
547 * void *mem = talloc_size(NULL, 100);
550 void *talloc_size(const void *ctx, size_t size);
552 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
557 * @brief Allocate into a typed pointer.
559 * The talloc_ptrtype() macro should be used when you have a pointer and want
560 * to allocate memory to point at with this pointer. When compiling with
561 * gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size() and
562 * talloc_get_name() will return the current location in the source file and
565 * @param[in] ctx The talloc context to hang the result off.
567 * @param[in] type The pointer you want to assign the result to.
569 * @return The properly casted allocated memory chunk, NULL on
574 * unsigned int *a = talloc_ptrtype(NULL, a);
577 void *talloc_ptrtype(const void *ctx, #type);
579 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
584 * @brief Allocate a new 0-sized talloc chunk.
586 * This is a utility macro that creates a new memory context hanging off an
587 * exiting context, automatically naming it "talloc_new: __location__" where
588 * __location__ is the source line it is called from. It is particularly
589 * useful for creating a new temporary working context.
591 * @param[in] ctx The talloc parent context.
593 * @return A new talloc chunk, NULL on error.
595 void *talloc_new(const void *ctx);
597 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
602 * @brief Allocate a 0-initizialized structure.
604 * The macro is equivalent to:
607 * ptr = talloc(ctx, type);
608 * if (ptr) memset(ptr, 0, sizeof(type));
611 * @param[in] ctx The talloc context to hang the result off.
613 * @param[in] type The type that we want to allocate.
615 * @return Pointer to a piece of memory, properly cast to 'type *',
620 * unsigned int *a, *b;
621 * a = talloc_zero(NULL, unsigned int);
622 * b = talloc_zero(a, unsigned int);
626 * @see talloc_zero_size()
627 * @see talloc_zero_array()
629 void *talloc_zero(const void *ctx, #type);
632 * @brief Allocate untyped, 0-initialized memory.
634 * @param[in] ctx The talloc context to hang the result off.
636 * @param[in] size Number of char's that you want to allocate.
638 * @return The allocated memory chunk.
640 void *talloc_zero_size(const void *ctx, size_t size);
642 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
643 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
644 void *_talloc_zero(const void *ctx, size_t size, const char *name);
648 * @brief Return the name of a talloc chunk.
650 * @param[in] ptr The talloc chunk.
652 * @return The current name for the given talloc pointer.
654 * @see talloc_set_name()
656 const char *talloc_get_name(const void *ptr);
659 * @brief Verify that a talloc chunk carries a specified name.
661 * This function checks if a pointer has the specified name. If it does
662 * then the pointer is returned.
664 * @param[in] ptr The talloc chunk to check.
666 * @param[in] name The name to check against.
668 * @return The pointer if the name matches, NULL if it doesn't.
670 void *talloc_check_name(const void *ptr, const char *name);
673 * @brief Get the parent chunk of a pointer.
675 * @param[in] ptr The talloc pointer to inspect.
677 * @return The talloc parent of ptr, NULL on error.
679 void *talloc_parent(const void *ptr);
682 * @brief Get a talloc chunk's parent name.
684 * @param[in] ptr The talloc pointer to inspect.
686 * @return The name of ptr's parent chunk.
688 const char *talloc_parent_name(const void *ptr);
691 * @brief Get the total size of a talloc chunk including its children.
693 * The function returns the total size in bytes used by this pointer and all
694 * child pointers. Mostly useful for debugging.
696 * Passing NULL is allowed, but it will only give a meaningful result if
697 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
700 * @param[in] ptr The talloc chunk.
702 * @return The total size.
704 size_t talloc_total_size(const void *ptr);
707 * @brief Get the number of talloc chunks hanging off a chunk.
709 * The talloc_total_blocks() function returns the total memory block
710 * count used by this pointer and all child pointers. Mostly useful for
713 * Passing NULL is allowed, but it will only give a meaningful result if
714 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
717 * @param[in] ptr The talloc chunk.
719 * @return The total size.
721 size_t talloc_total_blocks(const void *ptr);
725 * @brief Duplicate a memory area into a talloc chunk.
727 * The function is equivalent to:
730 * ptr = talloc_size(ctx, size);
731 * if (ptr) memcpy(ptr, p, size);
734 * @param[in] t The talloc context to hang the result off.
736 * @param[in] p The memory chunk you want to duplicate.
738 * @param[in] size Number of char's that you want copy.
740 * @return The allocated memory chunk.
744 void *talloc_memdup(const void *t, const void *p, size_t size);
746 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
747 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
752 * @brief Assign a type to a talloc chunk.
754 * This macro allows you to force the name of a pointer to be a particular type.
755 * This can be used in conjunction with talloc_get_type() to do type checking on
758 * It is equivalent to this:
761 * talloc_set_name_const(ptr, #type)
764 * @param[in] ptr The talloc chunk to assign the type to.
766 * @param[in] type The type to assign.
768 void talloc_set_type(const char *ptr, #type);
771 * @brief Get a typed pointer out of a talloc pointer.
773 * This macro allows you to do type checking on talloc pointers. It is
774 * particularly useful for void* private pointers. It is equivalent to
778 * (type *)talloc_check_name(ptr, #type)
781 * @param[in] ptr The talloc pointer to check.
783 * @param[in] type The type to check against.
785 * @return The properly casted pointer given by ptr, NULL on error.
787 void *talloc_get_name(const void *ptr, #type);
789 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
790 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
795 * @brief Safely turn a void pointer into a typed pointer.
797 * This macro is used together with talloc(mem_ctx, struct foo). If you had to
798 * assing the talloc chunk pointer to some void pointer variable,
799 * talloc_get_type_abort() is the recommended way to get the convert the void
800 * pointer back to a typed pointer.
802 * @param[in] ptr The void pointer to convert.
804 * @param[in] type The type that this chunk contains
806 * @return The ame value as ptr, type-checked and properly cast.
808 void *talloc_get_type_abort(const void *ptr, #type);
810 #define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
811 void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location);
815 * @brief Find a parent context by name.
817 * Find a parent memory context of the current context that has the given
818 * name. This can be very useful in complex programs where it may be
819 * difficult to pass all information down to the level you need, but you
820 * know the structure you want is a parent of another context.
822 * @param[in] ctx The talloc chunk to start from.
824 * @param[in] name The name of the parent we look for.
826 * @return The memory context we are looking for, NULL if not
829 void *talloc_find_parent_byname(const void *ctx, const char *name);
833 * @brief Find a parent context by type.
835 * Find a parent memory context of the current context that has the given
836 * name. This can be very useful in complex programs where it may be
837 * difficult to pass all information down to the level you need, but you
838 * know the structure you want is a parent of another context.
840 * Like talloc_find_parent_byname() but takes a type, making it typesafe.
842 * @param[in] ptr The talloc chunk to start from.
844 * @param[in] type The type of the parent to look for.
846 * @return The memory context we are looking for, NULL if not
849 void *talloc_find_parent_bytype(const void *ptr, #type);
851 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
855 * @brief Allocate a talloc pool.
857 * A talloc pool is a pure optimization for specific situations. In the
858 * release process for Samba 3.2 we found out that we had become considerably
859 * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU
860 * consumer in benchmarks. For Samba 3.2 we have internally converted many
861 * static buffers to dynamically allocated ones, so malloc(3) being beaten
862 * more was no surprise. But it made us slower.
864 * talloc_pool() is an optimization to call malloc(3) a lot less for the use
865 * pattern Samba has: The SMB protocol is mainly a request/response protocol
866 * where we have to allocate a certain amount of memory per request and free
867 * that after the SMB reply is sent to the client.
869 * talloc_pool() creates a talloc chunk that you can use as a talloc parent
870 * exactly as you would use any other ::TALLOC_CTX. The difference is that
871 * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc
872 * just increments a pointer inside the talloc_pool. This also works
873 * recursively. If you use the child of the talloc pool as a parent for
874 * grand-children, their memory is also taken from the talloc pool.
876 * If you talloc_free() children of a talloc pool, the memory is not given
877 * back to the system. Instead, free(3) is only called if the talloc_pool()
878 * itself is released with talloc_free().
880 * The downside of a talloc pool is that if you talloc_move() a child of a
881 * talloc pool to a talloc parent outside the pool, the whole pool memory is
882 * not free(3)'ed until that moved chunk is also talloc_free()ed.
884 * @param[in] context The talloc context to hang the result off.
886 * @param[in] size Size of the talloc pool.
888 * @return The allocated talloc pool, NULL on error.
890 void *talloc_pool(const void *context, size_t size);
893 * @brief Free a talloc chunk and NULL out the pointer.
895 * TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want
896 * immediate feedback (i.e. crash) if you use a pointer after having free'ed
899 * @param[in] ctx The chunk to be freed.
901 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
903 /* @} ******************************************************************/
906 * \defgroup talloc_ref The talloc reference function.
909 * This module contains the definitions around talloc references
915 * @brief Increase the reference count of a talloc chunk.
917 * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
920 * talloc_reference(NULL, ptr);
923 * You can use either syntax, depending on which you think is clearer in
926 * @param[in] ptr The pointer to increase the reference count.
928 * @return 0 on success, -1 on error.
930 int talloc_increase_ref_count(const void *ptr);
933 * @brief Get the number of references to a talloc chunk.
935 * @param[in] ptr The pointer to retrieve the reference count from.
937 * @return The number of references.
939 size_t talloc_reference_count(const void *ptr);
943 * @brief Create an additional talloc parent to a pointer.
945 * The talloc_reference() function makes "context" an additional parent of
946 * ptr. Each additional reference consumes around 48 bytes of memory on intel
949 * If ptr is NULL, then the function is a no-op, and simply returns NULL.
951 * After creating a reference you can free it in one of the following ways:
953 * - you can talloc_free() any parent of the original pointer. That
954 * will reduce the number of parents of this pointer by 1, and will
955 * cause this pointer to be freed if it runs out of parents.
957 * - you can talloc_free() the pointer itself. That will destroy the
958 * most recently established parent to the pointer and leave the
959 * pointer as a child of its current parent.
961 * For more control on which parent to remove, see talloc_unlink()
962 * @param[in] ctx The additional parent.
964 * @param[in] ptr The pointer you want to create an additional parent for.
966 * @return The original pointer 'ptr', NULL if talloc ran out of
967 * memory in creating the reference.
971 * unsigned int *a, *b, *c;
972 * a = talloc(NULL, unsigned int);
973 * b = talloc(NULL, unsigned int);
974 * c = talloc(a, unsigned int);
975 * // b also serves as a parent of c.
976 * talloc_reference(b, c);
979 * @see talloc_unlink()
981 void *talloc_reference(const void *ctx, const void *ptr);
983 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference_loc((ctx),(ptr), __location__)
984 void *_talloc_reference_loc(const void *context, const void *ptr, const char *location);
988 * @brief Remove a specific parent from a talloc chunk.
990 * The function removes a specific parent from ptr. The context passed must
991 * either be a context used in talloc_reference() with this pointer, or must be
992 * a direct parent of ptr.
994 * Usually you can just use talloc_free() instead of talloc_unlink(), but
995 * sometimes it is useful to have the additional control on which parent is
998 * @param[in] context The talloc parent to remove.
1000 * @param[in] ptr The talloc ptr you want to remove the parent from.
1002 * @return 0 on success, -1 on error.
1004 * @note If the parent has already been removed using talloc_free() then
1005 * this function will fail and will return -1. Likewise, if ptr is NULL,
1006 * then the function will make no modifications and return -1.
1010 * unsigned int *a, *b, *c;
1011 * a = talloc(NULL, unsigned int);
1012 * b = talloc(NULL, unsigned int);
1013 * c = talloc(a, unsigned int);
1014 * // b also serves as a parent of c.
1015 * talloc_reference(b, c);
1016 * talloc_unlink(b, c);
1019 int talloc_unlink(const void *context, void *ptr);
1022 * @brief Provide a talloc context that is freed at program exit.
1024 * This is a handy utility function that returns a talloc context
1025 * which will be automatically freed on program exit. This can be used
1026 * to reduce the noise in memory leak reports.
1028 * @return A talloc context, NULL on error.
1030 void *talloc_autofree_context(void);
1033 * @brief Get the size of a talloc chunk.
1035 * This function lets you know the amount of memory alloced so far by
1036 * this context. It does NOT account for subcontext memory.
1037 * This can be used to calculate the size of an array.
1039 * @param[in] ctx The talloc chunk.
1041 * @return The size of the talloc chunk.
1043 size_t talloc_get_size(const void *ctx);
1046 * @brief Show the parentage of a context.
1048 * @param[in] context The talloc context to look at.
1050 * @param[in] file The output to use, a file, stdout or stderr.
1052 void talloc_show_parents(const void *context, FILE *file);
1055 * @brief Check if a context is parent of a talloc chunk.
1057 * This checks if context is referenced in the talloc hierarchy above ptr.
1059 * @param[in] context The assumed talloc context.
1061 * @param[in] ptr The talloc chunk to check.
1063 * @return Return 1 if this is the case, 0 if not.
1065 int talloc_is_parent(const void *context, const void *ptr);
1068 * @brief Change the parent context of a talloc pointer.
1070 * The function changes the parent context of a talloc pointer. It is typically
1071 * used when the context that the pointer is currently a child of is going to be
1072 * freed and you wish to keep the memory for a longer time.
1074 * The difference between talloc_reparent() and talloc_steal() is that
1075 * talloc_reparent() can specify which parent you wish to change. This is
1076 * useful when a pointer has multiple parents via references.
1078 * @param[in] old_parent
1079 * @param[in] new_parent
1082 * @return Return the pointer you passed. It does not have any
1085 void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
1087 /* @} ******************************************************************/
1090 * @defgroup talloc_array The talloc array functions
1093 * Talloc contains some handy helpers for handling Arrays conveniently
1100 * @brief Allocate an array.
1102 * The macro is equivalent to:
1105 * (type *)talloc_size(ctx, sizeof(type) * count);
1108 * except that it provides integer overflow protection for the multiply,
1109 * returning NULL if the multiply overflows.
1111 * @param[in] ctx The talloc context to hang the result off.
1113 * @param[in] type The type that we want to allocate.
1115 * @param[in] count The number of 'type' elements you want to allocate.
1117 * @return The allocated result, properly cast to 'type *', NULL on
1122 * unsigned int *a, *b;
1123 * a = talloc_zero(NULL, unsigned int);
1124 * b = talloc_array(a, unsigned int, 100);
1128 * @see talloc_array_zero()
1130 void *talloc_array(const void *ctx, #type, unsigned count);
1132 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
1133 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1138 * @brief Allocate an array.
1140 * @param[in] ctx The talloc context to hang the result off.
1142 * @param[in] size The size of an array element.
1144 * @param[in] count The number of elements you want to allocate.
1146 * @return The allocated result, NULL on error.
1148 void *talloc_array_size(const void *ctx, size_t size, unsigned count);
1150 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
1155 * @brief Allocate an array into a typed pointer.
1157 * The macro should be used when you have a pointer to an array and want to
1158 * allocate memory of an array to point at with this pointer. When compiling
1159 * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
1160 * and talloc_get_name() will return the current location in the source file
1163 * @param[in] ctx The talloc context to hang the result off.
1165 * @param[in] ptr The pointer you want to assign the result to.
1167 * @param[in] count The number of elements you want to allocate.
1169 * @return The allocated memory chunk, properly casted. NULL on
1172 void *talloc_array_ptrtype(const void *ctx, const void *ptr, unsigned count);
1174 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
1179 * @brief Get the number of elements in a talloc'ed array.
1181 * A talloc chunk carries its own size, so for talloc'ed arrays it is not
1182 * necessary to store the number of elements explicitly.
1184 * @param[in] ctx The allocated array.
1186 * @return The number of elements in ctx.
1188 size_t talloc_array_length(const void *ctx);
1190 #define talloc_array_length(ctx) (talloc_get_size(ctx)/sizeof(*ctx))
1195 * @brief Allocate a zero-initialized array
1197 * @param[in] ctx The talloc context to hang the result off.
1199 * @param[in] type The type that we want to allocate.
1201 * @param[in] count The number of "type" elements you want to allocate.
1203 * @return The allocated result casted to "type *", NULL on error.
1205 * The talloc_zero_array() macro is equivalent to:
1208 * ptr = talloc_array(ctx, type, count);
1209 * if (ptr) memset(ptr, sizeof(type) * count);
1212 void *talloc_zero_array(const void *ctx, #type, unsigned count);
1214 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
1215 void *_talloc_zero_array(const void *ctx,
1223 * @brief Change the size of a talloc array.
1225 * The macro changes the size of a talloc pointer. The 'count' argument is the
1226 * number of elements of type 'type' that you want the resulting pointer to
1229 * talloc_realloc() has the following equivalences:
1232 * talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
1233 * talloc_realloc(ctx, NULL, type, N) ==> talloc_array(ctx, type, N);
1234 * talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);
1237 * The "context" argument is only used if "ptr" is NULL, otherwise it is
1240 * @param[in] ctx The parent context used if ptr is NULL.
1242 * @param[in] ptr The chunk to be resized.
1244 * @param[in] type The type of the array element inside ptr.
1246 * @param[in] count The intended number of array elements.
1248 * @return The new array, NULL on error. The call will fail either
1249 * due to a lack of memory, or because the pointer has more
1250 * than one parent (see talloc_reference()).
1252 void *talloc_realloc(const void *ctx, void *ptr, #type, size_t count);
1254 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
1255 void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
1260 * @brief Untyped realloc to change the size of a talloc array.
1262 * The macro is useful when the type is not known so the typesafe
1263 * talloc_realloc() cannot be used.
1265 * @param[in] ctx The parent context used if 'ptr' is NULL.
1267 * @param[in] ptr The chunk to be resized.
1269 * @param[in] size The new chunk size.
1271 * @return The new array, NULL on error.
1273 void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);
1275 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
1276 void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
1280 * @brief Provide a function version of talloc_realloc_size.
1282 * This is a non-macro version of talloc_realloc(), which is useful as
1283 * libraries sometimes want a ralloc function pointer. A realloc()
1284 * implementation encapsulates the functionality of malloc(), free() and
1285 * realloc() in one call, which is why it is useful to be able to pass around
1286 * a single function pointer.
1288 * @param[in] context The parent context used if ptr is NULL.
1290 * @param[in] ptr The chunk to be resized.
1292 * @param[in] size The new chunk size.
1294 * @return The new chunk, NULL on error.
1296 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
1298 /* @} ******************************************************************/
1301 * @defgroup talloc_string The talloc string functions.
1304 * talloc string allocation and manipulation functions.
1309 * @brief Duplicate a string into a talloc chunk.
1311 * This function is equivalent to:
1314 * ptr = talloc_size(ctx, strlen(p)+1);
1315 * if (ptr) memcpy(ptr, p, strlen(p)+1);
1318 * This functions sets the name of the new pointer to the passed
1319 * string. This is equivalent to:
1322 * talloc_set_name_const(ptr, ptr)
1325 * @param[in] t The talloc context to hang the result off.
1327 * @param[in] p The string you want to duplicate.
1329 * @return The duplicated string, NULL on error.
1331 char *talloc_strdup(const void *t, const char *p);
1332 char *talloc_strdup_append(char *s, const char *a);
1333 char *talloc_strdup_append_buffer(char *s, const char *a);
1336 * @brief Duplicate a length-limited string into a talloc chunk.
1338 * This function is the talloc equivalent of the C library function strndup(3).
1340 * This functions sets the name of the new pointer to the passed string. This is
1344 * talloc_set_name_const(ptr, ptr)
1347 * @param[in] t The talloc context to hang the result off.
1349 * @param[in] p The string you want to duplicate.
1351 * @param[in] n The maximum string length to duplicate.
1353 * @return The duplicated string, NULL on error.
1355 char *talloc_strndup(const void *t, const char *p, size_t n);
1356 char *talloc_strndup_append(char *s, const char *a, size_t n);
1357 char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
1360 * @brief Format a string given a va_list.
1362 * This function is the talloc equivalent of the C library function
1365 * This functions sets the name of the new pointer to the new string. This is
1369 * talloc_set_name_const(ptr, ptr)
1372 * @param[in] t The talloc context to hang the result off.
1374 * @param[in] fmt The format string.
1376 * @param[in] ap The parameters used to fill fmt.
1378 * @return The formatted string, NULL on error.
1380 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1381 char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1382 char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1385 * @brief Format a string.
1387 * This function is the talloc equivalent of the C library function asprintf(3).
1389 * This functions sets the name of the new pointer to the new string. This is
1393 * talloc_set_name_const(ptr, ptr)
1396 * @param[in] t The talloc context to hang the result off.
1398 * @param[in] fmt The format string.
1400 * @param[in] ... The parameters used to fill fmt.
1402 * @return The formatted string, NULL on error.
1404 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1407 * @brief Append a formatted string to another string.
1409 * This function appends the given formatted string to the given string. Use
1410 * this varient when the string in the current talloc buffer may have been
1411 * truncated in length.
1413 * This functions sets the name of the new pointer to the new
1414 * string. This is equivalent to:
1417 * talloc_set_name_const(ptr, ptr)
1420 * @param[in] s The string to append to.
1422 * @param[in] fmt The format string.
1424 * @param[in] ... The parameters used to fill fmt.
1426 * @return The formatted string, NULL on error.
1428 char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1431 * @brief Append a formatted string to another string.
1433 * @param[in] s The string to append to
1435 * @param[in] fmt The format string.
1437 * @param[in] ... The parameters used to fill fmt.
1439 * @return The formatted string, NULL on error.
1441 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1443 /* @} ******************************************************************/
1446 * @defgroup talloc_debug The talloc debugging support functions
1449 * To aid memory debugging, talloc contains routines to inspect the currently
1450 * allocated memory hierarchy.
1456 * @brief Walk a complete talloc hierarchy.
1458 * This provides a more flexible reports than talloc_report(). It
1459 * will recursively call the callback for the entire tree of memory
1460 * referenced by the pointer. References in the tree are passed with
1461 * is_ref = 1 and the pointer that is referenced.
1463 * You can pass NULL for the pointer, in which case a report is
1464 * printed for the top level memory context, but only if
1465 * talloc_enable_leak_report() or talloc_enable_leak_report_full()
1468 * The recursion is stopped when depth >= max_depth.
1469 * max_depth = -1 means only stop at leaf nodes.
1471 * @param[in] ptr The talloc chunk.
1473 * @param[in] depth Internal parameter to control recursion. Call with 0.
1475 * @param[in] max_depth Maximum recursion level.
1477 * @param[in] callback Function to be called on every chunk.
1479 * @param[in] private_data Private pointer passed to callback.
1481 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
1482 void (*callback)(const void *ptr,
1483 int depth, int max_depth,
1485 void *private_data),
1486 void *private_data);
1489 * @brief Print a talloc hierarchy.
1491 * This provides a more flexible reports than talloc_report(). It
1492 * will let you specify the depth and max_depth.
1494 * @param[in] ptr The talloc chunk.
1496 * @param[in] depth Internal parameter to control recursion. Call with 0.
1498 * @param[in] max_depth Maximum recursion level.
1500 * @param[in] f The file handle to print to.
1502 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
1505 * @brief Print a summary report of all memory used by ptr.
1507 * This provides a more detailed report than talloc_report(). It will
1508 * recursively print the ensire tree of memory referenced by the
1509 * pointer. References in the tree are shown by giving the name of the
1510 * pointer that is referenced.
1512 * You can pass NULL for the pointer, in which case a report is printed
1513 * for the top level memory context, but only if
1514 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
1517 * @param[in] ptr The talloc chunk.
1519 * @param[in] f The file handle to print to.
1523 * unsigned int *a, *b;
1524 * a = talloc(NULL, unsigned int);
1525 * b = talloc(a, unsigned int);
1526 * fprintf(stderr, "Dumping memory tree for a:\n");
1527 * talloc_report_full(a, stderr);
1530 * @see talloc_report()
1532 void talloc_report_full(const void *ptr, FILE *f);
1535 * @brief Print a summary report of all memory used by ptr.
1537 * This function prints a summary report of all memory used by ptr. One line of
1538 * report is printed for each immediate child of ptr, showing the total memory
1539 * and number of blocks used by that child.
1541 * You can pass NULL for the pointer, in which case a report is printed
1542 * for the top level memory context, but only if talloc_enable_leak_report()
1543 * or talloc_enable_leak_report_full() has been called.
1545 * @param[in] ptr The talloc chunk.
1547 * @param[in] f The file handle to print to.
1551 * unsigned int *a, *b;
1552 * a = talloc(NULL, unsigned int);
1553 * b = talloc(a, unsigned int);
1554 * fprintf(stderr, "Summary of memory tree for a:\n");
1555 * talloc_report(a, stderr);
1558 * @see talloc_report_full()
1560 void talloc_report(const void *ptr, FILE *f);
1563 * @brief Enable tracking the use of NULL memory contexts.
1565 * This enables tracking of the NULL memory context without enabling leak
1566 * reporting on exit. Useful for when you want to do your own leak
1567 * reporting call via talloc_report_null_full();
1569 void talloc_enable_null_tracking(void);
1572 * @brief Enable tracking the use of NULL memory contexts.
1574 * This enables tracking of the NULL memory context without enabling leak
1575 * reporting on exit. Useful for when you want to do your own leak
1576 * reporting call via talloc_report_null_full();
1578 void talloc_enable_null_tracking_no_autofree(void);
1581 * @brief Disable tracking of the NULL memory context.
1583 * This disables tracking of the NULL memory context.
1585 void talloc_disable_null_tracking(void);
1588 * @brief Enable leak report when a program exits.
1590 * This enables calling of talloc_report(NULL, stderr) when the program
1591 * exits. In Samba4 this is enabled by using the --leak-report command
1594 * For it to be useful, this function must be called before any other
1595 * talloc function as it establishes a "null context" that acts as the
1596 * top of the tree. If you don't call this function first then passing
1597 * NULL to talloc_report() or talloc_report_full() won't give you the
1598 * full tree printout.
1600 * Here is a typical talloc report:
1603 * talloc report on 'null_context' (total 267 bytes in 15 blocks)
1604 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1605 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1606 * iconv(UTF8,CP850) contains 42 bytes in 2 blocks
1607 * libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1608 * iconv(CP850,UTF8) contains 42 bytes in 2 blocks
1609 * iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
1610 * iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
1613 void talloc_enable_leak_report(void);
1616 * @brief Enable full leak report when a program exits.
1618 * This enables calling of talloc_report_full(NULL, stderr) when the
1619 * program exits. In Samba4 this is enabled by using the
1620 * --leak-report-full command line option.
1622 * For it to be useful, this function must be called before any other
1623 * talloc function as it establishes a "null context" that acts as the
1624 * top of the tree. If you don't call this function first then passing
1625 * NULL to talloc_report() or talloc_report_full() won't give you the
1626 * full tree printout.
1628 * Here is a typical full report:
1631 * full talloc report on 'root' (total 18 bytes in 8 blocks)
1632 * p1 contains 18 bytes in 7 blocks (ref 0)
1633 * r1 contains 13 bytes in 2 blocks (ref 0)
1635 * p2 contains 1 bytes in 1 blocks (ref 1)
1636 * x3 contains 1 bytes in 1 blocks (ref 0)
1637 * x2 contains 1 bytes in 1 blocks (ref 0)
1638 * x1 contains 1 bytes in 1 blocks (ref 0)
1641 void talloc_enable_leak_report_full(void);
1643 /* @} ******************************************************************/
1645 void talloc_set_abort_fn(void (*abort_fn)(const char *reason));
1646 void talloc_set_log_fn(void (*log_fn)(const char *message));
1647 void talloc_set_log_stderr(void);
1649 #if TALLOC_DEPRECATED
1650 #define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
1651 #define talloc_p(ctx, type) talloc(ctx, type)
1652 #define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
1653 #define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
1654 #define talloc_destroy(ctx) talloc_free(ctx)
1655 #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))