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/>.
34 * \section intro_sec Introduction
36 * Talloc is a hierarchical, reference counted memory pool system with
37 * destructors. Quite a mouthful really, but not too bad once you get used to
40 * Perhaps the biggest difference from other memory pool systems is that there
41 * is no distinction between a "talloc context" and a "talloc pointer". Any
42 * pointer returned from talloc() is itself a valid talloc context. This means
46 * struct foo *X = talloc(mem_ctx, struct foo);
47 * X->name = talloc_strdup(X, "foo");
50 * and the pointer X->name would be a "child" of the talloc context "X" which
51 * is itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is
52 * all destroyed, whereas if you do talloc_free(X) then just X and X->name are
53 * destroyed, and if you do talloc_free(X->name) then just the name element of
56 * If you think about this, then what this effectively gives you is an n-ary
57 * tree, where you can free any part of the tree with talloc_free().
59 * To start, you should probably first look at the definitions of
60 * ::TALLOC_CTX, talloc_init(), talloc() and talloc_free().
62 * \section named_blocks Named blocks
64 * Every talloc chunk has a name that can be used as a dynamic type-checking
65 * system. If for some reason like a callback function you had to cast a
66 * "struct foo *" to a "void *" variable, later you can safely reassign the
67 * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
68 * talloc_get_type_abort() macros.
71 * struct foo *X = talloc_get_type_abort(ptr, struct foo);
74 * This will abort if "ptr" does not contain a pointer that has been created
75 * with talloc(mem_ctx, struct foo).
77 * \section multi_threading Multi-Threading
79 * talloc itself does not deal with threads. It is thread-safe (assuming the
80 * underlying "malloc" is), as long as each thread uses different memory
83 * If two threads uses the same context then they need to synchronize in order
84 * to be safe. In particular:
87 * - when using talloc_enable_leak_report(), giving directly NULL as a
88 * parent context implicitly refers to a hidden "null context" global
89 * variable, so this should not be used in a multi-threaded environment
90 * without proper synchronization
91 * - the context returned by talloc_autofree_context() is also global so
92 * shouldn't be used by several threads simultaneously without
96 /** \defgroup talloc_basic Basic Talloc Routines
98 * This module contains the basic talloc routines that are used in everyday
103 * \defgroup talloc_ref Talloc References
105 * This module contains the definitions around talloc references
109 * \defgroup talloc_array Array routines
111 * Talloc contains some handy helpers for handling Arrays conveniently
115 * \defgroup talloc_string String handling routines
117 * Talloc contains some handy string handling functions
121 * \defgroup talloc_debug Debugging support routines
123 * To aid memory debugging, talloc contains routines to inspect the currently
124 * allocated memory hierarchy.
128 * \defgroup talloc_undoc Default group of undocumented stuff
130 * This should be empty...
136 * \typedef TALLOC_CTX
137 * \brief Define a talloc parent type
138 * \ingroup talloc_basic
140 * As talloc is a hierarchial memory allocator, every talloc chunk is a
141 * potential parent to other talloc chunks. So defining a separate type for a
142 * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
143 * as it provides an indicator for function arguments. You will frequently
147 * struct foo *foo_create(TALLOC_CTX *mem_ctx)
149 * struct foo *result;
150 * result = talloc(mem_ctx, struct foo);
151 * if (result == NULL) return NULL;
152 * ... initialize foo ...
157 * In this type of allocating functions it is handy to have a general
158 * TALLOC_CTX type to indicate which parent to put allocated structures on.
160 typedef void TALLOC_CTX;
163 this uses a little trick to allow __LINE__ to be stringified
166 #define __TALLOC_STRING_LINE1__(s) #s
167 #define __TALLOC_STRING_LINE2__(s) __TALLOC_STRING_LINE1__(s)
168 #define __TALLOC_STRING_LINE3__ __TALLOC_STRING_LINE2__(__LINE__)
169 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
172 #ifndef TALLOC_DEPRECATED
173 #define TALLOC_DEPRECATED 0
176 #ifndef PRINTF_ATTRIBUTE
178 /** Use gcc attribute to check printf fns. a1 is the 1-based index of
179 * the parameter containing the format, and a2 the index of the first
180 * argument. Note that some gcc 2.x versions don't handle this
182 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
184 #define PRINTF_ATTRIBUTE(a1, a2)
189 * \def talloc_set_destructor
190 * \brief Assign a function to be called when a chunk is freed
191 * \param ptr The talloc chunk to add a destructor to
192 * \param function The destructor function to be called
193 * \ingroup talloc_basic
195 * The function talloc_set_destructor() sets the "destructor" for the pointer
196 * "ptr". A destructor is a function that is called when the memory used by a
197 * pointer is about to be released. The destructor receives the pointer as an
198 * argument, and should return 0 for success and -1 for failure.
200 * The destructor can do anything it wants to, including freeing other pieces
201 * of memory. A common use for destructors is to clean up operating system
202 * resources (such as open file descriptors) contained in the structure the
203 * destructor is placed on.
205 * You can only place one destructor on a pointer. If you need more than one
206 * destructor then you can create a zero-length child of the pointer and place
207 * an additional destructor on that.
209 * To remove a destructor call talloc_set_destructor() with NULL for the
212 * If your destructor attempts to talloc_free() the pointer that it is the
213 * destructor for then talloc_free() will return -1 and the free will be
214 * ignored. This would be a pointless operation anyway, as the destructor is
215 * only called when the memory is just about to go away.
219 * \def talloc_steal(ctx, ptr)
220 * \brief Change a talloc chunk's parent
221 * \param ctx The new parent context
222 * \param ptr The talloc chunk to move
224 * \ingroup talloc_basic
226 * The talloc_steal() function changes the parent context of a talloc
227 * pointer. It is typically used when the context that the pointer is
228 * currently a child of is going to be freed and you wish to keep the
229 * memory for a longer time.
231 * The talloc_steal() function returns the pointer that you pass it. It
232 * does not have any failure modes.
234 * NOTE: It is possible to produce loops in the parent/child relationship
235 * if you are not careful with talloc_steal(). No guarantees are provided
236 * as to your sanity or the safety of your data if you do this.
238 * To make the changed hierarchy less error-prone, you might consider to use
241 * talloc_steal (ctx, NULL) will return NULL with no sideeffects.
244 /* try to make talloc_set_destructor() and talloc_steal() type safe,
245 if we have a recent gcc */
247 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
248 #define talloc_set_destructor(ptr, function) \
250 int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function); \
251 _talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
253 /* this extremely strange macro is to avoid some braindamaged warning
254 stupidity in gcc 4.1.x */
255 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); __talloc_steal_ret; })
257 #define talloc_set_destructor(ptr, function) \
258 _talloc_set_destructor((ptr), (int (*)(void *))(function))
259 #define _TALLOC_TYPEOF(ptr) void *
260 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
264 * \def talloc_reference(ctx, ptr)
265 * \brief Create an additional talloc parent to a pointer
266 * \param ctx The additional parent
267 * \param ptr The pointer you want to create an additional parent for
269 * \ingroup talloc_ref
271 * The talloc_reference() function makes "context" an additional parent of
274 * The return value of talloc_reference() is always the original pointer
275 * "ptr", unless talloc ran out of memory in creating the reference in which
276 * case it will return NULL (each additional reference consumes around 48
277 * bytes of memory on intel x86 platforms).
279 * If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
281 * After creating a reference you can free it in one of the following ways:
283 * - you can talloc_free() any parent of the original pointer. That
284 * will reduce the number of parents of this pointer by 1, and will
285 * cause this pointer to be freed if it runs out of parents.
287 * - you can talloc_free() the pointer itself. That will destroy the
288 * most recently established parent to the pointer and leave the
289 * pointer as a child of its current parent.
291 * For more control on which parent to remove, see talloc_unlink()
293 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
297 * \def talloc_move(ctx, ptr)
298 * \brief Change a talloc chunk's parent
299 * \param ctx The new parent context
300 * \param ptr Pointer to the talloc chunk to move
302 * \ingroup talloc_basic
304 * talloc_move() has the same effect as talloc_steal(), and additionally sets
305 * the source pointer to NULL. You would use it like this:
308 * struct foo *X = talloc(tmp_ctx, struct foo);
310 * Y = talloc_move(new_ctx, &X);
313 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
315 /* useful macros for creating type checked pointers */
318 * \def talloc(ctx, type)
319 * \brief Main entry point to allocate structures
320 * \param ctx The talloc context to hang the result off
321 * \param type The type that we want to allocate
322 * \return Pointer to a piece of memory, properly cast to "type *"
323 * \ingroup talloc_basic
325 * The talloc() macro is the core of the talloc library. It takes a memory
326 * context and a type, and returns a pointer to a new area of memory of the
329 * The returned pointer is itself a talloc context, so you can use it as the
330 * context argument to more calls to talloc if you wish.
332 * The returned pointer is a "child" of the supplied context. This means that
333 * if you talloc_free() the context then the new child disappears as
334 * well. Alternatively you can free just the child.
336 * The context argument to talloc() can be NULL, in which case a new top
337 * level context is created.
339 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
342 * \def talloc_size(ctx, size)
343 * \brief Untyped allocation
344 * \param ctx The talloc context to hang the result off
345 * \param size Number of char's that you want to allocate
346 * \return The allocated memory chunk
347 * \ingroup talloc_basic
349 * The function talloc_size() should be used when you don't have a convenient
350 * type to pass to talloc(). Unlike talloc(), it is not type safe (as it
351 * returns a void *), so you are on your own for type checking.
353 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
356 * \def talloc_ptrtype(ctx, ptr)
357 * \brief Allocate into a typed pointer
358 * \param ctx The talloc context to hang the result off
359 * \param ptr The pointer you want to assign the result to
360 * \result The allocated memory chunk, properly cast
361 * \ingroup talloc_basic
363 * The talloc_ptrtype() macro should be used when you have a pointer and
364 * want to allocate memory to point at with this pointer. When compiling
365 * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
366 * and talloc_get_name() will return the current location in the source file.
369 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
372 * \def talloc_new(ctx)
373 * \brief Allocate a new 0-sized talloc chunk
374 * \param ctx The talloc parent context
375 * \return A new talloc chunk
376 * \ingroup talloc_basic
378 * This is a utility macro that creates a new memory context hanging off an
379 * exiting context, automatically naming it "talloc_new: __location__" where
380 * __location__ is the source line it is called from. It is particularly
381 * useful for creating a new temporary working context.
383 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
386 * \def talloc_zero(ctx, type)
387 * \brief Allocate a 0-initizialized structure
388 * \param ctx The talloc context to hang the result off
389 * \param type The type that we want to allocate
390 * \return Pointer to a piece of memory, properly cast to "type *"
391 * \ingroup talloc_basic
393 * The talloc_zero() macro is equivalent to:
396 * ptr = talloc(ctx, type);
397 * if (ptr) memset(ptr, 0, sizeof(type));
400 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
403 * \def talloc_zero_size(ctx, size)
404 * \brief Untyped, 0-initialized allocation
405 * \param ctx The talloc context to hang the result off
406 * \param size Number of char's that you want to allocate
407 * \return The allocated memory chunk
408 * \ingroup talloc_basic
410 * The talloc_zero_size() macro is equivalent to:
413 * ptr = talloc_size(ctx, size);
414 * if (ptr) memset(ptr, 0, size);
418 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
420 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
423 * \def talloc_array(ctx, type, count)
424 * \brief Allocate an array
425 * \param ctx The talloc context to hang the result off
426 * \param type The type that we want to allocate
427 * \param count The number of "type" elements you want to allocate
428 * \return The allocated result, properly cast to "type *"
429 * \ingroup talloc_array
431 * The talloc_array() macro is equivalent to::
434 * (type *)talloc_size(ctx, sizeof(type) * count);
437 * except that it provides integer overflow protection for the multiply,
438 * returning NULL if the multiply overflows.
440 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
443 * \def talloc_array_size(ctx, size, count)
444 * \brief Allocate an array
445 * \param ctx The talloc context to hang the result off
446 * \param size The size of an array element
447 * \param count The number of "type" elements you want to allocate
448 * \return The allocated result, properly cast to "type *"
449 * \ingroup talloc_array
451 * The talloc_array_size() function is useful when the type is not
452 * known. It operates in the same way as talloc_array(), but takes a size
455 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
458 * \def talloc_array_ptrtype(ctx, ptr, count)
459 * \brief Allocate an array into a typed pointer
460 * \param ctx The talloc context to hang the result off
461 * \param ptr The pointer you want to assign the result to
462 * \param count The number of elements you want to allocate
463 * \result The allocated memory chunk, properly cast
464 * \ingroup talloc_array
466 * The talloc_array_ptrtype() macro should be used when you have a pointer to
467 * an array and want to allocate memory of an array to point at with this
468 * pointer. When compiling with gcc >= 3 it is typesafe. Note this is a
469 * wrapper of talloc_array_size() and talloc_get_name() will return the
470 * current location in the source file. and not the type.
472 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
475 * \def talloc_array_length(ctx)
476 * \brief Return the number of elements in a talloc'ed array
477 * \param ctx The talloc'ed array
478 * \return The number of elements in ctx
479 * \ingroup talloc_array
481 * A talloc chunk carries its own size, so for talloc'ed arrays it is not
482 * necessary to store the number of elements explicitly.
484 #define talloc_array_length(ctx) ((ctx) ? talloc_get_size(ctx)/sizeof(*ctx) : 0)
487 * \def talloc_realloc(ctx, p, type, count)
488 * \brief Change the size of a talloc array
489 * \param ctx The parent context used if "p" is NULL
490 * \param p The chunk to be resized
491 * \param type The type of the array element inside p
492 * \param count The intended number of array elements
493 * \return The new array
494 * \ingroup talloc_array
496 * The talloc_realloc() macro changes the size of a talloc
497 * pointer. The "count" argument is the number of elements of type "type"
498 * that you want the resulting pointer to hold.
500 * talloc_realloc() has the following equivalences::
503 * talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
504 * talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
505 * talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
508 * The "context" argument is only used if "ptr" is NULL, otherwise it is
511 * talloc_realloc() returns the new pointer, or NULL on failure. The call
512 * will fail either due to a lack of memory, or because the pointer has
513 * more than one parent (see talloc_reference()).
515 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
518 * \def talloc_realloc_size(ctx, ptr, size)
519 * \brief Untyped realloc
520 * \param ctx The parent context used if "ptr" is NULL
521 * \param ptr The chunk to be resized
522 * \param size The new chunk size
523 * \return The new chunk
524 * \ingroup talloc_array
526 * The talloc_realloc_size() function is useful when the type is not known so
527 * the typesafe talloc_realloc() cannot be used.
529 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
532 * \def talloc_memdup(t, p, size)
533 * \brief Duplicate a memory area into a talloc chunk
534 * \param t The talloc context to hang the result off
535 * \param p The memory chunk you want to duplicate
536 * \param size Number of char's that you want copy
537 * \return The allocated memory chunk
538 * \ingroup talloc_basic
540 * The talloc_memdup() function is equivalent to::
543 * ptr = talloc_size(ctx, size);
544 * if (ptr) memcpy(ptr, p, size);
547 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
550 * \def talloc_set_type(ptr, type)
551 * \brief Assign a type to a talloc chunk
552 * \param ptr The talloc chunk to assign the type to
553 * \param type The type to assign
554 * \ingroup talloc_basic
556 * This macro allows you to force the name of a pointer to be a
557 * particular type. This can be used in conjunction with
558 * talloc_get_type() to do type checking on void* pointers.
560 * It is equivalent to this::
563 * talloc_set_name_const(ptr, #type)
566 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
569 * \def talloc_get_type(ptr, type)
570 * \brief Get a typed pointer out of a talloc pointer
571 * \param ptr The talloc pointer to check
572 * \param type The type to check against
573 * \return ptr, properly cast, or NULL
574 * \ingroup talloc_basic
576 * This macro allows you to do type checking on talloc pointers. It is
577 * particularly useful for void* private pointers. It is equivalent to
581 * (type *)talloc_check_name(ptr, #type)
585 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
588 * \def talloc_get_type_abort(ptr, type)
589 * \brief Helper macro to safely turn a void * into a typed pointer
590 * \param ptr The void * to convert
591 * \param type The type that this chunk contains
592 * \return Same value as ptr, type-checked and properly cast
593 * \ingroup talloc_basic
595 * This macro is used together with talloc(mem_ctx, struct foo). If you had to
596 * assing the talloc chunk pointer to some void * variable,
597 * talloc_get_type_abort() is the recommended way to get the convert the void
598 * pointer back to a typed pointer.
600 #define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
603 * \def talloc_find_parent_bytype(ptr, type)
604 * \brief Find a parent context by type
605 * \param ptr The talloc chunk to start from
606 * \param type The type of the parent to look for
607 * \ingroup talloc_basic
609 * Find a parent memory context of the current context that has the given
610 * name. This can be very useful in complex programs where it may be
611 * difficult to pass all information down to the level you need, but you
612 * know the structure you want is a parent of another context.
614 * Like talloc_find_parent_byname() but takes a type, making it typesafe.
616 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
618 #if TALLOC_DEPRECATED
619 #define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
620 #define talloc_p(ctx, type) talloc(ctx, type)
621 #define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
622 #define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
623 #define talloc_destroy(ctx) talloc_free(ctx)
624 #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
627 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
629 /* The following definitions come from talloc.c */
630 void *_talloc(const void *context, size_t size);
633 * \brief Allocate a talloc pool
634 * \param context The talloc context to hang the result off
635 * \param size Size of the talloc pool
636 * \result The talloc pool
637 * \ingroup talloc_basic
639 * A talloc pool is a pure optimization for specific situations. In the
640 * release process for Samba 3.2 we found out that we had become considerably
641 * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU
642 * consumer in benchmarks. For Samba 3.2 we have internally converted many
643 * static buffers to dynamically allocated ones, so malloc(3) being beaten
644 * more was no surprise. But it made us slower.
646 * talloc_pool() is an optimization to call malloc(3) a lot less for the use
647 * pattern Samba has: The SMB protocol is mainly a request/response protocol
648 * where we have to allocate a certain amount of memory per request and free
649 * that after the SMB reply is sent to the client.
651 * talloc_pool() creates a talloc chunk that you can use as a talloc parent
652 * exactly as you would use any other ::TALLOC_CTX. The difference is that
653 * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc
654 * just increments a pointer inside the talloc_pool. This also works
655 * recursively. If you use the child of the talloc pool as a parent for
656 * grand-children, their memory is also taken from the talloc pool.
658 * If you talloc_free() children of a talloc pool, the memory is not given
659 * back to the system. Instead, free(3) is only called if the talloc_pool()
660 * itself is released with talloc_free().
662 * The downside of a talloc pool is that if you talloc_move() a child of a
663 * talloc pool to a talloc parent outside the pool, the whole pool memory is
664 * not free(3)'ed until that moved chunk is also talloc_free()ed.
666 void *talloc_pool(const void *context, size_t size);
667 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
670 * \brief Increase the reference count of a talloc chunk
673 * \ingroup talloc_ref
675 * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
678 * talloc_reference(NULL, ptr);
681 * You can use either syntax, depending on which you think is clearer in
684 * It returns 0 on success and -1 on failure.
686 int talloc_increase_ref_count(const void *ptr);
689 * \brief Return the number of references to a talloc chunk
690 * \param ptr The chunk you are interested in
691 * \return Number of refs
692 * \ingroup talloc_ref
694 size_t talloc_reference_count(const void *ptr);
695 void *_talloc_reference(const void *context, const void *ptr);
698 * \brief Remove a specific parent from a talloc chunk
699 * \param context The talloc parent to remove
700 * \param ptr The talloc ptr you want to remove the parent from
701 * \ingroup talloc_ref
703 * The talloc_unlink() function removes a specific parent from ptr. The
704 * context passed must either be a context used in talloc_reference() with
705 * this pointer, or must be a direct parent of ptr.
707 * Note that if the parent has already been removed using talloc_free() then
708 * this function will fail and will return -1. Likewise, if "ptr" is NULL,
709 * then the function will make no modifications and return -1.
711 * Usually you can just use talloc_free() instead of talloc_unlink(), but
712 * sometimes it is useful to have the additional control on which parent is
715 int talloc_unlink(const void *context, void *ptr);
718 * \brief Assign a name to a talloc chunk
719 * \param ptr The talloc chunk to assign a name to
720 * \param fmt Format string for the name
721 * \param ... printf-style additional arguments
722 * \return The assigned name
723 * \ingroup talloc_basic
725 * Each talloc pointer has a "name". The name is used principally for
726 * debugging purposes, although it is also possible to set and get the name on
727 * a pointer in as a way of "marking" pointers in your code.
729 * The main use for names on pointer is for "talloc reports". See
730 * talloc_report() and talloc_report_full() for details. Also see
731 * talloc_enable_leak_report() and talloc_enable_leak_report_full().
733 * The talloc_set_name() function allocates memory as a child of the
734 * pointer. It is logically equivalent to:
737 * talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
740 * Note that multiple calls to talloc_set_name() will allocate more memory
741 * without releasing the name. All of the memory is released when the ptr is
742 * freed using talloc_free().
744 const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
747 * \brief Assign a name to a talloc chunk
748 * \param ptr The talloc chunk to assign a name to
749 * \param name Format string for the name
750 * \ingroup talloc_basic
752 * The function talloc_set_name_const() is just like talloc_set_name(), but it
753 * takes a string constant, and is much faster. It is extensively used by the
754 * "auto naming" macros, such as talloc_p().
756 * This function does not allocate any memory. It just copies the supplied
757 * pointer into the internal representation of the talloc ptr. This means you
758 * must not pass a name pointer to memory that will disappear before the ptr
759 * is freed with talloc_free().
761 void talloc_set_name_const(const void *ptr, const char *name);
764 * \brief Create a named talloc chunk
765 * \param context The talloc context to hang the result off
766 * \param size Number of char's that you want to allocate
767 * \param fmt Format string for the name
768 * \param ... printf-style additional arguments
769 * \return The allocated memory chunk
770 * \ingroup talloc_basic
772 * The talloc_named() function creates a named talloc pointer. It is
776 * ptr = talloc_size(context, size);
777 * talloc_set_name(ptr, fmt, ....);
781 void *talloc_named(const void *context, size_t size,
782 const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
785 * \brief Basic routine to allocate a chunk of memory
786 * \param context The parent context
787 * \param size The number of char's that we want to allocate
788 * \param name The name the talloc block has
789 * \return The allocated chunk
790 * \ingroup talloc_basic
792 * This is equivalent to:
795 * ptr = talloc_size(context, size);
796 * talloc_set_name_const(ptr, name);
799 void *talloc_named_const(const void *context, size_t size, const char *name);
802 * \brief Return the name of a talloc chunk
803 * \param ptr The talloc chunk
805 * \ingroup talloc_basic
807 * This returns the current name for the given talloc pointer. See
808 * talloc_set_name() for details.
810 const char *talloc_get_name(const void *ptr);
813 * \brief Verify that a talloc chunk carries a specified name
814 * \param ptr The talloc chunk to check
815 * \param name The name to check agains
816 * \ingroup talloc_basic
818 * This function checks if a pointer has the specified name. If it does
819 * then the pointer is returned. It it doesn't then NULL is returned.
821 void *talloc_check_name(const void *ptr, const char *name);
823 void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location);
824 void *talloc_parent(const void *ptr);
825 const char *talloc_parent_name(const void *ptr);
828 * \brief Create a new top level talloc context
829 * \param fmt Format string for the name
830 * \param ... printf-style additional arguments
831 * \return The allocated memory chunk
832 * \ingroup talloc_basic
834 * This function creates a zero length named talloc context as a top level
835 * context. It is equivalent to:
838 * talloc_named(NULL, 0, fmt, ...);
841 void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
844 * \brief Free a chunk of talloc memory
845 * \param ptr The chunk to be freed
847 * \ingroup talloc_basic
849 * The talloc_free() function frees a piece of talloc memory, and all its
850 * children. You can call talloc_free() on any pointer returned by talloc().
852 * The return value of talloc_free() indicates success or failure, with 0
853 * returned for success and -1 for failure. The only possible failure
854 * condition is if the pointer had a destructor attached to it and the
855 * destructor returned -1. See talloc_set_destructor() for details on
858 * If this pointer has an additional parent when talloc_free() is called
859 * then the memory is not actually released, but instead the most
860 * recently established parent is destroyed. See talloc_reference() for
861 * details on establishing additional parents.
863 * For more control on which parent is removed, see talloc_unlink()
865 * talloc_free() operates recursively on its children.
867 int talloc_free(void *ptr);
870 * \brief Free a talloc chunk's children
871 * \param ptr The chunk that you want to free the children of
873 * \ingroup talloc_basic
875 * The talloc_free_children() walks along the list of all children of a talloc
876 * context and talloc_free()s only the children, not the context itself.
878 void talloc_free_children(void *ptr);
879 void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
880 void *_talloc_steal(const void *new_ctx, const void *ptr);
881 void *_talloc_move(const void *new_ctx, const void *pptr);
884 * \brief Return the total size of a talloc chunk including its children
885 * \param ptr The talloc chunk
886 * \return The total size
887 * \ingroup talloc_basic
889 * The talloc_total_size() function returns the total size in bytes used
890 * by this pointer and all child pointers. Mostly useful for debugging.
892 * Passing NULL is allowed, but it will only give a meaningful result if
893 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
896 size_t talloc_total_size(const void *ptr);
899 * \brief Return the number of talloc chunks hanging off a chunk
900 * \param ptr The talloc chunk
901 * \return The total size
902 * \ingroup talloc_basic
904 * The talloc_total_blocks() function returns the total memory block
905 * count used by this pointer and all child pointers. Mostly useful for
908 * Passing NULL is allowed, but it will only give a meaningful result if
909 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
912 size_t talloc_total_blocks(const void *ptr);
915 * \brief Walk a complete talloc hierarchy
916 * \param ptr The talloc chunk
917 * \param depth Internal parameter to control recursion. Call with 0.
918 * \param max_depth Maximum recursion level.
919 * \param callback Function to be called on every chunk
920 * \param private_data Private pointer passed to callback
921 * \ingroup talloc_debug
923 * This provides a more flexible reports than talloc_report(). It
924 * will recursively call the callback for the entire tree of memory
925 * referenced by the pointer. References in the tree are passed with
926 * is_ref = 1 and the pointer that is referenced.
928 * You can pass NULL for the pointer, in which case a report is
929 * printed for the top level memory context, but only if
930 * talloc_enable_leak_report() or talloc_enable_leak_report_full()
933 * The recursion is stopped when depth >= max_depth.
934 * max_depth = -1 means only stop at leaf nodes.
936 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
937 void (*callback)(const void *ptr,
938 int depth, int max_depth,
944 * \brief Print a talloc hierarchy
945 * \param ptr The talloc chunk
946 * \param depth Internal parameter to control recursion. Call with 0.
947 * \param max_depth Maximum recursion level.
948 * \param f The file handle to print to
949 * \ingroup talloc_debug
951 * This provides a more flexible reports than talloc_report(). It
952 * will let you specify the depth and max_depth.
954 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
957 * \brief Print a summary report of all memory used by ptr
958 * \param ptr The talloc chunk
959 * \param f The file handle to print to
960 * \ingroup talloc_debug
962 * This provides a more detailed report than talloc_report(). It will
963 * recursively print the ensire tree of memory referenced by the
964 * pointer. References in the tree are shown by giving the name of the
965 * pointer that is referenced.
967 * You can pass NULL for the pointer, in which case a report is printed
968 * for the top level memory context, but only if
969 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
972 void talloc_report_full(const void *ptr, FILE *f);
975 * \brief Print a summary report of all memory used by ptr
976 * \param ptr The talloc chunk
977 * \param f The file handle to print to
978 * \ingroup talloc_debug
980 * The talloc_report() function prints a summary report of all memory
981 * used by ptr. One line of report is printed for each immediate child of
982 * ptr, showing the total memory and number of blocks used by that child.
984 * You can pass NULL for the pointer, in which case a report is printed
985 * for the top level memory context, but only if
986 * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
989 void talloc_report(const void *ptr, FILE *f);
992 * \brief Enable tracking the use of NULL memory contexts
993 * \ingroup talloc_debug
995 * This enables tracking of the NULL memory context without enabling leak
996 * reporting on exit. Useful for when you want to do your own leak
997 * reporting call via talloc_report_null_full();
999 void talloc_enable_null_tracking(void);
1002 * \brief Disable tracking of the NULL memory context
1003 * \ingroup talloc_debug
1005 * This disables tracking of the NULL memory context.
1008 void talloc_disable_null_tracking(void);
1011 * \brief Enable calling of talloc_report(NULL, stderr) when a program exits
1012 * \ingroup talloc_debug
1014 * This enables calling of talloc_report(NULL, stderr) when the program
1015 * exits. In Samba4 this is enabled by using the --leak-report command
1018 * For it to be useful, this function must be called before any other
1019 * talloc function as it establishes a "null context" that acts as the
1020 * top of the tree. If you don't call this function first then passing
1021 * NULL to talloc_report() or talloc_report_full() won't give you the
1022 * full tree printout.
1024 * Here is a typical talloc report:
1027 talloc report on 'null_context' (total 267 bytes in 15 blocks)
1028 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1029 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1030 iconv(UTF8,CP850) contains 42 bytes in 2 blocks
1031 libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
1032 iconv(CP850,UTF8) contains 42 bytes in 2 blocks
1033 iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
1034 iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
1037 void talloc_enable_leak_report(void);
1040 * \brief Enable calling of talloc_report(NULL, stderr) when a program exits
1041 * \ingroup talloc_debug
1043 * This enables calling of talloc_report_full(NULL, stderr) when the
1044 * program exits. In Samba4 this is enabled by using the
1045 * --leak-report-full command line option.
1047 * For it to be useful, this function must be called before any other
1048 * talloc function as it establishes a "null context" that acts as the
1049 * top of the tree. If you don't call this function first then passing
1050 * NULL to talloc_report() or talloc_report_full() won't give you the
1051 * full tree printout.
1053 * Here is a typical full report:
1055 full talloc report on 'root' (total 18 bytes in 8 blocks)
1056 p1 contains 18 bytes in 7 blocks (ref 0)
1057 r1 contains 13 bytes in 2 blocks (ref 0)
1059 p2 contains 1 bytes in 1 blocks (ref 1)
1060 x3 contains 1 bytes in 1 blocks (ref 0)
1061 x2 contains 1 bytes in 1 blocks (ref 0)
1062 x1 contains 1 bytes in 1 blocks (ref 0)
1065 void talloc_enable_leak_report_full(void);
1066 void *_talloc_zero(const void *ctx, size_t size, const char *name);
1067 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
1068 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1069 void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1070 void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
1073 * \brief Provide a function version of talloc_realloc_size
1074 * \param context The parent context used if "ptr" is NULL
1075 * \param ptr The chunk to be resized
1076 * \param size The new chunk size
1077 * \return The new chunk
1078 * \ingroup talloc_array
1080 * This is a non-macro version of talloc_realloc(), which is useful as
1081 * libraries sometimes want a ralloc function pointer. A realloc()
1082 * implementation encapsulates the functionality of malloc(), free() and
1083 * realloc() in one call, which is why it is useful to be able to pass around
1084 * a single function pointer.
1086 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
1089 * \brief Provide a talloc context that is freed at program exit
1090 * \return A talloc context
1091 * \ingroup talloc_basic
1093 * This is a handy utility function that returns a talloc context
1094 * which will be automatically freed on program exit. This can be used
1095 * to reduce the noise in memory leak reports.
1097 void *talloc_autofree_context(void);
1100 * \brief Get the size of a talloc chunk
1101 * \param ctx The talloc chunk
1103 * \ingroup talloc_basic
1105 * This function lets you know the amount of memory alloced so far by
1106 * this context. It does NOT account for subcontext memory.
1107 * This can be used to calculate the size of an array.
1109 size_t talloc_get_size(const void *ctx);
1112 * \brief Find a parent context by name
1113 * \param ctx The talloc chunk to start from
1114 * \param name The name of the parent we look for
1115 * \ingroup talloc_basic
1117 * Find a parent memory context of the current context that has the given
1118 * name. This can be very useful in complex programs where it may be
1119 * difficult to pass all information down to the level you need, but you
1120 * know the structure you want is a parent of another context.
1122 void *talloc_find_parent_byname(const void *ctx, const char *name);
1123 void talloc_show_parents(const void *context, FILE *file);
1124 int talloc_is_parent(const void *context, const void *ptr);
1127 * \brief Duplicate a string into a talloc chunk
1128 * \param t The talloc context to hang the result off
1129 * \param p The string you want to duplicate
1130 * \return The duplicated string
1131 * \ingroup talloc_string
1133 * The talloc_strdup() function is equivalent to:
1136 * ptr = talloc_size(ctx, strlen(p)+1);
1137 * if (ptr) memcpy(ptr, p, strlen(p)+1);
1140 * This functions sets the name of the new pointer to the passed
1141 * string. This is equivalent to:
1144 * talloc_set_name_const(ptr, ptr)
1147 char *talloc_strdup(const void *t, const char *p);
1148 char *talloc_strdup_append(char *s, const char *a);
1149 char *talloc_strdup_append_buffer(char *s, const char *a);
1152 * \brief Duplicate a length-limited string into a talloc chunk
1153 * \param t The talloc context to hang the result off
1154 * \param p The string you want to duplicate
1155 * \param n The maximum string length to duplicate
1156 * \return The duplicated string
1157 * \ingroup talloc_string
1159 * The talloc_strndup() function is the talloc equivalent of the C
1160 * library function strndup()
1162 * This functions sets the name of the new pointer to the passed
1163 * string. This is equivalent to:
1166 * talloc_set_name_const(ptr, ptr)
1169 char *talloc_strndup(const void *t, const char *p, size_t n);
1170 char *talloc_strndup_append(char *s, const char *a, size_t n);
1171 char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
1174 * \brief Format a string given a va_list
1175 * \param t The talloc context to hang the result off
1176 * \param fmt The format string
1177 * \param ap The parameters used to fill fmt
1178 * \return The formatted string
1179 * \ingroup talloc_string
1181 * The talloc_vasprintf() function is the talloc equivalent of the C
1182 * library function vasprintf()
1184 * This functions sets the name of the new pointer to the new
1185 * string. This is equivalent to:
1188 * talloc_set_name_const(ptr, ptr)
1191 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1192 char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1193 char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1196 * \brief Format a string
1197 * \param t The talloc context to hang the result off
1198 * \param fmt The format string
1199 * \param ... The parameters used to fill fmt
1200 * \return The formatted string
1201 * \ingroup talloc_string
1203 * The talloc_asprintf() function is the talloc equivalent of the C
1204 * library function asprintf()
1206 * This functions sets the name of the new pointer to the new
1207 * string. This is equivalent to:
1210 * talloc_set_name_const(ptr, ptr)
1213 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1216 * \brief Append a formatted string to another string
1217 * \param s The string to append to
1218 * \param fmt The format string
1219 * \param ... The parameters used to fill fmt
1220 * \return The formatted string
1221 * \ingroup talloc_string
1223 * The talloc_asprintf_append() function appends the given formatted string to
1224 * the given string. Use this varient when the string in the current talloc
1225 * buffer may have been truncated in length.
1227 * This functions sets the name of the new pointer to the new
1228 * string. This is equivalent to:
1231 * talloc_set_name_const(ptr, ptr)
1234 char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1237 * \brief Append a formatted string to another string
1238 * \param s The string to append to
1239 * \param fmt The format string
1240 * \param ... The parameters used to fill fmt
1241 * \return The formatted string
1242 * \ingroup talloc_string
1244 * The talloc_asprintf_append() function appends the given formatted string to
1245 * the end of the currently allocated talloc buffer. This routine should be
1246 * used if you create a large string step by step. talloc_asprintf() or
1247 * talloc_asprintf_append() call strlen() at every
1248 * step. talloc_asprintf_append_buffer() uses the existing buffer size of the
1249 * talloc chunk to calculate where to append the string.
1251 * This functions sets the name of the new pointer to the new
1252 * string. This is equivalent to:
1255 * talloc_set_name_const(ptr, ptr)
1258 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1260 void talloc_set_abort_fn(void (*abort_fn)(const char *reason));