usual/talloc.h File Reference

Talloc - hierarchical memory allocator. More...

Defines
#define	TALLOC_POS(apifunc)
	Give name to "unnamed" allocations.
#define	TALLOC_FREE(ptr)
	Free and set pointer to NULL.
Typedefs
typedef void	TALLOC_CTX
	Type for untyped pointers that are usable as talloc parent.
typedef int(*	talloc_destructor_f )(void *ptr)
	Destructor signature.
Functions
Allocate object and give name based on C type.
Object names are set automatically based on C type.
type *	talloc (const void *parent,#type)
	Allocate memory for C type.
type *	talloc_zero (const void *parent,#type)
	Allocate zero-filled memory for C type.
type *	talloc_array (const void *parent,#type, size_t count)
	Allocate array of elements of type given.
type *	talloc_zero_array (const void *parent,#type, size_t count)
	Allocate zero-filled array of elements of type.
Allocate object and give custom name.
void *	talloc_named_const (const void *parent, size_t size, const char *name)
	Allocate named object.
void *	talloc_zero_named_const (const void *parent, size_t size, const char *name)
	Allocate zero-filled memory for named object.
void *	talloc_named (const void *parent, size_t size, const char *fmt,...)
	Allocate named context.
void *	talloc_init (const char *fmt,...)
	Allocate new top-level named context.
Allocate unnamed context.
The objects will get name based on calling location.
void *	talloc_size (const void *parent, size_t size)
	Allocate unnamed context.
void *	talloc_zero_size (const void *parent, size_t size)
	Allocate unnamed context with zeroed memory.
void *	talloc_array_size (const void *parent, size_t size, size_t count)
	Allocate array of elements of type.
type *	talloc_ptrtype (const void *parent, type *ptr)
	Allocate unnamed context from typed pointer.
type *	talloc_array_ptrtype (const void *parent, type *ptr, size_t count)
	Allocate array of elements of type taken from pointer.
void *	talloc_new (const void *parent)
	Allocate unnamed context as child of parent.
Special contexts.
Contexts that have unusual behaviour.
void *	talloc_autofree_context (void)
	Allocate context that will be freed on program exit.
void *	talloc_from_cx (const struct CxMem *cx, size_t size, const char *name)
	Allocate memory from CxMem.
struct CxMem *	talloc_as_cx (const void *parent, const char *name)
	Create CxMem context that uses talloc.
Free memory.
void	talloc_set_destructor (const void *ptr, talloc_destructor_f destructor)
	Set function to be called on final free.
int	talloc_free (const void *ptr)
	Free allocated context and all it's children.
Reallocate existing context.
Only context that have only one reference can be reallocated.
type *	talloc_realloc (const void *parent, const void *ptr,#type, size_t count)
	Reallocate array.
void *	talloc_realloc_size (const void *parent, void *ptr, size_t size)
	Reallocate untyped context.
void *	talloc_realloc_fn (const void *parent, void *ptr, size_t size)
	Function version of realloc.
Custom object name.
const char *	talloc_get_name (const void *ptr)
	Return object name.
const char *	talloc_set_name (const void *ptr, const char *fmt,...)
	Set formatted name.
void	talloc_set_name_const (const void *ptr, const char *name)
	Set name pointer directly.
void *	talloc_check_name (const void *ptr, const char *name)
	Return same pointer only if name matches, NULL otherwise.
Type-based names.
void	talloc_set_type (const void *ptr,#type)
	Set context name from type.
type *	talloc_get_type (const void *ptr,#type)
	Get typed pointer only if name matches.
type *	talloc_get_type_abort (const void *ptr,#type)
	Get typed pointed only if name matches, aborting otherwise.
Allocated area size.
size_t	talloc_get_size (const void *ptr)
	Get length of allocated area.
size_t	talloc_array_length (const type *array)
	Get number of elements in array.
Object parent.
void *	talloc_parent (const void *ptr)
	Get parent object.
const char *	talloc_parent_name (const void *ptr)
	Get parent object's name.
void *	talloc_find_parent_byname (const void *ptr, const char *name)
	Find direct parent based on name.
type *	talloc_find_parent_bytype (const void *ptr,#type)
	Find direct parent based on type.
Reference handling
Talloc operates on references, not reference counts.
void *	talloc_reference (const void *new_parent, const void *ptr)
	Create another reference from parent to child.
int	talloc_increase_ref_count (const void *ptr)
	Create another reference from NULL context to child.
int	talloc_unlink (const void *parent, const void *ptr)
	Remove parent's reference to child.
size_t	talloc_reference_count (const void *ptr)
	Return number of references context has.
Change parent
void *	talloc_reparent (const void *old_parent, const void *new_parent, const void *ptr)
	Find reference from old parent switch it to new parent.
void *	talloc_move (const void *new_parent, void **ptr_p)
	Change primary parent, set old pointer to NULL.
void *	talloc_steal (const void *new_parent, const void *ptr)
	Change primary parent.
String functions.
void *	talloc_memdup (const void *parent, const void *p, size_t len)
	Copy memory.
char *	talloc_strdup (const void *parent, const char *s)
	Copy string.
char *	talloc_strndup (const void *parent, const char *s, size_t maxlen)
	Copy string with size limit.
char *	talloc_asprintf (const void *parent, const char *fmt,...)
	Format string.
char *	talloc_vasprintf (const void *parent, const char *fmt, va_list ap)
	Format string taking argument from va_list.
String append functions.
The *_append() functions use strnlen() to get size of string in buffer.
char *	talloc_strdup_append (char *ptr, const char *s)
	Append string to existing string.
char *	talloc_strndup_append (char *ptr, const char *s, size_t maxlen)
	Append string with limit to existing string.
char *	talloc_asprintf_append (char *ptr, const char *fmt,...)
	Append formatted string to existing string.
char *	talloc_vasprintf_append (char *ptr, const char *fmt, va_list ap)
	Append formatted string to existing string.
String append to complete buffer.
The *_append_buffer() functions assume talloc_get_size() will give the string length with final NUL byte.
char *	talloc_strdup_append_buffer (char *ptr, const char *str)
	Append string to existing buffer.
char *	talloc_strndup_append_buffer (char *ptr, const char *str, size_t maxlen)
	Append string with limit to existing buffer.
char *	talloc_asprintf_append_buffer (char *ptr, const char *fmt,...)
	Append formatted string to existing buffer.
char *	talloc_vasprintf_append_buffer (char *ptr, const char *fmt, va_list ap)
	Append formatted string to existing buffer.
Debugging
void	talloc_set_log_fn (void(*log_fn)(const char *message))
	Set log function.
void	talloc_set_log_stderr (void)
	Restore default function.
void	talloc_set_abort_fn (void(*abort_fn)(const char *reason))
	Set function to be called on abort.
void	talloc_enable_null_tracking (void)
	Collect all parent==NULL allocations under one context.
void	talloc_enable_null_tracking_no_autofree (void)
	Collect all parent==NULL allocations under one context, but not autofree.
void	talloc_disable_null_tracking (void)
	Stop collecting all parent==NULL allocations under one context.
void	talloc_enable_leak_report (void)
	On program exit, run talloc_report(NULL, stderr)
void	talloc_enable_leak_report_full (void)
	On program exit, run talloc_report_full(NULL, stderr)
size_t	talloc_total_size (const void *ptr)
	Return allocated bytes under context.
size_t	talloc_total_blocks (const void *ptr)
	Return number of contexts under context.
bool	talloc_is_parent (const void *parent, const void *ptr)
	Walk parents.
void	talloc_report (const void *ptr, FILE *f)
	Print report about context and it's immediate childs.
void	talloc_report_full (const void *ptr, FILE *f)
	Print report about context and it's all childs.
void	talloc_report_depth_file (const void *ptr, int depth, int max_depth, FILE *f)
	Print full report about context, with customizable depth.
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)
	Run callback on context and it's children.
void	talloc_show_parents (const void *ptr, FILE *file)
	Print parents to file.
int	talloc_set_memlimit (const void *ptr, size_t max_size)
	Activate memory limit for object.

---

Detailed Description

Talloc - hierarchical memory allocator.

This is reimplementation of Samba's talloc: https://talloc.samba.org/

Features:

• Any allocated object can be parent to new objects.
• Any object can have more then one parent.
• References.
• Change parent.
• Built on top of <usual/cxalloc.h> API.

Missing features:

• Pools. Use <usual/cxextra.h> pools instead.

It mostly compatible with original so that Samba's documentation is usable, but it does not try to be bug-for-bug compatible.

---

Define Documentation

#define TALLOC_POS

(

apifunc

)

Give name to "unnamed" allocations.

By default it generates name that contains talloc API function name, source file and line number.

It can be redefined in user source files.

#define TALLOC_FREE

(

ptr

)

Free and set pointer to NULL.

---

Typedef Documentation

typedef void TALLOC_CTX

Type for untyped pointers that are usable as talloc parent.

For situations where (void*) needs to be used. There it might be used to use TALLOC_CTX to document that talloc pointer is needed.

typedef int(* talloc_destructor_f)(void *ptr)

Destructor signature.

If it returns -1, talloc_free() cancels its operation and also returns -1.

Parameters:

ptr	Object to be freed.

Returns:

0 on success, -1 otherwise.

---

Function Documentation

type* talloc	(	const void *	parent,
		#	type
	)

Allocate memory for C type.

Returned object will have memory for sizeof(type) bytes.

Parameters:

	parent	Parent context or NULL.
	type	C type of object.

Returns:

New object or NULL on error.

type* talloc_zero	(	const void *	parent,
		#	type
	)

Allocate zero-filled memory for C type.

Returned object will have memory for sizeof(type) bytes.

Parameters:

	parent	Parent context or NULL.
	type	C type of object.

Returns:

New object or NULL on error.

type* talloc_array	(	const void *	parent,
		#	type,
		size_t	count
	)

Allocate array of elements of type given.

size = count * sizeof(type);

Parameters:

parent	Parent context or NULL.
type	C type.
count	Number of elements.

Returns:

New context or NULL on error.

type* talloc_zero_array	(	const void *	parent,
		#	type,
		size_t	count
	)

Allocate zero-filled array of elements of type.

size = count * sizeof(type);

Parameters:

parent	Parent context or NULL.
type	C type.
count	Number of elements.

Returns:

New context or NULL on error.

void* talloc_named_const	(	const void *	parent,
		size_t	size,
		const char *	name
	)

Allocate named object.

Name pointer is used directly, so it should not change.

Parameters:

parent	Parent context or NULL.
size	Length in bytes.
name	Pointer to static string, will be used directly.

Returns:

New context or NULL on error.

void* talloc_zero_named_const	(	const void *	parent,
		size_t	size,
		const char *	name
	)

Allocate zero-filled memory for named object.

Name pointer is used directly, so it should not change.

Parameters:

parent	Parent context or NULL.
size	Length in bytes.
name	Pointer to static string, will be used directly.

Returns:

New context or NULL on error.

void* talloc_named	(	const void *	parent,
		size_t	size,
		const char *	fmt,
			...
	)

Allocate named context.

Name is formatted via talloc_vasprintf() and allocated as child of main object.

Parameters:

parent	Parent context or NULL.
size	Size for allocation.
fmt	printf format for name.

Returns:

New context or NULL on error.

void* talloc_init	(	const char *	fmt,
			...
	)

Allocate new top-level named context.

Name will be allocaten inside context.

Parameters:

fmt	Format string for sprintf.

Returns:

New context or NULL on error.

void* talloc_size	(	const void *	parent,
		size_t	size
	)

Allocate unnamed context.

Parameters:

parent	Parent context or NULL.
size	Size for allocation.

Returns:

New pointer or NULL on error.

void* talloc_zero_size	(	const void *	parent,
		size_t	size
	)

Allocate unnamed context with zeroed memory.

Parameters:

parent	Parent context or NULL.
size	Size for allocation.

Returns:

New pointer or NULL on error.

void* talloc_array_size	(	const void *	parent,
		size_t	size,
		size_t	count
	)

Allocate array of elements of type.

Parameters:

parent	Parent context or NULL.
size	Size for one element.
count	Number of elements.

Returns:

New pointer or NULL on error.

type* talloc_ptrtype	(	const void *	parent,
		type *	ptr
	)

Allocate unnamed context from typed pointer.

sizeof(*(ptr)) will be used as allocation size.

Parameters:

parent	Parent context or NULL.
ptr	Typed pointer

Returns:

New context or NULL on error.

type* talloc_array_ptrtype	(	const void *	parent,
		type *	ptr,
		size_t	count
	)

Allocate array of elements of type taken from pointer.

size = count * sizeof(*ptr);

Parameters:

parent	Parent context or NULL.
ptr	Typed pointer.
count	Number of elements.

Returns:

New context or NULL on error.

void* talloc_new

(

const void *

parent

)

Allocate unnamed context as child of parent.

Parameters:

parent

Parent context or NULL

Returns:

New pointer or NULL on error.

void* talloc_autofree_context

(

void

)

Allocate context that will be freed on program exit.

Objects allocated under this context will be freed via atexit() handler, unless freed earlier. This is useful to see leaked memory on program exit.

Returns:

New context or NULL on error.

void* talloc_from_cx	(	const struct CxMem *	cx,
		size_t	size,
		const char *	name
	)

Allocate memory from CxMem.

Returned pointer and all it's children will be allocated from CxMem;

Name pointer is used directly, so it should not change.

Parameters:

cx	CxMem context to allocate from.
size	Length in bytes.
name	Pointer to static string, will be used directly.

Returns:

New context or NULL on error.

struct CxMem* talloc_as_cx	(	const void *	parent,
		const char *	name
	)		[read]

Create CxMem context that uses talloc.

This makes CxMem-based code work with talloc.

Parameters:

parent	Parent context or NULL.
name	Pointer to static string, will be used directly.

Returns:

New CxMem context or NULL on error.

void talloc_set_destructor	(	const void *	ptr,
		talloc_destructor_f	destructor
	)

Set function to be called on final free.

int talloc_free

(

const void *

ptr

)

Free allocated context and all it's children.

This can be called only on context that have one parent. Use talloc_unlink() if object may have many references.

Parameters:

ptr	Pointer to previously allocated area.

Returns:

0 on success, -1 on error.

type* talloc_realloc	(	const void *	parent,
		const void *	ptr,
		#	type,
		size_t	count
	)

Reallocate array.

Parameters:

	parent	Parent context or NULL.
	ptr	Pointer to be reallocated.
	type	C type of one element.
	count	Number of elements.

Returns:

Reallocated context or NULL on error.

void* talloc_realloc_size	(	const void *	parent,
		void *	ptr,
		size_t	size
	)

Reallocate untyped context.

Parameters:

parent	Parent context or NULL.
ptr	Pointer to be reallocated.
size	New length in bytes.

Returns:

Reallocated context or NULL on error.

void* talloc_realloc_fn	(	const void *	parent,
		void *	ptr,
		size_t	size
	)

Function version of realloc.

This is guaranteed to not be macro, unlike other API calls.

Parameters:

parent	Parent context or NULL.
ptr	Pointer to be reallocated.
size	New length in bytes.

Returns:

Reallocated context or NULL on error.

const char* talloc_get_name

(

const void *

ptr

)

Return object name.

Result will be always non-NULL.

const char* talloc_set_name	(	const void *	ptr,
		const char *	fmt,
			...
	)

Set formatted name.

Format and allocate as child of ptr.

Parameters:

ptr	Pointer to be named.
fmt	Format string.

Returns:

New name or NULL on error.

void talloc_set_name_const	(	const void *	ptr,
		const char *	name
	)

Set name pointer directly.

Parameters:

ptr	Pointer to be named.
name	Pointer to string.

void* talloc_check_name	(	const void *	ptr,
		const char *	name
	)

Return same pointer only if name matches, NULL otherwise.

void talloc_set_type	(	const void *	ptr,
		#	type
	)

Set context name from type.

Parameters:

	ptr	Pointer to be named.
	type	C type.

type* talloc_get_type	(	const void *	ptr,
		#	type
	)

Get typed pointer only if name matches.

Parameters:

	ptr	Pointer to be checked.
	type	C type.

type* talloc_get_type_abort	(	const void *	ptr,
		#	type
	)

Get typed pointed only if name matches, aborting otherwise.

This is more extreme version of talloc_get_type().

Parameters:

	ptr	Pointer to be checked.
	type	C type.

size_t talloc_get_size

(

const void *

ptr

)

Get length of allocated area.

size_t talloc_array_length

(

const type *

array

)

Get number of elements in array.

void* talloc_parent

(

const void *

ptr

)

Get parent object.

const char* talloc_parent_name

(

const void *

ptr

)

Get parent object's name.

void* talloc_find_parent_byname	(	const void *	ptr,
		const char *	name
	)

Find direct parent based on name.

type* talloc_find_parent_bytype	(	const void *	ptr,
		#	type
	)

Find direct parent based on type.

void* talloc_reference	(	const void *	new_parent,
		const void *	ptr
	)

Create another reference from parent to child.

Parameters:

new_parent	New parent context or NULL.
ptr	Target pointer that is referenced.

Returns:

Original pointer or NULL on error.

int talloc_increase_ref_count

(

const void *

ptr

)

Create another reference from NULL context to child.

Parameters:

ptr	Target pointer that is referenced.

Returns:

0 on success, -1 on error.

int talloc_unlink	(	const void *	parent,
		const void *	ptr
	)

Remove parent's reference to child.

If parent is found, unlinks and returns 0, otherwise -1.

When removing last reference, the object is freed.

Parameters:

parent	Parent context or NULL.
ptr	Pointer to be unlinked.

Returns:

0 on success, -1 on error.

size_t talloc_reference_count

(

const void *

ptr

)

Return number of references context has.

void* talloc_reparent	(	const void *	old_parent,
		const void *	new_parent,
		const void *	ptr
	)

Find reference from old parent switch it to new parent.

void* talloc_move	(	const void *	new_parent,
		void **	ptr_p
	)

Change primary parent, set old pointer to NULL.

Useful when moving ponters between structs.

Cannot be used on pointers that have multiple parents.

Parameters:

new_parent	New parent.
ptr_p	Location of pointer, will be set to NULL if successful.

Returns:

Original pointer or NULL on error.

void* talloc_steal	(	const void *	new_parent,
		const void *	ptr
	)

Change primary parent.

Cannot be used on pointers that have multiple parents.

Parameters:

new_parent	New parent.
ptr	Pointer to be moved.

Returns:

Original pointer or NULL on error.

void* talloc_memdup	(	const void *	parent,
		const void *	p,
		size_t	len
	)

Copy memory.

char* talloc_strdup	(	const void *	parent,
		const char *	s
	)

Copy string.

char* talloc_strndup	(	const void *	parent,
		const char *	s,
		size_t	maxlen
	)

Copy string with size limit.

char* talloc_asprintf	(	const void *	parent,
		const char *	fmt,
			...
	)

Format string.

char* talloc_vasprintf	(	const void *	parent,
		const char *	fmt,
		va_list	ap
	)

Format string taking argument from va_list.

char* talloc_strdup_append	(	char *	ptr,
		const char *	s
	)

Append string to existing string.

char* talloc_strndup_append	(	char *	ptr,
		const char *	s,
		size_t	maxlen
	)

Append string with limit to existing string.

char* talloc_asprintf_append	(	char *	ptr,
		const char *	fmt,
			...
	)

Append formatted string to existing string.

char* talloc_vasprintf_append	(	char *	ptr,
		const char *	fmt,
		va_list	ap
	)

Append formatted string to existing string.

char* talloc_strdup_append_buffer	(	char *	ptr,
		const char *	str
	)

Append string to existing buffer.

char* talloc_strndup_append_buffer	(	char *	ptr,
		const char *	str,
		size_t	maxlen
	)

Append string with limit to existing buffer.

char* talloc_asprintf_append_buffer	(	char *	ptr,
		const char *	fmt,
			...
	)

Append formatted string to existing buffer.

char* talloc_vasprintf_append_buffer	(	char *	ptr,
		const char *	fmt,
		va_list	ap
	)

Append formatted string to existing buffer.

void talloc_set_log_fn

(

void(*)(const char *message)

log_fn

)

Set log function.

void talloc_set_log_stderr

(

void

)

Restore default function.

void talloc_set_abort_fn

(

void(*)(const char *reason)

abort_fn

)

Set function to be called on abort.

void talloc_enable_null_tracking

(

void

)

Collect all parent==NULL allocations under one context.

void talloc_enable_null_tracking_no_autofree

(

void

)

Collect all parent==NULL allocations under one context, but not autofree.

void talloc_disable_null_tracking

(

void

)

Stop collecting all parent==NULL allocations under one context.

void talloc_enable_leak_report

(

void

)

On program exit, run talloc_report(NULL, stderr)

void talloc_enable_leak_report_full

(

void

)

On program exit, run talloc_report_full(NULL, stderr)

size_t talloc_total_size

(

const void *

ptr

)

Return allocated bytes under context.

size_t talloc_total_blocks

(

const void *

ptr

)

Return number of contexts under context.

bool talloc_is_parent	(	const void *	parent,
		const void *	ptr
	)

Walk parents.

void talloc_report	(	const void *	ptr,
		FILE *	f
	)

Print report about context and it's immediate childs.

void talloc_report_full	(	const void *	ptr,
		FILE *	f
	)

Print report about context and it's all childs.

void talloc_report_depth_file	(	const void *	ptr,
		int	depth,
		int	max_depth,
		FILE *	f
	)

Print full report about context, with customizable depth.

void talloc_report_depth_cb	(	const void *	ptr,
		int	depth,
		int	max_depth,
		void(*)(const void *ptr, int depth, int max_depth, int is_ref, void *private_data)	callback,
		void *	private_data
	)

Run callback on context and it's children.

void talloc_show_parents	(	const void *	ptr,
		FILE *	file
	)

Print parents to file.

int talloc_set_memlimit	(	const void *	ptr,
		size_t	max_size
	)

Activate memory limit for object.

The limit affects only new children allocated after setting it. It does not take account object itself and it's current children.

Parameters:

ptr	Targer pointer.
max_size	Limit in bytes.

Returns:

0 on success, -1 otherwise.