malloc(3MALLOC) Memory Allocation Library Functions malloc(3MALLOC)NAME
malloc, free, memalign, realloc, valloc, calloc, mallopt, mallinfo -
memory allocator
SYNOPSIS
cc [ flag ... ] file ... -lmalloc [ library ... ]
#include <stdlib.h>
void *malloc(size_t size);
void free(void *ptr);
void *memalign(size_t alignment, size_t size);
void *realloc(void *ptr, size_t size);
void *valloc(size_t size);
void *calloc(size_t nelem, size_t elsize);
#include <malloc.h>
int mallopt(int cmd, int value);
struct mallinfo mallinfo(void);
DESCRIPTION
The malloc() and free() functions provide a simple general-purpose mem‐
ory allocation package.
The malloc() function 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 have been destroyed. See mallopt()
below for a way to change this behavior. If ptr is a null pointer, no
action occurs.
Undefined results occur if the space assigned by malloc() is overrun or
if some random number is handed to free().
The free() function does not set errno.
The memalign() function 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. The
value of alignment must be a power of two and must be greater than or
equal to the size of a word.
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 lesser of the new and old sizes.
If the new size of the block requires movement of the block, the space
for the previous instantiation of the block is freed. If the new size
is larger, the contents of the newly allocated portion of the block are
unspecified. If ptr is NULL, realloc() behaves like malloc() for the
specified size. If size is 0 and ptr is not a null pointer, the space
pointed to is freed.
The valloc() function has the same effect as malloc(), except that the
allocated memory will be aligned to a multiple of the value returned by
sysconf(_SC_PAGESIZE).
The calloc() function allocates space for an array of nelem elements of
size elsize. The space is initialized to zeros.
The mallopt() function provides for control over the allocation algo‐
rithm. The available values for cmd are:
M_MXFAST Set maxfast to value. The algorithm allocates all
blocks below the size of maxfast in large groups and
then doles them out very quickly. The default value for
maxfast is 24.
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. The sizes of all blocks smaller
than maxfast are considered to be 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 that will allow alignment of any data type. Value
will be rounded up to a multiple of the default when
grain is set.
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
it is not recommended.
These values are defined in the <malloc.h> header.
The mallopt() function can be called repeatedly, but cannot be called
after the first small block is allocated.
The mallinfo() function provides instrumentation describing space
usage. It returns the mallinfo structure with the following members:
unsigned long arena; /* total space in arena */
unsigned long ordblks; /* number of ordinary blocks */
unsigned long smblks; /* number of small blocks */
unsigned long hblkhd; /* space in holding block headers */
unsigned long hblks; /* number of holding blocks */
unsigned long usmblks; /* space in small blocks in use */
unsigned long fsmblks; /* space in free small blocks */
unsigned long uordblks; /* space in ordinary blocks in use */
unsigned long fordblks; /* space in free ordinary blocks */
unsigned long keepcost; /* space penalty if keep option */
/* is used */
The mallinfo structure is defined in the <malloc.h> header.
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
RETURN VALUES
The malloc(), memalign(), realloc(), valloc(), and calloc() functions
return a null pointer if there is not enough available memory. When
realloc() returns NULL, the block pointed to by ptr is left intact. If
size, nelem, or elsize is 0, either a null pointer or a unique pointer
that can be passed to free() is returned. If mallopt() is called after
any allocation or if cmd or value are invalid, a non-zero value is
returned. Otherwise, it returns 0.
ERRORS
If malloc(), calloc(), or realloc() returns unsuccessfully, errno is
set to indicate the error:
ENOMEM size bytes of memory exceeds the physical limits of
your system, and cannot be allocated.
EAGAIN There is not enough memory available at this point in
time to allocate size bytes of memory; but the applica‐
tion could try again later.
USAGE
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.
Function prototypes for malloc(), realloc(), calloc(), and free() are
also defined in the <malloc.h> header for compatibility with old appli‐
cations. New applications should include <stdlib.h> to access the pro‐
totypes for these functions.
Comparative features of the various allocation libraries can be found
in the umem_alloc(3MALLOC) manual page.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSObrk(2), bsdmalloc(3MALLOC), libmtmalloc(3LIB), malloc(3C), mapmal‐
loc(3MALLOC), mtmalloc(3MALLOC), umem_alloc(3MALLOC), watchmalloc(3MAL‐
LOC), attributes(5)SunOS 5.10 11 May 2005 malloc(3MALLOC)
