|
rpm-build |
95f51c |
Using talloc in Samba4
|
|
rpm-build |
95f51c |
======================
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
.. contents::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Andrew Tridgell
|
|
rpm-build |
95f51c |
August 2009
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The most current version of this document is available at
|
|
rpm-build |
95f51c |
http://samba.org/ftp/unpacked/talloc/talloc_guide.txt
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
|
|
rpm-build |
95f51c |
this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
|
|
rpm-build |
95f51c |
Samba4 talloc has been ported back to Samba3, so this guide applies to both.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The new talloc is a hierarchical, reference counted memory pool system
|
|
rpm-build |
95f51c |
with destructors. Quite a mouthful really, but not too bad once you
|
|
rpm-build |
95f51c |
get used to it.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Perhaps the biggest change from Samba3 is that there is no distinction
|
|
rpm-build |
95f51c |
between a "talloc context" and a "talloc pointer". Any pointer
|
|
rpm-build |
95f51c |
returned from talloc() is itself a valid talloc context. This means
|
|
rpm-build |
95f51c |
you can do this::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
struct foo *X = talloc(mem_ctx, struct foo);
|
|
rpm-build |
95f51c |
X->name = talloc_strdup(X, "foo");
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
and the pointer X->name would be a "child" of the talloc context "X"
|
|
rpm-build |
95f51c |
which is itself a child of "mem_ctx". So if you do talloc_free(mem_ctx)
|
|
rpm-build |
95f51c |
then it is all destroyed, whereas if you do talloc_free(X) then just X
|
|
rpm-build |
95f51c |
and X->name are destroyed, and if you do talloc_free(X->name) then
|
|
rpm-build |
95f51c |
just the name element of X is destroyed.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
If you think about this, then what this effectively gives you is an
|
|
rpm-build |
95f51c |
n-ary tree, where you can free any part of the tree with
|
|
rpm-build |
95f51c |
talloc_free().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
If you find this confusing, then I suggest you run the testsuite to
|
|
rpm-build |
95f51c |
watch talloc in action. You may also like to add your own tests to
|
|
rpm-build |
95f51c |
testsuite.c to clarify how some particular situation is handled.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Performance
|
|
rpm-build |
95f51c |
-----------
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
All the additional features of talloc() over malloc() do come at a
|
|
rpm-build |
95f51c |
price. We have a simple performance test in Samba4 that measures
|
|
rpm-build |
95f51c |
talloc() versus malloc() performance, and it seems that talloc() is
|
|
rpm-build |
95f51c |
about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
|
|
rpm-build |
95f51c |
the great reduction in code complexity that we get by using talloc
|
|
rpm-build |
95f51c |
makes this worthwhile, especially as the total overhead of
|
|
rpm-build |
95f51c |
talloc/malloc in Samba is already quite small.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc API
|
|
rpm-build |
95f51c |
----------
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The following is a complete guide to the talloc API. Read it all at
|
|
rpm-build |
95f51c |
least twice.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Multi-threading
|
|
rpm-build |
95f51c |
---------------
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc itself does not deal with threads. It is thread-safe (assuming
|
|
rpm-build |
95f51c |
the underlying "malloc" is), as long as each thread uses different
|
|
rpm-build |
95f51c |
memory contexts.
|
|
rpm-build |
95f51c |
If two threads use the same context then they need to synchronize in
|
|
rpm-build |
95f51c |
order to be safe. In particular:
|
|
rpm-build |
95f51c |
- when using talloc_enable_leak_report(), giving directly NULL as a
|
|
rpm-build |
95f51c |
parent context implicitly refers to a hidden "null context" global
|
|
rpm-build |
95f51c |
variable, so this should not be used in a multi-threaded environment
|
|
rpm-build |
95f51c |
without proper synchronization. In threaded code turn off null tracking using
|
|
rpm-build |
95f51c |
talloc_disable_null_tracking(). ;
|
|
rpm-build |
95f51c |
- the context returned by talloc_autofree_context() is also global so
|
|
rpm-build |
95f51c |
shouldn't be used by several threads simultaneously without
|
|
rpm-build |
95f51c |
synchronization.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc and shared objects
|
|
rpm-build |
95f51c |
-------------------------
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc can be used in shared objects. Special care needs to be taken
|
|
rpm-build |
95f51c |
to never use talloc_autofree_context() in code that might be loaded
|
|
rpm-build |
95f51c |
with dlopen() and unloaded with dlclose(), as talloc_autofree_context()
|
|
rpm-build |
95f51c |
internally uses atexit(3). Some platforms like modern Linux handles
|
|
rpm-build |
95f51c |
this fine, but for example FreeBSD does not deal well with dlopen()
|
|
rpm-build |
95f51c |
and atexit() used simultaneously: dlclose() does not clean up the list
|
|
rpm-build |
95f51c |
of atexit-handlers, so when the program exits the code that was
|
|
rpm-build |
95f51c |
registered from within talloc_autofree_context() is gone, the program
|
|
rpm-build |
95f51c |
crashes at exit.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(type *)talloc(const void *context, type);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc() macro is the core of the talloc library. It takes a
|
|
rpm-build |
95f51c |
memory context and a type, and returns a pointer to a new area of
|
|
rpm-build |
95f51c |
memory of the given type.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The returned pointer is itself a talloc context, so you can use it as
|
|
rpm-build |
95f51c |
the context argument to more calls to talloc if you wish.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The returned pointer is a "child" of the supplied context. This means
|
|
rpm-build |
95f51c |
that if you talloc_free() the context then the new child disappears as
|
|
rpm-build |
95f51c |
well. Alternatively you can free just the child.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The context argument to talloc() can be NULL, in which case a new top
|
|
rpm-build |
95f51c |
level context is created.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_size(const void *context, size_t size);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The function talloc_size() should be used when you don't have a
|
|
rpm-build |
95f51c |
convenient type to pass to talloc(). Unlike talloc(), it is not type
|
|
rpm-build |
95f51c |
safe (as it returns a void *), so you are on your own for type checking.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_ptrtype() macro should be used when you have a pointer and
|
|
rpm-build |
95f51c |
want to allocate memory to point at with this pointer. When compiling
|
|
rpm-build |
95f51c |
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
|
|
rpm-build |
95f51c |
and talloc_get_name() will return the current location in the source file.
|
|
rpm-build |
95f51c |
and not the type.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
int talloc_free(void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_free() function frees a piece of talloc memory, and all its
|
|
rpm-build |
95f51c |
children. You can call talloc_free() on any pointer returned by
|
|
rpm-build |
95f51c |
talloc().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The return value of talloc_free() indicates success or failure, with 0
|
|
rpm-build |
95f51c |
returned for success and -1 for failure. A possible failure condition
|
|
rpm-build |
95f51c |
is if the pointer had a destructor attached to it and the destructor
|
|
rpm-build |
95f51c |
returned -1. See talloc_set_destructor() for details on
|
|
rpm-build |
95f51c |
destructors. Likewise, if "ptr" is NULL, then the function will make
|
|
rpm-build |
95f51c |
no modifications and returns -1.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
From version 2.0 and onwards, as a special case, talloc_free() is
|
|
rpm-build |
95f51c |
refused on pointers that have more than one parent associated, as talloc
|
|
rpm-build |
95f51c |
would have no way of knowing which parent should be removed. This is
|
|
rpm-build |
95f51c |
different from older versions in the sense that always the reference to
|
|
rpm-build |
95f51c |
the most recently established parent has been destroyed. Hence to free a
|
|
rpm-build |
95f51c |
pointer that has more than one parent please use talloc_unlink().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
To help you find problems in your code caused by this behaviour, if
|
|
rpm-build |
95f51c |
you do try and free a pointer with more than one parent then the
|
|
rpm-build |
95f51c |
talloc logging function will be called to give output like this:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ERROR: talloc_free with references at some_dir/source/foo.c:123
|
|
rpm-build |
95f51c |
reference at some_dir/source/other.c:325
|
|
rpm-build |
95f51c |
reference at some_dir/source/third.c:121
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Please see the documentation for talloc_set_log_fn() and
|
|
rpm-build |
95f51c |
talloc_set_log_stderr() for more information on talloc logging
|
|
rpm-build |
95f51c |
functions.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_free() operates recursively on its children.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_free_children(void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_free_children() walks along the list of all children of a
|
|
rpm-build |
95f51c |
talloc context and talloc_free()s only the children, not the context
|
|
rpm-build |
95f51c |
itself.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
A NULL argument is handled as no-op.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_reference(const void *context, const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_reference() function makes "context" an additional parent
|
|
rpm-build |
95f51c |
of "ptr".
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The return value of talloc_reference() is always the original pointer
|
|
rpm-build |
95f51c |
"ptr", unless talloc ran out of memory in creating the reference in
|
|
rpm-build |
95f51c |
which case it will return NULL (each additional reference consumes
|
|
rpm-build |
95f51c |
around 48 bytes of memory on intel x86 platforms).
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
After creating a reference you can free it in one of the following
|
|
rpm-build |
95f51c |
ways:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
- you can talloc_free() any parent of the original pointer. That
|
|
rpm-build |
95f51c |
will reduce the number of parents of this pointer by 1, and will
|
|
rpm-build |
95f51c |
cause this pointer to be freed if it runs out of parents.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
- you can talloc_free() the pointer itself if it has at maximum one
|
|
rpm-build |
95f51c |
parent. This behaviour has been changed since the release of version
|
|
rpm-build |
95f51c |
2.0. Further information in the description of "talloc_free".
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
For more control on which parent to remove, see talloc_unlink()
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
int talloc_unlink(const void *context, void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_unlink() function removes a specific parent from ptr. The
|
|
rpm-build |
95f51c |
context passed must either be a context used in talloc_reference()
|
|
rpm-build |
95f51c |
with this pointer, or must be a direct parent of ptr.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Note that if the parent has already been removed using talloc_free()
|
|
rpm-build |
95f51c |
then this function will fail and will return -1. Likewise, if "ptr"
|
|
rpm-build |
95f51c |
is NULL, then the function will make no modifications and return -1.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can just use talloc_free() instead of talloc_unlink() if there
|
|
rpm-build |
95f51c |
is at maximum one parent. This behaviour has been changed since the
|
|
rpm-build |
95f51c |
release of version 2.0. Further information in the description of
|
|
rpm-build |
95f51c |
"talloc_free".
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The function talloc_set_destructor() sets the "destructor" for the
|
|
rpm-build |
95f51c |
pointer "ptr". A destructor is a function that is called when the
|
|
rpm-build |
95f51c |
memory used by a pointer is about to be released. The destructor
|
|
rpm-build |
95f51c |
receives the pointer as an argument, and should return 0 for success
|
|
rpm-build |
95f51c |
and -1 for failure.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The destructor can do anything it wants to, including freeing other
|
|
rpm-build |
95f51c |
pieces of memory. A common use for destructors is to clean up
|
|
rpm-build |
95f51c |
operating system resources (such as open file descriptors) contained
|
|
rpm-build |
95f51c |
in the structure the destructor is placed on.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can only place one destructor on a pointer. If you need more than
|
|
rpm-build |
95f51c |
one destructor then you can create a zero-length child of the pointer
|
|
rpm-build |
95f51c |
and place an additional destructor on that.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
To remove a destructor call talloc_set_destructor() with NULL for the
|
|
rpm-build |
95f51c |
destructor.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
If your destructor attempts to talloc_free() the pointer that it is
|
|
rpm-build |
95f51c |
the destructor for then talloc_free() will return -1 and the free will
|
|
rpm-build |
95f51c |
be ignored. This would be a pointless operation anyway, as the
|
|
rpm-build |
95f51c |
destructor is only called when the memory is just about to go away.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
int talloc_increase_ref_count(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_increase_ref_count(ptr) function is exactly equivalent to:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_reference(NULL, ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can use either syntax, depending on which you think is clearer in
|
|
rpm-build |
95f51c |
your code.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
It returns 0 on success and -1 on failure.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
size_t talloc_reference_count(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Return the number of references to the pointer.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_set_name(const void *ptr, const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Each talloc pointer has a "name". The name is used principally for
|
|
rpm-build |
95f51c |
debugging purposes, although it is also possible to set and get the
|
|
rpm-build |
95f51c |
name on a pointer in as a way of "marking" pointers in your code.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The main use for names on pointer is for "talloc reports". See
|
|
rpm-build |
95f51c |
talloc_report() and talloc_report_full() for details. Also see
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() and talloc_enable_leak_report_full().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_set_name() function allocates memory as a child of the
|
|
rpm-build |
95f51c |
pointer. It is logically equivalent to:
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Note that multiple calls to talloc_set_name() will allocate more
|
|
rpm-build |
95f51c |
memory without releasing the name. All of the memory is released when
|
|
rpm-build |
95f51c |
the ptr is freed using talloc_free().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_set_name_const(const void *ptr, const char *name);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The function talloc_set_name_const() is just like talloc_set_name(),
|
|
rpm-build |
95f51c |
but it takes a string constant, and is much faster. It is extensively
|
|
rpm-build |
95f51c |
used by the "auto naming" macros, such as talloc_p().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function does not allocate any memory. It just copies the
|
|
rpm-build |
95f51c |
supplied pointer into the internal representation of the talloc
|
|
rpm-build |
95f51c |
ptr. This means you must not pass a name pointer to memory that will
|
|
rpm-build |
95f51c |
disappear before the ptr is freed with talloc_free().
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_named(const void *context, size_t size, const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_named() function creates a named talloc pointer. It is
|
|
rpm-build |
95f51c |
equivalent to:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ptr = talloc_size(context, size);
|
|
rpm-build |
95f51c |
talloc_set_name(ptr, fmt, ....);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_named_const(const void *context, size_t size, const char *name);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ptr = talloc_size(context, size);
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, name);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
const char *talloc_get_name(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This returns the current name for the given talloc pointer. See
|
|
rpm-build |
95f51c |
talloc_set_name() for details.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_init(const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function creates a zero length named talloc context as a top
|
|
rpm-build |
95f51c |
level context. It is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_named(NULL, 0, fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_new(void *ctx);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This is a utility macro that creates a new memory context hanging
|
|
rpm-build |
95f51c |
off an exiting context, automatically naming it "talloc_new: __location__"
|
|
rpm-build |
95f51c |
where __location__ is the source line it is called from. It is
|
|
rpm-build |
95f51c |
particularly useful for creating a new temporary working context.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(type *)talloc_realloc(const void *context, void *ptr, type, count);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_realloc() macro changes the size of a talloc
|
|
rpm-build |
95f51c |
pointer. The "count" argument is the number of elements of type "type"
|
|
rpm-build |
95f51c |
that you want the resulting pointer to hold.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_realloc() has the following equivalences::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
|
|
rpm-build |
95f51c |
talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
|
|
rpm-build |
95f51c |
talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The "context" argument is only used if "ptr" is NULL, otherwise it is
|
|
rpm-build |
95f51c |
ignored.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_realloc() returns the new pointer, or NULL on failure. The call
|
|
rpm-build |
95f51c |
will fail either due to a lack of memory, or because the pointer has
|
|
rpm-build |
95f51c |
more than one parent (see talloc_reference()).
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_realloc_size(const void *context, void *ptr, size_t size);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
the talloc_realloc_size() function is useful when the type is not
|
|
rpm-build |
95f51c |
known so the typesafe talloc_realloc() cannot be used.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_steal(const void *new_ctx, const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_steal() function changes the parent context of a talloc
|
|
rpm-build |
95f51c |
pointer. It is typically used when the context that the pointer is
|
|
rpm-build |
95f51c |
currently a child of is going to be freed and you wish to keep the
|
|
rpm-build |
95f51c |
memory for a longer time.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_steal() function returns the pointer that you pass it. It
|
|
rpm-build |
95f51c |
does not have any failure modes.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
NOTE: It is possible to produce loops in the parent/child relationship
|
|
rpm-build |
95f51c |
if you are not careful with talloc_steal(). No guarantees are provided
|
|
rpm-build |
95f51c |
as to your sanity or the safety of your data if you do this.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Note that if you try and call talloc_steal() on a pointer that has
|
|
rpm-build |
95f51c |
more than one parent then the result is ambiguous. Talloc will choose
|
|
rpm-build |
95f51c |
to remove the parent that is currently indicated by talloc_parent()
|
|
rpm-build |
95f51c |
and replace it with the chosen parent. You will also get a message
|
|
rpm-build |
95f51c |
like this via the talloc logging functions:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
WARNING: talloc_steal with references at some_dir/source/foo.c:123
|
|
rpm-build |
95f51c |
reference at some_dir/source/other.c:325
|
|
rpm-build |
95f51c |
reference at some_dir/source/third.c:121
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
To unambiguously change the parent of a pointer please see the
|
|
rpm-build |
95f51c |
function talloc_reparent(). See the talloc_set_log_fn() documentation
|
|
rpm-build |
95f51c |
for more information on talloc logging.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_reparent() function changes the parent context of a talloc
|
|
rpm-build |
95f51c |
pointer. It is typically used when the context that the pointer is
|
|
rpm-build |
95f51c |
currently a child of is going to be freed and you wish to keep the
|
|
rpm-build |
95f51c |
memory for a longer time.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_reparent() function returns the pointer that you pass it. It
|
|
rpm-build |
95f51c |
does not have any failure modes.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The difference between talloc_reparent() and talloc_steal() is that
|
|
rpm-build |
95f51c |
talloc_reparent() can specify which parent you wish to change. This is
|
|
rpm-build |
95f51c |
useful when a pointer has multiple parents via references.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_parent(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_parent() function returns the current talloc parent. This
|
|
rpm-build |
95f51c |
is usually the pointer under which this memory was originally created,
|
|
rpm-build |
95f51c |
but it may have changed due to a talloc_steal() or talloc_reparent()
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
size_t talloc_total_size(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_total_size() function returns the total size in bytes used
|
|
rpm-build |
95f51c |
by this pointer and all child pointers. Mostly useful for debugging.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Passing NULL is allowed, but it will only give a meaningful result if
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
|
rpm-build |
95f51c |
been called.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
size_t talloc_total_blocks(const void *ptr);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_total_blocks() function returns the total memory block
|
|
rpm-build |
95f51c |
count used by this pointer and all child pointers. Mostly useful for
|
|
rpm-build |
95f51c |
debugging.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Passing NULL is allowed, but it will only give a meaningful result if
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
|
rpm-build |
95f51c |
been called.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
|
|
rpm-build |
95f51c |
void (*callback)(const void *ptr,
|
|
rpm-build |
95f51c |
int depth, int max_depth,
|
|
rpm-build |
95f51c |
int is_ref,
|
|
rpm-build |
95f51c |
void *priv),
|
|
rpm-build |
95f51c |
void *priv);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This provides a more flexible reports than talloc_report(). It
|
|
rpm-build |
95f51c |
will recursively call the callback for the entire tree of memory
|
|
rpm-build |
95f51c |
referenced by the pointer. References in the tree are passed with
|
|
rpm-build |
95f51c |
is_ref = 1 and the pointer that is referenced.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can pass NULL for the pointer, in which case a report is
|
|
rpm-build |
95f51c |
printed for the top level memory context, but only if
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() or talloc_enable_leak_report_full()
|
|
rpm-build |
95f51c |
has been called.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The recursion is stopped when depth >= max_depth.
|
|
rpm-build |
95f51c |
max_depth = -1 means only stop at leaf nodes.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This provides a more flexible reports than talloc_report(). It
|
|
rpm-build |
95f51c |
will let you specify the depth and max_depth.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_report(const void *ptr, FILE *f);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_report() function prints a summary report of all memory
|
|
rpm-build |
95f51c |
used by ptr. One line of report is printed for each immediate child of
|
|
rpm-build |
95f51c |
ptr, showing the total memory and number of blocks used by that child.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can pass NULL for the pointer, in which case a report is printed
|
|
rpm-build |
95f51c |
for the top level memory context, but only if
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
|
rpm-build |
95f51c |
been called.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_report_full(const void *ptr, FILE *f);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This provides a more detailed report than talloc_report(). It will
|
|
rpm-build |
95f51c |
recursively print the entire tree of memory referenced by the
|
|
rpm-build |
95f51c |
pointer. References in the tree are shown by giving the name of the
|
|
rpm-build |
95f51c |
pointer that is referenced.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
You can pass NULL for the pointer, in which case a report is printed
|
|
rpm-build |
95f51c |
for the top level memory context, but only if
|
|
rpm-build |
95f51c |
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
|
rpm-build |
95f51c |
been called.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_enable_leak_report(void);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This enables calling of talloc_report(NULL, stderr) when the program
|
|
rpm-build |
95f51c |
exits. In Samba4 this is enabled by using the --leak-report command
|
|
rpm-build |
95f51c |
line option.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
For it to be useful, this function must be called before any other
|
|
rpm-build |
95f51c |
talloc function as it establishes a "null context" that acts as the
|
|
rpm-build |
95f51c |
top of the tree. If you don't call this function first then passing
|
|
rpm-build |
95f51c |
NULL to talloc_report() or talloc_report_full() won't give you the
|
|
rpm-build |
95f51c |
full tree printout.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Here is a typical talloc report:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc report on 'null_context' (total 267 bytes in 15 blocks)
|
|
rpm-build |
95f51c |
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
|
rpm-build |
95f51c |
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
|
rpm-build |
95f51c |
iconv(UTF8,CP850) contains 42 bytes in 2 blocks
|
|
rpm-build |
95f51c |
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
|
rpm-build |
95f51c |
iconv(CP850,UTF8) contains 42 bytes in 2 blocks
|
|
rpm-build |
95f51c |
iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
|
|
rpm-build |
95f51c |
iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_enable_leak_report_full(void);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This enables calling of talloc_report_full(NULL, stderr) when the
|
|
rpm-build |
95f51c |
program exits. In Samba4 this is enabled by using the
|
|
rpm-build |
95f51c |
--leak-report-full command line option.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
For it to be useful, this function must be called before any other
|
|
rpm-build |
95f51c |
talloc function as it establishes a "null context" that acts as the
|
|
rpm-build |
95f51c |
top of the tree. If you don't call this function first then passing
|
|
rpm-build |
95f51c |
NULL to talloc_report() or talloc_report_full() won't give you the
|
|
rpm-build |
95f51c |
full tree printout.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Here is a typical full report:
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
full talloc report on 'root' (total 18 bytes in 8 blocks)
|
|
rpm-build |
95f51c |
p1 contains 18 bytes in 7 blocks (ref 0)
|
|
rpm-build |
95f51c |
r1 contains 13 bytes in 2 blocks (ref 0)
|
|
rpm-build |
95f51c |
reference to: p2
|
|
rpm-build |
95f51c |
p2 contains 1 bytes in 1 blocks (ref 1)
|
|
rpm-build |
95f51c |
x3 contains 1 bytes in 1 blocks (ref 0)
|
|
rpm-build |
95f51c |
x2 contains 1 bytes in 1 blocks (ref 0)
|
|
rpm-build |
95f51c |
x1 contains 1 bytes in 1 blocks (ref 0)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_enable_null_tracking(void);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This enables tracking of the NULL memory context without enabling leak
|
|
rpm-build |
95f51c |
reporting on exit. Useful for when you want to do your own leak
|
|
rpm-build |
95f51c |
reporting call via talloc_report_null_full();
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_disable_null_tracking(void);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This disables tracking of the NULL memory context.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(type *)talloc_zero(const void *ctx, type);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_zero() macro is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ptr = talloc(ctx, type);
|
|
rpm-build |
95f51c |
if (ptr) memset(ptr, 0, sizeof(type));
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_zero_size(const void *ctx, size_t size)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_zero_size() function is useful when you don't have a known type
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_memdup(const void *ctx, const void *p, size_t size);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_memdup() function is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ptr = talloc_size(ctx, size);
|
|
rpm-build |
95f51c |
if (ptr) memcpy(ptr, p, size);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_strdup(const void *ctx, const char *p);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_strdup() function is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
ptr = talloc_size(ctx, strlen(p)+1);
|
|
rpm-build |
95f51c |
if (ptr) memcpy(ptr, p, strlen(p)+1);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the passed
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_strndup(const void *t, const char *p, size_t n);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_strndup() function is the talloc equivalent of the C
|
|
rpm-build |
95f51c |
library function strndup()
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the passed
|
|
rpm-build |
95f51c |
string. This is equivalent to:
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_append_string(const void *t, char *orig, const char *append);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_append_string() function appends the given formatted
|
|
rpm-build |
95f51c |
string to the given string.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function sets the name of the new pointer to the new
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_vasprintf() function is the talloc equivalent of the C
|
|
rpm-build |
95f51c |
library function vasprintf()
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the new
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_asprintf(const void *t, const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_asprintf() function is the talloc equivalent of the C
|
|
rpm-build |
95f51c |
library function asprintf()
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the new
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_asprintf_append(char *s, const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_asprintf_append() function appends the given formatted
|
|
rpm-build |
95f51c |
string to the given string.
|
|
rpm-build |
95f51c |
Use this variant when the string in the current talloc buffer may
|
|
rpm-build |
95f51c |
have been truncated in length.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the new
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_asprintf_append() function appends the given formatted
|
|
rpm-build |
95f51c |
string to the end of the currently allocated talloc buffer.
|
|
rpm-build |
95f51c |
Use this variant when the string in the current talloc buffer has
|
|
rpm-build |
95f51c |
not been changed.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This functions sets the name of the new pointer to the new
|
|
rpm-build |
95f51c |
string. This is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, ptr)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
((type *)talloc_array(const void *ctx, type, unsigned int count);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_array() macro is equivalent to::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
(type *)talloc_size(ctx, sizeof(type) * count);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
except that it provides integer overflow protection for the multiply,
|
|
rpm-build |
95f51c |
returning NULL if the multiply overflows.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_array_size(const void *ctx, size_t size, unsigned int count);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_array_size() function is useful when the type is not
|
|
rpm-build |
95f51c |
known. It operates in the same way as talloc_array(), but takes a size
|
|
rpm-build |
95f51c |
instead of a type.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
The talloc_ptrtype() macro should be used when you have a pointer to an array
|
|
rpm-build |
95f51c |
and want to allocate memory of an array to point at with this pointer. When compiling
|
|
rpm-build |
95f51c |
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
|
|
rpm-build |
95f51c |
and talloc_get_name() will return the current location in the source file.
|
|
rpm-build |
95f51c |
and not the type.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This is a non-macro version of talloc_realloc(), which is useful
|
|
rpm-build |
95f51c |
as libraries sometimes want a ralloc function pointer. A realloc()
|
|
rpm-build |
95f51c |
implementation encapsulates the functionality of malloc(), free() and
|
|
rpm-build |
95f51c |
realloc() in one call, which is why it is useful to be able to pass
|
|
rpm-build |
95f51c |
around a single function pointer.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_autofree_context(void);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This is a handy utility function that returns a talloc context
|
|
rpm-build |
95f51c |
which will be automatically freed on program exit. This can be used
|
|
rpm-build |
95f51c |
to reduce the noise in memory leak reports.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_check_name(const void *ptr, const char *name);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function checks if a pointer has the specified name. If it does
|
|
rpm-build |
95f51c |
then the pointer is returned. It it doesn't then NULL is returned.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(type *)talloc_get_type(const void *ptr, type);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This macro allows you to do type checking on talloc pointers. It is
|
|
rpm-build |
95f51c |
particularly useful for void* private pointers. It is equivalent to
|
|
rpm-build |
95f51c |
this::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
(type *)talloc_check_name(ptr, #type)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
talloc_set_type(const void *ptr, type);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This macro allows you to force the name of a pointer to be of a
|
|
rpm-build |
95f51c |
particular type. This can be used in conjunction with
|
|
rpm-build |
95f51c |
talloc_get_type() to do type checking on void* pointers.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
It is equivalent to this::
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
talloc_set_name_const(ptr, #type)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
talloc_get_size(const void *ctx);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function lets you know the amount of memory allocated so far by
|
|
rpm-build |
95f51c |
this context. It does NOT account for subcontext memory.
|
|
rpm-build |
95f51c |
This can be used to calculate the size of an array.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void *talloc_find_parent_byname(const void *ctx, const char *name);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Find a parent memory context of the current context that has the given
|
|
rpm-build |
95f51c |
name. This can be very useful in complex programs where it may be
|
|
rpm-build |
95f51c |
difficult to pass all information down to the level you need, but you
|
|
rpm-build |
95f51c |
know the structure you want is a parent of another context.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
(type *)talloc_find_parent_bytype(ctx, type);
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
Like talloc_find_parent_byname() but takes a type, making it typesafe.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_set_log_fn(void (*log_fn)(const char *message));
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This function sets a logging function that talloc will use for
|
|
rpm-build |
95f51c |
warnings and errors. By default talloc will not print any warnings or
|
|
rpm-build |
95f51c |
errors.
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
|
rpm-build |
95f51c |
void talloc_set_log_stderr(void)
|
|
rpm-build |
95f51c |
|
|
rpm-build |
95f51c |
This sets the talloc log function to write log messages to stderr.
|