Using talloc in Samba4
-----------------------
+======================
+
+.. contents::
Andrew Tridgell
-September 2004
+August 2009
The most current version of this document is available at
- http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt
+ http://samba.org/ftp/unpacked/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
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:
+you can do this::
struct foo *X = talloc(mem_ctx, struct foo);
X->name = talloc_strdup(X, "foo");
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.
+returned for success and -1 for failure. A 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. Likewise, if "ptr" is NULL, then the function will make
+no modifications and returns -1.
If this pointer has an additional parent when talloc_free() is called
then the memory is not actually released, but instead the most
talloc_free() operates recursively on its children.
+From the 2.0 version of talloc, as a special case, talloc_free() is
+refused on pointers that have more than one parent, as talloc would
+have no way of knowing which parent should be removed. To free a
+pointer that has more than one parent please use talloc_unlink().
+
+To help you find problems in your code caused by this behaviour, if
+you do try and free a pointer with more than one parent then the
+talloc logging function will be called to give output like this:
+
+ ERROR: talloc_free with references at some_dir/source/foo.c:123
+ reference at some_dir/source/other.c:325
+ reference at some_dir/source/third.c:121
+
+Please see the documentation for talloc_set_log_fn() and
+talloc_set_log_stderr() for more information on talloc logging
+functions.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
int talloc_free_children(void *ptr);
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void *talloc_named_const(const void *context, size_t size, const char *name);
-This is equivalent to:
+This is equivalent to::
ptr = talloc_size(context, size);
talloc_set_name_const(ptr, name);
void *talloc_init(const char *fmt, ...);
This function creates a zero length named talloc context as a top
-level context. It is equivalent to:
+level context. It is equivalent to::
talloc_named(NULL, 0, fmt, ...);
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() 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_steal (new_ctx, NULL) will return NULL with no sideeffects.
+Note that if you try and call talloc_steal() on a pointer that has
+more than one parent then the result is ambiguous. Talloc will choose
+to remove the parent that is currently indicated by talloc_parent()
+and replace it with the chosen parent. You will also get a message
+like this via the talloc logging functions:
+
+ WARNING: talloc_steal with references at some_dir/source/foo.c:123
+ reference at some_dir/source/other.c:325
+ reference at some_dir/source/third.c:121
+
+To unambiguously change the parent of a pointer please see the
+function talloc_reparent(). See the talloc_set_log_fn() documentation
+for more information on talloc logging.
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
+
+The talloc_reparent() 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_reparent() function returns the pointer that you pass it. It
+does not have any failure modes.
+
+The difference between talloc_reparent() and talloc_steal() is that
+talloc_reparent() can specify which parent you wish to change. This is
+useful when a pointer has multiple parents via references.
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void *talloc_parent(const void *ptr);
+
+The talloc_parent() function returns the current talloc parent. This
+is usually the pointer under which this memory was originally created,
+but it may have changed due to a talloc_steal() or talloc_reparent()
+
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
size_t talloc_total_size(const void *ptr);
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
(type *)talloc_zero(const void *ctx, type);
-The talloc_zero() macro is equivalent to:
+The talloc_zero() macro is equivalent to::
ptr = talloc(ctx, type);
if (ptr) memset(ptr, 0, sizeof(type));
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void *talloc_memdup(const void *ctx, const void *p, size_t size);
-The talloc_memdup() function is equivalent to:
+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:
+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:
+string. This is equivalent to::
+
talloc_set_name_const(ptr, ptr)
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
string to the given string.
This function sets the name of the new pointer to the new
-string. This is equivalent to:
+string. This is equivalent to::
+
talloc_set_name_const(ptr, ptr)
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
library function vasprintf()
This functions sets the name of the new pointer to the new
-string. This is equivalent to:
+string. This is equivalent to::
+
talloc_set_name_const(ptr, ptr)
library function asprintf()
This functions sets the name of the new pointer to the new
-string. This is equivalent to:
+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 given string.
+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:
+string. This is equivalent to::
+
talloc_set_name_const(ptr, ptr)
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-(type *)talloc_array(const void *ctx, type, uint_t count);
+((type *)talloc_array(const void *ctx, type, unsigned int count);
-The talloc_array() macro is equivalent to:
+The talloc_array() macro is equivalent to::
(type *)talloc_size(ctx, sizeof(type) * count);
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-void *talloc_array_size(const void *ctx, size_t size, uint_t count);
+void *talloc_array_size(const void *ctx, size_t size, unsigned int 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);
+(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int 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
This macro allows you to do type checking on talloc pointers. It is
particularly useful for void* private pointers. It is equivalent to
-this:
+this::
(type *)talloc_check_name(ptr, #type)
particular type. This can be used in conjunction with
talloc_get_type() to do type checking on void* pointers.
-It is equivalent to this:
+It is equivalent to this::
+
talloc_set_name_const(ptr, #type)
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Like talloc_find_parent_byname() but takes a type, making it typesafe.
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void talloc_set_log_fn(void (*log_fn)(const char *message));
+
+This function sets a logging function that talloc will use for
+warnings and errors. By default talloc will not print any warnings or
+errors.
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void talloc_set_log_stderr(void)
+
+This sets the talloc log function to write log messages to stderr
git.samba.org / metze / ctdb / wip.git / blobdiff