MALLOC(3X) MALLOC(3X) NAME malloc, free, realloc, calloc, mallopt, mallinfo, mallocblksize, recalloc, memalign - fast main memory allocator SYNOPSIS #include <sys/types.h> #include <malloc.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); int mallopt (int cmd, int value); struct mallinfo mallinfo(void); size_t mallocblksize (void *ptr); void *recalloc (void *ptr, size_t nelem, size_t elsize); void *memalign (size_t align, size_t size); DESCRIPTION malloc and free provide a simple general-purpose memory allocation package, which is more flexible than the malloc(3c) package and, depending on an application's usage, may provide better performance. It is found in the library ``libmalloc.so'', and is loaded if the option ``-lmalloc'' is used with cc(1) or ld(1). malloc returns a pointer to a block of at least size bytes suitably aligned for any use. The argument to free is a pointer to a block previously allocated by malloc; after free is performed this space is made available for further allocation, and its contents are destroyed (see mallopt below for a way to change this behavior). Undefined results will occur if the space assigned by malloc is overrun or if some random number is handed to free. It is always permitted to pass NULL to free. realloc 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 lesser of the new and old sizes. In the special case of a null ptr, realloc degenerates to malloc. A zero size causes the passed block to be freed. calloc allocates space for an array of nelem elements of size elsize. The space is initialized to zeros. recalloc combines realloc and calloc. If the size of the block increases, any new bytes are initialized to zero. Note that for this to work properly, all allocations of a given pointer must go through recalloc. If the original pointer was allocated with either malloc, calloc, or realloc some new bytes may not be set properly to zero. memalign allocates size bytes on a specified alignment boundary, and returns a pointer to the allocated block. The value of the returned address is guaranteed to be an even multiple of align. Note: the value of align must be a multiple of a word (for 64 bit objects, a doubleword,) and must be greater than or equal to the size of a word, or, for 64 bit objects, the size of a doubleword. mallocblksize returns the actual size of the block pointed to by ptr. The returned size may be greater than the original requested size due to padding and alignment. mallopt provides for control over the allocation algorithm. The available values for cmd are: M_MXFAST Set maxfast to value. The algorithm allocates all blocks at or below the size of maxfast in large groups and then doles them out very quickly. The default value for maxfast is 28. M_NLBLKS Set numlblks to value. The above mentioned ``large groups'' each contain numlblks blocks. numlblks must be greater than 0. The default value for numlblks is 100. M_GRAIN Set grain to value. Requests less than or equal to maxfast will have the size of a pointer added to them and be rounded up to the next multiple of grain. value will be rounded up to a multiple of the alignment size (8 bytes for 32 bit programs, 16 bytes for 64 bit programs) when grain is set. grain must be greater than 0. The default value of grain is 8 for 32 bit programs, 16 for 64 bit programs. M_KEEP Preserve data in a freed block until the next malloc, realloc, or calloc. This option is provided only for compatibility with older versions of malloc and is not recommended. M_DEBUG Turns debug checking on if value is not equal to 0, otherwise turns debug checking off. When debugging is on, each call to malloc and free causes the entire malloc arena to be scanned and checked for consistency. This option may be invoked at any time. Note that when debug checking is on, the performance of malloc is reduced considerably. If corruption is detected in the arena, the checking code calls abort(3C). This usually results in the calling process exiting and leaving a core file in its current directory. M_BLKSZ When malloc requires additional space, it uses sbrk(2) to allocate enough memory for the current malloc request rounded up to a minimum size (default is 8K). The new size is set to value after it has been rounded up to the current block alignment. value must be at least 512 bytes. If a lot of space is to be allocated, setting the size larger can cut down on the system overhead. This option may be invoked at any time. M_MXCHK By default, malloc trades off time versus space - if anywhere in the arena there is a block of the appropriate size, malloc will find and return it. If the arena has become fragmented due to many mallocs and frees, it is possible that malloc will have to search through many blocks to find one of the appropriate size. If the arena is severely fragmented, the average malloc time can be on the order of tens of milliseconds (as opposed to a normal average of tens of microseconds). This option allows the user to place a limit on the number of blocks that malloc will search through before allocating a new block of space from the system. Small values (less than 50) can cause much more memory to be allocated. Values around 100 (the default) cause very uniform response time, with a small space penalty. This option may be invoked at any time. M_FREEHD When value is not zero, free, recalloc, and realloc will place any freed memory in the front of the free list(s) instead of at the end (which is the default). Some applications will benefit in processing speed and space compaction by having freed memory placed at the beginning of the free list(s). M_CLRONFREE With this option, all blocks that are freed are set to value. This option may be set at any time, but there is no way to turn it off. That part of the beginning of a freed block which is used for internal pointers will of course not be set to value. These values are defined in the <malloc.h> header file. mallopt may be called repeatedly, but, for most commands, may not be called after the first small block is allocated. mallinfo provides instrumentation describing space usage. It returns the structure (defined in <malloc.h>): struct mallinfo { int arena; /* total space in arena */ int ordblks; /* number of ordinary blocks */ int smblks; /* number of small blocks */ int hblkhd; /* space in holding block headers */ int hblks; /* number of holding blocks */ int usmblks; /* space in small blocks in use */ int fsmblks; /* space in free small blocks */ int uordblks; /* space in ordinary blocks in use */ int fordblks; /* space in free ordinary blocks */ int keepcost; /* space penalty if keep option */ /* is used */ } For example, an application wishing to determine how many bytes it has currently malloc'd should add the usmblks and uordblks fields. That total may also include some space that malloc allocates internally for its own use, and that extra space cannot be free'd. Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. SEE ALSO brk(2), malloc(3C), memalign(3C), amalloc(3P), valloc(3C). DIAGNOSTICS malloc, recalloc, memalign, realloc and calloc return a NULL pointer if there is not enough available memory or size is 0. memalign will also return NULL if align is 0 or not a 4 byte multiple (8 byte multiple for 64-bit programs). When realloc or recalloc returns NULL, the block pointed to by ptr is left intact. If mallopt is called after any allocation (for most cmd arguments) or if cmd or value are invalid, non- zero is returned. Otherwise, it returns zero. WARNINGS Note that unlike malloc(3C), this package does not preserve the contents of a block when it is freed, unless the M_KEEP option of mallopt is used. Undocumented features of malloc(3C) have not been duplicated. Products, libraries, or commands that provide their own malloc package must provide all of the entry points listed above, or the normal libmalloc or libc malloc entry point for the unimplmented routine(s) may be called instead, leading to corrupted heaps, as it is unlikely that the internal details of the heap management will be the same. If the package is a replacement for the libc set, but not the libmalloc set, it is not necessary to supply the mallopt, mallinfo, mallocblksize, or recalloc routines. Page 4