./_Man_SunOS_4.1.3_html/html3/malloc.3v.html

Manual page for MALLOC(3V)

malloc, free, realloc, calloc, cfree, memalign, valloc, mallocmap, mallopt, 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 coalescing 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(), realloc(), 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 unaltered. For backwards compatibility, realloc() accepts a pointer to a block freed since the most recent call to malloc(), calloc(), realloc(), 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. mallocmap() 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 containing small blocks. Under this small block algorithm, a request to malloc() 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 (numlblks) to value. The holding blocks each contain numlblks blocks. numlblks must be greater than 1. The default 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 describing 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 behavior 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 elsize 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() return 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 alloca() 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 allocation 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.

DIAGNOSTICS

More detailed diagnostics can be made available to programs using malloc(), 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(), memalign(), cfree(), and free(). The value of level is interpreted as follows:

Level 0: malloc(), calloc(), realloc(), valloc(), memalign(), 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 examined on every call to the above routines.

malloc_debug() returns the previous error diagnostic level. The default 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 significant 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 degradation of performance results. The semantics of free() should be changed so that the contents of a previously freed block are undefined.