libmpalloc.3

debug source code under unix platform.

LIBMPALLOC(3)            mpatrol library            LIBMPALLOC(3)


NNAAMMEE
       libmpalloc - dynamic memory allocation replacement library

SSYYNNOOPPSSIISS
       #include <mpalloc.h>

       void *MP_MALLOC(void *ptr, size_t count, typename type);
       void *MP_CALLOC(void *ptr, size_t count, typename type);
       char *MP_STRDUP(char *ptr, const char *str);
       void *MP_REALLOC(void *ptr, size_t count, typename type);
       void MP_FREE(void *ptr);
       __mp_failhandler MP_FAILURE(__mp_failhandler func);

DDEESSCCRRIIPPTTIIOONN
       The _m_p_a_l_l_o_c _l_i_b_r_a_r_y contains  release  implementations  of
       all  of  the  mpatrol  library  functions, with all of its
       checking, debugging and tracing features disabled.  It  is
       fully  link-compatible with the mpatrol library and so can
       be linked in instead of the mpatrol library  in  order  to
       quickly  disable  all  of its features without requiring a
       complete recompilation of all of the  source  files  in  a
       project.   It also contains implementations of the MMPP__MMAALL--
       LLOOCC family of functions that can  be  used  in  a  release
       environment.

       All  of  the function definitions in _m_p_a_t_r_o_l_._h can be dis-
       abled by defining the NNDDEEBBUUGG preprocessor macro, which  is
       the same macro used to control the behaviour of the aasssseerrtt
       function.  If NNDDEEBBUUGG is defined then no macro redefinition
       of  functions  will  take  place  and  all special mpatrol
       library functions will evaluate to empty statements.   The
       _m_p_a_l_l_o_c_._h  header file will also be included in this case.
       It is intended  that  the  NNDDEEBBUUGG  preprocessor  macro  be
       defined in release builds.

       The  mpalloc  library contains functional replacements for
       all of the mpatrol library's dynamic memory allocation and
       memory  operation  functions, mainly for use in situations
       where not all of the source files in a project  have  been
       recompiled  with the NNDDEEBBUUGG preprocessor macro in order to
       remove mpatrol.  However, not all of these  functions  can
       be  fully implemented using ANSI C and so may contain some
       limitations.  The only recommended solution  for  a  final
       release  is  to  perform  a complete recompile with NNDDEEBBUUGG
       defined.

FFUUNNCCTTIIOONNSS
       The following  6  functions  are  provided  as  convenient
       alternatives to the ANSI C dynamic memory allocation func-
       tions (although ssttrrdduupp is not strictly  an  ANSI  C  func-
       tion).   They  are implemented as preprocessor macro func-
       tions which may evaluate their arguments more  than  once,
       so  extra  care should be taken to avoid passing arguments
       with side-effects.  None of the functions return  NNUULLLL  if
       no  memory is available and instead abort the program with
       a useful error message indicating where the call to  allo-
       cate  memory  came  from and what was being allocated.  To
       use these you should include the _m_p_a_l_l_o_c_._h header file:


       MMPP__MMAALLLLOOCC
              Allocates _c_o_u_n_t uninitialised items  of  type  _t_y_p_e
              from the heap, sets _p_t_r to the result and returns a
              suitably-cast pointer to  the  first  item  of  the
              allocation.   The pointer returned will be suitably
              aligned for holding items of type _t_y_p_e.   If  _c_o_u_n_t
              is  _0  then  it will be implicitly rounded up to _1.
              If there is not enough space in the heap  then  the
              program  will  be aborted after calling the alloca-
              tion failure handler, which by  default  writes  an
              appropriate  error  message  to  the standard error
              file stream.  The allocated memory in _p_t_r  must  be
              deallocated   with   MMPP__FFRREEEE  or  reallocated  with
              MMPP__RREEAALLLLOOCC.

       MMPP__CCAALLLLOOCC
              Allocates _c_o_u_n_t zero-initialised items of type _t_y_p_e
              from the heap, sets _p_t_r to the result and returns a
              suitably-cast pointer to  the  first  item  of  the
              allocation.   The pointer returned will be suitably
              aligned for holding items of type _t_y_p_e.   If  _c_o_u_n_t
              is  _0  then  it will be implicitly rounded up to _1.
              If there is not enough space in the heap  then  the
              program  will  be aborted after calling the alloca-
              tion failure handler, which by  default  writes  an
              appropriate  error  message  to  the standard error
              file stream.  The allocated memory in _p_t_r  must  be
              deallocated   with   MMPP__FFRREEEE  or  reallocated  with
              MMPP__RREEAALLLLOOCC.

       MMPP__SSTTRRDDUUPP
              Allocates exactly enough memory from  the  heap  to
              duplicate  _s_t_r (including the terminating nul char-
              acter), sets _p_t_r to the result and returns a  suit-
              ably-cast  pointer to the first byte of the alloca-
              tion after copying _s_t_r to the newly-allocated  mem-
              ory.   The  pointer returned will have no alignment
              constraints and can be used to store character data
              up  to  the  length of _s_t_r.  If there is not enough
              space in the heap then the program will be  aborted
              after calling the allocation failure handler, which
              by default writes an appropriate error  message  to
              the standard error file stream.  The allocated mem-
              ory in _p_t_r must  be  deallocated  with  MMPP__FFRREEEE  or
              reallocated with MMPP__RREEAALLLLOOCC.

       MMPP__RREEAALLLLOOCC
              Resizes  the  memory allocation beginning at _p_t_r to
              _c_o_u_n_t items of type _t_y_p_e and  returns  a  suitably-
              cast  pointer  to the first item of the new alloca-
              tion after copying _p_t_r to the newly-allocated  mem-
              ory,  which  will  be truncated if _c_o_u_n_t is smaller
              than the original number  of  items.   The  pointer
              returned will be suitably aligned for holding items
              of type _t_y_p_e.  If _p_t_r is NNUULLLL then the call will be
              equivalent  to  MMPP__MMAALLLLOOCC.   If  _c_o_u_n_t is _0 then it
              will be implicitly rounded up to _1.   If  _c_o_u_n_t  is
              greater  than the original number of items then the
              extra  space  will  be  filled  with  uninitialised
              bytes.   If  there  is not enough space in the heap
              then the program will be aborted after calling  the
              allocation failure handler, which by default writes
              an appropriate error message to the standard  error
              file  stream.  The allocated memory must be deallo-
              cated with MMPP__FFRREEEE and  can  be  reallocated  again
              with MMPP__RREEAALLLLOOCC.

       MMPP__FFRREEEE
              Frees the memory allocation beginning at _p_t_r so the
              memory can be reused by another  call  to  allocate
              memory, and sets _p_t_r to NNUULLLL after freeing the mem-
              ory.  If _p_t_r is NNUULLLL then no memory will be  freed.

       MMPP__FFAAIILLUURREE
              Installs an allocation failure handler specifically
              for use with MMPP__MMAALLLLOOCC,  MMPP__CCAALLLLOOCC,  MMPP__SSTTRRDDUUPP  and
              MMPP__RREEAALLLLOOCC  and returns a pointer to the previously
              installed handler, normally the default handler  if
              no  handler  had  been  previously installed.  This
              will be called by the above functions when there is
              not  enough  space  in the heap for them to satisfy
              their allocation request.  The  default  allocation
              failure  handler  will  terminate the program after
              writing an error message to the standard error file
              stream  indicating  where  the  original allocation
              request took place and what was being allocated.

SSEEEE AALLSSOO
       mmppaattrrooll(1),  mmpprrooff(1),  mmppttrraaccee(1),  mmlleeaakk(1),   mmppssyymm(1),
       mmppeeddiitt(1),    hheexxwwoorrddss(1),    lliibbmmppaattrrooll(3),    mmaalllloocc(3),
       aasssseerrtt(3).

       The mpatrol manual and reference card.

       http://www.cbmamiga.demon.co.uk/mpatrol/

AAUUTTHHOORR
       Graeme S. Roy <[e-mail]>

CCOOPPYYRRIIGGHHTT
       Copyright (C) 1997-2002  Graeme  S.  Roy  <graeme.roy@ana-
       log.com>

       This  library  is  free  software; you can redistribute it
       and/or modify it under the terms of the GNU  Library  Gen-
       eral  Public  License  as  published  by the Free Software
       Foundation; either version 2 of the License, or  (at  your
       option) any later version.

       This  library  is  distributed in the hope that it will be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty  of  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU Library General Public  License  for
       more details.

       You should have received a copy of the GNU Library General
       Public License along with this library; if not,  write  to
       the Free Software Foundation, Inc., 59 Temple Place, Suite
       330, Boston, MA 02111-1307, USA.



Release 1.4               8 January 2002                        1