[0m


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



[1mNAME
     [0mmalloc, free, realloc, calloc, _byte_size, _free, _ALLOC_Id,
     _ALLOC_StorageInUse, _ALLOC_StorageFree, _ALLOC_FreeBlocks,
     _ALLOC_ResetBlockMap - memory allocator

[1mSYNOPSIS
     [0m#include <stdlib.h>
     [1mvoid *malloc(size_t size)

     void free(void *ptr)

     void *realloc(void *ptr, size_t size)

     void *calloc(size_t nelem, size_t elsize)

     [0m#include <malloc.h>
     [1msize_t _byte_size(void *ptr)

     void _free(void *ptr)

     const char *_ALLOC_Id(void)

     int _ALLOC_StorageInUse(void)

     int _ALLOC_StorageFree(void)

     int _ALLOC_FreeBlocks(size_t size)

     int _ALLOC_FreeWordsLarge(void)

     int _ALLOC_ResetBlockMap(const unsigned char new[256])

     int _ALLOC_Options(int cmd, int value)

     _ALLOC_info _ALLOC_Info(void);

DESCRIPTION
     [0m_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, and its contents are altered.

     Needless to say, grave disorder will result if the space
     assigned by _m_a_l_l_o_c is overrun or if a block handed to _f_r_e_e
     is used afterwards.  The storage allocator will spot an
     attempt to free an invalid pointer and (by default) will
     output a message on stderr and abort the program via
     _a_b_o_r_t(3).




Printed 13/2/92     Revision 1.6 of 26/11/90			1






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



     _M_a_l_l_o_c maintains multiple lists of free blocks according to
     size, allocating space from the appropriate list.	It calls
     the equivalent of _s_b_r_k and _b_r_k (see _b_r_k(2)) to get more
     memory from the system when there is no suitable space
     already free.  These functions may be used directly if
     required, but they should normally only be used to per-
     manently allocate large amounts of store - there is some
     overhead imposed on the storage allocator in dealing with
     interleaved _m_a_l_l_o_c and _s_b_r_k calls (which will lose some
     storage) and there is no way of freeing the result of a
     _s_b_r_k.  The heap limit should never be lowered using _b_r_k when
     _m_a_l_l_o_c has been used as this will certainly cause the allo-
     cator to fail.  Interleaved use of _s_b_r_k and _m_a_l_l_o_c is not a
     portable feature - such practices destroy the standard BSD43
     allocator.

     _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.  Realloc does not currently reduce the size of the
     block it is passed - but it may do so in the future.

     _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.

     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 storage cannot be
     allocated, or if 0 bytes are requested, both _m_a_l_l_o_c and
     _r_e_a_l_l_o_c return NULL.  On such failures the variable _e_r_r_n_o is
     set to the value [1mENOMEM [0mas defined in <_e_r_r_n_o._h>.

     The remaining functions are specific to this implementation
     of _m_a_l_l_o_c.  The header file <_m_a_l_l_o_c._h> defines prototypes
     for the functions as well as the [1m_ALLOC_Info [0mtype (a struc-
     ture) and various [1m#define [0mvalues.

     __b_y_t_e__s_i_z_e returns the size in bytes of the block pointed to
     by [1mptr [0mor 0 if the pointer is invalid - it never fails and
     only returns 0 on an invalid pointer, so may be used to
     check pointer validity as well as to judge the size of a
     block.

     __f_r_e_e functions like _f_r_e_e except that, when the [1mM_KEEP
     [0moption is specified (see below) it retains the passed
     pointer until the next call to __f_r_e_e.  If the pointer is
     equal to the last pointer no action is taken, if it is dif-
     ferent it is retained and the storage indicated by the pre-
     vious pointer is freed using _f_r_e_e.  This function offers
     some compatibility with old versions of the BSD and System V
     storage allocators.





Printed 13/2/92     Revision 1.6 of 26/11/90			2






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



     __A_L_L_O_C__I_d returns a string which indicates the current revi-
     sion of the storage manager.  The string may not be altered.

     __A_L_L_O_C__S_t_o_r_a_g_e_I_n_U_s_e returns the amount of storage (in bytes)
     currently used by the system - this includes all of the sys-
     tem overhead which is not statically allocated.

     __A_L_L_O_C__F_r_e_e_B_l_o_c_k_s returns the number of blocks of size [1msize
     [0mwords (sizeof (unsigned)) which are currently free.  In the
     default system overwrite checking consumes one extra word
     per block, so a request for w words will actually allocate a
     block of size (w+1).  An indirect consequence of calling
     __A_L_L_O_C__F_r_e_e_B_l_o_c_k_s is that all the free blocks of the given
     size in the system are checked for validity, thus a success-
     ful return from the routine means that the free list for
     that block size is not corrupt.

     __A_L_L_O_C__F_r_e_e_W_o_r_d_s_L_a_r_g_e returns the number of words of free
     storage currently available in the allocator for requests of
     size greater than the block map limit.  It also checks the
     consistency of this allocator.

     __A_L_L_O_C__S_t_o_r_a_g_e_F_r_e_e returns the total number of bytes of free
     storage (excluding the overwrite word in each block).  Thus
     the result of the function is a measure of the available
     storage when external fragmentation is ignored - external
     fragmentation of storage means that a request for a given
     number of bytes may not be satisfied even if it is less than
     __A_L_L_O_C__S_t_o_r_a_g_e_F_r_e_e() because there may not be a contiguous
     region of free store of this size.  Notice that all three of
     these routines describe the storage currently in the heap -
     the potential storage available will normally be more as the
     heap will be extended as required.

     __A_L_L_O_C__R_e_s_e_t_B_l_o_c_k_M_a_p resets the block map of the system.
     The block map is a byte array which maps a request for n
     words into the actual block size (including the overwrite
     guard word) which will be used to satisfy the request.  The
     array can be up to 256 bytes long (for requests up to 255
     words), however the storage manager is currently built to
     only manage requests up to a maximum of 126 words in this
     way.  Requests for more than 126 words (127 words if
     overwrite checking is compiled out) are allocated
     separately.  The routine will fail (returning a non-zero
     value) if it is called after _m_a_l_l_o_c or _r_e_a_l_l_o_c has been used
     for the first time otherwise it returns zero indicating suc-
     cess.  It may be used (normally as the very first function
     call in a program) to tailor the system to the particular
     pattern of allocations which a program generates.	The
     default blockmap is suitable for most programs, including
     programs which do large amounts of allocation and dealloca-
     tion.  A new blockmap would only be of advantage to a



Printed 13/2/92     Revision 1.6 of 26/11/90			3






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



     program which had a very unusal pattern of storage alloca-
     tion.  The function will also fail if the block map is
     invalid - with the current version of the storage manager
     this will occur if entry [1mn [0min the map specifies less than
     [1mn+1 [0mwords, or more than 127 words.  Any entry may specify 0
     words (meaning that allocation will be from the separate
     large block allocator).  Entry 127 [1mmust [0mspecify zero words,
     entries beyond 127 are not examined.

     __A_L_L_O_C__O_p_t_i_o_n_s allows control of various features of the
     storage manager.  The interface is analogous to the System V
     _m_a_l_l_o_p_t function, and the file <_m_a_l_l_o_c._h> contains a [1m#define
     [0mwhich defines _m_a_l_l_o_p_t as __A_L_L_O_C__O_p_t_i_o_n_s.  If any of the Sys-
     tem V options are used the storage manager behaviour is
     reset to resemble a System V storage allocator as closely as
     possible.	In particular _m_a_l_l_o_c and _f_r_e_e calls which fail
     are no longer faulted and storage corruption is ignored.  If
     the __A_L_L_O_C__O_p_t_i_o_n_s call fails it returns non-zero, else it
     returns zero.

     The following command values are supported for compatibility
     with the System V Interface Definition:-

     [1mM_MXFAST  [0mImplements the _m_a_l_l_o_p_t option of the same name.
	       The default _m_a_x_f_a_s_t value is not zero on this sys-
	       tem.  The value supplied is interpreted as the
	       maximum number of bytes to allocate using the fast
	       (small block) allocator.  The block map is reset
	       to agree with this.

     [1mM_NLBLKS  [0mThe value is stored but ignored.  The storage
	       allocator uses constant size chunks of memory for
	       small block allocation - the standard System V
	       storage allocator uses variable size chunks with a
	       fixed number of units (of a given size) in them.

     [1mM_GRAIN   [0mThe value supplied is interpreted as the base size
	       unit for small blocks.  All blocks are a multiple
	       of this (byte) size.  In fact each size generated
	       by this algorithm is rounded up to the next larg-
	       est size (in whole words) which will result in the
	       same number of blocks in a chunk.

     [1mM_KEEP    [0mThis option is for backwards compatibility with
	       old storage allocators, it switches on the facil-
	       ity to retain the last pointer passed to __f_r_e_e
	       until the next call of __f_r_e_e.  The argument is
	       ignored.

     The following commands are specific to this storage alloca-
     tor, in each case the argument is interpreted as a flag
     which allows the switch to be turned on or off.



Printed 13/2/92     Revision 1.6 of 26/11/90			4






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



     [1mM_FLTFREE [0mAbort fault an invalid _f_r_e_e call by calling the
	       fatal error handler (see below).  This is on by
	       default.

     [1mM_FLTMALLOC
	       [0mFault a _m_a_l_l_o_c call which fails (because the sys-
	       tem has run out of memory) rather than returning
	       NULL.  This is off by default.

     [1mM_FLTSMASH
	       [0mFault corruption of the heap as soon as it is
	       detected.  This is on by default.

     [1mM_MALLOC0 [0mReturn valid store in answer to a request for 0
	       bytes.  This is off by default - _m_a_l_l_o_c will
	       return the NULL pointer.  Notice that this does
	       not alter the behaviour of _r_e_a_l_l_o_c when called
	       with a size of 0 - it still passes the supplied
	       pointer to _f_r_e_e and returns NULL.  This facility
	       is off by default.

     The following commands are also specific to this allocator,
     they take a function pointer which may be ((_v_o_i_d(*)())NULL).

     [1mM_WARNING [0mSpecifies a (_v_o_i_d (*)(_c_o_n_s_t _c_h_a_r *)) function to
	       call when outputing a warning message.  The func-
	       tion will be called when a fatal error occurs if a
	       separate handler has not been specified (see
	       below).	On return the allocator will abort the
	       program using _a_b_o_r_t(3).	The argument is an error
	       message string, as described below.

     [1mM_ERROR   [0mSpecifies a (_v_o_i_d (*)(_c_o_n_s_t _c_h_a_r *)) function to
	       call when a fatal error occurs.	The argument is a
	       string describing the error.  If the function
	       returns execution of the program will continue.

     [1mM_NOMEM   [0mSpecifies a (_v_o_i_d *(*)(_s_i_z_e__t)) function to call
	       when storage allocation fails.  The function may
	       make arbitrary calls to the storage manager,
	       although if it calls _m_a_l_l_o_c or _r_e_a_l_l_o_c it must
	       protect itself against being called recursively.
	       The function must return a pointer which will be
	       returned as the result of the original _m_a_l_l_o_c or
	       _r_e_a_l_l_o_c function call.  If the function returns
	       the NULL pointer it is expected to set _e_r_r_n_o to
	       the value [1mENOMEM[0m.

     __A_L_L_O_C__I_n_f_o returns an __A_L_L_O_C__I_n_f_o structure, which is simi-
     lar to the System V _m_a_l_l_i_n_f_o structure and contains similar
     information.  Some values are generated by a heuristic
     method - accurate statistics for this storage manager can be



Printed 13/2/92     Revision 1.6 of 26/11/90			5






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



     obtained using the statistical functions above.

[1mNOTES
     [0mThe functions _m_a_l_l_o_c, _f_r_e_e, _r_e_a_l_l_o_c and _c_a_l_l_o_c are available
     in most storage manager implementations (and in all UNIX
     ones) the other functions are specific to this implementa-
     tion.  The _a_l_l_o_c_a function provided in most BSD43 implemen-
     tations cannot be implemented with some machine/compiler
     architectures - the _a_u_p_c_s(7) is such an architecture.

[1mDIAGNOSTICS
     [0m_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.  Various options in the source
     code allow the memory allocator to call _a_b_o_r_t(3) or some
     program specified function instead if this occurs.

     The allocator is very secure - it checks each block passed
     to _f_r_e_e for overwrite errors and will not free an invalid
     pointer.  It is also very fast for small allocations (less
     than the the block map limit - by default requests for up to
     84 words are satisfied this way).	The old BSD43 _a_l_l_o_c_a call
     should be replaced by appropriate calls to _m_a_l_l_o_c and _f_r_e_e
     which are faster than any possible implementation of _a_l_l_o_c_a
     which conforms to the procedure call mechanism used by
     _c_c(1).

     In the event of storage corruption the allocator will either
     output a message on stderr and abort the program or it will
     simply crash.  In particular overwriting the end of a block
     of store will first corrupt the guard word (in the standard
     system) then the following block.	If the block is allocated
     whatever is using it will go wrong, if it is not allocated
     the first word is used to maintain a list of free blocks and
     so a change to it will probably crash the allocator.

     If necessary the __A_L_L_O_C__S_t_o_r_a_g_e_F_r_e_e function and appropriate
     calls to __b_y_t_e__s_i_z_e can be used to spot storage corruption -
     a single call to __A_L_L_O_C__S_t_o_r_a_g_e_F_r_e_e followed by a call to
     __b_y_t_e__s_i_z_e for each allocated pointer will spot any corrup-
     tion.

     The allocator outputs the following messages on detection of
     errors:

     [1mallocate failed
	       [0mWhen the manager fails to allocate the requested
	       storage; only if allocation fail checking is
	       switched on and a program supplied function to
	       handle allocation failure has not be specified.	-
	       otherwise the _m_a_l_l_o_c, _c_a_l_l_o_c or _r_e_a_l_l_o_c call
	       returns 0 and sets _e_r_r_n_o to [1mENOMEM[0m.




Printed 13/2/92     Revision 1.6 of 26/11/90			6






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



     [1mrecursive [0mIf compiled with reentrancy checking and a recur-
	       sive call to the storage manager occurs (from a
	       signal handler).  The default manager does not
	       check this.  _e_r_r_n_o would be set to [1mEDEADLK[0m.

     [1mno lock   [0mIf reentrancy checking is compiled in this indi-
	       cates an internal error in the manager - otherwise
	       the message will not be produced.  _e_r_r_n_o would be
	       set to [1mENOLCK[0m.

     [1mcannot open <analysis file name>
	       [0mWhen the manager is compiled for storage analysis
	       and the given analysis file cannot be opened.
	       _e_r_r_n_o would be set to the result of the _o_p_e_n(2)
	       call.

     [1mrequest too large
	       [0mIf the manager is compiled with allocation fail
	       checking on large requests this message will be
	       produced when a silly request is made (by default
	       more than 4Mbyte) (subject to the qualifications
	       above about the allocate failed message).  _e_r_r_n_o
	       is set to [1mENOMEM[0m.

     [1mbad pointer
	       [0mThis is produced by _f_r_e_e when a badly aligned
	       pointer or a pointer which does not point to a
	       valid block is freed.  _e_r_r_n_o is set to [1mEINVAL[0m.

     [1mbad free  [0mThis is produced only when debugging code is com-
	       piled in and when large request allocator detects
	       a corrupted heap.  _e_r_r_n_o is set to [1mEINVAL[0m.

     [1mlist not empty
	       [0mThis is also only produced when debugging code is
	       compiled in - it corresponds to an internal error
	       in the code.  _e_r_r_n_o is set to [1mEFAULT[0m.

     [1minternal error
	       [0mThis message is produced when an internal incon-
	       sistency is detected during a free operation - it
	       should never occur.  _e_r_r_n_o is set to [1mEFAULT[0m.

     [1munallocated block
	       [0mThis is produced by _f_r_e_e when the pointer
	       corresponds to a part of the heap which has not
	       been allocated yet.  _e_r_r_n_o is set to [1mEINVAL[0m.

     [1mheader block
	       [0mThis is produced when the pointer passed to _f_r_e_e
	       corresponds to part of the control structure of
	       the allocator rather than to a valid part of the



Printed 13/2/92     Revision 1.6 of 26/11/90			7






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



	       heap.  _e_r_r_n_o is set to [1mEINVAL[0m.

     [1mheap corrupt
	       [0mThis message is produced whenever the allocator
	       detects corruption of the heap - a more common
	       symptom of this problem is for the program to
	       crash.  _e_r_r_n_o is set to [1mEFAULT[0m.

     [1mbad block size
	       [0mThis message is produced if the blockmap has been
	       corrupted.  _e_r_r_n_o is set to [1mEFAULT[0m.

     [1mmisaligned pointer
	       [0m_F_r_e_e produces this message when the pointer which
	       it is passed does not point to the head of a block
	       (although it is correctly aligned).  _e_r_r_n_o is set
	       to [1mEINVAL[0m.

     [1malready freed
	       [0mThis is produced by _f_r_e_e when a block is freed
	       twice or a block which has not yet been allocated
	       is freed.  _e_r_r_n_o is set to [1mEINVAL[0m.

     [1mend of block overwritten
	       [0mThis message is produced in the standard allocator
	       when a block with an invalid guard word is freed
	       (notice that the guard word is at the end of each
	       block).	_e_r_r_n_o is set to [1mEINVAL[0m.

[1mFEATURES
     [0mThe code contains checking features which are available all
     the time and analysis features which can be turn on when the
     code is compiled.	Developers of large applications who feel
     they need the analysis facilities should contact Acorn Com-
     puters Ltd (the code is not related to the BSD4.3 implemen-
     tation which is effectively unusable on an ARM).

     The overwrite checking can be switched off at compile time.
     This is only worth doing if the program in question allo-
     cates a very large number of very small blocks (less than 4
     words) - in this case it may also be worth tailoring the
     block map.  Again this requires access to the source code.

[1mBUGS
     [0mThere are no facilities for spotting storage leaks.

     It is not safe to use the storage allocator in a signal
     handler unless it is possible to guarantee that the handler
     has not interrupted a call to _m_a_l_l_o_c, _c_a_l_l_o_c, _r_e_a_l_l_o_c or
     _f_r_e_e.  This is because the storage allocator does not pro-
     tect itself against reentrance in this way and the code
     itself is not reentrant.  (This is also true of the standard



Printed 13/2/92     Revision 1.6 of 26/11/90			8






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



     BSD43 storage manager and of most other implementations of
     this functionality).

     It is not safe to _l_o_n_g_j_m_p out of a signal handler which has
     interrupted one of these storage manager calls either,
     although the normal consequence of doing so will simply be a
     storage leak.

[1mSEE ALSO
     [0mbrk(2)

[1mAUTHORS
     [0mJB Acorn Computers Ltd 1988










































Printed 13/2/92     Revision 1.6 of 26/11/90			9



[0m