malloc(3C)

NAME

malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() — 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);

alloca

#include <alloca.h>

void *alloca(size_t size);

SYSTEM V SYNOPSIS (HP-UX)

#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);

Remarks

The 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. Applications that used the malloc(3X) package should still work properly with the new malloc(3C) package. If the old versions must be used, they are provided in files /usr/old/libmalloc3x.a and /usr/old/libmalloc3c.o for Release 8.07 only.

DESCRIPTION

The functions described in this manual entry provide a simple, general purpose memory allocation package:

malloc()

Allocates space for a block of at least size bytes, but does not initialize the space.

calloc()

Allocates space for an array of nelem elements, each of size elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least nelem * elsize bytes.

realloc()

Changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If ptr is a NULL pointer, realloc() behaves like malloc() for the specified size. If size is zero and ptr is not a NULL pointer, the object it points to is freed and NULL is returned.

valloc()

Allocates space for a block of at least size bytes starting on a boundary aligned to a multiple of the value returned by sysconf (__SC_PAGESIZE). This space is uninitialized.

free()

Deallocates the space pointed to by ptr (a pointer to a block previously allocated by malloc(), realloc(), or calloc()) and makes the space available for further allocation. If ptr is a NULL pointer, no action occurs.

mallopt()

Provides for control over the allocation algorithm and other options in the malloc(3C) package. 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, then doles them out very quickly. The default value for maxfast is zero.
M_NLBLKS: Set numlblks to value. The above mentioned ``large groups'' each contain numlblks blocks. numlblks must be greater than 1. 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 zero. The default value of grain is the smallest number of bytes that can accommodate alignment of any data type. value is 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 is not recommended.
M_BLOCK: Block all blockable signals in malloc(), realloc(), calloc(), and free(). This option is provided for those who need to write signal handlers that allocate memory. When set, the malloc(3C) routines can be called from within signal handlers (they become re-entrant). Default action is not to block all blockable signals.
M_UBLOCK: Do not block all blockable signals in malloc(), realloc(), calloc(), and free(). This option cancels signal blocking initiated by the M_BLOCK option.

These values are defined in the <malloc.h> header file.

mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless cmd is set to M_BLOCK or M_UBLOCK).

mallinfo()

Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure:

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 */ 
} 

This structure is defined in the <malloc.h> header file.

Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object.

memorymap()

Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using printf()) to standard output. If the value of the show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written.

The addresses and sizes displayed by memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information.

alloca()

Allocates space from the stack of the caller for a block of at least size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits.

Memory returned by alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by alloca() as parameters to other memory functions is undefined.

The implementation of this routine is system dependent and its use is discouraged.

APPLICATION USAGE

malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap() and alloca() are thread-safe. These interfaces are not async-cancel-safe.

RETURN VALUE

Upon 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.

DIAGNOSTICS

malloc(), 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(), or calloc()) 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

[ENOMEM]: malloc(), realloc(), calloc(), and valloc() set errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises.
[EINVAL]: malloc(), realloc(), calloc(), and valloc() set errno to EINVAL and return a NULL pointer when the memory being managed by malloc() has been detectably corrupted.

WARNINGS

malloc() 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.

If free() or realloc() is passed a pointer that was not the result of a call to malloc(), realloc(), calloc(), or valloc(), or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to malloc(), realloc(), calloc(), valloc(), or free().

The following actions are not supported and cause undesirable effects:

Attempting to free() or realloc() a pointer not generated as the result of a call to malloc(), realloc(), calloc(), or valloc().

The following actions are strongly discouraged and may be unsupported in a future implementation of malloc():

attempting to free() the same block twice,
depending on unmodified contents of a block after it has been freed.

Undocumented features of earlier memory allocators have not been duplicated.

COMPATIBILITY

The 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.

Although the current implementation of malloc(3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to realloc(), calloc(), malloc(), or valloc()), support for these features may be discontinued in a future implementation of malloc(3C) and should not be used.

STANDARDS CONFORMANCE

malloc(): 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