MALLOC(3) NEWLIB MALLOC(3)NAME
2.23 `malloc', `realloc', `free'--manage memory
SYNOPSIS
#include <stdlib.h>
void *malloc(size_t NBYTES);
void *realloc(void *APTR, size_t NBYTES);
void *reallocf(void *APTR, size_t NBYTES);
void free(void *APTR);
void *memalign(size_t ALIGN, size_t NBYTES);
size_t malloc_usable_size(void *APTR);
void *_malloc_r(void *REENT, size_t NBYTES);
void *_realloc_r(void *REENT,
void *APTR, size_t NBYTES);
void *_reallocf_r(void *REENT,
void *APTR, size_t NBYTES);
void _free_r(void *REENT, void *APTR);
void *_memalign_r(void *REENT,
size_t ALIGN, size_t NBYTES);
size_t _malloc_usable_size_r(void *REENT, void *APTR);
DESCRIPTION
These functions manage a pool of system memory.
Use `malloc' to request allocation of an object with at least NBYTES
bytes of storage available. If the space is available, `malloc'
returns a pointer to a newly allocated block as its result.
If you already have a block of storage allocated by `malloc', but
you no longer need all the space allocated to it, you can make it
smaller by calling `realloc' with both the object pointer and the new
desired size as arguments. `realloc' guarantees that the contents of
the smaller object match the beginning of the original object.
Similarly, if you need more space for an object, use `realloc' to
request the larger size; again, `realloc' guarantees that the beginning
of the new, larger object matches the contents of the original object.
When you no longer need an object originally allocated by `malloc'
or `realloc' (or the related function `calloc'), return it to the mem‐
ory storage pool by calling `free' with the address of the object as
the argument. You can also use `realloc' for this purpose by calling
it with `0' as the NBYTES argument.
The `reallocf' function behaves just like `realloc' except if the
function is required to allocate new storage and this fails. In this
case `reallocf' will free the original object passed in whereas `real‐
loc' will not.
The `memalign' function returns a block of size NBYTES aligned to a
ALIGN boundary. The ALIGN argument must be a power of two.
The `malloc_usable_size' function takes a pointer to a block allo‐
cated by `malloc'. It returns the amount of space that is available in
the block. This may or may not be more than the size requested from
`malloc', due to alignment or minimum size constraints.
The alternate functions `_malloc_r', `_realloc_r', `_reallocf_r',
`_free_r', `_memalign_r', and `_malloc_usable_size_r' are reentrant
versions. The extra argument REENT is a pointer to a reentrancy struc‐
ture.
If you have multiple threads of execution which may call any of
these routines, or if any of these routines may be called reentrantly,
then you must provide implementations of the `__malloc_lock' and
`__malloc_unlock' functions for your system. See the documentation for
those functions.
These functions operate by calling the function `_sbrk_r' or `sbrk',
which allocates space. You may need to provide one of these functions
for your system. `_sbrk_r' is called with a positive value to allocate
more space, and with a negative value to release previously allocated
space if it is no longer required. *Note Stubs::.
RETURNS
`malloc' returns a pointer to the newly allocated space, if successful;
otherwise it returns `NULL'. If your application needs to generate
empty objects, you may use `malloc(0)' for this purpose.
`realloc' returns a pointer to the new block of memory, or `NULL' if
a new block could not be allocated. `NULL' is also the result when you
use ``realloc(APTR,0)'' (which has the same effect as ``free(APTR)'').
You should always check the result of `realloc'; successful realloca‐
tion is not guaranteed even when you request a smaller object.
`free' does not return a result.
`memalign' returns a pointer to the newly allocated space.
`malloc_usable_size' returns the usable size.
PORTABILITY
`malloc', `realloc', and `free' are specified by the ANSI C standard,
but other conforming implementations of `malloc' may behave differently
when NBYTES is zero.
`memalign' is part of SVR4.
`malloc_usable_size' is not portable.
Supporting OS subroutines required: `sbrk'.
SEE ALSOmalloc is part of the library. The full documentation for is main‐
tained as a Texinfo manual. If info and are properly installed at your
site, the command
info
will give you access to the complete manual.
NEWLIB April 2010 MALLOC(3)
