void
*
malloc(
size_t size
)
void
*
calloc(
size_t number
, size_t size
)
void
*
realloc(
void *ptr
, size_t size
)
void
free(
void *ptr
)
const
char
*
_malloc_options;
)
function allocates
size
bytes of uninitialized memory.
The allocated space is suitably aligned (after possible pointer coercion)
for storage of any type of object.
The
calloc()
function allocates space for
number
objects,
each
size
bytes in length.
The result is identical to calling
malloc()
with an argument of
``number * size'',
with the exception that the allocated memory is explicitly initialized
to zero bytes.
The
realloc()
function changes the size of the previously allocated memory referenced by
ptr
to
size
bytes.
The contents of the memory are unchanged up to the lesser of the new and
old sizes.
If the new size is larger,
the value of the newly allocated portion of the memory is undefined.
Upon success, the memory referenced by
ptr
is freed and a pointer to the newly allocated memory is returned.
Note that
realloc()
may move the memory allocation, resulting in a different return value than
ptr
.
If
ptr
is
NULL
,
the
realloc()
function behaves identically to
malloc(
)
for the specified size.
The
free()
function causes the allocated memory referenced by
ptr
to be made available for future allocations.
If
ptr
is
NULL
,
no action occurs.
The
``name''
of the file referenced by the symbolic link named
/etc/malloc.conf
,
the value of the environment variable
MALLOC_OPTIONS
,
and the string pointed to by the global variable
_malloc_options
will be interpreted, in that order, character by character as flags.
Most flags are single letters, where uppercase indicates that the behavior is set, or on, and lowercase means that the behavior is not set, or off.
)
system call.
),
realloc(
)
will be initialized to 0xa5.
All memory returned by
free(
),
realloc(
)
will be initialized to 0x5a.
This is intended for debugging and will impact performance negatively.
NULL
pointer instead of
a valid pointer.
(The default behavior is to make a minimal allocation and return a
pointer to it.)
This option is provided for System V compatibility.
This option is incompatible with the
``X''
option.
stderr
and cause the program to drop
core (using
abort(3)).
This option should be set at compile time by including the following in
the source code:
_malloc_options = "X";
),
realloc(
)
will be initialized to 0.
Note that this initialization only happens once for each byte, so
realloc(
)
call do not zero memory that was previously allocated.
This is intended for debugging and will impact performance negatively.
The ``J'' and ``Z'' options are intended for testing and debugging. An application which changes its behavior when these options are used is flawed.
Memory is conceptually broken into equal-sized chunks, where the chunk size is a power of two that is greater than the page size. Chunks are always aligned to multiples of the chunk size. This alignment makes it possible to find metadata for user objects very quickly.
User objects are broken into three categories according to size: small, large, and huge. Small objects are no larger than one half of a page. Large objects are smaller than the chunk size. Huge objects are a multiple of the chunk size. Small and large objects are managed by arenas; huge objects are managed separately in a single data structure that is shared by all threads. Huge objects are used by applications infrequently enough that this single data structure is not a scalability issue.
Each chunk that is managed by an arena tracks its contents in a page map as runs of contiguous pages (unused, backing a set of small objects, or backing one large object). The combination of chunk alignment and chunk page maps makes it possible to determine all metadata regarding small and large allocations in constant time.
Small objects are managed in groups by page runs. Each run maintains a bitmap that tracks which regions are in use. Allocation requests that are no more than half the quantum (see the ``Q'' option) are rounded up to the nearest power of two (typically 2, 4, or 8). Allocation requests that are more than half the quantum, but no more than the maximum quantum-multiple size class (see the ``S'' option) are rounded up to the nearest multiple of the quantum. Allocation requests that are larger than the maximum quantum-multiple size class, but no larger than one half of a page, are rounded up to the nearest power of two. Allocation requests that are larger than half of a page, but small enough to fit in an arena-managed chunk (see the ``K'' option), are rounded up to the nearest run size. Allocation requests that are too large to fit in an arena-managed chunk are rounded up to the nearest multiple of the chunk size.
Allocations are packed tightly together, which can be an issue for multi-threaded applications. If you need to assure that allocations do not suffer from cache line sharing, round your allocation requests up to the nearest multiple of the cache line size.
It is probably also a good idea to recompile the program with suitable options and symbols for debugger support.
If the program starts to give unusual results, coredump or generally behave differently without emitting any of the messages mentioned in the next section, it is likely because it depends on the storage being filled with zero bytes. Try running it with the ``Z'' option set; if that improves the situation, this diagnosis has been confirmed. If the program still misbehaves, the likely problem is accessing memory outside the allocated area.
Alternatively, if the symptoms are not easy to reproduce, setting the ``J'' option may help provoke the problem.
In truly difficult cases, the ``U'' option, if supported by the kernel, can provide a detailed trace of all calls made to these functions.
Unfortunately this implementation does not provide much detail about the problems it detects; the performance impact for storing such information would be prohibitive. There are a number of allocator implementations available on the Internet which focus on detecting and pinpointing problems by trading performance for extra sanity checks and detailed diagnostics.
STDERR_FILENO
.
Errors will result in the process dumping core.
If the
``A''
option is set, all warnings are treated as errors.
The
_malloc_message
variable allows the programmer to override the function which emits
the text strings forming the errors and warnings if for some reason
the
stderr
file descriptor is not suitable for this.
Please note that doing anything which tries to allocate memory in
this function is likely to result in a crash or deadlock.
All messages are prefixed by
``progname<.blm Pp:
(malloc)
. >
''
)
and
calloc(
)
functions return a pointer to the allocated memory if successful; otherwise
a
NULL
pointer is returned and
errno
is set to
ENOMEM
.
The
realloc()
function returns a pointer, possibly identical to
ptr
,
to the allocated memory
if successful; otherwise a
NULL
pointer is returned, and
errno
is set to
ENOMEM
if the error was the result of an allocation failure.
The
realloc()
function always leaves the original buffer intact
when an error occurs.
The
free()
function returns no value.
MALLOC_OPTIONS
MALLOC_OPTIONS
is set, the characters it contains will be interpreted as flags to the
allocation functions.
ln -s 'A' /etc/malloc.conf
To specify in the source that a program does no return value checking on calls to these functions:
_malloc_options = "X";
),
calloc(
),
realloc(
)
and
free(
)
functions conform to
ISO/IEC 9899:1990 (``ISO C90'') .