libmpatrol.3

debug source code under unix platform.

LIBMPATROL(3)            mpatrol library            LIBMPATROL(3)


NNAAMMEE
       libmpatrol - dynamic memory allocation and tracing library

SSYYNNOOPPSSIISS
       #include <mpatrol.h>

       void *malloc(size_t size);
       void *calloc(size_t nelem, size_t size);
       void *memalign(size_t align, size_t size);
       void *valloc(size_t size);
       void *pvalloc(size_t size);
       void *alloca(size_t size);
       char *strdup(const char *str);
       char *strndup(const char *str, size_t size);
       char *strsave(const char *str);
       char *strnsave(const char *str, size_t size);
       char *strdupa(const char *str);
       char *strndupa(const char *str, size_t size);
       void *realloc(void *ptr, size_t size);
       void *reallocf(void *ptr, size_t size);
       void *recalloc(void *ptr, size_t nelem, size_t size);
       void *expand(void *ptr, size_t size);
       void free(void *ptr);
       void cfree(void *ptr, size_t nelem, size_t size);
       void dealloca(void *ptr);

       void *xmalloc(size_t size);
       void *xcalloc(size_t nelem, size_t size);
       char *xstrdup(const char *str);
       void *xrealloc(void *ptr, size_t size);
       void xfree(void *ptr);

       void *operator new(size_t size) throw(std::bad_alloc);
       void *operator new(size_t size, const std::nothrow_t&)
             throw();
       void *operator new[](size_t size) throw(std::bad_alloc);
       void *operator new[](size_t size, const std::nothrow_t&)
             throw();
       void operator delete(void *ptr) throw();
       void operator delete(void *ptr, const std::nothrow_t&)
            throw();
       void operator delete[](void *ptr) throw();
       void operator delete[](void *ptr, const std::nothrow_t&)
            throw();
       std::new_handler std::set_new_handler(std::new_handler func)
                        throw();

       void *memset(void *ptr, int byte, size_t size);
       void bzero(void *ptr, size_t size);
       void *memccpy(void *dest, const void *src, int byte,
                     size_t size);
       void *memcpy(void *dest, const void *src, size_t size);
       void *memmove(void *dest, const void *src, size_t size);
       void bcopy(const void *src, void *dest, size_t size);
       int memcmp(const void *ptr1, const void *ptr2,
                  size_t size);
       int bcmp(const void *ptr1, const void *ptr2, size_t size);
       void *memchr(const void *ptr, int byte, size_t size);
       void *memmem(const void *ptr1, size_t size1,
                    const void *ptr2, size_t size2);

       int __mp_atexit(void (*func)(void));
       unsigned long __mp_setoption(long opt, unsigned long val);
       int __mp_getoption(long opt, unsigned long *val);
       unsigned long __mp_libversion(void);
       const char *__mp_strerror(__mp_errortype err);
       const char *__mp_function(__mp_alloctype func);
       int __mp_setuser(const void *ptr, const void *data);
       int __mp_setmark(const void *ptr);
       int __mp_info(const void *ptr, __mp_allocinfo *info);
       int __mp_syminfo(const void *ptr, __mp_symbolinfo *info);
       const char *__mp_symbol(const void *ptr);
       int __mp_printinfo(const void *ptr);
       unsigned long __mp_snapshot(void);
       size_t __mp_iterate(int (*func)(const void *, void *),
                           void *data, unsigned long event);
       size_t __mp_iterateall(int (*func)(const void *, void *),
                              void *data);
       int __mp_addallocentry(const char *file, unsigned long line,
                              size_t size);
       int __mp_addfreeentry(const char *file, unsigned long line,
                             size_t size);
       void __mp_clearleaktable(void);
       int __mp_startleaktable(void);
       int __mp_stopleaktable(void);
       void __mp_leaktable(size_t size, int opt,
                           unsigned char flags);
       void __mp_memorymap(int stats);
       void __mp_summary(void);
       int __mp_stats(__mp_heapinfo *info);
       void __mp_check(void);
       __mp_prologuehandler __mp_prologue(const
                                          __mp_prologuehandler);
       __mp_epiloguehandler __mp_epilogue(const
                                          __mp_epiloguehandler);
       __mp_nomemoryhandler __mp_nomemory(const
                                          __mp_nomemoryhandler);
       int __mp_printf(const char *fmt, ...);
       int __mp_vprintf(const char *fmt, va_list args);
       void __mp_locprintf(const char *fmt, ...);
       void __mp_vlocprintf(const char *fmt, va_list args);
       void __mp_logmemory(const void *ptr, size_t size);
       int __mp_logstack(size_t frames);
       int __mp_logaddr(const void *ptr);
       int __mp_edit(const char *file, unsigned long line);
       int __mp_list(const char *file, unsigned long line);
       int __mp_view(const char *file, unsigned long line);
       int __mp_readcontents(const char *file, void *ptr);
       int __mp_writecontents(const char *file, const void *ptr);
       long __mp_cmpcontents(const char *file, const void *ptr);
       int __mp_remcontents(const char *file, const void *ptr);

       __mp_errortype __mp_errno;

DDEESSCCRRIIPPTTIIOONN
       The _m_p_a_t_r_o_l _l_i_b_r_a_r_y contains  implementations  of  dynamic
       memory  allocation  functions  for  C and C++ suitable for
       tracing and debugging, and is available on UNIX,  AmigaOS,
       Windows and Netware platforms.  The library is intended to
       be used without requiring any  changes  to  existing  user
       source  code  except the inclusion of the _m_p_a_t_r_o_l_._h header
       file, although additional functions are supplied for extra
       tracing and control.  Note that the current version of the
       mpatrol library is contained in the  MMPPAATTRROOLL__VVEERRSSIIOONN  pre-
       processor macro.

       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  MMPP__MMAALLLLOOCC  family  of  functions  that are defined in
       _m_p_a_l_l_o_c_._h are also defined in _m_p_a_t_r_o_l_._h when NNDDEEBBUUGG is not
       defined.   The mpatrol versions of these functions contain
       more debugging information than the mpalloc  versions  do,
       but  they  do not call the allocation failure handler when
       no more memory is available (they cause the  _O_U_T_M_E_M  error
       message  to  be  given  instead).   See mmppaalllloocc(3) for the
       descriptions of the MMPP__MMAALLLLOOCC family of functions.

       All diagnostics are sent to the file  _m_p_a_t_r_o_l_._l_o_g  in  the
       current  directory  by  default but this can be changed at
       run-time.  Additional configuration options  can  also  be
       changed  at  run-time  by  setting  and  altering the MMPPAA--
       TTRROOLL__OOPPTTIIOONNSS environment variable.  In addition, the  LLOOGG--
       FFIILLEE,  PPRROOFFFFIILLEE  and TTRRAACCEEFFIILLEE options are affected by the
       LLOOGGDDIIRR, PPRROOFFDDIIRR and TTRRAACCEEDDIIRR environment variables respec-
       tively.  See EENNVVIIRROONNMMEENNTT below for more details.

       Details  of  memory allocations and free memory are stored
       internally as a tree structure for speed and also to allow
       the  best  fit allocation algorithm to be used.  This also
       enables the library to  perform  intelligent  resizing  of
       memory allocations and can be used to quickly determine if
       an address has been allocated on the heap.

       On systems that support  memory  protection,  the  library
       attempts to detect any illegal memory accesses and display
       as much information as it can obtain about the address  in
       question and where the illegal memory access occurred.

       Stack traceback information for every memory allocation is
       available on some supported platforms, which is useful for
       determining  exactly  where  a  memory allocation was per-
       formed or for adding meaning to tracing.  Symbol names are
       read  from  the executable file and also possibly from any
       required shared libraries, and if the UUSSEEDDEEBBUUGG  option  is
       used  and  is  available then the debugging section in the
       executable file  will  be  read  to  determine  additional
       source-level information.

       On systems that support it, global functions (with C link-
       age) in an executable file or shared library  whose  names
       begin  with  ____mmpp__iinniitt__  will  be  noted  when the mpatrol
       library first starts up and is reading the symbols.   Such
       functions  will  then  be  called  as  soon as the mpatrol
       library is initialised, which can be useful  if  the  ini-
       tialisation occurs before mmaaiinn is called.  These functions
       must accept no arguments and must return no value.   Simi-
       lar  behaviour  exists  for  global  functions whose names
       begin with ____mmpp__ffiinnii__, except that such functions will  be
       executed  when  the mpatrol library terminates.  Note that
       this feature will have no effect if the  symbol  table  is
       stripped from the executable file or shared library before
       the program is run, and the order in which such  functions
       will  be called if there are more than one is unspecified.

       On UNIX platforms, the ffoorrkk function can cause problems if
       it  is  used  to make a copy of the parent process without
       immediately calling one of the eexxeecc family  of  functions.
       This is because the child process inherits all of the mem-
       ory allocations of the parent process, but  also  inherits
       the  log,  profile  and  trace files as well.  If both the
       parent and child processes make subsequent memory  alloca-
       tions there will be multiple entries with the same alloca-
       tion indices written to the log, profile or  trace  files.
       This  can  be  most  confusing when processing these files
       afterwards!  As a workaround,  the  mpatrol  library  will
       always check the current process identifier every time one
       of its functions is called if the CCHHEECCKKFFOORRKK option is used
       and  will  open  new log, profile or trace files if it has
       determined that the  process  has  been  forked.   If  the
       CCHHEECCKKFFOORRKK  option  is  not used then a call to ____mmpp__rreeiinniitt