|
|
HP-UX Reference > Mmalloc(3C)HP-UX 11i Version 2: December 2007 Update |
|
NAMEmalloc(), alloca(), calloc(), free(), mallinfo(), mallopt(), memorymap(), realloc(), valloc() — main memory allocator SYNOPSIS#include <stdlib.h> void *malloc(size_t size); void *calloc(size_t nelem, size_t elsize); void *realloc(void *ptr, size_t size); void *valloc(size_t size); void free(void *ptr); void memorymap(int show_stats); (Obsoleted) System V Synopsis#include <malloc.h> char *malloc(unsigned size); void free(char *ptr); char *realloc(char *ptr, unsigned size); char *calloc(unsigned nelem, unsigned elsize); int mallopt(int cmd, int value); struct mallinfo mallinfo(void); RemarksThe functionality in the old malloc(3X) package has been incorporated into malloc(3C). The library (/usr/lib/libmalloc.a) corresponding to the -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. DESCRIPTIONThe functions described in this manual entry provide a simple, general purpose memory allocation package:
Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object.
RETURN VALUEUpon successful completion, malloc(), realloc(), calloc(), and valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. mallopt() returns zero for success and nonzero for failure. DIAGNOSTICSmalloc(), realloc(), calloc(), and valloc() return a NULL pointer if there is no available memory, or if the memory managed by malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by malloc(), realloc(), calloc(), or valloc() is passed as an argument to free() or realloc(). If mallopt() is called after any allocation of a small block and cmd is not set to M_BLOCK or M_UBLOCK, or if cmd or value is invalid, nonzero is returned. Otherwise, it returns zero. ERRORS
EXTERNAL INFLUENCESFor PA-RISC based systems, the performance of the malloc() family of APIs can be tuned via two environment variables, _M_ARENA_OPTS and _M_SBA_OPTS. For Itanium®-based systems, in addition to _M_ARENA_OPTS and _M_SBA_OPTS, three new global variables, __hp_malloc_maxfast, __hp_malloc_num_smallblocks and __hp_malloc_grain can be used for performance tuning. For threaded applications, malloc() uses multiple arenas. Memory requests from different threads are handled by different arenas. _M_ARENA_OPTS can be used to adjust the number of arenas and how many pages each time an arena expands itself (the expansion factor), assuming that the page size is 4096 bytes. In general, the more threads in an application, the more arenas should be used for better performance. The number of arenas can be from 1 to 64 for threaded applications. For non-threaded applications, only one arena is used. If the environment variable is not set, or the number of arenas is set to be out of the range, the default number of 8 will be used. The expansion factor is from 1 to 4096, default value is 32. Again, if the factor is out of the range, the default value will be used. Here is an example of how to use _M_ARENA_OPTS, $ export _M_ARENA_OPTS = 16:8 This means that the number of arenas is 16, and the expansion size is 8*4096 bytes. In general, the more arenas you use, the smaller the expansion factor should be, and vice versa. _M_SBA_OPTS is used to turn on the small block allocator, and to set up parameters for the small block allocator, namely, maxfast, grain, and numlblks. Applications with small block allocator turned on usually run faster than with it turned off. Small block allocator can be turned on through mallopt(); however, it is not early enough for C++/Java applications. The environment variable turns it on before the application starts. The mallopt() call can still be used the same way. If the environment variable is set, and no small block allocator has been used, the subsequent mallopt() calls can still overwrite whatever is set through _M_SBA_OPTS. If the environment variable is set, and small block allocator has been used, then mallopt() will have no effect. To use this environment variable, $ export _M_SBA_OPTS = 512:100:16 This means that the maxfast size is 512, the number of small blocks is 100, and the grain size is 16. You have to supply all 3 values, and in that order. If not, the default values will be used instead. _M_ARENA_OPTS has no effects on non-threaded applications, while _M_SBA_OPTS has. Three new global variables, __hp_malloc_maxfast, __hp_malloc_num_smallblocks and __hp_malloc_grain are introduced for Itanium-based systems to override the _M_SBA_OPTS environment option. When these three variables are initialized within an application, _M_SBA_OPTS has no effect. This way, a finely tuned application can lock in performance across different user environments. However, as _M_ARENA_OPTS, a subsequent call to mallopt() before any block of memory was allocated will change the malloc() behavior. By default, these three variables will be initialized to zero at start up. It is the same as setting them to extern int __hp_malloc_maxfast=512; extern int __hp_malloc_num_smallblocks=100; extern int __hp_malloc_grain=16; By default, SBA (Small Block Allocation) is turned on for Itanium-based systems. This may contribute to better application performance. A user can set extern int __hp_malloc_maxfast=-1; This will turn off SBA. For all other possible values, please refer to mallopt(). NOTE: Modifying these variables increases the chances of surfacing existing user memory defects such as buffer overrun. WARNINGSmalloc() functions use brk() and sbrk() (see brk(2)) to increase the address space of a process. Therefore, an application program that uses brk() or sbrk() must not use them to decrease the address space, because this confuses the malloc() functions. free() and realloc() do not check their pointer argument for validity. The following actions are considered bad programming practices and should not be done. The results are unpredictable, probably undesirable and not supported. Examples of undesirable results are loss of data, memory fault, bus error or infinite loop.
The following actions are strongly discouraged and may be unsupported in a future version of malloc():
Undocumented features of earlier memory allocators have not been duplicated. Applications which used any of the above bad programming practices or discouraged practices are not guaranteed to continue functioning at future releases. COMPATIBILITYThe only external difference between the old malloc(3X) allocator and the malloc(3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The malloc(3C) allocator returns a valid memory address. This is not a concern for most applications. By default, SBA (Small Block Allocation) is turned on for Itanium-based systems and is turned off for PA-RISC systems. This was due to performance concerns. Please refer to the EXTERNAL INFLUENCES section of this man page for details. STANDARDS CONFORMANCEmalloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C calloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C free(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C mallinfo(): SVID2, XPG2 mallopt(): SVID2, SVID3, XPG2 realloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C |
|