The talloc array functions
[The talloc API]

Talloc contains some handy helpers for handling Arrays conveniently. More...

Functions

void * talloc_array (const void *ctx,#type, unsigned count)
 Allocate an array.
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.
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.
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

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:
[in] ctx The talloc context to hang the result off.
[in] type The type that we want to allocate.
[in] 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:
[in] 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:
[in] ctx The talloc context to hang the result off.
[in] ptr The pointer you want to assign the result to.
[in] count The number of elements you want to allocate.
Returns:
The allocated memory chunk, properly casted. NULL on error.
void* talloc_array_size ( const void *  ctx,
size_t  size,
unsigned  count 
)

Allocate an array.

Parameters:
[in] ctx The talloc context to hang the result off.
[in] size The size of an array element.
[in] count The number of elements you want to allocate.
Returns:
The allocated result, NULL on error.
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:
[in] ctx The parent context used if ptr is NULL.
[in] ptr The chunk to be resized.
[in] type The type of the array element inside ptr.
[in] 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()).
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:
[in] context The parent context used if ptr is NULL.
[in] ptr The chunk to be resized.
[in] 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:
[in] ctx The parent context used if 'ptr' is NULL.
[in] ptr The chunk to be resized.
[in] 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:
[in] ctx The talloc context to hang the result off.
[in] type The type that we want to allocate.
[in] 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, sizeof(type) * count);
Generated by  doxygen 1.6.3