talloc_array

Section: talloc (3)
Updated: Tue Jan 26 2021
Page Index

NAME

talloc_array - The talloc array functions

- Talloc contains some handy helpers for handling Arrays conveniently.

SYNOPSIS

Modules

The talloc string functions.
talloc string allocation and manipulation functions.

Functions

_PUBLIC_ void * talloc_array (const void *ctx, #type, unsigned count)
Allocate an array.
_PUBLIC_ void * talloc_array_size (const void *ctx, size_t size, unsigned count)
Allocate an array.
void * talloc_array_ptrtype (const void *ctx, const void *ptr, unsigned count)
Allocate an array into a typed pointer.
size_t talloc_array_length (const void *ctx)
Get the number of elements in a talloc'ed array.
void * talloc_zero_array (const void *ctx, #type, unsigned count)
Allocate a zero-initialized array.
_PUBLIC_ void * talloc_realloc (const void *ctx, void *ptr, #type, size_t count)
Change the size of a talloc array.
void * talloc_realloc_size (const void *ctx, void *ptr, size_t size)
Untyped realloc to change the size of a talloc array.
_PUBLIC_ void * talloc_realloc_fn (const void *context, void *ptr, size_t size)
Provide a function version of talloc_realloc_size.

Detailed Description

Talloc contains some handy helpers for handling Arrays conveniently.

Function Documentation

_PUBLIC_ void* talloc_array (const void * ctx, # type, unsigned count)

Allocate an array. The macro is equivalent to:

(type *)talloc_size(ctx, sizeof(type) * count);

except that it provides integer overflow protection for the multiply, returning NULL if the multiply overflows.

Parameters

: ctx The talloc context to hang the result off.
type The type that we want to allocate.
count The number of 'type' elements you want to allocate.

Returns

: The allocated result, properly cast to 'type *', NULL on error.

Example:

unsigned int *a, *b;
a = talloc_zero(NULL, unsigned int);
b = talloc_array(a, unsigned int, 100);

See also

: talloc()
talloc_zero_array()

size_t talloc_array_length (const void * ctx)

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.

Parameters

: ctx The allocated array.

Returns

: The number of elements in ctx.

void* talloc_array_ptrtype (const void * ctx, const void * ptr, unsigned count)

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.

Parameters

: ctx The talloc context to hang the result off.
ptr The pointer you want to assign the result to.
count The number of elements you want to allocate.

Returns

: The allocated memory chunk, properly casted. NULL on error.

_PUBLIC_ void* talloc_array_size (const void * ctx, size_t size, unsigned count)

Allocate an array.

Parameters

: ctx The talloc context to hang the result off.
size The size of an array element.
count The number of elements you want to allocate.

Returns

: The allocated result, NULL on error.

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

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:

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);

The 'context' argument is only used if 'ptr' is NULL, otherwise it is ignored.

Parameters

: ctx The parent context used if ptr is NULL.
ptr The chunk to be resized.
type The type of the array element inside ptr.
count The intended number of array elements.

Returns

: 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_fn (const void * context, void * ptr, size_t size)

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.

Parameters

: context The parent context used if ptr is NULL.
ptr The chunk to be resized.
size The new chunk size.

Returns

: The new chunk, NULL on error.

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

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.

Parameters

: ctx The parent context used if 'ptr' is NULL.
ptr The chunk to be resized.
size The new chunk size.

Returns

: The new array, NULL on error.

void* talloc_zero_array (const void * ctx, # type, unsigned count)

Allocate a zero-initialized array.

Parameters

: ctx The talloc context to hang the result off.
type The type that we want to allocate.
count The number of 'type' elements you want to allocate.

Returns

: The allocated result casted to 'type *', NULL on error.

The talloc_zero_array() macro is equivalent to:

ptr = talloc_array(ctx, type, count);
if (ptr) memset(ptr, 0, sizeof(type) * count);

Author

Generated automatically by Doxygen for talloc from the source code.