libmpatrol.3

debug source code under unix platform.

       should be added as the first function call  in  the  child
       process  in order to duplicate the behaviour of the CCHHEECCKK--
       FFOORRKK option.

       Memory allocation profiling is supported, with  statistics
       about  every  memory  allocation and deallocation that was
       made during the execution of a program being written to  a
       file  at  program  termination if the PPRROOFF option is used.
       The information stored in this file can then  be  used  by
       the  mmpprrooff  command  to display various tables summarising
       the memory allocation behaviour of the program  that  pro-
       duced  it.   Memory  allocation tracing is also supported,
       where a trace of all memory allocations, reallocations and
       deallocations can be written to a tracing output file in a
       concise encoded format for later processing by the mmppttrraaccee
       command.  This is controlled with the TTRRAACCEE option.

FFUUNNCCTTIIOONNSS
       The  following  19 functions are available as replacements
       for existing C library functions.  To use these  you  must
       include  _m_p_a_t_r_o_l_._h before all other header files, although
       on UNIX and Windows platforms (and AmigaOS when using ggcccc)
       they  will be used anyway, albeit with slightly less trac-
       ing information.  If aallllooccaa is being used and _a_l_l_o_c_a_._h  is
       included  then _m_p_a_t_r_o_l_._h must appear after _a_l_l_o_c_a_._h other-
       wise the debugging version of aallllooccaa will not be used:

       mmaalllloocc Allocates _s_i_z_e uninitialised bytes  from  the  heap
              and  returns  a  pointer  to  the first byte of the
              allocation.  The pointer returned will be  suitably
              aligned  for casting to any type and can be used to
              store data of up to _s_i_z_e bytes in length.  If  _s_i_z_e
              is  _0  then the memory allocated will be implicitly
              rounded up to _1 byte.  If there is not enough space
              in  the heap then the null pointer will be returned
              and eerrrrnnoo will be set  to  EENNOOMMEEMM.   The  allocated
              memory must be deallocated with ffrreeee or reallocated
              with rreeaalllloocc.

       ccaalllloocc Allocates _n_e_l_e_m elements of  _s_i_z_e  zero-initialised
              bytes  from  the  heap and returns a pointer to the
              first byte of the allocation.  The pointer returned
              will  be  suitably  aligned for casting to any type
              and can be used to store data of up to _n_e_l_e_m _* _s_i_z_e
              bytes  in  length.   If  _n_e_l_e_m _* _s_i_z_e is _0 then the
              amount  of  memory  allocated  will  be  implicitly
              rounded up to _1 byte.  If there is not enough space
              in the heap then the null pointer will be  returned
              and  eerrrrnnoo  will  be  set to EENNOOMMEEMM.  The allocated
              memory must be deallocated with ffrreeee or reallocated
              with rreeaalllloocc.

       mmeemmaalliiggnn
              Allocates  _s_i_z_e  uninitialised  bytes from the heap
              and returns a pointer to  the  first  byte  of  the
              allocation.   The  pointer returned will be aligned
              to _a_l_i_g_n bytes and can be used to store data of  up
              to _s_i_z_e bytes in length.  If _a_l_i_g_n is zero then the
              default system alignment will be used.  If _a_l_i_g_n is
              not  a  power  of two then it will be rounded up to
              the nearest power of two.  If _a_l_i_g_n is greater than
              the  system  page size then it will be truncated to
              that value.  If _s_i_z_e is _0 then the memory allocated
              will  be implicitly rounded up to _1 byte.  If there
              is not enough space  in  the  heap  then  the  null
              pointer  will  be returned and eerrrrnnoo will be set to
              EENNOOMMEEMM.  The allocated memory must  be  deallocated
              with ffrreeee or reallocated with rreeaalllloocc, although the
              latter  will  not  guarantee  the  preservation  of
              alignment.

       vvaalllloocc Allocates  _s_i_z_e  uninitialised  bytes from the heap
              and returns a pointer to  the  first  byte  of  the
              allocation.   The  pointer returned will be aligned
              to the system page size and can be  used  to  store
              data  of  up to _s_i_z_e bytes in length.  If _s_i_z_e is _0
              then  the  memory  allocated  will  be   implicitly
              rounded up to _1 byte.  If there is not enough space
              in the heap then the null pointer will be  returned
              and  eerrrrnnoo  will  be  set to EENNOOMMEEMM.  The allocated
              memory must be deallocated with ffrreeee or reallocated
              with  rreeaalllloocc, although the latter will not guaran-
              tee the preservation of alignment.

       ppvvaalllloocc
              Allocates _s_i_z_e uninitialised bytes  from  the  heap
              and  returns  a  pointer  to  the first byte of the
              allocation.  The pointer returned will  be  aligned
              to  the  system  page size and can be used to store
              data of up to _s_i_z_e bytes in length.  If _s_i_z_e  is  _0
              then   the  memory  allocated  will  be  implicitly
              rounded up  to  _1  page,  otherwise  _s_i_z_e  will  be
              implicitly  rounded  up to a multiple of the system
              page size.  If there is not  enough  space  in  the
              heap  then  the  null  pointer will be returned and
              eerrrrnnoo will be set to EENNOOMMEEMM.  The allocated  memory
              must  be  deallocated with ffrreeee or reallocated with
              rreeaalllloocc, although the latter will not guarantee the
              preservation of alignment.

       aallllooccaa Allocates  _s_i_z_e  temporary uninitialised bytes from
              the heap and returns a pointer to the first byte of
              the allocation.  The pointer returned will be suit-
              ably aligned for casting to any  type  and  can  be
              used  to  store data of up to _s_i_z_e bytes in length.
              If _s_i_z_e is _0 then  the  memory  allocated  will  be
              implicitly  rounded  up to _1 byte.  If there is not
              enough space in the heap then the program  will  be
              terminated and the _O_U_T_M_E_M error will be given.  The
              aallllooccaa function normally allocates its memory  from
              the  stack,  with  the result that all such alloca-
              tions will be  freed  when  the  function  returns.
              This  version  of  aallllooccaa allocates its memory from
              the heap in order to provide better debugging,  but
              the  allocations may not necessarily be freed imme-
              diately when the function returns.   The  allocated
              memory can be deallocated explicitly with ddeeaallllooccaa,
              but may not be reallocated or  deallocated  in  any
              other  way.   This  function is available for back-
              wards compatibility with older C  source  code  and
              should not be used in new code.

       ssttrrdduupp Allocates  exactly  enough  memory from the heap to
              duplicate _s_t_r (including the terminating nul  char-
              acter)  and  returns a pointer to the first byte of
              the allocation after copying _s_t_r to the newly-allo-
              cated  memory.   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 _s_t_r is
              NNUULLLL then an error  will  be  given  and  the  null
              pointer  will  be returned.  If there is not enough
              space in the heap then the  null  pointer  will  be
              returned  and  eerrrrnnoo  will  be  set to EENNOOMMEEMM.  The
              allocated memory must be deallocated with  ffrreeee  or
              reallocated with rreeaalllloocc.

       ssttrrnndduupp
              Allocates  exactly  enough  memory from the heap to
              duplicate _s_t_r (including the terminating nul  char-
              acter)  and  returns a pointer to the first byte of
              the allocation after copying _s_t_r to the newly-allo-
              cated  memory.   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 _s_t_r is
              NNUULLLL and _s_i_z_e is non-zero then  an  error  will  be
              given  and  the  null pointer will be returned.  If
              the length of _s_t_r is greater than  _s_i_z_e  then  only
              _s_i_z_e  characters will be allocated and copied, with
              one additional byte  for  the  nul  character.   If
              there is not enough space in the heap then the null
              pointer will be returned and eerrrrnnoo will be  set  to
              EENNOOMMEEMM.   The  allocated memory must be deallocated
              with ffrreeee or reallocated with rreeaalllloocc.  This  func-
              tion  is available for backwards compatibility with
              older C libraries and should not  be  used  in  new
              code.

       ssttrrssaavvee
              Allocates  exactly  enough  memory from the heap to
              duplicate _s_t_r (including the terminating nul  char-
              acter)  and  returns a pointer to the first byte of
              the allocation after copying _s_t_r to the newly-allo-
              cated  memory.   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 _s_t_r is
              NNUULLLL then an error  will  be  given  and  the  null
              pointer  will  be returned.  If there is not enough
              space in the heap then the  null  pointer  will  be
              returned  and  eerrrrnnoo  will  be  set to EENNOOMMEEMM.  The
              allocated memory must be deallocated with  ffrreeee  or
              reallocated  with rreeaalllloocc.  This function is avail-
              able  for  backwards  compatibility  with  older  C
              libraries and should not be used in new code.

       ssttrrnnssaavvee
              Allocates  exactly  enough  memory from the heap to
              duplicate _s_t_r (including the terminating nul  char-
              acter)  and  returns a pointer to the first byte of
              the allocation after copying _s_t_r to the newly-allo-
              cated  memory.   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 _s_t_r is
              NNUULLLL and _s_i_z_e is non-zero then  an  error  will  be
              given  and  the  null pointer will be returned.  If
              the length of _s_t_r is greater than  _s_i_z_e  then  only
              _s_i_z_e  characters will be allocated and copied, with
              one additional byte  for  the  nul  character.   If
              there is not enough space in the heap then the null
              pointer will be returned and eerrrrnnoo will be  set  to
              EENNOOMMEEMM.   The  allocated memory must be deallocated
              with ffrreeee or reallocated with rreeaalllloocc.  This  func-
              tion  is available for backwards compatibility with
              older C libraries and should not  be  used  in  new
              code.

       ssttrrdduuppaa
              Allocates  exactly enough temporary memory from the
              heap to duplicate _s_t_r  (including  the  terminating
              nul  character)  and returns a pointer to the first
              byte of the allocation after  copying  _s_t_r  to  the
              newly-allocated  memory.  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
              _s_t_r is NNUULLLL then an error will  be  given  and  the
              null  pointer  will  be  returned.  If there is not
              enough space in the heap then the program  will  be
              terminated and the _O_U_T_M_E_M error will be given.  The
              ssttrrdduuppaa function normally allocates its memory from
              the  stack,  with  the result that all such alloca-
              tions will be  freed  when  the  function  returns.
              This  version  of ssttrrdduuppaa allocates its memory from
              the heap in order to provide better debugging,  but
              the  allocations may not necessarily be freed imme-
              diately when the function returns.   The  allocated