talloc_array - Man Page

The talloc string 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.

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

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.

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.

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.

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()).

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.

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.

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