Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
array_allocate(3)	   Library Functions Manual	     array_allocate(3)

       array_allocate -	make sure array	has at least n elements	allocated

       #include	<array.h>

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

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

       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;	other-
       wise  the effects are undefined.) If not	enough bytes are allocated (or
       x is unallocated), array_allocate allocates more	bytes, moving the  dy-
       namically  allocated  region  if	necessary.  array_allocate often allo-
       cates 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 initial-
       ized, 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., ob-
       ject 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	appro-
       priately,  without  touching x. In particular, array_allocate returns 0

       o      x	has failed, or

       o      pos is negative, or

       o      not enough memory	is available.

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

       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 swap-
       ping and	blocking.

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



Want to link to this manual page? Use this URL:

home | help