libmpatrol.3

debug source code under unix platform.

              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.

       ssttrrnndduuppaa
              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 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 pro-
              gram will be terminated and the _O_U_T_M_E_M  error  will
              be given.  The ssttrrnndduuppaa function normally allocates
              its memory from the stack, with the result that all
              such  allocations  will  be freed when the function
              returns.  This version of  ssttrrnndduuppaa  allocates  its
              memory  from  the  heap  in order to provide better
              debugging, but the allocations may not  necessarily
              be  freed  immediately  when  the function returns.
              The allocated memory can be deallocated  explicitly
              with  ddeeaallllooccaa, but may not be reallocated or deal-
              located in any other way.  This function is  avail-
              able  for  backwards  compatibility  with  older  C
              source code and should not be used in new code.

       rreeaalllloocc
              Resizes the memory allocation beginning at  _p_t_r  to
              _s_i_z_e  bytes and returns a pointer to the first byte
              of the new allocation  after  copying  _p_t_r  to  the
              newly-allocated  memory, which will be truncated if
              _s_i_z_e is smaller than the original allocation.   The
              pointer returned will be suitably aligned for cast-
              ing to any type and can be used to store data of up
              to  _s_i_z_e  bytes in length.  If _p_t_r is NNUULLLL then the
              call will be equivalent to mmaalllloocc.  If  _s_i_z_e  is  _0
              then  the  existing memory allocation will be freed
              and the null pointer will be returned.  If _s_i_z_e  is
              greater than the original allocation then the extra
              space will be filled with uninitialised bytes.   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 and can be reallocated again  with  rreeaall--
              lloocc.

       rreeaallllooccff
              Resizes  the  memory allocation beginning at _p_t_r to
              _s_i_z_e bytes and returns a pointer to the first  byte
              of  the  new  allocation  after  copying _p_t_r to the
              newly-allocated memory, which will be truncated  if
              _s_i_z_e  is smaller than the original allocation.  The
              pointer returned will be suitably aligned for cast-
              ing to any type and can be used to store data of up
              to _s_i_z_e bytes in length.  If _p_t_r is NNUULLLL  then  the
              call  will  be  equivalent to mmaalllloocc.  If _s_i_z_e is _0
              then the existing memory allocation will  be  freed
              and  the null pointer will be returned.  If _s_i_z_e is
              greater than the original allocation then the extra
              space  will be filled with uninitialised bytes.  If
              there is not enough space in the heap then the null
              pointer  will  be returned, the original allocation
              will be freed and eerrrrnnoo will be set to EENNOOMMEEMM.  The
              allocated  memory must be deallocated with ffrreeee and
              can be reallocated again with rreeaalllloocc.  This  func-
              tion  is available for backwards compatibility with
              older C libraries and should not  be  used  in  new
              code.

       rreeccaalllloocc
              Resizes  the  memory allocation beginning at _p_t_r to
              _n_e_l_e_m elements of _s_i_z_e bytes and returns a  pointer
              to the first byte of the new allocation after copy-
              ing _p_t_r to the newly-allocated memory,  which  will
              be  truncated  if  _n_e_l_e_m * _s_i_z_e is smaller than the
              original 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  _p_t_r  is  NNUULLLL  then  the call will be
              equivalent to ccaalllloocc.  If _n_e_l_e_m * _s_i_z_e  is  _0  then
              the  existing  memory  allocation will be freed and
              the null pointer will be returned.  If _n_e_l_e_m * _s_i_z_e
              is  greater  than  the original allocation then the
              extra space will be  filled  with  zero-initialised
              bytes.   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  and  can  be  reallocated
              again with rreeaalllloocc.  This function is available for
              backwards compatibility with older C libraries  and
              ccaalllloocc and should not be used in new code.

       eexxppaanndd Attempts  to resize the memory allocation beginning
              at _p_t_r to _s_i_z_e bytes  and  either  returns  _p_t_r  if
              there was enough space to resize it, or NNUULLLL if the
              block could not be resized for a particular reason.
              If  _p_t_r is NNUULLLL then the call will be equivalent to
              mmaalllloocc.  If _s_i_z_e is  00  then  the  existing  memory
              allocation  will be freed and the NNUULLLL pointer will
              be returned.  If _s_i_z_e is greater than the  original
              allocation then the extra space will be filled with
              uninitialised bytes and if _s_i_z_e is  less  than  the
              original  allocation  then the memory block will be
              truncated.  If there is not  enough  space  in  the
              heap  then  the  NNUULLLL  pointer will be returned and
              eerrrrnnoo will be set to EENNOOMMEEMM.  The allocated  memory
              must  be  deallocated  with ffrreeee and can be reallo-
              cated again with rreeaalllloocc.  This function is  avail-
              able  for  backwards  compatibility  with  older  C
              libraries and should not be used in new code.

       ffrreeee   Frees the memory allocation beginning at _p_t_r so the
              memory  can  be  reused by another call to allocate
              memory.  If _p_t_r is NNUULLLL  then  no  memory  will  be
              freed.   All  of  the  previous  contents  will  be
              destroyed.

       ccffrreeee  Frees the memory allocation beginning at _p_t_r so the
              memory  can  be  reused by another call to allocate
              memory.  If _p_t_r is NNUULLLL  then  no  memory  will  be
              freed.   All  of  the  previous  contents  will  be
              destroyed.   The  _n_e_l_e_m  and  _s_i_z_e  parameters  are
              ignored  in  this implementation.  This function is
              available for backwards compatibility with older  C
              libraries  and ccaalllloocc and should not be used in new
              code.

       ddeeaallllooccaa
              Explicitly frees the  temporary  memory  allocation
              beginning  at  _p_t_r  so  the memory can be reused by
              another call to allocate memory.  If  _p_t_r  is  NNUULLLL
              then  no  memory  will be explicitly freed.  All of
              the previous  contents  will  be  destroyed.   This
              function  can  only be used to free memory that was
              allocated with the  aallllooccaa,  ssttrrdduuppaa  and  ssttrrnndduuppaa
              functions,  but is only really required if the mpa-
              trol library does not automatically free such  mem-
              ory   allocations   when  the  allocating  function
              returns.  This  function  is  mpatrol-specific  and
              should not be used in release code.

       The  following  5  functions are available as replacements
       for existing C library  extension  functions  that  always
       abort  and never return NNUULLLL if there is insufficient mem-
       ory to fulfil a request.  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 tracing
       information:

       xxmmaalllloocc
              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 program will be terminated and
              the _O_U_T_M_E_M error will be given.  The allocated mem-
              ory  must  be deallocated with xxffrreeee or reallocated
              with xxrreeaalllloocc.

       xxccaalllloocc
              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 program will be terminated and
              the _O_U_T_M_E_M error will be given.  The allocated mem-
              ory must be deallocated with xxffrreeee  or  reallocated
              with xxrreeaalllloocc.

       xxssttrrdduupp
              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 program will  be  termi-
              nated  and  the  _O_U_T_M_E_M  error  will be given.  The
              allocated memory must be deallocated with xxffrreeee  or
              reallocated with xxrreeaalllloocc.

       xxrreeaalllloocc
              Resizes  the  memory allocation beginning at _p_t_r to
              _s_i_z_e bytes and returns a pointer to the first  byte
              of  the  new  allocation  after  copying _p_t_r to the
              newly-allocated memory, which will be truncated  if
              _s_i_z_e  is smaller than the original allocation.  The
              pointer returned will be suitably aligned for cast-
              ing to any type and can be used to store data of up
              to _s_i_z_e bytes in length.  If _p_t_r is NNUULLLL  then  the
              call  will  be equivalent to xxmmaalllloocc.  If _s_i_z_e is _0
              then it will be implictly rounded up to _1.  If _s_i_z_e
              is  greater  than  the original allocation then the
              extra  space  will  be  filled  with  uninitialised
              bytes.   If  there  is not enough space in the heap