From 66dc53ee017d74a6f610bbe04337f064901fe2a1 Mon Sep 17 00:00:00 2001 From: Stefan Metzmacher Date: Fri, 20 Mar 2009 16:27:17 +0100 Subject: socket_wrapper: fix connect() for dgram sockets, if the destination isn't there yet metze --- lib/socket_wrapper/socket_wrapper.c | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'lib') diff --git a/lib/socket_wrapper/socket_wrapper.c b/lib/socket_wrapper/socket_wrapper.c index 44082e78a1..1d35c8d20c 100644 --- a/lib/socket_wrapper/socket_wrapper.c +++ b/lib/socket_wrapper/socket_wrapper.c @@ -1686,10 +1686,14 @@ _PUBLIC_ int swrap_connect(int s, const struct sockaddr *serv_addr, socklen_t ad ret = sockaddr_convert_to_un(si, (const struct sockaddr *)serv_addr, addrlen, &un_addr, 0, NULL); if (ret == -1) return -1; - swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); + if (si->type == SOCK_DGRAM) { + ret = 0; + } else { + swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); - ret = real_connect(s, (struct sockaddr *)&un_addr, - sizeof(struct sockaddr_un)); + ret = real_connect(s, (struct sockaddr *)&un_addr, + sizeof(struct sockaddr_un)); + } /* to give better errors */ if (ret == -1 && errno == ENOENT) { -- cgit From f55e84e904173bed8dc9099ad523ca1e7be12355 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 10:17:24 +0100 Subject: Add a basic Doxyfile for talloc --- lib/talloc/Doxyfile | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 lib/talloc/Doxyfile (limited to 'lib') diff --git a/lib/talloc/Doxyfile b/lib/talloc/Doxyfile new file mode 100644 index 0000000000..0ccf563d75 --- /dev/null +++ b/lib/talloc/Doxyfile @@ -0,0 +1,8 @@ +OUTPUT_DIRECTORY = doc +PROJECT_NAME = Talloc +OPTIMIZE_OUTPUT_FOR_C = YES +GENERATE_LATEX = NO +GENERATE_MAN = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = PRINTF_ATTRIBUTE(x,y)= -- cgit From d21212c9192b41a3fdc7e96cb9bf0125a1dc6c2d Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 12:43:08 +0100 Subject: Convert the contents of talloc_guide.txt to doxygen-style talloc.h comments talloc_guide.txt was partly outdated, and as going through talloc.h now shows it was incomplete. --- lib/talloc/talloc.h | 1024 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 1023 insertions(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 5c8d5c5fe2..4b50ba99c2 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -29,7 +29,119 @@ #include #include -/* this is only needed for compatibility with the old talloc */ +/** \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. + */ typedef void TALLOC_CTX; /* @@ -58,6 +170,62 @@ 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) @@ -77,34 +245,359 @@ 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 @@ -122,67 +615,596 @@ 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)); -- cgit From 3f9c30022a53a37ad829f8882a9a5161fcadda8b Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 16:40:33 +0100 Subject: Delete talloc_guide.txt --- lib/talloc/talloc_guide.txt | 694 -------------------------------------------- 1 file changed, 694 deletions(-) delete mode 100644 lib/talloc/talloc_guide.txt (limited to 'lib') diff --git a/lib/talloc/talloc_guide.txt b/lib/talloc/talloc_guide.txt deleted file mode 100644 index 3201fe6f0f..0000000000 --- a/lib/talloc/talloc_guide.txt +++ /dev/null @@ -1,694 +0,0 @@ -Using talloc in Samba4 -====================== - -.. contents:: - -Andrew Tridgell -September 2004 - -The most current version of this document is available at - http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt - -If you are used to the "old" talloc from Samba3 before 3.0.20 then please read -this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the -Samba4 talloc has been ported back to Samba3, so this guide applies to both. - -The new 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 change from Samba3 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:: - - struct foo *X = talloc(mem_ctx, struct foo); - X->name = talloc_strdup(X, "foo"); - -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(). - -If you find this confusing, then I suggest you run the testsuite to -watch talloc in action. You may also like to add your own tests to -testsuite.c to clarify how some particular situation is handled. - - -Performance ------------ - -All the additional features of talloc() over malloc() do come at a -price. We have a simple performance test in Samba4 that measures -talloc() versus malloc() performance, and it seems that talloc() is -about 4% slower than malloc() on my x86 Debian Linux box. For Samba, -the great reduction in code complexity that we get by using talloc -makes this worthwhile, especially as the total overhead of -talloc/malloc in Samba is already quite small. - - -talloc API ----------- - -The following is a complete guide to the talloc API. Read it all at -least twice. - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(type *)talloc(const void *context, type); - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_size(const void *context, size_t size); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -int talloc_free(void *ptr); - -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_children(void *ptr); - -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_reference(const void *context, const void *ptr); - -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() - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -int talloc_unlink(const void *context, const void *ptr); - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_set_destructor(const void *ptr, int (*destructor)(void *)); - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -int talloc_increase_ref_count(const void *ptr); - -The talloc_increase_ref_count(ptr) function is exactly equivalent to: - - talloc_reference(NULL, ptr); - -You can use either syntax, depending on which you think is clearer in -your code. - -It returns 0 on success and -1 on failure. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -size_t talloc_reference_count(const void *ptr); - -Return the number of references to the pointer. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_set_name(const void *ptr, const char *fmt, ...); - -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: - talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...)); - -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(). - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_set_name_const(const void *ptr, const char *name); - -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_named(const void *context, size_t size, const char *fmt, ...); - -The talloc_named() function creates a named talloc pointer. It is -equivalent to: - - ptr = talloc_size(context, size); - talloc_set_name(ptr, fmt, ....); - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_named_const(const void *context, size_t size, const char *name); - -This is equivalent to:: - - ptr = talloc_size(context, size); - talloc_set_name_const(ptr, name); - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -const char *talloc_get_name(const void *ptr); - -This returns the current name for the given talloc pointer. See -talloc_set_name() for details. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_init(const char *fmt, ...); - -This function creates a zero length named talloc context as a top -level context. It is equivalent to:: - - talloc_named(NULL, 0, fmt, ...); - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_new(void *ctx); - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(type *)talloc_realloc(const void *context, void *ptr, type, count); - -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:: - - 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); - -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()). - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_realloc_size(const void *context, void *ptr, size_t size); - -the talloc_realloc_size() function is useful when the type is not -known so the typesafe talloc_realloc() cannot be used. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_steal(const void *new_ctx, const void *ptr); - -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. - -talloc_steal (new_ctx, NULL) will return NULL with no sideeffects. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -size_t talloc_total_size(const void *ptr); - -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_blocks(const void *ptr); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -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 *priv), - void *priv); - -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_file(const void *ptr, int depth, int max_depth, FILE *f); - -This provides a more flexible reports than talloc_report(). It -will let you specify the depth and max_depth. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_report(const void *ptr, FILE *f); - -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_full(const void *ptr, FILE *f); - -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_enable_leak_report(void); - -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: - -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 - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_enable_leak_report_full(void); - -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: - -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) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void talloc_enable_null_tracking(void); - -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_disable_null_tracking(void); - -This disables tracking of the NULL memory context. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(type *)talloc_zero(const void *ctx, type); - -The talloc_zero() macro is equivalent to:: - - ptr = talloc(ctx, type); - if (ptr) memset(ptr, 0, sizeof(type)); - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_zero_size(const void *ctx, size_t size) - -The talloc_zero_size() function is useful when you don't have a known type - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_memdup(const void *ctx, const void *p, size_t size); - -The talloc_memdup() function is equivalent to:: - - ptr = talloc_size(ctx, size); - if (ptr) memcpy(ptr, p, size); - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_strdup(const void *ctx, const char *p); - -The talloc_strdup() function is equivalent to:: - - ptr = talloc_size(ctx, strlen(p)+1); - if (ptr) memcpy(ptr, p, strlen(p)+1); - -This functions sets the name of the new pointer to the passed -string. This is equivalent to:: - - talloc_set_name_const(ptr, ptr) - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_strndup(const void *t, const char *p, size_t n); - -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: - talloc_set_name_const(ptr, ptr) - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_append_string(const void *t, char *orig, const char *append); - -The talloc_append_string() function appends the given formatted -string to the given string. - -This function sets the name of the new pointer to the new -string. This is equivalent to:: - - talloc_set_name_const(ptr, ptr) - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_vasprintf(const void *t, const char *fmt, va_list ap); - -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:: - - talloc_set_name_const(ptr, ptr) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_asprintf(const void *t, const char *fmt, ...); - -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:: - - talloc_set_name_const(ptr, ptr) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_asprintf_append(char *s, const char *fmt, ...); - -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:: - - talloc_set_name_const(ptr, ptr) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...); - -The talloc_asprintf_append() function appends the given formatted -string to the end of the currently allocated talloc buffer. -Use this varient when the string in the current talloc buffer has -not been changed. - -This functions sets the name of the new pointer to the new -string. This is equivalent to:: - - talloc_set_name_const(ptr, ptr) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -((type *)talloc_array(const void *ctx, type, uint_t count); - -The talloc_array() macro is equivalent to:: - - (type *)talloc_size(ctx, sizeof(type) * count); - -except that it provides integer overflow protection for the multiply, -returning NULL if the multiply overflows. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_array_size(const void *ctx, size_t size, uint_t count); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count); - -The talloc_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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size); - -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_autofree_context(void); - -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_check_name(const void *ptr, const char *name); - -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. - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(type *)talloc_get_type(const void *ptr, type); - -This macro allows you to do type checking on talloc pointers. It is -particularly useful for void* private pointers. It is equivalent to -this:: - - (type *)talloc_check_name(ptr, #type) - - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -talloc_set_type(const void *ptr, type); - -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:: - - talloc_set_name_const(ptr, #type) - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -talloc_get_size(const void *ctx); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -void *talloc_find_parent_byname(const void *ctx, const char *name); - -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. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -(type *)talloc_find_parent_bytype(ctx, type); - -Like talloc_find_parent_byname() but takes a type, making it typesafe. - -- cgit From ba42320c7e9f5ccbd32eccbfb1f2d77e13b3a318 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 16:50:58 +0100 Subject: Add a default "undocumented" module --- lib/talloc/talloc.h | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 4b50ba99c2..523a4840d3 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -117,6 +117,13 @@ * allocated memory hierarchy. */ +/** \defgroup todo Default group of undocumented stuff + * + * This should be empty... + */ + +/*\{*/ + /** * \typedef TALLOC_CTX * \brief Define a talloc parent type @@ -1210,3 +1217,5 @@ char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIB void talloc_set_abort_fn(void (*abort_fn)(const char *reason)); #endif + +/*\}*/ -- cgit From cfce2d3611f225244fadf3d27d76371827fd6422 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 16:52:13 +0100 Subject: Add some initial hook to the front page --- lib/talloc/talloc.h | 3 +++ 1 file changed, 3 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 523a4840d3..d0a9762f4d 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -56,6 +56,9 @@ * 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(). * + * To start, you should probably first look at the definitions of + * ::TALLOC_CTX, talloc_init(), talloc() and talloc_free(). + * * \section named_blocks Named blocks * * Every talloc chunk has a name that can be used as a dynamic type-checking -- cgit From db447d0c476699dbf7fa0567c67f5938674ec811 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 16:58:54 +0100 Subject: Reformatting --- lib/talloc/talloc.h | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index d0a9762f4d..4adc67b7fd 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -99,28 +99,33 @@ * programming. */ -/** \defgroup talloc_ref Talloc References +/** + * \defgroup talloc_ref Talloc References * * This module contains the definitions around talloc references */ -/** \defgroup talloc_array Array routines +/** + * \defgroup talloc_array Array routines * * Talloc contains some handy helpers for handling Arrays conveniently */ -/** \defgroup talloc_string String handling routines +/** + * \defgroup talloc_string String handling routines * * Talloc contains some handy string handling functions */ -/** \defgroup talloc_debug Debugging support routines +/** + * \defgroup talloc_debug Debugging support routines * * To aid memory debugging, talloc contains routines to inspect the currently * allocated memory hierarchy. */ -/** \defgroup todo Default group of undocumented stuff +/** + * \defgroup talloc_undoc Default group of undocumented stuff * * This should be empty... */ -- cgit From 27944ed7452207ef3c686ff6bcd9c4e1cb7f36d8 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 19:48:54 +0100 Subject: Document talloc_pool() --- lib/talloc/talloc.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 4adc67b7fd..e44d924e76 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -628,6 +628,41 @@ typedef void TALLOC_CTX; /* The following definitions come from talloc.c */ void *_talloc(const void *context, size_t size); + +/** + * \brief Allocate a talloc pool + * \param context The talloc context to hang the result off + * \param size Size of the talloc pool + * \result The talloc pool + * \ingroup talloc_basic + * + * A talloc pool is a pure optimization for specific situations. In the + * release process for Samba 3.2 we found out that we had become considerably + * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU + * consumer in benchmarks. For Samba 3.2 we have internally converted many + * static buffers to dynamically allocated ones, so malloc(3) being beaten + * more was no surprise. But it made us slower. + * + * talloc_pool() is an optimization to call malloc(3) a lot less for the use + * pattern Samba has: The SMB protocol is mainly a request/response protocol + * where we have to allocate a certain amount of memory per request and free + * that after the SMB reply is sent to the client. + * + * talloc_pool() creates a talloc chunk that you can use as a talloc parent + * exactly as you would use any other ::TALLOC_CTX. The difference is that + * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc + * just increments a pointer inside the talloc_pool. This also works + * recursively. If you use the child of the talloc pool as a parent for + * grand-children, their memory is also taken from the talloc pool. + * + * If you talloc_free() children of a talloc pool, the memory is not given + * back to the system. Instead, free(3) is only called if the talloc_pool() + * itself is released with talloc_free(). + * + * The downside of a talloc pool is that if you talloc_move() a child of a + * talloc pool to a talloc parent outside the pool, the whole pool memory is + * not free(3)'ed until that moved chunk is also talloc_free()ed. + */ void *talloc_pool(const void *context, size_t size); void _talloc_set_destructor(const void *ptr, int (*destructor)(void *)); -- cgit From 02662d56c64f367bffa2febba9a396c15454cfdb Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 20:02:19 +0100 Subject: Add a talloc_internal "module" --- lib/talloc/talloc.h | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index e44d924e76..f3aa6def63 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -124,6 +124,15 @@ * allocated memory hierarchy. */ +/** + * \defgroup talloc_internal Internal routines + * + * To achieve type-safety, talloc.h defines a lot of macros with type + * casts. These macros define the user interface to the internal routines you + * find here. You should not really use these routines directly but go through + * the external API. + */ + /** * \defgroup talloc_undoc Default group of undocumented stuff * -- cgit From 2ce70d4f5a30973b4cc083dbbb38b519007a31bd Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 20:02:42 +0100 Subject: Document _talloc --- lib/talloc/talloc.h | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index f3aa6def63..01e7326ccc 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -635,7 +635,16 @@ typedef void TALLOC_CTX; #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0) -/* The following definitions come from talloc.c */ +/** + * \brief Allocate untyped, unnamed memory + * \param context 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_internal + * + * Essentially the same as talloc_size() without setting the chunk name to the + * current file/line number. + */ void *_talloc(const void *context, size_t size); /** -- cgit From 3f81649b8dcadb3bd424f41d803dbd59f770b9ba Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 20:02:50 +0100 Subject: Document TALLOC_FREE() --- lib/talloc/talloc.h | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 01e7326ccc..d103d6f4f2 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -633,6 +633,16 @@ typedef void TALLOC_CTX; #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a)) #endif +/** + * \def TALLOC_FREE(ctx) + * \brief talloc_free a chunk and NULL out the pointer + * \param ctx The chunk to be freed + * \ingroup talloc_basic + * + * TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want + * immediate feedback (i.e. crash) if you use a pointer after having free'ed + * it. + */ #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0) /** -- cgit From 986c2e01cca0be993f1e52d3a27819f4044bfe4b Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 23:49:30 +0100 Subject: Document talloc_parent, talloc_parent_name and talloc_is_parent --- lib/talloc/talloc.h | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index d103d6f4f2..9806bdd3ad 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -849,7 +849,25 @@ const char *talloc_get_name(const void *ptr); void *talloc_check_name(const void *ptr, const char *name); void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location); + +/** + * \brief Return the parent chunk of a pointer + * \param ptr The talloc pointer to inspect + * \return The talloc parent of "ptr" + * \ingroup talloc_basic + * + * Return the parent chunk of a pointer + */ void *talloc_parent(const void *ptr); + +/** + * \brief Return a talloc chunk's parent name + * \param ptr The talloc pointer to inspect + * \return The name of ptr's parent chunk + * \ingroup talloc_basic + * + * Return a talloc chunk's parent name + */ const char *talloc_parent_name(const void *ptr); /** @@ -1149,6 +1167,17 @@ size_t talloc_get_size(const void *ctx); */ void *talloc_find_parent_byname(const void *ctx, const char *name); void talloc_show_parents(const void *context, FILE *file); + +/** + * \brief Check if a context is parent of a talloc chunk + * \param context The assumed talloc context + * \param ptr The talloc chunk to check + * \return Is context an anchestor of ptr + * \ingroup talloc_basic + * + * talloc_is_parent() checks if context is referenced in the talloc + * hierarchy above ptr. Return 1 if this is the case, 0 if not. + */ int talloc_is_parent(const void *context, const void *ptr); /** -- cgit From 59dff5745528a3efe585cdeb03e2bedd6b2e404a Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sat, 21 Mar 2009 23:57:14 +0100 Subject: Document talloc_zero_array() --- lib/talloc/talloc.h | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 9806bdd3ad..ae488baf32 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -426,6 +426,22 @@ typedef void TALLOC_CTX; #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__) +/** + * \def talloc_zero_array(ctx, type, count) + * \brief Allocate a 0-initialized 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_zero_array() macro is equivalent to: + * + * \code + * ptr = talloc_array(ctx, type, count); + * if (ptr) memset(ptr, sizeof(type) * count); + * \endcode + */ #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type) /** -- cgit From 257ea7e6f10ab4eda4efae0d6ad0cdc2bd49ffd8 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:47:37 +0100 Subject: Revert "Document talloc_zero_array()" This reverts commit 59dff5745528a3efe585cdeb03e2bedd6b2e404a. --- lib/talloc/talloc.h | 16 ---------------- 1 file changed, 16 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index ae488baf32..9806bdd3ad 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -426,22 +426,6 @@ typedef void TALLOC_CTX; #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__) -/** - * \def talloc_zero_array(ctx, type, count) - * \brief Allocate a 0-initialized 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_zero_array() macro is equivalent to: - * - * \code - * ptr = talloc_array(ctx, type, count); - * if (ptr) memset(ptr, sizeof(type) * count); - * \endcode - */ #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type) /** -- cgit From c086c26ffba72f27530d93ca4a7ad315203f7194 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:47:44 +0100 Subject: Revert "Document talloc_parent, talloc_parent_name and talloc_is_parent" This reverts commit 986c2e01cca0be993f1e52d3a27819f4044bfe4b. --- lib/talloc/talloc.h | 29 ----------------------------- 1 file changed, 29 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 9806bdd3ad..d103d6f4f2 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -849,25 +849,7 @@ const char *talloc_get_name(const void *ptr); void *talloc_check_name(const void *ptr, const char *name); void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location); - -/** - * \brief Return the parent chunk of a pointer - * \param ptr The talloc pointer to inspect - * \return The talloc parent of "ptr" - * \ingroup talloc_basic - * - * Return the parent chunk of a pointer - */ void *talloc_parent(const void *ptr); - -/** - * \brief Return a talloc chunk's parent name - * \param ptr The talloc pointer to inspect - * \return The name of ptr's parent chunk - * \ingroup talloc_basic - * - * Return a talloc chunk's parent name - */ const char *talloc_parent_name(const void *ptr); /** @@ -1167,17 +1149,6 @@ size_t talloc_get_size(const void *ctx); */ void *talloc_find_parent_byname(const void *ctx, const char *name); void talloc_show_parents(const void *context, FILE *file); - -/** - * \brief Check if a context is parent of a talloc chunk - * \param context The assumed talloc context - * \param ptr The talloc chunk to check - * \return Is context an anchestor of ptr - * \ingroup talloc_basic - * - * talloc_is_parent() checks if context is referenced in the talloc - * hierarchy above ptr. Return 1 if this is the case, 0 if not. - */ int talloc_is_parent(const void *context, const void *ptr); /** -- cgit From f15a0305f3982a9bc54aac0690e25a52f1021bb2 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:47:51 +0100 Subject: Revert "Document TALLOC_FREE()" This reverts commit 3f81649b8dcadb3bd424f41d803dbd59f770b9ba. --- lib/talloc/talloc.h | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index d103d6f4f2..01e7326ccc 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -633,16 +633,6 @@ typedef void TALLOC_CTX; #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a)) #endif -/** - * \def TALLOC_FREE(ctx) - * \brief talloc_free a chunk and NULL out the pointer - * \param ctx The chunk to be freed - * \ingroup talloc_basic - * - * TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want - * immediate feedback (i.e. crash) if you use a pointer after having free'ed - * it. - */ #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0) /** -- cgit From cce595d1fcaa84d09ae9e261b5e20da03ca38137 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:47:59 +0100 Subject: Revert "Document _talloc" This reverts commit 2ce70d4f5a30973b4cc083dbbb38b519007a31bd. --- lib/talloc/talloc.h | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 01e7326ccc..f3aa6def63 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -635,16 +635,7 @@ typedef void TALLOC_CTX; #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0) -/** - * \brief Allocate untyped, unnamed memory - * \param context 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_internal - * - * Essentially the same as talloc_size() without setting the chunk name to the - * current file/line number. - */ +/* The following definitions come from talloc.c */ void *_talloc(const void *context, size_t size); /** -- cgit From 6b1a5bbf02dfdb847a5481d1b4b37deb0e0f09a5 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:06 +0100 Subject: Revert "Add a talloc_internal "module"" This reverts commit 02662d56c64f367bffa2febba9a396c15454cfdb. --- lib/talloc/talloc.h | 9 --------- 1 file changed, 9 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index f3aa6def63..e44d924e76 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -124,15 +124,6 @@ * allocated memory hierarchy. */ -/** - * \defgroup talloc_internal Internal routines - * - * To achieve type-safety, talloc.h defines a lot of macros with type - * casts. These macros define the user interface to the internal routines you - * find here. You should not really use these routines directly but go through - * the external API. - */ - /** * \defgroup talloc_undoc Default group of undocumented stuff * -- cgit From c67ea37d62692e5e21f76135ecdfa0d369bed0eb Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:14 +0100 Subject: Revert "Document talloc_pool()" This reverts commit 27944ed7452207ef3c686ff6bcd9c4e1cb7f36d8. --- lib/talloc/talloc.h | 35 ----------------------------------- 1 file changed, 35 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index e44d924e76..4adc67b7fd 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -628,41 +628,6 @@ typedef void TALLOC_CTX; /* The following definitions come from talloc.c */ void *_talloc(const void *context, size_t size); - -/** - * \brief Allocate a talloc pool - * \param context The talloc context to hang the result off - * \param size Size of the talloc pool - * \result The talloc pool - * \ingroup talloc_basic - * - * A talloc pool is a pure optimization for specific situations. In the - * release process for Samba 3.2 we found out that we had become considerably - * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU - * consumer in benchmarks. For Samba 3.2 we have internally converted many - * static buffers to dynamically allocated ones, so malloc(3) being beaten - * more was no surprise. But it made us slower. - * - * talloc_pool() is an optimization to call malloc(3) a lot less for the use - * pattern Samba has: The SMB protocol is mainly a request/response protocol - * where we have to allocate a certain amount of memory per request and free - * that after the SMB reply is sent to the client. - * - * talloc_pool() creates a talloc chunk that you can use as a talloc parent - * exactly as you would use any other ::TALLOC_CTX. The difference is that - * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc - * just increments a pointer inside the talloc_pool. This also works - * recursively. If you use the child of the talloc pool as a parent for - * grand-children, their memory is also taken from the talloc pool. - * - * If you talloc_free() children of a talloc pool, the memory is not given - * back to the system. Instead, free(3) is only called if the talloc_pool() - * itself is released with talloc_free(). - * - * The downside of a talloc pool is that if you talloc_move() a child of a - * talloc pool to a talloc parent outside the pool, the whole pool memory is - * not free(3)'ed until that moved chunk is also talloc_free()ed. - */ void *talloc_pool(const void *context, size_t size); void _talloc_set_destructor(const void *ptr, int (*destructor)(void *)); -- cgit From 5098f4625e74eb4b37b6f7fdfa0486df7e1d7cf4 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:19 +0100 Subject: Revert "Reformatting" This reverts commit db447d0c476699dbf7fa0567c67f5938674ec811. --- lib/talloc/talloc.h | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 4adc67b7fd..d0a9762f4d 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -99,33 +99,28 @@ * programming. */ -/** - * \defgroup talloc_ref Talloc References +/** \defgroup talloc_ref Talloc References * * This module contains the definitions around talloc references */ -/** - * \defgroup talloc_array Array routines +/** \defgroup talloc_array Array routines * * Talloc contains some handy helpers for handling Arrays conveniently */ -/** - * \defgroup talloc_string String handling routines +/** \defgroup talloc_string String handling routines * * Talloc contains some handy string handling functions */ -/** - * \defgroup talloc_debug Debugging support routines +/** \defgroup talloc_debug Debugging support routines * * To aid memory debugging, talloc contains routines to inspect the currently * allocated memory hierarchy. */ -/** - * \defgroup talloc_undoc Default group of undocumented stuff +/** \defgroup todo Default group of undocumented stuff * * This should be empty... */ -- cgit From 790326cc38a9453aea3ad7e5a3f7384bfdd58e84 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:27 +0100 Subject: Revert "Add some initial hook to the front page" This reverts commit cfce2d3611f225244fadf3d27d76371827fd6422. --- lib/talloc/talloc.h | 3 --- 1 file changed, 3 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index d0a9762f4d..523a4840d3 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -56,9 +56,6 @@ * 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(). * - * To start, you should probably first look at the definitions of - * ::TALLOC_CTX, talloc_init(), talloc() and talloc_free(). - * * \section named_blocks Named blocks * * Every talloc chunk has a name that can be used as a dynamic type-checking -- cgit From b7fb083dd775c625882163f140e7e5ca550ebec7 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:34 +0100 Subject: Revert "Add a default "undocumented" module" This reverts commit ba42320c7e9f5ccbd32eccbfb1f2d77e13b3a318. --- lib/talloc/talloc.h | 9 --------- 1 file changed, 9 deletions(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 523a4840d3..4b50ba99c2 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -117,13 +117,6 @@ * allocated memory hierarchy. */ -/** \defgroup todo Default group of undocumented stuff - * - * This should be empty... - */ - -/*\{*/ - /** * \typedef TALLOC_CTX * \brief Define a talloc parent type @@ -1217,5 +1210,3 @@ char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIB void talloc_set_abort_fn(void (*abort_fn)(const char *reason)); #endif - -/*\}*/ -- cgit From c3df04069940ab29f52763dc56f2ded98a4a72a6 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:41 +0100 Subject: Revert "Delete talloc_guide.txt" This reverts commit 3f9c30022a53a37ad829f8882a9a5161fcadda8b. --- lib/talloc/talloc_guide.txt | 694 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 694 insertions(+) create mode 100644 lib/talloc/talloc_guide.txt (limited to 'lib') diff --git a/lib/talloc/talloc_guide.txt b/lib/talloc/talloc_guide.txt new file mode 100644 index 0000000000..3201fe6f0f --- /dev/null +++ b/lib/talloc/talloc_guide.txt @@ -0,0 +1,694 @@ +Using talloc in Samba4 +====================== + +.. contents:: + +Andrew Tridgell +September 2004 + +The most current version of this document is available at + http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt + +If you are used to the "old" talloc from Samba3 before 3.0.20 then please read +this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the +Samba4 talloc has been ported back to Samba3, so this guide applies to both. + +The new 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 change from Samba3 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:: + + struct foo *X = talloc(mem_ctx, struct foo); + X->name = talloc_strdup(X, "foo"); + +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(). + +If you find this confusing, then I suggest you run the testsuite to +watch talloc in action. You may also like to add your own tests to +testsuite.c to clarify how some particular situation is handled. + + +Performance +----------- + +All the additional features of talloc() over malloc() do come at a +price. We have a simple performance test in Samba4 that measures +talloc() versus malloc() performance, and it seems that talloc() is +about 4% slower than malloc() on my x86 Debian Linux box. For Samba, +the great reduction in code complexity that we get by using talloc +makes this worthwhile, especially as the total overhead of +talloc/malloc in Samba is already quite small. + + +talloc API +---------- + +The following is a complete guide to the talloc API. Read it all at +least twice. + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(type *)talloc(const void *context, type); + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_size(const void *context, size_t size); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +int talloc_free(void *ptr); + +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_children(void *ptr); + +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_reference(const void *context, const void *ptr); + +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() + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +int talloc_unlink(const void *context, const void *ptr); + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_set_destructor(const void *ptr, int (*destructor)(void *)); + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +int talloc_increase_ref_count(const void *ptr); + +The talloc_increase_ref_count(ptr) function is exactly equivalent to: + + talloc_reference(NULL, ptr); + +You can use either syntax, depending on which you think is clearer in +your code. + +It returns 0 on success and -1 on failure. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +size_t talloc_reference_count(const void *ptr); + +Return the number of references to the pointer. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_set_name(const void *ptr, const char *fmt, ...); + +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: + talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...)); + +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(). + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_set_name_const(const void *ptr, const char *name); + +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_named(const void *context, size_t size, const char *fmt, ...); + +The talloc_named() function creates a named talloc pointer. It is +equivalent to: + + ptr = talloc_size(context, size); + talloc_set_name(ptr, fmt, ....); + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_named_const(const void *context, size_t size, const char *name); + +This is equivalent to:: + + ptr = talloc_size(context, size); + talloc_set_name_const(ptr, name); + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +const char *talloc_get_name(const void *ptr); + +This returns the current name for the given talloc pointer. See +talloc_set_name() for details. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_init(const char *fmt, ...); + +This function creates a zero length named talloc context as a top +level context. It is equivalent to:: + + talloc_named(NULL, 0, fmt, ...); + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_new(void *ctx); + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(type *)talloc_realloc(const void *context, void *ptr, type, count); + +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:: + + 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); + +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()). + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_realloc_size(const void *context, void *ptr, size_t size); + +the talloc_realloc_size() function is useful when the type is not +known so the typesafe talloc_realloc() cannot be used. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_steal(const void *new_ctx, const void *ptr); + +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. + +talloc_steal (new_ctx, NULL) will return NULL with no sideeffects. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +size_t talloc_total_size(const void *ptr); + +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_blocks(const void *ptr); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +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 *priv), + void *priv); + +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_file(const void *ptr, int depth, int max_depth, FILE *f); + +This provides a more flexible reports than talloc_report(). It +will let you specify the depth and max_depth. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_report(const void *ptr, FILE *f); + +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_full(const void *ptr, FILE *f); + +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_enable_leak_report(void); + +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: + +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 + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_enable_leak_report_full(void); + +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: + +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) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void talloc_enable_null_tracking(void); + +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_disable_null_tracking(void); + +This disables tracking of the NULL memory context. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(type *)talloc_zero(const void *ctx, type); + +The talloc_zero() macro is equivalent to:: + + ptr = talloc(ctx, type); + if (ptr) memset(ptr, 0, sizeof(type)); + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_zero_size(const void *ctx, size_t size) + +The talloc_zero_size() function is useful when you don't have a known type + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_memdup(const void *ctx, const void *p, size_t size); + +The talloc_memdup() function is equivalent to:: + + ptr = talloc_size(ctx, size); + if (ptr) memcpy(ptr, p, size); + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_strdup(const void *ctx, const char *p); + +The talloc_strdup() function is equivalent to:: + + ptr = talloc_size(ctx, strlen(p)+1); + if (ptr) memcpy(ptr, p, strlen(p)+1); + +This functions sets the name of the new pointer to the passed +string. This is equivalent to:: + + talloc_set_name_const(ptr, ptr) + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_strndup(const void *t, const char *p, size_t n); + +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: + talloc_set_name_const(ptr, ptr) + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_append_string(const void *t, char *orig, const char *append); + +The talloc_append_string() function appends the given formatted +string to the given string. + +This function sets the name of the new pointer to the new +string. This is equivalent to:: + + talloc_set_name_const(ptr, ptr) + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_vasprintf(const void *t, const char *fmt, va_list ap); + +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:: + + talloc_set_name_const(ptr, ptr) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_asprintf(const void *t, const char *fmt, ...); + +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:: + + talloc_set_name_const(ptr, ptr) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_asprintf_append(char *s, const char *fmt, ...); + +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:: + + talloc_set_name_const(ptr, ptr) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...); + +The talloc_asprintf_append() function appends the given formatted +string to the end of the currently allocated talloc buffer. +Use this varient when the string in the current talloc buffer has +not been changed. + +This functions sets the name of the new pointer to the new +string. This is equivalent to:: + + talloc_set_name_const(ptr, ptr) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +((type *)talloc_array(const void *ctx, type, uint_t count); + +The talloc_array() macro is equivalent to:: + + (type *)talloc_size(ctx, sizeof(type) * count); + +except that it provides integer overflow protection for the multiply, +returning NULL if the multiply overflows. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_array_size(const void *ctx, size_t size, uint_t count); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count); + +The talloc_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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size); + +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_autofree_context(void); + +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_check_name(const void *ptr, const char *name); + +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. + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(type *)talloc_get_type(const void *ptr, type); + +This macro allows you to do type checking on talloc pointers. It is +particularly useful for void* private pointers. It is equivalent to +this:: + + (type *)talloc_check_name(ptr, #type) + + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +talloc_set_type(const void *ptr, type); + +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:: + + talloc_set_name_const(ptr, #type) + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +talloc_get_size(const void *ctx); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +void *talloc_find_parent_byname(const void *ctx, const char *name); + +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. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +(type *)talloc_find_parent_bytype(ctx, type); + +Like talloc_find_parent_byname() but takes a type, making it typesafe. + -- cgit From a83c18062ae04942ceff757534ba251b045ad04c Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:48 +0100 Subject: Revert "Convert the contents of talloc_guide.txt to doxygen-style talloc.h comments" This reverts commit d21212c9192b41a3fdc7e96cb9bf0125a1dc6c2d. --- lib/talloc/talloc.h | 1024 +-------------------------------------------------- 1 file changed, 1 insertion(+), 1023 deletions(-) (limited to 'lib') 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 #include -/** \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)); -- cgit From f590915fe5b0deb9e99ab5b2c13c587eadf194f6 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 09:48:54 +0100 Subject: Revert "Add a basic Doxyfile for talloc" This reverts commit f55e84e904173bed8dc9099ad523ca1e7be12355. --- lib/talloc/Doxyfile | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 lib/talloc/Doxyfile (limited to 'lib') diff --git a/lib/talloc/Doxyfile b/lib/talloc/Doxyfile deleted file mode 100644 index 0ccf563d75..0000000000 --- a/lib/talloc/Doxyfile +++ /dev/null @@ -1,8 +0,0 @@ -OUTPUT_DIRECTORY = doc -PROJECT_NAME = Talloc -OPTIMIZE_OUTPUT_FOR_C = YES -GENERATE_LATEX = NO -GENERATE_MAN = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -PREDEFINED = PRINTF_ATTRIBUTE(x,y)= -- cgit From 1f72e4abfdc85fbe624ec7910b68868d97f88ff2 Mon Sep 17 00:00:00 2001 From: Stefan Metzmacher Date: Sun, 22 Mar 2009 12:36:38 +0100 Subject: Revert "socket_wrapper: fix connect() for dgram sockets, if the destination isn't there yet" This reverts commit 66dc53ee017d74a6f610bbe04337f064901fe2a1. Somehow this leads to timeouts in some tests, samba4.ldb.ldapi and samba4.rpc.schannel. I need to look at it more closely later... metze --- lib/socket_wrapper/socket_wrapper.c | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) (limited to 'lib') diff --git a/lib/socket_wrapper/socket_wrapper.c b/lib/socket_wrapper/socket_wrapper.c index 1d35c8d20c..44082e78a1 100644 --- a/lib/socket_wrapper/socket_wrapper.c +++ b/lib/socket_wrapper/socket_wrapper.c @@ -1686,14 +1686,10 @@ _PUBLIC_ int swrap_connect(int s, const struct sockaddr *serv_addr, socklen_t ad ret = sockaddr_convert_to_un(si, (const struct sockaddr *)serv_addr, addrlen, &un_addr, 0, NULL); if (ret == -1) return -1; - if (si->type == SOCK_DGRAM) { - ret = 0; - } else { - swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); + swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); - ret = real_connect(s, (struct sockaddr *)&un_addr, - sizeof(struct sockaddr_un)); - } + ret = real_connect(s, (struct sockaddr *)&un_addr, + sizeof(struct sockaddr_un)); /* to give better errors */ if (ret == -1 && errno == ENOENT) { -- cgit From 979a1b06d01817a01967d9137e4f70f222fa8eab Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 22 Mar 2009 22:07:58 +0100 Subject: talloc_array_length: talloc_get_size deals fine with NULL --- lib/talloc/talloc.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 5c8d5c5fe2..f87564a13b 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -94,7 +94,7 @@ typedef void TALLOC_CTX; #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type) #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__) #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count) -#define talloc_array_length(ctx) ((ctx) ? talloc_get_size(ctx)/sizeof(*ctx) : 0) +#define talloc_array_length(ctx) (talloc_get_size(ctx)/sizeof(*ctx)) #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type) #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__) -- cgit From 435a0a5a3bc8114991650a78e1f90049d2f3f343 Mon Sep 17 00:00:00 2001 From: Stefan Metzmacher Date: Mon, 23 Mar 2009 09:16:18 +0100 Subject: socket_wrapper: fix connect() for dgram sockets, if the destination isn't there yet Now we defer the real_connect() for dgram sockets to the first send()/sendto() call, as the destination might not be there at connect time. Commit 66dc53ee017d74a6f610bbe04337f064901fe2a1 was an incomplete fix for this problem. metze --- lib/socket_wrapper/socket_wrapper.c | 56 ++++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 4 deletions(-) (limited to 'lib') diff --git a/lib/socket_wrapper/socket_wrapper.c b/lib/socket_wrapper/socket_wrapper.c index 44082e78a1..553827b192 100644 --- a/lib/socket_wrapper/socket_wrapper.c +++ b/lib/socket_wrapper/socket_wrapper.c @@ -218,6 +218,7 @@ struct socket_info int bcast; int is_server; int connected; + int defer_connect; char *path; char *tmp_path; @@ -1686,10 +1687,15 @@ _PUBLIC_ int swrap_connect(int s, const struct sockaddr *serv_addr, socklen_t ad ret = sockaddr_convert_to_un(si, (const struct sockaddr *)serv_addr, addrlen, &un_addr, 0, NULL); if (ret == -1) return -1; - swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); + if (si->type == SOCK_DGRAM) { + si->defer_connect = 1; + ret = 0; + } else { + swrap_dump_packet(si, serv_addr, SWRAP_CONNECT_SEND, NULL, 0); - ret = real_connect(s, (struct sockaddr *)&un_addr, - sizeof(struct sockaddr_un)); + ret = real_connect(s, (struct sockaddr *)&un_addr, + sizeof(struct sockaddr_un)); + } /* to give better errors */ if (ret == -1 && errno == ENOENT) { @@ -1917,7 +1923,22 @@ _PUBLIC_ ssize_t swrap_sendto(int s, const void *buf, size_t len, int flags, con return len; } - + + if (si->defer_connect) { + ret = real_connect(s, (struct sockaddr *)&un_addr, + sizeof(un_addr)); + + /* to give better errors */ + if (ret == -1 && errno == ENOENT) { + errno = EHOSTUNREACH; + } + + if (ret == -1) { + return ret; + } + si->defer_connect = 0; + } + ret = real_sendto(s, buf, len, flags, (struct sockaddr *)&un_addr, sizeof(un_addr)); break; default: @@ -2002,6 +2023,33 @@ _PUBLIC_ ssize_t swrap_send(int s, const void *buf, size_t len, int flags) len = MIN(len, 1500); + if (si->defer_connect) { + struct sockaddr_un un_addr; + int bcast = 0; + + if (si->bound == 0) { + ret = swrap_auto_bind(si, si->family); + if (ret == -1) return -1; + } + + ret = sockaddr_convert_to_un(si, si->peername, si->peername_len, + &un_addr, 0, &bcast); + if (ret == -1) return -1; + + ret = real_connect(s, (struct sockaddr *)&un_addr, + sizeof(un_addr)); + + /* to give better errors */ + if (ret == -1 && errno == ENOENT) { + errno = EHOSTUNREACH; + } + + if (ret == -1) { + return ret; + } + si->defer_connect = 0; + } + ret = real_send(s, buf, len, flags); if (ret == -1) { -- cgit From 33d9f46674a270a0715213c17581deef192826e1 Mon Sep 17 00:00:00 2001 From: Michael Adam Date: Mon, 23 Mar 2009 17:36:46 +0100 Subject: libreplace: use libreplace_SAVE_CPPFLAGS instead of SAVE_CPPFLAGS This fixes Samba3's double listing of -I options in CFLAGS, since samba3's configure wraps the call to AC_LIBREPLACE_NETWORK_CHECKS into a SAVE_CPPFLAGS="${CPPFLAGS}" .. CPPFLAGS="${SAVE_CPPFLAGS}" sequence... :-) Michael --- lib/replace/libreplace_network.m4 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib') diff --git a/lib/replace/libreplace_network.m4 b/lib/replace/libreplace_network.m4 index 3bac72d136..2af02312ab 100644 --- a/lib/replace/libreplace_network.m4 +++ b/lib/replace/libreplace_network.m4 @@ -170,7 +170,7 @@ fi # The following tests need LIBS="${LIBREPLACE_NETWORK_LIBS}" old_LIBS=$LIBS LIBS="${LIBREPLACE_NETWORK_LIBS}" -SAVE_CPPFLAGS="$CPPFLAGS" +libreplace_SAVE_CPPFLAGS="$CPPFLAGS" CPPFLAGS="$CPPFLAGS -I$libreplacedir" AC_CHECK_FUNCS(socketpair,[],[LIBREPLACE_NETWORK_OBJS="${LIBREPLACE_NETWORK_OBJS} socketpair.o"]) @@ -381,7 +381,7 @@ if test x"$libreplace_cv_HAVE_IPV6" = x"yes"; then fi LIBS=$old_LIBS -CPPFLAGS="$SAVE_CPPFLAGS" +CPPFLAGS="$libreplace_SAVE_CPPFLAGS" LIBREPLACEOBJ="${LIBREPLACEOBJ} ${LIBREPLACE_NETWORK_OBJS}" -- cgit From 6a2e71b12dbfed195859f0fc521ec5a5c145e1f5 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 1 Mar 2009 22:25:51 +0100 Subject: Add tevent_req_simple_recv_ntstatus() --- lib/util/tevent_ntstatus.c | 10 ++++++++++ lib/util/tevent_ntstatus.h | 1 + 2 files changed, 11 insertions(+) (limited to 'lib') diff --git a/lib/util/tevent_ntstatus.c b/lib/util/tevent_ntstatus.c index 1a34e9c749..4e4339989a 100644 --- a/lib/util/tevent_ntstatus.c +++ b/lib/util/tevent_ntstatus.c @@ -49,3 +49,13 @@ bool tevent_req_is_nterror(struct tevent_req *req, NTSTATUS *status) } return true; } + +NTSTATUS tevent_req_simple_recv_ntstatus(struct tevent_req *req) +{ + NTSTATUS status; + + if (tevent_req_is_nterror(req, &status)) { + return status; + } + return NT_STATUS_OK; +} diff --git a/lib/util/tevent_ntstatus.h b/lib/util/tevent_ntstatus.h index 84c275fb13..d7194a9b73 100644 --- a/lib/util/tevent_ntstatus.h +++ b/lib/util/tevent_ntstatus.h @@ -28,5 +28,6 @@ bool tevent_req_nterror(struct tevent_req *req, NTSTATUS status); bool tevent_req_is_nterror(struct tevent_req *req, NTSTATUS *pstatus); +NTSTATUS tevent_req_simple_recv_ntstatus(struct tevent_req *req); #endif -- cgit