libmpatrol.3

debug source code under unix platform.

              then the program will be terminated and the  _O_U_T_M_E_M
              error  will be given.  The allocated memory must be
              deallocated with xxffrreeee and can be reallocated again
              with xxrreeaalllloocc.

       xxffrreeee  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  following  5  functions are available as replacements
       for existing C++ library functions, but  the  replacements
       in  _m_p_a_t_r_o_l_._h will only be used if the MMPP__NNOOCCPPLLUUSSPPLLUUSS pre-
       processor macro is not defined.  The replacement operators
       make  use  of  the preprocessor in order to obtain source-
       level information.   If  this  causes  problems  then  you
       should  define  the  MMPP__NNOONNEEWWDDEELLEETTEE preprocessor macro and
       use  the  MMPP__NNEEWW,  MMPP__NNEEWW__NNOOTTHHRROOWW  and  MMPP__DDEELLEETTEE   macros
       instead of nneeww and ddeelleettee directly.  To use these C++ fea-
       tures 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:

       ooppeerraattoorr nneeww
              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 either the  _s_t_d_:_:_b_a_d___a_l_l_o_c  excep-
              tion  will  be  thrown  or the null pointer will be
              returned and eerrrrnnoo will be  set  to  EENNOOMMEEMM  -  the
              behaviour depends on whether the nothrow version of
              the operator is used.  The allocated memory must be
              deallocated with ooppeerraattoorr ddeelleettee.

       ooppeerraattoorr nneeww[[]]
              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 either the  _s_t_d_:_:_b_a_d___a_l_l_o_c  excep-
              tion  will  be  thrown  or the null pointer will be
              returned and eerrrrnnoo will be  set  to  EENNOOMMEEMM  -  the
              behaviour depends on whether the nothrow version of
              the operator is used.  The allocated memory must be
              deallocated with ooppeerraattoorr ddeelleettee[[]].

       ooppeerraattoorr ddeelleettee
              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.   This  function  must only be used with
              memory allocated by ooppeerraattoorr nneeww.

       ooppeerraattoorr ddeelleettee[[]]
              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.  This function must only  be  used  with
              memory allocated by ooppeerraattoorr nneeww[[]].

       sseett__nneeww__hhaannddlleerr
              Installs  a low-memory handler specifically for use
              with ooppeerraattoorr nneeww and ooppeerraattoorr nneeww[[]] and returns  a
              pointer to the previously installed handler, or the
              null pointer if  no  handler  had  been  previously
              installed.   This will be called repeatedly by both
              functions when they would normally return NNUULLLL, and
              this  loop will continue until they manage to allo-
              cate the requested space.  Note that this  function
              is equivalent to ____mmpp__nnoommeemmoorryy and will replace the
              handler installed by that function.

       The following 10 functions are available  as  replacements
       for existing C library memory operation 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 tracing information:

       mmeemmsseett Writes _s_i_z_e bytes of value _b_y_t_e to the memory loca-
              tion beginning at _p_t_r and returns _p_t_r.  If _s_i_z_e  is
              00  then no bytes will be written.  If the operation
              would affect an existing memory allocation  in  the
              heap  but  would  straddle that allocation's bound-
              aries then an error message will  be  generated  in
              the log file and no bytes will be written.

       bbzzeerroo  Writes  _s_i_z_e  zero  bytes  to  the  memory location
              beginning at _p_t_r.  If _s_i_z_e is 00 then no bytes  will
              be  written.   If  the  operation  would  affect an
              existing memory allocation in the  heap  but  would
              straddle that allocation's boundaries then an error
              message will be generated in the log  file  and  no
              bytes  will be written.  This function is available
              for backwards compatibility with older C  libraries
              and should not be used in new code.

       mmeemmccccppyy
              Copies  _s_i_z_e  bytes  from  _s_r_c  to _d_e_s_t and returns
              NNUULLLL, or copies the  number  of  bytes  up  to  and
              including  the  first  occurrence  of  _b_y_t_e if _b_y_t_e
              exists within the specified  range  and  returns  a
              pointer to the first byte after _b_y_t_e.  If _s_i_z_e is 00
              or _s_r_c is the same as _d_e_s_t then no  bytes  will  be
              copied.   The  source and destination ranges should
              not overlap, otherwise a warning will be written to
              the  log  file.   If  the operation would affect an
              existing memory allocation in the  heap  but  would
              straddle that allocation's boundaries then an error
              message will be generated in the log  file  and  no
              bytes will be copied.

       mmeemmccppyy Copies  _s_i_z_e  bytes  from  _s_r_c  to _d_e_s_t and returns
              _d_e_s_t.  If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then
              no  bytes  will be copied.  The source and destina-
              tion ranges should not overlap, otherwise a warning
              will  be written to the log file.  If the operation
              would affect an existing memory allocation  in  the
              heap  but  would  straddle that allocation's bound-
              aries then an error message will  be  generated  in
              the log file and no bytes will be copied.

       mmeemmmmoovvee
              Copies  _s_i_z_e  bytes  from  _s_r_c  to _d_e_s_t and returns
              _d_e_s_t.  If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then
              no  bytes  will  be copied.  If the operation would
              affect an existing memory allocation  in  the  heap
              but  would  straddle  that  allocation's boundaries
              then an error message will be generated in the  log
              file and no bytes will be copied.

       bbccooppyy  Copies  _s_i_z_e  bytes from _s_r_c to _d_e_s_t.  If _s_i_z_e is 00
              or _s_r_c is the same as _d_e_s_t then no  bytes  will  be
              copied.   If the operation would affect an existing
              memory allocation in the heap  but  would  straddle
              that  allocation's boundaries then an error message
              will be generated in the log file and no bytes will
              be  copied.   This  function is available for back-
              wards compatibility  with  older  C  libraries  and
              should not be used in new code.

       mmeemmccmmpp Compares  _s_i_z_e bytes from _p_t_r_1 and _p_t_r_2 and returns
              00 if all of the bytes are identical, or returns the
              byte  difference  of the first differing bytes.  If
              _s_i_z_e is 00 or _p_t_r_1 is the same as _p_t_r_2 then no bytes
              will be compared.  If the operation would read from
              an existing memory allocation in the heap but would
              straddle that allocation's boundaries then an error
              message will be generated in the log  file  and  no
              bytes will be compared.

       bbccmmpp   Compares  _s_i_z_e bytes from _p_t_r_1 and _p_t_r_2 and returns
              00 if all of the bytes are identical, or returns the
              byte  difference  of the first differing bytes.  If
              _s_i_z_e is 00 or _p_t_r_1 is the same as _p_t_r_2 then no bytes
              will be compared.  If the operation would read from
              an existing memory allocation in the heap but would
              straddle that allocation's boundaries then an error
              message will be generated in the log  file  and  no
              bytes will be compared.  This function is available
              for backwards compatibility with older C  libraries
              and should not be used in new code.

       mmeemmcchhrr Searches  up  to  _s_i_z_e  bytes  in _p_t_r for the first
              occurrence of _b_y_t_e and returns a pointer to  it  or
              NNUULLLL  if no such byte occurs.  If _s_i_z_e is 00 then no
              bytes will be searched.   If  the  operation  would
              affect  an  existing  memory allocation in the heap
              but would  straddle  that  allocation's  boundaries
              then  an error message will be generated in the log
              file and no bytes will be searched.

       mmeemmmmeemm Searches up to _s_i_z_e_1 bytes in _p_t_r_1  for  the  first
              occurrence of _p_t_r_2 (which is exactly _s_i_z_e_2 bytes in
              length) and returns a pointer to it or NNUULLLL  if  no
              such sequence of bytes occur.  If _s_i_z_e_1 or _s_i_z_e_2 is
              00 then no bytes will be searched.  If the operation
              would  affect  an existing memory allocation in the
              heap but would straddle  that  allocation's  bound-
              aries  then  an  error message will be generated in
              the log file and no bytes will be searched.

       The following 42 functions are available as  support  rou-
       tines  for  additional  control and tracing in the mpatrol
       library.  Although they are documented here as being  pre-
       fixed  by  ____mmpp__, their equivalent functions that are pre-
       fixed by mmppaattrrooll__ are also defined as aliases in the  _m_p_a_-
       _t_r_o_l_._h  header  file.  To use these you should include the
       _m_p_a_t_r_o_l_._h header file:

       ____mmpp__aatteexxiitt
              Installs a function to be called when  the  mpatrol
              library terminates.  Up to 32 such functions can be
              registered and will be called in reverse  order  of
              registration.   Returns  _1  on success or _0 if _f_u_n_c
              could not be registered.

       ____mmpp__sseettooppttiioonn
              Sets the value  of  an  mpatrol  option  after  the
              library has been initialised.  Options that require
              values  are  listed  in  _m_p_a_t_r_o_l_._h  prefixed   with
              _M_P___O_P_T___*.  The _o_p_t argument should be set to one of
              these macros, and the _v_a_l argument should be set to