# CFI_allocate

C function prototype: Allocates memory for an object described by a C descriptor.

    int CFI_allocate (CFI_cdesc_t *dv,
                      const CFI_index_t lower_bounds[]),
                      const CFI_index_t upper_bounds[],
                      size_t elem_len);

Formal Parameters:

dv | The address of a C descriptor specifying the rank and type of the object. The `base_addr` member of the C descriptor is a null pointer. If the type is not a character type, the elem_len member must specify the element length. The attribute member must have a value of CFI_attribute_allocatable or CFI_attribute_pointer.
lower_bounds | The address of an array with at least dv->rank elements. The first dv->rank elements of lower_bounds provide the lower Fortran bounds for each corresponding dimension of the object.
upper_bounds | The address of an array with at least dv->rank elements. The first dv->rank elements of upper_bounds provide the upper Fortran bounds for each corresponding dimension of the object.
elem_len | If the type specified in the C descriptor type is a Fortran character type, the value of elem_len is the storage size in bytes of an element of the object; otherwise, elem_len is ignored.

## Description

Successful execution of CFI_allocate allocates memory for the object described by the C descriptor with the address dv using the same mechanism as the Fortran ALLOCATE statement, and assigns the address of that memory to dv->`base_addr`.

The first dv->rank elements of the lower_bounds and upper_bounds arguments provide the lower and upper Fortran bounds, respectively, for each corresponding dimension of the object. The supplied lower and upper bounds override any current dimension information in the C descriptor. If the rank is zero, the lower_bounds and upper_bounds arguments are ignored.

If the type specified in the C descriptor is a character type, the supplied element length overrides the current element-length information in the descriptor.

If an error is detected, the C descriptor is not modified.

## Result Value

The result is an error indicator.

## Example

If dv is the address of a C descriptor for the Fortran array A declared as follows:

    REAL, ALLOCATABLE :: A(:, :)

and the array is not allocated, the following code allocates it to be of shape [100, 500]:

    CFI_index_t lower[2], upper[2];
    int ind;
    lower[0] = 1; lower[1] = 1;
    upper[0] = 100; upper[1] = 500;
    ind = CFI_allocate(dv, lower, upper, 0);

Parent topic: C to D

## See Also

ALLOCATE
C Structures Typedefs and Macros for interoperability
Interoperating with arguments using C descriptors