malloc

Date:: 10-12-2011

NAME

MALLOC, REALLOC, FREE - Allocates, reallocates, and deallocates main memory

SYNOPSIS

MALLOC ([N=]nbytes)
newiptr = REALLOC ([P=]iptr, [I=]nbytes)
CALL FREE ([P=]iptr)
   INTEGER :: nbytes
   POINTER (iptr)

IMPLEMENTATION

Cray Linux Environment (CLE)

STANDARDS

Fortran extension

DESCRIPTION

The MALLOC, REALLOC, and FREE intrinsic functions provide a simple general-purpose memory allocation package; they are elemental functions. The MALLOC function returns a pointer to a block of at least nbytes suitably aligned for any use. MALLOC returns the first contiguous region of free space found in a circular search from the last block allocated or freed, coalescing adjacent free blocks as it searches. It calls sbrk() to get more memory from the system when there is no suitable space already free.

REALLOC

The REALLOC function changes the size of a block (pointed to by iptr) to nbytes and returns a pointer to a block that may have moved. The contents of the block remains the same up to the lesser of the new and old sizes. If a free block of size nbytes is not available in the storage arena, REALLOC calls ALLOC to enlarge the arena by nbytes. If the call is successful, the data is moved to the new block.

The iptr argument is a pointer to a block previously allocated by MALLOC. If the iptr pointer is NULL, REALLOC behaves like MALLOC(nbytes).

If nbytes is zero, one of the following may happen:

The storage associated with iptr may be freed and REALLOC may return the same result as MALLOC(0).
The storage associated with iptr may be combined with space from another area and a non-NULL pointer to the larger area may be returned. This area may then be used in a call to FREE to free the block.

FREE

The iptr argument is a pointer to a block previously allocated by the MALLOC function. If you pass this pointer to the FREE function, this block is made available for subsequent allocation, but its content is left undisturbed.

NOTES

For most Cray Fortran applications, MALLOC and FREE can be replaced by the ALLOCATE and DEALLOCATE Fortran statements. The statements are simpler and portable. Do not use a pointer created by an ALLOCATE statement in a REALLOC or FREE intrinsic reference. Do not use a pointer generated by MALLOC or REALLOC intrinsic reference in a DEALLOCATE statement.

Search time increases when many objects have been allocated; that is, if a program allocates but never frees, then each successive allocation takes longer.

Memory Limits

The limit of the local heap size can affect whether MALLOC can allocate enough memory. For more information, refer to the malloc(3c) man page. Use the man -a option to see multiple man pages of the same name.

RETURN VALUES

Undefined results occur if the space assigned by MALLOC is overrun or if some random number is handed to FREE.

MALLOC and REALLOC return a NULL pointer if there is no available memory or if the area has been detectably corrupted by storing outside the bounds of a block. When this happens the block pointed to by iptr can be destroyed.

EXAMPLES

The following examples, show how to use MALLOC, REALLOC, and FREE.

POINTER (iraddr,ira)
POINTER (inewraddr,irc)
integer isize

! MALLOC example
isize = 8000
iraddr = malloc(isize)
if (iraddr .EQ. 0_8) then
  print *, 'malloc(8000) returns null ptr, malloc fails. '
else
  print '(1x,a,z17)','malloc(8000) returns ptr=',iraddr
endif

print *,'end of malloc test'


! REALLOC example
ira = 16000
isize = 16000
inewraddr = realloc(iraddr,isize)

if (iraddr .EQ. inewraddr) then
  print '(1x,a,z17)','realloc(ptr,16000) returns same ptr,',inewraddr
else
  print '(1x,a)','realloc(ptr,16000) returns diff ptr,'
  print '(1x,a,2z17)','iraddr,inewraddr=',iraddr,inewraddr
endif

print *,'end of realloc test'

! FREE example
call free(inewraddr)

end

The output for this program follows:

malloc(8000) returns ptr = 13B1610
end of malloc test
realloc(ptr,16000) returns diff ptr,
iraddr,inewraddr = 13B1610 13B67D0
end of realloc test