Content-type: text/html Man page of malloc

malloc

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

alloca, calloc, free, mallinfo, malloc, mallopt, realloc, valloc - Provides a memory allocator  

LIBRARY

Standard C Library (libc.so, libc.a) Berkeley Compatibility Library (libbsd.a)  

SYNOPSIS

#include <stdlib.h>

void *calloc(
        size_t num_of_elts,
        size_t elt_size);

void free(
        void *pointer);

void *malloc(
        size_t size);

void *realloc(
        void *pointer,
        size_t size);

void *valloc(
        size_t size);

The following function definitions do not conform to current standards and are supported only for backward compatibility:

char *valloc( /* libbsd.a version */
        size_t size);    /* returns pointer to char */

#include <alloca.h> void *alloca(
        int size);

The following function definitions are provided only for System V compatibility:

#include <malloc.h>

struct mallinfo mallinfo(void);

int mallopt(
        int command,
        int value*O);  

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

calloc(), free(), malloc(), realloc():  XPG4, XPG4-UNIX

valloc():  XPG4-UNIX

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

Specifies a number of bytes of memory. Points to the block of memory that was returned by the malloc() or calloc() function. Specifies a mallopt() function command. Specifies M_MXFAST, M_NLBLKS, M_GRAIN, or M_KEEP. Specifies the number of elements in the array. Specifies the size of each element in the array.  

DESCRIPTION

The malloc() and free() functions provide a simple, general-purpose memory allocation package.

The malloc() function returns a pointer to a block of memory of at least the number of bytes specified by the size parameter. The block is aligned so that it can be used for any type of data. If the size parameter is 0 (zero), the malloc() function returns a null pointer.

The free() function frees the block of memory pointed to by the pointer parameter for further allocation. The block pointed to by the pointer parameter must have been previously allocated as follows: By either the malloc(), realloc(), or calloc() functions. [XPG4-UNIX]  By either the malloc(), realloc(), calloc(), or valloc() functions.

The realloc() function changes the size of the block of memory pointed to by the pointer parameter to the number of bytes specified by the size parameter, and returns a pointer to the block. The contents of the block remain unchanged up to the lesser of the old and new sizes. If necessary, a new block is allocated, and data is copied to it. If the pointer parameter is a null pointer, the realloc() function simply allocates a new block of the requested size. If the size parameter is 0 (zero) and pointer is not a null pointer, the realloc() function frees the specified block.

The calloc() function allocates space for an array with the number of elements specified by the num_of_elts parameter, where each element is of the size specified by the elt_size parameter. The space is initialized to zeros.

[Digital]  The alloca() function allocates the number of bytes of space specified by the size parameter in the stack frame of the caller. This space is automatically freed when the function that called the alloca() function returns to its caller. The alloca() function requires inclusion of <alloca.h>. Without this header file, alloca() allocates memory in the heap instead of the stack; this memory is not necessarily freed when the calling routine exits.

The valloc() function has the same effect as malloc(), except that the allocated memory is automatically aligned to a page boundary (that is, the value returned by a call to getpagesize()).

The mallopt() and mallinfo() functions are intended to allow tuning the allocation algorithm at execution time. They have no effect on the current Tru64 UNIX implementation of memory allocation. See the NOTES section for details.

The mallopt() function can be called repeatedly, but parameters cannot be changed after the first small block is allocated from a holding block. If the mallopt() function is called again after the first small block is allocated, it returns an error.

The mallinfo() function can be used during program development to determine the best settings of these parameters for a particular application. It must only be called after some storage has been allocated. Information describing space usage is returned. Refer to the /usr/include/malloc.h header file for details of the mallinfo structure.  

Tuning Memory Allocation

The behavior of these memory allocation functions can be tuned to optimize their performance in a particular application.

The following variables control how the functions operate. Note that these variables and their effects are specific to the current Tru64 UNIX memory allocation implementation. The default values for these variables are specified by libc. To specify values other than the defaults, create a module containing definitions for the complete set of variables and include that module in your compilation. (If you define only some of these variables, your compilation will produce "multiply defined" errors if you link the program nonshared.) For each variable in this list, the default value is indicated after the equal sign.

Except where noted, these variables also apply to the functions described in amalloc(3). The variable __delayed_free is used to cause the free function to use a ``delay'' slot (of size 1). This means that any time you call free, it saves your pointer and actually frees what you last called free with. This is intended to compensate for misuse of realloc, where the user frees a pointer and then calls realloc with it.

Because the delay slot is shared across all threads, this feature will not provide reliable protection for multithreaded applications. Sharing the delay slot also results in it being accessed internally with atomic instruction sequences, which can create a bottleneck on multiCPU systems.
A value of 1 turns this feature on for single-threaded applications. A value of 2 turns this feature on for both single and multithreaded applications. A value of 0 (zero) turns this feature off. All other values cause undefined behavior. It is recommended that all multithreaded applications should try to use the value 0 or 1. The default value of 2 will change to 1 in a future release. The variable __fast_free_max is the maximum number of small buffers that malloc retains in the free list without attempting to coalesce. This number is further adjusted by the number of megabytes in the user heap. As the heap size increases, this number in reduced by 1 for each 10 MB of heap so that at a heap size of 130 MB only one buffer of each type is held in the free list.
Increasing the value of __fast_free_max increases both execution speed and overhead (the size of the heap in relation to the memory requested). The variable __first_fit is currently intended only for performance critical multithreaded applications. It should not be used with single threaded applications. Its value is used to allow malloc and amalloc to skip up to a larger internal cache list if the optimum node size list is found to be in use by another thread. The allowed values are 0, 1, and 2. Do not use any other value. A value of 0 disables this feature. A value of 1 allows the next larger list to be used, and a value of 2 allows the next list after that to also be used (three lists in total).
Increasing the value of __first_fit can increase both execution speed and memory consumption of multithreaded applications making heavy concurrent use of either malloc functions or the same arena with amalloc functions. The __madvisor variable controls how malloc communicates memory usage information to the kernel. Permissible values for __madvisor are 0 and 1. If the variable value is 1, any physical memory associated with the virtual memory range is removed, reducing the resident set size (RSS). The kernel does not need to swap this memory out.
Setting a value of 1 for __madvisor results in a trivial decrease in execution speed. If execution speed is important, leave the setting at the default value of 0. (Does not apply to amalloc functions.) The __max_cache variable suggests the number of internal cache (lookaside) lists to be used by malloc and amalloc. Each list contains blocks within the same size range. A larger value of __max_cache causes the internal caching of larger sized blocks. The currently allowable values for this variable are 15, 18, 21, 24, and 27. Do not use any other value. The given values correspond to lists containing nodes up to 632, 1272, 2552, 5112, and 10232 bytes in size, respectively. The maximum length of the lists is determined by the __fast_free_max variable described elsewhere in this section.
Application requests for storage that can be satisfied from a node on a cache list typically happen somewhat faster than those that cannot. Increasing the value of this variable can increase both the execution speed and that memory consumption of an application that allocates nodes in the given size range. The variable __mingrow is the minimum size that the heap is allowed to grow in response to any request for a buffer that would grow the heap. The amount to grow is the larger of __mingrow or __mingrowfactor * heap_size_in_bytes. The value of this variable is used in whole-page increments; any value that is not an integral multiple of the page size is rounded upward to the next whole number of pages.
The __mingrow and __mingrowfactor variables control compromises between speed and memory usage; increasing either or both of them increases overhead but decreases execution time. The variable __mingrowfactor is the minimum fraction that the heap will be allowed to grow. The actual amount grown is the larger of __mingrowO or __mingrowfactor * heap_size_in_bytes. The variable __minshrink is the minimum size that the heap is allowed to shrink in response to the freeing of space at the end of the heap. The heap will shrink if the space is greater than __minshrink and greater than __minshrinkfactor * heap_size_in_bytes.
This variable has no effect unless __noshrink is 0. The variable __minshrinkfactor is the minimum fraction that the heap is allowed to shrink in response to the freeing of space at the end of the heap. The heap will shrink if the space is greater than __minshrink and greater than __minshrinkfactor * heap_size_in_bytes.
This variable has no effect unless __noshrink is 0. The variable __noshrink controls management of the heap size (which in turn controls the size of the required swap area). As the user makes calls to free() or realloc(), the memory associated with the call can be put back into the pool of free memory. Permissible values for __noshrink are 0 and 1.
If the memory that is freed resides at the end of the heap and meets the constraints of __minshrink and __minshrinkfactor, it can be returned to the kernel by sbrk(nnn) if __noshrink is 0. If __noshrink is 1, no attempts are made to return the freed memory.
Set __noshrink to 1 if execution speed is more important than economy of memory usage. The variable __sbrk_override controls the manner in which the heap growth is obtained. If this variable is set to 1 and the call to sbrk to grow the heap fails, a call is made to mmap to attempt to obtain memory. This technique is extremely valuable to programs running in taso mode. (Does not apply to amalloc functions.) The use of this method to obtain heap space will cause sbrk(0) to return a value that does not reflect the true end of the heap. The __small_buff variable affects how malloc allocates space for extremely small buffers. If the variable is 1, malloc allocates 24 bytes for requests of 1 to 15 bytes; if it is 0, the buffer allocated is 32 bytes. The size of 32 bytes is required by X/Open guidelines specifying that a buffer must be so aligned that it can be assigned to any type of object. Permissible values for __small_buff are 0 and 1.
If the process is using a great many small (1 to 15 byte) buffers, setting __small_buff to 1 reduces heap overhead. The variable __taso_mode is set to 1 to indicate that the program is executing in taso mode. If the variable is set to 1, the pointers returned by malloc and realloc are bounds checked and the ENOMEM error is returned if the pointer exceeds MAXINT.
 

NOTES

The mallopt() and mallinfo() functions are not supported for multithreaded applications.

The mallopt() and mallinfo() functions are designed for tuning a specific algorithm. The Tru64 UNIX operating system uses a new, more efficient algorithm. The mallopt() and mallinfo() functions are provided for System V compatibility only and should not be used by new applications. The behavior of the current malloc() and free() functions is not be affected by calls to mallopt(). The structure returned by the mallinfo() function might not contain any useful information.

The valloc() function is scheduled to be withdrawn from a future version of the X/Open CAE Specification.  

RESTRICTIONS

Because the alloca() function requires inclusion of <alloca.h> in order to work correctly, this function is not portable.

Usage of brk(), sbrk(), or other virtual memory primitives can interfere with the operation of malloc() and its associated functions.  

RETURN VALUES

Each of the allocation functions returns a pointer to space that is suitably aligned for storage of any type of object. Cast the pointer to the type pointer-to-element before using it.

The malloc(), realloc(), calloc(), and valloc() functions return a null pointer if no memory is available or if the memory arena has been corrupted by storing outside the bounds of a block. When this happens, the block pointed to by the pointer parameter could be destroyed.

Upon successful completion, the mallopt() function returns 0 (zero). If the argument makes no sense, mallopt() returns -1 and sets errno to indicate the error. Otherwise, another nonzero value is returned.

The mallinfo() function returns a pointer to a mallinfo structure, defined in the /usr/include/malloc.h header file.  

ERRORS

The malloc(), calloc(), realloc(), and valloc() functions set errno to the specified values for the following conditions:

Insufficient storage space is available. [Digital]  For malloc(), this value indicates that the value of the size parameter is out of range.

[Digital]  For realloc(), this value indicates that the buffer is already free.

The mallopt() function sets errno to the specified values for the following conditions:

The value argument makes no sense. Conditions that can cause this error include: M_MXFAST argument < 0 M_NBLKS argument <= 1 M_GRAIN argument <= 0 All commands after the first small block is allocated An unknown command

Additionally, malloc() and its associated routines call other libc routines, which can set errno (for example, sbrk()).  

RELATED INFORMATION

Functions: amalloc(3), sysconf(3)

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
Tuning Memory Allocation
NOTES
RESTRICTIONS
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:29 GMT, October 02, 2010