libmpatrol.3

debug source code under unix platform.

              the option value, cast to an unsigned integer.  The
              return value will be _0 on success and _1 on failure.
              Options that are flags are listed in _m_p_a_t_r_o_l_._h pre-
              fixed with _M_P___F_L_G___*.  Multiple flags can be set  or
              unset   at   once  using  the  _M_P___O_P_T___S_E_T_F_L_A_G_S  and
              _M_P___O_P_T___U_N_S_E_T_F_L_A_G_S options  respectively,  with  the
              necessary flags specified in _v_a_l.  The return value
              will be _0 on success and a combination  of  all  of
              the  flags  that could not be set or unset on fail-
              ure.

       ____mmpp__ggeettooppttiioonn
              Gets the value  of  an  mpatrol  option  after  the
              library  has  been  initialised.  If _o_p_t is a valid
              option listed in _m_p_a_t_r_o_l_._h then _1 will be  returned
              and  the  associated  value will be returned in _v_a_l
              and cast to an unsigned integer, otherwise  _0  will
              be returned.  If _o_p_t is _M_P___O_P_T___S_E_T_F_L_A_G_S then all of
              the mpatrol library flags  that  are  set  will  be
              returned  in _v_a_l.  If _o_p_t is _M_P___O_P_T___U_N_S_E_T_F_L_A_G_S then
              all of the mpatrol library flags that are  not  set
              will be returned in _v_a_l.

       ____mmpp__lliibbvveerrssiioonn
              Returns  the version number of the mpatrol library.
              This can be useful for verifying that  the  version
              of  the  mpatrol  library  that a program is linked
              with is the one expected at compile-time.

       ____mmpp__ssttrreerrrroorr
              Returns the  error  message  corresponding  to  the
              error  code  _e_r_r  or  NNUULLLL  if  no  such error code
              exists.  The most recent error code recorded by the
              mpatrol   library  can  be  obtained  by  examining
              ____mmpp__eerrrrnnoo.

       ____mmpp__ffuunnccttiioonn
              Returns the name of the function  corresponding  to
              the allocation type _f_u_n_c or NNUULLLL if no such alloca-
              tion type exists.

       ____mmpp__sseettuusseerr
              Sets the user data for the memory  allocation  con-
              taining  _p_t_r.   The  contents  of _d_a_t_a are entirely
              application-specific as user  data  will  never  be
              examined  by  the  mpatrol  library.   Such data is
              associated with a memory allocation for its  entire
              lifetime  unless overridden by a subsequent call to
              ____mmpp__sseettuusseerr.  As such, the user data must be valid
              for  the  entire lifetime of the memory allocation,
              perhaps even after the allocation has been freed if
              the  NNOOFFRREEEE  option  is  being used.  This function
              returns _1 if there is  an  allocated  memory  block
              containing _p_t_r, and _0 otherwise.

       ____mmpp__sseettmmaarrkk
              Sets the marked flag for the memory allocation con-
              taining _p_t_r, indicating that the memory  allocation
              cannot  be  freed (but can be reallocated) and thus
              will not be listed as a memory leak.  This function
              returns  _1  if  there  is an allocated memory block
              containing _p_t_r, and _0 otherwise.  Note that a  mem-
              ory  allocation made by aallllooccaa, ssttrrdduuppaa or ssttrrnndduuppaa
              may not be marked.

       ____mmpp__iinnffoo
              Obtains information about a specific memory alloca-
              tion  by  placing statistics about _p_t_r in _i_n_f_o.  If
              _p_t_r does not belong to a previously allocated  mem-
              ory  allocation or free memory block then _0 will be
              returned, otherwise _1 will  be  returned  and  _i_n_f_o
              will contain the following information (note that a
              free memory block will only contain the  _b_l_o_c_k  and
              _s_i_z_e fields and can be identified by not having the
              _a_l_l_o_c_a_t_e_d flag set):

              FFiieelldd       DDeessccrriippttiioonn

              bblloocckk       Pointer to first byte of alloc.
              ssiizzee        Size of alloc in bytes.
              ttyyppee        Type of function which allocated memory.
              aalllloocc       Allocation index.
              rreeaalllloocc     Number of times reallocated.
              tthhrreeaadd      Thread identifier.
              eevveenntt       Event of last modification.
              ffuunncc        Function in which alloc took place.
              ffiillee        File in which alloc took place.
              lliinnee        Line number at which alloc took place.
              ssttaacckk       Pointer to function call stack.
              ttyyppeessttrr     Type stored in allocation.
              ttyyppeessiizzee    Size of type stored in allocation.
              uusseerrddaattaa    User data associated with allocation.
              aallllooccaatteedd   Indicates if alloc was allocated.
              ffrreeeedd       Indicates if alloc has been freed.
              mmaarrkkeedd      Indicates if alloc has been marked.
              pprrooffiilleedd    Indicates if alloc has been profiled.
              ttrraacceedd      Indicates if alloc has been traced.
              iinntteerrnnaall    Indicates if alloc is internal.

       ____mmpp__ssyymmiinnffoo
              Obtains symbolic information about a specific  code
              address  by  placing  statistics about _p_t_r in _i_n_f_o.
              If _p_t_r does not belong to a function symbol then  _0
              will  be returned, otherwise _1 will be returned and
              _i_n_f_o will contain the following information:

              FFiieelldd    DDeessccrriippttiioonn

              nnaammee     Name of symbol.
              oobbjjeecctt   File containing symbol.
              aaddddrr     Start address of symbol.
              ssiizzee     Size of symbol.
              ffiillee     Filename corresponding to address.
              lliinnee     Line number corresponding to address.

       ____mmpp__ssyymmbbooll
              Obtains the name of a  function  symbol  containing
              the code address specified in _p_t_r.  If _p_t_r does not
              belong to a  function  symbol  then  NNUULLLL  will  be
              returned.

       ____mmpp__pprriinnttiinnffoo
              Displays  information about a specific memory allo-
              cation containing _p_t_r to the  standard  error  file
              stream.   If  _p_t_r  does  not belong to a previously
              allocated memory allocation or  free  memory  block
              then  _0  will  be  returned,  otherwise  _1  will be
              returned.  This function is intended to  be  called
              from within a debugger.

       ____mmpp__ssnnaappsshhoott
              Returns  the current event number, effectively tak-
              ing a snapshot of the heap.  This number  can  then
              be used in later calls to ____mmpp__iitteerraattee.

       ____mmpp__iitteerraattee
              Iterates  over  all  of  the  current allocated and
              freed memory allocations,  calling  _f_u_n_c  with  the
              start  address  of every memory allocation that has
              been modified since event number _e_v_e_n_t.  If _f_u_n_c is
              NNUULLLL  then ____mmpp__pprriinnttiinnffoo will be used as the call-
              back function.  If eevveenntt is _0  then  _f_u_n_c  will  be
              called with the start address of every memory allo-
              cation.  If _f_u_n_c returns a negative number then the
              iteration  process will be stopped immediately.  If
              _f_u_n_c returns a  positive  number  above  zero  then
              ____mmpp__iitteerraattee  will  return the number of times _f_u_n_c
              returned a non-zero number after the iteration pro-
              cess  has  stopped.   The  _d_a_t_a  argument is passed
              directly to _f_u_n_c as its second argument and is  not
              read by the mpatrol library.

       ____mmpp__iitteerraatteeaallll
              Iterates  over  all  of  the  current allocated and
              freed  memory  allocations  and  any  free   memory
              blocks,  calling  _f_u_n_c  with  the  start address of
              every memory allocation or free block.  If _f_u_n_c  is
              NNUULLLL  then ____mmpp__pprriinnttiinnffoo will be used as the call-
              back function.  If _f_u_n_c returns a  negative  number
              then  the iteration process will be stopped immedi-
              ately.  If _f_u_n_c returns  a  positive  number  above
              zero  then  ____mmpp__iitteerraattee  will return the number of
              times _f_u_n_c returned a  non-zero  number  after  the
              iteration  process  has stopped.  The _d_a_t_a argument
              is passed directly to _f_u_n_c as its  second  argument
              and  is not read by the mpatrol library.  Note that
              unlike  ____mmpp__iitteerraattee,  this  function   will   also
              include  internal  memory  allocations  made by the
              mpatrol library and is  intended  for  walking  the
              entire heap.

       ____mmpp__aaddddaalllloocceennttrryy
              Adds  an  entry  representing an allocation of size
              _s_i_z_e to the leak table.   The  allocation  will  be
              associated  with  a  source  filename of _f_i_l_e and a
              line number of _l_i_n_e if the former is  non-NNUULLLL  and
              the  latter  is  non-zero.  If _f_i_l_e is non-NNUULLLL and
              _l_i_n_e is _0 then _f_i_l_e  represents  the  name  of  the
              function that made the allocation.  If _f_i_l_e is NNUULLLL
              and _l_i_n_e is non-zero then _l_i_n_e represents the  code
              address  at which the allocation was made.  If _f_i_l_e
              is NNUULLLL and _l_i_n_e is _0  then  the  location  of  the
              allocation  is unknown.  Returns _1 on success and _0
              if there  was  no  more  memory  available  to  add
              another entry to the leak table.

       ____mmpp__aaddddffrreeeeeennttrryy
              Adds  an  entry representing a deallocation of size
              _s_i_z_e to the leak table.  The deallocation  will  be
              associated  with  a  source  filename of _f_i_l_e and a
              line number of _l_i_n_e if the former is  non-NNUULLLL  and
              the  latter  is  non-zero.  If _f_i_l_e is non-NNUULLLL and
              _l_i_n_e is _0 then _f_i_l_e  represents  the  name  of  the
              function  that  made  the deallocation.  If _f_i_l_e is
              NNUULLLL and _l_i_n_e is non-zero then _l_i_n_e represents  the
              code  address  at  which the deallocation was made.
              If _f_i_l_e is NNUULLLL and _l_i_n_e is _0 then the location  of
              the  deallocation is unknown.  Returns _1 on success
              and _0 if there was no existing allocation from  the
              same location in the leak table.

       ____mmpp__cclleeaarrlleeaakkttaabbllee
              Deletes  all  of  the  existing entries in the leak
              table, making it empty.  This will also affect  the
              behaviour of the LLEEAAKKTTAABBLLEE option since that option
              will then only be able to show  a  summary  of  the
              entries in the leak table that were collected after
              the last call to this function rather than from the
              start of program execution.

       ____mmpp__ssttaarrttlleeaakkttaabbllee
              Starts  the automatic logging of all memory alloca-