Allocating Exportable Dynamic Memory

The CNF functions cnfMalloc and cnfCalloc should be used whenever you wish to dynamically allocate memory in a C function and export the resulting pointer for use from FORTRAN. You might also want to use them if you are writing a subroutine library that returns pointers to dynamic memory through its public interface, since the caller might then decide to pass these pointers on to a FORTRAN routine.

For example, here is how you should allocate space for an array of N FORTRAN REAL values in a C function and pass back the resulting pointer to FORTRAN:

F77_POINTER_FUNCTION(ralloc)( INTEGER(N) )
{
   GENPTR_INTEGER(N)

/* Allocate the memory and return the converted pointer. */
   return cnfFptr(cnfMalloc(*N*sizeof(F77_REAL_TYPE)));
}

When the allocated memory is no longer required, it should be freed using cnfFree. This is how you might import the FORTRAN pointer value allocated above back into C in order to free it:

F77_SUBROUTINE(rfree)( POINTER(FPNTR) )
{
   GENPTR_POINTER(FPNTR)

/* Convert back to a C pointer and then free it. */
   cnfFree(cnfCptr(*FPNTR));
}

Externally, these CNF memory allocation functions behave exactly like their standard C equivalents malloc, calloc and free. Internally, however, they perform two important additional functions:

• They maintain the internal table of ``registered'' pointers, so that the conversion functions cnfFptr and cnfCptr can operate (if you use malloc to obtain a pointer, for instance, then these conversion functions will fail and return zero).

• They ensure that all memory allocation results in pointers whose lowest 32 bits (or the length of a FORTRAN INTEGER) are unique, so that conversion between FORTRAN and C pointer values is a well-defined operation.

For convenience, cnfFree is also able to free pointers which have not been registered, in which case it behaves exactly like free.