Man page - array_allocate(3)

Packages contains this manual

Manual

array_allocate

NAME
SYNTAX
DESCRIPTION
PERFORMANCE
SEE ALSO

NAME

array_allocate - make sure array has at least n elements allocated

SYNTAX

#include <libowfat/array.h>

void* array_allocate (array* x , uint64 membersize , int64 pos );

array x ;
int64 pos ;
t * p = array_allocate(& x ,sizeof( t ), pos );

DESCRIPTION

array_allocate makes sure that enough bytes are allocated in x for at least pos +1 objects of type t . (The size of t must be positive; otherwise the effects are undefined.) If not enough bytes are allocated (or x is unallocated), array_allocate allocates more bytes, moving the dynamically allocated region if necessary. array_allocate often allocates somewhat more bytes than necessary, to save time later.

array_allocate then makes sure that the number of bytes initialized covers at least those pos +1 objects. If not enough bytes are initialized, array_allocate initializes more bytes (setting them to 0), up to exactly the end of the pos +1st object.

array_allocate then returns a pointer to the pos +1st object; i.e., object number pos , with objects numbered starting at 0. This pointer can be used to change or inspect the object. The pointer can continue to be used through subsequent calls to array_get, array_start, array_length, and array_bytes, but it must not be used after any other operations on this array.

If something goes wrong, array_allocate returns 0, setting errno appropriately, without touching x . In particular, array_allocate returns 0 if

•

x has failed, or

•

pos is negative, or

•

not enough memory is available.

array_allocate does not change x to have failed; if you want to do that, use array_fail.

PERFORMANCE

This function can call realloc when the array needs to be enlarged. Under exceptional circumstances, this can lead to blocking the current thread. It will also zero-fill the newly enlarged part of the array, leading to all pages being mapped in by the operating system. If a small array is enlarged to a very large array, this can lead to swapping and blocking.

SEE ALSO

array_get(3), array_start(3), array_fail(3)