4.3BSD-UWisc/man/cat3/malloc.3

MALLOC(3)           UNIX Programmer's Manual            MALLOC(3)



NAME
     malloc, free, realloc, calloc, alloca - memory allocator

SYNOPSIS
     char *malloc(size)
     unsigned size;

     free(ptr)
     char *ptr;

     char *realloc(ptr, size)
     char *ptr;
     unsigned size;

     char *calloc(nelem, elsize)
     unsigned nelem, elsize;

     char *alloca(size)
     int size;

DESCRIPTION
     _M_a_l_l_o_c and _f_r_e_e provide a general-purpose memory allocation
     package.  _M_a_l_l_o_c returns a pointer to a block of at least
     _s_i_z_e bytes beginning on a word boundary.

     The argument to _f_r_e_e is a pointer to a block previously
     allocated by _m_a_l_l_o_c; this space is made available for
     further allocation, but its contents are left undisturbed.

     Needless to say, grave disorder will result if the space
     assigned by _m_a_l_l_o_c is overrun or if some random number is
     handed to _f_r_e_e.

     _M_a_l_l_o_c maintains multiple lists of free blocks according to
     size, allocating space from the appropriate list.  It calls
     _s_b_r_k (see _b_r_k(2)) to get more memory from the system when
     there is no suitable space already free.

     _R_e_a_l_l_o_c changes the size of the block pointed to by _p_t_r to
     _s_i_z_e 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.

     In order to be compatible with older versions, _r_e_a_l_l_o_c also
     works if _p_t_r points to a block freed since the last call of
     _m_a_l_l_o_c, _r_e_a_l_l_o_c or _c_a_l_l_o_c; sequences of _f_r_e_e, _m_a_l_l_o_c and
     _r_e_a_l_l_o_c were previously used to attempt storage compaction.
     This procedure is no longer recommended.

     _C_a_l_l_o_c allocates space for an array of _n_e_l_e_m elements of
     size _e_l_s_i_z_e. The space is initialized to zeros.




Printed 12/27/86          May 14, 1986                          1






MALLOC(3)           UNIX Programmer's Manual            MALLOC(3)



     _A_l_l_o_c_a allocates _s_i_z_e bytes of space in the stack frame of
     the caller.  This temporary space is automatically freed on
     return.

     Each of the allocation routines returns a pointer to space
     suitably aligned (after possible pointer coercion) for
     storage of any type of object.  If the space is of _p_a_g_e_s_i_z_e
     or larger, the memory returned will be page-aligned.

SEE ALSO
     brk(2), pagesize(2)

DIAGNOSTICS
     _M_a_l_l_o_c, _r_e_a_l_l_o_c and _c_a_l_l_o_c return a null pointer (0) if
     there is no available memory or if the arena has been
     detectably corrupted by storing outside the bounds of a
     block.  _M_a_l_l_o_c may be recompiled to check the arena very
     stringently on every transaction; those sites with a source
     code license may check the source code to see how this can
     be done.

BUGS
     When _r_e_a_l_l_o_c returns 0, the block pointed to by _p_t_r may be
     destroyed.

     The current implementation of _m_a_l_l_o_c does not always fail
     gracefully when system memory limits are approached.  It may
     fail to allocate memory when larger free blocks could be
     broken up, or when limits are exceeded because the size is
     rounded up.  It is optimized for sizes that are powers of
     two.

     _A_l_l_o_c_a is machine dependent; its use is discouraged.






















Printed 12/27/86          May 14, 1986                          2