user from section @ref context-hierarchy
should be created with the context hierarchy illustrated on the next image.
@image html context_tree.png
@section bp-tmpctx Every function should use its own context
It is a good practice to create a temporary talloc context at the function
beginning and free the context just before the return statement. All the data
must be allocated on this context or on its children. This ensures that no
memory leaks are created as long as we do not forget to free the temporary
context.
This pattern applies to both situations - when a function does not return any
dynamically allocated value and when it does. However, it needs a little
extension for the latter case.
@subsection bp-tmpctx-1 Functions that do not return any dynamically allocated
value
If the function does not return any value created on the heap, we will just obey
the aforementioned pattern.
@code
int bar()
{
int ret;
TALLOC_CTX *tmp_ctx = talloc_new(NULL);
if (tmp_ctx == NULL) {
ret = ENOMEM;
goto done;
}
/* allocate data on tmp_ctx or on its descendants */
ret = EOK;
done:
talloc_free(tmp_ctx);
return ret;
}
@endcode
@subsection bp-tmpctx-2 Functions returning dynamically allocated values
If our function returns any dynamically allocated data, its first parameter
should always be the destination talloc context. This context serves as a parent
for the output values. But again, we will create the output values as the
descendants of the temporary context. If everything goes well, we will change
the parent of the output values from the temporary to the destination talloc
context.
This pattern ensures that if an error occurs (e.g. I/O error or insufficient
amount of the memory), all allocated data is freed and no garbage appears on
the destination context.
@code
int struct_foo_init(TALLOC_CTX *mem_ctx, struct foo **_foo)
{
int ret;
struct foo *foo = NULL;
TALLOC_CTX *tmp_ctx = talloc_new(NULL);
if (tmp_ctx == NULL) {
ret = ENOMEM;
goto done;
}
foo = talloc_zero(tmp_ctx, struct foo);
/* ... */
*_foo = talloc_steal(mem_ctx, foo);
ret = EOK;
done:
talloc_free(tmp_ctx);
return ret;
}
@endcode
@section bp-null Allocate temporary contexts on NULL
As it can be seen on the previous listing, instead of allocating the temporary
context directly on mem_ctx, we created a new top level context
using NULL as the parameter for talloc_new() function.
Take a look at the following example:
@code
char *create_user_filter(TALLOC_CTX *mem_ctx,
uid_t uid, const char *username)
{
char *filter = NULL;
char *sanitized_username = NULL;
/* tmp_ctx is a child of mem_ctx */
TALLOC_CTX *tmp_ctx = talloc_new(mem_ctx);
if (tmp_ctx == NULL) {
return NULL;
}
sanitized_username = sanitize_string(tmp_ctx, username);
if (sanitized_username == NULL) {
talloc_free(tmp_ctx);
return NULL;
}
filter = talloc_aprintf(tmp_ctx,"(|(uid=%llu)(uname=%s))",
uid, sanitized_username);
if (filter == NULL) {
return NULL; /* tmp_ctx is not freed */ (*@\label{lst:tmp-ctx-3:leak}@*)
}
/* filter becomes a child of mem_ctx */
filter = talloc_steal(mem_ctx, filter);
talloc_free(tmp_ctx);
return filter;
}
@endcode
We forgot to free tmp_ctx before the return statement
in the filter == NULL condition. However, it is created as a child
of mem_ctx context and as such it will be freed as soon as the
mem_ctx is freed. Therefore, no detectable memory leak is created.
On the other hand, we do not have any way to access the allocated data
and for all we know mem_ctx may exist for the lifetime of our
application. For these reasons this should be considered as a memory leak. How
can we detect if it is unreferenced but still attached to its parent context?
The only way is to notice the mistake in the source code.
But if we create the temporary context as a top level context, it will not be
freed and memory diagnostic tools
(e.g. valgrind) are able to do their job.
@section bp-pool Temporary contexts and the talloc pool
If we want to take the advantage of the talloc pool but also keep to the
pattern introduced in the previous section, we are unable to do it directly. The
best thing to do is to create a conditional build where we can decide how do we
want to create the temporary context. For example, we can create the following
macros:
@code
#ifdef USE_POOL_CONTEXT
#define CREATE_POOL_CTX(ctx, size) talloc_pool(ctx, size)
#define CREATE_TMP_CTX(ctx) talloc_new(ctx)
#else
#define CREATE_POOL_CTX(ctx, size) talloc_new(ctx)
#define CREATE_TMP_CTX(ctx) talloc_new(NULL)
#endif
@endcode
Now if our application is under development, we will build it with macro
USE_POOL_CONTEXT undefined. This way, we can use memory diagnostic
utilities to detect memory leaks.
The release version will be compiled with the macro defined. This will enable
pool contexts and therefore reduce the malloc() calls, which will
end up in a little bit faster processing.
@code
int struct_foo_init(TALLOC_CTX *mem_ctx, struct foo **_foo)
{
int ret;
struct foo *foo = NULL;
TALLOC_CTX *tmp_ctx = CREATE_TMP_CTX(mem_ctx);
/* ... */
}
errno_t handle_request(TALLOC_CTX mem_ctx)
{
int ret;
struct foo *foo = NULL;
TALLOC_CTX *pool_ctx = CREATE_POOL_CTX(NULL, 1024);
ret = struct_foo_init(mem_ctx, &foo);
/* ... */
}
@endcode
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_context.dox 0000664 0000000 0000000 00000015777 14207652121 016446 0 ustar 00root root /**
@page libtalloc_context Chapter 1: Talloc context
@section context Talloc context
The talloc context is the most important part of this library and is
responsible for every single feature of this memory allocator. It is a logical
unit which represents a memory space managed by talloc.
From the programmer's point of view, the talloc context is completely
equivalent to a pointer that would be returned by the memory routines from the
C standard library. This means that every context that is returned from the
talloc library can be used directly in functions that do not use talloc
internally. For example we can do the following:
@code
char *str1 = strdup("I am NOT a talloc context");
char *str2 = talloc_strdup(NULL, "I AM a talloc context");
printf("%d\n", strcmp(str1, str2) == 0);
free(str1);
talloc_free(str2); /* we can not use free() on str2 */
@endcode
This is possible because the context is internally handled as a special
fixed-length structure called talloc chunk. Each chunk stores context metadata
followed by the memory space requested by the programmer. When a talloc
function returns a context (pointer), it will in fact return a pointer to the user
space portion of the talloc chunk. If we to manipulate this context using
talloc functions, the talloc library transforms the user-space pointer back to
the starting address of the chunk. This is also the reason why we were unable
to use free(str2) in the previous example - because
str2 does not point at the beginning of the allocated block of
memory. This is illustrated on the next image:
@image html context.png
The type TALLOC_CTX is defined in talloc.h to identify a talloc context in
function parameters. However, this type is just an alias for void
and exists only for semantical reasons - thus we can differentiate between
void * (arbitrary data) and TALLOC_CTX * (talloc
context).
@subsection metadata Context meta data
Every talloc context carries several pieces of internal information along with
the allocated memory:
- name - which is used in reports of context hierarchy and to simulate
a dynamic type system,
- size of the requested memory in bytes - this can be used to determine
the number of elements in arrays,
- attached destructor - which is executed just before the memory block is
about to be freed,
- references to the context
- children and parent contexts - create the hierarchical view on the
memory.
@section context-hierarchy Hierarchy of talloc context
Every talloc context contains information about its parent and children. Talloc
uses this information to create a hierarchical model of memory or to be more
precise, it creates an n-ary tree where each node represents a single talloc
context. The root node of the tree is referred to as a top level context - a
context without any parent.
This approach has several advantages:
- as a consequence of freeing a talloc context, all of its children
will be properly deallocated as well,
- the parent of a context can be changed at any time, which
results in moving the whole subtree under another node,
- it creates a more natural way of managing data structures.
@subsection Example
We have a structure that stores basic information about a user - his/her name,
identification number and groups he/she is a member of:
@code
struct user {
uid_t uid;
char *username;
size_t num_groups;
char **groups;
};
@endcode
We will allocate this structure using talloc. The result will be the following
context tree:
@image html context_tree.png
@code
/* create new top level context */
struct user *user = talloc(NULL, struct user);
user->uid = 1000;
user->num_groups = N;
/* make user the parent of following contexts */
user->username = talloc_strdup(user, "Test user");
user->groups = talloc_array(user, char*, user->num_groups);
for (i = 0; i < user->num_groups; i++) {
/* make user->groups the parent of following context */
user->groups[i] = talloc_asprintf(user->groups,
"Test group %d", i);
}
@endcode
This way, we have gained a lot of additional capabilities, one of which is
very simple deallocation of the structure and all of its elements.
With the C standard library we need first to iterate over the array of groups
and free every element separately. Then we must deallocate the array that stores
them. Next we deallocate the username and as the last step free the structure
itself. But with talloc, the only operation we need to execute is freeing the
structure context. Its descendants will be freed automatically.
@code
talloc_free(user);
@endcode
@section keep-hierarchy Always keep the hieararchy steady!
The talloc is a hierarchy memory allocator. The hierarchy nature is what makes
the programming more error proof. It makes the memory easier to manage and to
free. Therefore, the first thing we should have on our mind is: always
project our data structures into the talloc context hierarchy.
That means if we have a structure, we should always use it as a parent context
for its elements. This way we will not encounter any troubles when freeing this
structure or when changing its parent. The same rule applies for arrays.
@section creating-context Creating a talloc context
Here are the most important functions that create a new talloc context.
@subsection type-safe Type-safe functions
It allocates the size that is necessary for the given type and returns a new,
properly-casted pointer. This is the preferred way to create a new context as
we can rely on the compiler to detect type mismatches.
The name of the context is automatically set to the name of the data type which
is used to simulate a dynamic type system.
@code
struct user *user = talloc(ctx, struct user);
/* initialize to default values */
user->uid = 0;
user->name = NULL;
user->num_groups = 0;
user->groups = NULL;
/* or we can achieve the same result with */
struct user *user_zero = talloc_zero(ctx, struct user);
@endcode
@subsection zero-length Zero-length contexts
The zero-length context is basically a context without any special semantical
meaning. We can use it the same way as any other context. The only difference
is that it consists only of the meta data about the context. Therefore, it is
strictly of type TALLOC_CTX*. It is often used in cases where we
want to aggregate several data structures under one parent (zero-length)
context, such as a temporary context to contain memory needed within a single
function that is not interesting to the caller. Allocating on a zero-length
temporary context will make clean-up of the function simpler.
@code
TALLOC_CTX *tmp_ctx = NULL;
struct foo *foo = NULL;
struct bar *bar = NULL;
/* new zero-length top level context */
tmp_ctx = talloc_new(NULL);
if (tmp_ctx == NULL) {
return ENOMEM;
}
foo = talloc(tmp_ctx, struct foo);
bar = talloc(tmp_ctx, struct bar);
/* free everything at once */
talloc_free(tmp_ctx);
@endcode
@subsection context-see-also See also
- talloc_size()
- talloc_named()
- @ref talloc_array
- @ref talloc_string
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_debugging.dox 0000664 0000000 0000000 00000007650 14207652121 016704 0 ustar 00root root /**
@page libtalloc_debugging Chapter 6: Debugging
Although talloc makes memory management significantly easier than the C standard
library, developers are still only humans and can make mistakes. Therefore, it
can be handy to know some tools for the inspection of talloc memory usage.
@section log-abort Talloc log and abort
We have already encountered the abort function in section @ref dts.
In that case it was used when a type mismatch was detected. However, talloc
calls this abort function in several more situations:
- when the provided pointer is not a valid talloc context,
- when the meta data is invalid - probably due to memory corruption,
- and when an access after free is detected.
The third one is probably the most interesting. It can help us with detecting
an attempt to double-free a context or any other manipulation with it via
talloc functions (using it as a parent, stealing it, etc.).
Before the context is freed talloc sets a flag in the meta data. This is then
used to detect the access after free. It basically works on the assumption that
the memory stays unchanged (at least for a while) even when it is properly
deallocated. This will work even if the memory is filled with the value
specified in TALLOC_FREE_FILL environment variable, because it
fills only the data part and leaves the meta data intact.
Apart from the abort function, talloc uses a log function to provide additional
information to the aforementioned violations. To enable logging we shall set the
log function with one of:
- talloc_set_log_fn()
- talloc_set_log_stderr()
The following code is a sample output of accessing a context after it has been
freed:
@code
talloc_set_log_stderr();
TALLOC_CTX *ctx = talloc_new(NULL);
talloc_free(ctx);
talloc_free(ctx);
results in:
talloc: access after free error - first free may be at ../src/main.c:55
Bad talloc magic value - access after free
@endcode
Another example is an invalid context:
@code
talloc_set_log_stderr();
TALLOC_CTX *ctx = talloc_new(NULL);
char *str = strdup("not a talloc context");
talloc_steal(ctx, str);
results in:
Bad talloc magic value - unknown value
@endcode
@section reports Memory usage reports
Talloc can print reports of memory usage of a specified talloc context to a
file (to stdout or stderr). The report can be
simple or full. The simple report provides information only about the context
itself and its direct descendants. The full report goes recursively through the
entire context tree. See:
- talloc_report()
- talloc_report_full()
We will use the following code to retrieve the sample report:
@code
struct foo {
char *str;
};
TALLOC_CTX *ctx = talloc_new(NULL);
char *str = talloc_strdup(ctx, "my string");
struct foo *foo = talloc_zero(ctx, struct foo);
foo->str = talloc_strdup(foo, "I am Foo");
char *str2 = talloc_strdup(foo, "Foo is my parent");
/* print full report */
talloc_report_full(ctx, stdout);
@endcode
It will print a full report of ctx to the standard output.
The message should be similar to:
@code
full talloc report on 'talloc_new: ../src/main.c:82' (total 46 bytes in 5 blocks)
struct foo contains 34 bytes in 3 blocks (ref 0) 0x1495130
Foo is my parent contains 17 bytes in 1 blocks (ref 0) 0x1495200
I am Foo contains 9 bytes in 1 blocks (ref 0) 0x1495190
my string contains 10 bytes in 1 blocks (ref 0) 0x14950c0
@endcode
We can notice in this report that something is wrong with the context containing
struct foo. We know that the structure has only one string element.
However, we can see in the report that it has two children. This indicates that
we have either violated the memory hierarchy or forgotten to free it as
temporary data. Looking into the code, we can see that "Foo is my parent"
should be attached to ctx.
See also:
- talloc_enable_null_tracking()
- talloc_disable_null_tracking()
- talloc_enable_leak_report()
- talloc_enable_leak_report_full()
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_destructors.dox 0000664 0000000 0000000 00000004641 14207652121 017327 0 ustar 00root root /**
@page libtalloc_destructors Chapter 4: Using destructors
@section destructors Using destructors
Destructors are well known methods in the world of object oriented programming.
A destructor is a method of an object that is automatically run when the object
is destroyed. It is usually used to return resources taken by the object back to
the system (e.g. closing file descriptors, terminating connection to a database,
deallocating memory).
With talloc we can take the advantage of destructors even in C. We can easily
attach our own destructor to a talloc context. When the context is freed, the
destructor will run automatically.
To attach/detach a destructor to a talloc context use: talloc_set_destructor().
@section destructors-example Example
Imagine that we have a dynamically created linked list. Before we deallocate an
element of the list, we need to make sure that we have successfully removed it
from the list. Normally, this would be done by two commands in the exact order:
remove it from the list and then free the element. With talloc, we can do this
at once by setting a destructor on the element which will remove it from the
list and talloc_free() will do the rest.
The destructor would be:
@code
int list_remove(void *ctx)
{
struct list_el *el = NULL;
el = talloc_get_type_abort(ctx, struct list_el);
/* remove element from the list */
}
@endcode
GCC version 3 and newer can check for the types during the compilation. So if
it is our major compiler, we can use a more advanced destructor:
@code
int list_remove(struct list_el *el)
{
/* remove element from the list */
}
@endcode
Now we will assign the destructor to the list element. We can do this directly
in the function that inserts it.
@code
struct list_el* list_insert(TALLOC_CTX *mem_ctx,
struct list_el *where,
void *ptr)
{
struct list_el *el = talloc(mem_ctx, struct list_el);
el->data = ptr;
/* insert into list */
talloc_set_destructor(el, list_remove);
return el;
}
@endcode
Because talloc is a hierarchical memory allocator, we can go a step further and
free the data with the element as well:
@code
struct list_el* list_insert_free(TALLOC_CTX *mem_ctx,
struct list_el *where,
void *ptr)
{
struct list_el *el = NULL;
el = list_insert(mem_ctx, where, ptr);
talloc_steal(el, ptr);
return el;
}
@endcode
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_dts.dox 0000664 0000000 0000000 00000006321 14207652121 015535 0 ustar 00root root /**
@page libtalloc_dts Chapter 3: Dynamic type system
@section dts Dynamic type system
Generic programming in the C language is very difficult. There is no inheritance
nor templates known from object oriented languages. There is no dynamic type
system. Therefore, generic programming in this language is usually done by
type-casting a variable to void* and transferring it through
a generic function to a specialized callback as illustrated on the next listing.
@code
void generic_function(callback_fn cb, void *pvt)
{
/* do some stuff and call the callback */
cb(pvt);
}
void specific_callback(void *pvt)
{
struct specific_struct *data;
data = (struct specific_struct*)pvt;
/* ... */
}
void specific_function()
{
struct specific_struct data;
generic_function(callback, &data);
}
@endcode
Unfortunately, the type information is lost as a result of this type cast. The
compiler cannot check the type during the compilation nor are we able to do it
at runtime. Providing an invalid data type to the callback will result in
unexpected behaviour (not necessarily a crash) of the application. This mistake
is usually hard to detect because it is not the first thing which comes the
mind.
As we already know, every talloc context contains a name. This name is available
at any time and it can be used to determine the type of a context even if we
lose the type of a variable.
Although the name of the context can be set to any arbitrary string, the best
way of using it to simulate the dynamic type system is to set it directly to the
type of the variable.
It is recommended to use one of talloc() and talloc_array() (or its
variants) to create the context as they set its name to the name of the
given type automatically.
If we have a context with such as a name, we can use two similar functions that
do both the type check and the type cast for us:
- talloc_get_type()
- talloc_get_type_abort()
@section dts-examples Examples
The following example will show how generic programming with talloc is handled -
if we provide invalid data to the callback, the program will be aborted. This
is a sufficient reaction for such an error in most applications.
@code
void foo_callback(void *pvt)
{
struct foo *data = talloc_get_type_abort(pvt, struct foo);
/* ... */
}
int do_foo()
{
struct foo *data = talloc_zero(NULL, struct foo);
/* ... */
return generic_function(foo_callback, data);
}
@endcode
But what if we are creating a service application that should be running for the
uptime of a server, we may want to abort the application during the development
process (to make sure the error is not overlooked) and try to recover from the
error in the customer release. This can be achieved by creating a custom abort
function with a conditional build.
@code
void my_abort(const char *reason)
{
fprintf(stderr, "talloc abort: %s\n", reason);
#ifdef ABORT_ON_TYPE_MISMATCH
abort();
#endif
}
@endcode
The usage of talloc_get_type_abort() would be then:
@code
talloc_set_abort_fn(my_abort);
TALLOC_CTX *ctx = talloc_new(NULL);
char *str = talloc_get_type_abort(ctx, char);
if (str == NULL) {
/* recovery code */
}
/* talloc abort: ../src/main.c:25: Type mismatch:
name[talloc_new: ../src/main.c:24] expected[char] */
@endcode
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_introduction.dox 0000664 0000000 0000000 00000002676 14207652121 017475 0 ustar 00root root /**
@page libtalloc_tutorial The Tutorial
@section introduction Introduction
Talloc is a hierarchical, reference counted memory pool system with destructors.
It is built atop the C standard library and it defines a set of utility
functions that altogether simplifies allocation and deallocation of data,
especially for complex structures that contain many dynamically allocated
elements such as strings and arrays.
The main goals of this library are: removing the needs for creating a cleanup
function for every complex structure, providing a logical organization of
allocated memory blocks and reducing the likelihood of creating memory leaks in
long-running applications. All of this is achieved by allocating memory in a
hierarchical structure of talloc contexts such that deallocating one context
recursively frees all of its descendants as well.
@section main-features Main features
- An open source project
- A hierarchical memory model
- Natural projection of data structures into the memory space
- Simplifies memory management of large data structures
- Automatic execution of a destructor before the memory is freed
- Simulates a dynamic type system
- Implements a transparent memory pool
@section toc Table of contents:
@subpage libtalloc_context
@subpage libtalloc_stealing
@subpage libtalloc_dts
@subpage libtalloc_destructors
@subpage libtalloc_pools
@subpage libtalloc_debugging
@subpage libtalloc_bestpractices
@subpage libtalloc_threads
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_pools.dox 0000664 0000000 0000000 00000007114 14207652121 016100 0 ustar 00root root /**
@page libtalloc_pools Chapter 5: Memory pools
@section pools Memory pools
Allocation of a new memory is an expensive operation and large programs can
contain thousands of calls of malloc() for a single computation, where every
call allocates only a very small amount of the memory. This can result in an
undesirable slowdown of the application. We can avoid this slowdown by
decreasing the number of malloc() calls by using a memory pool.
A memory pool is a preallocated memory space with a fixed size. If we need to
allocate new data we will take the desired amount of the memory from the pool
instead of requesting a new memory from the system. This is done by creating a
pointer that points inside the preallocated memory. Such a pool must not be
reallocated as it would change its location - pointers that were pointing
inside the pool would become invalid. Therefore, a memory pool requires a very
good estimate of the required memory space.
The talloc library contains its own implementation of a memory pool. It is
highly transparent for the programmer. The only thing that needs to be done is
an initialization of a new pool context using talloc_pool() -
which can be used in the same way as any other context.
Refactoring of existing code (that uses talloc) to take the advantage of a
memory pool is quite simple due to the following properties of the pool context:
- if we are allocating data on a pool context, it takes the desired
amount of memory from the pool,
- if the context is a descendant of the pool context, it takes the space
from the pool as well,
- if the pool does not have sufficient portion of memory left, it will
create a new non-pool context, leaving the pool intact
@code
/* allocate 1KiB in a pool */
TALLOC_CTX *pool_ctx = talloc_pool(NULL, 1024);
/* Take 512B from the pool, 512B is left there */
void *ptr = talloc_size(pool_ctx, 512);
/* 1024B > 512B, this will create new talloc chunk outside
the pool */
void *ptr2 = talloc_size(ptr, 1024);
/* The pool still contains 512 free bytes
* this will take 200B from them. */
void *ptr3 = talloc_size(ptr, 200);
/* This will destroy context 'ptr3' but the memory
* is not freed, the available space in the pool
* will increase to 512B. */
talloc_free(ptr3);
/* This will free memory taken by 'pool_ctx'
* and 'ptr2' as well. */
talloc_free(pool_ctx);
@endcode
The above given is very convenient, but there is one big issue to be kept in
mind. If the parent of a talloc pool child is changed to a parent that is
outside of this pool, the whole pool memory will not be freed until the child is
freed. For this reason we must be very careful when stealing a descendant of a
pool context.
@code
TALLOC_CTX *mem_ctx = talloc_new(NULL);
TALLOC_CTX *pool_ctx = talloc_pool(NULL, 1024);
struct foo *foo = talloc(pool_ctx, struct foo);
/* mem_ctx is not in the pool */
talloc_steal(mem_ctx, foo);
/* pool_ctx is marked as freed but the memory is not
deallocated, accessing the pool_ctx again will cause
an error */
talloc_free(pool_ctx);
/* This deallocates the pool_ctx. */
talloc_free(mem_ctx);
@endcode
It may often be better to copy the memory we want instead of stealing it to
avoid this problem. If we do not need to retain the context name (to keep the
type information), we can use talloc_memdup() to do this.
Copying the memory out of the pool may, however, discard all the performance
boost given by the pool, depending on the size of the copied memory. Therefore,
the code should be well profiled before taking this path. In general, the
golden rule is: if we need to steal from the pool context, we should not
use a pool context.
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_stealing.dox 0000664 0000000 0000000 00000003624 14207652121 016554 0 ustar 00root root /**
@page libtalloc_stealing Chapter 2: Stealing a context
@section stealing Stealing a context
Talloc has the ability to change the parent of a talloc context to another
one. This operation is commonly referred to as stealing and it is one of
the most important actions performed with talloc contexts.
Stealing a context is necessary if we want the pointer to outlive the context it
is created on. This has many possible use cases, for instance stealing a result
of a database search to an in-memory cache context, changing the parent of a
field of a generic structure to a more specific one or vice-versa. The most
common scenario, at least in Samba, is to steal output data from a function-specific
context to the output context given as an argument of that function.
@code
struct foo {
char *a1;
char *a2;
char *a3;
};
struct bar {
char *wurst;
struct foo *foo;
};
struct foo *foo = talloc_zero(ctx, struct foo);
foo->a1 = talloc_strdup(foo, "a1");
foo->a2 = talloc_strdup(foo, "a2");
foo->a3 = talloc_strdup(foo, "a3");
struct bar *bar = talloc_zero(NULL, struct bar);
/* change parent of foo from ctx to bar */
bar->foo = talloc_steal(bar, foo);
/* or do the same but assign foo = NULL */
bar->foo = talloc_move(bar, &foo);
@endcode
The talloc_move() function is similar to the talloc_steal() function but
additionally sets the source pointer to NULL.
In general, the source pointer itself is not changed (it only replaces the
parent in the meta data). But the common usage is that the result is
assigned to another variable, thus further accessing the pointer from the
original variable should be avoided unless it is necessary. In this case
talloc_move() is the preferred way of stealing a context. Additionally sets the
source pointer to NULL, thus.protects the pointer from being accidentally freed
and accessed using the old variable after its parent has been changed.
@image html stealing.png
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doc/tutorial_threads.dox 0000664 0000000 0000000 00000011230 14207652121 016370 0 ustar 00root root /**
@page libtalloc_threads Chapter 8: Using threads with talloc
@section Talloc and thread safety
The talloc library is not internally thread-safe, in that accesses
to variables on a talloc context are not controlled by mutexes or
other thread-safe primitives.
However, so long as talloc_disable_null_tracking() is called from
the main thread to disable global variable access within talloc,
then each thread can safely use its own top level talloc context
allocated off the NULL context.
For example:
@code
static void *thread_fn(void *arg)
{
const char *ctx_name = (const char *)arg;
/*
* Create a new top level talloc hierarchy in
* this thread.
*/
void *top_ctx = talloc_named_const(NULL, 0, "top");
if (top_ctx == NULL) {
return NULL;
}
sub_ctx = talloc_named_const(top_ctx, 100, ctx_name);
if (sub_ctx == NULL) {
return NULL;
}
/*
* Do more processing/talloc calls on top_ctx
* and its children.
*/
......
talloc_free(top_ctx);
return value;
}
@endcode
is a perfectly safe use of talloc within a thread.
The problem comes when one thread wishes to move some
memory allocated on its local top level talloc context
to another thread. Care must be taken to add data access
exclusion to prevent memory corruption. One method would
be to lock a mutex before any talloc call on each thread,
but this would push the burden of total talloc thread-safety
on the poor user of the library.
A much easier way to transfer talloced memory between
threads is by the use of an intermediate, mutex locked,
intermediate variable.
An example of this is below - taken from test code inside
the talloc testsuite.
The main thread creates 1000 sub-threads, and then accepts
the transfer of some thread-talloc'ed memory onto its top
level context from each thread in turn.
A pthread mutex and condition variable are used to
synchronize the transfer via the intermediate_ptr
variable.
@code
/* Required sync variables. */
static pthread_mutex_t mtx = PTHREAD_MUTEX_INITIALIZER;
static pthread_cond_t condvar = PTHREAD_COND_INITIALIZER;
/* Intermediate talloc pointer for transfer. */
static void *intermediate_ptr;
/* Subthread. */
static void *thread_fn(void *arg)
{
int ret;
const char *ctx_name = (const char *)arg;
void *sub_ctx = NULL;
/*
* Do stuff that creates a new talloc hierarchy in
* this thread.
*/
void *top_ctx = talloc_named_const(NULL, 0, "top");
if (top_ctx == NULL) {
return NULL;
}
sub_ctx = talloc_named_const(top_ctx, 100, ctx_name);
if (sub_ctx == NULL) {
return NULL;
}
/*
* Now transfer a pointer from our hierarchy
* onto the intermediate ptr.
*/
ret = pthread_mutex_lock(&mtx);
if (ret != 0) {
talloc_free(top_ctx);
return NULL;
}
/* Wait for intermediate_ptr to be free. */
while (intermediate_ptr != NULL) {
ret = pthread_cond_wait(&condvar, &mtx);
if (ret != 0) {
talloc_free(top_ctx);
return NULL;
}
}
/* and move our memory onto it from our toplevel hierarchy. */
intermediate_ptr = talloc_move(NULL, &sub_ctx);
/* Tell the main thread it's ready for pickup. */
pthread_cond_broadcast(&condvar);
pthread_mutex_unlock(&mtx);
talloc_free(top_ctx);
return NULL;
}
/* Main thread. */
#define NUM_THREADS 1000
static bool test_pthread_talloc_passing(void)
{
int i;
int ret;
char str_array[NUM_THREADS][20];
pthread_t thread_id;
void *mem_ctx;
/*
* Important ! Null tracking breaks threaded talloc.
* It *must* be turned off.
*/
talloc_disable_null_tracking();
/* Main thread toplevel context. */
mem_ctx = talloc_named_const(NULL, 0, "toplevel");
if (mem_ctx == NULL) {
return false;
}
/*
* Spin off NUM_THREADS threads.
* They will use their own toplevel contexts.
*/
for (i = 0; i < NUM_THREADS; i++) {
(void)snprintf(str_array[i],
20,
"thread:%d",
i);
if (str_array[i] == NULL) {
return false;
}
ret = pthread_create(&thread_id,
NULL,
thread_fn,
str_array[i]);
if (ret != 0) {
return false;
}
}
/* Now wait for NUM_THREADS transfers of the talloc'ed memory. */
for (i = 0; i < NUM_THREADS; i++) {
ret = pthread_mutex_lock(&mtx);
if (ret != 0) {
talloc_free(mem_ctx);
return false;
}
/* Wait for intermediate_ptr to have our data. */
while (intermediate_ptr == NULL) {
ret = pthread_cond_wait(&condvar, &mtx);
if (ret != 0) {
talloc_free(mem_ctx);
return false;
}
}
/* and move it onto our toplevel hierarchy. */
(void)talloc_move(mem_ctx, &intermediate_ptr);
/* Tell the sub-threads we're ready for another. */
pthread_cond_broadcast(&condvar);
pthread_mutex_unlock(&mtx);
}
/* Dump the hierarchy. */
talloc_report(mem_ctx, stdout);
talloc_free(mem_ctx);
return true;
}
@endcode
*/
././@PaxHeader 0000000 0000000 0000000 00000000034 00000000000 010212 x ustar 00 28 mtime=1646220369.1444228
talloc-2.4.2/doxy.config 0000664 0000000 0000000 00000225716 14207652121 013724 0 ustar 00root root # Doxyfile 1.8.0
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
#
# All text after a hash (#) is considered a comment and will be ignored.
# The format is:
# TAG = value [value, ...]
# For lists items can also be appended using:
# TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ").
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
# This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all
# text before the first occurrence of this tag. Doxygen uses libiconv (or the
# iconv built into libc) for the transcoding. See
# http://www.gnu.org/software/libiconv for the list of possible encodings.
DOXYFILE_ENCODING = UTF-8
# The PROJECT_NAME tag is a single word (or sequence of words) that should
# identify the project. Note that if you do not use Doxywizard you need
# to put quotes around the project name if it contains spaces.
PROJECT_NAME = talloc
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.
PROJECT_NUMBER = 2.0
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer
# a quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF =
# With the PROJECT_LOGO tag one can specify an logo or icon that is
# included in the documentation. The maximum height of the logo should not
# exceed 55 pixels and the maximum width should not exceed 200 pixels.
# Doxygen will copy the logo to the output directory.
PROJECT_LOGO =
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = doc
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
# 4096 sub-directories (in 2 levels) under the output directory of each output
# format and will distribute the generated files over these directories.
# Enabling this option can be useful when feeding doxygen a huge amount of
# source files, where putting all generated files in the same directory would
# otherwise cause performance problems for the file system.
CREATE_SUBDIRS = NO
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German,
# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English
# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian,
# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak,
# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
OUTPUT_LANGUAGE = English
# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
# include brief member descriptions after the members that are listed in
# the file and class documentation (similar to JavaDoc).
# Set to NO to disable this.
BRIEF_MEMBER_DESC = YES
# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
# the brief description of a member or function before the detailed description.
# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
# brief descriptions will be completely suppressed.
REPEAT_BRIEF = YES
# This tag implements a quasi-intelligent brief description abbreviator
# that is used to form the text in various listings. Each string
# in this list, if found as the leading text of the brief description, will be
# stripped from the text and the result after processing the whole list, is
# used as the annotated text. Otherwise, the brief description is used as-is.
# If left blank, the following values are used ("$name" is automatically
# replaced with the name of the entity): "The $name class" "The $name widget"
# "The $name file" "is" "provides" "specifies" "contains"
# "represents" "a" "an" "the"
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
# Doxygen will generate a detailed section even if there is only a brief
# description.
ALWAYS_DETAILED_SEC = NO
# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
# inherited members of a class in the documentation of that class as if those
# members were ordinary class members. Constructors, destructors and assignment
# operators of the base classes will not be shown.
INLINE_INHERITED_MEMB = NO
# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
# path before files name in the file list and in the header files. If set
# to NO the shortest path that makes the file name unique will be used.
FULL_PATH_NAMES = YES
# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
# can be used to strip a user-defined part of the path. Stripping is
# only done if one of the specified strings matches the left-hand part of
# the path. The tag can be used to show relative paths in the file list.
# If left blank the directory from which doxygen is run is used as the
# path to strip.
STRIP_FROM_PATH =
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
# the path mentioned in the documentation of a class, which tells
# the reader which header file to include in order to use a class.
# If left blank only the name of the header file containing the class
# definition is used. Otherwise one should specify the include paths that
# are normally passed to the compiler using the -I flag.
STRIP_FROM_INC_PATH =
# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
# (but less readable) file names. This can be useful if your file system
# doesn't support long names like on DOS, Mac, or CD-ROM.
SHORT_NAMES = NO
# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
# will interpret the first line (until the first dot) of a JavaDoc-style
# comment as the brief description. If set to NO, the JavaDoc
# comments will behave just like regular Qt-style comments
# (thus requiring an explicit @brief command for a brief description.)
JAVADOC_AUTOBRIEF = YES
# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
# interpret the first line (until the first dot) of a Qt-style
# comment as the brief description. If set to NO, the comments
# will behave just like regular Qt-style comments (thus requiring
# an explicit \brief command for a brief description.)
QT_AUTOBRIEF = NO
# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
# treat a multi-line C++ special comment block (i.e. a block of //! or ///
# comments) as a brief description. This used to be the default behaviour.
# The new default is to treat a multi-line C++ comment block as a detailed
# description. Set this tag to YES if you prefer the old behaviour instead.
MULTILINE_CPP_IS_BRIEF = NO
# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
# member inherits the documentation from any documented member that it
# re-implements.
INHERIT_DOCS = YES
# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
# a new page for each member. If set to NO, the documentation of a member will
# be part of the file/class/namespace that contains it.
SEPARATE_MEMBER_PAGES = NO
# The TAB_SIZE tag can be used to set the number of spaces in a tab.
# Doxygen uses this value to replace tabs by spaces in code fragments.
TAB_SIZE = 8
# This tag can be used to specify a number of aliases that acts
# as commands in the documentation. An alias has the form "name=value".
# For example adding "sideeffect=\par Side Effects:\n" will allow you to
# put the command \sideeffect (or @sideeffect) in the documentation, which
# will result in a user-defined paragraph with heading "Side Effects:".
# You can put \n's in the value part of an alias to insert newlines.
ALIASES =
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding
# "class=itcl::class" will allow you to use the command class in the
# itcl::class meaning.
TCL_SUBST =
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
# sources only. Doxygen will then generate output that is more tailored for C.
# For instance, some of the names that are used will be different. The list
# of all members will be omitted, etc.
OPTIMIZE_OUTPUT_FOR_C = YES
# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
# sources only. Doxygen will then generate output that is more tailored for
# Java. For instance, namespaces will be presented as packages, qualified
# scopes will look different, etc.
OPTIMIZE_OUTPUT_JAVA = NO
# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
# sources only. Doxygen will then generate output that is more tailored for
# Fortran.
OPTIMIZE_FOR_FORTRAN = NO
# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
# sources. Doxygen will then generate output that is tailored for
# VHDL.
OPTIMIZE_OUTPUT_VHDL = NO
# Doxygen selects the parser to use depending on the extension of the files it
# parses. With this tag you can assign which parser to use for a given extension.
# Doxygen has a built-in mapping, but you can override or extend it using this
# tag. The format is ext=language, where ext is a file extension, and language
# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C,
# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make
# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions
# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
EXTENSION_MAPPING =
# If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all
# comments according to the Markdown format, which allows for more readable
# documentation. See http://daringfireball.net/projects/markdown/ for details.
# The output of markdown processing is further processed by doxygen, so you
# can mix doxygen, HTML, and XML commands with Markdown formatting.
# Disable only in case of backward compatibilities issues.
MARKDOWN_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should
# set this tag to YES in order to let doxygen match functions declarations and
# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
# func(std::string) {}). This also makes the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate.
BUILTIN_STL_SUPPORT = NO
# If you use Microsoft's C++/CLI language, you should set this option to YES to
# enable parsing support.
CPP_CLI_SUPPORT = NO
# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only.
# Doxygen will parse them like normal C++ but will assume all classes use public
# instead of private inheritance when no explicit protection keyword is present.
SIP_SUPPORT = NO
# For Microsoft's IDL there are propget and propput attributes to indicate getter
# and setter methods for a property. Setting this option to YES (the default)
# will make doxygen replace the get and set methods by a property in the
# documentation. This will only work if the methods are indeed getting or
# setting a simple type. If this is not the case, or you want to show the
# methods anyway, you should set this option to NO.
IDL_PROPERTY_SUPPORT = YES
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
DISTRIBUTE_GROUP_DOC = NO
# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
# the same type (for instance a group of public functions) to be put as a
# subgroup of that type (e.g. under the Public Functions section). Set it to
# NO to prevent subgrouping. Alternatively, this can be done per class using
# the \nosubgrouping command.
SUBGROUPING = YES
# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and
# unions are shown inside the group in which they are included (e.g. using
# @ingroup) instead of on a separate page (for HTML and Man pages) or
# section (for LaTeX and RTF).
INLINE_GROUPED_CLASSES = NO
# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and
# unions with only public data fields will be shown inline in the documentation
# of the scope in which they are defined (i.e. file, namespace, or group
# documentation), provided this scope is documented. If set to NO (the default),
# structs, classes, and unions are shown on a separate page (for HTML and Man
# pages) or section (for LaTeX and RTF).
INLINE_SIMPLE_STRUCTS = NO
# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
# is documented as struct, union, or enum with the name of the typedef. So
# typedef struct TypeS {} TypeT, will appear in the documentation as a struct
# with name TypeT. When disabled the typedef will appear as a member of a file,
# namespace, or class. And the struct will be named TypeS. This can typically
# be useful for C code in case the coding convention dictates that all compound
# types are typedef'ed and only the typedef is referenced, never the tag name.
TYPEDEF_HIDES_STRUCT = NO
# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to
# determine which symbols to keep in memory and which to flush to disk.
# When the cache is full, less often used symbols will be written to disk.
# For small to medium size projects (<1000 input files) the default value is
# probably good enough. For larger projects a too small cache size can cause
# doxygen to be busy swapping symbols to and from disk most of the time
# causing a significant performance penalty.
# If the system has enough physical memory increasing the cache will improve the
# performance by keeping more symbols in memory. Note that the value works on
# a logarithmic scale so increasing the size by one will roughly double the
# memory usage. The cache size is given by this formula:
# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
# corresponding to a cache size of 2^16 = 65536 symbols.
SYMBOL_CACHE_SIZE = 0
# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
# their name and scope. Since this can be an expensive process and often the
# same symbol appear multiple times in the code, doxygen keeps a cache of
# pre-resolved symbols. If the cache is too small doxygen will become slower.
# If the cache is too large, memory is wasted. The cache size is given by this
# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0,
# corresponding to a cache size of 2^16 = 65536 symbols.
LOOKUP_CACHE_SIZE = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
# will be included in the documentation.
EXTRACT_PRIVATE = NO
# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal scope will be included in the documentation.
EXTRACT_PACKAGE = NO
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
EXTRACT_STATIC = NO
# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
# defined locally in source files will be included in the documentation.
# If set to NO only classes defined in header files are included.
EXTRACT_LOCAL_CLASSES = NO
# This flag is only useful for Objective-C code. When set to YES local
# methods, which are defined in the implementation section but not in
# the interface are included in the documentation.
# If set to NO (the default) only methods in the interface are included.
EXTRACT_LOCAL_METHODS = NO
# If this flag is set to YES, the members of anonymous namespaces will be
# extracted and appear in the documentation as a namespace called
# 'anonymous_namespace{file}', where file will be replaced with the base
# name of the file that contains the anonymous namespace. By default
# anonymous namespaces are hidden.
EXTRACT_ANON_NSPACES = NO
# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
# undocumented members of documented classes, files or namespaces.
# If set to NO (the default) these members will be included in the
# various overviews, but no documentation section is generated.
# This option has no effect if EXTRACT_ALL is enabled.
HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy.
# If set to NO (the default) these classes will be included in the various
# overviews. This option has no effect if EXTRACT_ALL is enabled.
HIDE_UNDOC_CLASSES = YES
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
# friend (class|struct|union) declarations.
# If set to NO (the default) these declarations will be included in the
# documentation.
HIDE_FRIEND_COMPOUNDS = NO
# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
# documentation blocks found inside the body of a function.
# If set to NO (the default) these blocks will be appended to the
# function's detailed documentation block.
HIDE_IN_BODY_DOCS = NO
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
# to NO (the default) then the documentation will be excluded.
# Set it to YES to include the internal documentation.
INTERNAL_DOCS = NO
# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
# file names in lower-case letters. If set to YES upper-case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO.
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
# will show members with their full class and namespace scopes in the
# documentation. If set to YES the scope will be hidden.
HIDE_SCOPE_NAMES = NO
# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
# will put a list of the files that are included by a file in the documentation
# of that file.
SHOW_INCLUDE_FILES = YES
# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen
# will list include files with double quotes in the documentation
# rather than with sharp brackets.
FORCE_LOCAL_INCLUDES = NO
# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
# is inserted in the documentation for inline members.
INLINE_INFO = YES
# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
# will sort the (detailed) documentation of file and class members
# alphabetically by member name. If set to NO the members will appear in
# declaration order.
SORT_MEMBER_DOCS = YES
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
# brief documentation of file, namespace and class members alphabetically
# by member name. If set to NO (the default) the members will appear in
# declaration order.
SORT_BRIEF_DOCS = NO
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
# will sort the (brief and detailed) documentation of class members so that
# constructors and destructors are listed first. If set to NO (the default)
# the constructors will appear in the respective orders defined by
# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS.
# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO
# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO.
SORT_MEMBERS_CTORS_1ST = NO
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
# hierarchy of group names into alphabetical order. If set to NO (the default)
# the group names will appear in their defined order.
SORT_GROUP_NAMES = NO
# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
# sorted by fully-qualified names, including namespaces. If set to
# NO (the default), the class list will be sorted only by class name,
# not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
# Note: This option applies only to the class list, not to the
# alphabetical list.
SORT_BY_SCOPE_NAME = NO
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to
# do proper type resolution of all parameters of a function it will reject a
# match between the prototype and the implementation of a member function even
# if there is only one candidate or it is obvious which candidate to choose
# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen
# will still accept a match between prototype and implementation in such cases.
STRICT_PROTO_MATCHING = NO
# The GENERATE_TODOLIST tag can be used to enable (YES) or
# disable (NO) the todo list. This list is created by putting \todo
# commands in the documentation.
GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or
# disable (NO) the test list. This list is created by putting \test
# commands in the documentation.
GENERATE_TESTLIST = YES
# The GENERATE_BUGLIST tag can be used to enable (YES) or
# disable (NO) the bug list. This list is created by putting \bug
# commands in the documentation.
GENERATE_BUGLIST = YES
# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
# disable (NO) the deprecated list. This list is created by putting
# \deprecated commands in the documentation.
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
ENABLED_SECTIONS =
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
# the initial value of a variable or macro consists of for it to appear in
# the documentation. If the initializer consists of more lines than specified
# here it will be hidden. Use a value of 0 to hide initializers completely.
# The appearance of the initializer of individual variables and macros in the
# documentation can be controlled using \showinitializer or \hideinitializer
# command in the documentation regardless of this setting.
MAX_INITIALIZER_LINES = 30
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
# at the bottom of the documentation of classes and structs. If set to YES the
# list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
# This will remove the Files entry from the Quick Index and from the
# Folder Tree View (if specified). The default is YES.
SHOW_FILES = YES
# Set the SHOW_NAMESPACES tag to NO to disable the generation of the
# Namespaces page.
# This will remove the Namespaces entry from the Quick Index
# and from the Folder Tree View (if specified). The default is YES.
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
# the version control system). Doxygen will invoke the program by executing (via
# popen()) the command talloc_set_destructor()for details on destructors.
talloc_reference()for details on establishing additional parents.
talloc_unlink().
talloc_unlink().
talloc_report_depth_cb(),
talloc_report_depth_file(),
talloc_report()
talloc_report()and
talloc_report_full()for details. Also see
talloc_enable_leak_report()and
talloc_enable_leak_report_full().
talloc_set_name()for details.
talloc_reference()).
talloc_reparent(). See the talloc_set_log_fn() documentation for more information on talloc logging.
TALLOC_FREE_FILL environment variable is set,
* the memory occupied by the context is filled with the value of this variable.
* The value should be a numeric representation of the character you want to
* use.
*
* talloc_free() operates recursively on its children.
*
* @param[in] ptr The chunk to be freed.
*
* @return Returns 0 on success and -1 on error. A possible
* failure condition is if the pointer had a destructor
* attached to it and the destructor returned -1. Likewise,
* if "ptr" is NULL, then the function will make no
* modifications and returns -1.
*
* Example:
* @code
* unsigned int *a, *b;
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
*
* talloc_free(a); // Frees a and b
* @endcode
*
* @see talloc_set_destructor()
* @see talloc_unlink()
*/
_PUBLIC_ int talloc_free(void *ptr);
#else
#define talloc_free(ctx) _talloc_free(ctx, __location__)
_PUBLIC_ int _talloc_free(void *ptr, const char *location);
#endif
/**
* @brief Free a talloc chunk's children.
*
* The function walks along the list of all children of a talloc context and
* talloc_free()s only the children, not the context itself.
*
* A NULL argument is handled as no-op.
*
* @param[in] ptr The chunk that you want to free the children of
* (NULL is allowed too)
*/
_PUBLIC_ void talloc_free_children(void *ptr);
#ifdef DOXYGEN
/**
* @brief Assign a destructor function to be called when a chunk is freed.
*
* 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.
*
* @param[in] ptr The talloc chunk to add a destructor to.
*
* @param[in] destructor The destructor function to be called. NULL to remove
* it.
*
* Example:
* @code
* 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;
* }
* @endcode
*
* @see talloc()
* @see talloc_free()
*/
_PUBLIC_ void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
/**
* @brief Change a talloc chunk's parent.
*
* 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.
*
* To make the changed hierarchy less error-prone, you might consider to use
* talloc_move().
*
* 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:
*
* @code
* 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
* @endcode
*
* 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.
*
* @param[in] new_ctx The new parent context.
*
* @param[in] ptr The talloc chunk to move.
*
* @return 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.
*/
_PUBLIC_ void *talloc_steal(const void *new_ctx, const void *ptr);
#else /* DOXYGEN */
/* try to make talloc_set_destructor() and talloc_steal() type safe,
if we have a recent gcc */
#if (__GNUC__ >= 3)
#define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
#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_loc((ctx),(ptr), __location__); __talloc_steal_ret; })
#else /* __GNUC__ >= 3 */
#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_loc((ctx),(ptr), __location__)
#endif /* __GNUC__ >= 3 */
_PUBLIC_ void _talloc_set_destructor(const void *ptr, int (*_destructor)(void *));
_PUBLIC_ void *_talloc_steal_loc(const void *new_ctx, const void *ptr, const char *location);
#endif /* DOXYGEN */
/**
* @brief Assign a name to a talloc chunk.
*
* Each talloc pointer has a "name". The name is used principally for
* debugging purposes, although it is also possible to set and get the name on
* a pointer in as a way of "marking" pointers in your code.
*
* The main use for names on pointer is for "talloc reports". See
* talloc_report() and talloc_report_full() for details. Also see
* talloc_enable_leak_report() and talloc_enable_leak_report_full().
*
* The talloc_set_name() function allocates memory as a child of the
* pointer. It is logically equivalent to:
*
* @code
* talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
* @endcode
*
* @param[in] ptr The talloc chunk to assign a name to.
*
* @param[in] fmt Format string for the name.
*
* @param[in] ... Add printf-style additional arguments.
*
* @return The assigned name, NULL on error.
*
* @note 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().
*/
_PUBLIC_ const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
#ifdef DOXYGEN
/**
* @brief Change a talloc chunk's parent.
*
* This function has the same effect as talloc_steal(), and additionally sets
* the source pointer to NULL. You would use it like this:
*
* @code
* struct foo *X = talloc(tmp_ctx, struct foo);
* struct foo *Y;
* Y = talloc_move(new_ctx, &X);
* @endcode
*
* @param[in] new_ctx The new parent context.
*
* @param[in] pptr Pointer to a pointer to the talloc chunk to move.
*
* @return The pointer to the talloc chunk that moved.
* It does not have any failure modes.
*
*/
_PUBLIC_ void *talloc_move(const void *new_ctx, void **pptr);
#else
#define talloc_move(ctx, pptr) (_TALLOC_TYPEOF(*(pptr)))_talloc_move((ctx),(void *)(pptr))
_PUBLIC_ void *_talloc_move(const void *new_ctx, const void *pptr);
#endif
/**
* @brief Assign a name to a talloc chunk.
*
* The function is just like talloc_set_name(), but it takes a string constant,
* and is much faster. It is extensively used by the "auto naming" macros, such
* as talloc_p().
*
* This function does not allocate any memory. It just copies the supplied
* pointer into the internal representation of the talloc ptr. This means you
* must not pass a name pointer to memory that will disappear before the ptr
* is freed with talloc_free().
*
* @param[in] ptr The talloc chunk to assign a name to.
*
* @param[in] name Format string for the name.
*/
_PUBLIC_ void talloc_set_name_const(const void *ptr, const char *name);
/**
* @brief Create a named talloc chunk.
*
* The talloc_named() function creates a named talloc pointer. It is
* equivalent to:
*
* @code
* ptr = talloc_size(context, size);
* talloc_set_name(ptr, fmt, ....);
* @endcode
*
* @param[in] context The talloc context to hang the result off.
*
* @param[in] size Number of char's that you want to allocate.
*
* @param[in] fmt Format string for the name.
*
* @param[in] ... Additional printf-style arguments.
*
* @return The allocated memory chunk, NULL on error.
*
* @see talloc_set_name()
*/
_PUBLIC_ void *talloc_named(const void *context, size_t size,
const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
/**
* @brief Basic routine to allocate a chunk of memory.
*
* This is equivalent to:
*
* @code
* ptr = talloc_size(context, size);
* talloc_set_name_const(ptr, name);
* @endcode
*
* @param[in] context The parent context.
*
* @param[in] size The number of char's that we want to allocate.
*
* @param[in] name The name the talloc block has.
*
* @return The allocated memory chunk, NULL on error.
*/
_PUBLIC_ void *talloc_named_const(const void *context, size_t size, const char *name);
#ifdef DOXYGEN
/**
* @brief Untyped allocation.
*
* The function 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.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] size Number of char's that you want to allocate.
*
* @return The allocated memory chunk, NULL on error.
*
* Example:
* @code
* void *mem = talloc_size(NULL, 100);
* @endcode
*/
_PUBLIC_ void *talloc_size(const void *ctx, size_t size);
#else
#define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Allocate into a typed pointer.
*
* 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.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] type The pointer you want to assign the result to.
*
* @return The properly casted allocated memory chunk, NULL on
* error.
*
* Example:
* @code
* unsigned int *a = talloc_ptrtype(NULL, a);
* @endcode
*/
_PUBLIC_ void *talloc_ptrtype(const void *ctx, #type);
#else
#define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
#endif
#ifdef DOXYGEN
/**
* @brief Allocate a new 0-sized talloc chunk.
*
* This is a utility macro that creates a new memory context hanging off an
* existing 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.
*
* @param[in] ctx The talloc parent context.
*
* @return A new talloc chunk, NULL on error.
*/
_PUBLIC_ void *talloc_new(const void *ctx);
#else
#define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Allocate a 0-initizialized structure.
*
* The macro is equivalent to:
*
* @code
* ptr = talloc(ctx, type);
* if (ptr) memset(ptr, 0, sizeof(type));
* @endcode
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] type The type that we want to allocate.
*
* @return Pointer to a piece of memory, properly cast to 'type *',
* NULL on error.
*
* Example:
* @code
* unsigned int *a, *b;
* a = talloc_zero(NULL, unsigned int);
* b = talloc_zero(a, unsigned int);
* @endcode
*
* @see talloc()
* @see talloc_zero_size()
* @see talloc_zero_array()
*/
_PUBLIC_ void *talloc_zero(const void *ctx, #type);
/**
* @brief Allocate untyped, 0-initialized memory.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] size Number of char's that you want to allocate.
*
* @return The allocated memory chunk.
*/
_PUBLIC_ void *talloc_zero_size(const void *ctx, size_t size);
#else
#define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
#define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
_PUBLIC_ void *_talloc_zero(const void *ctx, size_t size, const char *name);
#endif
/**
* @brief Return the name of a talloc chunk.
*
* @param[in] ptr The talloc chunk.
*
* @return The current name for the given talloc pointer.
*
* @see talloc_set_name()
*/
_PUBLIC_ const char *talloc_get_name(const void *ptr);
/**
* @brief Verify that a talloc chunk carries a specified name.
*
* This function checks if a pointer has the specified name. If it does
* then the pointer is returned.
*
* @param[in] ptr The talloc chunk to check.
*
* @param[in] name The name to check against.
*
* @return The pointer if the name matches, NULL if it doesn't.
*/
_PUBLIC_ void *talloc_check_name(const void *ptr, const char *name);
/**
* @brief Get the parent chunk of a pointer.
*
* @param[in] ptr The talloc pointer to inspect.
*
* @return The talloc parent of ptr, NULL on error.
*/
_PUBLIC_ void *talloc_parent(const void *ptr);
/**
* @brief Get a talloc chunk's parent name.
*
* @param[in] ptr The talloc pointer to inspect.
*
* @return The name of ptr's parent chunk.
*/
_PUBLIC_ const char *talloc_parent_name(const void *ptr);
/**
* @brief Get the size of a talloc chunk.
*
* This function lets you know the amount of memory allocated so far by
* this context. It does NOT account for subcontext memory.
* This can be used to calculate the size of an array.
*
* @param[in] ctx The talloc chunk.
*
* @return The size of the talloc chunk.
*/
_PUBLIC_ size_t talloc_get_size(const void *ctx);
/**
* @brief Get the total size of a talloc chunk including its children.
*
* The 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.
*
* @param[in] ptr The talloc chunk.
*
* @return The total size.
*/
_PUBLIC_ size_t talloc_total_size(const void *ptr);
/**
* @brief Get the number of talloc chunks hanging off a chunk.
*
* The talloc_total_blocks() function returns the total memory block
* count used by this pointer and all child pointers. Mostly useful for
* debugging.
*
* Passing NULL is allowed, but it will only give a meaningful result if
* talloc_enable_leak_report() or talloc_enable_leak_report_full() has
* been called.
*
* @param[in] ptr The talloc chunk.
*
* @return The total size.
*/
_PUBLIC_ size_t talloc_total_blocks(const void *ptr);
#ifdef DOXYGEN
/**
* @brief Duplicate a memory area into a talloc chunk.
*
* The function is equivalent to:
*
* @code
* ptr = talloc_size(ctx, size);
* if (ptr) memcpy(ptr, p, size);
* @endcode
*
* @param[in] t The talloc context to hang the result off.
*
* @param[in] p The memory chunk you want to duplicate.
*
* @param[in] size Number of chars that you want to copy.
*
* @return The allocated memory chunk.
*
* @see talloc_size()
*/
_PUBLIC_ void *talloc_memdup(const void *t, const void *p, size_t size);
#else
#define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
_PUBLIC_ void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
#endif
#ifdef DOXYGEN
/**
* @brief Assign a type to a talloc chunk.
*
* This macro allows you to force the name of a pointer to be of a particular
* type. This can be used in conjunction with talloc_get_type() to do type
* checking on void* pointers.
*
* It is equivalent to this:
*
* @code
* talloc_set_name_const(ptr, #type)
* @endcode
*
* @param[in] ptr The talloc chunk to assign the type to.
*
* @param[in] type The type to assign.
*/
_PUBLIC_ void talloc_set_type(const char *ptr, #type);
/**
* @brief Get a typed pointer out of a talloc pointer.
*
* This macro allows you to do type checking on talloc pointers. It is
* particularly useful for void* private pointers. It is equivalent to
* this:
*
* @code
* (type *)talloc_check_name(ptr, #type)
* @endcode
*
* @param[in] ptr The talloc pointer to check.
*
* @param[in] type The type to check against.
*
* @return The properly casted pointer given by ptr, NULL on error.
*/
type *talloc_get_type(const void *ptr, #type);
#else
#define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
#define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
#endif
#ifdef DOXYGEN
/**
* @brief Safely turn a void pointer into a typed pointer.
*
* This macro is used together with talloc(mem_ctx, struct foo). If you had to
* assign the talloc chunk pointer to some void pointer variable,
* talloc_get_type_abort() is the recommended way to convert the void
* pointer back to a typed pointer.
*
* @param[in] ptr The void pointer to convert.
*
* @param[in] type The type that this chunk contains
*
* @return The same value as ptr, type-checked and properly cast.
*/
_PUBLIC_ void *talloc_get_type_abort(const void *ptr, #type);
#else
#ifdef TALLOC_GET_TYPE_ABORT_NOOP
#define talloc_get_type_abort(ptr, type) (type *)(ptr)
#else
#define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
#endif
_PUBLIC_ void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location);
#endif
/**
* @brief Find a parent context by name.
*
* Find a parent memory context of the current context that has the given
* name. This can be very useful in complex programs where it may be
* difficult to pass all information down to the level you need, but you
* know the structure you want is a parent of another context.
*
* @param[in] ctx The talloc chunk to start from.
*
* @param[in] name The name of the parent we look for.
*
* @return The memory context we are looking for, NULL if not
* found.
*/
_PUBLIC_ void *talloc_find_parent_byname(const void *ctx, const char *name);
#ifdef DOXYGEN
/**
* @brief Find a parent context by type.
*
* Find a parent memory context of the current context that has the given
* name. This can be very useful in complex programs where it may be
* difficult to pass all information down to the level you need, but you
* know the structure you want is a parent of another context.
*
* Like talloc_find_parent_byname() but takes a type, making it typesafe.
*
* @param[in] ptr The talloc chunk to start from.
*
* @param[in] type The type of the parent to look for.
*
* @return The memory context we are looking for, NULL if not
* found.
*/
_PUBLIC_ void *talloc_find_parent_bytype(const void *ptr, #type);
#else
#define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
#endif
/**
* @brief Allocate a talloc pool.
*
* A talloc pool is a pure optimization for specific situations. In the
* release process for Samba 3.2 we found out that we had become considerably
* slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU
* consumer in benchmarks. For Samba 3.2 we have internally converted many
* static buffers to dynamically allocated ones, so malloc(3) being beaten
* more was no surprise. But it made us slower.
*
* talloc_pool() is an optimization to call malloc(3) a lot less for the use
* pattern Samba has: The SMB protocol is mainly a request/response protocol
* where we have to allocate a certain amount of memory per request and free
* that after the SMB reply is sent to the client.
*
* talloc_pool() creates a talloc chunk that you can use as a talloc parent
* exactly as you would use any other ::TALLOC_CTX. The difference is that
* when you talloc a child of this pool, no malloc(3) is done. Instead, talloc
* just increments a pointer inside the talloc_pool. This also works
* recursively. If you use the child of the talloc pool as a parent for
* grand-children, their memory is also taken from the talloc pool.
*
* If there is not enough memory in the pool to allocate the new child,
* it will create a new talloc chunk as if the parent was a normal talloc
* context.
*
* If you talloc_free() children of a talloc pool, the memory is not given
* back to the system. Instead, free(3) is only called if the talloc_pool()
* itself is released with talloc_free().
*
* The downside of a talloc pool is that if you talloc_move() a child of a
* talloc pool to a talloc parent outside the pool, the whole pool memory is
* not free(3)'ed until that moved chunk is also talloc_free()ed.
*
* @param[in] context The talloc context to hang the result off.
*
* @param[in] size Size of the talloc pool.
*
* @return The allocated talloc pool, NULL on error.
*/
_PUBLIC_ void *talloc_pool(const void *context, size_t size);
#ifdef DOXYGEN
/**
* @brief Allocate a talloc object as/with an additional pool.
*
* This is like talloc_pool(), but's it's more flexible
* and allows an object to be a pool for its children.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] type The type that we want to allocate.
*
* @param[in] num_subobjects The expected number of subobjects, which will
* be allocated within the pool. This allocates
* space for talloc_chunk headers.
*
* @param[in] total_subobjects_size The size that all subobjects can use in total.
*
*
* @return The allocated talloc object, NULL on error.
*/
_PUBLIC_ void *talloc_pooled_object(const void *ctx, #type,
unsigned num_subobjects,
size_t total_subobjects_size);
#else
#define talloc_pooled_object(_ctx, _type, \
_num_subobjects, \
_total_subobjects_size) \
(_type *)_talloc_pooled_object((_ctx), sizeof(_type), #_type, \
(_num_subobjects), \
(_total_subobjects_size))
_PUBLIC_ void *_talloc_pooled_object(const void *ctx,
size_t type_size,
const char *type_name,
unsigned num_subobjects,
size_t total_subobjects_size);
#endif
/**
* @brief Free a talloc chunk and NULL out the pointer.
*
* TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want
* immediate feedback (i.e. crash) if you use a pointer after having free'ed
* it.
*
* @param[in] ctx The chunk to be freed.
*/
#define TALLOC_FREE(ctx) do { if (ctx != NULL) { talloc_free(ctx); ctx=NULL; } } while(0)
/* @} ******************************************************************/
/**
* \defgroup talloc_ref The talloc reference function.
* @ingroup talloc
*
* This module contains the definitions around talloc references
*
* @{
*/
/**
* @brief Increase the reference count of a talloc chunk.
*
* The talloc_increase_ref_count(ptr) function is exactly equivalent to:
*
* @code
* talloc_reference(NULL, ptr);
* @endcode
*
* You can use either syntax, depending on which you think is clearer in
* your code.
*
* @param[in] ptr The pointer to increase the reference count.
*
* @return 0 on success, -1 on error.
*/
_PUBLIC_ int talloc_increase_ref_count(const void *ptr);
/**
* @brief Get the number of references to a talloc chunk.
*
* @param[in] ptr The pointer to retrieve the reference count from.
*
* @return The number of references.
*/
_PUBLIC_ size_t talloc_reference_count(const void *ptr);
#ifdef DOXYGEN
/**
* @brief Create an additional talloc parent to a pointer.
*
* The talloc_reference() function makes "context" an additional parent of
* ptr. 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 if it has at maximum one
* parent. This behaviour has been changed since the release of version
* 2.0. Further information in the description of "talloc_free".
*
* For more control on which parent to remove, see talloc_unlink()
* @param[in] ctx The additional parent.
*
* @param[in] ptr The pointer you want to create an additional parent for.
*
* @return The original pointer 'ptr', NULL if talloc ran out of
* memory in creating the reference.
*
* @warning You should try to avoid using this interface. It turns a beautiful
* talloc-tree into a graph. It is often really hard to debug if you
* screw something up by accident.
*
* Example:
* @code
* 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);
* @endcode
*
* @see talloc_unlink()
*/
_PUBLIC_ void *talloc_reference(const void *ctx, const void *ptr);
#else
#define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference_loc((ctx),(ptr), __location__)
_PUBLIC_ void *_talloc_reference_loc(const void *context, const void *ptr, const char *location);
#endif
/**
* @brief Remove a specific parent from a talloc chunk.
*
* The 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.
*
* You can just use talloc_free() instead of talloc_unlink() if there
* is at maximum one parent. This behaviour has been changed since the
* release of version 2.0. Further information in the description of
* "talloc_free".
*
* @param[in] context The talloc parent to remove.
*
* @param[in] ptr The talloc ptr you want to remove the parent from.
*
* @return 0 on success, -1 on error.
*
* @note 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.
*
* @warning You should try to avoid using this interface. It turns a beautiful
* talloc-tree into a graph. It is often really hard to debug if you
* screw something up by accident.
*
* Example:
* @code
* 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);
* @endcode
*/
_PUBLIC_ int talloc_unlink(const void *context, void *ptr);
/**
* @brief Provide a talloc context that is freed at program 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.
*
* Never use this in code that might be used in objects loaded with
* dlopen and unloaded with dlclose. talloc_autofree_context()
* internally uses atexit(3). Some platforms like modern Linux handles
* this fine, but for example FreeBSD does not deal well with dlopen()
* and atexit() used simultaneously: dlclose() does not clean up the
* list of atexit-handlers, so when the program exits the code that
* was registered from within talloc_autofree_context() is gone, the
* program crashes at exit.
*
* @return A talloc context, NULL on error.
*/
_PUBLIC_ void *talloc_autofree_context(void) _DEPRECATED_;
/**
* @brief Show the parentage of a context.
*
* @param[in] context The talloc context to look at.
*
* @param[in] file The output to use, a file, stdout or stderr.
*/
_PUBLIC_ void talloc_show_parents(const void *context, FILE *file);
/**
* @brief Check if a context is parent of a talloc chunk.
*
* This checks if context is referenced in the talloc hierarchy above ptr.
*
* @param[in] context The assumed talloc context.
*
* @param[in] ptr The talloc chunk to check.
*
* @return Return 1 if this is the case, 0 if not.
*/
_PUBLIC_ int talloc_is_parent(const void *context, const void *ptr);
/**
* @brief Change the parent context of a talloc pointer.
*
* The 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 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.
*
* @param[in] old_parent
* @param[in] new_parent
* @param[in] ptr
*
* @return Return the pointer you passed. It does not have any
* failure modes.
*/
_PUBLIC_ void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
/* @} ******************************************************************/
/**
* @defgroup talloc_array The talloc array functions
* @ingroup talloc
*
* Talloc contains some handy helpers for handling Arrays conveniently
*
* @{
*/
#ifdef DOXYGEN
/**
* @brief Allocate an array.
*
* The macro is equivalent to:
*
* @code
* (type *)talloc_size(ctx, sizeof(type) * count);
* @endcode
*
* except that it provides integer overflow protection for the multiply,
* returning NULL if the multiply overflows.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] type The type that we want to allocate.
*
* @param[in] count The number of 'type' elements you want to allocate.
*
* @return The allocated result, properly cast to 'type *', NULL on
* error.
*
* Example:
* @code
* unsigned int *a, *b;
* a = talloc_zero(NULL, unsigned int);
* b = talloc_array(a, unsigned int, 100);
* @endcode
*
* @see talloc()
* @see talloc_zero_array()
*/
_PUBLIC_ void *talloc_array(const void *ctx, #type, unsigned count);
#else
#define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
_PUBLIC_ void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
#endif
#ifdef DOXYGEN
/**
* @brief Allocate an array.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] size The size of an array element.
*
* @param[in] count The number of elements you want to allocate.
*
* @return The allocated result, NULL on error.
*/
_PUBLIC_ void *talloc_array_size(const void *ctx, size_t size, unsigned count);
#else
#define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Allocate an array into a typed pointer.
*
* The macro should be used when you have a pointer to an array and want to
* allocate memory of an array to point at with this pointer. When compiling
* with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
* and talloc_get_name() will return the current location in the source file
* and not the type.
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] ptr The pointer you want to assign the result to.
*
* @param[in] count The number of elements you want to allocate.
*
* @return The allocated memory chunk, properly casted. NULL on
* error.
*/
void *talloc_array_ptrtype(const void *ctx, const void *ptr, unsigned count);
#else
#define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
#endif
#ifdef DOXYGEN
/**
* @brief Get the number of elements in a talloc'ed array.
*
* A talloc chunk carries its own size, so for talloc'ed arrays it is not
* necessary to store the number of elements explicitly.
*
* @param[in] ctx The allocated array.
*
* @return The number of elements in ctx.
*/
size_t talloc_array_length(const void *ctx);
#else
#define talloc_array_length(ctx) (talloc_get_size(ctx)/sizeof(*ctx))
#endif
#ifdef DOXYGEN
/**
* @brief Allocate a zero-initialized array
*
* @param[in] ctx The talloc context to hang the result off.
*
* @param[in] type The type that we want to allocate.
*
* @param[in] count The number of "type" elements you want to allocate.
*
* @return The allocated result casted to "type *", NULL on error.
*
* The talloc_zero_array() macro is equivalent to:
*
* @code
* ptr = talloc_array(ctx, type, count);
* if (ptr) memset(ptr, 0, sizeof(type) * count);
* @endcode
*/
void *talloc_zero_array(const void *ctx, #type, unsigned count);
#else
#define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
_PUBLIC_ void *_talloc_zero_array(const void *ctx,
size_t el_size,
unsigned count,
const char *name);
#endif
#ifdef DOXYGEN
/**
* @brief Change the size of a talloc array.
*
* The macro changes the size of a talloc pointer. The 'count' argument is the
* number of elements of type 'type' that you want the resulting pointer to
* hold.
*
* talloc_realloc() has the following equivalences:
*
* @code
* talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
* talloc_realloc(ctx, NULL, type, N) ==> talloc_array(ctx, type, N);
* talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);
* @endcode
*
* The "context" argument is only used if "ptr" is NULL, otherwise it is
* ignored.
*
* @param[in] ctx The parent context used if ptr is NULL.
*
* @param[in] ptr The chunk to be resized.
*
* @param[in] type The type of the array element inside ptr.
*
* @param[in] count The intended number of array elements.
*
* @return The new array, NULL on error. The call will fail either
* due to a lack of memory, or because the pointer has more
* than one parent (see talloc_reference()).
*/
_PUBLIC_ void *talloc_realloc(const void *ctx, void *ptr, #type, size_t count);
#else
#define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
_PUBLIC_ void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
#endif
#ifdef DOXYGEN
/**
* @brief Untyped realloc to change the size of a talloc array.
*
* The macro is useful when the type is not known so the typesafe
* talloc_realloc() cannot be used.
*
* @param[in] ctx The parent context used if 'ptr' is NULL.
*
* @param[in] ptr The chunk to be resized.
*
* @param[in] size The new chunk size.
*
* @return The new array, NULL on error.
*/
void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);
#else
#define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
_PUBLIC_ void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
#endif
/**
* @brief Provide a function version of talloc_realloc_size.
*
* This is a non-macro version of talloc_realloc(), which is useful as
* libraries sometimes want a ralloc function pointer. A realloc()
* implementation encapsulates the functionality of malloc(), free() and
* realloc() in one call, which is why it is useful to be able to pass around
* a single function pointer.
*
* @param[in] context The parent context used if ptr is NULL.
*
* @param[in] ptr The chunk to be resized.
*
* @param[in] size The new chunk size.
*
* @return The new chunk, NULL on error.
*/
_PUBLIC_ void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
/* @} ******************************************************************/
/**
* @defgroup talloc_string The talloc string functions.
* @ingroup talloc
*
* talloc string allocation and manipulation functions.
* @{
*/
/**
* @brief Duplicate a string into a talloc chunk.
*
* This function is equivalent to:
*
* @code
* ptr = talloc_size(ctx, strlen(p)+1);
* if (ptr) memcpy(ptr, p, strlen(p)+1);
* @endcode
*
* This functions sets the name of the new pointer to the passed
* string. This is equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* @param[in] t The talloc context to hang the result off.
*
* @param[in] p The string you want to duplicate.
*
* @return The duplicated string, NULL on error.
*/
_PUBLIC_ char *talloc_strdup(const void *t, const char *p);
/**
* @brief Append a string to given string.
*
* The destination string is reallocated to take
* strlen(s) + strlen(a) + 1 characters.
*
* This functions sets the name of the new pointer to the new
* string. This is equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The destination to append to.
*
* @param[in] a The string you want to append.
*
* @return The concatenated strings, NULL on error.
*
* @see talloc_strdup()
* @see talloc_strdup_append_buffer()
*/
_PUBLIC_ char *talloc_strdup_append(char *s, const char *a);
/**
* @brief Append a string to a given buffer.
*
* This is a more efficient version of talloc_strdup_append(). It determines the
* length of the destination string by the size of the talloc context.
*
* Use this very carefully as it produces a different result than
* talloc_strdup_append() when a zero character is in the middle of the
* destination string.
*
* @code
* char *str_a = talloc_strdup(NULL, "hello world");
* char *str_b = talloc_strdup(NULL, "hello world");
* str_a[5] = str_b[5] = '\0'
*
* char *app = talloc_strdup_append(str_a, ", hello");
* char *buf = talloc_strdup_append_buffer(str_b, ", hello");
*
* printf("%s\n", app); // hello, hello (app = "hello, hello")
* printf("%s\n", buf); // hello (buf = "hello\0world, hello")
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The destination buffer to append to.
*
* @param[in] a The string you want to append.
*
* @return The concatenated strings, NULL on error.
*
* @see talloc_strdup()
* @see talloc_strdup_append()
* @see talloc_array_length()
*/
_PUBLIC_ char *talloc_strdup_append_buffer(char *s, const char *a);
/**
* @brief Duplicate a length-limited string into a talloc chunk.
*
* This function is the talloc equivalent of the C library function strndup(3).
*
* This functions sets the name of the new pointer to the passed string. This is
* equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* @param[in] t The talloc context to hang the result off.
*
* @param[in] p The string you want to duplicate.
*
* @param[in] n The maximum string length to duplicate.
*
* @return The duplicated string, NULL on error.
*/
_PUBLIC_ char *talloc_strndup(const void *t, const char *p, size_t n);
/**
* @brief Append at most n characters of a string to given string.
*
* The destination string is reallocated to take
* strlen(s) + strnlen(a, n) + 1 characters.
*
* This functions sets the name of the new pointer to the new
* string. This is equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The destination string to append to.
*
* @param[in] a The source string you want to append.
*
* @param[in] n The number of characters you want to append from the
* string.
*
* @return The concatenated strings, NULL on error.
*
* @see talloc_strndup()
* @see talloc_strndup_append_buffer()
*/
_PUBLIC_ char *talloc_strndup_append(char *s, const char *a, size_t n);
/**
* @brief Append at most n characters of a string to given buffer
*
* This is a more efficient version of talloc_strndup_append(). It determines
* the length of the destination string by the size of the talloc context.
*
* Use this very carefully as it produces a different result than
* talloc_strndup_append() when a zero character is in the middle of the
* destination string.
*
* @code
* char *str_a = talloc_strdup(NULL, "hello world");
* char *str_b = talloc_strdup(NULL, "hello world");
* str_a[5] = str_b[5] = '\0'
*
* char *app = talloc_strndup_append(str_a, ", hello", 7);
* char *buf = talloc_strndup_append_buffer(str_b, ", hello", 7);
*
* printf("%s\n", app); // hello, hello (app = "hello, hello")
* printf("%s\n", buf); // hello (buf = "hello\0world, hello")
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The destination buffer to append to.
*
* @param[in] a The source string you want to append.
*
* @param[in] n The number of characters you want to append from the
* string.
*
* @return The concatenated strings, NULL on error.
*
* @see talloc_strndup()
* @see talloc_strndup_append()
* @see talloc_array_length()
*/
_PUBLIC_ char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
/**
* @brief Format a string given a va_list.
*
* This function is the talloc equivalent of the C library function
* vasprintf(3).
*
* This functions sets the name of the new pointer to the new string. This is
* equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* @param[in] t The talloc context to hang the result off.
*
* @param[in] fmt The format string.
*
* @param[in] ap The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*/
_PUBLIC_ char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
/**
* @brief Format a string given a va_list and append it to the given destination
* string.
*
* @param[in] s The destination string to append to.
*
* @param[in] fmt The format string.
*
* @param[in] ap The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*
* @see talloc_vasprintf()
*/
_PUBLIC_ char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
/**
* @brief Format a string given a va_list and append it to the given destination
* buffer.
*
* @param[in] s The destination buffer to append to.
*
* @param[in] fmt The format string.
*
* @param[in] ap The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*
* @see talloc_vasprintf()
*/
_PUBLIC_ char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
/**
* @brief Build up a string buffer, handle allocation failure
*
* @param[in] ps Pointer to the talloc'ed string to be extended
* @param[in] fmt The format string
* @param[in] ... The parameters used to fill fmt.
*
* This does nothing if *ps is NULL and sets *ps to NULL if the
* intermediate reallocation fails. Useful when building up a string
* step by step, no intermediate NULL checks are required.
*/
_PUBLIC_ void talloc_asprintf_addbuf(char **ps, const char *fmt, ...) \
PRINTF_ATTRIBUTE(2,3);
/**
* @brief Format a string.
*
* This function is the talloc equivalent of the C library function asprintf(3).
*
* This functions sets the name of the new pointer to the new string. This is
* equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* @param[in] t The talloc context to hang the result off.
*
* @param[in] fmt The format string.
*
* @param[in] ... The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*/
_PUBLIC_ char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
/**
* @brief Append a formatted string to another string.
*
* This function appends the given formatted string to the given string. Use
* this variant when the string in the current talloc buffer may have been
* truncated in length.
*
* This functions sets the name of the new pointer to the new
* string. This is equivalent to:
*
* @code
* talloc_set_name_const(ptr, ptr)
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The string to append to.
*
* @param[in] fmt The format string.
*
* @param[in] ... The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*/
_PUBLIC_ char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
/**
* @brief Append a formatted string to another string.
*
* This is a more efficient version of talloc_asprintf_append(). It determines
* the length of the destination string by the size of the talloc context.
*
* Use this very carefully as it produces a different result than
* talloc_asprintf_append() when a zero character is in the middle of the
* destination string.
*
* @code
* char *str_a = talloc_strdup(NULL, "hello world");
* char *str_b = talloc_strdup(NULL, "hello world");
* str_a[5] = str_b[5] = '\0'
*
* char *app = talloc_asprintf_append(str_a, "%s", ", hello");
* char *buf = talloc_strdup_append_buffer(str_b, "%s", ", hello");
*
* printf("%s\n", app); // hello, hello (app = "hello, hello")
* printf("%s\n", buf); // hello (buf = "hello\0world, hello")
* @endcode
*
* If s == NULL then new context is created.
*
* @param[in] s The string to append to
*
* @param[in] fmt The format string.
*
* @param[in] ... The parameters used to fill fmt.
*
* @return The formatted string, NULL on error.
*
* @see talloc_asprintf()
* @see talloc_asprintf_append()
*/
_PUBLIC_ char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
/* @} ******************************************************************/
/**
* @defgroup talloc_debug The talloc debugging support functions
* @ingroup talloc
*
* To aid memory debugging, talloc contains routines to inspect the currently
* allocated memory hierarchy.
*
* @{
*/
/**
* @brief Walk a complete talloc hierarchy.
*
* 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.
*
* @param[in] ptr The talloc chunk.
*
* @param[in] depth Internal parameter to control recursion. Call with 0.
*
* @param[in] max_depth Maximum recursion level.
*
* @param[in] callback Function to be called on every chunk.
*
* @param[in] private_data Private pointer passed to callback.
*/
_PUBLIC_ void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
void (*callback)(const void *ptr,
int depth, int max_depth,
int is_ref,
void *private_data),
void *private_data);
/**
* @brief Print a talloc hierarchy.
*
* This provides a more flexible reports than talloc_report(). It
* will let you specify the depth and max_depth.
*
* @param[in] ptr The talloc chunk.
*
* @param[in] depth Internal parameter to control recursion. Call with 0.
*
* @param[in] max_depth Maximum recursion level.
*
* @param[in] f The file handle to print to.
*/
_PUBLIC_ void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
/**
* @brief Print a summary report of all memory used by ptr.
*
* This provides a more detailed report than talloc_report(). It will
* 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_leak_report() or talloc_enable_leak_report_full() has
* been called.
*
* @param[in] ptr The talloc chunk.
*
* @param[in] f The file handle to print to.
*
* Example:
* @code
* 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);
* @endcode
*
* @see talloc_report()
*/
_PUBLIC_ void talloc_report_full(const void *ptr, FILE *f);
/**
* @brief Print a summary report of all memory used by ptr.
*
* This function prints a summary report of all memory used by ptr. One line of
* report is printed for each immediate child of ptr, showing the total memory
* and number of blocks used by that child.
*
* You can pass NULL for the pointer, in which case a report is printed
* for the top level memory context, but only if talloc_enable_leak_report()
* or talloc_enable_leak_report_full() has been called.
*
* @param[in] ptr The talloc chunk.
*
* @param[in] f The file handle to print to.
*
* Example:
* @code
* 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);
* @endcode
*
* @see talloc_report_full()
*/
_PUBLIC_ void talloc_report(const void *ptr, FILE *f);
/**
* @brief Enable tracking the use of NULL memory contexts.
*
* 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();
*/
_PUBLIC_ void talloc_enable_null_tracking(void);
/**
* @brief Enable tracking the use of NULL memory contexts.
*
* 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();
*/
_PUBLIC_ void talloc_enable_null_tracking_no_autofree(void);
/**
* @brief Disable tracking of the NULL memory context.
*
* This disables tracking of the NULL memory context.
*/
_PUBLIC_ void talloc_disable_null_tracking(void);
/**
* @brief Enable leak report when a program exits.
*
* 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:
*
* @code
* 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
* @endcode
*/
_PUBLIC_ void talloc_enable_leak_report(void);
/**
* @brief Enable full leak report when a program exits.
*
* 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:
*
* @code
* 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)
* @endcode
*/
_PUBLIC_ void talloc_enable_leak_report_full(void);
/**
* @brief Set a custom "abort" function that is called on serious error.
*
* The default "abort" function is abort().
*
* The "abort" function is called when:
*
* To get started with talloc, I would recommend you read the talloc guide.
rsync -Pavz samba.org::ftp/unpacked/standalone_projects/lib/talloc .