realloc(3STDC)

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | EXTENDED DESCRIPTION | NOTES | ATTRIBUTES

NAME

malloc, free, realloc, calloc- main memory allocator

SYNOPSIS

$(NUCLEUS_DIR)/lib/classix/libmalloc.s.a
#include <stdlib.h>

void * malloc(size_t size);
void free(void * ptr);
void * realloc(void * ptr, size_t size);
void *calloc(size_t nelem, size_t elsize);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

The malloc() and free() functions provide a simple general-purpose memory allocation package. The malloc() function returns a pointer to a block of at least size bytes suitably aligned for any use. ChorusOS 5.0 offers three malloc() libraries. See EXTENDED DESCRIPTION below for details.

The argument passed to free() is a pointer to a block allocated previously by malloc() . After free() is performed this space is made available for further allocation, but its contents are left undisturbed.

The free() function may be called with a NULL pointer as parameter.

If the space assigned by malloc() is overrun or if a random number is passed to free() , the result is undefined.

The malloc() function searches for free space from the last block allocated or freed, grouping together any adjacent free blocks. It allocates the first contiguous area of free space that is at least size bytes.

The realloc() function changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the smaller of the new and old sizes. If no free block of size bytes is available in the storage area, realloc() will ask malloc() to enlarge the area by size bytes and will then move the data to the new space. If the space cannot be allocated, the object pointed to by ptr is unchanged. If size is zero and ptr is not a null pointer, the object it points to is freed. If ptr is a null pointer, the realloc() function behaves like the malloc() function for the specified size.

The realloc() function also works if ptr points to a block freed since the last call to malloc() , realloc() , or calloc() . Thus sequences of free() , malloc() and realloc() can be used to exploit the search strategy of malloc() in order to perform storage compacting.

The calloc() function allocates space for an array of nelem elements of size elsize . The space is initialized to zeros.

Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object.

RETURN VALUES

The malloc() , realloc() and calloc() functions return a NULL pointer if there is no memory available, or if the area has been detectably corrupted by storing outside the bounds of a block. When this happens, the block indicated by ptr is neither damaged nor freed.

EXTENDED DESCRIPTION

ChorusOS 5.0 offers three malloc() libraries. The following list describes each library:

lib/classix/libcx.a

The standard malloc() for ChorusOS 5.0, based on the standard Solaris^TM libc implementation, which has been extended to release freed memory to the system for use by the micro kernel and by other actors. However, calling free() does not automatically return memory to the system. The malloc() function takes memory chunks from page-aligned regions. Regions are only returned to the system once all the chunks in the region have been freed. Furthermore, free() buffers memory chunks so that they can be reused immediately by malloc() if possible. Therefore, memory may not be returned to the system until malloc() is called again. malloc_trim() can be used to release empty regions to the system explicitly.

alloca() , calloc() , memalign() and valloc() are not available in lib/classix/libcx.a .

lib/classix/libleamalloc.a

Doug Lea's malloc() , also known as the libg++ malloc() implementation, has been adapted for ChorusOS 5.0 to allow the heap to be sparsed in several regions. This implementation is especially useful in supervisor mode, because supervisor space is shared by several actors. Freed memory may be returned to the system using malloc_trim() . The free() function may also call malloc_trim() if enough memory is free at the top of the heap.

lib/classix/libomalloc.a

The BSD malloc() is provided for backwards compatibility with previous releases. This implementation corresponds to bsdmalloc(3X) in 2.6. See Solaris man Pages(3): Basic Library Functions in the Solaris Reference Manual Collection for details.

NOTES

Performance and efficiency depend upon the way the library is used. Search time increases when many objects have been allocated; that is, if a program allocates but never frees, each successive allocation takes longer. Tests on the running program should be performed in order to determine the best balance between performance and efficient use of space to achieve optimum performance.

If the program is multi-threaded, and if the free() and then realloc() feature is used, it is up to the programmer to set up the mutual exclusion schemes needed to prevent a malloc() taking place between free() and realloc() calls.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | EXTENDED DESCRIPTION | NOTES | ATTRIBUTES