libmpatrol.3

debug source code under unix platform.

'\" t
.\"
.\" mpatrol
.\" A library for controlling and tracing dynamic memory allocations.
.\" Copyright (C) 1997-2002 Graeme S. Roy <[e-mail]>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Library General Public
.\" License as published by the Free Software Foundation; either
.\" version 2 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" Library General Public License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with this library; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
.\" MA 02111-1307, USA.
.\"
.\" UNIX Manual Page
.\"
.\" $Id: libmpatrol.3,v 1.37 2002/01/08 20:28:42 graeme Exp $
.\"
.TH LIBMPATROL 3 "8 January 2002" "Release 1.4" "mpatrol library"
.SH NAME
libmpatrol \- dynamic memory allocation and tracing library
.SH SYNOPSIS
.nf
#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);
.if n \{void *operator new(size_t size, const std::nothrow_t&)
      throw();
\}
.if t \{void *operator new(size_t size, const std::nothrow_t&) throw();
\}
void *operator new[](size_t size) throw(std::bad_alloc);
.if n \{void *operator new[](size_t size, const std::nothrow_t&)
      throw();
\}
.if t \{void *operator new[](size_t size, const std::nothrow_t&) throw();
\}
void operator delete(void *ptr) throw();
.if n \{void operator delete(void *ptr, const std::nothrow_t&)
     throw();
\}
.if t \{void operator delete(void *ptr, const std::nothrow_t&) throw();
\}
void operator delete[](void *ptr) throw();
.if n \{void operator delete[](void *ptr, const std::nothrow_t&)
     throw();
\}
.if t \{void operator delete[](void *ptr, const std::nothrow_t&) throw();
\}
.if n \{std::new_handler std::set_new_handler(std::new_handler func)
                 throw();
\}
.if t \{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);
.if n \{void *memccpy(void *dest, const void *src, int byte,
              size_t size);
\}
.if t \{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);
.if n \{int memcmp(const void *ptr1, const void *ptr2,
           size_t size);
\}
.if t \{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);
.if n \{void *memmem(const void *ptr1, size_t size1,
             const void *ptr2, size_t size2);
\}
.if t \{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);
.if n \{size_t __mp_iterate(int (*func)(const void *, void *),
                    void *data, unsigned long event);
\}
.if t \{size_t __mp_iterate(int (*func)(const void *, void *), void *data, unsigned long event);
\}
.if n \{size_t __mp_iterateall(int (*func)(const void *, void *),
                       void *data);
\}
.if t \{size_t __mp_iterateall(int (*func)(const void *, void *), void *data);
\}
.if n \{int __mp_addallocentry(const char *file, unsigned long line,
                       size_t size);
\}
.if t \{int __mp_addallocentry(const char *file, unsigned long line, size_t size);
\}
.if n \{int __mp_addfreeentry(const char *file, unsigned long line,
                      size_t size);
\}
.if t \{int __mp_addfreeentry(const char *file, unsigned long line, size_t size);
\}
void __mp_clearleaktable(void);
int __mp_startleaktable(void);
int __mp_stopleaktable(void);
.if n \{void __mp_leaktable(size_t size, int opt,
                    unsigned char flags);
\}
.if t \{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);
.if n \{__mp_prologuehandler __mp_prologue(const
                                   __mp_prologuehandler);
\}
.if t \{__mp_prologuehandler __mp_prologue(const __mp_prologuehandler);
\}
.if n \{__mp_epiloguehandler __mp_epilogue(const
                                   __mp_epiloguehandler);
\}
.if t \{__mp_epiloguehandler __mp_epilogue(const __mp_epiloguehandler);
\}
.if n \{__mp_nomemoryhandler __mp_nomemory(const
                                   __mp_nomemoryhandler);
\}
.if t \{__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;
.fi
.SH DESCRIPTION
The \fImpatrol library\fP 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 \fImpatrol.h\fP 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 \fBMPATROL_VERSION\fP
preprocessor macro.
.PP
All of the function definitions in \fImpatrol.h\fP can be disabled by defining
the \fBNDEBUG\fP preprocessor macro, which is the same macro used to control
the behaviour of the \fBassert\fP function.  If \fBNDEBUG\fP is defined then
no macro redefinition of functions will take place and all special mpatrol
library functions will evaluate to empty statements.  The \fImpalloc.h\fP header
file will also be included in this case.  It is intended that the \fBNDEBUG\fP
preprocessor macro be defined in release builds.
.PP
The \fBMP_MALLOC\fP family of functions that are defined in \fImpalloc.h\fP are
also defined in \fImpatrol.h\fP when \fBNDEBUG\fP 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 \fIOUTMEM\fP error message to be given
instead).  See \fBmpalloc\fP(3) for the descriptions of the \fBMP_MALLOC\fP
family of functions.
.PP
All diagnostics are sent to the file \fImpatrol.log\fP 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
\fBMPATROL_OPTIONS\fP environment variable.  In addition, the \fBLOGFILE\fP,
\fBPROFFILE\fP and \fBTRACEFILE\fP options are affected by the \fBLOGDIR\fP,
\fBPROFDIR\fP and \fBTRACEDIR\fP environment variables respectively.  See
\fBENVIRONMENT\fP below for more details.
.PP
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.
.PP
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.
.PP
Stack traceback information for every memory allocation is available on some
supported platforms, which is useful for determining exactly where a memory
allocation was performed 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 \fBUSEDEBUG\fP option is used and is available then the
debugging section in the executable file will be read to determine additional
source-level information.
.PP
On systems that support it, global functions (with C linkage) in an executable
file or shared library whose names begin with \fB__mp_init_\fP will be noted
when the mpatrol library first starts up and is reading the symbols.  Such