FreeBSD Manual Pages
MALLOC(3V) MALLOC(3V) NAME malloc, free, realloc, calloc, cfree, memalign, valloc, mallocmap, mal- lopt, mallinfo, malloc_debug, malloc_verify, alloca - memory allocator SYNOPSIS #include <malloc.h> char *malloc(size) unsigned size; int free(ptr) char *ptr; char *realloc(ptr, size) char *ptr; unsigned size; char *calloc(nelem, elsize) unsigned nelem, elsize; int cfree(ptr) char *ptr; char *memalign(alignment, size) unsigned alignment; unsigned size; char *valloc(size) unsigned size; void mallocmap() int mallopt(cmd, value) int cmd, value; struct mallinfo mallinfo() #include <alloca.h> char *alloca(size) int size; SYSTEM V SYNOPSIS #include <malloc.h> void *malloc(size) size_t size; void free(ptr) void *ptr; void *realloc(ptr, size) void *ptr; size_t size; void *calloc(nelem, elsize) size_t nelem; size_t elsize; void *memalign(alignment, size) size_t alignment; size_t size; void *valloc(size) size_t size; The XPG2 versions of the functions listed in this section are declared as they are in SYNOPSIS above, except free(), which is declared as: void free(ptr) char *ptr; DESCRIPTION These routines provide a general-purpose memory allocation package. They maintain a table of free blocks for efficient allocation and coa- lescing of free storage. When there is no suitable space already free, the allocation routines call sbrk() (see brk(2)) to get more memory from the system. Each of the allocation routines returns a pointer to space suitably aligned for storage of any type of object. Each returns a NULL pointer if the request cannot be completed (see DIAGNOSTICS). malloc() returns a pointer to a block of at least size bytes, which is appropriately aligned. free() releases a previously allocated block. Its argument is a pointer to a block previously allocated by malloc(), calloc(), real- loc(), malloc(), or memalign(). realloc() changes the size of the block referenced 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. If unable to honor a reallocation request, realloc() leaves its first argument unal- tered. For backwards compatibility, realloc() accepts a pointer to a block freed since the most recent call to malloc(), calloc(), real- loc(), valloc(), or memalign(). Note: using realloc() with a block freed before the most recent call to malloc(), calloc(), realloc(), valloc(), or memalign() is an error. calloc() uses malloc() to allocate space for an array of nelem elements of size elsize, initializes the space to zeros, and returns a pointer to the initialized block. The block can be freed with free() or cfree(). 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 alignment. Note: the value of alignment must be a power of two, and must be greater than or equal to the size of a word. valloc(size) is equivalent to memalign(getpagesize(), size). mallocmap() prints a map of the heap to the standard output. mal- locmap() prints each block's address, size (in bytes) and status (free or busy). A block must have a size that is no larger than the current extent of the heap. mallopt() allows quick allocation of small blocks of memory. mallopt() tells subsequent calls to malloc() to allocate holding blocks contain- ing small blocks. Under this small block algorithm, a request to mal- loc() for a small block of memory returns a pointer to one of the pre- allocated small blocks. Different holding blocks are created as needed for different sizes of small blocks. cmd may be one of the following values, defined in <malloc.h>: M_MXFAST Set the maximum size of blocks to be allocated using the small block algorithm (maxfast) to value. The algorithm allocates all blocks smaller than maxfast in large groups and then doles them out very quickly. Initially, maxfast is 0 and the small block algorithm is disabled. M_NLBLKS Set the number of small blocks in a holding block (numl- blks) to value. The holding blocks each contain numl- blks blocks. numlblks must be greater than 1. The de- fault value for numlblks is 100. M_GRAIN Set the granularity for small block requests (grain) to value. The sizes of all blocks smaller than maxfast are rounded up to the nearest multiple of grain. grain must be greater than 0. The default value of grain is the smallest number of bytes which will allow alignment of any data type. When grain is set, value is rounded up to a multiple of this default. M_KEEP Preserve data in a freed block until the next malloc(), realloc(), or calloc(). This option is provided only for compatibility with the old version of malloc() and is not recommended. mallopt() may be called repeatedly, but may not be called after the first small block is allocated. mallinfo() can be used during program development to determine the best settings for the parameters set by mallopt(). Do not call mallinfo() until after a call to malloc(). mallinfo() provides information de- scribing space usage. It returns a mallinfo structure, defined in <malloc.h> as: struct mallinfo { int arena; /* total space in arena */ int ordblks; /* number of ordinary blocks */ int smblks; /* number of small blocks */ int hblks; /* number of holding blocks */ int hblkhd; /* space in holding block headers */ 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; /* cost of enabling keep option */ int mxfast; /* max size of small blocks */ int nlblks; /* number of small blocks in a holding block */ int grain; /* small block rounding factor */ int uordbytes; /* space (including overhead) allocated in ord. blks */ int allocated; /* number of ordinary blocks allocated */ int treeoverhead; /* bytes used in maintaining the free tree */ }; alloca() allocates size bytes of space in the stack frame of the caller, and returns a pointer to the allocated block. This temporary space is automatically freed when the caller returns. Note that if the allocated block is beyond the current stack limit, the resulting behav- ior is undefined. malloc(), realloc(), memalign() and valloc() return a non-NULL pointer if size is 0, and calloc() returns a non-NULL pointer if nelem or el- size is 0, but these pointers should not be dereferenced. Note: Always cast the value returned by malloc(), realloc(), calloc(), memalign(), valloc() or alloca(). SYSTEM V DESCRIPTION The XPG2 versions of malloc(), realloc(), memalign() and valloc() re- turn NULL if size is 0. The XPG2 version of calloc() returns NULL if nelem or elsize is 0. RETURN VALUES On success, malloc(), calloc(), realloc(), memalign(), valloc() and al- loca() return a pointer to space suitably aligned for storage of any type of object. On failure, they return NULL. free() and cfree() return: 1 on success. 0 on failure and set errno to indicate the error. mallopt() returns 0 on success. If mallopt() is called after the allo- cation of a small block, or if cmd or value is invalid, it returns a non-zero value. mallinfo() returns a struct mallinfo. SYSTEM V RETURN VALUES If size is 0, the XPG2 versions of malloc(), realloc(), memalign() and valloc() return NULL. If nelem or elsize is 0, the XPG2 version of calloc() returns NULL. free() does not return a value. ERRORS malloc(), calloc(), realloc(), valloc(), memalign(), cfree(), and free() will each fail if one or more of the following are true: EINVAL An invalid argument was specified. The value of ptr passed to free(), cfree(), or realloc() was not a pointer to a block previously allocated by malloc(), calloc(), realloc(), valloc(), or memalign(). The allocation heap is found to have been corrupted. More detailed information may be obtained by enabling range checks using malloc_debug(). ENOMEM size bytes of memory could not be allocated. FILES /usr/lib/debug/malloc.o diagnostic versions of malloc() routines. /usr/lib/debug/mallocmap.o routines to print a map of the heap. SEE ALSO csh(1), ld(1), brk(2), getrlimit(2), sigvec(2), sigstack(2) Stephenson, C.J., Fast Fits, in Proceedings of the ACM 9th Symposium on Operating Systems, SIGOPS Operating Systems Review, vol. 17, no. 5, Oc- tober 1983. Core Wars, in Scientific American, May 1984. DIAGNOSTICS More detailed diagnostics can be made available to programs using mal- loc(), calloc(), realloc(), valloc(), memalign(), cfree(), and free(), by including a special relocatable object file at link time (see FILES). This file also provides routines for control of error handling and diagnosis, as defined below. Note: these routines are not defined in the standard library. int malloc_debug(level) int level; int malloc_verify() malloc_debug() sets the level of error diagnosis and reporting during subsequent calls to malloc(), calloc(), realloc(), valloc(), mema- lign(), cfree(), and free(). The value of level is interpreted as fol- lows: Level 0 malloc(), calloc(), realloc(), valloc(), mema- lign(), cfree(), and free() behave the same as in the standard library. Level 1 The routines abort with a message to the standard error if errors are detected in arguments or in the heap. If a bad block is encountered, its address and size are included in the message. Level 2 Same as level 1, except that the entire heap is ex- amined on every call to the above routines. malloc_debug() returns the previous error diagnostic level. The de- fault level is 1. malloc_verify() attempts to determine if the heap has been corrupted. It scans all blocks in the heap (both free and allocated) looking for strange addresses or absurd sizes, and also checks for inconsistencies in the free space table. malloc_verify() returns 1 if all checks pass without error, and otherwise returns 0. The checks can take a signifi- cant amount of time, so it should not be used indiscriminately. WARNINGS alloca() is machine-, compiler-, and most of all, system-dependent. Its use is strongly discouraged. See getrlimit(2), sigvec(2), sigstack(2), csh(1), and ld(1). NOTES Because malloc(), realloc(), memalign() and valloc() return a non-NULL pointer if size is 0, and calloc() returns a non-NULL pointer if nelem or elsize is 0, a zero size need not be treated as a special case if it should be passed to these functions unpredictably. Also, the pointer returned by these functions may be passed to subsequent invocations of realloc(). SYSTEM V NOTES The XPG2 versions of the allocation routines return NULL when passed a zero size (see SYSTEM V DESCRIPTION above). BUGS Since realloc() accepts a pointer to a block freed since the last call to malloc(), calloc(), realloc(), valloc(), or memalign(), a degrada- tion of performance results. The semantics of free() should be changed so that the contents of a previously freed block are undefined. 24 January 1990 MALLOC(3V)
NAME | SYNOPSIS | SYSTEM V SYNOPSIS | DESCRIPTION | SYSTEM V DESCRIPTION | RETURN VALUES | SYSTEM V RETURN VALUES | ERRORS | FILES | SEE ALSO | DIAGNOSTICS | WARNINGS | NOTES | SYSTEM V NOTES | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=alloca&manpath=SunOS+4.1.3>