Skip to content

C
ccan
Commit 4cdcc648 authored by Rusty Russell's avatar Rusty Russell
Browse files
Options

Move documentation from talloc_guide.txt into talloc.h and remove some 

cruft.
parent ff03158c
Show whitespace changes
Inline Side-by-side
Showing with 843 additions and 62 deletions
talloc/talloc.c
View file @ 4cdcc648
......@@ -1102,7 +1102,7 @@ char *talloc_strdup(const void *t, const char *p)
/*
append to a talloced string
*/
char *talloc_append_string(const void *t, char *orig, const char *append)
char *talloc_append_string(char *orig, const char *append)
{
char *ret;
size_t olen = strlen(orig);
......@@ -1113,7 +1113,7 @@ char *talloc_append_string(const void *t, char *orig, const char *append)
alenz = strlen(append) + 1;
ret = talloc_realloc(t, orig, char, olen + alenz);
ret = talloc_realloc(NULL, orig, char, olen + alenz);
if (!ret)
return NULL;
......
talloc/talloc.h
View file @ 4cdcc648
#ifndef _TALLOC_H_
#define _TALLOC_H_
#ifndef CCAN_TALLOC_H
#define CCAN_TALLOC_H
/*
Unix SMB/CIFS implementation.
Samba temporary memory allocation functions
......@@ -31,9 +31,6 @@
#include <stdarg.h>
#include "config.h"
/* this is only needed for compatibility with the old talloc */
typedef void TALLOC_CTX;
/*
this uses a little trick to allow __LINE__ to be stringified
*/
......@@ -44,12 +41,7 @@ typedef void TALLOC_CTX;
#define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
#endif
#ifndef TALLOC_DEPRECATED
#define TALLOC_DEPRECATED 0
#endif
#ifndef PRINTF_ATTRIBUTE
#if (__GNUC__ >= 3)
#if HAVE_ATTRIBUTE_PRINTF
/** Use gcc attribute to check printf fns. a1 is the 1-based index of
* the parameter containing the format, and a2 the index of the first
* argument. Note that some gcc 2.x versions don't handle this
......@@ -58,117 +50,906 @@ typedef void TALLOC_CTX;
#else
#define PRINTF_ATTRIBUTE(a1, a2)
#endif
#endif
/* try to make talloc_set_destructor() and talloc_steal() type safe,
if we have a recent gcc */
#if (__GNUC__ >= 3)
#if HAVE_TYPEOF
#define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
#else
#define _TALLOC_TYPEOF(ptr) void *
#endif
#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
/**
* talloc - allocate dynamic memory for a type
* @ctx: context to be parent of this allocation, or NULL.
* @type: the type to be allocated.
*
* 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 @ctx. This means that if you
* talloc_free() @ctx then the new child disappears as well. Alternatively you
* can free just the child.
*
* @ctx can be NULL, in which case a new top level context is created.
*
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
*
* See Also:
* talloc_zero, talloc_array, talloc_steal, talloc_free.
*/
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
/**
* talloc_free - free talloc'ed memory and its children
* @ptr: the talloced pointer to free
*
* 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.
*
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* // Frees a and b
* talloc_free(a);
*
* See Also:
* talloc_set_destructor, talloc_unlink
*/
int talloc_free(void *ptr);
/**
* talloc_set_destructor: set a destructor for when this pointer is freed
* @ptr: the talloc pointer to set the destructor on
* @destructor: the function to be called
*
* 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.
*
* Example:
* static int destroy_fd(int *fd)
* {
* close(*fd);
* return 0;
* }
*
* int *open_file(const char *filename)
* {
* int *fd = talloc(NULL, int);
* *fd = open(filename, O_RDONLY);
* if (*fd < 0) {
* talloc_free(fd);
* return NULL;
* }
* // Whenever they free this, we close the file.
* talloc_set_destructor(fd, destroy_fd);
* return fd;
* }
*
* See Also:
* talloc, talloc_free
*/
#define talloc_set_destructor(ptr, function) \
do { \
int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function); \
_talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
} while(0)
/* this extremely strange macro is to avoid some braindamaged warning
stupidity in gcc 4.1.x */
#define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); __talloc_steal_ret; })
/**
* talloc_zero - allocate zeroed dynamic memory for a type
* @ctx: context to be parent of this allocation, or NULL.
* @type: the type to be allocated.
*
* The talloc_zero() macro is equivalent to:
*
* ptr = talloc(ctx, type);
* if (ptr) memset(ptr, 0, sizeof(type));
*
* Example:
* unsigned int *a, *b;
* a = talloc_zero(NULL, unsigned int);
* b = talloc_zero(a, unsigned int);
*
* See Also:
* talloc, talloc_zero_size, talloc_zero_array
*/
#define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
/**
* talloc_array - allocate dynamic memory for an array of a given type
* @ctx: context to be parent of this allocation, or NULL.
* @type: the type to be allocated.
* @count: the number of elements to be allocated.
*
* The talloc_array() macro is a safe way of allocating an array. It 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.
*
* Example:
* unsigned int *a, *b;
* a = talloc_zero(NULL, unsigned int);
* b = talloc_array(a, unsigned int, 100);
*
* See Also:
* talloc, talloc_zero_array
*/
#define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
/**
* talloc_size - allocate a particular size of memory
* @ctx: context to be parent of this allocation, or NULL.
* @size: the number of bytes to allocate
*
* 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.
*
* Best to use talloc() or talloc_array() instead.
*
* Example:
* void *mem = talloc_size(NULL, 100);
*
* See Also:
* talloc, talloc_array, talloc_zero_size
*/
#define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
#ifdef HAVE_TYPEOF
/**
* talloc_steal - change/set the parent context of a talloc pointer
* @ctx: the new parent
* @ptr: the talloc pointer to reparent
*
* 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.
*
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(NULL, unsigned int);
* // Reparent b to a as if we'd done 'b = talloc(a, unsigned int)'.
* talloc_steal(a, b);
*
* See Also:
* talloc_reference
*/
#define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) _talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); _talloc_steal_ret; }) /* this extremely strange macro is to avoid some braindamaged warning stupidity in gcc 4.1.x */
#else
#define talloc_set_destructor(ptr, function) \
_talloc_set_destructor((ptr), (int (*)(void *))(function))
#define _TALLOC_TYPEOF(ptr) void *
#define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
#endif
#endif /* HAVE_TYPEOF */
/**
* talloc_report_full - report all the memory used by a pointer and children.
* @ptr: the context to report on
* @f: the file to report to
*
* Recursively print the entire 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_null_tracking() has been
* called.
*
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* fprintf(stderr, "Dumping memory tree for a:\n");
* talloc_report_full(a, stderr);
*
* See Also:
* talloc_report
*/
void talloc_report_full(const void *ptr, FILE *f);
/**
* talloc_reference - add an additional parent to a context
* @ctx: the additional parent
* @ptr: the talloc pointer
*
* The talloc_reference() function makes @ctx 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().
* Example:
* unsigned int *a, *b, *c;
* a = talloc(NULL, unsigned int);
* b = talloc(NULL, unsigned int);
* c = talloc(a, unsigned int);
* // b also serves as a parent of c.
* talloc_reference(b, c);
*/
#define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
/* useful macros for creating type checked pointers */
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
#define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
/**
* talloc_unlink: remove a specific parent from a talloc pointer.
* @context: the parent to remove
* @ptr: the talloc pointer
*
* 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.
* Example:
* unsigned int *a, *b, *c;
* a = talloc(NULL, unsigned int);
* b = talloc(NULL, unsigned int);
* c = talloc(a, unsigned int);
* // b also serves as a parent of c.
* talloc_reference(b, c);
* talloc_unlink(b, c);
*/
int talloc_unlink(const void *context, void *ptr);
/**
* talloc_report - print a summary of memory used by a pointer
*
* 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_null_tracking() has been
* called.
*
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* fprintf(stderr, "Summary of memory tree for a:\n");
* talloc_report(a, stderr);
*
* See Also:
* talloc_report_full
*/
void talloc_report(const void *ptr, FILE *f);
/**
* talloc_ptrtype - allocate a size of memory suitable for this pointer
* @ctx: context to be parent of this allocation, or NULL.
* @ptr: the pointer whose type we are to allocate
*
* 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.
*
* Example:
* unsigned int *a = talloc_ptrtype(NULL, a);
*/
#define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
/**
* talloc_free_children - free talloc'ed memory's children only
* @ptr: the talloced pointer whose children we want to free
*
* talloc_free_children() walks along the list of all children of a talloc
* context @ptr and talloc_free()s only the children, not the context itself.
* Example:
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* // Frees b
* talloc_free_children(a);
*/
void talloc_free_children(void *ptr);
/**
* talloc_new - create a new context
* @ctx: the context to use as a parent.
*
* 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__)
#define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
/**
* talloc_zero_size - allocate a particular size of zeroed memory
*
* The talloc_zero_size() function is useful when you don't have a known type.
*/
#define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
/**
* talloc_zero_array - allocate an array of zeroed types
* @ctx: context to be parent of this allocation, or NULL.
* @type: the type to be allocated.
* @count: the number of elements to be allocated.
*
* Just like talloc_array, but zeroes the memory.
*/
#define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
#define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
/**
* talloc_zero_array - allocate an array of zeroed types
* @ctx: context to be parent of this allocation, or NULL.
* @type: the type to be allocated.
* @count: the number of elements to be allocated.
*
* Just like talloc_array, but zeroes the memory.
*/
#define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
/**
* talloc_array_ptrtype - allocate an array of memory suitable for this pointer
* @ctx: context to be parent of this allocation, or NULL.
* @ptr: the pointer whose type we are to allocate
* @count: the number of elements for the array
*
* Like talloc_ptrtype(), except it allocates an array.
*/
#define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
/**
* talloc_realloc - resize a talloc array
* @ctx: the parent to assign (if p is NULL)
* @p: the memory to reallocate
* @type: the type of the object to allocate
* @count: the number of objects to reallocate
*
* 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()).
*/
#define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
/**
* talloc_realloc_size - resize talloc memory
* @ctx: the parent to assign (if p is NULL)
* @ptr: the memory to reallocate
* @size: the new size of memory.
*
* 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__)
/**
* talloc_strdup - duplicate a string
* @ctx: the talloc context for the new string
* @p: the string to copy
*
* 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_strdup(const void *t, const char *p);
/**
* talloc_strndup - duplicate a limited length of a string
* @ctx: the talloc context for the new string
* @p: the string to copy
* @n: the maximum length of the returned string.
*
* The talloc_strndup() function is the talloc equivalent of the C library
* function strndup(): the result will be truncated to @n characters before
* the nul terminator.
*
* 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);
/**
* talloc_memdup - duplicate some talloc memory
*
* The talloc_memdup() function is equivalent to:
*
* ptr = talloc_size(ctx, size);
* if (ptr) memcpy(ptr, p, size);
*/
#define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
/**
* talloc_asprintf - sprintf into a talloc buffer.
* @t: The context to allocate the buffer from
* @fmt: printf-style format for the buffer.
*
* 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(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
/**
* talloc_append_string - concatenate onto a tallocated string
* @orig: the tallocated string to append to
* @append: the string to add, or NULL to add nothing.
*
* 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_append_string(char *orig, const char *append);
/**
* talloc_asprintf_append - sprintf onto the end of a talloc buffer.
* @s: The tallocated string buffer
* @fmt: printf-style format to append to the buffer.
*
* The talloc_asprintf_append() function appends the given formatted string to
* the given string.
*
* 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, ...) PRINTF_ATTRIBUTE(2,3);
/**
* talloc_vasprintf - vsprintf into a talloc buffer.
* @t: The context to allocate the buffer from
* @fmt: printf-style format for the buffer
* @ap: va_list arguments
*
* 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_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
/**
* talloc_vasprintf_append - sprintf onto the end of a talloc buffer.
* @t: The context to allocate the buffer from
* @fmt: printf-style format for the buffer
* @ap: va_list arguments
*
* The talloc_vasprintf_append() function is equivalent to
* talloc_asprintf_append(), except it takes a va_list.
*/
char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
/**
* talloc_set_type - force the name of a pointer to a particular type
* @ptr: the talloc pointer
* @type: the type whose name to set the ptr name to.
*
* 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)
*/
#define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
/**
* talloc_get_type - convert a talloced pointer with typechecking
* @ptr: the talloc pointer
* @type: the type which we expect the talloced pointer to be.
*
* 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)
*/
#define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
/**
* talloc_find_parent_byname - find a talloc parent by type
* @ptr: the talloc pointer
* @type: the type we're looking for
*
* 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.
*/
#define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
#if TALLOC_DEPRECATED
#define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
#define talloc_p(ctx, type) talloc(ctx, type)
#define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
#define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
#define talloc_destroy(ctx) talloc_free(ctx)
#endif
/* The following definitions come from talloc.c */
void *_talloc(const void *context, size_t size);
void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
/**
* talloc_increase_ref_count - hold a reference to a talloc pointer
* @ptr: the talloc pointer
*
* 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.
*/
int talloc_increase_ref_count(const void *ptr);
size_t talloc_reference_count(const void *ptr);
void *_talloc_reference(const void *context, const void *ptr);
int talloc_unlink(const void *context, void *ptr);
/**
* talloc_set_name - set the name for a talloc pointer
* @ptr: the talloc pointer
* @fmt: the printf-style format string for the name
*
* 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().
*/
const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
/**
* talloc_set_name_const - set a talloc pointer name to a string constant
* @ptr: the talloc pointer to name
* @name: the strucng constant.
*
* 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().
*
* 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);
/**
* talloc_named - create a specifically-named talloc pointer
* @context: the parent context for the allocation
* @size: the size to allocate
* @fmt: the printf-style format for the name
*
* 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 void *context, size_t size,
const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
/**
* talloc_named_const - create a specifically-named talloc pointer
* @context: the parent context for the allocation
* @size: the size to allocate
* @name: the string constant to use as the name
*
* This is equivalent to:
*
* ptr = talloc_size(context, size);
* talloc_set_name_const(ptr, name);
*/
void *talloc_named_const(const void *context, size_t size, const char *name);
/**
* talloc_get_name - get the name of a talloc pointer
* @ptr: the talloc pointer
*
* This returns the current name for the given talloc pointer. See
* talloc_set_name() for details.
*/
const char *talloc_get_name(const void *ptr);
/**
* talloc_check_name - check if a pointer has the specified name
* @ptr: the talloc pointer
* @name: the name to compare with the pointer's 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.
*/
void *talloc_check_name(const void *ptr, const char *name);
void *talloc_parent(const void *ptr);
const char *talloc_parent_name(const void *ptr);
/**
* talloc_init - create a top-level context of particular name
* @fmt: the printf-style format of the name
*
* 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_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
int talloc_free(void *ptr);
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);
/**
* talloc_total_size - get the bytes used by the pointer and its children
* @ptr: the talloc pointer
*
* 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);
/**
* talloc_total_blocks - get the number of allocations for the pointer
* @ptr: the talloc pointer
*
* The talloc_total_blocks() function returns the total allocations used by
* this pointer and all child pointers. Mostly useful for debugging. For
* example, a pointer with no children will return "1".
*
* 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);
/**
* talloc_report_depth_cb - walk the entire talloc tree under a talloc pointer
* @ptr: the talloc pointer to recurse under
* @depth: the current depth of traversal
* @max_depth: maximum depth to traverse, or -1 for no maximum
* @callback: the function to call on each pointer
* @private_data: pointer to hand to @callback.
*
* 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);
/**
* talloc_report_depth_file - report talloc usage to a maximum depth
* @ptr: the talloc pointer to recurse under
* @depth: the current depth of traversal
* @max_depth: maximum depth to traverse, or -1 for no maximum
* @f: the file to report to
*
* 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);
void talloc_report_full(const void *ptr, FILE *f);
void talloc_report(const void *ptr, FILE *f);
/**
* talloc_enable_null_tracking - enable tracking of top-level tallocs
*
* 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);
/**
* talloc_disable_null_tracking - enable tracking of top-level tallocs
*
* This disables tracking of the NULL memory context.
*/
void talloc_disable_null_tracking(void);
/**
* talloc_enable_leak_report - call talloc_report on program exit
*
* 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(void);
/**
* talloc_enable_leak_report - call talloc_report_full on program exit
*
* 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_leak_report_full(void);
/**
* talloc_autofree_context - a context which will be freed at exit
*
* 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);
/**
* talloc_get_size - get the size of an allocation
* @ctx: the talloc pointer whose allocation to measure.
*
* 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);
/**
* talloc_find_parent_byname - find a parent of this context with this name
* @ctx: the context whose ancestors to search
* @name: the name to look for
*
* Find a parent memory context of @ctx 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);
/* The following definitions come from talloc.c */
void *_talloc(const void *context, size_t size);
void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
size_t talloc_reference_count(const void *ptr);
void *_talloc_reference(const void *context, const void *ptr);
void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
void *talloc_parent(const void *ptr);
const char *talloc_parent_name(const void *ptr);
void *_talloc_steal(const void *new_ctx, const void *ptr);
void *_talloc_move(const void *new_ctx, const void *pptr);
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);
char *talloc_strdup(const void *t, const char *p);
char *talloc_strndup(const void *t, const char *p, size_t n);
char *talloc_append_string(const void *t, char *orig, const char *append);
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_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
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);
void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
void *talloc_autofree_context(void);
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);
int talloc_is_parent(const void *context, const void *ptr);
#endif
#endif /* CCAN_TALLOC_H */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7