NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXTENDED DESCRIPTION | NOTES | ATTRIBUTES
#include <stdlib.h>void * malloc(size_t size);
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 4.0 offers three malloc() libraries. See EXTENDED DESCRIPTION below for details.
The argument passed to free() is a pointer to a block previously allocated 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 do 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.
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.
ChorusOS 4.0 offers three malloc() libraries. The following list describes each library:
The standard malloc() for ChorusOS 4.0, based on the standard SolarisTM libc implementation, which has been extended to release freed memory to the system for use by the kernel and by other actors. However, calling free() does not automatically return memory to the system. malloc() 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 .
Doug Lea's malloc() , also known as the libg++ malloc() implementation, adapted for ChorusOS 4.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() . free() may also call malloc_trim() if enough memory is free at the top of the heap.
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): Library Routines in the Solaris 2.6 Reference Manual AnswerBook for details.
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.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXTENDED DESCRIPTION | NOTES | ATTRIBUTES