*** UNIX MANUAL PAGE BROWSER ***

malloc(3) Library Functions Manual malloc(3) NAME alloca, calloc, free, mallinfo, malloc, mallopt, realloc, valloc - Pro- vides a memory allocator LIBRARY Standard C Library (libc.so, libc.a) Berkeley Compatibility Library (libbsd.a) SYNOPSIS #include <stdlib.h> void *calloc( size_t num_of_elts, size_t elt_size); void free( void *pointer); void *malloc( size_t size); void *realloc( void *pointer, size_t size); void *valloc( size_t size); The following function definitions do not conform to current standards and are supported only for backward compatibility: char *valloc( /* libbsd.a version */ size_t size); /* returns pointer to char */ #include <alloca.h> void *alloca( int size); The following function definitions are provided only for System V com- patibility: #include <malloc.h> struct mallinfo mallinfo(void); int mallopt( int command, int value; STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: calloc(), free(), malloc(), realloc(): XPG4, XPG4-UNIX valloc(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies a number of bytes of memory. Points to the block of memory that was returned by the malloc() or calloc() function. Specifies a mallopt() function command. Specifies M_MXFAST, M_NLBLKS, M_GRAIN, or M_KEEP. Specifies the number of elements in the array. Specifies the size of each element in the array. DESCRIPTION The malloc() and free() functions provide a simple, general-purpose memory allocation package. The malloc() function returns a pointer to a block of memory of at least the number of bytes specified by the size parameter. The block is aligned so that it can be used for any type of data. If the size parameter is 0 (zero), the malloc() function returns a null pointer. The free() function frees the block of memory pointed to by the pointer parameter for further allocation. The block pointed to by the pointer parameter must have been previously allocated as follows: By either the malloc(), realloc(), or calloc() functions. [XPG4-UNIX] By either the malloc(), realloc(), calloc(), or valloc() functions. The realloc() function changes the size of the block of memory pointed to by the pointer parameter to the number of bytes specified by the size parameter, and returns a pointer to the block. The contents of the block remain unchanged up to the lesser of the old and new sizes. If necessary, a new block is allocated, and data is copied to it. If the pointer parameter is a null pointer, the realloc() function simply allocates a new block of the requested size. If the size parameter is 0 (zero) and pointer is not a null pointer, the realloc() function frees the specified block. The calloc() function allocates space for an array with the number of elements specified by the num_of_elts parameter, where each element is of the size specified by the elt_size parameter. The space is initial- ized to zeros. [Digital] The alloca() function allocates the number of bytes of space specified by the size parameter in the stack frame of the caller. This space is automatically freed when the function that called the alloca() function returns to its caller. The alloca() function requires inclu- sion of <alloca.h>. Without this header file, alloca() allocates mem- ory in the heap instead of the stack; this memory is not necessarily freed when the calling routine exits. The valloc() function has the same effect as malloc(), except that the allocated memory is automatically aligned to a page boundary (that is, the value returned by a call to getpagesize()). The mallopt() and mallinfo() functions are intended to allow tuning the allocation algorithm at execution time. They have no effect on the current DIGITAL UNIX implementation of memory allocation. See the NOTES section for details. The mallopt() function can be called repeatedly, but parameters cannot be changed after the first small block is allocated from a holding block. If the mallopt() function is called again after the first small block is allocated, it returns an error. The mallinfo() function can be used during program development to de- termine the best settings of these parameters for a particular applica- tion. It must only be called after some storage has been allocated. Information describing space usage is returned. Refer to the /usr/in- clude/malloc.h header file for details of the mallinfo structure. Tuning Memory Allocation The behavior of these memory allocation functions can be tuned to opti- mize their performance in a particular application. The following variables control how the functions operate. Note that these variables and their effects are specific to the current DIGITAL UNIX memory allocation implementation. The default values for these variables are specified by libc. To specify values other than the de- faults, create a module containing definitions for the complete set of variables and include that module in your compilation. (If you define only some of these variables, your compilation will produce "multiply defined" errors if you link the program nonshared.) For each variable in this list, the default value is indicated after the equal sign. The variable __noshrink controls management of the heap size (which in turn controls the size of the required swap area). As the user makes calls to free() or realloc(), the memory associated with the call can be put back into the pool of free memory. Permissible values for __noshrink are 0 and 1. If the memory that is freed resides at the end of the heap and meets the constraints of __minshrink and __minshrinkfactor, it can be returned to the kernel by sbrk(nnn) if __noshrink is 0. If __noshrink is 1, no attempts are made to return the freed memory. Set __noshrink to 1 if execution speed is more important than economy of memory usage. The variable __minshrink is the mini- mum size that the heap is allowed to shrink in response to the freeing of space at the end of the heap. The heap will shrink if the space is greater than __minshrink and greater than __min- shrinkfactor * heap_size_in_bytes. This variable has no effect unless __noshrink is 0. The vari- able __minshrinkfactor is the minimum fraction that the heap is allowed to shrink in response to the freeing of space at the end of the heap. The heap will shrink if the space is greater than __minshrink and greater than __minshrinkfactor * heap_size_in_bytes. This variable has no effect unless __noshrink is 0. The vari- able __mingrow is the minimum size that the heap is allowed to grow in response to any request for a buffer that would grow the heap. The amount to grow is the larger of __mingrow or __min- growfactor * heap_size_in_bytes. The value of this variable is used in whole-page increments; any value that is not an integral multiple of the page size is rounded upward to the next whole number of pages. The __mingrow and __mingrowfactor variables control compromises between speed and memory usage; increasing either or both of them increases overhead but decreases execution time. The vari- able __mingrowfactor is the minimum fraction that the heap will be allowed to grow. The actual amount grown is the larger of __mingrowor __mingrowfactor * heap_size_in_bytes. The __madvi- sor variable controls how malloc communicates memory usage in- formation to the kernel. Permissible values for __madvisor are 0 and 1. If the variable value is 1, any physical memory asso- ciated with the virtual memory range is removed, reducing the resident set size (RSS). The kernel does not need to swap this memory out. Setting a value of 1 for __madvisor results in a trivial de- crease in execution speed. If execution speed is important, leave the setting at the default value of 0. The __small_buff variable affects how malloc allocates space for extremely small buffers. If the variable is 1, malloc allocates 24 bytes for requests of 1 to 15 bytes; if it is 0, the buffer allocated is 32 bytes. The size of 32 bytes is required by X/Open guidelines specifying that a buffer must be so aligned that it can be as- signed to any type of object. Permissible values for __small_buff are 0 and 1. If the process is using a great many small (1 to 15 byte) buffers, setting __small_buff to 1 reduces heap overhead. The variable __fast_free_max is the maximum number of small buffers that malloc retains in the free list without attempting to coa- lesce. This number is further adjusted by the number of megabytes in the user heap. As the heap size increases, this number in reduced by 1 for each 10 MB of heap so that at a heap size of 130 MB only one buffer of each type is held in the free list. Increasing the value of __fast_free_max increases both execution speed and overhead (the size of the heap in relation to the mem- ory requested). The variable __sbrk_override controls the man- ner in which the heap growth is obtained. If this variable is set to 1 and the call to sbrk to grow the heap fails, a call is made to mmap to attempt to obtain memory. This technique is ex- tremely valuable to programs running in taso mode. The use of this method to obtain heap space will cause sbrk(0) to return a value that does not reflect the true end of the heap. The vari- able __taso_mode is set to 1 to indicate that the program is ex- ecuting in taso mode. If the variable is set to 1, the pointers returned by malloc and realloc are bounds checked and the ENOMEM error is returned if the pointer exceeds MAXINT. NOTES The mallopt() and mallinfo() functions are not supported for multi- threaded applications. The mallopt() and mallinfo() functions are designed for tuning a spe- cific algorithm. The DIGITAL UNIX operating system uses a new, more efficient algorithm. The mallopt() and mallinfo() functions are pro- vided for System V compatibility only and should not be used by new ap- plications. The behavior of the current malloc() and free() functions is not be affected by calls to mallopt(). The structure returned by the mallinfo() function might not contain any useful information. The valloc() function is scheduled to be withdrawn from a future ver- sion of the X/Open CAE Specification. RESTRICTIONS Because the alloca() function requires inclusion of <alloca.h> in order to work correctly, this function is not portable. Usage of brk(), sbrk(), or other virtual memory primitives can inter- fere with the operation of malloc() and its associated functions. RETURN VALUES Each of the allocation functions returns a pointer to space that is suitably aligned for storage of any type of object. Cast the pointer to the type pointer-to-element before using it. The malloc(), realloc(), calloc(), and valloc() functions return a null pointer if no memory is available or if the memory arena has been cor- rupted by storing outside the bounds of a block. When this happens, the block pointed to by the pointer parameter could be destroyed. Upon successful completion, the mallopt() function returns 0 (zero). If the argument makes no sense, mallopt() returns -1 and sets errno to indicate the error. Otherwise, another nonzero value is returned. The mallinfo() function returns a pointer to a mallinfo structure, de- fined in the /usr/include/malloc.h header file. ERRORS The malloc(), calloc(), realloc(), and valloc() functions set errno to the specified values for the following conditions: Insufficient storage space is available. [Digital] For malloc(), this value indicates that the value of the size parameter is out of range. [Digital] For realloc(), this value indicates that the buffer is already free. The mallopt() function sets errno to the specified values for the fol- lowing conditions: The value argument makes no sense. Conditions that can cause this er- ror include: M_MXFAST argument < 0 M_NBLKS argument <= 1 M_GRAIN ar- gument <= 0 All commands after the first small block is allocated An unknown command Additionally, malloc() and its associated routines call other libc rou- tines, which can set errno (for example, sbrk()). RELATED INFORMATION Functions: sysconf(3) Standards: standards(5) delim off malloc(3)