diff options
Diffstat (limited to 'lib/talloc')
| -rw-r--r-- | lib/talloc/talloc.h | 1024 |
1 files changed, 1 insertions, 1023 deletions
diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 4b50ba99c2..5c8d5c5fe2 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -29,119 +29,7 @@ #include <stdio.h> #include <stdarg.h> -/** \mainpage - * - * \section intro_sec Introduction - * - * Talloc is a hierarchical, reference counted memory pool system with - * destructors. Quite a mouthful really, but not too bad once you get used to - * it. - * - * Perhaps the biggest difference from other memory pool systems is that there - * is no distinction between a "talloc context" and a "talloc pointer". Any - * pointer returned from talloc() is itself a valid talloc context. This means - * you can do this: - * - * \code - * struct foo *X = talloc(mem_ctx, struct foo); - * X->name = talloc_strdup(X, "foo"); - * \endcode - * - * and the pointer X->name would be a "child" of the talloc context "X" which - * is itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is - * all destroyed, whereas if you do talloc_free(X) then just X and X->name are - * destroyed, and if you do talloc_free(X->name) then just the name element of - * X is destroyed. - * - * If you think about this, then what this effectively gives you is an n-ary - * tree, where you can free any part of the tree with talloc_free(). - * - * \section named_blocks Named blocks - * - * Every talloc chunk has a name that can be used as a dynamic type-checking - * system. If for some reason like a callback function you had to cast a - * "struct foo *" to a "void *" variable, later you can safely reassign the - * "void *" pointer to a "struct foo *" by using the talloc_get_type() or - * talloc_get_type_abort() macros. - * - * \code - * struct foo *X = talloc_get_type_abort(ptr, struct foo); - * \endcode - * - * This will abort if "ptr" does not contain a pointer that has been created - * with talloc(mem_ctx, struct foo). - * - * \section multi_threading Multi-Threading - * - * talloc itself does not deal with threads. It is thread-safe (assuming the - * underlying "malloc" is), as long as each thread uses different memory - * contexts. - * - * If two threads uses the same context then they need to synchronize in order - * to be safe. In particular: - * - * - * - when using talloc_enable_leak_report(), giving directly NULL as a - * parent context implicitly refers to a hidden "null context" global - * variable, so this should not be used in a multi-threaded environment - * without proper synchronization - * - the context returned by talloc_autofree_context() is also global so - * shouldn't be used by several threads simultaneously without - * synchronization. - */ - -/** \defgroup talloc_basic Basic Talloc Routines - * - * This module contains the basic talloc routines that are used in everyday - * programming. - */ - -/** \defgroup talloc_ref Talloc References - * - * This module contains the definitions around talloc references - */ - -/** \defgroup talloc_array Array routines - * - * Talloc contains some handy helpers for handling Arrays conveniently - */ - -/** \defgroup talloc_string String handling routines - * - * Talloc contains some handy string handling functions - */ - -/** \defgroup talloc_debug Debugging support routines - * - * To aid memory debugging, talloc contains routines to inspect the currently - * allocated memory hierarchy. - */ - -/** - * \typedef TALLOC_CTX - * \brief Define a talloc parent type - * \ingroup talloc_basic - * - * As talloc is a hierarchial memory allocator, every talloc chunk is a - * potential parent to other talloc chunks. So defining a separate type for a - * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless, - * as it provides an indicator for function arguments. You will frequently - * write code like - * - * \code - * struct foo *foo_create(TALLOC_CTX *mem_ctx) - * { - * struct foo *result; - * result = talloc(mem_ctx, struct foo); - * if (result == NULL) return NULL; - * ... initialize foo ... - * return result; - * } - * \endcode - * - * In this type of allocating functions it is handy to have a general - * TALLOC_CTX type to indicate which parent to put allocated structures on. - */ +/* this is only needed for compatibility with the old talloc */ typedef void TALLOC_CTX; /* @@ -170,62 +58,6 @@ typedef void TALLOC_CTX; #endif #endif -/** - * \def talloc_set_destructor - * \brief Assign a function to be called when a chunk is freed - * \param ptr The talloc chunk to add a destructor to - * \param function The destructor function to be called - * \ingroup talloc_basic - * - * The function talloc_set_destructor() sets the "destructor" for the pointer - * "ptr". A destructor is a function that is called when the memory used by a - * pointer is about to be released. The destructor receives the pointer as an - * argument, and should return 0 for success and -1 for failure. - * - * The destructor can do anything it wants to, including freeing other pieces - * of memory. A common use for destructors is to clean up operating system - * resources (such as open file descriptors) contained in the structure the - * destructor is placed on. - * - * You can only place one destructor on a pointer. If you need more than one - * destructor then you can create a zero-length child of the pointer and place - * an additional destructor on that. - * - * To remove a destructor call talloc_set_destructor() with NULL for the - * destructor. - * - * If your destructor attempts to talloc_free() the pointer that it is the - * destructor for then talloc_free() will return -1 and the free will be - * ignored. This would be a pointless operation anyway, as the destructor is - * only called when the memory is just about to go away. - */ - -/** - * \def talloc_steal(ctx, ptr) - * \brief Change a talloc chunk's parent - * \param ctx The new parent context - * \param ptr The talloc chunk to move - * \return ptr - * \ingroup talloc_basic - * - * The talloc_steal() function changes the parent context of a talloc - * pointer. It is typically used when the context that the pointer is - * currently a child of is going to be freed and you wish to keep the - * memory for a longer time. - * - * The talloc_steal() function returns the pointer that you pass it. It - * does not have any failure modes. - * - * NOTE: It is possible to produce loops in the parent/child relationship - * if you are not careful with talloc_steal(). No guarantees are provided - * as to your sanity or the safety of your data if you do this. - * - * To make the changed hierarchy less error-prone, you might consider to use - * talloc_move(). - * - * talloc_steal (ctx, NULL) will return NULL with no sideeffects. - */ - /* try to make talloc_set_destructor() and talloc_steal() type safe, if we have a recent gcc */ #if (__GNUC__ >= 3) @@ -245,359 +77,34 @@ typedef void TALLOC_CTX; #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)) #endif -/** - * \def talloc_reference(ctx, ptr) - * \brief Create an additional talloc parent to a pointer - * \param ctx The additional parent - * \param ptr The pointer you want to create an additional parent for - * \return ptr - * \ingroup talloc_ref - * - * The talloc_reference() function makes "context" an additional parent of - * "ptr". - * - * The return value of talloc_reference() is always the original pointer - * "ptr", unless talloc ran out of memory in creating the reference in which - * case it will return NULL (each additional reference consumes around 48 - * bytes of memory on intel x86 platforms). - * - * If "ptr" is NULL, then the function is a no-op, and simply returns NULL. - * - * After creating a reference you can free it in one of the following ways: - * - * - you can talloc_free() any parent of the original pointer. That - * will reduce the number of parents of this pointer by 1, and will - * cause this pointer to be freed if it runs out of parents. - * - * - you can talloc_free() the pointer itself. That will destroy the - * most recently established parent to the pointer and leave the - * pointer as a child of its current parent. - * - * For more control on which parent to remove, see talloc_unlink() - */ #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr)) - - -/** - * \def talloc_move(ctx, ptr) - * \brief Change a talloc chunk's parent - * \param ctx The new parent context - * \param ptr Pointer to the talloc chunk to move - * \return ptr - * \ingroup talloc_basic - * - * talloc_move() has the same effect as talloc_steal(), and additionally sets - * the source pointer to NULL. You would use it like this: - * - * \code - * struct foo *X = talloc(tmp_ctx, struct foo); - * struct foo *Y; - * Y = talloc_move(new_ctx, &X); - * \endcode - */ #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr)) /* useful macros for creating type checked pointers */ - -/** - * \def talloc(ctx, type) - * \brief Main entry point to allocate structures - * \param ctx The talloc context to hang the result off - * \param type The type that we want to allocate - * \return Pointer to a piece of memory, properly cast to "type *" - * \ingroup talloc_basic - * - * The talloc() macro is the core of the talloc library. It takes a memory - * context and a type, and returns a pointer to a new area of memory of the - * given type. - * - * The returned pointer is itself a talloc context, so you can use it as the - * context argument to more calls to talloc if you wish. - * - * The returned pointer is a "child" of the supplied context. This means that - * if you talloc_free() the context then the new child disappears as - * well. Alternatively you can free just the child. - * - * The context argument to talloc() can be NULL, in which case a new top - * level context is created. - */ #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type) - -/** - * \def talloc_size(ctx, size) - * \brief Untyped allocation - * \param ctx The talloc context to hang the result off - * \param size Number of char's that you want to allocate - * \return The allocated memory chunk - * \ingroup talloc_basic - * - * The function talloc_size() should be used when you don't have a convenient - * type to pass to talloc(). Unlike talloc(), it is not type safe (as it - * returns a void *), so you are on your own for type checking. - */ #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__) - -/** - * \def talloc_ptrtype(ctx, ptr) - * \brief Allocate into a typed pointer - * \param ctx The talloc context to hang the result off - * \param ptr The pointer you want to assign the result to - * \result The allocated memory chunk, properly cast - * \ingroup talloc_basic - * - * The talloc_ptrtype() macro should be used when you have a pointer and - * want to allocate memory to point at with this pointer. When compiling - * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size() - * and talloc_get_name() will return the current location in the source file. - * and not the type. - */ #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr))) -/** - * \def talloc_new(ctx) - * \brief Allocate a new 0-sized talloc chunk - * \param ctx The talloc parent context - * \return A new talloc chunk - * \ingroup talloc_basic - * - * This is a utility macro that creates a new memory context hanging off an - * exiting context, automatically naming it "talloc_new: __location__" where - * __location__ is the source line it is called from. It is particularly - * useful for creating a new temporary working context. - */ #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__) -/** - * \def talloc_zero(ctx, type) - * \brief Allocate a 0-initizialized structure - * \param ctx The talloc context to hang the result off - * \param type The type that we want to allocate - * \return Pointer to a piece of memory, properly cast to "type *" - * \ingroup talloc_basic - * - * The talloc_zero() macro is equivalent to: - * - * \code - * ptr = talloc(ctx, type); - * if (ptr) memset(ptr, 0, sizeof(type)); - * \endcode - */ #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type) - -/** - * \def talloc_zero_size(ctx, size) - * \brief Untyped, 0-initialized allocation - * \param ctx The talloc context to hang the result off - * \param size Number of char's that you want to allocate - * \return The allocated memory chunk - * \ingroup talloc_basic - * - * The talloc_zero_size() macro is equivalent to: - * - * \code - * ptr = talloc_size(ctx, size); - * if (ptr) memset(ptr, 0, size); - * \endcode - */ - #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__) #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type) - -/** - * \def talloc_array(ctx, type, count) - * \brief Allocate an array - * \param ctx The talloc context to hang the result off - * \param type The type that we want to allocate - * \param count The number of "type" elements you want to allocate - * \return The allocated result, properly cast to "type *" - * \ingroup talloc_array - * - * The talloc_array() macro is equivalent to:: - * - * \code - * (type *)talloc_size(ctx, sizeof(type) * count); - * \endcode - * - * except that it provides integer overflow protection for the multiply, - * returning NULL if the multiply overflows. - */ #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type) - -/** - * \def talloc_array_size(ctx, size, count) - * \brief Allocate an array - * \param ctx The talloc context to hang the result off - * \param size The size of an array element - * \param count The number of "type" elements you want to allocate - * \return The allocated result, properly cast to "type *" - * \ingroup talloc_array - * - * The talloc_array_size() function is useful when the type is not - * known. It operates in the same way as talloc_array(), but takes a size - * instead of a type. - */ #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__) - -/** - * \def talloc_array_ptrtype(ctx, ptr, count) - * \brief Allocate an array into a typed pointer - * \param ctx The talloc context to hang the result off - * \param ptr The pointer you want to assign the result to - * \param count The number of elements you want to allocate - * \result The allocated memory chunk, properly cast - * \ingroup talloc_array - * - * The talloc_array_ptrtype() macro should be used when you have a pointer to - * an array and want to allocate memory of an array to point at with this - * pointer. When compiling with gcc >= 3 it is typesafe. Note this is a - * wrapper of talloc_array_size() and talloc_get_name() will return the - * current location in the source file. and not the type. - */ #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count) - -/** - * \def talloc_array_length(ctx) - * \brief Return the number of elements in a talloc'ed array - * \param ctx The talloc'ed array - * \return The number of elements in ctx - * \ingroup talloc_array - * - * A talloc chunk carries its own size, so for talloc'ed arrays it is not - * necessary to store the number of elements explicitly. - */ #define talloc_array_length(ctx) ((ctx) ? talloc_get_size(ctx)/sizeof(*ctx) : 0) -/** - * \def talloc_realloc(ctx, p, type, count) - * \brief Change the size of a talloc array - * \param ctx The parent context used if "p" is NULL - * \param p The chunk to be resized - * \param type The type of the array element inside p - * \param count The intended number of array elements - * \return The new array - * \ingroup talloc_array - * - * The talloc_realloc() macro changes the size of a talloc - * pointer. The "count" argument is the number of elements of type "type" - * that you want the resulting pointer to hold. - * - * talloc_realloc() has the following equivalences:: - * - * \code - * talloc_realloc(context, NULL, type, 1) ==> talloc(context, type); - * talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N); - * talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr); - * \endcode - * - * The "context" argument is only used if "ptr" is NULL, otherwise it is - * ignored. - * - * talloc_realloc() returns the new pointer, or NULL on failure. The call - * will fail either due to a lack of memory, or because the pointer has - * more than one parent (see talloc_reference()). - */ #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type) - -/** - * \def talloc_realloc_size(ctx, ptr, size) - * \brief Untyped realloc - * \param ctx The parent context used if "ptr" is NULL - * \param ptr The chunk to be resized - * \param size The new chunk size - * \return The new chunk - * \ingroup talloc_array - * - * The talloc_realloc_size() function is useful when the type is not known so - * the typesafe talloc_realloc() cannot be used. - */ #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__) -/** - * \def talloc_memdup(t, p, size) - * \brief Duplicate a memory area into a talloc chunk - * \param t The talloc context to hang the result off - * \param p The memory chunk you want to duplicate - * \param size Number of char's that you want copy - * \return The allocated memory chunk - * \ingroup talloc_basic - * - * The talloc_memdup() function is equivalent to:: - * - * \code - * ptr = talloc_size(ctx, size); - * if (ptr) memcpy(ptr, p, size); - * \endcode - */ #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__) -/** - * \def talloc_set_type(ptr, type) - * \brief Assign a type to a talloc chunk - * \param ptr The talloc chunk to assign the type to - * \param type The type to assign - * \ingroup talloc_basic - * - * This macro allows you to force the name of a pointer to be a - * particular type. This can be used in conjunction with - * talloc_get_type() to do type checking on void* pointers. - * - * It is equivalent to this:: - * - * \code - * talloc_set_name_const(ptr, #type) - * \endcode - */ #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type) - -/** - * \def talloc_get_type(ptr, type) - * \brief Get a typed pointer out of a talloc pointer - * \param ptr The talloc pointer to check - * \param type The type to check against - * \return ptr, properly cast, or NULL - * \ingroup talloc_basic - * - * This macro allows you to do type checking on talloc pointers. It is - * particularly useful for void* private pointers. It is equivalent to - * this: - * - * \code - * (type *)talloc_check_name(ptr, #type) - * \endcode - */ - #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type) - -/** - * \def talloc_get_type_abort(ptr, type) - * \brief Helper macro to safely turn a void * into a typed pointer - * \param ptr The void * to convert - * \param type The type that this chunk contains - * \return Same value as ptr, type-checked and properly cast - * \ingroup talloc_basic - * - * This macro is used together with talloc(mem_ctx, struct foo). If you had to - * assing the talloc chunk pointer to some void * variable, - * talloc_get_type_abort() is the recommended way to get the convert the void - * pointer back to a typed pointer. - */ #define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__) -/** - * \def talloc_find_parent_bytype(ptr, type) - * \brief Find a parent context by type - * \param ptr The talloc chunk to start from - * \param type The type of the parent to look for - * \ingroup talloc_basic - * - * Find a parent memory context of the current context that has the given - * name. This can be very useful in complex programs where it may be - * difficult to pass all information down to the level you need, but you - * know the structure you want is a parent of another context. - * - * Like talloc_find_parent_byname() but takes a type, making it typesafe. - */ #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type) #if TALLOC_DEPRECATED @@ -615,596 +122,67 @@ typedef void TALLOC_CTX; void *_talloc(const void *context, size_t size); void *talloc_pool(const void *context, size_t size); void _talloc_set_destructor(const void *ptr, int (*destructor)(void *)); - -/** - * \brief Increase the reference count of a talloc chunk - * \param ptr - * \return success? - * \ingroup talloc_ref - * - * The talloc_increase_ref_count(ptr) function is exactly equivalent to: - * - * \code - * talloc_reference(NULL, ptr); - * \endcode - * - * You can use either syntax, depending on which you think is clearer in - * your code. - * - * It returns 0 on success and -1 on failure. - */ int talloc_increase_ref_count(const void *ptr); - -/** - * \brief Return the number of references to a talloc chunk - * \param ptr The chunk you are interested in - * \return Number of refs - * \ingroup talloc_ref - */ size_t talloc_reference_count(const void *ptr); void *_talloc_reference(const void *context, const void *ptr); - -/** - * \brief Remove a specific parent from a talloc chunk - * \param context The talloc parent to remove - * \param ptr The talloc ptr you want to remove the parent from - * \ingroup talloc_ref - * - * The talloc_unlink() function removes a specific parent from ptr. The - * context passed must either be a context used in talloc_reference() with - * this pointer, or must be a direct parent of ptr. - * - * Note that if the parent has already been removed using talloc_free() then - * this function will fail and will return -1. Likewise, if "ptr" is NULL, - * then the function will make no modifications and return -1. - * - * Usually you can just use talloc_free() instead of talloc_unlink(), but - * sometimes it is useful to have the additional control on which parent is - * removed. - */ int talloc_unlink(const void *context, void *ptr); - -/** - * \brief Assign a name to a talloc chunk - * \param ptr The talloc chunk to assign a name to - * \param fmt Format string for the name - * \param ... printf-style additional arguments - * \return The assigned name - * \ingroup talloc_basic - * - * Each talloc pointer has a "name". The name is used principally for - * debugging purposes, although it is also possible to set and get the name on - * a pointer in as a way of "marking" pointers in your code. - * - * The main use for names on pointer is for "talloc reports". See - * talloc_report() and talloc_report_full() for details. Also see - * talloc_enable_leak_report() and talloc_enable_leak_report_full(). - * - * The talloc_set_name() function allocates memory as a child of the - * pointer. It is logically equivalent to: - * - * \code - * talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...)); - * \endcode - * - * Note that multiple calls to talloc_set_name() will allocate more memory - * without releasing the name. All of the memory is released when the ptr is - * freed using talloc_free(). - */ const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3); - -/** - * \brief Assign a name to a talloc chunk - * \param ptr The talloc chunk to assign a name to - * \param name Format string for the name - * \ingroup talloc_basic - * - * The function talloc_set_name_const() is just like talloc_set_name(), but it - * takes a string constant, and is much faster. It is extensively used by the - * "auto naming" macros, such as talloc_p(). - * - * This function does not allocate any memory. It just copies the supplied - * pointer into the internal representation of the talloc ptr. This means you - * must not pass a name pointer to memory that will disappear before the ptr - * is freed with talloc_free(). - */ void talloc_set_name_const(const void *ptr, const char *name); - -/** - * \brief Create a named talloc chunk - * \param context The talloc context to hang the result off - * \param size Number of char's that you want to allocate - * \param fmt Format string for the name - * \param ... printf-style additional arguments - * \return The allocated memory chunk - * \ingroup talloc_basic - * - * The talloc_named() function creates a named talloc pointer. It is - * equivalent to: - * - * \code - * ptr = talloc_size(context, size); - * talloc_set_name(ptr, fmt, ....); - * \endcode - * - */ void *talloc_named(const void *context, size_t size, const char *fmt, ...) PRINTF_ATTRIBUTE(3,4); - -/** - * \brief Basic routine to allocate a chunk of memory - * \param context The parent context - * \param size The number of char's that we want to allocate - * \param name The name the talloc block has - * \return The allocated chunk - * \ingroup talloc_basic - * - * This is equivalent to: - * - * \code - * ptr = talloc_size(context, size); - * talloc_set_name_const(ptr, name); - * \endcode - */ void *talloc_named_const(const void *context, size_t size, const char *name); - -/** - * \brief Return the name of a talloc chunk - * \param ptr The talloc chunk - * \return The name - * \ingroup talloc_basic - * - * This returns the current name for the given talloc pointer. See - * talloc_set_name() for details. - */ const char *talloc_get_name(const void *ptr); - -/** - * \brief Verify that a talloc chunk carries a specified name - * \param ptr The talloc chunk to check - * \param name The name to check agains - * \ingroup talloc_basic - * - * This function checks if a pointer has the specified name. If it does - * then the pointer is returned. It it doesn't then NULL is returned. - */ void *talloc_check_name(const void *ptr, const char *name); - void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location); void *talloc_parent(const void *ptr); const char *talloc_parent_name(const void *ptr); - -/** - * \brief Create a new top level talloc context - * \param fmt Format string for the name - * \param ... printf-style additional arguments - * \return The allocated memory chunk - * \ingroup talloc_basic - * - * This function creates a zero length named talloc context as a top level - * context. It is equivalent to: - * - * \code - * talloc_named(NULL, 0, fmt, ...); - * \endcode - */ void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2); - -/** - * \brief Free a chunk of talloc memory - * \param ptr The chunk to be freed - * \return success? - * \ingroup talloc_basic - * - * The talloc_free() function frees a piece of talloc memory, and all its - * children. You can call talloc_free() on any pointer returned by talloc(). - * - * The return value of talloc_free() indicates success or failure, with 0 - * returned for success and -1 for failure. The only possible failure - * condition is if the pointer had a destructor attached to it and the - * destructor returned -1. See talloc_set_destructor() for details on - * destructors. - * - * If this pointer has an additional parent when talloc_free() is called - * then the memory is not actually released, but instead the most - * recently established parent is destroyed. See talloc_reference() for - * details on establishing additional parents. - * - * For more control on which parent is removed, see talloc_unlink() - * - * talloc_free() operates recursively on its children. - */ int talloc_free(void *ptr); - -/** - * \brief Free a talloc chunk's children - * \param ptr The chunk that you want to free the children of - * \return success? - * \ingroup talloc_basic - * - * The talloc_free_children() walks along the list of all children of a talloc - * context and talloc_free()s only the children, not the context itself. - */ void talloc_free_children(void *ptr); void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name); void *_talloc_steal(const void *new_ctx, const void *ptr); void *_talloc_move(const void *new_ctx, const void *pptr); - -/** - * \brief Return the total size of a talloc chunk including its children - * \param ptr The talloc chunk - * \return The total size - * \ingroup talloc_basic - * - * The talloc_total_size() function returns the total size in bytes used - * by this pointer and all child pointers. Mostly useful for debugging. - * - * Passing NULL is allowed, but it will only give a meaningful result if - * talloc_enable_leak_report() or talloc_enable_leak_report_full() has - * been called. - */ size_t talloc_total_size(const void *ptr); - -/** - * \brief Return the number of talloc chunks hanging off a chunk - * \param ptr The talloc chunk - * \return The total size - * \ingroup talloc_basic - * - * The talloc_total_blocks() function returns the total memory block - * count used by this pointer and all child pointers. Mostly useful for - * debugging. - * - * Passing NULL is allowed, but it will only give a meaningful result if - * talloc_enable_leak_report() or talloc_enable_leak_report_full() has - * been called. - */ size_t talloc_total_blocks(const void *ptr); - -/** - * \brief Walk a complete talloc hierarchy - * \param ptr The talloc chunk - * \param depth Internal parameter to control recursion. Call with 0. - * \param max_depth Maximum recursion level. - * \param callback Function to be called on every chunk - * \param private_data Private pointer passed to callback - * \ingroup talloc_debug - * - * This provides a more flexible reports than talloc_report(). It - * will recursively call the callback for the entire tree of memory - * referenced by the pointer. References in the tree are passed with - * is_ref = 1 and the pointer that is referenced. - * - * You can pass NULL for the pointer, in which case a report is - * printed for the top level memory context, but only if - * talloc_enable_leak_report() or talloc_enable_leak_report_full() - * has been called. - * - * The recursion is stopped when depth >= max_depth. - * max_depth = -1 means only stop at leaf nodes. - */ void talloc_report_depth_cb(const void *ptr, int depth, int max_depth, void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *private_data), void *private_data); - -/** - * \brief Print a talloc hierarchy - * \param ptr The talloc chunk - * \param depth Internal parameter to control recursion. Call with 0. - * \param max_depth Maximum recursion level. - * \param f The file handle to print to - * \ingroup talloc_debug - * - * This provides a more flexible reports than talloc_report(). It - * will let you specify the depth and max_depth. - */ void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f); - -/** - * \brief Print a summary report of all memory used by ptr - * \param ptr The talloc chunk - * \param f The file handle to print to - * \ingroup talloc_debug - * - * This provides a more detailed report than talloc_report(). It will - * recursively print the ensire tree of memory referenced by the - * pointer. References in the tree are shown by giving the name of the - * pointer that is referenced. - * - * You can pass NULL for the pointer, in which case a report is printed - * for the top level memory context, but only if - * talloc_enable_leak_report() or talloc_enable_leak_report_full() has - * been called. - */ void talloc_report_full(const void *ptr, FILE *f); - -/** - * \brief Print a summary report of all memory used by ptr - * \param ptr The talloc chunk - * \param f The file handle to print to - * \ingroup talloc_debug - * - * The talloc_report() function prints a summary report of all memory - * used by ptr. One line of report is printed for each immediate child of - * ptr, showing the total memory and number of blocks used by that child. - * - * You can pass NULL for the pointer, in which case a report is printed - * for the top level memory context, but only if - * talloc_enable_leak_report() or talloc_enable_leak_report_full() has - * been called. - */ void talloc_report(const void *ptr, FILE *f); - -/** - * \brief Enable tracking the use of NULL memory contexts - * \ingroup talloc_debug - * - * This enables tracking of the NULL memory context without enabling leak - * reporting on exit. Useful for when you want to do your own leak - * reporting call via talloc_report_null_full(); - */ void talloc_enable_null_tracking(void); - -/** - * \brief Disable tracking of the NULL memory context - * \ingroup talloc_debug - * - * This disables tracking of the NULL memory context. - */ - void talloc_disable_null_tracking(void); - -/** - * \brief Enable calling of talloc_report(NULL, stderr) when a program exits - * \ingroup talloc_debug - * - * This enables calling of talloc_report(NULL, stderr) when the program - * exits. In Samba4 this is enabled by using the --leak-report command - * line option. - * - * For it to be useful, this function must be called before any other - * talloc function as it establishes a "null context" that acts as the - * top of the tree. If you don't call this function first then passing - * NULL to talloc_report() or talloc_report_full() won't give you the - * full tree printout. - * - * Here is a typical talloc report: - * -\verbatim -talloc report on 'null_context' (total 267 bytes in 15 blocks) - libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks - libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks - iconv(UTF8,CP850) contains 42 bytes in 2 blocks - libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks - iconv(CP850,UTF8) contains 42 bytes in 2 blocks - iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks - iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks -\endverbatim - */ void talloc_enable_leak_report(void); - -/** - * \brief Enable calling of talloc_report(NULL, stderr) when a program exits - * \ingroup talloc_debug - * - * This enables calling of talloc_report_full(NULL, stderr) when the - * program exits. In Samba4 this is enabled by using the - * --leak-report-full command line option. - * - * For it to be useful, this function must be called before any other - * talloc function as it establishes a "null context" that acts as the - * top of the tree. If you don't call this function first then passing - * NULL to talloc_report() or talloc_report_full() won't give you the - * full tree printout. - * - * Here is a typical full report: -\verbatim -full talloc report on 'root' (total 18 bytes in 8 blocks) - p1 contains 18 bytes in 7 blocks (ref 0) - r1 contains 13 bytes in 2 blocks (ref 0) - reference to: p2 - p2 contains 1 bytes in 1 blocks (ref 1) - x3 contains 1 bytes in 1 blocks (ref 0) - x2 contains 1 bytes in 1 blocks (ref 0) - x1 contains 1 bytes in 1 blocks (ref 0) -\endverbatim -*/ void talloc_enable_leak_report_full(void); void *_talloc_zero(const void *ctx, size_t size, const char *name); void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name); void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name); void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name); void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name); - -/** - * \brief Provide a function version of talloc_realloc_size - * \param context The parent context used if "ptr" is NULL - * \param ptr The chunk to be resized - * \param size The new chunk size - * \return The new chunk - * \ingroup talloc_array - * - * This is a non-macro version of talloc_realloc(), which is useful as - * libraries sometimes want a ralloc function pointer. A realloc() - * implementation encapsulates the functionality of malloc(), free() and - * realloc() in one call, which is why it is useful to be able to pass around - * a single function pointer. -*/ void *talloc_realloc_fn(const void *context, void *ptr, size_t size); - -/** - * \brief Provide a talloc context that is freed at program exit - * \return A talloc context - * \ingroup talloc_basic - * - * This is a handy utility function that returns a talloc context - * which will be automatically freed on program exit. This can be used - * to reduce the noise in memory leak reports. - */ void *talloc_autofree_context(void); - -/** - * \brief Get the size of a talloc chunk - * \param ctx The talloc chunk - * \return The size - * \ingroup talloc_basic - * - * This function lets you know the amount of memory alloced so far by - * this context. It does NOT account for subcontext memory. - * This can be used to calculate the size of an array. - */ size_t talloc_get_size(const void *ctx); - -/** - * \brief Find a parent context by name - * \param ctx The talloc chunk to start from - * \param name The name of the parent we look for - * \ingroup talloc_basic - * - * Find a parent memory context of the current context that has the given - * name. This can be very useful in complex programs where it may be - * difficult to pass all information down to the level you need, but you - * know the structure you want is a parent of another context. - */ void *talloc_find_parent_byname(const void *ctx, const char *name); void talloc_show_parents(const void *context, FILE *file); int talloc_is_parent(const void *context, const void *ptr); -/** - * \brief Duplicate a string into a talloc chunk - * \param t The talloc context to hang the result off - * \param p The string you want to duplicate - * \return The duplicated string - * \ingroup talloc_string - * - * The talloc_strdup() function is equivalent to: - * - * \code - * ptr = talloc_size(ctx, strlen(p)+1); - * if (ptr) memcpy(ptr, p, strlen(p)+1); - * \endcode - * - * This functions sets the name of the new pointer to the passed - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_strdup(const void *t, const char *p); char *talloc_strdup_append(char *s, const char *a); char *talloc_strdup_append_buffer(char *s, const char *a); -/** - * \brief Duplicate a length-limited string into a talloc chunk - * \param t The talloc context to hang the result off - * \param p The string you want to duplicate - * \param n The maximum string length to duplicate - * \return The duplicated string - * \ingroup talloc_string - * - * The talloc_strndup() function is the talloc equivalent of the C - * library function strndup() - * - * This functions sets the name of the new pointer to the passed - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_strndup(const void *t, const char *p, size_t n); char *talloc_strndup_append(char *s, const char *a, size_t n); char *talloc_strndup_append_buffer(char *s, const char *a, size_t n); -/** - * \brief Format a string given a va_list - * \param t The talloc context to hang the result off - * \param fmt The format string - * \param ap The parameters used to fill fmt - * \return The formatted string - * \ingroup talloc_string - * - * The talloc_vasprintf() function is the talloc equivalent of the C - * library function vasprintf() - * - * This functions sets the name of the new pointer to the new - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0); char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0); char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0); -/** - * \brief Format a string - * \param t The talloc context to hang the result off - * \param fmt The format string - * \param ... The parameters used to fill fmt - * \return The formatted string - * \ingroup talloc_string - * - * The talloc_asprintf() function is the talloc equivalent of the C - * library function asprintf() - * - * This functions sets the name of the new pointer to the new - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3); - -/** - * \brief Append a formatted string to another string - * \param s The string to append to - * \param fmt The format string - * \param ... The parameters used to fill fmt - * \return The formatted string - * \ingroup talloc_string - * - * The talloc_asprintf_append() function appends the given formatted string to - * the given string. Use this varient when the string in the current talloc - * buffer may have been truncated in length. - * - * This functions sets the name of the new pointer to the new - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3); - -/** - * \brief Append a formatted string to another string - * \param s The string to append to - * \param fmt The format string - * \param ... The parameters used to fill fmt - * \return The formatted string - * \ingroup talloc_string - * - * The talloc_asprintf_append() function appends the given formatted string to - * the end of the currently allocated talloc buffer. This routine should be - * used if you create a large string step by step. talloc_asprintf() or - * talloc_asprintf_append() call strlen() at every - * step. talloc_asprintf_append_buffer() uses the existing buffer size of the - * talloc chunk to calculate where to append the string. - * - * This functions sets the name of the new pointer to the new - * string. This is equivalent to: - * - * \code - * talloc_set_name_const(ptr, ptr) - * \endcode - */ char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3); void talloc_set_abort_fn(void (*abort_fn)(const char *reason)); |